The CLI killed live-but-busy daemons: a heavy dev-mode page (cold-compiling
Next.js route, timed-out navigation still churning) kept the daemon from
answering /health longer than the old ~1s probe window (3 × 250ms), so the
connection-error path declared it dead, SIGTERMed a healthy process, and
every kill lost the session's tabs, cookies, and logins (reproduced 4/4 in
the #2219 report).
New contract (decision 9 / F10):
- probeHealthWithBackoff is budget-based: ~8s total
(HEALTH_PROBE_TOTAL_BUDGET_MS), 500ms intervals, each probe self-bounded
at 2s — sized to the observed busy windows.
- decideDaemonRestart (pure, exported, unit-tested) encodes the IRON RULE:
healthy-after-probe → retry the SAME daemon; alive+unhealthy →
"daemon busy — retry or --force-restart" + NONZERO exit, daemon untouched;
only a DEAD pid (or an explicit --force-restart) reaches kill+restart.
- --force-restart global flag (extractGlobalFlags): the one consent path
that replaces a live daemon, always announcing the state it costs.
- Wired at all three kill sites: sendCommand's connection-error branch,
ensureServer's stale-state path (which previously killServer'd any alive
pid whose single 2s health probe missed), and connect — which used to
"Kill ANY existing server" and now refuses to replace a healthy daemon
without 'browse disconnect' or --force-restart. pair-agent's internal
headed switch passes --force-restart explicitly (the mode switch is that
command's stated purpose), preserving its behavior.
E5 IRON RULE regression tests (busy-daemon-iron-rule.test.ts, real spawned
CLI + fake daemons + live sleep-pid stand-ins per the
busy-daemon-recovery.test.ts pattern): healthy daemon SURVIVES connect
(refused with guidance, pid alive, state file untouched); wedged-alive
daemon + plain command → busy report, nonzero exit, pid alive; wedged
daemon + --force-restart IS killed and a real replacement daemon serves the
command. Plus pure-function coverage of all four decision outcomes and the
~8s budget pin.
Tests: busy-daemon-iron-rule 8 pass (16.7s, includes a real daemon
lifecycle); busy-daemon-recovery + proxy-config + daemon-mismatch-refuse +
cli-lock + cli-start-final-healthcheck + cli-setsid-daemonize 39 pass.
Fixes#2219.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
