fix(coding-agent): keep snapshot and recovery failures isolated

.pylon/features.yaml

@@ -170,3 +170,36 @@ decisions:
     upstream_support: "Prime PR #1886 repairs protocol fixtures regressed by the #1839 merge commit, but is not yet on main."
     revisit_when:
       - "Prime merges PR #1886 and the exact fix reaches the mirrored main branch."
+
+  snapshot-recovery-integrity:
+    area: runtime-reliability
+    state: candidate
+    owner: shared
+    decision: hybridize
+    pylon_refs:
+      - https://github.com/pylon-code/prime-agent/issues/11
+    upstream_refs:
+      - https://github.com/PrimeIntellect-ai/prime-agent/issues/1229
+      - https://github.com/PrimeIntellect-ai/prime-agent/pull/1845
+      - https://github.com/PrimeIntellect-ai/prime-agent/pull/1756
+      - https://github.com/PrimeIntellect-ai/prime-agent/pull/1864
+    fork_change: immutable-snapshot-transfer-and-isolated-retry
+    upstream_support: Prime now provides one RLM child projection, recovery-aware session reuse, and ownership checks for in-flight opens, but still reuses the event cursor as snapshot transfer identity, serializes selected message objects lazily, and closes a healthy worker on an isolated duplicate-transfer mismatch.
+    revisit_when:
+      - Prime gives each transfer immutable bytes and a unique identity while preserving the event cursor as ordering metadata.
+      - Prime retries an isolated bad snapshot generation without closing the resident worker control channel.
+
+  authoritative-owned-session-cleanup:
+    area: runtime-reliability
+    state: candidate
+    owner: shared
+    decision: hybridize
+    pylon_refs:
+      - https://github.com/pylon-code/prime-agent/issues/11
+      - https://github.com/pylon-code/pylon/issues/114
+      - https://github.com/rynfar/comet/issues/5
+    fork_change: negotiated-authoritative-owned-session-cleanup-v1
+    upstream_support: Prime v0.8.1 supports client-owned sessions and best-effort owner cleanup, but another host process cannot prove exact worker-generation and durable-descriptor absence after the owner connection disappears.
+    revisit_when:
+      - Prime upstream exposes an equivalent privacy-safe, capability-negotiated cleanup proof with durable descriptor-last retries.
+      - Comet and Pylon can remove the fork capability without weakening crash cleanup or stock-Prime fallback behavior.

.pylon/upstream-review.md

@@ -45,3 +45,24 @@ This ledger records Prime upstream evidence and the decision taken for each over
 - Fork candidate: [pylon-code/prime-agent#9](https://github.com/pylon-code/prime-agent/pull/9).
 - Validation: the post-rebase lifecycle, connection, supervisor, runtime, recovery, and ledger checkpoint passed 564 tests across 17 files. The final changed-boundary checkpoint passed 202 connection and supervisor-monitor tests; the clean supervisor process checkpoint passed 10 tests with 8 fixture-gated skips. `npm run check` passed Biome over 940 files, TypeScript, installer rendering, and browser smoke; `git diff --check` passed. Independent final and follow-up audits found no remaining P0 or P1 findings.
 - Revisit when Prime upstream ships an explicitly negotiated equivalent with the same delivery, provenance, scoped cancellation, recovery, generation, retry-integrity, privacy, and per-prompt usage guarantees.
+
+## 2026-08-29 — snapshot recovery integrity candidate
+
+- Audited baseline remains `PrimeIntellect-ai/prime-agent@d60fab8a76d9c169f945341f0ee3bde21903bb55`; latest audited release remains `v0.8.1`. The selected evidence commits are later than that baseline, but the intervening range was not fully audited and therefore does not advance `reviewed_upstream_commit`.
+- Reviewed closed Prime issue #1229, merged Prime PRs #1845, #1756, and #1864, and their commits `c0334a176fb8f78b8c37327a6c76865792b03b52`, `ee8fd699617e8b66cb4bf36c97872c8fe52192e3`, and `5b6c0e94e11a97fcfdd7a9fc9dc4f7acbda9c853`. The pull requests solve child-snapshot projection fan-in, recovery-aware worker reuse, and in-flight open ownership. They do not fix the snapshot identity and failure-containment invariant recorded in #1229.
+- `snapshot-recovery-integrity`: **hybridize**. Adopt and adapt those three upstream changes, while retaining Pylon's correlated prompt lifecycle and adding the missing transfer boundary: each attach, replacement, or catch-up gets an opaque unique snapshot ID; selected messages are encoded into immutable memory/file-backed chunks before deferred streaming; and a transfer-local mismatch retires only that generation and permits one bounded fresh-generation retry without closing the healthy resident worker.
+- Protocol classification: **backward-compatible, capability-gated**. Schema revision 25 adds optional `immutable_snapshot_transfer_v1` negotiation without changing protocol version 7 or any existing command/event shape. A new supervisor requests worker chunk streams only when the worker advertises immutable identities. With an older worker it requests the full snapshot and re-encodes it under a supervisor-owned UUID, while old supervisors and stock clients retain their existing behavior.
+- Resource boundary: transcript preparation checks cancellation before allocation, yields during large encodes, serializes per-session preparation, cleans partial spill files on every constructor/factory failure, uses private pid/start-identity/UUID cache roots, and sweeps abandoned roots only after ownership can be disproved. A single very large JSON message still incurs one synchronous `JSON.stringify` interval; realistic transcript size is not capped.
+- The local `refs/review/current-candidate` at `a37efe92f88ae7234dcea1d065c0d3d76ac048cc` predates these corrections and includes the unaudited intervening range. Do not merge it. The upstream-review workflow must discard or regenerate it after this issue lands; this change does not mutate the protected review ref.
+- Validation: the touched snapshot, protocol, connection, supervisor, recursion, daemon-mode, session-list, and lazy-subagent suites passed 616 tests across 11 files. The real-process supervisor control-channel regression for root isolation, chunked snapshot streaming, and worker adoption passed. `npm run check` passed Biome over 940 files, TypeScript, installer rendering, and browser smoke; `git diff --check` passed.
+- Revisit when Prime gives every snapshot attempt immutable bytes and unique transfer identity, isolates bad generations from worker recovery, and preserves the same recovery and ownership guarantees without weakening Pylon's correlated lifecycle contract.
+
+## 2026-08-30 — snapshot, worker-authority, and authoritative owned-session cleanup candidate
+
+- Pylon base: `pylon@f728316dabbaa85aa561e6d6b08550ed337574be`, which includes merged correlated-lifecycle PR [#12](https://github.com/pylon-code/prime-agent/pull/12). Upstream evidence remains `PrimeIntellect-ai/prime-agent@a903d4b6768f484bd6d459b7b0aa7dee38e461e2`; latest compatibility release remains stock `v0.8.1`.
+- The recovered [#11](https://github.com/pylon-code/prime-agent/issues/11) candidate keeps protocol version 7. Schema revision 26 adds the optional pre-begin `session_snapshot_failed.purpose` correlation used by immutable snapshot transfer. Schema revision 27 adds the supervisor-only `authoritative_owned_session_cleanup_v1` offer and read-only `get_owned_session_cleanup` query. Neither capability is inferred from package version, schema alone, method presence, or the legacy `client_owned_sessions` offer.
+- `snapshot-recovery-integrity`: **hybridize**. In addition to immutable transfer identities and isolated generation failure, the candidate preserves terminal child errors through passive hydration, stabilizes snapshot cursors across asynchronous roster selection and the exact attach-registration cut, invalidates stale supervisor selection/materialization, closes a private channel if an announced frame is interrupted, and binds worker frames to the current authenticated channel and latest authoritative roster.
+- `authoritative-owned-session-cleanup`: **hybridize**. `complete_owned_session` cannot succeed until the exact process generation is absent, ancillary journals are absent, the durable descriptor is removed and verified last, and only then the in-memory registration is removed. Tombstone, archive, and descriptor failures retain a stopping registration and arm a single exact-generation retry finalizer. A different client that already knows the exact host-private active-session ID may poll only `active | stopping | settled`; no PID, path, owner identity, descriptor, token, or diagnostics cross the public boundary.
+- Compatibility classification: **backward-compatible, additive, capability-gated**. Private session workers continue to advertise the shared default server capabilities and do not falsely offer the supervisor-only cleanup query. Current clients reject the query locally against stock `v0.8.1` or schema 26 without sending an unknown command. The proof applies only to registrations created or durably adopted by a capable supervisor; it cannot retroactively certify a descriptorless historical orphan.
+- Validation: 695 focused protocol/client/connection/session/snapshot/supervisor tests passed across 13 files; 40 correlated-lifecycle/queue/continuation tests passed; 13 real-process supervisor tests passed with 8 fixture-gated skips, including direct completion, owner loss before and after worker registration, visible `stopping`, replacement-client `settled` proof, supervisor replacement, exact worker exit, and zero descriptors. Final exact-head review also forced recovery-join, published-replacement rollback retention, reentrant shutdown single-flight, concurrent-completion, and generation-keyed-finalizer repairs before renewed exact-head review. Both stock/current `v0.8.1` adoption directions passed with local cleanup-query rejection on the stock supervisor. `npm run check` passed Biome over 941 files, TypeScript, installer rendering, and browser smoke. The root build passed; the live generated model catalog was restored afterward. `git diff --check` passed.
+- Revisit when Prime upstream provides equivalent immutable snapshot, attach admission, worker-channel authority, and descriptor-last crash cleanup contracts without weakening the stock fallback or exposing host-private process/session details.

packages/coding-agent/.changes/11-snapshot-recovery-integrity.md

@@ -0,0 +1,4 @@
+- Fixed daemon snapshot catch-up and recovery so transfer mismatches no longer interrupt healthy workers and recovered sessions preserve their state and owner ([#11](https://github.com/pylon-code/prime-agent/issues/11)).
+- Fixed recovered child rosters and activity so parent sessions show current delegated work after restart ([#11](https://github.com/pylon-code/prime-agent/issues/11)).
+- Fixed concurrent session opens so one owner and recovery attempt is reused instead of starting competing workers ([#11](https://github.com/pylon-code/prime-agent/issues/11)).
+- Added capability-gated authoritative cleanup proof for client-owned daemon sessions, including crash-safe descriptor-last retries and privacy-safe polling from a replacement host ([#11](https://github.com/pylon-code/prime-agent/issues/11)).

packages/coding-agent/docs/agent-connection.md

@@ -102,12 +102,25 @@ The protocol does not promise that every historical event remains replayable. Du
 
 ## Command Lifecycle and Idempotency
 
-The public daemon protocol is JSONL-framed and currently at protocol v4. Commands may be sent in versioned envelopes containing protocol metadata, client ID, and command ID.
+The public daemon protocol is JSONL-framed and currently at protocol v7. Commands may be sent in versioned envelopes containing protocol metadata, client ID, and command ID.
 
 Mutating commands are recorded before dispatch. A repeated completed command returns its recorded result. A command known to have been received but lacking a durable result is reported as uncertain instead of being replayed blindly. Clients acknowledge durable results so old journal entries can be compacted.
 
 The `AgentConnection` method promise is a client convenience. It should not be treated as a general accepted/running/completed remote workflow API.
 
+## Client-Owned Session Cleanup
+
+`DaemonAgentConnection.dispose()` performs best-effort cleanup for a client-owned session, but it deliberately does not turn cleanup failure into a disposal failure. An authoritative local host must use raw `DaemonClient` commands instead:
+
+1. Require the supervisor-only `authoritative_owned_session_cleanup_v1` server capability.
+2. Send `complete_owned_session` from the owning client and check its response.
+3. If the owner connection disappears or completion is uncertain, poll `get_owned_session_cleanup` from a replacement client with the exact host-private `activeSessionId`.
+4. Accept only `settled` as proof that the exact worker generation, cleanup journals, durable descriptor, and in-memory registration are absent. Treat `active`, `stopping`, a missing capability, or transport uncertainty as not cleaned up.
+
+The query returns only `{ status: "active" | "stopping" | "settled" }`. It does not expose process IDs, worker or owner IDs, filesystem paths, tokens, descriptor contents, or diagnostics. Stock v0.8.1 does not offer this capability, so `DaemonClient` rejects the query locally without sending an unknown command. The proof applies to registrations created or durably adopted by a capable supervisor; it cannot retroactively certify a descriptorless orphan created before that supervisor observed it.
+
+Cleanup closes and joins any admitted recovery before it can publish a successor. Concurrent completion requests for the same resident generation share one stop operation. Finalizers are keyed by process identity and stop revision, and daemon shutdown keeps registry ownership and retry services alive until every requested worker cleanup settles. Repeated shutdown commands and signals join that same drain rather than forcing an early process exit. A client-owned create rechecks owner liveness after registration, so a disconnect while daemon readiness or process launch is still pending cannot miss its cleanup timer.
+
 ## Session Replacement
 
 New, switch, fork, import, and tree-navigation operations may replace the runtime behind an active connection. The adapter owns rebinding and emits a replacement snapshot. The UI applies the new state and transcript; it does not rewire `AgentSession` listeners directly.