From d259039706c25fe99096ecdf3302987a3a792ebb Mon Sep 17 00:00:00 2001
From: blasty <blasty@local>
Date: Thu, 23 Jul 2026 00:14:59 +0200
Subject: launch: `ida-tui foo.elf` one-shot wrapper (server + locks + session)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A caveman entry point so you don't hand-craft the plumbing every time. It:
  * ensures the ida-pro-mcp supervisor is up — starts spawn.sh detached
    (start_new_session, tmux-free) and waits for the port if it's down;
  * recovers a binary wedged by a hard-killed worker — sweeps the stale
    unpacked .id0/.id1/.id2/.nam/.til next to the .i64 and retries (the packed
    .i64 is never touched);
  * adopts an already-open session for the same binary (idempotent), else
    idb_opens it with a sane idle-TTL;
  * launches the TUI attached to that session with keepalive on.

  ./ida-tui /path/to/binary     # open a binary and drive it
  ./ida-tui                     # attach to the sole session
  ./ida-tui --db <id>           # attach to a specific session

Pieces: idatui/launch.py (logic, reuses pane.py's server probe), a repo-root
`ida-tui` sh wrapper (resolves ~/ida-venv python, keeps idatui importable from
any cwd), and an `ida-tui` console-script in pyproject. --help works without
textual (app imported late). README documents both the one-liner and the
manual recovery. gitignore bin/ (binary targets, like targets/).

Verified live: ensure_server up-detection, open, adopt (same session id), and
lock-sweep all work against a running supervisor.
---
 README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index ef66db2..ac9c680 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,22 @@ pulls in Textual + Pygments.
 
 ## Running
 
+The caveman way — one command does all the plumbing (starts the supervisor if
+it's down, recovers a binary wedged by a crashed worker, opens/adopts the
+session, launches the TUI):
+
+```sh
+./ida-tui /path/to/binary        # open a binary and drive it — that's it
+./ida-tui                        # attach to the sole open session
+./ida-tui --db <session>         # attach to a specific session
+```
+
+It uses `~/ida-venv/bin/python` for the TUI (override with `$IDATUI_PYTHON`) and
+resolves binary paths against your real cwd. The binary's directory must be
+writable (idalib writes a `.i64` there).
+
+The manual way (if you want the pieces separate):
+
 ```sh
 # 1. Start the ida-pro-mcp supervisor (opens bin/ls by default).
 ./spawn.sh                       # supervisor on 127.0.0.1:8745
@@ -61,6 +77,11 @@ python -m idatui.tui --db <session>
 python -m idatui.tui --open /abs/path/bin  # dir must be WRITABLE (.i64)
 ```
 
+> Recovering a wedged database by hand: if a worker was hard-killed it leaves
+> unpacked `foo.id0/.id1/.id2/.nam/.til` next to `foo.i64`, and the `.i64` then
+> refuses to reopen. Delete those stale files (never the `.i64`) and retry —
+> `ida-tui` does this automatically.
+
 The `spawn.sh` host/port/target are overridable via `IDA_MCP_HOST`,
 `IDA_MCP_PORT`, `IDA_MCP_TARGET`, `IDA_MCP_MAX_WORKERS`. A systemd unit is in
 `systemd/`.
-- 
cgit v1.3.1-sl0p