fix: verify subagent launches and retry dropped commands (shell-init race)

[elucid]

TL;DR

Launch keystrokes can be swallowed by shell init, leaving a "running" subagent that never started. Launches are now verified against a marker file and retried safely until they provably ran — or fail loudly instead of stalling forever.

Problem

Subagent launches type the launch command into a freshly created pane after a fixed delay (default 500 ms, PI_SUBAGENT_SHELL_READY_DELAY_MS). If the shell is still initializing when the keystrokes arrive — common with direnv/devenv/nix hooks — some init steps flush the tty input queue: the command is echoed to the scrollback but never executed.

Result: the pane sits at an idle prompt, the tool has already reported the subagent as running, and the orchestrator receives "stalled" notifications forever. No session is created and no work happens.

Fixed delays can't reliably fix this because shell init time is unbounded (cold caches, disk pressure). In an environment with a heavy direnv hook, a warm-cache init reliably swallowed commands sent up to ~500 ms after the split, and a cold init swallowed them at any plausible delay.

Fix: make the launch closed-loop

1. Idempotency-guarded launch scripts (df5fa1e) — every generated launch script now begins with:

[ -e '<script>.started' ] && exit 0
: > '<script>.started'

The .started marker is both proof that the launch ran and a guard that makes re-running the script a no-op — which is what makes retrying safe.

2. Verify/retry loop — after the initial send, an async loop polls for the marker (2 s, 4 s, 8 s, 15 s, 30 s backoff). If it's missing, the launch line is resent. On tmux, a resend only happens while the pane's current command is still an idle shell, so a retry can never type into the child's TUI. Loops are per-launch (unique script + marker per attempt, including resumes), abortable on /reload, and safe under concurrent spawns.

3. Truthful failure state (3c84bca) — if the marker never appears after all retries, the subagent is removed from the running set (stall notifications stop) and the orchestrator gets an explicit failure message including the pane/surface id and the launch script path, with the pane kept open for post-mortem. Launch failures surface through the normal result path instead of an eternal "stalled".

4. Surface id in tool results (b1d718b) — subagent and subagent_resume results now include the pane/surface id so orchestrators can inspect or take over a pane deliberately when something goes wrong.

Behavior notes

• The happy path is unchanged: when the first send lands (fast shell init), the marker appears immediately and no retry occurs. The existing configurable delay is retained, but it's now a latency optimization rather than a correctness knob.
• All mux backends get marker verification; the idle-shell resend gate is tmux-only (other backends retry on marker absence alone).
• Recovery cost when the race is lost is one retry interval (~2–14 s depending on init time) instead of a dead subagent.

Testing

• Unit suite: 114 → 131 tests, all passing (npm test): guard ordering/escaping, exactly-once execution under repeated runs, resend/backoff/abort logic, idle-shell gating, failure handling.
• Live tmux validation in a slow direnv/devenv environment, with the delay forced to 0 to guarantee the race is lost: single spawns recovered via resend and completed; three concurrent spawns each launched exactly once (one marker/session per spawn, no duplicates); a deliberately unlaunchable pane (running cat) produced the failure message with zero unsafe resends and no lingering stall notifications.

Known limitation

Resuming a session that is already running is not detected.