[roodboi]

Root cause

On Linux CI (linux-process-lifetime, PR #381), the test "a starter lost after readiness leaves a claimed helper that another client reuses and releases" failed at the last assertion. releaseSharedHostHelper({ holder: "branch-b" }) returned { state: "stopped" }, and then the fixture's isAlive(owned) returned true.

The product and the fixture used different liveness rules:

• The product (readCensus) already counts a zombie as exited. Release returns stopped only after a census shows every tree member gone or a zombie.
• The fixture's isAlive matched any ps row with the same PID and birth time. That includes a zombie.

In this test the starter is killed with SIGKILL, so the helper is orphaned. On Linux, init or a subreaper reaps it, and that can lag behind the stop. During that window the helper is a zombie. Release correctly reported stopped, but the zombie-blind fixture still saw the helper as alive. On macOS, launchd reaps orphans almost at once, so the window is rarely seen. The same mismatch applies to the time-zone test, whose first starter also exits and orphans the helper.

The only other way to get that result is lstart drift that flips back within milliseconds. A zombie is the simple explanation that fits. The new assertions would still fail, and show the problem, if a non-zombie row were ever left after stopped.

Contract (decided and documented)

stopped means a census, taken after the signals, observed every member of the captured tree exited within one bounded, named wait:

1. TERM, then poll for graceMs (SHARED_HOST_RELEASE_GRACE_MS = 2000 ms by default; a failed start uses 1000 ms).
2. KILL to the members still running, then poll for up to SHARED_HOST_KILL_CONFIRM_MS (1000 ms).
3. Otherwise the result is stop-unconfirmed (the existing closed state for an uncertain stop), and the claim is kept.

Exit is observed when the PID is gone or is a zombie. A PID that is still running never counts as exited, even with another birth time. Linux lstart can drift, so that row may be the same helper. Before this change such a row read as "exited", so a live process could be reported stopped. A census that fails during the wait now keeps polling until the deadline instead of escalating to KILL early.

Fix

• src/lib/shared-host-lifecycle.ts
  • Exported one liveness predicate, isSharedHostProcessRunning: exact PID and birth, not a zombie. The product uses it internally.
  • Added exitObserved for the stop wait.
  • Named the waits, and folded the two poll loops into one bounded awaitExit.
• tests/shared-host-lifecycle.test.ts
  • isAlive now uses the product predicate.
  • Added isPresent and waitReaped for the one check that really is about reaping. waitGone now means "exited".
• docs/reference/shared-host-lifecycle.md: new "What stopped means" section, plus new fixture rows.

Tests (each new assertion proven by mutation)

New test / assertion	Mutation	Result
Helper ignores TERM for 600 ms (slow-term fixture), 10 s grace. Release returns stopped only after the exit, the helper is not running at return, the TERM-path marker exists, and elapsed time is at least about 600 ms.	M1: return stopped right after TERM	fails (plus the census test below)
Same	M4: TERM grace forced to 0 (straight to KILL)	fails (no marker)
Simulated census: helper runs for 3 polls after TERM, then shows as a zombie. Expect stopped on poll 4, TERM only.	M1, M4	fail
Simulated census: PID keeps running with a drifted birth. Expect stop-unconfirmed, TERM then KILL, claim kept with no holders.	M2: exit observed by birth match (the old rule)	fails
Existing unreaped-zombie test now also asserts the fixture isAlive is false while the row is still a zombie. This is the deterministic local repro of the HACK-1336 failure mode.	M3: zombie-blind fixture isAlive (the old helper)	fails
Same	M5: product predicate counts zombies as running	fails

M6 (dropping the !row.zombie clause inside exitObserved) is an equivalent mutant, because readCensus already removes zombie rows. The clause is kept as defense in depth.

Evidence

• Bun 1.4.2 (mise x bun@1.4.2), bun install --frozen-lockfile; bun.lock unchanged.
• Local (macOS, loaded host, load average about 28 on 18 cores, plus 4 extra CPU spinners): bun test tests/shared-host-lifecycle.test.ts passed 5 out of 5 runs, 36 tests each, 0 failures. All mutations above were run locally.
• Root bun run check (includes privacy:check: ok) and bun run --cwd packages/cli typecheck: exit 0. The Biome warnings shown are pre-existing in other files.
• gitleaks 8.30.1 over origin/next..HEAD (patch export): no leaks.
• Full suite on the M3 at the exact pushed commit 89b6221d (detached worktree, Bun 1.4.2): 7678 pass, 126 skip, 5 fail, 548 files, 3421 s. tests/shared-host-lifecycle.test.ts passed there. None of the 5 failures is in a file this PR changes, and the changed module is imported only by the shared-host tests and fixtures:
  • repository catalog > the checked-in .hack/tasks.json recipes are all reviewed: fails in detached worktrees (HACK-1358). It passes in this checkout (18/0) and in the hosted test job.
  • new no-host death uses real read-only quiescence facts… and new no-host recovery retains original bindings on last-await (tests/native-authored-project-recovery.test.ts): these also fail when rerun serially with --timeout 60000 on this Mac (16/2). The same two failures appear in full-suite logs for other branches, including a baseline run, so they predate this PR. Reported separately.
  • original capture uses its live session… (native-authored-process-incarnation): rerun serially on this Mac, 10/0.
  • legacy linked admission shares all six managed layers… (native-compose-adoption-env-inputs, 15 s timeout): rerun serially with --timeout 60000 on this Mac, 35/0.
• Hosted checks on this PR at 89b6221d: all pass, including linux-process-lifetime (the step with tests/shared-host-lifecycle.test.ts: 67 pass, 0 fail) and test.

Gaps

• The Linux zombie window cannot be forced on macOS, where launchd reaps orphans at once. The Linux receipt is the hosted linux-process-lifetime job on this PR. One green hosted run does not prove the intermittent failure is gone. The deterministic proof is the zombie test plus mutation M3.
• lstart drift outside a stop (a release that reads the claim as stale) is still the documented gap under "Not covered here". This PR only makes drift during a stop fail closed.
• The serial reruns of the M3 failures ran on this Mac, not on the M3. A queued M3 rerun waited almost three hours behind other units for the shared M3 lock, so I stopped it without touching the lock.
• No CLI surface, agent guidance, or package.json scripts changed, so there is nothing to regenerate or re-pin.

Refs HACK-1336

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[linear-code]

HACK-1336