rpc host: a superseded generation never announces the handoff to attached clients, never parks their sessions, and never exits while they stay connected

[code-yeongyu]

Summary

When a generation of the shared multi-session RPC host is superseded (a successor takes the public socket; watchForSupersession or SIGUSR1 puts the predecessor into drainForHandoff), the predecessor keeps serving the connections it already proxies and parks only the sessions nobody is attached to. A client that stays attached is told nothing: no wire record announces the supersession, its sessions are never parked, and IdleExitDecider (connections must be zero) keeps the superseded process alive for as long as that client holds its socket. Meanwhile any traffic that client sends over a NEW connection lands on the successor, whose registry has never seen those handles, and answers unknown_session. Observed on one machine 2026-09-21: a desktop client attached to generation A kept a multi-GB superseded host alive after generation B took the socket, and its next set_model/prompt on the thread answered unknown_session from generation B while A still held the session.

Reproduction

1. Start a multi-session host on a public socket; open one session from a client and keep the connection attached and idle.
2. Start a second supervisor that takes the public socket (an upgrade handoff, or simply a newer build's host ensure).
3. Observe: the first supervisor logs "draining into the next generation" / "another generation owns the public socket"; the attached client receives no record; senpi host status on the new socket lists none of the old sessions; the old process never exits while the client stays connected; a command from the client on a fresh connection to the public path answers unknown_session.

Expected (ideal state / acceptance criteria)

• On supersession the predecessor sends every attached connection an unsolicited record — proposed { "type": "host_superseded", "instanceId", "generation", "successor": { "socket" } | null } — before anything else changes for that connection.
• Attached sessions are parked too, not only unattached ones: once a session's current turn settles (or immediately when idle, and always within a bounded grace the supervisor owns), the predecessor sends session_closed { reason: "handoff_parked", sessionPath } and closes the connection, so the client reattaches by open_session { sessionPath } on the successor — exactly the recovery rpc-types.ts already documents for handoff_parked. No turn is cut short; no session is ended.
• Having parked everything, the superseded generation exits on its own even when a client never disconnects — the memory the shared RPC host: a superseded generation never drains — keeps ~6 GB RSS, retained sessions and 59 path reservations, so the current generation refuses opens with session_path_in_use; hosts.json lists dead pids #1893 drain was meant to reclaim is actually reclaimed.
• A client that ignores host_superseded still gets the guarantee above (the session_closed + close is what moves it); a client that honours it can reattach early.
• docs/rpc.md documents the record and the grace; CHANGELOG.md [Unreleased] and src/changes.md carry entries; regression tests in packages/coding-agent/test cover: attached-idle session parked and announced; attached mid-turn session parked only after its turn settles; superseded generation exits with a still-attached client; a command sent after the announce on the OLD connection is served or answered by the close, never by unknown_session.

Actual

host-lifecycle.ts drainForHandoff(): "stop accepting, keep every connection already proxied, and tell the host child to park its retained sessions as their turns settle" — attached sessions are excluded from parking; the accept guard destroys only NEW connections; nothing is written to existing clients. IdleExitDecider needs connections == 0 continuously, so an attached client pins the generation forever.

Evidence

• packages/coding-agent/src/modes/rpc/host-lifecycle.ts — drainForHandoff() (keeps proxied connections, SIGUSR1 to the child), the accept guard (if (shuttingDown || draining) client.destroy()), IdleExitDecider (connections gate), watchForSupersession wiring ("Losing the public entry IS a drain request").
• packages/coding-agent/src/modes/rpc/host-supersession.ts — detection only; no client notification.
• packages/coding-agent/src/modes/rpc/rpc-types.ts — session_closed.reason union already has handoff_parked ("open_session { sessionPath } reopens it in the new generation"); instanceId "changes when the host process does, including on a handoff"; no host_superseded-style record exists in the event union.
• packages/coding-agent/src/modes/rpc/session-registry.ts getForCommand — the successor's registry is empty for the predecessor's handles, hence unknown_session.
• CHANGELOG.md [2026.9.21] — the shared RPC host: a superseded generation never drains — keeps ~6 GB RSS, retained sessions and 59 path reservations, so the current generation refuses opens with session_path_in_use; hosts.json lists dead pids #1893 entry: "parks the sessions nobody is attached to, releases their files and exits" — the attached case was left out by design and is what this issue closes.

Scope

In: the host_superseded record, parking + announcing attached sessions after settle within a bounded grace, exit of the superseded generation, docs, changelog, tests. Out: the client-side reattach (the desktop tracks it separately), the takeover decision policy (host-decision.ts already refuses silent-but-live hosts and requires a strictly newer build for upgrade).

Related

#1893 (superseded generation never drains), #1805-era handoff, #1782 (drain-and-exit). Desktop counterpart: code-yeongyu/omo-desktop-app#849 (reactive recovery on unknown_session) and #850 (proactive reconciliation, which will consume host_superseded and handoff_parked).

[code-yeongyu]

Root cause confirmed by source inspection at 421d198 (no runtime test claim): host-lifecycle.ts:667 sets draining and signals the child without announcing to attached connections; session-command-router.ts:189 explicitly excludes entries with attachments from the drain sweep. The child already bypasses connection occupancy when draining, but cannot empty its registry while that exclusion holds.

A lifecycle-contract decision needs review before implementation: the existing drain deliberately protects the complete isSessionBusy predicate, including background terminal jobs, extension wake sources, compaction, and queued session work, not just an agent turn (core/session-activity.ts, session-command-router.ts:315-325). A fixed grace after the last agent turn would eventually dispose those still-busy sessions; waiting for the complete predicate to clear preserves that contract but does not bound exit after the last agent turn. The existing close path calls abort and disposal (session-teardown.ts:105-130). This is a semantic distinction, not an idle-connection timer fix.

Escalating that decision before edits. No RED/GREEN results, commits, or PR are claimed; no scratch hosts or remote test directories have been created.

[code-yeongyu]

Implementation decision: handoff parking will use a dedicated activity predicate protecting agent runs, bash/tool work, compaction, queued session work, and in-flight host requests, while excluding durable wake-source holds. Existing idle eviction keeps its broader predicate unchanged. Announcement will be serialized by the child host event writer (not injected into a supervisor byte proxy, which could split JSONL frames). Attached parkable sessions will release their files and publish handoff_parked before closing their connection; a shared connection will remain until its other active sessions settle. The supervisor owns SENPI_RPC_HANDOFF_GRACE_MS (default 600000): expiry retries draining and reports the remaining work, never aborts a turn. Regression coverage and remote RED are in progress.

[code-yeongyu]

RED captured on the remote Linux test runner before production edits: bun test packages/coding-agent/test/rpc-host-supersession-announce.test.ts exited 1 in 54.53 s: 0 pass, 4 fail. All four fail waiting for the missing host_superseded record (idle attached, monitor-only attached, held turn across grace, real successor handoff). The idle client saw 16 other records and the held-turn client saw 22; neither received the announcement. Dependency installation exited 0. No tests ran on the session machine.

[code-yeongyu]

GREEN for the initial real-socket regression suite on the remote Linux runner: bun test packages/coding-agent/test/rpc-host-supersession-announce.test.ts exited 0: 4 pass, 0 fail, 21 assertions in 5.44 s. Idle attached drain completed in 1.139 s; monitor-only drain in 0.970 s; held-turn case crossed the actual 50 ms supervisor grace-expiry signal, successfully served get_state on the OLD connection, then parked only after agent_settled (1.278 s total). A real successor reopened the released session file (1.981 s). The tests never voluntarily disconnected to make the predecessor exit. Broader runtime coverage and repository gates are next; these are not yet claimed green.

[code-yeongyu]

Milestone: gates green on a remote macOS box (never the session machine).

New tests — test/rpc-host-supersession-announce.test.ts + test/rpc-handoff-activity.test.ts:

Test Files  2 passed (2)
      Tests  10 passed (10)

Pre-existing handoff suite on the same tree — test/rpc-host-handoff.test.ts: Tests 5 passed (5) (unchanged by this PR).

Static gate on a remote Linux box — bun run check: exit 0 (biome, pinned-deps, ts-imports, entry-graphs, shrinkwrap, install-lock, claude-sdk platform lock, tsc --noEmit x2, browser smoke).

Two findings worth recording, both from the gate rather than the product:

1. The workspace must be built before these tests run. @earendil-works/pi-ai is a workspace package (node_modules/@earendil-works/pi-ai -> packages/ai) whose main is ./dist/index.js. On a tree where bun run build has not run, every host-spawning test fails at ensureHost with ERR_MODULE_NOT_FOUND '@earendil-works/pi-ai' -> rpc host process exited unexpectedly (1). That hits the pre-existing suite identically (9 failed / 7 passed before the build; 5/5 passing after), so it is an environment prerequisite, not a regression.

2. handoff_parked reports the CANONICAL session path. The host reserves and reports session files by canonical path, so a scratch dir opened as /var/... comes back as /private/var/... on macOS. The first three announce-test failures were the test comparing the raw path it opened with; the tests now open with the raw path (that canonicalization is part of what they cover) and assert against the canonical one. docs/rpc.md states the contract explicitly, because a client matching the record against its own stored path has to canonicalize first - code-yeongyu/omo-desktop-app#850 consumes exactly this field.

Head 722286cb0.

[code-yeongyu]

Regression found by CI, root-caused and fixed.

What broke: Test (coding-agent 1/3), (3/3) and (workspaces + scripts) went red — 21 failures across rpc-attach-edges, rpc-session-registry, rpc-session-occupancy and rpc-multi-session-isolation. The loudest signature was expected [] to have a length of 9: no open_session response records at all.

Root cause: the handoff work assumed two optional runtime hooks are always present —

• entry.runtime.session.subscribe(...), subscribed on every open to wake the drain sweep early;
• entry.runtime.session.activitySnapshot, read on every drain sweep.

Neither is part of the surface every runtime implements. The occupancy suite's fake session provides isSessionBusy, abort, dispose and friends and nothing else, so the subscription threw a TypeError inside the open path before any response was written — which is also why the failures looked like "sessions vanished" rather than "handoff misbehaves".

Fix: both hooks are feature-detected. A runtime that cannot report settle still opens normally and is still parked by the periodic sweep (the early wake is an optimisation, not the mechanism); a runtime that publishes no activity snapshot is never treated as busy, since a park waiting on a signal that never arrives would strand the session on the generation that is leaving.

Verified on a remote macOS box, the same four files that failed: Test Files 4 passed (4), Tests 43 passed (43).

Why my own gate missed it: I ran only the new announce/handoff files plus rpc-host-handoff/rpc-inprocess-host. A change that rewrites the router's open and drain paths has a blast radius across the router, registry, attachment and occupancy suites; a targeted gate could not have caught this, and I should have run the package's RPC suites before calling the gate green.

[code-yeongyu]

Closed by PR #1939 — merge commit 7a62cf402 on main (head b815c7ed6).

What shipped:

• host_superseded { instanceId, generation, successor } announced to every attached connection before parking.
• Attached sessions parked once turns and in-flight requests settle, emitting session_closed { reason: "handoff_parked", sessionPath } and closing the connection so the client reopens on the successor. Durable wake sources (persistent monitors, scheduled continuations, goal loops) are excluded from the parkable predicate — they resume from the persisted session, so letting one pin the old generation would defeat the fix.
• A soft SENPI_RPC_HANDOFF_GRACE_MS (default 600000) that rescans and reports at expiry and never aborts a turn; the generation exits once everything parks, even with a client still connected.
• New stable error code host_draining for an open on a draining connection, documented in the stable error-code list.
• docs/rpc.md gains the "Supersession lifecycle" section; CHANGELOG + both changes.md trackers updated.

Evidence:

• New tests (rpc-host-supersession-announce, rpc-handoff-activity): 10/10, covering announce-then-park for an idle attached session, monitor-only sessions on both runtimes, a turn outliving grace, single-announce under a re-entered drain, socket replacement without a drain signal, a shared connection staying open for its other session, and no-park while a host request is in flight.
• Pre-existing suites unchanged: rpc-host-handoff 5/5, rpc-inprocess-host 16/16.
• bun run check exit 0; required contexts green.

Two defects found and fixed inside the PR:

1. Optional runtime hooks treated as universal — session.subscribe(...) and session.activitySnapshot were assumed on every runtime, so open_session threw before writing a response on runtimes that implement only what they need; 21 tests failed across rpc-attach-edges, rpc-session-registry, rpc-session-occupancy and rpc-multi-session-isolation. Feature-detected now; re-verified 43/43 on those four files.
2. handoff_parked reports the canonical session path (/var/… → /private/var/… on macOS), now stated in docs/rpc.md because clients match on that field.

Desktop counterpart: code-yeongyu/omo-desktop-app#850 (PR #866) consumes host_superseded, handoff_parked and host_draining.