fix(sessions): drive turn status off Claude Code's real lifecycle hooks (v0.324.0)

[vikasprogrammer]

Reported: finished/stopped sessions still show the LoaderCircle spinner.

Root cause

term_sessions.busy_since — the flag the console spins on — was a one-way latch. It was cleared in exactly one place: the resident branch of markTurnIdle. A member's own interactive session returns before that branch (!r.headless), so its flag was never cleared.

On the live instapods DB: 72 of 520 rows carried a stale busy_since, 66 of them done/stopped/crashed — a finished run whose pane lingers reads live and working, i.e. a spinner on a session that ended hours ago.

The deeper problem: status was inferred (a latched flag + a tmux poll) instead of driven by the runtime's own lifecycle events. We listened to PreToolUse, Notification and Stop. Per the hooks reference there were three more that matter, and all three were missing:

Event	Why it matters
UserPromptSubmit	The turn-START signal we simply didn't have. busy_since was stamped only when the server delivered a message — a human typing straight into an attached TUI ran whole turns the console couldn't see.
StopFailure	A turn killed by an API error (rate_limit, overloaded, …). Claude fires no Stop then, so the turn never ended server-side: the run kept reading "working", the automations pile-up guard kept holding its slot, and an unattended run parked as a zombie until a 24h reaper found it — the shape behind the recurring weekly-limit zombie sessions.
SessionEnd	The run is over, with claude's own reason. Only prompt_input_exit / logout / bypass_permissions_disabled are terminal — clear, resume, compact are mid-run, so a /clear must not look like a finished session.

What changed

• terminal/lifecycle-hook.sh → POST /api/session-event → TerminalManager.recordLifecycle handles the three events above. Stop keeps its own script (it carries the unattended-teardown decision, and codex-launch.sh wires that one too).
• markTurnIdle clears busy_since for every lane — the lane only decides what happens to the pane, never whether the flag is honest.
• Every terminal status transition NULLs the flag.
• Defence in depth — a hook that never fires must not strand a spinner. isWorking now requires all five: flag set; row not stopped/crashed (done still counts — report flips the row mid-turn); runtime still alive; no turn-END recorded after the start (last_activity > busy_since, which heals rows latched by older builds with no beacon needed); turn younger than the 2h wedged-turn ceiling.
• One-time migration clears the already-latched rows (terminal ones + any turn past the ceiling). A genuinely in-flight turn is untouched, so it's safe on a live box.

Verification

Against a VACUUM INTO copy of the live instapods DB: 72 stale flags → 5, and all 5 confirmed genuinely mid-turn by capturing their live tmux panes (e.g. ses_aacdc040029c2643 showed Bootstrapping… (8m 23s)).

scripts/turn-lifecycle-test.cjs — 32 assertions, wired into npm run test:governance: the interactive-lane clear, the turn-start signal, StopFailure teardown, each SessionEnd reason, all five isWorking clauses, ignore-unknown-events. Full suite green.

Contract documented in docs/session-lifecycle-hooks.md.

Deploy note: server restart required. Hook settings are written at launch, so the new events reach a session only when it next launches — which is exactly why isWorking self-heals rather than waiting on a beacon.

🤖 Generated with Claude Code

https://claude.ai/code/session_015ZUfffxY4hKv7M6wMCcaTz