fix(spawn): prove the shell is ready before typing a launch command

[stoneevenson-biz]

The incident

Two registered secondmates — cellarsky-sm and hermes-jarvis-sm — were found on 2026-08-26 as bare zsh prompts, not running agents. Their launch line had been typed into a shell that was not at a prompt:

(base) stoneevenson@Air firstmate % claude --dangerously-skip-permissions You are a secondmate…
zsh: parse error near `do'

They had never started. data/secondmates.md listed three live supervisors; one was real. firstmate had already recorded their metas. Nothing noticed for weeks.

Root cause

fm-spawn.sh inferred shell readiness from pane_current_path changing after treehouse get. That proves a chdir happened — it says nothing about whether the shell returned to a prompt, and tmux send-keys has no acknowledgment channel to tell the difference:

tmux send-keys -t "$T" -l "$LAUNCH"   # blind keystroke injection
sleep 0.3                              # a timing guess, no backing signal
tmux send-keys -t "$T" Enter

The fix

Two guards in bin/fm-tmux-lib.sh:

fm_tmux_wait_shell_ready — a bounded echo round-trip. Send a unique marker through the shell; wait to see it rendered back on its own line. Seeing it is positive proof the shell read a command line, ran it, and printed a result. A probe that lands in a busy shell is a harmless short printf, unlike a multi-KB launch string. Only the output line matches (grep -qx), so the echo of the probe's own keystrokes is not accepted as proof.

fm_tmux_launch_failed — reads the pane after launch and fails loudly on a shell error, instead of recording a meta for a pane that holds nothing.

Both are bypassable with FM_SKIP_SHELL_READY=1, which the two suites that exercise spawn's worktree logic over a fake tmux now set — the same way they already set FM_INTAKE_OVERRIDE=1.

Drive-by

tests/lib.sh — fm_test_cleanup ended on a falsy [ -n "$d" ] and returned 1. Its own header tells suites to call it from a custom EXIT trap, so any suite following that advice failed with every test passing. Now returns 0.

Verification

Falsifiable — red before green. With the readiness guard stubbed to return 0 (the pre-fix behavior):

ok     - ready shell: probe round-trips, gate opens
not ok - deaf shell: gate opened on a shell that never ran the probe
exit=1

Restored, all six pass. New suite tests/fm-spawn-shell-ready.test.sh pins both guards, including the exact zsh: parse error near \do'` text from the incident, and asserts a healthy running-agent pane is not flagged.

full suite:  38 pass, 1 fail
shellcheck:  clean

The one failure, fm-loop-l2, fails identically at 24f6891 — before any commit in this branch. Verified in a detached worktree, not assumed.

Related

herdr v0.8.2 ships "agent start now properly waits for pane/agent readiness instead of racing" — the same defect class, solved upstream at the multiplexer. This fix makes the tmux driver safe today; docs/plans/cmux-herdr-surface-split.md remains the longer-term answer.