From 2b36188a14c92ca6c9f561ff20871905ce6bd5c2 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 02:24:50 -0700
Subject: [PATCH 01/87] docs: add implementation plan for
 reconcile-client-adoption
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../2026-07-26-reconcile-client-adoption.md   | 1395 +++++++++++++++++
 1 file changed, 1395 insertions(+)
 create mode 100644 docs/plans/2026-07-26-reconcile-client-adoption.md

diff --git a/docs/plans/2026-07-26-reconcile-client-adoption.md b/docs/plans/2026-07-26-reconcile-client-adoption.md
new file mode 100644
index 000000000..7f0ae5f79
--- /dev/null
+++ b/docs/plans/2026-07-26-reconcile-client-adoption.md
@@ -0,0 +1,1395 @@
+# Reconciliation Handshake Phase 3 — Client Adoption Implementation Plan
+
+> **For agentic workers:** This plan is executed task-by-task by the
+> workflow's execute stage: a fresh implementer per task, with a spec +
+> quality review after each task. Steps use checkbox (`- [ ]`) syntax
+> for tracking.
+
+**Goal:** Activate the ~1,400 dormant server lines of the pane-reconcile handshake by making the client send `capabilities.paneReconcileV1` and fold server verdicts, delete the `retry` verdict from the wire (server absorbs `index_warming` with a bounded deferral), and close D8 with a server-side per-`sessionRef` single-flight lease so two clients sharing a session can never mint two PTYs.
+
+**Architecture:** Server-first: reshape the verdict wire (delete `retry`, add `error{index_warming|provider_unavailable}`, bounded single deferral), add a sessionRef-level liveness-bound lease alongside the existing `createRequestId` keyed-create single-flight, then adopt on the client — a new `src/lib/pane-reconcile.ts` module builds `pane.reconcile.request` from persisted panes and folds `pane.reconcile.result` verdicts into existing pane reducers, with the legacy `clearDeadTerminals` census kept as the capability-gated fallback.
+
+**Tech Stack:** Rust (crates/freshell-ws, crates/freshell-protocol, tokio, tokio-tungstenite tests), TypeScript/React 18/Redux Toolkit (Vite client), Zod (`shared/ws-protocol.ts`), Vitest + Testing Library, Playwright (`test/e2e-browser`, rust-chromium project).
+
+## Global Constraints
+
+Every task's requirements implicitly include this section.
+
+**Repo / process rules:**
+- Work ONLY in the worktree `/home/dan/code/freshell/.worktrees/reconcile-client-adoption` (branch from `origin/main@2dfbba58`). All `cd` in this plan means that directory.
+- PR policy for this branch: **NOT approved.** Push the branch, STOP before `gh pr create` or any equivalent. Final deliverable is branch + red→green proof.
+- NEVER restart the user's self-hosted Freshell server. NEVER use broad kill patterns (`pkill -f`, `pkill node`, ...). Only kill PIDs you spawned and recorded.
+- E2E servers: own `RustServer` instances via `test/e2e-browser/helpers/rust-server.ts`, ephemeral ports (the helper picks a free port) — NEVER ports 3001/3002.
+- Broad coordinated test runs go through the shared coordinator gate: set `FRESHELL_TEST_SUMMARY="B1 reconcile client adoption: <what>"`. If another agent holds the gate, WAIT (3 sibling lanes run concurrently). Use `npm run test:status` to inspect. Focused runs use `npm run test:vitest -- run <path>`.
+- CI-required Rust checks: `cargo fmt --all --check` and `cargo clippy --workspace --all-targets -- -D warnings` must pass.
+- Server-side TS uses NodeNext/ESM — relative imports include `.js` extensions; client `src/` follows existing import style (no extension, `@/` alias).
+- Disk is ~78GB free — halt and report on any ENOSPC.
+- Commit messages end with the Amplifier attribution block:
+  `🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)` + `Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>`.
+
+**Scope fence (sibling lanes are working concurrently on other branches):**
+- You own: `src/lib/ws-client.ts`, client verdict folding (`App.tsx` recovery region + new `src/lib/pane-reconcile.ts` + minimal support edits in `panesSlice.ts` / `paneTypes.ts` / `terminal-restore.ts` / `TerminalView.tsx` / `shared/ws-protocol.ts` + the new `DeadSessionPanel` component), `crates/freshell-ws/src/reconcile.rs`, `crates/freshell-ws/src/existence.rs` (+ the concrete probe in `crates/freshell-server/src/existence.rs` for warming/provider-unavailable), `crates/freshell-ws/src/terminal.rs` create/reconcile paths, `crates/freshell-ws/src/registry.rs` reservation, and the ledger WRITE at respawn-winner bind (the wave-A ledger API).
+- Do NOT touch: `codex_candidate.rs` / rollout locator (Lane B2), `tabs_snapshots.rs` + tabs-snapshot recovery UI (Lane B3), `freshell-freshagent` crates + fresh-agent verdict support (Lane B4). `reconcile.rs` keeps rejecting `kind: fresh-agent` (`reconcile.rs:169` `unsupported_kind`) this slice — keep edits near that dispatch match-arm minimal and tight (B4 merges a new arm there; expect a trivial merge conflict). No kimi/gemini work.
+
+**Council-gated behavioral invariants (from the restart-resilience analysis §4.3 — every rule here is binding):**
+1. Verdict folds: `attach` → plain attach (NO recreate, NO new `createRequestId`), `respawn` → create-with-resume using the server-named `sessionRef`, `fresh` → clean create, `dead_session` → loud per-pane breadcrumb + ONE batched adjudication panel listing all dead panes (never N modals).
+2. `createRequestId` is NEVER re-minted by any reconcile fold path (it is the keyed-create dedupe key; "Start fresh here" reuses the same id).
+3. `retry` verdict does not exist on the wire. `index_warming` is absorbed server-side: bounded deferral (2s budget, SINGLE deferral), then a loud `error` verdict with `reason: "index_warming"` + a client-side manual retry affordance — never a fake `fresh`/`dead_session`, never an unbounded await.
+4. A known provider with no home on this machine is NOT warming — it gets `error` with `reason: "provider_unavailable"`, immediately (no deferral).
+5. Under a post-restart storm, warming notices batch into ONE banner ("Waiting for session index — N panes"), same anti-N-modal rule as `dead_session`.
+6. Multi-client single-flight is per `sessionRef`, not just per `createRequestId`. The first respawn winner binds `sessionRef → new terminalId` (registry + ledger); every other client's reconcile/create for the same `sessionRef` — regardless of `createRequestId` — receives `attach {terminalId}` to the winner.
+7. The sessionRef reservation is a liveness-bound LEASE: released on spawn complete (bind), spawn fail (error), or holder connection death; a wall-clock TTL (~2× spawn budget) backstops a hung holder. TTL expiry is KILL-BEFORE-RELEASE: kill the holder's in-flight spawn and confirm death before releasing; if the kill cannot be confirmed, the lease is NOT released (fail loud, hold closed).
+8. Losers get an `error` frame `{code: SESSION_RESERVED, retryAfterMs}`; the client retries via a bounded re-drive loop whose total window exceeds the lease TTL + margin. Exhaustion resolves AUTOMATICALLY against current state: binding exists → silently attach; winner failed → dead_session/fresh-recovery flow with a visible notice. Never a dead button, never a silent wedge, never a duplicate.
+9. A ≥2-live-PTYs-per-sessionRef backstop detector alarms (ERROR-level invariant log).
+10. `corrected: true` on any verdict is ALWAYS user-visible (a pane notice), never a silent identity switch. `duplicate` on an attach verdict is a non-destructive "duplicate detected and ignored" notice; the client is never switched off its live terminal (I6).
+11. The legacy `clearDeadTerminals` census path remains as the fallback when the server does not ack the capability (legacy TS server) — capability-gated branch, NOT deletion.
+12. `dead_session` is a UI state, not a deletion: nothing is auto-closed, disk is never touched, and every terminal verdict has an exit affordance ("Start fresh here" reusing the same `createRequestId` / "Close pane") (I5/I7).
+13. Recovery is automatic, never offered: when the server knows enough to act, act; choices are only for genuinely dead sessions.
+14. Launch-time `INVALID_TERMINAL_ID` gets a bounded retry (F9) — same bounded re-drive machinery as SESSION_RESERVED — because attach verdicts racing terminal exit would otherwise funnel into a permanent-error dead-end.
+
+**Named red tests this plan must land (spec-mandated):** `warming-never-completes` (Task 2), `restart-storm-all-panes-warming` (Task 13), `two-clients-same-sessionRef` exactly-1-PTY (Task 6 + pin flip Task 14), `winner-dies-mid-claim` (Task 5), `winner-hangs-mid-claim` (Task 5), `loser-exhausts-then-holder-fails` (Task 12).
+
+**Wire surface after this plan (for reference in every task):**
+- `hello.capabilities.paneReconcileV1: true` (client opt-in); `ready.capabilities: {paneReconcileV1: true}` emitted iff hello opted in.
+- `pane.reconcile.request`: `{type, reconcileId, panes[]}`; pane = `{paneKey (opaque), kind: "terminal", mode, createRequestId (required), terminalId?, serverInstanceId?, sessionRef?{provider,sessionId}, resumeSessionId?, status?}`; cap 200 → error `RECONCILE_TOO_LARGE`.
+- `pane.reconcile.result`: `{type, reconcileId, bootId, serverInstanceId, verdicts[]}`; verdict = `{paneKey, verdict, terminalId?, sessionRef?, corrected?: true, reason?, duplicate?}`.
+- Verdict enum (6): `attach | respawn | fresh | dead_session | invalid | error` (`retry` deleted; `retryAfterMs` no longer appears on verdicts).
+- Error frames: existing `RECONCILE_TOO_LARGE`/`RECONCILE_UNAVAILABLE` + new `SESSION_RESERVED` with additive `retryAfterMs` field on the error frame; reconcile-scoped errors carry the `reconcileId` in `ErrorMsg.requestId`.
+
+---
+
+## File Structure
+
+**Rust (server):**
+- Modify: `crates/freshell-protocol/src/` (locate with `rg -n "enum ReconcileVerdict" crates/`) — verdict enum reshape, `ErrorMsg.retryAfterMs`, `SESSION_RESERVED` code.
+- Modify: `crates/freshell-ws/src/reconcile.rs` — verdict derivation: `error` reasons, sessionRef-level attach, keep the `unsupported_kind` arm untouched.
+- Modify: `crates/freshell-ws/src/existence.rs` — `SessionExistence::ProviderUnavailable` variant.
+- Modify: `crates/freshell-server/src/existence.rs` — concrete probe returns `ProviderUnavailable` when a known provider's session root is missing.
+- Modify: `crates/freshell-ws/src/registry.rs` — sessionRef lease + binding map + duplicate-PTY detector.
+- Modify: `crates/freshell-ws/src/terminal.rs` — bounded warming deferral in `handle_pane_reconcile`; lease acquire/release in the create path; ledger `record_binding` at winner bind.
+- Modify: `crates/freshell-ws/tests/pane_reconcile.rs` — updated retry-era tests + warming tests.
+- Create: `crates/freshell-ws/tests/session_ref_singleflight.rs` — D8 wire-level tests.
+
+**Client:**
+- Modify: `shared/ws-protocol.ts` — the two frame schemas + ready capabilities.
+- Modify: `src/store/paneTypes.ts` — `reconcileNotice`, `pendingReconcile` fields.
+- Modify: `src/store/panesSlice.ts` — `applyReconcileAttach`, `resetPaneForReconcileCreate`, dead-session/warming aggregation state.
+- Create: `src/lib/pane-reconcile.ts` — request builder + verdict folding + cardinality invariant.
+- Modify: `src/lib/ws-client.ts` — hello capability, ready-capabilities capture, in-flight-create replay suppression.
+- Modify: `src/App.tsx` — send request on ready-with-capability, fold results, gate legacy census.
+- Modify: `src/lib/terminal-restore.ts` — bypass arm/peek latch when capability active.
+- Modify: `src/components/TerminalView.tsx` — verdict-driven create args, SESSION_RESERVED + INVALID_TERMINAL_ID bounded retry, exhaustion auto-resolve, reconcile notices.
+- Create: `src/components/DeadSessionPanel.tsx` — the ONE batched adjudication panel.
+- Create: `src/components/ReconcileWarmingBanner.tsx` — the ONE warming banner (small; may be folded into App if <40 lines, implementer's call, but it must remain a single banner).
+
+**Tests (client/e2e):**
+- Create: `test/unit/lib/pane-reconcile.test.ts`, `test/unit/store/panesSlice.reconcile.test.ts`, `test/unit/lib/ws-client.reconcile.test.ts`, `test/unit/App.reconcile-adoption.test.tsx`, `test/unit/components/DeadSessionPanel.test.tsx`, `test/unit/components/TerminalView.session-reserved.test.tsx`.
+- Modify: `test/e2e-browser/specs/restore-contract-wall-rust.spec.ts` — flip the P1.7 pin (:1877-1880), update the double-restart guard (:2042).
+- Create: `test/e2e-browser/specs/reconcile-client-adoption-rust.spec.ts`.
+
+---
+
+### Task 1: Baseline verification
+
+**Files:** none modified (verification only; no commit).
+
+**Interfaces:**
+- Consumes: the worktree at `/home/dan/code/freshell/.worktrees/reconcile-client-adoption` (created by the workspace stage from `origin/main@2dfbba58`).
+- Produces: recorded proof the base is green so later failures are attributable to this lane.
+
+- [ ] **Step 1: Confirm base commit and node_modules**
+
+```bash
+cd /home/dan/code/freshell/.worktrees/reconcile-client-adoption
+git log --oneline -1        # expect: 2dfbba58 Merge pull request #536 ...
+ls node_modules/.bin/vitest # if missing: npm ci
+ls node_modules/tsx/dist/loader.mjs  # if missing after npm ci: ln -s ../node_modules/tsx node_modules/tsx (needed by freshell-ws MCP-injector tests)
+```
+
+- [ ] **Step 2: Rust baseline**
+
+```bash
+cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings
+cargo test -p freshell-ws
+```
+Expected: all green (2dfbba58 is a merged main state).
+
+- [ ] **Step 3: Focused client baseline (cheap sanity, not the coordinated suite)**
+
+```bash
+npm run test:vitest -- run test/unit/lib/terminal-restore.test.ts test/unit/store/panesSlice.test.ts
+```
+Expected: PASS. (The full coordinated suite runs in Task 15; the workspace stage already verified base green.)
+
+- [ ] **Step 4: Record baseline evidence** — paste the three command tails into your task report. No commit.
+
+---
+
+### Task 2: Server — delete `retry` from the wire; `error{index_warming}` + bounded single deferral
+
+**Files:**
+- Modify: `crates/freshell-protocol/src/` (locate: `rg -n "enum ReconcileVerdict" crates/` and `rg -n "retryAfterMs" crates/freshell-protocol/`)
+- Modify: `crates/freshell-ws/src/reconcile.rs` (retry emission site :249-253; `RETRY_AFTER_MS` const :24)
+- Modify: `crates/freshell-ws/src/terminal.rs` (`handle_pane_reconcile` :1911)
+- Modify: `crates/freshell-ws/src/lib.rs` or wherever `WsState` config lives (add deferral budget knob; locate: `rg -n "struct WsState" crates/freshell-ws/src/`)
+- Test: `crates/freshell-ws/tests/pane_reconcile.rs`
+
+**Interfaces:**
+- Consumes: `derive_verdicts(&ReconcileDeps<'_>, &[ReconcilePane]) -> Vec<PaneVerdict>` (`reconcile.rs:37`), `SessionExistence::{Present,Absent,Unknown}` (`existence.rs`), `handle_pane_reconcile(request, ws_tx, state) -> bool` (`terminal.rs:1911`), test helpers `spawn_server()`, `connect(url, pane_reconcile_v1)`, `next_frame_of_type` in `tests/pane_reconcile.rs`.
+- Produces: `ReconcileVerdict::Error` (wire `"error"`) replacing `ReconcileVerdict::Retry`; verdict `reason: "index_warming"`; `WsState.reconcile_deferral_budget_ms: u64` (default `2000`, settable in tests); `handle_pane_reconcile` performs at most ONE deferral then re-derives once. Later tasks (3, 4, 6, 7) rely on the `Error` variant and the budget knob.
+
+- [ ] **Step 1: Write the failing tests** — in `crates/freshell-ws/tests/pane_reconcile.rs`, following the file's existing helper pattern (`spawn_server`, `connect`, `next_frame_of_type`, fake existence probe). Also UPDATE the existing "honest unknowns → retry" test (design-doc test 9.1.6) to the new expectation — do not leave a test asserting `"retry"`.
+
+```rust
+/// warming-never-completes (council red test): a probe pinned to Unknown
+/// forever must yield error{index_warming} after ONE bounded deferral —
+/// never a hang, never a fake fresh/dead_session.
+#[tokio::test]
+async fn warming_never_completes_yields_error_index_warming() {
+    // Server with deferral budget shrunk for tests (50ms) and the default
+    // NoIndexProbe (always Unknown for known providers).
+    let server = spawn_server_with(|state| state.reconcile_deferral_budget_ms = 50).await;
+    let mut ws = connect(&server.url, true).await;
+    let started = std::time::Instant::now();
+    ws.send_json(reconcile_request_with_session_ref("claude", "sess-1")).await;
+    let result = next_frame_of_type(&mut ws, "pane.reconcile.result").await;
+    assert!(started.elapsed() < std::time::Duration::from_secs(2), "bounded, single deferral");
+    let v = &result["verdicts"][0];
+    assert_eq!(v["verdict"], "error");
+    assert_eq!(v["reason"], "index_warming");
+    assert!(v.get("retryAfterMs").is_none(), "retry is deleted from the wire");
+}
+
+/// The deferral is real: index warms during the wait -> the SECOND derivation
+/// answers with the warm verdict, not error.
+#[tokio::test]
+async fn warming_resolves_during_deferral_rederives() {
+    // Fake probe: first call Unknown, subsequent calls Absent (never observed
+    // -> per existing rules the verdict for a never-observed identity is
+    // fresh{identity_never_observed}).
+    let probe = FlippingProbe::new(vec![SessionExistence::Unknown, SessionExistence::Absent]);
+    let server = spawn_server_with_probe(probe, |state| state.reconcile_deferral_budget_ms = 50).await;
+    let mut ws = connect(&server.url, true).await;
+    ws.send_json(reconcile_request_with_session_ref("claude", "sess-2")).await;
+    let result = next_frame_of_type(&mut ws, "pane.reconcile.result").await;
+    assert_ne!(result["verdicts"][0]["verdict"], "error");
+}
+```
+
+Write `FlippingProbe` (implements `SessionExistenceProbe`, pops from a Vec, repeats last) and the `spawn_server_with`/`spawn_server_with_probe` variants next to the existing helpers — copy the existing `spawn_server`/`headless()` bodies and add the closure/probe parameters. If the existing harness already supports probe injection (design says "SessionExistence is a test fake per §5.1"), reuse it instead of duplicating.
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+cargo test -p freshell-ws --test pane_reconcile warming
+```
+Expected: FAIL — compile error (no `spawn_server_with`) or assertion failure on `"retry"` verdict.
+
+- [ ] **Step 3: Implement**
+
+(a) Protocol crate — reshape the enum (keep serde snake_case):
+
+```rust
+#[serde(rename_all = "snake_case")]
+pub enum ReconcileVerdict {
+    Attach,
+    Respawn,
+    Fresh,
+    DeadSession,
+    Invalid,
+    /// Terminal per-pane error state (replaces the deleted `retry`):
+    /// reason is one of "index_warming" | "provider_unavailable".
+    Error,
+}
+```
+Delete the `Retry` variant and remove `retry_after_ms` from `PaneVerdict` (grep all uses: `rg -n "Retry|retry_after_ms" crates/`). Keep `retryAfterMs` support on `ErrorMsg` OUT of this task (Task 6 adds it as an additive error-frame field).
+
+(b) `reconcile.rs:249-253` — replace the retry emission:
+
+```rust
+SessionExistence::Unknown => pane_verdict(pane, ReconcileVerdict::Error)
+    .with_reason("index_warming"),
+```
+(Adapt to the file's local constructor style — the existing arm at :249 shows it.) Delete the now-unused `RETRY_AFTER_MS` const at `reconcile.rs:24`, or repurpose it as `pub const RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT: u64 = 2000;`.
+
+(c) `WsState` — add `pub reconcile_deferral_budget_ms: u64` initialized to `RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT` wherever `WsState` is constructed (grep constructors).
+
+(d) `terminal.rs` `handle_pane_reconcile` (:1911) — bounded single deferral:
+
+```rust
+let mut verdicts = derive_verdicts(&deps, &request.panes);
+let warming = |vs: &[PaneVerdict]| vs.iter().any(|v|
+    matches!(v.verdict, ReconcileVerdict::Error)
+        && v.reason.as_deref() == Some("index_warming"));
+if warming(&verdicts) {
+    // SINGLE deferral: release any locks held for derivation, wait the
+    // budget once, re-derive once. Never loop.
+    tokio::time::sleep(Duration::from_millis(state.reconcile_deferral_budget_ms)).await;
+    verdicts = derive_verdicts(&rebuild_deps(&state), &request.panes);
+}
+// send pane.reconcile.result as before
+```
+IMPORTANT: `derive_verdicts` is a pure read over `ReconcileDeps { registry, identity, existence }` — make sure no registry/identity lock is held across the `sleep` (rebuild the deps after the await; the existing call site shows how they are built).
+
+- [ ] **Step 4: Run the full crate test suite**
+
+```bash
+cargo test -p freshell-ws
+```
+Expected: PASS, including the two new tests and all updated retry-era tests. If any other test in the workspace references `Retry` (grep first), update it to the new semantics in this task.
+
+- [ ] **Step 5: fmt + clippy + commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add -A crates/
+git commit -m "feat(ws): delete retry verdict; bounded index-warming deferral yields error{index_warming}"
+```
+
+---
+
+### Task 3: Server — `error{provider_unavailable}` for a known provider with no home
+
+**Files:**
+- Modify: `crates/freshell-ws/src/existence.rs` (enum + `NoIndexProbe` :76)
+- Modify: `crates/freshell-server/src/existence.rs` (`IndexExistenceProbe` cold peek :81)
+- Modify: `crates/freshell-ws/src/reconcile.rs`
+- Test: `crates/freshell-ws/tests/pane_reconcile.rs`
+
+**Interfaces:**
+- Consumes: `SessionExistence` enum, `SessionExistenceProbe` trait (`crates/freshell-ws/src/existence.rs`), `ReconcileVerdict::Error` (Task 2), `FlippingProbe`/probe-injection helpers (Task 2).
+- Produces: `SessionExistence::ProviderUnavailable` variant; verdict `error{reason:"provider_unavailable"}` emitted with NO deferral. Client Task 9 folds this reason.
+
+- [ ] **Step 1: Write the failing tests**
+
+```rust
+/// A known provider with no home on this machine is NOT warming — it gets
+/// the honest provider_unavailable label, immediately (no 2s deferral).
+#[tokio::test]
+async fn provider_unavailable_is_immediate_and_honest() {
+    let probe = FixedProbe::new(SessionExistence::ProviderUnavailable);
+    // Deliberately LARGE budget: proves no deferral happens for this reason.
+    let server = spawn_server_with_probe(probe, |state| state.reconcile_deferral_budget_ms = 30_000).await;
+    let mut ws = connect(&server.url, true).await;
+    let started = std::time::Instant::now();
+    ws.send_json(reconcile_request_with_session_ref("codex", "sess-9")).await;
+    let result = next_frame_of_type(&mut ws, "pane.reconcile.result").await;
+    assert!(started.elapsed() < std::time::Duration::from_secs(2));
+    let v = &result["verdicts"][0];
+    assert_eq!(v["verdict"], "error");
+    assert_eq!(v["reason"], "provider_unavailable");
+}
+```
+
+Plus a unit test in `crates/freshell-server/src/existence.rs` `#[cfg(test)]`: build an `IndexExistenceProbe` over a temp dir where the provider's session root does NOT exist → probe returns `ProviderUnavailable` (not `Unknown`); where the root exists but is cold → `Unknown` (unchanged). Read the existing probe code at `crates/freshell-server/src/existence.rs:81` first — reuse whatever path-resolution helper it already has for the provider session root.
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+cargo test -p freshell-ws --test pane_reconcile provider_unavailable
+cargo test -p freshell-server existence
+```
+Expected: FAIL — `ProviderUnavailable` variant doesn't exist.
+
+- [ ] **Step 3: Implement**
+  - `existence.rs`: add `ProviderUnavailable` to `SessionExistence`. `NoIndexProbe` behavior unchanged (still `Unknown` for known providers — test harnesses keep warming semantics).
+  - `crates/freshell-server/src/existence.rs`: before the cold-peek `Unknown` return, check the provider's session root directory; if the provider is known but its root does not exist on disk → return `SessionExistence::ProviderUnavailable`.
+  - `reconcile.rs`: add the match arm next to the Task-2 arm:
+
+```rust
+SessionExistence::ProviderUnavailable => pane_verdict(pane, ReconcileVerdict::Error)
+    .with_reason("provider_unavailable"),
+```
+  - The Task-2 `warming()` predicate in `terminal.rs` already only defers on `index_warming` — verify, don't widen.
+
+- [ ] **Step 4: Run tests**
+
+```bash
+cargo test -p freshell-ws && cargo test -p freshell-server
+```
+Expected: PASS.
+
+- [ ] **Step 5: fmt + clippy + commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add -A crates/
+git commit -m "feat(ws): provider_unavailable existence state yields immediate honest error verdict"
+```
+
+---
+
+### Task 4: Server — sessionRef-level attach in verdict derivation + duplicate-PTY backstop detector
+
+**Files:**
+- Modify: `crates/freshell-ws/src/registry.rs`
+- Modify: `crates/freshell-ws/src/reconcile.rs`
+- Test: `crates/freshell-ws/tests/pane_reconcile.rs` and `registry.rs` `#[cfg(test)]`
+
+**Interfaces:**
+- Consumes: the identity registry (`ReconcileDeps.identity`) mapping live terminals ↔ `SessionLocator` (stamping landed in commit 80772ff2 — locate the live lookup with `rg -n "SessionLocator" crates/freshell-ws/src/identity.rs crates/freshell-ws/src/registry.rs`).
+- Produces: `TerminalRegistry::live_terminal_for_session_ref(&SessionLocator) -> Option<String>`; `derive_verdicts` returns `attach{terminalId}` for a pane claiming a `sessionRef` that a live terminal already carries, regardless of `createRequestId`; `TerminalRegistry::alarm_if_duplicate_session_ref(&SessionLocator)` ERROR-logs when ≥2 live PTYs carry one sessionRef. Task 5/6 use both.
+
+- [ ] **Step 1: Write the failing tests**
+
+```rust
+/// Cross-client attach: a live terminal spawned under createRequestId A and
+/// bound to sessionRef S answers a reconcile claim from createRequestId B
+/// (a different client) with attach{terminalId of A's terminal}.
+#[tokio::test]
+async fn different_create_request_id_same_session_ref_gets_attach_to_winner() {
+    let server = spawn_server_default().await;
+    // Seed: headless terminal live in the registry, identity-stamped with
+    // sessionRef {claude, sess-x} (the existing tests seed identity directly
+    // — copy that seeding pattern).
+    let tid = seed_live_terminal_with_identity(&server, "claude", "sess-x").await;
+    let mut ws = connect(&server.url, true).await;
+    ws.send_json(reconcile_request(vec![pane_claim("cr-OTHER", Some(("claude", "sess-x")))])).await;
+    let result = next_frame_of_type(&mut ws, "pane.reconcile.result").await;
+    let v = &result["verdicts"][0];
+    assert_eq!(v["verdict"], "attach");
+    assert_eq!(v["terminalId"], tid);
+}
+```
+
+And a registry unit test: seed two live terminals stamped with the same sessionRef → `alarm_if_duplicate_session_ref` returns `true` (and, by inspection, emits `tracing::error!` with target `"invariant"` and message containing `duplicate_pty_for_session_ref`); with one live terminal → `false`.
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+cargo test -p freshell-ws --test pane_reconcile different_create_request_id
+cargo test -p freshell-ws duplicate_session_ref
+```
+Expected: FAIL (today derivation keys on `createRequestId` only — `newest_live_by_create_request_id`).
+
+- [ ] **Step 3: Implement**
+  - `registry.rs`:
+
+```rust
+/// Live terminal currently identity-stamped with this sessionRef, if any.
+pub fn live_terminal_for_session_ref(&self, locator: &SessionLocator) -> Option<String> { /* scan live rows joined with identity */ }
+
+/// D8 backstop: >=2 live PTYs carrying one sessionRef is the two-writers
+/// corruption shape. Alarm loudly; never kill silently.
+pub fn alarm_if_duplicate_session_ref(&self, locator: &SessionLocator) -> bool {
+    let live = /* count live terminals stamped with locator */;
+    if live >= 2 {
+        tracing::error!(target: "invariant",
+            provider = %locator.provider, session_id = %locator.session_id, live,
+            "duplicate_pty_for_session_ref: >=2 live PTYs share one sessionRef");
+        return true;
+    }
+    false
+}
+```
+Where identity lives (registry rows vs the separate identity registry) — follow how `derive_verdicts`' existing rows resolve identity today (`ReconcileDeps.identity`); put the lookup where the data actually is and expose it through whichever of the two structs `ReconcileDeps` already carries.
+  - `reconcile.rs`: in the per-pane derivation for `kind: terminal`, BEFORE the existing `createRequestId`-keyed resolution: if the pane claims a `sessionRef` and `live_terminal_for_session_ref` returns `Some(tid)` → verdict `attach{terminalId: tid, sessionRef: <server's ref>}`, with `corrected: true` iff the client's claimed `sessionRef`/`terminalId` disagreed with the server's truth (follow the existing corrected-computation pattern used by the current attach arm). Do NOT touch the `unsupported_kind` arm at :169.
+
+- [ ] **Step 4: Run tests**
+
+```bash
+cargo test -p freshell-ws
+```
+Expected: PASS (all existing decision-table tests still green — the new branch only fires when a live terminal carries the claimed ref, which previously produced `attach` via the createRequestId path or a wrong `respawn`; if any existing test asserted `respawn` in that situation, that test was pinning D8 itself — update it and say so in the commit).
+
+- [ ] **Step 5: fmt + clippy + commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add -A crates/
+git commit -m "feat(ws): sessionRef-level attach in verdict derivation + duplicate-PTY invariant alarm"
+```
+
+---
+
+### Task 5: Server — sessionRef liveness-bound lease in the registry
+
+**Files:**
+- Modify: `crates/freshell-ws/src/registry.rs`
+- Test: `crates/freshell-ws/src/registry.rs` `#[cfg(test)]` (unit level; wire level is Task 6)
+
+**Interfaces:**
+- Consumes: `TerminalRegistry` internals (existing `keyed_create_inflight` pattern at `registry.rs:1599-1608` is the shape to mirror), `SessionLocator`.
+- Produces (exact API Task 6 calls):
+
+```rust
+pub const SESSION_REF_LEASE_TTL_MS: u64 = 20_000; // ~2x the 10s spawn budget
+pub const SESSION_RESERVED_RETRY_AFTER_MS: u64 = 1_000;
+
+pub enum SessionRefClaim {
+    Acquired,
+    Held { retry_after_ms: u64 },
+    /// TTL expired on a holder with a recorded child: caller must kill pid,
+    /// CONFIRM death, then call force_release_after_confirmed_kill and re-claim.
+    ExpiredNeedsKill { pid: u32 },
+    BoundElsewhere { terminal_id: String },
+}
+
+impl TerminalRegistry {
+    pub fn claim_session_ref(&self, locator: &SessionLocator, holder_create_request_id: &str, holder_conn: u64, now_ms: u64) -> SessionRefClaim;
+    pub fn set_session_ref_lease_pid(&self, locator: &SessionLocator, holder_create_request_id: &str, pid: u32);
+    /// Spawn succeeded: record binding, release lease, run the duplicate alarm.
+    /// Returns false if the lease was revoked while spawning (caller must kill
+    /// its own child and fail the create loudly).
+    pub fn complete_session_ref_claim(&self, locator: &SessionLocator, holder_create_request_id: &str, terminal_id: &str) -> bool;
+    pub fn fail_session_ref_claim(&self, locator: &SessionLocator, holder_create_request_id: &str);
+    /// Connection death: release this conn's leases. Returns (locator_key, pid)
+    /// pairs whose in-flight children the caller must kill (kill-before-release
+    /// applies: entries WITH a pid are returned still-held; caller kills,
+    /// confirms, then calls force_release_after_confirmed_kill).
+    pub fn release_session_ref_leases_for_conn(&self, conn: u64) -> Vec<(SessionLocator, Option<u32>)>;
+    pub fn force_release_after_confirmed_kill(&self, locator: &SessionLocator);
+}
+```
+
+Semantics (council-gated, restated as code truths):
+- `claim_session_ref` checks, in order: live binding (`live_terminal_for_session_ref`, Task 4) → `BoundElsewhere`; a held, unexpired lease → `Held{SESSION_RESERVED_RETRY_AFTER_MS}`; a held lease past `acquired_at_ms + SESSION_REF_LEASE_TTL_MS` → if it has a pid, `ExpiredNeedsKill{pid}`; if it has NO pid (holder hung pre-spawn), set `revoked = true` on the lease, log ERROR, and return `Held{...}` — hold closed, never release what you can't kill.
+- A lease whose holder later calls `complete_session_ref_claim` while `revoked` gets `false` back.
+- Leases released on `complete` (bind), `fail`, or conn cleanup (pid-less entries release immediately; pid-carrying entries follow kill-before-release via the returned Vec).
+
+- [ ] **Step 1: Write the failing unit tests** (in `registry.rs` `#[cfg(test)]`, `now_ms` passed explicitly so no sleeping):
+
+```rust
+#[test]
+fn second_claim_while_held_is_reserved() {
+    let reg = test_registry();
+    let s = locator("claude", "s1");
+    assert!(matches!(reg.claim_session_ref(&s, "cr-A", 1, 1000), SessionRefClaim::Acquired));
+    assert!(matches!(reg.claim_session_ref(&s, "cr-B", 2, 1500), SessionRefClaim::Held { .. }));
+}
+
+#[test]
+fn completed_claim_yields_bound_elsewhere() {
+    let reg = test_registry();
+    let s = locator("claude", "s1");
+    reg.claim_session_ref(&s, "cr-A", 1, 1000);
+    assert!(reg.complete_session_ref_claim(&s, "cr-A", "term-1"));
+    match reg.claim_session_ref(&s, "cr-B", 2, 2000) {
+        SessionRefClaim::BoundElsewhere { terminal_id } => assert_eq!(terminal_id, "term-1"),
+        other => panic!("expected BoundElsewhere, got {other:?}"),
+    }
+}
+
+/// winner-dies-mid-claim (council red test): holder conn death releases the
+/// pid-less lease; the loser's next claim wins.
+#[test]
+fn winner_dies_mid_claim_releases_lease() {
+    let reg = test_registry();
+    let s = locator("claude", "s1");
+    reg.claim_session_ref(&s, "cr-A", 1, 1000);
+    let to_kill = reg.release_session_ref_leases_for_conn(1);
+    assert!(to_kill.iter().all(|(_, pid)| pid.is_none()));
+    assert!(matches!(reg.claim_session_ref(&s, "cr-B", 2, 1500), SessionRefClaim::Acquired));
+}
+
+/// winner-hangs-mid-claim (council red test): TTL expiry with a recorded
+/// child pid demands kill-before-release; confirmed kill releases; a pid-less
+/// hung holder is revoked and HELD CLOSED, never released.
+#[test]
+fn winner_hangs_mid_claim_ttl_is_kill_before_release() {
+    let reg = test_registry();
+    let s = locator("claude", "s1");
+    reg.claim_session_ref(&s, "cr-A", 1, 1000);
+    reg.set_session_ref_lease_pid(&s, "cr-A", 4242);
+    let late = 1000 + SESSION_REF_LEASE_TTL_MS + 1;
+    match reg.claim_session_ref(&s, "cr-B", 2, late) {
+        SessionRefClaim::ExpiredNeedsKill { pid } => assert_eq!(pid, 4242),
+        other => panic!("expected ExpiredNeedsKill, got {other:?}"),
+    }
+    reg.force_release_after_confirmed_kill(&s);
+    assert!(matches!(reg.claim_session_ref(&s, "cr-B", 2, late + 1), SessionRefClaim::Acquired));
+}
+
+#[test]
+fn hung_holder_without_pid_is_revoked_and_held_closed() {
+    let reg = test_registry();
+    let s = locator("claude", "s1");
+    reg.claim_session_ref(&s, "cr-A", 1, 1000);
+    let late = 1000 + SESSION_REF_LEASE_TTL_MS + 1;
+    assert!(matches!(reg.claim_session_ref(&s, "cr-B", 2, late), SessionRefClaim::Held { .. }));
+    // The revoked holder's late completion is rejected.
+    assert!(!reg.complete_session_ref_claim(&s, "cr-A", "term-late"));
+}
+```
+(`test_registry()`/`locator()` helpers: copy the construction pattern from the existing registry tests — `rg -n "fn test" crates/freshell-ws/src/registry.rs`.)
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+cargo test -p freshell-ws claim_session_ref -- --nocapture || cargo test -p freshell-ws session_ref
+```
+Expected: FAIL — compile errors (API absent).
+
+- [ ] **Step 3: Implement** the lease per the Produces block: a `Mutex<HashMap<String /* "provider\u{0}sessionId" */, SessionRefLease>>` next to `keyed_create_inflight`, plus `session_ref_bindings: Mutex<HashMap<String, String>>` (locator → terminalId) consulted by `claim_session_ref` alongside `live_terminal_for_session_ref` (a binding whose terminal is no longer live must NOT yield `BoundElsewhere` — check liveness before answering, so a dead winner doesn't strand losers).
+
+- [ ] **Step 4: Run tests**
+
+```bash
+cargo test -p freshell-ws
+```
+Expected: PASS.
+
+- [ ] **Step 5: fmt + clippy + commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add -A crates/
+git commit -m "feat(ws): sessionRef liveness-bound lease with TTL kill-before-release semantics"
+```
+
+---
+
+### Task 6: Server — create-path lease integration, `SESSION_RESERVED` error, ledger write at winner bind
+
+**Files:**
+- Modify: `crates/freshell-protocol/src/` (add `SESSION_RESERVED` error code + additive `retryAfterMs: Option<u64>` on `ErrorMsg`, `skip_serializing_if = "Option::is_none"`)
+- Modify: `crates/freshell-ws/src/terminal.rs` (create path around the `KeyedCreateGuard` at :907 and adopt loop :937-976; connection-close cleanup site)
+- Test: Create `crates/freshell-ws/tests/session_ref_singleflight.rs`
+
+**Interfaces:**
+- Consumes: Task 5 lease API; `KeyedCreateGuard` (`terminal.rs:907`); pane-ledger write API from wave A — `record_binding(&BindingWrite) -> io::Result<()>` with `BindingWrite { provider, session_id, terminal_id, mode, cwd, create_request_id, now_ms }` (locate the handle the inventory-stamping read path already uses: `rg -n "record_binding\|pane_ledger\|lookup_by_session" crates/`).
+- Produces: on a `paneReconcileV1`-negotiated connection, a `terminal.create` carrying a resume `sessionRef` runs the lease discipline; losers receive `error{code: SESSION_RESERVED, requestId: <createRequestId>, retryAfterMs: 1000}`; the winner's successful spawn binds sessionRef→terminalId in registry AND ledger. Non-negotiated (frozen legacy) connections are byte-for-byte unchanged.
+
+- [ ] **Step 1: Write the failing wire-level tests** in the new `tests/session_ref_singleflight.rs` (copy the helper mod from `tests/pane_reconcile.rs`):
+
+```rust
+/// two-clients-same-sessionRef (council red test): two negotiated
+/// connections, DIFFERENT createRequestIds, same sessionRef resume ->
+/// exactly one PTY; the loser is reserved then attaches to the winner.
+#[tokio::test]
+async fn two_clients_same_session_ref_yield_exactly_one_pty() {
+    let server = spawn_server_default().await;
+    let mut a = connect(&server.url, true).await;
+    let mut b = connect(&server.url, true).await;
+    a.send_json(terminal_create_resume("cr-A", "claude", "sess-dup")).await;
+    b.send_json(terminal_create_resume("cr-B", "claude", "sess-dup")).await;
+    // One connection gets terminal.created (spawn); collect both outcomes.
+    let (created, other) = race_created_and_error(&mut a, &mut b).await;
+    let tid = created["terminalId"].as_str().unwrap().to_string();
+    // The other either got SESSION_RESERVED then, on re-send, terminal.created
+    // for the SAME terminalId (adopt/attach), or adopted immediately.
+    if other["type"] == "error" {
+        assert_eq!(other["code"], "SESSION_RESERVED");
+        assert!(other["retryAfterMs"].as_u64().unwrap() >= 1);
+        // re-send after the hint
+        resend_create_and_expect_created_for(&mut a, &mut b, &tid).await;
+    } else {
+        assert_eq!(other["terminalId"], tid);
+    }
+    assert_eq!(server.live_pty_count_for_session("claude", "sess-dup").await, 1);
+}
+
+/// Legacy connections (no capability) never see SESSION_RESERVED — the
+/// frozen-client create path is byte-for-byte unchanged.
+#[tokio::test]
+async fn legacy_connection_create_path_unchanged() {
+    let server = spawn_server_default().await;
+    let mut legacy = connect(&server.url, false).await;
+    legacy.send_json(terminal_create_resume("cr-L", "claude", "sess-legacy")).await;
+    let created = next_frame_of_type(&mut legacy, "terminal.created").await;
+    assert!(created["terminalId"].is_string());
+}
+
+/// Winner bind writes the ledger: after the winner's terminal.created,
+/// lookup_by_session resolves sessionRef -> that terminalId.
+#[tokio::test]
+async fn winner_bind_writes_ledger_binding() {
+    let server = spawn_server_default().await;
+    let mut a = connect(&server.url, true).await;
+    a.send_json(terminal_create_resume("cr-A", "claude", "sess-led")).await;
+    let created = next_frame_of_type(&mut a, "terminal.created").await;
+    let resolved = server.ledger_lookup("claude", "sess-led").await;
+    assert_eq!(resolved.as_deref(), Some(created["terminalId"].as_str().unwrap()));
+}
+```
+Helper notes: `terminal_create_resume` builds the same `terminal.create` JSON the client sends for resume (copy field names from an existing create-with-resume test or `shared/ws-protocol.ts` `TerminalCreateSchema:301` — it is `.strict()`, so it IS the wire truth). `live_pty_count_for_session` / `ledger_lookup` are small test accessors — expose them via the existing test-server handle pattern (the harness owns the state). Headless mode (`headless()`) keeps spawns cheap.
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+cargo test -p freshell-ws --test session_ref_singleflight
+```
+Expected: FAIL — today both creates spawn (two PTYs), no SESSION_RESERVED code exists.
+
+- [ ] **Step 3: Implement**
+  - Protocol: add `SESSION_RESERVED` to the error-code enum; add `retry_after_ms: Option<u64>` (wire `retryAfterMs`) to `ErrorMsg`.
+  - `terminal.rs` create path (inside the negotiated branch that already hosts the keyed-create adopt loop :937-976):
+    1. If the create carries a resume `sessionRef` (provider + sessionId resolvable from the create body): `claim_session_ref(...)` with the connection's id and `now_ms`.
+    2. `BoundElsewhere{terminal_id}` → emit `terminal.created` for that existing terminal (mirror the adopt loop's emission — attach to the winner, spawn nothing).
+    3. `Held{retry_after_ms}` → send `error{SESSION_RESERVED, requestId: create.request_id, retryAfterMs}`; do not spawn; do not charge the rate limiter (adopt precedent: `create_protection.rs:250`).
+    4. `ExpiredNeedsKill{pid}` → kill the pid (SIGKILL), confirm death by polling `kill(pid, 0)` for ESRCH up to 500ms; confirmed → `force_release_after_confirmed_kill` then re-claim and proceed; NOT confirmed → treat as `Held` + `tracing::error!` (hold closed).
+    5. `Acquired` → proceed to spawn; immediately after the PTY child exists call `set_session_ref_lease_pid`; on success call `complete_session_ref_claim` — if it returns `false` (revoked), kill the just-spawned child, confirm, and answer the create with a plain error (fail loud); on spawn failure call `fail_session_ref_claim`.
+    6. On `complete_session_ref_claim == true`, write the ledger binding (best-effort, NEVER blocks the create):
+
+```rust
+if let Err(e) = ledger.record_binding(&BindingWrite {
+    provider, session_id, terminal_id, mode, cwd, create_request_id, now_ms,
+}) {
+    tracing::error!(target: "invariant", error = %e,
+        "pane-ledger record_binding failed at respawn-winner bind");
+}
+```
+  - Connection-close cleanup (find where the ws connection teardown already releases per-conn resources): call `release_session_ref_leases_for_conn(conn)`; for returned pid-carrying entries, kill + confirm + `force_release_after_confirmed_kill` (same discipline as step 4).
+
+- [ ] **Step 4: Run tests**
+
+```bash
+cargo test -p freshell-ws
+```
+Expected: PASS including `create_protection.rs` and `pane_reconcile.rs` suites.
+
+- [ ] **Step 5: fmt + clippy + commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add -A crates/
+git commit -m "feat(ws): per-sessionRef single-flight on the create path with SESSION_RESERVED + ledger bind (closes D8 server-side)"
+```
+
+---
+
+### Task 7: Client — protocol schemas + pane content fields
+
+**Files:**
+- Modify: `shared/ws-protocol.ts` (ClientMessageSchema union :569, ServerMessage union :988)
+- Modify: `src/store/paneTypes.ts` (`TerminalPaneContent` :68-97)
+- Test: Create `test/unit/shared/ws-protocol.reconcile.test.ts`
+
+**Interfaces:**
+- Consumes: existing Zod patterns in `shared/ws-protocol.ts` (`HelloSchema:267`, `TerminalCreateSchema:301`).
+- Produces (exact names later tasks import from `shared/ws-protocol.ts`):
+  - `ReconcileSessionRefSchema` (`{provider: string, sessionId: string}` — reuse an existing sessionRef schema if one exists: `rg -n "sessionRef" shared/ws-protocol.ts` first),
+  - `ReconcilePaneSchema`, `PaneReconcileRequestSchema` (+ in `ClientMessageSchema` union), types `ReconcilePane`, `PaneReconcileRequest`,
+  - `PaneVerdictSchema` with `verdict: z.enum(['attach','respawn','fresh','dead_session','invalid','error'])`, `PaneReconcileResultSchema`, types `PaneVerdict`, `PaneReconcileResultMessage` (+ in the `ServerMessage` union),
+  - `ReadyCapabilitiesSchema = z.object({ paneReconcileV1: z.literal(true).optional() }).optional()` merged into the ready message type,
+  - error-frame type gains optional `retryAfterMs?: number` and the `SESSION_RESERVED` code string.
+  - `TerminalPaneContent` gains: `reconcileNotice?: string` and `pendingReconcile?: 'respawn' | 'fresh'`.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import { describe, it, expect } from 'vitest'
+import {
+  PaneReconcileRequestSchema,
+  PaneReconcileResultSchema,
+  ClientMessageSchema,
+} from '@/../shared/ws-protocol' // match the repo's existing import path for shared/
+
+describe('pane.reconcile schemas', () => {
+  const request = {
+    type: 'pane.reconcile.request',
+    reconcileId: 'rec-1',
+    panes: [{
+      paneKey: 'tab1:paneA', kind: 'terminal', mode: 'claude',
+      createRequestId: 'cr-1', terminalId: 'term-1',
+      sessionRef: { provider: 'claude', sessionId: 's-1' }, status: 'running',
+    }],
+  }
+  it('parses a valid request and accepts it in the client union', () => {
+    expect(PaneReconcileRequestSchema.parse(request)).toBeTruthy()
+    expect(ClientMessageSchema.safeParse(request).success).toBe(true)
+  })
+  it('rejects >200 panes', () => {
+    const big = { ...request, panes: Array.from({ length: 201 }, (_, i) => ({ ...request.panes[0], paneKey: `t:${i}` })) }
+    expect(PaneReconcileRequestSchema.safeParse(big).success).toBe(false)
+  })
+  it('parses a result with the 6-verdict enum and no retry', () => {
+    const result = {
+      type: 'pane.reconcile.result', reconcileId: 'rec-1', bootId: 'b1', serverInstanceId: 'srv1',
+      verdicts: [
+        { paneKey: 'tab1:paneA', verdict: 'attach', terminalId: 'term-1', corrected: true },
+        { paneKey: 'tab1:paneB', verdict: 'error', reason: 'index_warming' },
+      ],
+    }
+    expect(PaneReconcileResultSchema.parse(result)).toBeTruthy()
+    expect(PaneReconcileResultSchema.safeParse({ ...result, verdicts: [{ paneKey: 'x', verdict: 'retry' }] }).success).toBe(false)
+  })
+})
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+npm run test:vitest -- run test/unit/shared/ws-protocol.reconcile.test.ts
+```
+Expected: FAIL — exports don't exist.
+
+- [ ] **Step 3: Implement** the schemas per the Produces block (follow the file's existing style; the request schema mirrors the Rust wire exactly — field names camelCase, `panes: z.array(ReconcilePaneSchema).max(200)`). Add the two `TerminalPaneContent` fields with doc comments:
+
+```ts
+/** One-shot user-visible reconcile notice (corrected identity, fresh-by-reason, duplicate ignored). Rendered then cleared by TerminalView. */
+reconcileNotice?: string
+/** Set by verdict folding; consumed by TerminalView when it sends terminal.create. 'respawn' = create-with-resume from sessionRef; 'fresh' = clean create. */
+pendingReconcile?: 'respawn' | 'fresh'
+```
+Check `normalizePaneContent` (`panesSlice.ts:61`) — if it whitelists fields, add both.
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npm run test:vitest -- run test/unit/shared/ws-protocol.reconcile.test.ts test/unit/store/panesSlice.test.ts
+```
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add shared/ws-protocol.ts src/store/paneTypes.ts src/store/panesSlice.ts test/unit/shared/ws-protocol.reconcile.test.ts
+git commit -m "feat(protocol): pane.reconcile client schemas, ready capabilities, reconcile pane fields"
+```
+
+---
+
+### Task 8: Client — panesSlice reducers for verdict folding
+
+**Files:**
+- Modify: `src/store/panesSlice.ts`
+- Test: Create `test/unit/store/panesSlice.reconcile.test.ts`
+
+**Interfaces:**
+- Consumes: `TerminalPaneContent` fields from Task 7; existing helpers in `panesSlice.ts` for locating a pane's content by `(tabId, paneId)` (see how `clearTerminalContentForRecreate` :544-568 walks the layout — reuse its lookup, NOT its body).
+- Produces (exported actions later tasks dispatch):
+  - `applyReconcileAttach({tabId, paneId, terminalId, serverInstanceId?, sessionRef?, corrected?, duplicate?})`
+  - `resetPaneForReconcileCreate({tabId, paneId, intent: 'respawn'|'fresh', sessionRef?, reason?, corrected?})`
+  - `setPaneReconcileNotice({tabId, paneId, notice})` / `clearPaneReconcileNotice({tabId, paneId})`
+  - `setDeadSessionAdjudication(entries: DeadSessionEntry[])` / `resolveDeadSessionEntry({tabId, paneId})` / `clearDeadSessionAdjudication()` — non-persisted state field `deadSessionAdjudication: DeadSessionEntry[]` where `DeadSessionEntry = {tabId, paneId, title: string, mode: string, sessionRef?: {provider, sessionId}, reason?: string}`
+  - `setReconcileWarming({count, paneRefs: {tabId, paneId}[]})` / `clearReconcileWarming()` — non-persisted field `reconcileWarming: {count: number, paneRefs: {tabId: string, paneId: string}[]} | null`
+- CRITICAL: none of these reducers may mint a `createRequestId`. `resetPaneForReconcileCreate` PRESERVES the existing `createRequestId` (this is the load-bearing difference from `clearTerminalContentForRecreate`, which mints — D4).
+
+- [ ] **Step 1: Write the failing tests** (copy store-construction boilerplate from `test/unit/store/panesSlice.test.ts`):
+
+```ts
+describe('reconcile reducers', () => {
+  it('applyReconcileAttach sets terminalId/status without touching createRequestId', () => {
+    const state = stateWithTerminalPane({ createRequestId: 'cr-keep', terminalId: undefined, status: 'creating' })
+    const next = panesReducer(state, applyReconcileAttach({ tabId: 'tab1', paneId: 'p1', terminalId: 'term-9', serverInstanceId: 'srv-2', sessionRef: { provider: 'claude', sessionId: 's1' } }))
+    const c = terminalContent(next, 'tab1', 'p1')
+    expect(c.terminalId).toBe('term-9')
+    expect(c.status).toBe('running')
+    expect(c.createRequestId).toBe('cr-keep')   // council rule: never re-minted
+    expect(c.restoreError).toBeUndefined()
+  })
+  it('applyReconcileAttach with corrected sets a visible notice', () => {
+    const next = panesReducer(stateWithTerminalPane({}), applyReconcileAttach({ tabId: 'tab1', paneId: 'p1', terminalId: 't', corrected: true }))
+    expect(terminalContent(next, 'tab1', 'p1').reconcileNotice).toMatch(/corrected/i)
+  })
+  it('resetPaneForReconcileCreate(respawn) clears handles, keeps createRequestId, sets server-named sessionRef', () => {
+    const state = stateWithTerminalPane({ createRequestId: 'cr-keep', terminalId: 'dead', streamId: 'st', sessionRef: { provider: 'claude', sessionId: 'client-guess' } })
+    const next = panesReducer(state, resetPaneForReconcileCreate({ tabId: 'tab1', paneId: 'p1', intent: 'respawn', sessionRef: { provider: 'claude', sessionId: 'server-truth' } }))
+    const c = terminalContent(next, 'tab1', 'p1')
+    expect(c.terminalId).toBeUndefined(); expect(c.streamId).toBeUndefined()
+    expect(c.status).toBe('creating')
+    expect(c.createRequestId).toBe('cr-keep')
+    expect(c.sessionRef).toEqual({ provider: 'claude', sessionId: 'server-truth' })
+    expect(c.pendingReconcile).toBe('respawn')
+  })
+  it('resetPaneForReconcileCreate(fresh) clears session identity and notes the reason', () => {
+    const state = stateWithTerminalPane({ createRequestId: 'cr-keep', sessionRef: { provider: 'claude', sessionId: 'gone' }, resumeSessionId: 'gone' })
+    const next = panesReducer(state, resetPaneForReconcileCreate({ tabId: 'tab1', paneId: 'p1', intent: 'fresh', reason: 'identity_never_observed' }))
+    const c = terminalContent(next, 'tab1', 'p1')
+    expect(c.sessionRef).toBeUndefined(); expect(c.resumeSessionId).toBeUndefined()
+    expect(c.pendingReconcile).toBe('fresh')
+    expect(c.reconcileNotice).toMatch(/identity_never_observed/)
+  })
+  it('dead-session adjudication is one batched list', () => {
+    let s = panesReducer(undefined, setDeadSessionAdjudication([
+      { tabId: 't1', paneId: 'p1', title: 'a', mode: 'claude' },
+      { tabId: 't1', paneId: 'p2', title: 'b', mode: 'codex' },
+    ]))
+    expect(s.deadSessionAdjudication).toHaveLength(2)
+    s = panesReducer(s, resolveDeadSessionEntry({ tabId: 't1', paneId: 'p1' }))
+    expect(s.deadSessionAdjudication).toHaveLength(1)
+  })
+})
+```
+(Write `stateWithTerminalPane`/`terminalContent` helpers in the test using the slice's real initializers; the existing `panesSlice.test.ts` shows how a layout with a terminal pane is seeded.)
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+npm run test:vitest -- run test/unit/store/panesSlice.reconcile.test.ts
+```
+Expected: FAIL — actions don't exist.
+
+- [ ] **Step 3: Implement** the reducers per the Produces block. Notice copy (exact strings, reused by later tasks/tests):
+  - corrected: `Session identity corrected by server — this pane now points at its live session.`
+  - duplicate: `A duplicate terminal for this session was detected and ignored.`
+  - fresh with reason: `` `Started fresh (${reason}).` ``
+  Ensure `deadSessionAdjudication` and `reconcileWarming` are stripped from persistence (check `persistMiddleware.ts:484`'s strip list — it already strips `restoreFallbackAttemptsByPane`; add these two the same way).
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npm run test:vitest -- run test/unit/store/panesSlice.reconcile.test.ts test/unit/store/panesSlice.test.ts test/unit/store/createRequestIdStability.test.ts
+```
+Expected: PASS (the stability suite proves we didn't regress P1.6).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/store/panesSlice.ts src/store/persistMiddleware.ts test/unit/store/panesSlice.reconcile.test.ts
+git commit -m "feat(store): reconcile verdict fold reducers - attach/reset without createRequestId re-mint, batched dead-session state"
+```
+
+---
+
+### Task 9: Client — `pane-reconcile.ts` (request builder + verdict folding + cardinality invariant)
+
+**Files:**
+- Create: `src/lib/pane-reconcile.ts`
+- Test: Create `test/unit/lib/pane-reconcile.test.ts`
+
+**Interfaces:**
+- Consumes: Task 7 schemas/types; Task 8 actions; the pane-tree walk — reuse/extract the logic of `collectTerminalPaneTargets` (`App.tsx:811`) rather than re-deriving it (either import it if exported, or move it into this module and re-export for App).
+- Produces (exact exports):
+
+```ts
+export function buildReconcileRequest(state: RootState): PaneReconcileRequest | null
+export function buildReconcileRequestForPanes(state: RootState, targets: {tabId: string, paneId: string}[]): PaneReconcileRequest | null
+export interface FoldOutcome { attached: number; respawned: number; fresh: number; dead: number; warming: number; invalid: number; cardinalityViolation: boolean }
+export function foldVerdicts(dispatch: AppDispatch, request: PaneReconcileRequest, result: PaneReconcileResultMessage): FoldOutcome
+export function paneKeyFor(tabId: string, paneId: string): string   // `${tabId}:${paneId}`
+```
+- Rules: panes without a terminal content or without `createRequestId` are skipped; >200 panes → `console.error` breadcrumb + first 200 sent; `foldVerdicts` FIRST checks cardinality (`verdicts.length === request.panes.length` AND every `paneKey` matches 1:1) — on violation it dispatches NOTHING except the outcome flag (the caller falls back to the legacy census, Task 11); `paneKey` is parsed back via the request's own pane list (index paneKey→{tabId,paneId} from the request, never by string-splitting server input).
+
+- [ ] **Step 1: Write the failing tests**
+
+```ts
+describe('buildReconcileRequest', () => {
+  it('collects terminal panes with paneKey tab:pane and required createRequestId', () => {
+    const state = storeStateWith2TerminalPanes() // helper: seed via real reducers
+    const req = buildReconcileRequest(state)!
+    expect(req.type).toBe('pane.reconcile.request')
+    expect(req.panes).toHaveLength(2)
+    expect(req.panes[0].paneKey).toBe(paneKeyFor('tab1', 'p1'))
+    expect(req.panes[0].createRequestId).toBeTruthy()
+    expect(req.panes[0].kind).toBe('terminal')
+  })
+  it('returns null with no terminal panes', () => {
+    expect(buildReconcileRequest(emptyState())).toBeNull()
+  })
+})
+
+describe('foldVerdicts', () => {
+  it('dispatches the right action per verdict', () => {
+    const { req, dispatch, dispatched } = foldHarness([
+      ['attach',       { terminalId: 'T1' }],
+      ['respawn',      { sessionRef: { provider: 'claude', sessionId: 's' } }],
+      ['fresh',        { reason: 'identity_never_observed' }],
+      ['dead_session', { sessionRef: { provider: 'codex', sessionId: 'gone' } }],
+      ['error',        { reason: 'index_warming' }],
+    ])
+    const outcome = foldVerdicts(dispatch, req, resultFor(req, dispatched.verdicts))
+    expect(outcome).toMatchObject({ attached: 1, respawned: 1, fresh: 1, dead: 1, warming: 1, cardinalityViolation: false })
+    expect(dispatched.types).toContain(applyReconcileAttach.type)
+    expect(dispatched.types).toContain(resetPaneForReconcileCreate.type)
+    expect(dispatched.types).toContain(setDeadSessionAdjudication.type)
+    expect(dispatched.types).toContain(setReconcileWarming.type)
+  })
+  it('dead sessions are batched into ONE setDeadSessionAdjudication dispatch (never N)', () => {
+    const { req, dispatch, dispatched } = foldHarnessAllDead(3)
+    foldVerdicts(dispatch, req, deadResultFor(req))
+    expect(dispatched.countOf(setDeadSessionAdjudication.type)).toBe(1)
+    expect(dispatched.lastPayloadOf(setDeadSessionAdjudication.type)).toHaveLength(3)
+  })
+  it('cardinality violation folds NOTHING and flags the caller', () => {
+    const { req, dispatch, dispatched } = foldHarness([['attach', { terminalId: 'T1' }]])
+    const short = { ...resultFor(req, []), verdicts: [] }
+    const outcome = foldVerdicts(dispatch, req, short)
+    expect(outcome.cardinalityViolation).toBe(true)
+    expect(dispatched.types).toHaveLength(0)
+  })
+  it('error{provider_unavailable} becomes a per-pane restoreError, not warming', () => {
+    const { req, dispatch, dispatched } = foldHarness([['error', { reason: 'provider_unavailable' }]])
+    const outcome = foldVerdicts(dispatch, req, resultFor(req, dispatched.verdicts))
+    expect(outcome.warming).toBe(0)
+    // folded via the existing restoreError rendering path
+  })
+})
+```
+(Build `foldHarness` with a recording dispatch; seed state through real reducers so paneKeys resolve.)
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+npm run test:vitest -- run test/unit/lib/pane-reconcile.test.ts
+```
+Expected: FAIL — module doesn't exist.
+
+- [ ] **Step 3: Implement.** Fold mapping (complete):
+  - `attach` → `applyReconcileAttach({..., terminalId, serverInstanceId: result.serverInstanceId, sessionRef, corrected, duplicate})`
+  - `respawn` → `resetPaneForReconcileCreate({..., intent: 'respawn', sessionRef: verdict.sessionRef, corrected})`
+  - `fresh` → `resetPaneForReconcileCreate({..., intent: 'fresh', reason: verdict.reason})`
+  - `dead_session` → collect `{tabId, paneId, title, mode, sessionRef, reason}`; after the loop, ONE `setDeadSessionAdjudication(all)`; ALSO set the per-pane loud breadcrumb via the existing restoreError shape (dispatch the existing action that sets `content.restoreError` — locate with `rg -n "restoreError" src/store/panesSlice.ts` and reuse; if only reachable via another reducer, extend `resetPaneForReconcileCreate`-style with a small `setPaneRestoreError` reducer in Task 8's file — keep it in panesSlice).
+  - `invalid` → per-pane restoreError with `reason` (loud, non-destructive) + count in outcome.
+  - `error` + `reason === 'index_warming'` → collect; after loop ONE `setReconcileWarming({count, paneRefs})`.
+  - `error` + `reason === 'provider_unavailable'` → per-pane restoreError `PROVIDER_UNAVAILABLE`.
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npm run test:vitest -- run test/unit/lib/pane-reconcile.test.ts
+```
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/lib/pane-reconcile.ts test/unit/lib/pane-reconcile.test.ts src/store/panesSlice.ts
+git commit -m "feat(client): pane-reconcile module - request builder, verdict folding, cardinality invariant"
+```
+
+---
+
+### Task 10: Client — ws-client capability + ready-capabilities + replay suppression
+
+**Files:**
+- Modify: `src/lib/ws-client.ts` (hello :343, ready handling in `handleIncomingMessage` :148, replay :195-205)
+- Test: Create `test/unit/lib/ws-client.reconcile.test.ts`
+
+**Interfaces:**
+- Consumes: `getWsClient()` (:643), `resetWsClientForTests()` (:652), `receiveMessageForTest` (:631) — the existing test seams.
+- Produces: hello carries `paneReconcileV1: true`; `getWsClient().getServerCapabilities(): {paneReconcileV1?: true}` (empty object until a ready with capabilities arrives; RESET on disconnect so a downgraded server is honored); when `paneReconcileV1` was acked on the CURRENT socket's ready, the blind `inFlightCreates` replay is skipped (verdicts, not resends, decide — `preReadyCreateQueue` flush is unchanged: those are new user-initiated creates).
+
+- [ ] **Step 1: Write the failing tests** (drive with `resetWsClientForTests` + `receiveMessageForTest`; mock the WebSocket the way existing ws-client tests do — `rg -l "resetWsClientForTests" test/` and copy the newest pattern):
+
+```ts
+it('hello advertises paneReconcileV1', () => {
+  const sent = captureHello()  // helper: mock ws, trigger onopen, parse first frame
+  expect(sent.capabilities).toMatchObject({ uiScreenshotV1: true, terminalOutputBatchV1: true, paneReconcileV1: true })
+})
+it('surfaces ready.capabilities and resets them on disconnect', () => {
+  const client = getWsClient()
+  receiveReady({ capabilities: { paneReconcileV1: true } })
+  expect(client.getServerCapabilities().paneReconcileV1).toBe(true)
+  simulateDisconnect()
+  expect(client.getServerCapabilities().paneReconcileV1).toBeUndefined()
+})
+it('suppresses the in-flight create replay when the capability is acked', () => {
+  seedInFlightCreate('cr-1')
+  const frames = reconnectAndCollectFrames({ capabilities: { paneReconcileV1: true } })
+  expect(frames.filter(f => f.type === 'terminal.create')).toHaveLength(0)
+})
+it('keeps the legacy replay when the server does not ack (old server)', () => {
+  seedInFlightCreate('cr-1')
+  const frames = reconnectAndCollectFrames({ /* no capabilities */ })
+  expect(frames.filter(f => f.type === 'terminal.create')).toHaveLength(1)
+})
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+npm run test:vitest -- run test/unit/lib/ws-client.reconcile.test.ts
+```
+Expected: FAIL.
+
+- [ ] **Step 3: Implement**
+  - `:343`: `capabilities: { uiScreenshotV1: true, terminalOutputBatchV1: true, paneReconcileV1: true },`
+  - In the `ready` branch of `handleIncomingMessage`: `this.serverCapabilities = msg.capabilities ?? {}` BEFORE the replay block; clear it in the disconnect path (`onDisconnect`/`scheduleReconnect` entry).
+  - Wrap the `inFlightCreates` replay (:195-205): `if (!this.serverCapabilities.paneReconcileV1) { /* existing replay */ }`.
+  - Add `getServerCapabilities()` accessor.
+
+- [ ] **Step 4: Run tests** (new + any existing ws-client/bootstrap suites)
+
+```bash
+npm run test:vitest -- run test/unit/lib/ws-client.reconcile.test.ts test/unit/App.ws-bootstrap.test.tsx
+```
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/lib/ws-client.ts test/unit/lib/ws-client.reconcile.test.ts
+git commit -m "feat(client): advertise paneReconcileV1, surface ready capabilities, gate blind create replay"
+```
+
+---
+
+### Task 11: Client — App wiring: send request on ready, fold results, gate the legacy census; terminal-restore bypass
+
+**Files:**
+- Modify: `src/App.tsx` (ReadyMessageSchema :149; inventory census block :1018-1091)
+- Modify: `src/lib/terminal-restore.ts`
+- Test: Create `test/unit/App.reconcile-adoption.test.tsx`; Modify `test/unit/lib/terminal-restore.test.ts`
+
+**Interfaces:**
+- Consumes: Task 9 `buildReconcileRequest`/`foldVerdicts`, Task 10 capabilities, Task 8 actions.
+- Produces: on every `ready` whose `capabilities.paneReconcileV1 === true`: `setPaneReconcileActive(true)` + build & send `pane.reconcile.request` + register the one-shot result fold (matched on `reconcileId`); the destructive census (`clearDeadTerminals` + restore-arming walk) runs ONLY when the capability is absent (`setLiveTerminalIds` + `setServerRestarted(false)` stay unconditional); cardinality violation → `console.error` + run the legacy census once for THIS inventory cycle (fail-safe); `terminal-restore.ts` exports `setPaneReconcileActive(v: boolean)` and, when active, `consumeTerminalRestoreRequestId` / `consumeTerminalFreshRecoveryRequest` report not-armed.
+
+- [ ] **Step 1: Write the failing tests.** App-level: copy the store/ws mocking scaffold from `test/unit/App.ws-bootstrap.test.tsx` (it already boots App against a scripted ws).
+
+```ts
+it('sends pane.reconcile.request after ready-with-capability and does NOT run the census', async () => {
+  seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+  const { sentFrames, dispatched } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+  await receiveInventory({ liveTerminalIds: [] })
+  expect(sentFrames.some(f => f.type === 'pane.reconcile.request')).toBe(true)
+  expect(dispatched.types).not.toContain(clearDeadTerminals.type)
+  expect(dispatched.types).toContain(setLiveTerminalIds.type) // non-destructive part stays
+})
+it('runs the legacy census when the server does not ack the capability', async () => {
+  seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+  const { sentFrames, dispatched } = await bootAppWithReady({ /* no capabilities */ })
+  await receiveInventory({ liveTerminalIds: [] })
+  expect(sentFrames.some(f => f.type === 'pane.reconcile.request')).toBe(false)
+  expect(dispatched.types).toContain(clearDeadTerminals.type)
+})
+it('folds a matching pane.reconcile.result', async () => {
+  seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+  const { sentFrames, dispatched } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+  const req = sentFrames.find(f => f.type === 'pane.reconcile.request')!
+  await receiveServerFrame(attachResultFor(req, 'term-77'))
+  expect(dispatched.types).toContain(applyReconcileAttach.type)
+})
+it('cardinality violation falls back to the census, loudly', async () => {
+  seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+  const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+  const { sentFrames, dispatched } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+  const req = sentFrames.find(f => f.type === 'pane.reconcile.request')!
+  await receiveServerFrame({ type: 'pane.reconcile.result', reconcileId: req.reconcileId, bootId: 'b', serverInstanceId: 's', verdicts: [] })
+  await receiveInventory({ liveTerminalIds: [] })
+  expect(errSpy).toHaveBeenCalled()
+  expect(dispatched.types).toContain(clearDeadTerminals.type)
+})
+```
+`terminal-restore.test.ts` additions: after `setPaneReconcileActive(true)`, `addTerminalRestoreRequestId('cr-x')` then `consumeTerminalRestoreRequestId('cr-x')` → falsy; after `setPaneReconcileActive(false)` the latch behaves as before.
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+npm run test:vitest -- run test/unit/App.reconcile-adoption.test.tsx test/unit/lib/terminal-restore.test.ts
+```
+Expected: FAIL.
+
+- [ ] **Step 3: Implement**
+  - `App.tsx` ready handler: extend the local `ReadyMessageSchema` (:149) with the optional capabilities object; then:
+
+```ts
+const paneReconcile = ready.capabilities?.paneReconcileV1 === true
+paneReconcileActiveRef.current = paneReconcile
+setPaneReconcileActive(paneReconcile)
+if (paneReconcile) {
+  const req = buildReconcileRequest(store.getState())
+  if (req) {
+    pendingReconcileRef.current = req
+    getWsClient().send(req)
+  }
+}
+```
+  - Message handler: on `pane.reconcile.result` with `reconcileId === pendingReconcileRef.current?.reconcileId` → `const outcome = foldVerdicts(dispatch, pendingReconcileRef.current, msg)`; clear the ref; if `outcome.cardinalityViolation` → `console.error('[reconcile] cardinality violation — falling back to legacy census')` + `paneReconcileActiveRef.current = false` + `setPaneReconcileActive(false)` (re-set true on the next ready).
+  - Census block (:1018-1091): wrap ONLY the destructive part (`clearDeadTerminals` dispatch + the `addTerminalRestoreRequestId`/`addTerminalFreshRecoveryRequestId` walk) in `if (!paneReconcileActiveRef.current) { ... }`.
+  - `terminal-restore.ts`:
+
+```ts
+let paneReconcileActive = false
+export function setPaneReconcileActive(v: boolean): void { paneReconcileActive = v }
+// first line of consumeTerminalRestoreRequestId and consumeTerminalFreshRecoveryRequest:
+if (paneReconcileActive) return undefined  // (or false — match each fn's return type)
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npm run test:vitest -- run test/unit/App.reconcile-adoption.test.tsx test/unit/lib/terminal-restore.test.ts test/unit/App.ws-bootstrap.test.tsx test/unit/App.restart-signals.test.tsx
+```
+Expected: PASS (existing App suites prove the legacy path is intact).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/App.tsx src/lib/terminal-restore.ts test/unit/App.reconcile-adoption.test.tsx test/unit/lib/terminal-restore.test.ts
+git commit -m "feat(client): reconcile on ready-with-capability; census becomes the capability-gated fallback (F3/F4)"
+```
+
+---
+
+### Task 12: Client — TerminalView: verdict-driven create, SESSION_RESERVED + INVALID_TERMINAL_ID bounded retry, exhaustion auto-resolve
+
+**Files:**
+- Modify: `src/components/TerminalView.tsx` (create send site :2789-2825; error-frame handling — locate with `rg -n "INVALID_TERMINAL_ID" src/`)
+- Test: Create `test/unit/components/TerminalView.session-reserved.test.tsx`
+
+**Interfaces:**
+- Consumes: `pendingReconcile`/`reconcileNotice` (Task 7/8), `getCreateSessionStateFromRef` (`src/components/terminal-view-utils.ts:9`), `buildReconcileRequestForPanes` + `foldVerdicts` (Task 9), `writeLocalXtermNotice` (:909), server error frames `{code: 'SESSION_RESERVED', requestId, retryAfterMs}` (Task 6).
+- Produces:
+  - Create args: when `pendingReconcile === 'respawn'` → resume args come from `content.sessionRef` (the server-named ref — precedence over any other inference) with `restore: true`; when `'fresh'` → no resume fields; field cleared when `terminal.created` arrives.
+  - `RESERVE_RETRY_WINDOW_MS = 30_000` (> lease TTL 20s + margin, council rule) and `RESERVE_RETRY_FLOOR_MS = 250`: on `SESSION_RESERVED` matching this pane's `createRequestId`, re-send the same `terminal.create` after `max(retryAfterMs, floor)`, until the window is spent.
+  - Exhaustion auto-resolve: after the window, send `buildReconcileRequestForPanes(state, [thisPane])` and fold the single verdict — binding exists → attach silently; winner failed → dead_session/fresh flow with visible notice. Never a permanent error, never a dead button. (This is the client half of `loser-exhausts-then-holder-fails`.)
+  - F9: launch-time `INVALID_TERMINAL_ID` for this pane → bounded retry (5 attempts, 500ms apart) through the same re-drive helper before surfacing `status:'error'`.
+  - `reconcileNotice` rendered once via `writeLocalXtermNotice` after attach, then `clearPaneReconcileNotice`.
+
+- [ ] **Step 1: Write the failing tests** (fake timers; mock ws-client send; copy mounting scaffold from `test/unit/components/TerminalView.restore-flag-persistence.test.tsx`):
+
+```ts
+it('respawn create uses the server-named sessionRef with restore:true', () => {
+  mountPane({ pendingReconcile: 'respawn', sessionRef: { provider: 'claude', sessionId: 'server-truth' }, status: 'creating', createRequestId: 'cr-1' })
+  const create = lastSentOfType('terminal.create')
+  expect(create.restore).toBe(true)
+  expect(resumeIdentityOf(create)).toMatchObject({ provider: 'claude', sessionId: 'server-truth' })
+})
+it('SESSION_RESERVED re-drives the same create after retryAfterMs, same createRequestId', async () => {
+  mountPane({ pendingReconcile: 'respawn', status: 'creating', createRequestId: 'cr-1' })
+  receiveError({ code: 'SESSION_RESERVED', requestId: 'cr-1', retryAfterMs: 1000 })
+  expect(countSentOfType('terminal.create')).toBe(1)
+  await vi.advanceTimersByTimeAsync(1000)
+  expect(countSentOfType('terminal.create')).toBe(2)
+  expect(lastSentOfType('terminal.create').requestId).toBe('cr-1') // never re-minted
+})
+/// loser-exhausts-then-holder-fails (council red test, client half):
+it('exhaustion auto-resolves via a single-pane reconcile — never a wedge', async () => {
+  mountPane({ pendingReconcile: 'respawn', status: 'creating', createRequestId: 'cr-1' })
+  // keep answering SESSION_RESERVED past the 30s window
+  autoRespondErrors({ code: 'SESSION_RESERVED', requestId: 'cr-1', retryAfterMs: 1000 })
+  await vi.advanceTimersByTimeAsync(31_000)
+  expect(lastSentOfType('pane.reconcile.request')).toBeTruthy()
+  // holder failed -> server answers dead_session; assert the fold ran and a notice is visible
+  receiveServerFrame(deadSessionResultForLastRequest())
+  expect(paneShowsRestoreErrorCard()).toBe(true)
+})
+it('INVALID_TERMINAL_ID at launch is retried bounded (F9), not a permanent error', async () => {
+  mountPane({ status: 'creating', createRequestId: 'cr-1', terminalId: 'term-stale' })
+  receiveError({ code: 'INVALID_TERMINAL_ID', terminalId: 'term-stale' })
+  await vi.advanceTimersByTimeAsync(500)
+  expect(countSentOfType('terminal.create')).toBeGreaterThanOrEqual(2)
+})
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+npm run test:vitest -- run test/unit/components/TerminalView.session-reserved.test.tsx
+```
+Expected: FAIL.
+
+- [ ] **Step 3: Implement.** One small internal helper owns both retries:
+
+```ts
+// Bounded re-drive: SESSION_RESERVED honors the server hint inside a 30s
+// window (> lease TTL + margin); INVALID_TERMINAL_ID gets 5 x 500ms.
+// On exhaustion: single-pane reconcile -> fold (auto-resolve, council rule 8).
+```
+At the create site, resume-arg precedence: `pendingReconcile === 'respawn'` → `getCreateSessionStateFromRef(content.sessionRef)` result wins; `'fresh'` → omit resume fields entirely. Clear `pendingReconcile` on `terminal.created`. After attach, if `content.reconcileNotice` → `writeLocalXtermNotice(term, content.reconcileNotice)` + dispatch `clearPaneReconcileNotice`.
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npm run test:vitest -- run test/unit/components/TerminalView.session-reserved.test.tsx test/unit/components/TerminalView.restore-flag-persistence.test.tsx
+```
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/components/TerminalView.tsx test/unit/components/TerminalView.session-reserved.test.tsx
+git commit -m "feat(client): verdict-driven create args; bounded SESSION_RESERVED/INVALID_TERMINAL_ID re-drive with auto-resolve exhaustion"
+```
+
+---
+
+### Task 13: Client — DeadSessionPanel (ONE batched panel) + warming banner (ONE banner)
+
+**Files:**
+- Create: `src/components/DeadSessionPanel.tsx`
+- Create: `src/components/ReconcileWarmingBanner.tsx`
+- Modify: `src/App.tsx` (render both near the existing modal/banner region)
+- Test: Create `test/unit/components/DeadSessionPanel.test.tsx` (covers both components)
+
+**Interfaces:**
+- Consumes: `deadSessionAdjudication` / `reconcileWarming` state + `resolveDeadSessionEntry` / `clearDeadSessionAdjudication` / `clearReconcileWarming` / `resetPaneForReconcileCreate` (Task 8); pane-close action (locate the existing close-pane dispatch: `rg -n "closePane" src/store/panesSlice.ts`); `buildReconcileRequestForPanes` (Task 9).
+- Produces: `DeadSessionPanel` — a single `role="dialog"` (aria-label "Dead sessions") listing ALL entries with per-row semantic `<button>`s **Start fresh here** (dispatch `resetPaneForReconcileCreate({intent:'fresh'})` — same `createRequestId`, I7) and **Close pane**, plus **Dismiss** (keeps per-pane restoreError cards; nothing auto-closed). `ReconcileWarmingBanner` — one `role="status"` banner: `Waiting for session index — N pane(s)` + **Retry now** button that re-sends a reconcile request for exactly the warming panes. A11y rules from AGENTS.md apply (semantic buttons, aria-labels, no div-onClick).
+
+- [ ] **Step 1: Write the failing tests**
+
+```ts
+/// F11-human: one panel, never N modals.
+it('renders ONE dialog listing all dead panes', () => {
+  renderWithStore({ deadSessionAdjudication: [entry('p1'), entry('p2'), entry('p3')] })
+  expect(screen.getAllByRole('dialog')).toHaveLength(1)
+  expect(screen.getAllByRole('button', { name: /start fresh here/i })).toHaveLength(3)
+})
+it('Start fresh dispatches a fresh reset preserving createRequestId and removes the row', async () => {
+  const { store } = renderWithStore({ deadSessionAdjudication: [entry('p1')] })
+  await userEvent.click(screen.getByRole('button', { name: /start fresh here/i }))
+  expect(dispatchedTypes(store)).toContain(resetPaneForReconcileCreate.type)
+  expect(store.getState().panes.deadSessionAdjudication).toHaveLength(0)
+})
+it('renders nothing when the list is empty', () => {
+  renderWithStore({ deadSessionAdjudication: [] })
+  expect(screen.queryByRole('dialog')).toBeNull()
+})
+/// restart-storm-all-panes-warming (council red test, client half):
+it('N warming panes produce exactly ONE banner with the count', () => {
+  renderWithStore({ reconcileWarming: { count: 7, paneRefs: sevenRefs() } })
+  expect(screen.getAllByRole('status')).toHaveLength(1)
+  expect(screen.getByRole('status')).toHaveTextContent(/waiting for session index/i)
+  expect(screen.getByRole('status')).toHaveTextContent(/7/)
+})
+it('Retry now re-sends a reconcile request for exactly the warming panes', async () => {
+  renderWithStore({ reconcileWarming: { count: 2, paneRefs: [ref('p1'), ref('p2')] } })
+  await userEvent.click(screen.getByRole('button', { name: /retry now/i }))
+  const req = lastSentOfType('pane.reconcile.request')
+  expect(req.panes).toHaveLength(2)
+})
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+npm run test:vitest -- run test/unit/components/DeadSessionPanel.test.tsx
+```
+Expected: FAIL.
+
+- [ ] **Step 3: Implement** both components per the Produces block (shadcn/ui dialog + Tailwind, matching neighboring components' style) and mount them in `App.tsx` beside the existing modal region (`rg -n "AuthRequiredModal" src/App.tsx` — render adjacent).
+
+- [ ] **Step 4: Run tests + lint (a11y is CI-gated)**
+
+```bash
+npm run test:vitest -- run test/unit/components/DeadSessionPanel.test.tsx
+npm run lint
+```
+Expected: PASS, no new a11y violations.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/components/DeadSessionPanel.tsx src/components/ReconcileWarmingBanner.tsx src/App.tsx test/unit/components/DeadSessionPanel.test.tsx
+git commit -m "feat(client): batched dead-session adjudication panel + single warming banner with manual retry"
+```
+
+---
+
+### Task 14: E2E — new adoption spec, flip the P1.7 pin, update the double-restart guard
+
+**Files:**
+- Create: `test/e2e-browser/specs/reconcile-client-adoption-rust.spec.ts`
+- Modify: `test/e2e-browser/specs/restore-contract-wall-rust.spec.ts` (:1877-1880 pin; :2042 guard)
+
+**Interfaces:**
+- Consumes: `RustServer` (`test/e2e-browser/helpers/rust-server.ts` — `start()`, `restart()`, `restartAbrupt()`, `stop()`, `info {port, baseUrl, wsUrl, token, homeDir}`); the wall spec's existing fixture-session + `browser.newContext()` patterns (read the wall spec's two-clients test at :1867-1961 and its fixture setup before writing anything).
+- Produces: e2e proof that verdicts drive recovery end-to-end with the real SPA; the flipped pin (an unexpected PASS of a `test.fail` is a hard suite failure, so the pin MUST be deleted in the same commit that makes it pass — this task, after Tasks 2-13 are merged into the branch).
+
+- [ ] **Step 1: Flip the pin.** Delete the `test.fail(e2eServerKind === 'rust', 'P1.7 (D8): ...')` line at `restore-contract-wall-rust.spec.ts:1877-1880` (delete the pin line only — never widen it). The test body (`expect(respawns.length).toBe(1)` at :1961) now must pass against the adopted client + leased server.
+
+- [ ] **Step 2: Update the double-restart guard** at :2042. It currently pins observed legacy behavior ("OBSERVE-THEN-PIN … paneReconcileV1 never sent"). Rewrite its expectation to the adopted reality: the client DOES send `pane.reconcile.request` after each ready, and after a double restart mid-reconcile the panes converge (each persisted pane ends with exactly one live terminal; assert via `/api/terminals` as the wall spec already does). Keep the test's name and scenario; change only the assertions that encoded the legacy observation.
+
+- [ ] **Step 3: Write the new spec** `reconcile-client-adoption-rust.spec.ts` with three scenarios (own `RustServer` per test group, real SPA pages via `page.goto(server.info.baseUrl + '/?token=' + server.info.token)` — copy the wall spec's boot helper):
+
+```ts
+test('restart with mixed pane types: verdicts drive recovery, census never destroys', async ({ browser }) => {
+  // 1. Boot SPA; create a shell pane and a fake-CLI pane with a fixture
+  //    session file in the server home (copy the wall spec's fixture helper).
+  // 2. server.restart()
+  // 3. Assert: shell pane comes back live (fresh/respawn per contract — it
+  //    renders a working terminal, no restoreError); CLI pane resumes with
+  //    the SAME sessionRef (assert resume args via /api/terminals);
+  //    pane count unchanged (nothing destroyed by census — F3 closed).
+})
+test('dead sessions surface as ONE batched adjudication panel', async ({ browser }) => {
+  // 1. Two fake-CLI panes with fixture session files; verify both live.
+  // 2. server.stop({ preserveHome }); delete both session files from the
+  //    server home; server.start() (same home).
+  // 3. Assert: exactly one [role=dialog] listing both panes; click
+  //    "Start fresh here" on the first -> that pane becomes a live terminal
+  //    (same createRequestId observable via /api/terminals row count for the
+  //    pane: exactly 1); second entry still listed; nothing auto-closed.
+})
+test('double-restart mid-reconcile converges with no duplicates', async ({ browser }) => {
+  // 1. Boot SPA with 2 CLI panes (fixture sessions).
+  // 2. server.restartAbrupt(); wait ~300ms into the reconcile window;
+  //    server.restartAbrupt() again.
+  // 3. Assert: within the recovery timeout every pane settles to a live
+  //    terminal or an explicit labeled state (no permanent 'creating' wedge),
+  //    and /api/terminals shows exactly one live PTY per createRequestId.
+})
+```
+These comments are the scenario contract; the bodies must be real Playwright code following the wall spec's helpers (settle-loops, `expect.poll` on `/api/terminals`). Robust additional experiments (e.g. killing one browser context mid-retry) are encouraged as extra tests, not replacements.
+
+- [ ] **Step 4: Run the touched e2e suites**
+
+```bash
+npx playwright test --config test/e2e-browser/playwright.config.ts --project=rust-chromium \
+  test/e2e-browser/specs/reconcile-client-adoption-rust.spec.ts
+npx playwright test --config test/e2e-browser/playwright.config.ts --project=rust-chromium \
+  test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
+```
+Expected: new spec PASS; wall spec PASS including the unpinned two-clients test (this is the headline red→green) and the rewritten double-restart guard. Iterate here until green — this task is the integration proof of the whole lane.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test/e2e-browser/specs/
+git commit -m "test(e2e): reconcile client adoption proofs; flip P1.7 D8 pin - two clients one sessionRef now yields exactly 1 PTY"
+```
+
+---
+
+### Task 15: Final verification, full suites, push (STOP before PR)
+
+**Files:** none new (fixes only if gates fail).
+
+**Interfaces:**
+- Consumes: everything above.
+- Produces: green full gates; pushed branch; red→green report. NO PR.
+
+- [ ] **Step 1: Rust gates**
+
+```bash
+cargo fmt --all --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
+```
+Expected: all PASS.
+
+- [ ] **Step 2: Coordinated JS suite** (waits politely on the shared gate; 3 sibling lanes run concurrently — WAIT, never kill a foreign holder)
+
+```bash
+FRESHELL_TEST_SUMMARY="B1 reconcile client adoption: full-suite gate before push" env -u NODE_ENV npm test
+```
+Expected: PASS (default + server configs).
+
+- [ ] **Step 3: E2E rust project** (at minimum the two touched specs; run the full rust project if time allows)
+
+```bash
+npx playwright test --config test/e2e-browser/playwright.config.ts --project=rust-chromium
+```
+Expected: PASS, including the formerly-pinned two-clients test.
+
+- [ ] **Step 4: Push the branch — and STOP**
+
+```bash
+git push -u origin HEAD
+```
+Do NOT run `gh pr create` (not approved). Report: branch name, commit list, and the red→green proof for each named council red test (`warming-never-completes`, `restart-storm-all-panes-warming`, `two-clients-same-sessionRef`, `winner-dies-mid-claim`, `winner-hangs-mid-claim`, `loser-exhausts-then-holder-fails`) plus the flipped P1.7 pin.
+
+---
+
+## Self-Review Notes (spec coverage map)
+
+| Spec requirement | Covering task(s) |
+|---|---|
+| Client sends `capabilities.paneReconcileV1` | 10 |
+| Reconcile request on reconnect/restart with persisted panes | 9, 11 |
+| attach → plain attach, no recreate, no new createRequestId | 8, 9 (tests pin it) |
+| respawn → create-with-resume from server-named sessionRef | 8, 9, 12 |
+| fresh → clean create | 8, 9 |
+| dead_session → loud breadcrumb + ONE batched panel (F11-human) | 9, 13, 14 |
+| corrected:true → user-visible notice, never silent | 8 (notice), 12 (render), 4 (server emit) |
+| Legacy census as capability-gated fallback, not deleted | 11, 14 (guard rewrite proves old-server path) |
+| retry verdict DELETED from wire | 2 |
+| Bounded warming deferral (2s, single) then loud error{INDEX_WARMING} + manual retry | 2 (server), 13 (retry affordance) |
+| PROVIDER_UNAVAILABLE for known provider w/o home | 3 |
+| Warming storm → ONE banner | 13 (`restart-storm-all-panes-warming`) |
+| Red test warming-never-completes | 2 |
+| SessionRef-level single-flight; winner binds registry + ledger; others attach | 4, 5, 6 |
+| Liveness-bound lease, TTL kill-before-release, hold-closed on unconfirmed kill | 5, 6 |
+| Losers: SESSION_RESERVED + retryAfterMs; client window > TTL + margin | 6, 12 |
+| Exhaustion auto-resolves (attach silently / dead-fresh with notice) | 12 (`loser-exhausts-then-holder-fails`) |
+| ≥2-live-PTYs-per-sessionRef alarm | 4 |
+| Red tests two-clients-same-sessionRef / winner-dies / winner-hangs | 6, 5, 5 (+ e2e 14) |
+| F9 INVALID_TERMINAL_ID bounded retry (council: ships in this slice) | 12 |
+| Flip P1.7 pins | 14 |
+| E2E: mixed restart / two contexts one sessionRef / dead-session panel / double restart | 14 (two-contexts = the unpinned wall test) |
+| B4 conflict kept tight (reconcile.rs dispatch arm untouched) | 2, 3, 4 (explicit non-goals) |
+
+No unresolved coverage gaps.

From c8a2d93e2cf4787b6b9d21690e0ab0bf59136427 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 02:27:13 -0700
Subject: [PATCH 02/87] docs: add implementation plan for
 freshagent-verdicts-resume
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lane B4: fresh-agent panes into the reconcile verdict system (server side),
resume-invocation record in the pane-identity ledger, settings-from-ledger
resume for codex/opencode/claude, and the codex crash-respawn degradation
frame. 15 TDD tasks, capability-gated behind paneReconcileFreshAgentV1.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../2026-07-26-freshagent-verdicts-resume.md  | 1955 +++++++++++++++++
 1 file changed, 1955 insertions(+)
 create mode 100644 docs/plans/2026-07-26-freshagent-verdicts-resume.md

diff --git a/docs/plans/2026-07-26-freshagent-verdicts-resume.md b/docs/plans/2026-07-26-freshagent-verdicts-resume.md
new file mode 100644
index 000000000..c7edff1e1
--- /dev/null
+++ b/docs/plans/2026-07-26-freshagent-verdicts-resume.md
@@ -0,0 +1,1955 @@
+# Fresh-Agent Verdicts + Settings-From-Ledger Resume (Lane B4) Implementation Plan
+
+> **For agentic workers:** This plan is executed task-by-task by the
+> workflow's execute stage: a fresh implementer per task, with a spec +
+> quality review after each task. Steps use checkbox (`- [ ]`) syntax
+> for tracking.
+
+**Goal:** Bring fresh-agent panes (freshcodex / freshopencode / freshclaude / kilroy) into the server-side pane-reconcile verdict system, persist a resume-invocation record (model, sandbox, permissionMode, effort, cwd) in the pane-identity ledger at every fresh-agent identity event, reapply those settings automatically on every resume path, and broadcast a user-visible degradation frame when codex crash-respawn discards conversation memory.
+
+**Architecture:** A `PaneIdentitySink` trait defined in `freshell-freshagent` (which cannot depend on `freshell-ws`) is implemented in `freshell-server` over the existing `Arc<PaneLedger>` and injected into the three provider states at wiring time — this solves the wave-A crate-boundary deferral without hoisting the ledger module. `BindingRow` gains optional resume-settings fields under `LEDGER_VERSION 1` (no version bump). Reconcile gains a new sync-safe module `reconcile_freshagent.rs`: an async snapshot of fresh-agent liveness/existence is built in `handle_pane_reconcile` (which is async) *before* the sync `derive_verdicts` runs inside `catch_unwind`; the only `reconcile.rs` changes are one `ReconcileDeps` field, one match arm, and inverting one unit test. The new arm is gated behind a NEW hello capability `paneReconcileFreshAgentV1` so the frozen client (which never sends it) is completely unaffected.
+
+**Tech Stack:** Rust (tokio, serde, axum WS), Playwright e2e (rust-chromium project), fake CLI/sidecar fixtures (Node).
+
+## Global Constraints
+
+- Base: `origin/main @ 2dfbba58`; all work in worktree `/home/dan/code/freshell/.worktrees/freshagent-verdicts-resume`.
+- CI Rust gate (must stay green after every task): `cargo fmt --all --check` and `cargo clippy --workspace --all-targets -- -D warnings`.
+- Rust tests: `cargo test -p <crate>` locally (no cargo test in CI, run anyway).
+- Coordinated node suites: check `npm run test:status` first; run `FRESHELL_TEST_SUMMARY="B4 freshagent-verdicts-resume" env -u FRESHELL_BIND_HOST npm test`; if the coordinator gate is held by another agent, WAIT (3 sibling lanes run concurrently — never kill a foreign holder).
+- E2E: own `RustServer` instances on ephemeral ports only. NEVER ports 3001/3002. NEVER touch the user's self-hosted server. No broad kill patterns.
+- SCOPE FENCE — do NOT touch: the rest of `crates/freshell-ws/src/reconcile.rs` beyond the single dispatch arm + one `ReconcileDeps` field + inverting the `unsupported_kind` unit test (Lane B1 owns the rest, incl. retry-verdict deletion — a trivial merge conflict at the arm is expected and fine); `crates/freshell-ws/src/existence.rs` (B1; read-only use is fine); codex_candidate/rollout locator (B2); tabs_snapshots + recovery UI (B3); ALL client code (`src/`, ws-client, App.tsx) — client folding of fresh-agent verdicts is the NEXT wave. No kimi/gemini work.
+- `LEDGER_VERSION` stays `1`. All new `BindingRow` fields are `Option` with `skip_serializing_if` — no `deny_unknown_fields`, no required non-defaulted fields.
+- Ledger writes are sync + fsync: async call sites MUST wrap them in `tokio::task::spawn_blocking` (module doc `pane_ledger.rs:34-43`).
+- TypeScript (e2e specs): NodeNext/ESM — relative imports include `.js` where the repo convention requires (spec files follow the sibling specs' import style).
+- Alarm/degradation frames use `freshAgent.error` event codes that are NOT `INVALID_SESSION_ID` and do NOT start with `RESTORE_` (that combination renders the persistent amber `role="alert"` banner in today's frozen client, `src/lib/fresh-agent-ws.ts:307-318` → `FreshAgentView.tsx:2046`).
+- PR POLICY: NOT approved. Push the branch, STOP before `gh pr create`.
+- ~78GB disk free — halt on ENOSPC.
+- Reference (read-only context, do not commit): campaign plan at `/home/dan/code/freshell/docs/plans/2026-07-24-restart-resilience-architecture-analysis.md` (untracked, absolute path).
+
+---
+
+## File Structure
+
+| File | Change | Responsibility |
+|---|---|---|
+| `crates/freshell-ws/src/pane_ledger.rs` | Modify | `BindingRow` optional resume-settings fields; `FreshAgentBindingWrite` + `record_fresh_agent_binding` upsert |
+| `crates/freshell-freshagent/src/identity_sink.rs` | Create | `PaneIdentitySink` trait, `FreshAgentSettings`, `FreshAgentBindingUpsert`, `FakeIdentitySink` (cfg(test)) |
+| `crates/freshell-freshagent/src/lib.rs` | Modify | `pub mod identity_sink;` + re-exports |
+| `crates/freshell-freshagent/src/codex.rs` | Modify | sink field/setter; ledger writes at identity events; settings-from-ledger on R1/R2/R3; degradation frame |
+| `crates/freshell-freshagent/src/opencode_ws.rs` | Modify | sink field/setter; pending + binding writes; settings-from-ledger resume |
+| `crates/freshell-freshagent/src/claude.rs` | Modify | sink field/setter; binding write at `sdk.session.init`; settings-from-ledger resume |
+| `crates/freshell-server/src/identity_sink.rs` | Create | `LedgerIdentitySink: PaneIdentitySink` over `Arc<PaneLedger>` |
+| `crates/freshell-server/src/main.rs` | Modify | construct + inject the sink into the three states |
+| `crates/freshell-ws/src/reconcile_freshagent.rs` | Create | snapshot types, async snapshot builder, pure verdict mapping, respawn cap, dedupe |
+| `crates/freshell-ws/src/reconcile.rs` | Modify (minimal) | one `ReconcileDeps` field + one match arm + invert one unit test |
+| `crates/freshell-ws/src/lib.rs` | Modify | `mod reconcile_freshagent;`, `paneReconcileFreshAgentV1` capability parse/echo, `WsState.fresh_agent_respawn_counts` |
+| `crates/freshell-ws/src/terminal.rs` | Modify | thread capability bool; build fresh-agent snapshot in `handle_pane_reconcile` |
+| `crates/freshell-ws/tests/pane_reconcile_freshagent.rs` | Create | direct-WS integration tests for the fresh-agent arm |
+| `test/e2e-browser/fixtures/coding-cli/…/fake-app-server.mjs` (`test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs`) | Modify | crash-on-marker behavior knob |
+| `test/e2e-browser/specs/freshagent-settings-resume-rust.spec.ts` | Create | per-provider settings-survive-restart + codex degradation banner |
+| `test/e2e-browser/playwright.config.ts` | Modify | register new spec in `RUST_ONLY_SPECS` + `rust-chromium` `testMatch` |
+| `test/e2e-browser/specs/restore-contract-wall-rust.spec.ts` | Modify | flip/narrow the P1.13 freshopencode pin |
+
+---
+
+### Task 1: Ledger schema — resume-invocation record fields + fresh-agent upsert
+
+**Files:**
+- Modify: `crates/freshell-ws/src/pane_ledger.rs`
+- Test: inline `#[cfg(test)] mod` in the same file (follow the existing test module, e.g. `record_binding_roundtrips_all_fields`)
+
+**Interfaces:**
+- Consumes: existing `BindingRow`, `RowState`, `PaneLedger` internals (`record_binding` at `pane_ledger.rs:315` is the structural donor).
+- Produces (later tasks rely on these EXACT names):
+  - `BindingRow` new pub fields: `pane_kind: Option<String>`, `model: Option<String>`, `sandbox: Option<String>`, `permission_mode: Option<String>`, `effort: Option<String>` (serde camelCase: `paneKind`, `model`, `sandbox`, `permissionMode`, `effort`).
+  - `pub struct FreshAgentBindingWrite<'a>` (fields below).
+  - `pub fn PaneLedger::record_fresh_agent_binding(&self, w: &FreshAgentBindingWrite<'_>) -> std::io::Result<()>`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to the existing `#[cfg(test)]` module in `pane_ledger.rs` (reuse the module's existing temp-root helper — the same one `record_binding_roundtrips_all_fields` uses):
+
+```rust
+#[test]
+fn fresh_agent_binding_roundtrips_settings_and_pane_kind() {
+    let (ledger, _tmp) = test_ledger(); // the module's existing temp-root constructor helper
+    ledger
+        .record_fresh_agent_binding(&FreshAgentBindingWrite {
+            provider: "codex",
+            session_id: "thread-1",
+            mode: "freshcodex",
+            cwd: Some("/home/u/proj"),
+            create_request_id: Some("req-1"),
+            model: Some("gpt-5.3-codex"),
+            sandbox: Some("workspace-write"),
+            permission_mode: Some("on-request"),
+            effort: Some("high"),
+            now_ms: 1_000,
+        })
+        .unwrap();
+    let row = ledger.load_binding("codex", "thread-1").expect("row");
+    assert_eq!(row.pane_kind.as_deref(), Some("fresh-agent"));
+    assert_eq!(row.model.as_deref(), Some("gpt-5.3-codex"));
+    assert_eq!(row.sandbox.as_deref(), Some("workspace-write"));
+    assert_eq!(row.permission_mode.as_deref(), Some("on-request"));
+    assert_eq!(row.effort.as_deref(), Some("high"));
+    assert_eq!(row.cwd.as_deref(), Some("/home/u/proj"));
+    assert_eq!(row.created_at, 1_000);
+}
+
+#[test]
+fn fresh_agent_binding_upsert_preserves_created_at_and_refreshes_settings() {
+    let (ledger, _tmp) = test_ledger();
+    let base = FreshAgentBindingWrite {
+        provider: "opencode",
+        session_id: "ses_abc",
+        mode: "freshopencode",
+        cwd: Some("/w"),
+        create_request_id: None,
+        model: Some("m1"),
+        sandbox: None,
+        permission_mode: None,
+        effort: Some("low"),
+        now_ms: 1_000,
+    };
+    ledger.record_fresh_agent_binding(&base).unwrap();
+    ledger
+        .record_fresh_agent_binding(&FreshAgentBindingWrite { model: Some("m2"), effort: None, now_ms: 2_000, ..base })
+        .unwrap();
+    let row = ledger.load_binding("opencode", "ses_abc").expect("row");
+    assert_eq!(row.created_at, 1_000, "upsert must preserve created_at");
+    assert_eq!(row.updated_at, 2_000);
+    assert_eq!(row.model.as_deref(), Some("m2"));
+    assert_eq!(row.effort, None, "settings are a full snapshot, not a merge");
+}
+
+#[test]
+fn old_terminal_rows_without_settings_fields_still_deserialize() {
+    // A wave-A row serialized before this change has none of the new fields.
+    let json = r#"{"ledgerVersion":1,"provider":"claude","sessionId":"s1","mode":"claude",
+        "createdAt":1,"updatedAt":1,"lastObservedAt":1,"state":"bound"}"#;
+    let row: BindingRow = serde_json::from_str(json).expect("old row must parse");
+    assert_eq!(row.pane_kind, None);
+    assert_eq!(row.model, None);
+}
+```
+
+Note: for `FreshAgentBindingWrite` to support `..base` struct update, derive `Clone` and `Copy` is impossible (`&str` refs are Copy — `#[derive(Clone, Copy)]` works since all fields are `&str`/`Option<&str>`/`i64`). Derive `Debug, Clone, Copy`.
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test -p freshell-ws fresh_agent_binding`
+Expected: COMPILE ERROR (`FreshAgentBindingWrite` and `record_fresh_agent_binding` not defined; `pane_kind` no field). A compile failure is the RED state for new-API tests.
+
+- [ ] **Step 3: Implement**
+
+(a) Append to `BindingRow` (after `superseded_by`), matching the existing serde style:
+
+```rust
+    /// "fresh-agent" for fresh-agent rows (P1.13); absent on terminal rows.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pane_kind: Option<String>,
+    /// Resume-invocation record (campaign plan §4.2): exactly what the
+    /// provider-native resume command needs. Updated when the user changes
+    /// them. All optional under LEDGER_VERSION 1 — no version bump.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sandbox: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub permission_mode: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub effort: Option<String>,
+```
+
+Fix every `BindingRow { … }` literal the compiler now flags (inside `record_binding`, `resolve_pending`, tests, etc.) by adding `pane_kind: None, model: None, sandbox: None, permission_mode: None, effort: None`.
+
+(b) Add next to `BindingWrite`:
+
+```rust
+/// One fresh-agent identity event's worth of binding-row input (P1.13).
+/// Settings are a FULL snapshot: callers always know the current values,
+/// so writes replace rather than merge.
+#[derive(Debug, Clone, Copy)]
+pub struct FreshAgentBindingWrite<'a> {
+    pub provider: &'a str,
+    pub session_id: &'a str,
+    pub mode: &'a str,
+    pub cwd: Option<&'a str>,
+    pub create_request_id: Option<&'a str>,
+    pub model: Option<&'a str>,
+    pub sandbox: Option<&'a str>,
+    pub permission_mode: Option<&'a str>,
+    pub effort: Option<&'a str>,
+    pub now_ms: i64,
+}
+```
+
+(c) Implement `record_fresh_agent_binding` by duplicating the structure of `record_binding` (`pane_ledger.rs:315`) — same disabled-root no-op, same in-memory index update, same atomic temp+rename+fsync persist path via the module's existing private row-persist helper — with these differences:
+- Upsert keyed `(provider, session_id)`: if a row exists, keep its `created_at`; otherwise `created_at = w.now_ms`.
+- Always set: `state: RowState::Bound`, `retired_reason: None`, `pane_kind: Some("fresh-agent".into())`, `updated_at = w.now_ms`, `last_observed_at = w.now_ms`, `live_terminal_id: None` (fresh-agent panes have no terminal), full settings snapshot from `w` (`model/sandbox/permission_mode/effort/cwd`), `create_request_id` from `w` (preserve the existing row's value when `w.create_request_id` is `None`), `superseded_by: None`.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-ws pane_ledger`
+Expected: PASS (all three new tests plus every pre-existing pane_ledger test).
+
+- [ ] **Step 5: Quality gate + commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-ws/src/pane_ledger.rs
+git commit -m "feat(ledger): resume-invocation record fields + fresh-agent binding upsert (P1.13)"
+```
+
+---
+
+### Task 2: `PaneIdentitySink` trait in freshell-freshagent + state wiring points
+
+**Files:**
+- Create: `crates/freshell-freshagent/src/identity_sink.rs`
+- Modify: `crates/freshell-freshagent/src/lib.rs` (module decl + re-export)
+- Modify: `crates/freshell-freshagent/src/codex.rs`, `crates/freshell-freshagent/src/opencode_ws.rs`, `crates/freshell-freshagent/src/claude.rs` (field + setter only in this task)
+- Test: `#[cfg(test)]` in `identity_sink.rs`
+
+**Interfaces:**
+- Consumes: nothing repo-specific (leaf abstraction; `freshell-freshagent` must NOT gain a dependency on `freshell-ws`).
+- Produces (exact, used by Tasks 3-10):
+
+```rust
+pub struct FreshAgentSettings {
+    pub model: Option<String>,
+    pub sandbox: Option<String>,
+    pub permission_mode: Option<String>,
+    pub effort: Option<String>,
+    pub cwd: Option<String>,
+}
+pub struct FreshAgentBindingUpsert {
+    pub provider: String,
+    pub session_id: String,
+    pub mode: String,
+    pub create_request_id: Option<String>,
+    pub resolves_pending: Option<String>,
+    pub settings: FreshAgentSettings,
+}
+pub trait PaneIdentitySink: Send + Sync {
+    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>);
+    fn record_binding(&self, upsert: FreshAgentBindingUpsert);
+    fn load_settings(&self, provider: &str, session_id: &str) -> Option<FreshAgentSettings>;
+}
+```
+- Produces on each of `FreshCodexState`, `FreshOpencodeState`, `FreshClaudeState`:
+  - `pub fn set_identity_sink(&self, sink: std::sync::Arc<dyn PaneIdentitySink>)`
+  - private `fn identity_sink(&self) -> Option<std::sync::Arc<dyn PaneIdentitySink>>`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `crates/freshell-freshagent/src/identity_sink.rs` with ONLY the test module first:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+
+    #[test]
+    fn fake_sink_records_and_serves_settings() {
+        let fake = Arc::new(FakeIdentitySink::default());
+        fake.record_pending("freshopencode-r1", "freshopencode", Some("/w"));
+        fake.record_binding(FreshAgentBindingUpsert {
+            provider: "opencode".into(),
+            session_id: "ses_1".into(),
+            mode: "freshopencode".into(),
+            create_request_id: Some("r1".into()),
+            resolves_pending: Some("freshopencode-r1".into()),
+            settings: FreshAgentSettings {
+                model: Some("m".into()),
+                sandbox: None,
+                permission_mode: None,
+                effort: Some("low".into()),
+                cwd: Some("/w".into()),
+            },
+        });
+        let s = fake.load_settings("opencode", "ses_1").expect("settings");
+        assert_eq!(s.model.as_deref(), Some("m"));
+        assert_eq!(s.effort.as_deref(), Some("low"));
+        assert_eq!(fake.pendings.lock().unwrap().len(), 1);
+        assert_eq!(fake.bindings.lock().unwrap().len(), 1);
+        assert!(fake.load_settings("opencode", "nope").is_none());
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo test -p freshell-freshagent identity_sink`
+Expected: COMPILE ERROR (types not defined).
+
+- [ ] **Step 3: Implement the module**
+
+Full content of `identity_sink.rs` above the test module:
+
+```rust
+//! P1.13 crate-boundary bridge: fresh-agent identity events flow OUT of this
+//! crate through this trait; `freshell-server` implements it over the pane
+//! ledger (this crate must not depend on `freshell-ws`, where the ledger
+//! lives — the dependency edge runs the other way).
+
+use std::sync::Arc;
+
+/// Resume-invocation record (campaign plan §4.2): exactly what the
+/// provider-native resume command needs.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct FreshAgentSettings {
+    pub model: Option<String>,
+    pub sandbox: Option<String>,
+    pub permission_mode: Option<String>,
+    pub effort: Option<String>,
+    pub cwd: Option<String>,
+}
+
+/// One fresh-agent identity event. Settings are a FULL snapshot (replace,
+/// not merge). `resolves_pending` names a pending marker (placeholder id)
+/// this binding supersedes.
+#[derive(Debug, Clone, PartialEq)]
+pub struct FreshAgentBindingUpsert {
+    pub provider: String,
+    pub session_id: String,
+    pub mode: String,
+    pub create_request_id: Option<String>,
+    pub resolves_pending: Option<String>,
+    pub settings: FreshAgentSettings,
+}
+
+/// Fire-and-forget writes (implementations must not block the caller;
+/// ledger fsync work belongs on `spawn_blocking`), memory-fast reads.
+pub trait PaneIdentitySink: Send + Sync {
+    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>);
+    fn record_binding(&self, upsert: FreshAgentBindingUpsert);
+    fn load_settings(&self, provider: &str, session_id: &str) -> Option<FreshAgentSettings>;
+}
+
+pub type SharedPaneIdentitySink = Arc<dyn PaneIdentitySink>;
+
+/// In-memory sink for tests, crate-wide.
+#[cfg(test)]
+#[derive(Default)]
+pub(crate) struct FakeIdentitySink {
+    pub pendings: std::sync::Mutex<Vec<(String, String, Option<String>)>>,
+    pub bindings: std::sync::Mutex<Vec<FreshAgentBindingUpsert>>,
+    pub settings: std::sync::Mutex<std::collections::HashMap<(String, String), FreshAgentSettings>>,
+}
+
+#[cfg(test)]
+impl FakeIdentitySink {
+    pub fn seed(&self, provider: &str, session_id: &str, s: FreshAgentSettings) {
+        self.settings.lock().unwrap().insert((provider.into(), session_id.into()), s);
+    }
+}
+
+#[cfg(test)]
+impl PaneIdentitySink for FakeIdentitySink {
+    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>) {
+        self.pendings.lock().unwrap().push((placeholder_id.into(), mode.into(), cwd.map(Into::into)));
+    }
+    fn record_binding(&self, upsert: FreshAgentBindingUpsert) {
+        self.settings
+            .lock()
+            .unwrap()
+            .insert((upsert.provider.clone(), upsert.session_id.clone()), upsert.settings.clone());
+        self.bindings.lock().unwrap().push(upsert);
+    }
+    fn load_settings(&self, provider: &str, session_id: &str) -> Option<FreshAgentSettings> {
+        self.settings.lock().unwrap().get(&(provider.into(), session_id.into())).cloned()
+    }
+}
+```
+
+In `lib.rs`: `pub mod identity_sink;` and `pub use identity_sink::{FreshAgentBindingUpsert, FreshAgentSettings, PaneIdentitySink, SharedPaneIdentitySink};`
+
+On EACH of the three states (`FreshCodexState`, `FreshOpencodeState`, `FreshClaudeState`) add a clone-shared, set-once field (states are cloned into consumer tasks, so the `OnceLock` must sit behind an `Arc`):
+
+```rust
+identity_sink: std::sync::Arc<std::sync::OnceLock<SharedPaneIdentitySink>>,
+```
+
+Initialize `identity_sink: Arc::new(OnceLock::new())` in each constructor, and add to each state:
+
+```rust
+pub fn set_identity_sink(&self, sink: SharedPaneIdentitySink) {
+    let _ = self.identity_sink.set(sink);
+}
+fn identity_sink(&self) -> Option<SharedPaneIdentitySink> {
+    self.identity_sink.get().cloned()
+}
+```
+
+(Precedent for the post-construction setter: `TerminalRegistry::set_activity_observer`, wired at `freshell-server/src/main.rs:408`. Clippy will demand `#[allow(dead_code)]` or usage — the private getter is used starting Task 4; if clippy `-D warnings` flags it in this task, mark the getter `pub(crate)` and add a `// used by identity-event tasks` comment rather than suppressing.)
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-freshagent identity_sink && cargo test -p freshell-freshagent`
+Expected: PASS, no regressions.
+
+- [ ] **Step 5: Quality gate + commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-freshagent/src/identity_sink.rs crates/freshell-freshagent/src/lib.rs \
+        crates/freshell-freshagent/src/codex.rs crates/freshell-freshagent/src/opencode_ws.rs \
+        crates/freshell-freshagent/src/claude.rs
+git commit -m "feat(freshagent): PaneIdentitySink trait - crate-boundary bridge for the pane ledger (P1.13)"
+```
+
+---
+
+### Task 3: `LedgerIdentitySink` in freshell-server + main.rs injection
+
+**Files:**
+- Create: `crates/freshell-server/src/identity_sink.rs`
+- Modify: `crates/freshell-server/src/main.rs`
+- Test: `#[cfg(test)]` in `crates/freshell-server/src/identity_sink.rs`
+
+**Interfaces:**
+- Consumes: `PaneLedger::{record_pending, record_fresh_agent_binding, delete_pending, load_binding}` (Task 1), `freshell_freshagent::{PaneIdentitySink, FreshAgentBindingUpsert, FreshAgentSettings}` (Task 2).
+- Produces: `pub struct LedgerIdentitySink; pub fn LedgerIdentitySink::new(ledger: Arc<PaneLedger>) -> Self`.
+
+- [ ] **Step 1: Write the failing test**
+
+In the new file's test module (async because writes hop through `spawn_blocking`):
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use freshell_freshagent::{FreshAgentBindingUpsert, FreshAgentSettings, PaneIdentitySink};
+    use std::sync::Arc;
+    use std::time::Duration;
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn writes_through_to_ledger_and_reads_back() {
+        let tmp = tempfile::tempdir().unwrap();
+        let ledger = Arc::new(freshell_ws::pane_ledger::PaneLedger::new(Some(tmp.path().to_path_buf())));
+        let sink = LedgerIdentitySink::new(ledger.clone());
+        sink.record_binding(FreshAgentBindingUpsert {
+            provider: "codex".into(),
+            session_id: "t1".into(),
+            mode: "freshcodex".into(),
+            create_request_id: None,
+            resolves_pending: None,
+            settings: FreshAgentSettings {
+                model: Some("gpt-5.3-codex".into()),
+                sandbox: Some("workspace-write".into()),
+                permission_mode: Some("on-request".into()),
+                effort: None,
+                cwd: Some("/w".into()),
+            },
+        });
+        // record_binding is fire-and-forget via spawn_blocking: poll.
+        let mut got = None;
+        for _ in 0..50 {
+            if let Some(s) = sink.load_settings("codex", "t1") { got = Some(s); break; }
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+        let s = got.expect("binding visible within 1s");
+        assert_eq!(s.model.as_deref(), Some("gpt-5.3-codex"));
+        assert_eq!(s.sandbox.as_deref(), Some("workspace-write"));
+        let row = ledger.load_binding("codex", "t1").unwrap();
+        assert_eq!(row.pane_kind.as_deref(), Some("fresh-agent"));
+    }
+}
+```
+
+(If `tempfile` is not already a dev-dependency of `freshell-server`, add it to `[dev-dependencies]` — check how the existing `existence.rs` tests create temp dirs and reuse that helper instead if one exists.)
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo test -p freshell-server identity_sink`
+Expected: COMPILE ERROR (module/type not defined).
+
+- [ ] **Step 3: Implement**
+
+`crates/freshell-server/src/identity_sink.rs`:
+
+```rust
+//! Server-side implementation of the fresh-agent identity bridge (P1.13):
+//! freshell-freshagent cannot see the ledger (crate cycle), so main.rs
+//! injects this adapter at wiring time.
+
+use freshell_freshagent::{FreshAgentBindingUpsert, FreshAgentSettings, PaneIdentitySink};
+use freshell_ws::pane_ledger::{FreshAgentBindingWrite, PaneLedger};
+use std::sync::Arc;
+
+pub struct LedgerIdentitySink {
+    ledger: Arc<PaneLedger>,
+}
+
+impl LedgerIdentitySink {
+    pub fn new(ledger: Arc<PaneLedger>) -> Self {
+        Self { ledger }
+    }
+}
+
+fn now_ms() -> i64 {
+    // Match the timestamp convention main.rs already uses for ledger writes
+    // (see the boot-scan / record_binding call sites in main.rs).
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_millis() as i64)
+        .unwrap_or(0)
+}
+
+impl PaneIdentitySink for LedgerIdentitySink {
+    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>) {
+        let ledger = self.ledger.clone();
+        let (p, m, c) = (placeholder_id.to_string(), mode.to_string(), cwd.map(str::to_string));
+        tokio::task::spawn_blocking(move || {
+            if let Err(e) = ledger.record_pending(&p, &m, c.as_deref(), now_ms()) {
+                tracing::warn!(error = %e, placeholder = %p, "pane_ledger.fresh_agent.pending_write_failed");
+            }
+        });
+    }
+
+    fn record_binding(&self, upsert: FreshAgentBindingUpsert) {
+        let ledger = self.ledger.clone();
+        tokio::task::spawn_blocking(move || {
+            let w = FreshAgentBindingWrite {
+                provider: &upsert.provider,
+                session_id: &upsert.session_id,
+                mode: &upsert.mode,
+                cwd: upsert.settings.cwd.as_deref(),
+                create_request_id: upsert.create_request_id.as_deref(),
+                model: upsert.settings.model.as_deref(),
+                sandbox: upsert.settings.sandbox.as_deref(),
+                permission_mode: upsert.settings.permission_mode.as_deref(),
+                effort: upsert.settings.effort.as_deref(),
+                now_ms: now_ms(),
+            };
+            if let Err(e) = ledger.record_fresh_agent_binding(&w) {
+                tracing::warn!(error = %e, provider = %upsert.provider, session = %upsert.session_id,
+                    "pane_ledger.fresh_agent.binding_write_failed");
+            }
+            if let Some(p) = upsert.resolves_pending.as_deref() {
+                if let Err(e) = ledger.delete_pending(p) {
+                    tracing::warn!(error = %e, placeholder = %p, "pane_ledger.fresh_agent.pending_delete_failed");
+                }
+            }
+        });
+    }
+
+    fn load_settings(&self, provider: &str, session_id: &str) -> Option<FreshAgentSettings> {
+        // Reads are memory-only against the write-through index — safe inline.
+        let row = self.ledger.load_binding(provider, session_id)?;
+        Some(FreshAgentSettings {
+            model: row.model,
+            sandbox: row.sandbox,
+            permission_mode: row.permission_mode,
+            effort: row.effort,
+            cwd: row.cwd,
+        })
+    }
+}
+```
+
+In `main.rs`: add `mod identity_sink;`, then AFTER the ledger is constructed (`main.rs:426-429`) inject into the three provider states (they are constructed earlier, at `main.rs:209/219/234/239` — the post-construction setter exists precisely for this ordering):
+
+```rust
+let fresh_agent_identity_sink: freshell_freshagent::SharedPaneIdentitySink =
+    std::sync::Arc::new(identity_sink::LedgerIdentitySink::new(pane_ledger.clone()));
+fresh_codex.set_identity_sink(fresh_agent_identity_sink.clone());
+fresh_claude.set_identity_sink(fresh_agent_identity_sink.clone());
+fresh_opencode.set_identity_sink(fresh_agent_identity_sink.clone());
+```
+
+(Use the actual local variable names from main.rs — the states are the ones placed into `WsState` fields `fresh_codex` / `fresh_claude` / `fresh_opencode`; if `WsState` is already constructed by line 426, call the setters on the state handles before they're moved, or via `state.fresh_codex.set_identity_sink(...)` — the field is `Arc<OnceLock>` so either handle works. `pane_ledger` in main.rs may be a value, not `Arc` — wrap once: `let pane_ledger = Arc::new(pane_ledger);` mirroring how `session_existence` receives it at `main.rs:440-449`, adapting the `WsState` field if it takes the Arc.)
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-server identity_sink && cargo test -p freshell-server`
+Expected: PASS.
+
+- [ ] **Step 5: Quality gate + commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-server/src/identity_sink.rs crates/freshell-server/src/main.rs \
+        crates/freshell-server/Cargo.toml
+git commit -m "feat(server): wire pane ledger into fresh-agent states via LedgerIdentitySink (P1.13)"
+```
+
+---
+
+### Task 4: Codex — ledger writes at every identity event
+
+**Files:**
+- Modify: `crates/freshell-freshagent/src/codex.rs`
+- Test: inline `#[cfg(test)]` tests in `codex.rs` (harness: `ENV_LOCK` + `configure_fake_codex_cmd` at `codex.rs:4975/4979`, `create_real_fake_session` at `:4988`)
+
+**Interfaces:**
+- Consumes: `FakeIdentitySink` / `set_identity_sink` (Task 2). `CodexSession` fields (`codex.rs:163-199`): `model: String`, `effort: Option<String>`, `cwd: Option<String>`, `sandbox: Option<String>`, `permission_mode: Option<String>`.
+- Produces: private helper `fn record_codex_binding(&self, session_id: &str, create_request_id: Option<&str>, model: &str, sandbox: Option<&str>, permission_mode: Option<&str>, effort: Option<&str>, cwd: Option<&str>)` on `FreshCodexState`, called at all five identity sites. Codex ledger rows use `provider: "codex"`, `mode: "freshcodex"`.
+
+- [ ] **Step 1: Write the failing test**
+
+Add near the existing create tests (using the module's existing fake-app-server harness — model the setup on the test at `codex.rs:5145`'s sibling create tests / `create_real_fake_session`):
+
+```rust
+#[tokio::test(flavor = "multi_thread")]
+async fn create_records_fresh_agent_binding_with_settings() {
+    let _guard = ENV_LOCK.lock().await;
+    configure_fake_codex_cmd(/* default behavior json the existing create tests use */);
+    let (state, _bus) = state_with_bus();
+    let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+    state.set_identity_sink(fake.clone());
+
+    // Drive a real create through the fake app server, requesting explicit
+    // settings — reuse create_real_fake_session, passing model/sandbox if it
+    // accepts them, otherwise inline the same freshAgent.create the existing
+    // create tests send, with:
+    //   model: "gpt-5.3-codex", sandbox: "workspace-write",
+    //   permissionMode: "on-request", effort: "high", cwd: <tmp dir>
+    let thread_id = create_real_fake_session(&state /* …with settings… */).await;
+
+    let bindings = fake.bindings.lock().unwrap();
+    let b = bindings.iter().find(|b| b.session_id == thread_id).expect("binding row written at thread/start");
+    assert_eq!(b.provider, "codex");
+    assert_eq!(b.mode, "freshcodex");
+    assert_eq!(b.settings.model.as_deref(), Some("gpt-5.3-codex"));
+    assert_eq!(b.settings.sandbox.as_deref(), Some("workspace-write"));
+    assert_eq!(b.settings.permission_mode.as_deref(), Some("on-request"));
+    assert_eq!(b.settings.effort.as_deref(), Some("high"));
+}
+```
+
+(The comment lines describe which existing helper to reuse — the implementer replaces them with the harness's real invocation, keeping the four explicit settings values and all five assertions exactly as written. The existing create tests in `codex.rs` show the exact `freshAgent.create` message shape; wire params are camelCase: `requestId`, `sessionType`, `cwd`, `model`, `permissionMode`, `sandbox`, `effort`, `resumeSessionId`.)
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo test -p freshell-freshagent create_records_fresh_agent_binding`
+Expected: FAIL — `bindings` is empty (no ledger write exists yet).
+
+- [ ] **Step 3: Implement**
+
+(a) Add the shared helper on `FreshCodexState`:
+
+```rust
+fn record_codex_binding(
+    &self,
+    session_id: &str,
+    create_request_id: Option<&str>,
+    model: &str,
+    sandbox: Option<&str>,
+    permission_mode: Option<&str>,
+    effort: Option<&str>,
+    cwd: Option<&str>,
+) {
+    let Some(sink) = self.identity_sink() else { return };
+    sink.record_binding(crate::identity_sink::FreshAgentBindingUpsert {
+        provider: "codex".into(),
+        session_id: session_id.into(),
+        mode: "freshcodex".into(),
+        create_request_id: create_request_id.map(Into::into),
+        resolves_pending: None,
+        settings: crate::identity_sink::FreshAgentSettings {
+            model: if model.is_empty() { None } else { Some(model.into()) },
+            sandbox: sandbox.map(Into::into),
+            permission_mode: permission_mode.map(Into::into),
+            effort: effort.map(Into::into),
+            cwd: cwd.map(Into::into),
+        },
+    });
+}
+```
+
+(b) Call it immediately after each of the five `sessions.insert` construction sites, passing that site's just-inserted values:
+1. `finish_create` (`codex.rs:603-619`) — the healthy create; `session_id` = `started.thread_id` (durable at create, born at `codex.rs:398`); `create_request_id` = the create message's `requestId`.
+2. `handle_create_resume` (R1, `codex.rs:462`…).
+3. `ensure_session_alive` (R2, `codex.rs:1064`…) — refresh write, same id.
+4. `ensure_session_resumable` (R3, `codex.rs:1675`…) — refresh write (its settings become real in Task 5).
+5. `respawn_as_new_thread_after_crash` (`codex.rs:1283`, re-key at `:1325-1347`) — NEW row under the new thread id (`codex.rs:1307`).
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-freshagent codex`
+Expected: PASS (new test + all existing codex tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-freshagent/src/codex.rs
+git commit -m "feat(codex): write fresh-agent ledger binding rows at every identity event (P1.13)"
+```
+
+---
+
+### Task 5: Codex — settings-from-ledger on all three resume paths + SETTINGS_RESET alarm
+
+**Files:**
+- Modify: `crates/freshell-freshagent/src/codex.rs`
+- Test: inline `#[cfg(test)]` in `codex.rs`
+
+**Interfaces:**
+- Consumes: `identity_sink().load_settings("codex", id)` (Task 2); fake app server request recorder (`appendThreadOperationLogPath` → JSONL `{method, threadId, params}` per `thread/*` RPC, `fake-app-server.mjs:360-374`; behavior via `FAKE_CODEX_APP_SERVER_BEHAVIOR`).
+- Produces: private `fn emit_fresh_agent_error(&self, session_id: &str, code: &str, message: &str)` on `FreshCodexState`; alarm code string `"SETTINGS_RESET"` (shared vocabulary with Tasks 8 and 10).
+
+**Known defect being fixed:** `ensure_session_resumable` (`codex.rs:1675`, restart/reload path — reached from attach-untracked `:1017` and REST snapshot `:1584`) resumes with `model/sandbox/approval_policy = None` (`:1721-1727`) and registers `model: String::new(), effort/sandbox/permission_mode: None` (`:1791-1799`); every post-restart turn silently runs on defaults forever.
+
+- [ ] **Step 1: Write the failing tests**
+
+```rust
+#[tokio::test(flavor = "multi_thread")]
+async fn resume_after_restart_reapplies_settings_from_ledger() {
+    let _guard = ENV_LOCK.lock().await;
+    // Behavior JSON: thread/resume succeeds; include appendThreadOperationLogPath
+    // pointing at a temp file (the existing consumer of this knob is
+    // test/integration/server/codex-session-flow.test.ts:497 — copy the JSON shape).
+    let op_log = tempfile::NamedTempFile::new().unwrap();
+    configure_fake_codex_cmd(/* behavior json with appendThreadOperationLogPath = op_log.path() */);
+    let (state, _bus) = state_with_bus();
+    let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+    fake.seed("codex", "thread-9", crate::identity_sink::FreshAgentSettings {
+        model: Some("gpt-5.3-codex".into()),
+        sandbox: Some("workspace-write".into()),
+        permission_mode: Some("on-request".into()),
+        effort: Some("high".into()),
+        cwd: Some("/w".into()),
+    });
+    state.set_identity_sink(fake.clone());
+
+    // Simulate the restart path exactly as the existing R3 tests do
+    // (handle_attach_unknown_session_* at codex.rs:3751/3793/3832/3862):
+    // attach to "thread-9" which is NOT in the in-memory map.
+    // <invoke the same entry point those tests use>
+
+    // (1) The registered session carries the recovered settings:
+    let sessions = state.sessions.lock().await;
+    let s = sessions.get("thread-9").expect("session registered");
+    assert_eq!(s.model, "gpt-5.3-codex");
+    assert_eq!(s.sandbox.as_deref(), Some("workspace-write"));
+    assert_eq!(s.permission_mode.as_deref(), Some("on-request"));
+    assert_eq!(s.effort.as_deref(), Some("high"));
+    drop(sessions);
+
+    // (2) The thread/resume RPC itself carried them (the wire is the contract):
+    let log = std::fs::read_to_string(op_log.path()).unwrap();
+    let resume_line = log.lines().find(|l| l.contains("\"thread/resume\"")).expect("thread/resume logged");
+    let entry: serde_json::Value = serde_json::from_str(resume_line).unwrap();
+    assert_eq!(entry["params"]["model"], "gpt-5.3-codex");
+    assert_eq!(entry["params"]["sandbox"], "workspace-write");
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn resume_with_no_ledger_record_emits_settings_reset_alarm() {
+    let _guard = ENV_LOCK.lock().await;
+    configure_fake_codex_cmd(/* resume-succeeds behavior */);
+    let (state, mut bus_rx) = state_with_bus(); // subscribe to the broadcast bus
+    let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default()); // deliberately empty
+    state.set_identity_sink(fake);
+
+    // Same R3 entry point as above for an untracked "thread-x".
+
+    // Drain broadcast frames (bounded) and find the alarm:
+    let mut found = false;
+    while let Ok(frame) = tokio::time::timeout(std::time::Duration::from_secs(2), bus_rx.recv()).await {
+        let Ok(text) = frame else { break };
+        if text.contains("SETTINGS_RESET") { found = true; break; }
+    }
+    assert!(found, "missing-record resume must broadcast a SETTINGS_RESET freshAgent.error");
+}
+```
+
+(The `<invoke the same entry point those tests use>` comments direct the implementer to the exact donor tests at `codex.rs:3751-3862`; the assertions are the contract and must remain exactly as written. If `sessions` is not directly readable from tests, reuse whatever accessor those donor tests use to inspect registered sessions.)
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test -p freshell-freshagent resume_after_restart_reapplies_settings`
+Expected: FAIL — registered session has `model == ""` and the op-log resume params lack model/sandbox. The alarm test FAILS with no SETTINGS_RESET frame.
+
+- [ ] **Step 3: Implement**
+
+(a) Alarm helper on `FreshCodexState` — deliver through the same broadcast path the consumer already uses to forward sidecar-originated `freshAgent.error` events to clients (locate the consumer's event forwarding; the frame on the wire must be byte-compatible with a sidecar-produced error event so the frozen client's banner path fires). The event payload is exactly:
+
+```json
+{ "type": "freshAgent.error", "sessionId": "<id>", "code": "<code>", "message": "<message>" }
+```
+
+```rust
+fn emit_fresh_agent_error(&self, session_id: &str, code: &str, message: &str) {
+    // Build the envelope the same way the consumer forwards sidecar events
+    // (same outer frame the client's fresh-agent-ws.ts event router reads),
+    // with the payload above, and send it via self.broadcast / broadcast_tx.
+}
+```
+
+(b) `ensure_session_resumable` (R3): before issuing `thread/resume`, load the record:
+
+```rust
+let recovered = self.identity_sink().and_then(|s| s.load_settings("codex", durable_id));
+if recovered.is_none() {
+    tracing::warn!(session = %durable_id, "freshagent.codex.settings_record_missing");
+    self.emit_fresh_agent_error(
+        durable_id,
+        "SETTINGS_RESET",
+        "Session settings could not be recovered after restart - the agent is running with default model and permissions. Reconfirm your settings.",
+    );
+}
+let rec = recovered.unwrap_or_default();
+```
+
+Then replace the three `None`s at `:1721-1727` with `rec.model` / `rec.sandbox` / `rec.permission_mode` (the resume request's approval-policy param) — and pass `rec.effort` wherever the healthy create passes effort. Replace the blank registration at `:1791-1799` with `model: rec.model.clone().unwrap_or_default(), sandbox: rec.sandbox.clone(), permission_mode: rec.permission_mode.clone(), effort: rec.effort.clone(), cwd: <existing cwd source>.or(rec.cwd.clone())`. Delete the stale comment claiming `handle_send` repairs settings (it only reads, `:733-777`). The Task-4 `record_codex_binding` call at this site now persists the recovered values.
+
+(c) `ensure_session_alive` (R2): where it forwards stored settings, add a ledger fallback for the blank case:
+
+```rust
+let (model, sandbox, permission_mode, effort) = if session_model.is_empty() {
+    let rec = self.identity_sink().and_then(|s| s.load_settings("codex", durable_id)).unwrap_or_default();
+    (rec.model.unwrap_or_default(), rec.sandbox, rec.permission_mode, rec.effort)
+} else {
+    (session_model, session_sandbox, session_permission_mode, session_effort)
+};
+```
+
+(d) `handle_create_resume` (R1): the client's explicit params win; ledger fills gaps:
+
+```rust
+let rec = self.identity_sink().and_then(|s| s.load_settings("codex", resume_id)).unwrap_or_default();
+let model = msg_model.or(rec.model);
+let sandbox = msg_sandbox.or(rec.sandbox);
+let permission_mode = msg_permission_mode.or(rec.permission_mode);
+let effort = msg_effort.or(rec.effort);
+let cwd = msg_cwd.or(rec.cwd);
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-freshagent codex`
+Expected: PASS (both new tests + all existing codex tests, including the existing R2/R3 fallback tests — if an existing test pinned the blank-registration behavior, update its assertions to the new contract and say so in the commit body).
+
+- [ ] **Step 5: Commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-freshagent/src/codex.rs
+git commit -m "fix(codex): resume paths reapply model/sandbox/permission/effort from the ledger record (P1.13 §2.6c)"
+```
+
+---
+
+### Task 6: Codex — crash-respawn degradation frame (memory loss is user-visible)
+
+**Files:**
+- Modify: `crates/freshell-freshagent/src/codex.rs`
+- Test: extend the existing crash tests (`send_after_crash_falls_back_to_mint_new_thread…` at `codex.rs:5145`, siblings at `:5224/:4625`)
+
+**Interfaces:**
+- Consumes: `emit_fresh_agent_error` (Task 5), `record_codex_binding` (Task 4).
+- Produces: alarm code string `"THREAD_MEMORY_LOST"`.
+
+**Known defect being fixed:** `respawn_as_new_thread_after_crash` (`codex.rs:1283`) silently discards conversation memory — the only signal is `tracing::warn!(… "freshagent.crash_recovery.minted_new")` at `:1362-1366`, server-log only.
+
+- [ ] **Step 1: Write the failing test**
+
+Extend (or clone-and-extend) `send_after_crash_falls_back_to_mint_new_thread…` (`codex.rs:5145`): after driving the crash-respawn, drain the broadcast bus and assert a `THREAD_MEMORY_LOST` frame was emitted with the NEW thread id, AFTER the `freshAgent.session.materialized` frame:
+
+```rust
+// … existing test body up to the respawn assertion, keeping a bus receiver …
+let mut saw_materialized = false;
+let mut degradation_after_materialized = false;
+while let Ok(frame) = tokio::time::timeout(std::time::Duration::from_secs(2), bus_rx.recv()).await {
+    let Ok(text) = frame else { break };
+    if text.contains("freshAgent.session.materialized") { saw_materialized = true; }
+    if text.contains("THREAD_MEMORY_LOST") {
+        assert!(saw_materialized, "degradation frame must follow materialized (client re-keys on it)");
+        assert!(text.contains(&new_thread_id), "frame must target the NEW thread id");
+        degradation_after_materialized = true;
+        break;
+    }
+}
+assert!(degradation_after_materialized, "crash respawn must broadcast a user-visible degradation frame");
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo test -p freshell-freshagent send_after_crash`
+Expected: FAIL — no `THREAD_MEMORY_LOST` frame.
+
+- [ ] **Step 3: Implement**
+
+In `respawn_as_new_thread_after_crash`, in the gap between the map re-key (`:1325-1347`) and the existing `warn!` (`:1348-1361`), keep the `warn!`, and AFTER the `FreshAgentSessionMaterialized` broadcast (`:1368`) add:
+
+```rust
+self.emit_fresh_agent_error(
+    &new_thread_id,
+    "THREAD_MEMORY_LOST",
+    "Codex crashed and this pane was restarted as a new thread. The agent no longer has memory of the earlier conversation in this pane.",
+);
+```
+
+(Order matters: the frozen client re-keys its session state on `materialized` (`fresh-agent-ws.ts:143-160`); emitting the error first would target a session id the client no longer tracks. The non-`RESTORE_` error branch also clears streaming and forces `running → idle` — safe here, the turn is already dead. The Task-4 binding write for the new thread id sits at the same site.)
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-freshagent codex`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-freshagent/src/codex.rs
+git commit -m "feat(codex): user-visible THREAD_MEMORY_LOST degradation frame on crash respawn (P1.13 §2.6b)"
+```
+
+---
+
+### Task 7: Opencode — pending marker + binding writes + settings-change updates
+
+**Files:**
+- Modify: `crates/freshell-freshagent/src/opencode_ws.rs`
+- Test: inline `#[cfg(test)]` using the existing in-crate trait fakes (`FakeHttp` etc. at `opencode_ws.rs:866-1076`, harnesses `:1080-1111`)
+
+**Interfaces:**
+- Consumes: `set_identity_sink`/`FakeIdentitySink` (Task 2). Sites: create `handle_create` (`opencode_ws.rs:243-247`, placeholder `freshopencode-<requestId>` at `:245`); materialization (durable `ses_*` id assigned `:359`, cwd upgraded `:360-364`, `freshAgent.session.materialized` broadcast `:373-384`); settings commit in `handle_send` (`session.model = model; session.effort = effort;` at `:397-398`).
+- Produces: opencode ledger rows use `provider: "opencode"`, `mode: "freshopencode"`.
+
+- [ ] **Step 1: Write the failing test**
+
+```rust
+#[tokio::test]
+async fn materialization_resolves_pending_into_binding_with_settings() {
+    // Harness: same FakeHttp setup the existing materialization test uses.
+    let (state, /* … */) = harness(/* … */);
+    let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+    state.set_identity_sink(fake.clone());
+
+    // Create with settings, then first send (materializes ses_*):
+    // freshAgent.create { requestId: "r1", sessionType: "freshopencode",
+    //                     cwd: "/w", model: "big-model", effort: "high" }
+    // then freshAgent.send — reuse the existing test's driver.
+
+    // Pending was recorded at create under the placeholder:
+    let pendings = fake.pendings.lock().unwrap();
+    assert!(pendings.iter().any(|(id, mode, _)| id.starts_with("freshopencode-") && mode == "freshopencode"));
+    drop(pendings);
+
+    // Binding recorded at materialization, resolving the pending:
+    let bindings = fake.bindings.lock().unwrap();
+    let b = bindings.iter().find(|b| b.session_id.starts_with("ses_")).expect("binding at materialization");
+    assert_eq!(b.provider, "opencode");
+    assert_eq!(b.settings.model.as_deref(), Some("big-model"));
+    assert_eq!(b.settings.effort.as_deref(), Some("high"));
+    assert!(b.settings.cwd.is_some(), "cwd captured (upgraded from created.directory)");
+    assert!(b.resolves_pending.as_deref().unwrap_or("").starts_with("freshopencode-"));
+}
+
+#[tokio::test]
+async fn send_with_changed_settings_refreshes_the_binding() {
+    // Same harness; after materialization, send again with
+    // settings: { model: "small-model", effort: "low" } (FreshAgentSendSettings,
+    // consumed per-turn at opencode_ws.rs:315-327).
+    // Assert the LAST recorded binding for the ses_* id carries the new values:
+    let bindings = fake.bindings.lock().unwrap();
+    let b = bindings.iter().rev().find(|b| b.session_id.starts_with("ses_")).unwrap();
+    assert_eq!(b.settings.model.as_deref(), Some("small-model"));
+    assert_eq!(b.settings.effort.as_deref(), Some("low"));
+}
+```
+
+(Driver plumbing comes from the existing tests in this file — e.g. the materialization/send tests around the harnesses at `:1080-1111` and `:1795-1819`; the assertions stand as written.)
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test -p freshell-freshagent opencode_ws -- materialization_resolves_pending send_with_changed_settings`
+Expected: FAIL — no pendings, no bindings recorded.
+
+- [ ] **Step 3: Implement**
+
+1. `handle_create` (`:243-247`): after registering the placeholder session:
+```rust
+if let Some(sink) = self.identity_sink() {
+    sink.record_pending(&placeholder_id, "freshopencode", session_cwd.as_deref());
+}
+```
+2. Materialization (`:359-369`, right after the durable id is assigned and cwd upgraded, before/alongside the `materialized` broadcast):
+```rust
+if let Some(sink) = self.identity_sink() {
+    sink.record_binding(crate::identity_sink::FreshAgentBindingUpsert {
+        provider: "opencode".into(),
+        session_id: durable_id.clone(),
+        mode: "freshopencode".into(),
+        create_request_id: Some(request_id.clone()),
+        resolves_pending: Some(placeholder_id.clone()),
+        settings: crate::identity_sink::FreshAgentSettings {
+            model: session.model.clone(),
+            sandbox: None,
+            permission_mode: None,
+            effort: session.effort.clone(),
+            cwd: session.cwd.clone(),
+        },
+    });
+}
+```
+(Adapt local variable names at the site; opencode has no sandbox/permission concepts — always `None`.)
+3. `handle_send` commit (`:397-398`): after `session.model = model.clone(); session.effort = effort.clone();`, if the session id is durable (`starts_with("ses_")`), record a refresh binding (same construction as above with `resolves_pending: None`, `create_request_id: None`).
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-freshagent opencode_ws`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-freshagent/src/opencode_ws.rs
+git commit -m "feat(opencode): pending marker at create, binding row at ses_* materialization, refresh on settings change (P1.13)"
+```
+
+---
+
+### Task 8: Opencode — settings-from-ledger resume
+
+**Files:**
+- Modify: `crates/freshell-freshagent/src/opencode_ws.rs`
+- Test: inline `#[cfg(test)]`
+
+**Interfaces:**
+- Consumes: `load_settings("opencode", id)` (Task 2); `emit`-style broadcast via `FreshOpencodeState::broadcast` (`opencode_ws.rs:194-196`); alarm code `"SETTINGS_RESET"` (same vocabulary as Task 5).
+- Site: `resume_durable_session` (`opencode_ws.rs:662-696`) — sole caller `handle_attach` (`:598-600`).
+
+**Known defect being fixed:** `resume_durable_session` builds `OpencodeSession::new(session_id, cwd.map(...), None, None)` at `:681` — model and effort hard-`None`; `cwd` comes from the attach message, not the session's real directory; the serve `GET /session/:id` body is fetched then discarded at `:678` (`let _ = info;`).
+
+- [ ] **Step 1: Write the failing tests**
+
+Clone the key resume test `attach_unknown_session_resumes_a_durable_serve_session_not_in_the_local_map` (`opencode_ws.rs:1523-1588`) into:
+
+```rust
+#[tokio::test]
+async fn resume_durable_session_reapplies_settings_from_ledger() {
+    // Same RealisticServeHttp harness as the donor test.
+    let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+    fake.seed("opencode", DURABLE_ID, crate::identity_sink::FreshAgentSettings {
+        model: Some("big-model".into()),
+        sandbox: None,
+        permission_mode: None,
+        effort: Some("high".into()),
+        cwd: Some("/real/project".into()),
+    });
+    state.set_identity_sink(fake);
+
+    // Drive the same attach the donor test drives.
+
+    let sessions = state.sessions.lock().await;
+    let s = sessions.get(DURABLE_ID).expect("resumed").lock().await;
+    assert_eq!(s.model.as_deref(), Some("big-model"));
+    assert_eq!(s.effort.as_deref(), Some("high"));
+    assert_eq!(s.cwd.as_deref(), Some("/real/project"), "cwd from the record, not the attach message");
+}
+
+#[tokio::test]
+async fn resume_without_record_emits_settings_reset_and_uses_serve_directory() {
+    // Same harness; NO seed. RealisticServeHttp's GET /session/:id returns a
+    // directory — assert it is now used instead of being discarded, and that
+    // a SETTINGS_RESET freshAgent.error frame was broadcast.
+    // (bus subscription pattern as in Task 5's alarm test)
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test -p freshell-freshagent resume_durable_session_reapplies`
+Expected: FAIL — model/effort are `None`, cwd is the attach message's.
+
+- [ ] **Step 3: Implement**
+
+In `resume_durable_session` (`:662-696`):
+
+```rust
+let recovered = self.identity_sink().and_then(|s| s.load_settings("opencode", &session_id));
+if recovered.is_none() {
+    tracing::warn!(session = %session_id, "freshagent.opencode.settings_record_missing");
+    self.emit_fresh_agent_error(
+        &session_id,
+        "SETTINGS_RESET",
+        "Session settings could not be recovered after restart - the agent is running with default model and effort. Reconfirm your settings.",
+    );
+}
+let rec = recovered.unwrap_or_default();
+// :678 — stop discarding the serve body; parse its `directory` field:
+let serve_dir = info_directory; // extract from `info` instead of `let _ = info;`
+let cwd = rec.cwd.clone().or(serve_dir).or(attach_msg_cwd);
+let session = OpencodeSession::new(session_id.clone(), cwd, rec.model.clone(), rec.effort.clone());
+```
+
+(`emit_fresh_agent_error` is a small helper mirroring Task 5's codex helper — same name, same `freshAgent.error` payload shape — built on `FreshOpencodeState::broadcast`. Model/effort take effect on the next turn because opencode sends them per-turn in the `prompt_async` body, `serve.rs:936-953` — the session fields are the source those sends read, plus Task 7's refresh keeps the ledger current.) After a successful resume, record a refresh binding (Task 7 construction, `resolves_pending: None`).
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-freshagent opencode_ws`
+Expected: PASS (donor test still green — it asserted resume works, not that settings are empty; if it pinned `None` settings, update it to the new contract and note that in the commit body).
+
+- [ ] **Step 5: Commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-freshagent/src/opencode_ws.rs
+git commit -m "fix(opencode): resume reapplies model/effort/cwd from the ledger record (P1.13 §2.7b)"
+```
+
+---
+
+### Task 9: Claude — binding writes at `sdk.session.init` (settings threaded to the consumer)
+
+**Files:**
+- Modify: `crates/freshell-freshagent/src/claude.rs`
+- Test: inline `#[cfg(test)]` using `FakeClaudeSidecarEnv` (`claude.rs:1518-1578`) + `CLAUDE_ENV_LOCK` (`:1463`)
+
+**Interfaces:**
+- Consumes: Task 2 sink. Sites: healthy create request built inline in `handle_create` (`claude.rs:216-225`, keys `cwd`, `model`, `permissionMode`, `effort`, `resumeSessionId`); `sdk.session.init` handled in `spawn_consumer`'s task (cliSessionId recorded into `cli_index`, `claude.rs:605-618`; in scope there: `broadcast_tx`, `sessions`, `cli_index` clones at `:593-595`).
+- Produces: `spawn_consumer` gains two params: `mode: String` (from `session_type_str`, `claude.rs:700-705` — preserves the `"freshclaude"` vs `"kilroy"` flavour; provider is always `"claude"`, `claude.rs:66`) and `settings: crate::identity_sink::FreshAgentSettings`. All `spawn_consumer` call sites updated.
+
+- [ ] **Step 1: Write the failing test**
+
+Model on the existing create tests that use `FakeClaudeSidecarEnv`:
+
+```rust
+#[tokio::test(flavor = "multi_thread")]
+async fn session_init_records_binding_with_create_settings() {
+    let _guard = CLAUDE_ENV_LOCK.lock().await;
+    let env = FakeClaudeSidecarEnv::new(/* as the donor create test does */);
+    let (state, /* … */) = /* donor harness */;
+    let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+    state.set_identity_sink(fake.clone());
+
+    // Drive freshAgent.create with:
+    //   sessionType: "kilroy", model: "opus-x", permissionMode: "plan",
+    //   effort: "high", cwd: <tmp>
+    // and wait for sdk.session.init to be consumed (donor tests show the wait).
+
+    let bindings = fake.bindings.lock().unwrap();
+    let b = bindings.last().expect("binding at sdk.session.init");
+    assert_eq!(b.provider, "claude");
+    assert_eq!(b.mode, "kilroy", "sessionType flavour preserved in the row");
+    assert!(b.session_id.len() > 0, "keyed by cliSessionId");
+    assert_eq!(b.settings.model.as_deref(), Some("opus-x"));
+    assert_eq!(b.settings.permission_mode.as_deref(), Some("plan"));
+    assert_eq!(b.settings.effort.as_deref(), Some("high"));
+    assert!(b.settings.cwd.is_some());
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo test -p freshell-freshagent session_init_records_binding`
+Expected: FAIL — no bindings recorded.
+
+- [ ] **Step 3: Implement**
+
+1. In `handle_create`: build `let settings = crate::identity_sink::FreshAgentSettings { model: msg.model.clone(), sandbox: None, permission_mode: msg.permission_mode.clone(), effort: msg.effort.clone(), cwd: resolved_cwd.clone() };` (claude has no sandbox concept — always `None`; use the resolved cwd the create request actually sends at `:216-225`). Pass `session_type_str(&msg).to_string()` and `settings` into `spawn_consumer`.
+2. In `spawn_consumer`'s `sdk.session.init` arm (`:605-618`), after `cli_index` is updated:
+```rust
+if let Some(sink) = identity_sink.clone() { // clone the Option<Arc> into the task alongside broadcast_tx/sessions/cli_index
+    sink.record_binding(crate::identity_sink::FreshAgentBindingUpsert {
+        provider: "claude".into(),
+        session_id: cli_session_id.clone(),
+        mode: mode.clone(),
+        create_request_id: None,
+        resolves_pending: None,
+        settings: settings.clone(),
+    });
+}
+```
+3. Update every `spawn_consumer` call site (create and resume paths) — the resume path passes the settings it resolves in Task 10; until Task 10 lands, pass `FreshAgentSettings::default()` there so this task compiles and its test passes.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-freshagent claude`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-freshagent/src/claude.rs
+git commit -m "feat(claude): record fresh-agent binding row with create settings at sdk.session.init (P1.13)"
+```
+
+---
+
+### Task 10: Claude — settings-from-ledger resume
+
+**Files:**
+- Modify: `crates/freshell-freshagent/src/claude.rs`
+- Test: inline `#[cfg(test)]`
+
+**Interfaces:**
+- Consumes: `load_settings("claude", durable)` (Task 2); the fake sidecar spawn log — the scripted Node fake logs the WHOLE create-request JSON per spawn to `FRESHELL_TEST_CLAUDE_SPAWN_LOG` (`claude.rs:1474-1516`), so asserting reapplied settings needs no new plumbing.
+- Site: `resume_for_attach` (`claude.rs:470-562`; signature `(&self, msg: &FreshAgentAttach, durable: &str) -> Result<(), ResumeClaudeError>`; sole caller `handle_attach` `:454` under the `resuming` single-flight). The Null-settings create request is built at `:502-511` (`"model": Null, "permissionMode": Null, "effort": Null`) — an independent duplicate of the create-path `json!` at `:216-225`.
+
+**Known defect being fixed:** `ClaudeSession` (`claude.rs:112-134`) tracks no settings at all; resume-in-place sends Nulls, so a restarted freshclaude/kilroy pane silently reverts model/permissionMode/effort.
+
+- [ ] **Step 1: Write the failing tests**
+
+Model on the existing resume tests (`claude.rs:1154-1304`, `:1797-1871`):
+
+```rust
+#[tokio::test(flavor = "multi_thread")]
+async fn resume_for_attach_reapplies_settings_from_ledger() {
+    let _guard = CLAUDE_ENV_LOCK.lock().await;
+    let env = FakeClaudeSidecarEnv::new(/* donor resume-test setup, with a spawn log */);
+    let (state, /* … */) = /* donor harness */;
+    let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+    fake.seed("claude", DURABLE, crate::identity_sink::FreshAgentSettings {
+        model: Some("opus-x".into()),
+        sandbox: None,
+        permission_mode: Some("plan".into()),
+        effort: Some("high".into()),
+        cwd: None,
+    });
+    state.set_identity_sink(fake);
+
+    // Drive the donor resume flow (attach to DURABLE with a transcript on disk).
+
+    let log = std::fs::read_to_string(env.spawn_log_path()).unwrap();
+    let create_req: serde_json::Value = /* parse the create-request JSON the fake logged, as the donor tests do */;
+    assert_eq!(create_req["model"], "opus-x");
+    assert_eq!(create_req["permissionMode"], "plan");
+    assert_eq!(create_req["effort"], "high");
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn resume_without_record_emits_settings_reset_and_sends_nulls() {
+    // Same flow, no seed: assert the spawn-logged create request has null
+    // model/permissionMode/effort (today's behavior preserved as fallback)
+    // AND a SETTINGS_RESET freshAgent.error frame was broadcast
+    // (bus subscription pattern from Task 5).
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test -p freshell-freshagent resume_for_attach_reapplies`
+Expected: FAIL — logged create request has nulls despite the seeded record.
+
+- [ ] **Step 3: Implement**
+
+In `resume_for_attach`, before building the create request at `:502-511`:
+
+```rust
+let recovered = self.identity_sink().and_then(|s| s.load_settings("claude", durable));
+if recovered.is_none() {
+    tracing::warn!(session = %durable, "freshagent.claude.settings_record_missing");
+    self.emit_fresh_agent_error(
+        durable,
+        "SETTINGS_RESET",
+        "Session settings could not be recovered after restart - the agent is running with default model and permissions. Reconfirm your settings.",
+    );
+}
+let rec = recovered.unwrap_or_default();
+```
+
+Replace the three `Null`s: `"model": rec.model, "permissionMode": rec.permission_mode, "effort": rec.effort` (`serde_json::json!` serializes `None` as `null`, preserving today's fallback wire shape exactly). Keep the existing deliberate cwd handling (`:487-497`) as the primary, with `rec.cwd` as a final fallback only if both existing sources are absent. Pass `mode:` derived via the existing `session_type_str` helper (`claude.rs:700-705`) applied to the attach message's sessionType (defaulting to `"freshclaude"` when absent) and `settings: rec.clone()` into this path's `spawn_consumer` call (Task 9 threading), so the re-init re-records the row under any new cliSessionId. `emit_fresh_agent_error` is the same helper shape as Task 5's, built on claude's direct broadcast (`claude.rs:173-177`).
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-freshagent claude`
+Expected: PASS (existing resume tests `:1154-1304`/`:1797-1871` still green — they assert transcript parity, not null settings; if any pinned the nulls, update to the new contract, noted in the commit body).
+
+- [ ] **Step 5: Commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-freshagent/src/claude.rs
+git commit -m "fix(claude): resume-in-place reapplies model/permissionMode/effort from the ledger record (P1.13)"
+```
+
+---
+
+### Task 11: `paneReconcileFreshAgentV1` capability — parse, thread, echo
+
+**Files:**
+- Modify: `crates/freshell-ws/src/lib.rs` (parse at the hello handler — sibling pattern `terminalOutputBatchV1` at `lib.rs:592-597`; `paneReconcileV1` at `:574-578`; ready echo where `paneReconcileV1` is echoed)
+- Modify: `crates/freshell-ws/src/terminal.rs` (`terminal::run` signature + `handle_pane_reconcile` param)
+- Test: `crates/freshell-ws/tests/pane_reconcile_freshagent.rs` (new file — first two tests)
+
+**Interfaces:**
+- Consumes: hello/ready handshake, `terminal::run(…, pane_reconcile_v1, …)` threading.
+- Produces: capability string `"paneReconcileFreshAgentV1"`; `handle_pane_reconcile(…, pane_reconcile_fresh_agent_v1: bool, …)`. Test harness helper `connect(url, pane_reconcile_v1, fresh_agent_v1) -> (TestWs, ready)`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `crates/freshell-ws/tests/pane_reconcile_freshagent.rs`. Copy the harness from `crates/freshell-ws/tests/pane_reconcile.rs` (`spawn_server()` at `:62-125` — full `WsState` literal, `NoIndexProbe`, `PaneLedger::disabled()`, ephemeral `127.0.0.1:0` axum; `connect()` at `:133-165`; `next_frame_of_type()`; `reconcile_request()`), with `connect` extended:
+
+```rust
+async fn connect(url: &str, pane_reconcile_v1: bool, fresh_agent_v1: bool) -> (TestWs, serde_json::Value) {
+    // identical to the donor, but:
+    // hello["capabilities"] = json!({
+    //     "paneReconcileV1": pane_reconcile_v1,
+    //     "paneReconcileFreshAgentV1": fresh_agent_v1,
+    // });
+}
+
+#[tokio::test]
+async fn ready_echoes_fresh_agent_capability_when_negotiated() {
+    let server = spawn_server().await;
+    let (_ws, ready) = connect(&server.url, true, true).await;
+    assert_eq!(ready["capabilities"]["paneReconcileFreshAgentV1"], serde_json::json!(true));
+}
+
+#[tokio::test]
+async fn without_the_capability_fresh_agent_kind_stays_invalid_unsupported() {
+    let server = spawn_server().await;
+    let (mut ws, _ready) = connect(&server.url, true, false).await; // frozen-client shape
+    let verdicts = reconcile_request(&mut ws, serde_json::json!([{
+        "paneKey": "p1", "kind": "fresh-agent",
+        "sessionRef": {"provider": "claude", "sessionId": "s-1"}
+    }])).await;
+    assert_eq!(verdicts[0]["verdict"], "invalid");
+    assert_eq!(verdicts[0]["reason"], "unsupported_kind");
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test -p freshell-ws --test pane_reconcile_freshagent`
+Expected: first test FAILS (ready has no `paneReconcileFreshAgentV1`); second PASSES already (it pins the frozen-client protection — keep it as the permanent regression guard).
+
+- [ ] **Step 3: Implement**
+
+In `lib.rs`, next to the `paneReconcileV1` parse (`:574-578`), same raw-JSON pattern as `terminalOutputBatchV1` (`:592-597`):
+
+```rust
+let pane_reconcile_fresh_agent_v1 = value
+    .get("capabilities")
+    .and_then(|c| c.get("paneReconcileFreshAgentV1"))
+    .and_then(|v| v.as_bool())
+    .unwrap_or(false);
+```
+
+Echo `paneReconcileFreshAgentV1: true` in `ready.capabilities` when negotiated (same conditional style as `paneReconcileV1` — omitted entirely when false). Thread the bool through `terminal::run` into `handle_pane_reconcile` (parameter only in this task; used in Task 13).
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-ws --test pane_reconcile_freshagent && cargo test -p freshell-ws`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-ws/src/lib.rs crates/freshell-ws/src/terminal.rs \
+        crates/freshell-ws/tests/pane_reconcile_freshagent.rs
+git commit -m "feat(ws): paneReconcileFreshAgentV1 capability - parsed, threaded, echoed; frozen client unaffected"
+```
+
+---
+
+### Task 12: `reconcile_freshagent` — pure verdict mapping (sync, catch_unwind-safe)
+
+**Files:**
+- Create: `crates/freshell-ws/src/reconcile_freshagent.rs`
+- Modify: `crates/freshell-ws/src/lib.rs` (`pub(crate) mod reconcile_freshagent;` — make it `pub` if the integration tests need the types; they do for the snapshot in Task 13, so declare `pub mod reconcile_freshagent;`)
+- Test: unit tests inline in the new module
+
+**Interfaces:**
+- Consumes: `freshell_protocol` types `ReconcilePane`, `PaneVerdict`, `ReconcileVerdict`, `SessionLocator` (verdict wire names: `attach`/`respawn`/`fresh`/`dead_session`/`invalid`; `PaneVerdict` fields `pane_key`, `verdict`, `terminal_id`, `session_ref`, `corrected`, `reason`, `retry_after_ms`, `duplicate` — optionals absent, never null).
+- Produces (exact, used by Task 13):
+
+```rust
+pub const FRESH_AGENT_RESPAWN_CAP: u32 = 3;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FreshAgentPresence { Live, OnDisk, GoneObserved, NeverObserved, Unknown }
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct FreshAgentPaneFacts {
+    pub presence: FreshAgentPresence,
+    pub duplicate_of: Option<String>, // paneKey of the earlier pane claiming the same session
+    pub respawn_exhausted: bool,
+}
+
+#[derive(Debug, Default)]
+pub struct FreshAgentReconcileSnapshot {
+    pub facts: std::collections::HashMap<String /* paneKey */, FreshAgentPaneFacts>,
+}
+
+pub fn verdict_for_pane(snapshot: Option<&FreshAgentReconcileSnapshot>, pane: &ReconcilePane) -> PaneVerdict
+```
+
+- [ ] **Step 1: Write the failing unit tests**
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    // helpers: fn pane(key: &str, sref: Option<(&str, &str)>) -> ReconcilePane { … kind: Some("fresh-agent".into()) … }
+    //          fn snap(entries: &[(&str, FreshAgentPresence, Option<&str>, bool)]) -> FreshAgentReconcileSnapshot { … }
+
+    #[test]
+    fn no_snapshot_means_capability_off_and_stays_invalid_unsupported() {
+        let v = verdict_for_pane(None, &pane("p", Some(("claude", "s"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Invalid);
+        assert_eq!(v.reason.as_deref(), Some("unsupported_kind"));
+    }
+
+    #[test]
+    fn missing_session_ref_is_fresh_no_recoverable_identity() {
+        let s = snap(&[]);
+        let v = verdict_for_pane(Some(&s), &pane("p", None));
+        assert_eq!(v.verdict, ReconcileVerdict::Fresh);
+        assert_eq!(v.reason.as_deref(), Some("no_recoverable_identity"));
+    }
+
+    #[test]
+    fn live_maps_to_attach_with_session_ref_echoed() {
+        let s = snap(&[("p", FreshAgentPresence::Live, None, false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("codex", "t1"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Attach);
+        assert_eq!(v.session_ref.as_ref().unwrap().session_id, "t1");
+        assert_eq!(v.terminal_id, None, "fresh-agent panes have no terminal id");
+    }
+
+    #[test]
+    fn on_disk_maps_to_respawn() {
+        let s = snap(&[("p", FreshAgentPresence::OnDisk, None, false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("opencode", "ses_1"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Respawn);
+        assert_eq!(v.session_ref.as_ref().unwrap().session_id, "ses_1");
+    }
+
+    #[test]
+    fn gone_observed_maps_to_dead_session_not_on_disk() {
+        let s = snap(&[("p", FreshAgentPresence::GoneObserved, None, false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("claude", "gone"))));
+        assert_eq!(v.verdict, ReconcileVerdict::DeadSession);
+        assert_eq!(v.reason.as_deref(), Some("session_not_on_disk"));
+        assert_eq!(v.session_ref.as_ref().unwrap().session_id, "gone", "claimed identity echoed for the error UI");
+    }
+
+    #[test]
+    fn never_observed_maps_to_fresh_identity_never_observed() {
+        let s = snap(&[("p", FreshAgentPresence::NeverObserved, None, false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("claude", "never"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Fresh);
+        assert_eq!(v.reason.as_deref(), Some("identity_never_observed"));
+    }
+
+    #[test]
+    fn unknown_prefers_respawn_over_memory_loss() {
+        // Cost asymmetry: respawn on a gone session degrades gracefully via the
+        // providers' native not-found fallbacks; fresh on a live-on-disk session
+        // loses conversation memory permanently.
+        let s = snap(&[("p", FreshAgentPresence::Unknown, None, false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("codex", "warm"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Respawn);
+    }
+
+    #[test]
+    fn duplicate_claim_yields_fresh_with_duplicate_marker() {
+        let s = snap(&[("p2", FreshAgentPresence::OnDisk, Some("p1"), false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p2", Some(("codex", "t1"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Fresh);
+        assert_eq!(v.reason.as_deref(), Some("duplicate_session_claim"));
+        assert_eq!(v.duplicate.as_deref(), Some("p1"));
+    }
+
+    #[test]
+    fn respawn_exhausted_yields_dead_session() {
+        let s = snap(&[("p", FreshAgentPresence::OnDisk, None, true)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("codex", "t1"))));
+        assert_eq!(v.verdict, ReconcileVerdict::DeadSession);
+        assert_eq!(v.reason.as_deref(), Some("respawn_exhausted"));
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test -p freshell-ws reconcile_freshagent`
+Expected: COMPILE ERROR (module doesn't exist).
+
+- [ ] **Step 3: Implement**
+
+```rust
+//! Fresh-agent pane verdicts (P1.13, campaign §4.3): same verdict vocabulary
+//! as terminals — attach (tracked live) / respawn (resumable via
+//! provider-native resume) / dead_session (positively gone) / fresh — no new
+//! states. All async work (session maps, probes) happens in the snapshot
+//! builder (Task 13); this module is pure + sync so it stays legal inside
+//! derive_verdicts' catch_unwind.
+
+use freshell_protocol::/* the same paths reconcile.rs imports for */ {PaneVerdict, ReconcilePane, ReconcileVerdict};
+
+pub const FRESH_AGENT_RESPAWN_CAP: u32 = 3;
+// … types exactly as the Interfaces block above …
+
+fn base(pane: &ReconcilePane, verdict: ReconcileVerdict) -> PaneVerdict {
+    PaneVerdict {
+        pane_key: pane.pane_key.clone(),
+        verdict,
+        terminal_id: None,
+        session_ref: None,
+        corrected: None,
+        reason: None,
+        retry_after_ms: None,
+        duplicate: None,
+    }
+}
+
+pub fn verdict_for_pane(snapshot: Option<&FreshAgentReconcileSnapshot>, pane: &ReconcilePane) -> PaneVerdict {
+    let Some(snapshot) = snapshot else {
+        // Capability not negotiated: the frozen client keeps today's contract.
+        let mut v = base(pane, ReconcileVerdict::Invalid);
+        v.reason = Some("unsupported_kind".into());
+        return v;
+    };
+    let Some(sref) = pane.session_ref.clone() else {
+        let mut v = base(pane, ReconcileVerdict::Fresh);
+        v.reason = Some("no_recoverable_identity".into());
+        return v;
+    };
+    let Some(facts) = snapshot.facts.get(&pane.pane_key) else {
+        let mut v = base(pane, ReconcileVerdict::Fresh);
+        v.reason = Some("no_recoverable_identity".into());
+        return v;
+    };
+    if let Some(winner) = &facts.duplicate_of {
+        let mut v = base(pane, ReconcileVerdict::Fresh);
+        v.reason = Some("duplicate_session_claim".into());
+        v.duplicate = Some(winner.clone());
+        return v;
+    }
+    match facts.presence {
+        FreshAgentPresence::Live => {
+            let mut v = base(pane, ReconcileVerdict::Attach);
+            v.session_ref = Some(sref);
+            v
+        }
+        FreshAgentPresence::OnDisk | FreshAgentPresence::Unknown => {
+            if facts.respawn_exhausted {
+                let mut v = base(pane, ReconcileVerdict::DeadSession);
+                v.reason = Some("respawn_exhausted".into());
+                v.session_ref = Some(sref);
+                v
+            } else {
+                let mut v = base(pane, ReconcileVerdict::Respawn);
+                v.session_ref = Some(sref);
+                v
+            }
+        }
+        FreshAgentPresence::GoneObserved => {
+            let mut v = base(pane, ReconcileVerdict::DeadSession);
+            v.reason = Some("session_not_on_disk".into());
+            v.session_ref = Some(sref);
+            v
+        }
+        FreshAgentPresence::NeverObserved => {
+            let mut v = base(pane, ReconcileVerdict::Fresh);
+            v.reason = Some("identity_never_observed".into());
+            v
+        }
+    }
+}
+```
+
+(Import paths: mirror whatever `reconcile.rs` uses for `PaneVerdict`/`ReconcileVerdict`/`ReconcilePane` — they live in `server_messages.rs`/`client_messages.rs` re-exports. The tiny private `base` constructor is deliberately duplicated from `reconcile.rs:68` rather than making B1's helpers pub.)
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-ws reconcile_freshagent`
+Expected: PASS (9 unit tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-ws/src/reconcile_freshagent.rs crates/freshell-ws/src/lib.rs
+git commit -m "feat(ws): reconcile_freshagent - pure fresh-agent verdict mapping with dedupe + respawn cap"
+```
+
+---
+
+### Task 13: Snapshot builder, `has_live_session`, dispatch arm, integration tests
+
+**Files:**
+- Modify: `crates/freshell-ws/src/reconcile_freshagent.rs` (builder), `crates/freshell-ws/src/terminal.rs` (`handle_pane_reconcile`), `crates/freshell-ws/src/lib.rs` (`WsState` field), `crates/freshell-ws/src/reconcile.rs` (ONE field + ONE arm + invert one unit test — nothing else)
+- Modify: `crates/freshell-freshagent/src/codex.rs`, `opencode_ws.rs`, `claude.rs` (one `has_live_session` method each)
+- Test: `crates/freshell-ws/tests/pane_reconcile_freshagent.rs` (extend)
+
+**Interfaces:**
+- Consumes: `SessionExistenceProbe` (`crates/freshell-ws/src/existence.rs:23-44`, READ-ONLY — B1 owns the file): `enum SessionExistence { Present, Absent, Unknown }`; sync `fn exists(&self, provider: &str, session_id: &str) -> SessionExistence` and `fn ever_observed(&self, provider: &str, session_id: &str) -> bool`. `PaneLedger::ever_bound`. Task 12 types. `ReconcileDeps` (`reconcile.rs:28-32`: `registry`, `identity`, `existence`), built at `terminal.rs:1932-1936`.
+- Produces:
+  - `pub async fn FreshCodexState::has_live_session(&self, session_id: &str) -> bool` (map contains id AND `!exited.load(SeqCst)`), `pub async fn FreshOpencodeState::has_live_session(&self, session_id: &str) -> bool` (sessions map contains the durable key — it is keyed by placeholder AND durable id, `opencode_ws.rs:96`), `pub async fn FreshClaudeState::has_live_session(&self, session_id: &str) -> bool` (`cli_index` durable → mapkey → sessions contains, `claude.rs:81-86`).
+  - `pub async fn reconcile_freshagent::build_snapshot(state: &WsState, panes: &[ReconcilePane]) -> FreshAgentReconcileSnapshot`.
+  - `WsState.fresh_agent_respawn_counts: std::sync::Arc<std::sync::Mutex<std::collections::HashMap<(String, String), u32>>>` (per-boot, in-memory).
+  - `ReconcileDeps.fresh_agent: Option<&'a FreshAgentReconcileSnapshot>`.
+
+- [ ] **Step 1: Write the failing integration tests**
+
+Extend `crates/freshell-ws/tests/pane_reconcile_freshagent.rs`. Add a scripted probe (the trait is public in freshell-ws) and pass it into `spawn_server` (extend the donor's `spawn_server` to accept a probe + a real temp-root `PaneLedger`, exposing both on the returned `Server` — same pattern as it already exposes `registry`/`identity`):
+
+```rust
+#[derive(Default)]
+struct StubProbe {
+    answers: std::sync::Mutex<std::collections::HashMap<(String, String), freshell_ws::existence::SessionExistence>>,
+    observed: std::sync::Mutex<std::collections::HashSet<(String, String)>>,
+}
+impl freshell_ws::existence::SessionExistenceProbe for StubProbe {
+    fn exists(&self, provider: &str, session_id: &str) -> freshell_ws::existence::SessionExistence {
+        self.answers.lock().unwrap()
+            .get(&(provider.into(), session_id.into()))
+            .copied()
+            .unwrap_or(freshell_ws::existence::SessionExistence::Unknown)
+    }
+    fn ever_observed(&self, provider: &str, session_id: &str) -> bool {
+        self.observed.lock().unwrap().contains(&(provider.into(), session_id.into()))
+    }
+}
+
+#[tokio::test]
+async fn fresh_agent_verdicts_cover_the_four_states() {
+    let probe = std::sync::Arc::new(StubProbe::default());
+    probe.answers.lock().unwrap().insert(("codex".into(), "resumable".into()), SessionExistence::Present);
+    probe.answers.lock().unwrap().insert(("claude".into(), "deleted".into()), SessionExistence::Absent);
+    probe.observed.lock().unwrap().insert(("claude".into(), "deleted".into()));
+    probe.answers.lock().unwrap().insert(("opencode".into(), "never".into()), SessionExistence::Absent);
+    let server = spawn_server_with_probe(probe).await;
+    let (mut ws, _ready) = connect(&server.url, true, true).await;
+    let verdicts = reconcile_request(&mut ws, serde_json::json!([
+        { "paneKey": "a", "kind": "fresh-agent", "sessionRef": {"provider": "codex", "sessionId": "resumable"} },
+        { "paneKey": "b", "kind": "fresh-agent", "sessionRef": {"provider": "claude", "sessionId": "deleted"} },
+        { "paneKey": "c", "kind": "fresh-agent", "sessionRef": {"provider": "opencode", "sessionId": "never"} },
+        { "paneKey": "d", "kind": "fresh-agent" }
+    ])).await;
+    assert_eq!(verdicts[0]["verdict"], "respawn", "killed-server-but-resumable");
+    assert_eq!(verdicts[0]["sessionRef"]["sessionId"], "resumable");
+    assert_eq!(verdicts[1]["verdict"], "dead_session", "transcript deleted");
+    assert_eq!(verdicts[1]["reason"], "session_not_on_disk");
+    assert_eq!(verdicts[2]["verdict"], "fresh", "never existed");
+    assert_eq!(verdicts[2]["reason"], "identity_never_observed");
+    assert_eq!(verdicts[3]["verdict"], "fresh");
+    assert_eq!(verdicts[3]["reason"], "no_recoverable_identity");
+    // terminal panes in the same request still work (mixed-kind request):
+}
+
+#[tokio::test]
+async fn live_fresh_agent_session_gets_attach() {
+    // Donor: crates/freshell-ws/tests/freshagent_claude_attach.rs — spawn the
+    // server with FRESHELL_CLAUDE_SIDECAR pointing at its fake sidecar script,
+    // drive freshAgent.create over the WS, await sdk.session.init / the
+    // created frame carrying the cliSessionId, THEN:
+    let verdicts = reconcile_request(&mut ws, serde_json::json!([
+        { "paneKey": "live", "kind": "fresh-agent",
+          "sessionRef": {"provider": "claude", "sessionId": cli_session_id} }
+    ])).await;
+    assert_eq!(verdicts[0]["verdict"], "attach");
+    assert_eq!(verdicts[0]["sessionRef"]["sessionId"], cli_session_id);
+    assert!(verdicts[0].get("terminalId").is_none());
+}
+
+#[tokio::test]
+async fn duplicate_session_claims_dedupe_within_one_request() {
+    // probe: ("codex","t1") Present
+    let verdicts = reconcile_request(&mut ws, serde_json::json!([
+        { "paneKey": "first",  "kind": "fresh-agent", "sessionRef": {"provider": "codex", "sessionId": "t1"} },
+        { "paneKey": "second", "kind": "fresh-agent", "sessionRef": {"provider": "codex", "sessionId": "t1"} }
+    ])).await;
+    assert_eq!(verdicts[0]["verdict"], "respawn");
+    assert_eq!(verdicts[1]["verdict"], "fresh");
+    assert_eq!(verdicts[1]["reason"], "duplicate_session_claim");
+    assert_eq!(verdicts[1]["duplicate"], "first");
+}
+
+#[tokio::test]
+async fn respawn_cap_turns_the_fourth_answer_into_dead_session() {
+    // probe: ("codex","cap") Present; 4 sequential single-pane requests:
+    for i in 0..4 {
+        let verdicts = reconcile_request(&mut ws, serde_json::json!([
+            { "paneKey": "p", "kind": "fresh-agent", "sessionRef": {"provider": "codex", "sessionId": "cap"} }
+        ])).await;
+        if i < 3 {
+            assert_eq!(verdicts[0]["verdict"], "respawn", "answer {i}");
+        } else {
+            assert_eq!(verdicts[0]["verdict"], "dead_session");
+            assert_eq!(verdicts[0]["reason"], "respawn_exhausted");
+        }
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test -p freshell-ws --test pane_reconcile_freshagent`
+Expected: COMPILE ERROR first (`spawn_server_with_probe`, `has_live_session` missing), then after harness plumbing: verdicts come back `invalid/unsupported_kind` — the arm doesn't exist yet.
+
+- [ ] **Step 3: Implement**
+
+(a) `has_live_session` on the three provider states (signatures in Interfaces; bodies are two-line map lookups under the states' own locks — for codex also require `!session.exited.load(std::sync::atomic::Ordering::SeqCst)`).
+
+(b) `WsState` field `fresh_agent_respawn_counts` (type above, `Default`-initialized). Fix every `WsState { … }` literal the compiler flags (main.rs, `tests/pane_reconcile.rs`, `tests/common/mod.rs`, other test files) with `fresh_agent_respawn_counts: Default::default()`.
+
+(c) `build_snapshot` in `reconcile_freshagent.rs`:
+
+```rust
+pub async fn build_snapshot(
+    state: &crate::WsState,
+    panes: &[ReconcilePane],
+) -> FreshAgentReconcileSnapshot {
+    let mut facts = std::collections::HashMap::new();
+    let mut claimed: std::collections::HashMap<(String, String), String> = std::collections::HashMap::new();
+    for pane in panes.iter().filter(|p| p.kind.as_deref() == Some("fresh-agent")) {
+        let Some(sref) = pane.session_ref.as_ref() else { continue }; // verdict fn answers no_recoverable_identity
+        let key = (sref.provider.clone(), sref.session_id.clone());
+        if let Some(winner) = claimed.get(&key) {
+            facts.insert(pane.pane_key.clone(), FreshAgentPaneFacts {
+                presence: FreshAgentPresence::Unknown,
+                duplicate_of: Some(winner.clone()),
+                respawn_exhausted: false,
+            });
+            continue;
+        }
+        claimed.insert(key.clone(), pane.pane_key.clone());
+        let live = match sref.provider.as_str() {
+            "codex" => state.fresh_codex.has_live_session(&sref.session_id).await,
+            "claude" => state.fresh_claude.has_live_session(&sref.session_id).await,
+            "opencode" => state.fresh_opencode.has_live_session(&sref.session_id).await,
+            _ => false,
+        };
+        use crate::existence::SessionExistence as E;
+        let presence = if live {
+            FreshAgentPresence::Live
+        } else {
+            match state.session_existence.exists(&sref.provider, &sref.session_id) {
+                E::Present => FreshAgentPresence::OnDisk,
+                E::Absent => {
+                    if state.session_existence.ever_observed(&sref.provider, &sref.session_id) {
+                        FreshAgentPresence::GoneObserved
+                    } else {
+                        FreshAgentPresence::NeverObserved
+                    }
+                }
+                E::Unknown => {
+                    // The ledger is positive evidence the session existed.
+                    if state.pane_ledger.ever_bound(&sref.provider, &sref.session_id) {
+                        FreshAgentPresence::OnDisk
+                    } else {
+                        FreshAgentPresence::Unknown
+                    }
+                }
+            }
+        };
+        let respawn_exhausted = if matches!(presence, FreshAgentPresence::OnDisk | FreshAgentPresence::Unknown) {
+            let mut counts = state.fresh_agent_respawn_counts.lock().expect("respawn counts poisoned");
+            let c = counts.entry(key).or_insert(0);
+            *c += 1;
+            *c > FRESH_AGENT_RESPAWN_CAP
+        } else {
+            false
+        };
+        facts.insert(pane.pane_key.clone(), FreshAgentPaneFacts { presence, duplicate_of: None, respawn_exhausted });
+    }
+    FreshAgentReconcileSnapshot { facts }
+}
+```
+
+(Adapt the `state.pane_ledger` access to how `WsState` actually holds the ledger — direct field per `pane_ledger: :476` in main.rs wiring. Cap semantics: each respawn-candidate ANSWER burns one attempt per (provider, sessionId) per boot; after `FRESH_AGENT_RESPAWN_CAP` answers, `dead_session{respawn_exhausted}` — mirroring the terminal wall's protection so a client stuck in a respawn loop cannot spin forever.)
+
+(d) `terminal.rs` `handle_pane_reconcile` (before the `catch_unwind` at `:1932`):
+
+```rust
+let fresh_agent_snapshot = if pane_reconcile_fresh_agent_v1
+    && request.panes.iter().any(|p| p.kind.as_deref() == Some("fresh-agent"))
+{
+    Some(crate::reconcile_freshagent::build_snapshot(state, &request.panes).await)
+} else {
+    None
+};
+```
+
+and add `fresh_agent: fresh_agent_snapshot.as_ref()` to the `ReconcileDeps` literal.
+
+(e) `reconcile.rs` — the WHOLE diff (plus the field):
+
+```rust
+// in ReconcileDeps:
+    pub fresh_agent: Option<&'a crate::reconcile_freshagent::FreshAgentReconcileSnapshot>,
+
+// in verdict_for_pane's kind match (before the Some(_) arm):
+        Some("fresh-agent") => {
+            return crate::reconcile_freshagent::verdict_for_pane(deps.fresh_agent, pane)
+        }
+```
+
+and invert the inline unit test at `reconcile.rs:545-550` that used the literal `"fresh-agent"` as its `unsupported_kind` negative example — switch its kind to `"browser"` (still unsupported) so it keeps guarding the same contract. Any other `ReconcileDeps` literals in reconcile.rs unit tests gain `fresh_agent: None`. NOTHING ELSE in reconcile.rs changes (B1 owns it; a trivial merge conflict at the arm is expected and fine). Update the `kind` doc comment at `client_messages.rs:361` (`/// v1: "terminal" only …`) to mention `"fresh-agent"` behind `paneReconcileFreshAgentV1`.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-ws && cargo test -p freshell-freshagent && cargo test -p freshell-server`
+Expected: PASS — all new integration tests, all existing reconcile tests (including `tests/pane_reconcile.rs` and protocol tests) still green.
+
+- [ ] **Step 5: Commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-ws crates/freshell-freshagent crates/freshell-server
+git commit -m "feat(ws): fresh-agent panes enter the reconcile verdict system behind paneReconcileFreshAgentV1 (P1.13 §4.3)"
+```
+
+---
+
+### Task 14: E2E — settings survive restart (3 providers) + codex crash degradation banner
+
+**Files:**
+- Modify: `test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs` (crash knob)
+- Create: `test/e2e-browser/specs/freshagent-settings-resume-rust.spec.ts`
+- Modify: `test/e2e-browser/playwright.config.ts` (add the spec to BOTH `RUST_ONLY_SPECS` (~line 90) and the `rust-chromium` project `testMatch` (~line 250))
+
+**Interfaces:**
+- Consumes: `RustServer` (`test/e2e-browser/helpers/rust-server.ts`): `start()`, `restartAbrupt()` (SIGKILL + reboot on same home/port/token), `{env, setupHome}` options. `bootWall(page, {env, setupHome})` from the wall spec's helper pattern. Fakes: `CODEX_CMD="node <fake-app-server.mjs>"` + `FAKE_CODEX_APP_SERVER_BEHAVIOR` (JSON, supports `appendThreadOperationLogPath` → JSONL `{method, threadId, params}`); `OPENCODE_CMD` + `FAKE_OPENCODE_AUDIT_LOG`; `FRESHELL_CLAUDE_SIDECAR` + `FAKE_CLAUDE_SIDECAR_LOG` (JSONL of every inbound message). REST agent API: `POST /api/tabs` with `agent`/`model`/`effort` params; `POST /api/panes/:id/send-keys`.
+- Primary donor spec: `test/e2e-browser/specs/freshclaude-restart-parity-rust.spec.ts:212-310` — copy its boot, pane-creation, send, restart, and re-attach patterns verbatim; the NEW content of each test is its final assertion block, given below in full.
+
+- [ ] **Step 1: Add the crash knob to the codex fake (test infra, no prod code)**
+
+In `fake-app-server.mjs`, where inbound prompt/turn requests are handled, honor a new behavior field:
+
+```js
+// behavior.crashOnPromptMarker: if the inbound turn text contains this
+// marker, hard-exit to simulate a sidecar crash mid-session.
+if (behavior.crashOnPromptMarker && promptText.includes(behavior.crashOnPromptMarker)) {
+  process.exit(1);
+}
+```
+
+- [ ] **Step 2: Write the four e2e tests (they fail against pre-fix behavior only where the fix is server-side; write them to assert the FIXED contract)**
+
+`freshagent-settings-resume-rust.spec.ts` — one `test.describe` with four tests, each booting its own `RustServer` on an ephemeral port with the provider's fake wired via env (donor patterns), each cleaning up in `finally`/`afterEach`:
+
+1. **`codex: restart → attach resumes with the user's model, not defaults`**
+   - Boot with `CODEX_CMD` fake + behavior including `appendThreadOperationLogPath: <tmp>/codex-ops.jsonl` and a resume-succeeds script.
+   - Create a codex fresh-agent pane WITH an explicit model (donor pane-creation pattern; if the creation surface in the donor doesn't carry model, use the REST agent API: `POST ${baseUrl}/api/tabs` with `{ agent: 'codex', model: 'gpt-5.3-codex' }` and the auth token).
+   - Send one message; wait for the reply (donor wait pattern).
+   - `await server.restartAbrupt()`; `await page.reload()`; wait for the pane to re-attach (donor wait).
+   - Assertion block:
+   ```ts
+   const ops = fs.readFileSync(opLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
+   const resume = ops.find((o) => o.method === 'thread/resume')
+   expect(resume, 'restart must resume the durable thread').toBeTruthy()
+   expect(resume.params.model, 'resume must carry the recorded model, not null').toBe('gpt-5.3-codex')
+   ```
+   (Sandbox/permissionMode reapplication is pinned at the Rust layer in Task 5 — the creation surface here only carries `model`/`effort`.)
+
+2. **`opencode: restart → attach → next send carries the recorded model/effort`**
+   - Boot with `OPENCODE_CMD` fake + `FAKE_OPENCODE_AUDIT_LOG`.
+   - Create an opencode pane with `{ agent: 'opencode', model: 'big-model', effort: 'high' }`; send once (materializes `ses_*`); `restartAbrupt()`; reload; wait for re-attach; send a second message.
+   - Assertion block:
+   ```ts
+   const audit = fs.readFileSync(auditLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
+   const prompts = audit.filter((e) => e.path && String(e.path).includes('/message')) // the prompt_async POSTs (match the fake's actual audit shape)
+   const afterRestart = prompts[prompts.length - 1]
+   expect(JSON.stringify(afterRestart), 'post-restart send must carry the recorded model').toContain('big-model')
+   expect(JSON.stringify(afterRestart), 'post-restart send must carry the recorded effort').toContain('high')
+   ```
+
+3. **`claude: restart → attach resume request carries model/permissionMode`**
+   - Boot with `FRESHELL_CLAUDE_SIDECAR` fake + `FAKE_CLAUDE_SIDECAR_LOG` (exactly the donor's env, `rust-server.ts` + donor `:212-310`).
+   - Create a freshclaude pane with an explicit model (donor creation; REST `{ agent: 'claude', model: 'opus-x' }` if the donor path doesn't carry model); send once; `restartAbrupt()`; reload; wait for the resume (donor wait — it already proves transcript parity).
+   - Assertion block:
+   ```ts
+   const msgs = fs.readFileSync(sidecarLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
+   const resumeCreate = msgs.filter((m) => m.msg && m.msg.resumeSessionId).pop()
+   expect(resumeCreate, 'restart must issue a resume create').toBeTruthy()
+   expect(resumeCreate.msg.model, 'resume must carry the recorded model, not null').toBe('opus-x')
+   ```
+
+4. **`codex: crash respawn shows a visible memory-loss notice`**
+   - Boot with the codex fake, behavior `{ crashOnPromptMarker: 'CRASH_NOW', … }` and a follow-up behavior (rewritten between spawns, as the Rust tests do via the behavior file) whose `thread/resume` answers not-found so the respawn mints a new thread.
+   - Create a codex pane; send `CRASH_NOW` (sidecar exits); send another message (triggers crash-recovery respawn).
+   - Assertion block:
+   ```ts
+   const banner = page.getByRole('alert').filter({ hasText: 'no longer has memory' })
+   await expect(banner, 'memory loss must be user-visible, not just a server warn').toBeVisible({ timeout: 15000 })
+   ```
+
+- [ ] **Step 3: Register the spec and run it**
+
+Add `'freshagent-settings-resume-rust.spec.ts'` to `RUST_ONLY_SPECS` and the `rust-chromium` `testMatch` in `playwright.config.ts`.
+
+Run: `npx playwright test --config test/e2e-browser/playwright.config.ts --project=rust-chromium freshagent-settings-resume-rust`
+Expected: ALL FOUR PASS (the server-side fixes landed in Tasks 4-10/13). If a test fails, that is a real defect in the preceding tasks — fix the production code, not the assertion.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs \
+        test/e2e-browser/specs/freshagent-settings-resume-rust.spec.ts \
+        test/e2e-browser/playwright.config.ts
+git commit -m "test(e2e): per-provider settings survive restart + codex crash memory-loss banner (P1.13)"
+```
+
+---
+
+### Task 15: Restore-contract-wall pin flip + full gates
+
+**Files:**
+- Modify: `test/e2e-browser/specs/restore-contract-wall-rust.spec.ts`
+
+**Interfaces:**
+- Consumes: the P1.13-tagged pin at `:1017-1020` inside test `freshopencode: SIGKILL restore keeps the ses_* identity and rehydrates history` (`:1001`): `test.fail(e2eServerKind === 'rust', 'P1.8/P1.13 (§2.7): post-reload freshopencode pane re-mints a freshopencode-* placeholder instead of rebinding the surviving ses_* session')`. Pin-flip discipline: a flip DELETES the `test.fail(...)` line (Playwright makes unexpected-pass a hard failure); if the test still fails for a reason OUTSIDE this lane (client folding is next wave), NARROW the reason instead (the `9dc032b7` flavor) — never widen. The aggregate RULER pin (`:1333`, `:1339-1357`) is NOT flipped by this lane.
+
+- [ ] **Step 1: Run the pinned test as-is**
+
+```bash
+npx playwright test --config test/e2e-browser/playwright.config.ts \
+  --project=rust-chromium restore-contract-wall-rust -g "freshopencode: SIGKILL restore keeps"
+```
+
+- If it reports an UNEXPECTED PASS (the pin now fails the run): the server-side fixes flipped it — go to Step 2a.
+- If it still fails inside the pin: read the failure; if the residual cause is client-side re-mint folding (next wave's scope), go to Step 2b.
+
+- [ ] **Step 2a: Flip — delete the pin**
+
+Delete the `test.fail(e2eServerKind === 'rust', 'P1.8/P1.13 …')` line (and its `EXPECTED-FAIL WALL PIN` comment block's stale reason — replace the comment with a dated `HISTORY:` note: fixed by this lane's settings-from-ledger resume, per the flip pattern in `restore-matrix.spec.ts:1695-1716`). Re-run the command from Step 1. Expected: PASS.
+
+- [ ] **Step 2b: Narrow — server side fixed, client folding pending**
+
+Update the pin's reason string to: `'P1.8 (§2.7, client folding — next wave): server resume now reapplies the ledger record (P1.13 done); post-reload client still re-mints a freshopencode-* placeholder'` and update the pin comment's dated observation + FLIP clause to name the client-folding lane. Re-run Step 1's command; expected: the pinned test is an expected failure (suite green).
+
+- [ ] **Step 3: Full verification gates**
+
+```bash
+cargo fmt --all --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
+npm run test:status   # wait politely if a sibling holds the gate
+FRESHELL_TEST_SUMMARY="B4 freshagent-verdicts-resume full gate" env -u FRESHELL_BIND_HOST npm test
+npx playwright test --config test/e2e-browser/playwright.config.ts --project=rust-chromium \
+  freshagent-settings-resume-rust restore-contract-wall-rust freshclaude-restart-parity-rust
+```
+Expected: everything green (wall pins that are not ours remain expected-fails).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
+git commit -m "test(wall): flip/narrow P1.13 freshopencode settings pin - fresh-agent resume record live"
+```
+
+---
+
+## Verification Summary (what proves the user stories)
+
+| Requirement (spec) | Proving test |
+|---|---|
+| Ledger rows at codex thread/start, opencode session.materialized (+pending before), claude sdk.session.init | Tasks 4/7/9 Rust tests |
+| Resume-invocation record persisted + updated on user change (§4.2) | Task 1 round-trip; Task 7 `send_with_changed_settings_refreshes_the_binding` |
+| Codex resume-after-restart runs with user's model/sandbox (defect §2.6c) | Task 5 wire-level op-log test + Task 14 e2e test 1 |
+| Opencode resume keeps model/effort/cwd (defect §2.7b) | Task 8 Rust test + Task 14 e2e test 2 |
+| Claude resume keeps model/permissionMode/effort | Task 10 spawn-log test + Task 14 e2e test 3 |
+| "settings reset — reconfirm" breadcrumb = missing-record ALARM only | Tasks 5/8/10 SETTINGS_RESET alarm tests (frame emitted ONLY when the record is absent) |
+| reconcile accepts kind:fresh-agent with attach/respawn/dead_session/fresh | Task 12 unit + Task 13 direct-WS tests (live / killed-resumable / transcript-deleted / never-existed) |
+| Dedupe + respawn caps for fresh agents | Task 13 `duplicate_session_claims…` + `respawn_cap_turns_the_fourth…` |
+| Capability-gated; frozen client unaffected | Task 11 `without_the_capability…` (permanent regression guard) |
+| Codex crash-respawn degradation frame, user-visible TODAY | Task 6 broadcast test + Task 14 e2e banner test |
+| Flip P1.13-tagged wall pins this lane fixes | Task 15 |

From e0a56172610b8740a4bfbc0877134f7d8202522a Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 02:31:14 -0700
Subject: [PATCH 03/87] docs: add implementation plan for recover-my-panes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lane B3 (campaign P1.9 + kata h9vt resolution): user-facing browser-loss
recovery surface. Plan covers the GET /api/recovery/inventory read API
(snapshots union + pane-ledger join), the client offer panel with
boot-captured trigger eligibility, ledger-authority-chain recreation,
the browser-loss e2e, and deletion of the operator restore endpoint +
marker/fence machinery (h9vt Option A disposition).

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 docs/plans/2026-07-26-recover-my-panes.md | 1270 +++++++++++++++++++++
 1 file changed, 1270 insertions(+)
 create mode 100644 docs/plans/2026-07-26-recover-my-panes.md

diff --git a/docs/plans/2026-07-26-recover-my-panes.md b/docs/plans/2026-07-26-recover-my-panes.md
new file mode 100644
index 000000000..8f9d8d90e
--- /dev/null
+++ b/docs/plans/2026-07-26-recover-my-panes.md
@@ -0,0 +1,1270 @@
+# Recover My Panes Implementation Plan
+
+> **For agentic workers:** This plan is executed task-by-task by the
+> workflow's execute stage: a fresh implementer per task, with a spec +
+> quality review after each task. Steps use checkbox (`- [ ]`) syntax
+> for tracking.
+
+**Goal:** When a browser connects with no local layout while the server holds recoverable state (pane-identity ledger bindings and/or tabs-snapshots), offer the user "Restore N panes from server memory?" — accept recreates the panes (snapshot = layout, ledger = identity per the §4.2 authority chain), decline is remembered. This resolves campaign item P1.9 and kata h9vt.
+
+**Architecture:** A new authenticated `GET /api/recovery/inventory` endpoint (axum, `crates/freshell-server/src/recovery_inventory.rs`) joins the newest tabs-snapshot generation union (excluding the requesting client's own pushes) with pane-ledger bindings and returns a recoverable inventory. The client captures "had persisted layout at boot" at module load, fetches the inventory when eligible, and shows a self-gating offer panel; accept recreates tabs client-side through the existing `addTab` + `restoreLayout` path (the same path `reopenClosedTab` uses). The operator-only `POST /api/tabs-sync/restore` endpoint and its marker/fence machinery are deleted (kata h9vt Option A disposition, see below).
+
+**Tech Stack:** Rust (axum 0.8, tokio, serde_json), React 18 + Redux Toolkit + Vitest/Testing Library, Playwright e2e with owned `RustServer` instances.
+
+## Kata h9vt Disposition (decided during planning — state in the final report)
+
+**Option A — the tabs-snapshots store becomes load-bearing.** Snapshots are the only durable source of *layout* (the ledger has identity but no layout; localStorage is exactly what's lost in the browser-loss scenario), so ledger-only recovery (Option B) cannot restore tabs/splits/cwd — the store stays.
+
+Within Option A, per the directive "reuse what serves the UI flow, DELETE what doesn't":
+- **REUSED:** the write path (`tabs_persist.rs`, untouched), and the read selectors (`list_snapshot_devices`, `read_device_overview`, `read_generations_union_by_ids`) which feed the new inventory endpoint.
+- **DELETED (Task 9):** `POST /api/tabs-sync/restore`, the write-ahead marker module (`tabs_snapshots_marker.rs`), the exactly-one-browser gate, the screenshot delivery-fence (explicitly flagged for deletion — an unreachable fence is context poison), `scripts/restore-tabs.sh`, and `tabs_snapshots_create_body.rs`. Rationale: all of that machinery exists to make a *blind server-push* to an operator-invisible browser safe. The UI flow is client-driven — the client fetches the inventory and recreates panes itself through the normal create path — so there is no server-push, no ambiguous target browser, nothing for a marker or fence to protect.
+
+## Design Decisions
+
+**D1 — Trigger conditions (Principle 4 compliance).** The offer appears iff ALL of:
+1. `localStorage` had NO layout key (`freshell.layout.v3` and `freshell.layout.v3.bak` both absent) **captured at module load**, before the auto-shell-tab (`App.tsx:1423-1427`) and the 500 ms persist debounce can write one — OR a pending-offer flag from a prior undecided visit is set (see D3).
+2. `GET /api/recovery/inventory` reports `recoverable: true`.
+3. The inventory `contentId` is not in the dismissed list.
+
+Consequences: *empty-never* and *empty-cleared* browsers (both have no layout key) get the offer — correct, both are genuinely new-browser situations. *Same-browser reload with intact localStorage* (key present) never sees the offer — even if the user deliberately closed all tabs (key present, zero tabs). Principle 4 ("never ask when we can act") is not violated: an empty client layout gives the server no client claim to adjudicate; silently materializing another device's layout onto a possibly-brand-new user's browser would be "silently wrong," so offering is the correct reading (the campaign plan's §4.4 itself says "offer"). `serverInstanceId` is NOT part of the trigger — snapshots and the ledger persist across restarts, and `restoreLayout` strips live-attach fields anyway.
+
+**D2 — Self-pollution filter.** A fresh browser context mints a fresh per-window `clientInstanceId` (sessionStorage) and starts pushing snapshots (auto shell tab) within seconds. The inventory request carries `?clientInstanceId=<current>`; the server excludes that client's generations when building each device union, so the requester's own junk pushes never appear as "recoverable." (A fresh browser also mints a fresh `deviceId`, so its pushes usually land in a different device dir — the filter covers the selective-clear case where the deviceId survived.)
+
+**D3 — Dismissal + pending persistence.** Decline writes the inventory `contentId` to `localStorage["freshell.recovery.dismissed.v1"]` (array, capped at 20). While the offer is shown but undecided, `localStorage["freshell.recovery.pending.v1"] = contentId` so a reload mid-decision (which by then has a persisted auto-tab layout) re-offers instead of silently losing the recovery chance; accept/decline clears it.
+
+**D4 — Authority chain (§4.2): ledger identity beats snapshot claim.** For each snapshot pane with a `sessionRef`, the server joins the ledger and reports a verdict; the client uses `effectiveSessionRef`:
+- ledger row chain (following `supersededBy`, max 10 hops) ends at a `bound` row → resume the **ledger's** `{provider, sessionId}` (snapshot claim overridden).
+- row `retired` with reason `gc_expired` (no live successor) → keep the snapshot ref (the server attach path adjudicates revival — `pane_ledger_auto_resume`).
+- row `retired` with reason `closed` → no resume; recreate a fresh pane in the same cwd/mode.
+- no ledger row (e.g. fresh-agent sessions — the ledger has no rows for them) → the snapshot claim stands.
+
+Bound ledger rows referenced by **no** snapshot pane are returned as `ledgerOnly` and recreated in an extra "Recovered sessions" tab, so ledger-known sessions are never dropped just because layout was lost.
+
+**D5 — Recreation path.** Accept dispatches, per inventory tab: `addTab({id: nanoid(), title: tabName})` then `restoreLayout({tabId, layout, paneTitles})` — the exact path `reopenClosedTab` already exercises. `restoreLayout` re-mints `createRequestId`/`status` and strips `terminalId`, so after dispatch we read the post-normalization layout back from the store and arm terminal restore via `addTerminalRestoreRequestId(...)` for every terminal leaf carrying a `sessionRef` (the `App.tsx:1069` / `terminal-restore.ts` pattern) so the create goes out as a restore. Terminal panes get the D4 treatment; non-terminal kinds (`browser`, `editor`, `fresh-agent`, `extension`, `picker`) are recreated by passing the snapshot pane payload through as content (`{kind, ...payload}`) — the same normalize/strip path handles them, exactly as it does for `reopenClosedTab`. The auto-created empty shell tab from `App.tsx:1423` is left in place (deliberate: removing it would touch tab-lifecycle code other lanes own; it is one empty shell tab).
+
+**D6 — Snapshot records have no split geometry** (flat `panes[]` per tab record), so recreation builds a right-leaning binary split chain (`direction: 'horizontal'`, `sizes: [50, 50]`) — panes come back, geometry is a default. This is what the store contains; not a deferral.
+
+## Global Constraints
+
+- Worktree: `/home/dan/code/freshell/.worktrees/recover-my-panes`, branch `feat/recover-my-panes`, base `origin/main@2dfbba58`. All commands below run from the worktree root.
+- Rust: `cargo fmt --all` clean; `cargo clippy --workspace --all-targets -- -D warnings` green (required CI); `cargo test --workspace` green.
+- Client: `npm run lint` green (jsx-a11y is a CI requirement); coordinated suites via `env -u FRESHELL_BIND_HOST npm test` (waits on the shared coordinator gate — WAIT if held, never kill a foreign holder; set `FRESHELL_TEST_SUMMARY="recover-my-panes lane B3"`); focused runs via `npm run test:vitest -- run <paths> [--config config/vitest/vitest.server.config.ts where noted]`.
+- E2E: own `RustServer` instances on `findFreePort()` ephemeral ports — NEVER 3001/3002. Never restart the user's self-hosted server; never use broad kill patterns. ~78 GB disk — halt on ENOSPC.
+- SCOPE FENCE — do NOT touch: `src/lib/ws-client.ts`; `App.tsx` regions 811-898, 900-981, 1002-1090, 1283-1325 (Lane B1); `crates/*/src/**/reconcile*` (B1); codex_candidate/locator (B2); `crates/freshell-freshagent/` (B4); the `tabs_persist.rs` WRITE path (read-only consumption is fine). No kimi/gemini work.
+- Node test files use ESM: relative imports include `.js` extensions.
+- PR policy: push the branch, STOP before `gh pr create`. Final report must state the kata h9vt disposition (Option A, restore endpoint + marker/fence deleted).
+- Commit after every task with the trailer:
+
+```
+🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)
+
+Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
+```
+
+## File Structure
+
+| File | Responsibility |
+|---|---|
+| `crates/freshell-server/src/recovery_inventory.rs` (create) | Pure inventory builder + axum router/handler for `GET /api/recovery/inventory` |
+| `crates/freshell-server/src/recovery_inventory_tests.rs` (create) | Sibling test module (house convention) |
+| `crates/freshell-server/src/main.rs` (modify) | `mod recovery_inventory;` + one `.merge(...)` |
+| `crates/freshell-server/src/tabs_snapshots.rs` (modify, Task 9) | Restore endpoint deleted; file shrinks to whatever the read side still needs |
+| `crates/freshell-server/src/tabs_snapshots_marker.rs`, `tabs_snapshots_create_body.rs`, `tabs_snapshots_selectors.rs` (delete, Task 9) | Server-push machinery — no UI-flow consumer |
+| `scripts/restore-tabs.sh` (delete, Task 9) | Operator curl wrapper for the deleted endpoint |
+| `src/lib/recovery/boot-state.ts` (create) | Boot-time "had persisted layout" capture |
+| `src/lib/recovery/dismissal.ts` (create) | Dismissed/pending localStorage persistence |
+| `src/lib/recovery/types.ts` (create) | `RecoveryInventory` TS types |
+| `src/lib/recovery/build-recovery-plan.ts` (create) | Pure inventory → (addTab payload, PaneNode layout) mapping incl. authority chain |
+| `src/lib/api.ts` (modify) | `getRecoveryInventory` helper |
+| `src/store/tabRegistrySync.ts` (modify) | Export the existing module-private clientInstanceId getter |
+| `src/components/RecoveryOfferPanel.tsx` (create) | Self-gating offer panel (fetch, render, accept/decline) |
+| `src/App.tsx` (modify) | One JSX line in a distinct `LANE B3` region next to `SetupWizard` (~line 1347-1362) |
+| `test/unit/client/lib/recovery/*.test.ts` (create) | Unit tests for boot-state, dismissal, build-recovery-plan |
+| `test/unit/client/components/RecoveryOfferPanel.test.tsx` (create) | Component tests |
+| `test/e2e-browser/specs/recover-my-panes-rust.spec.ts` (create) | The browser-loss recovery e2e |
+
+---
+
+### Task 1: Server — pure inventory builder
+
+**Files:**
+- Create: `crates/freshell-server/src/recovery_inventory.rs`
+- Create: `crates/freshell-server/src/recovery_inventory_tests.rs`
+- Modify: `crates/freshell-server/src/main.rs` (add `mod recovery_inventory;` only)
+
+**Interfaces:**
+- Consumes: `freshell_ws::pane_ledger::BindingRow` (fields serialize camelCase: `provider`, `sessionId`, `mode`, `cwd`, `state: bound|retired`, `retiredReason?: superseded|closed|gc_expired`, `supersededBy?: {provider, sessionId}`, `updatedAt`). Snapshot union doc shape (from `tabs_persist.rs`): `{deviceId, deviceLabel, capturedAt, records: [{tabKey, tabId, tabName, revision, updatedAt, paneCount, panes: [{paneId, kind, payload: {mode?, shell?, initialCwd?, sessionRef?: {provider, sessionId}, createRequestId?, ...}}]}]}`.
+- Produces: `pub struct DeviceUnion { pub device_id: String, pub union_doc: serde_json::Value }` and `pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow>) -> serde_json::Value` returning:
+
+```json
+{
+  "recoverable": true,
+  "contentId": "9f3a1c2e00112233",
+  "device": {
+    "deviceId": "dev1", "deviceLabel": "Dan's laptop", "capturedAt": 1000,
+    "tabs": [
+      { "tabKey": "k1", "tabName": "work",
+        "panes": [
+          { "paneId": "p1", "kind": "terminal", "mode": "claude", "shell": null,
+            "cwd": "/home/dan/proj", "payload": { "...": "verbatim snapshot payload" },
+            "sessionRef": { "provider": "claude", "sessionId": "S2" },
+            "ledgerState": "bound" }
+        ] }
+    ]
+  },
+  "otherDevices": [ { "deviceId": "dev0", "deviceLabel": "old", "capturedAt": 500, "paneCount": 3 } ],
+  "ledgerOnly": [ { "provider": "codex", "sessionId": "C9", "mode": "codex", "cwd": "/x" } ]
+}
+```
+
+Rules encoded: `device` = the union with the greatest `capturedAt` that has ≥1 record; every pane's `sessionRef` in the response is the **effective** ref per Design Decision D4 (`ledgerState` ∈ `bound|closed|gc_expired|unknown`; `closed` ⇒ `sessionRef: null`); `ledgerOnly` = `state == bound` rows whose `(provider, sessionId)` matches no effective pane ref in the primary device; `contentId` = hex of `std::hash::DefaultHasher` over the sorted list of `<deviceId>:<capturedAt>` for all unions plus sorted `<provider>:<sessionId>:<updatedAt>` for all bound rows (`DefaultHasher::new()` is deterministic across runs); `recoverable` = primary device exists OR `ledgerOnly` non-empty. Empty input ⇒ `{"recoverable": false, "contentId": "...", "device": null, "otherDevices": [], "ledgerOnly": []}`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `crates/freshell-server/src/recovery_inventory_tests.rs`. Use the sibling-module house convention. Construct `BindingRow` values directly (import from `freshell_ws::pane_ledger`; use its real field/enum names — open that file to copy them; e.g. if state is an enum use `BindingState::Bound`). Test bodies:
+
+```rust
+use super::*;
+use serde_json::json;
+
+fn union_doc(device: &str, captured_at: u64, panes: serde_json::Value) -> serde_json::Value {
+    json!({
+        "deviceId": device, "deviceLabel": format!("label-{device}"), "capturedAt": captured_at,
+        "records": [{ "tabKey": "k1", "tabId": "t1", "tabName": "work", "revision": 1,
+                      "updatedAt": captured_at, "paneCount": 1, "panes": panes }]
+    })
+}
+
+#[test]
+fn empty_inputs_not_recoverable() {
+    let out = build_inventory(vec![], vec![]);
+    assert_eq!(out["recoverable"], false);
+    assert!(out["device"].is_null());
+    assert_eq!(out["ledgerOnly"].as_array().unwrap().len(), 0);
+}
+
+#[test]
+fn newest_device_wins_others_summarized() {
+    let old = DeviceUnion { device_id: "dev0".into(), union_doc: union_doc("dev0", 500, json!([{ "paneId": "p0", "kind": "terminal", "payload": {"mode": "shell"} }])) };
+    let new = DeviceUnion { device_id: "dev1".into(), union_doc: union_doc("dev1", 1000, json!([{ "paneId": "p1", "kind": "terminal", "payload": {"mode": "shell", "initialCwd": "/w"} }])) };
+    let out = build_inventory(vec![old, new], vec![]);
+    assert_eq!(out["recoverable"], true);
+    assert_eq!(out["device"]["deviceId"], "dev1");
+    assert_eq!(out["device"]["tabs"][0]["panes"][0]["cwd"], "/w");
+    assert_eq!(out["otherDevices"][0]["deviceId"], "dev0");
+    assert_eq!(out["otherDevices"][0]["paneCount"], 1);
+}
+
+#[test]
+fn ledger_bound_row_overrides_snapshot_claim_via_superseded_chain() {
+    // snapshot says S1; ledger: S1 retired(superseded -> S2), S2 bound
+    let d = DeviceUnion { device_id: "dev1".into(), union_doc: union_doc("dev1", 1000,
+        json!([{ "paneId": "p1", "kind": "terminal",
+                 "payload": { "mode": "claude", "sessionRef": { "provider": "claude", "sessionId": "S1" } } }])) };
+    let bindings = vec![
+        binding_row("claude", "S1", retired_superseded_by("claude", "S2")),
+        binding_row("claude", "S2", bound()),
+    ];
+    let out = build_inventory(vec![d], bindings);
+    let pane = &out["device"]["tabs"][0]["panes"][0];
+    assert_eq!(pane["ledgerState"], "bound");
+    assert_eq!(pane["sessionRef"]["sessionId"], "S2"); // ledger identity beat the snapshot claim
+    assert_eq!(out["ledgerOnly"].as_array().unwrap().len(), 0); // S2 is referenced, not ledger-only
+}
+
+#[test]
+fn closed_row_strips_resume_gc_expired_keeps_snapshot_ref_unknown_passes_through() {
+    let d = DeviceUnion { device_id: "dev1".into(), union_doc: union_doc("dev1", 1000, json!([
+        { "paneId": "p1", "kind": "terminal", "payload": { "mode": "claude", "sessionRef": { "provider": "claude", "sessionId": "CLOSED" } } },
+        { "paneId": "p2", "kind": "terminal", "payload": { "mode": "codex",  "sessionRef": { "provider": "codex",  "sessionId": "EXPIRED" } } },
+        { "paneId": "p3", "kind": "fresh-agent", "payload": { "sessionRef": { "provider": "freshclaude", "sessionId": "NOROW" } } }
+    ])) };
+    let bindings = vec![
+        binding_row("claude", "CLOSED", retired_closed()),
+        binding_row("codex", "EXPIRED", retired_gc_expired()),
+    ];
+    let out = build_inventory(vec![d], bindings);
+    let panes = out["device"]["tabs"][0]["panes"].as_array().unwrap();
+    assert_eq!(panes[0]["ledgerState"], "closed");
+    assert!(panes[0]["sessionRef"].is_null());
+    assert_eq!(panes[1]["ledgerState"], "gc_expired");
+    assert_eq!(panes[1]["sessionRef"]["sessionId"], "EXPIRED");
+    assert_eq!(panes[2]["ledgerState"], "unknown");
+    assert_eq!(panes[2]["sessionRef"]["sessionId"], "NOROW");
+}
+
+#[test]
+fn unreferenced_bound_rows_become_ledger_only() {
+    let out = build_inventory(vec![], vec![binding_row("codex", "C9", bound())]);
+    assert_eq!(out["recoverable"], true);
+    assert_eq!(out["ledgerOnly"][0]["sessionId"], "C9");
+}
+
+#[test]
+fn content_id_is_stable_and_input_sensitive() {
+    let a = build_inventory(vec![], vec![binding_row("codex", "C9", bound())]);
+    let b = build_inventory(vec![], vec![binding_row("codex", "C9", bound())]);
+    let c = build_inventory(vec![], vec![binding_row("codex", "C8", bound())]);
+    assert_eq!(a["contentId"], b["contentId"]);
+    assert_ne!(a["contentId"], c["contentId"]);
+}
+```
+
+Write small local helpers `binding_row(provider, session_id, state_parts)`, `bound()`, `retired_closed()`, `retired_gc_expired()`, `retired_superseded_by(p, s)` that construct real `BindingRow` values (copy field names/enums from `crates/freshell-ws/src/pane_ledger.rs:93`; fill required timestamps with constants like `1000`).
+
+Create `crates/freshell-server/src/recovery_inventory.rs` containing ONLY the types + an `unimplemented!()`-free stub that compiles but returns `json!(null)`, plus the test include:
+
+```rust
+#[cfg(test)]
+#[path = "recovery_inventory_tests.rs"]
+mod tests;
+```
+
+Add `mod recovery_inventory;` to `main.rs` (mirror how `mod tabs_snapshots;` is declared).
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test -p freshell-server recovery_inventory -- --nocapture`
+Expected: FAIL — assertions fail against the `null` stub (compilation must succeed; assertion failure is the red).
+
+- [ ] **Step 3: Implement `build_inventory`**
+
+In `recovery_inventory.rs`:
+
+```rust
+use std::collections::HashMap;
+use std::hash::{DefaultHasher, Hash, Hasher};
+use freshell_ws::pane_ledger::BindingRow;
+use serde_json::{json, Value};
+
+pub struct DeviceUnion { pub device_id: String, pub union_doc: Value }
+
+fn ref_key(provider: &str, session_id: &str) -> String { format!("{provider}\u{1}{session_id}") }
+
+enum Verdict { Bound(String, String), Closed, GcExpired, Unknown }
+
+fn resolve(provider: &str, session_id: &str, by_key: &HashMap<String, &BindingRow>) -> Verdict {
+    let (mut p, mut s) = (provider.to_string(), session_id.to_string());
+    for _ in 0..10 {
+        match by_key.get(&ref_key(&p, &s)) {
+            None => return if (p.as_str(), s.as_str()) == (provider, session_id) { Verdict::Unknown } else { Verdict::GcExpired },
+            Some(row) if row_is_bound(row) => return Verdict::Bound(row_provider(row), row_session_id(row)),
+            Some(row) => match row_successor(row) {
+                Some((np, ns)) => { p = np; s = ns; }
+                None => return if row_reason_is_closed(row) { Verdict::Closed } else { Verdict::GcExpired },
+            },
+        }
+    }
+    Verdict::GcExpired
+}
+
+pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow>) -> Value {
+    let by_key: HashMap<String, &BindingRow> = bindings.iter()
+        .map(|r| (ref_key(&row_provider(r), &row_session_id(r)), r)).collect();
+
+    // contentId over ALL inputs (stable, order-independent)
+    let mut ids: Vec<String> = device_unions.iter()
+        .map(|d| format!("{}:{}", d.device_id, d.union_doc["capturedAt"])).collect();
+    ids.extend(bindings.iter().filter(|r| row_is_bound(r))
+        .map(|r| format!("{}:{}:{}", row_provider(r), row_session_id(r), row_updated_at(r))));
+    ids.sort();
+    let mut h = DefaultHasher::new();
+    ids.hash(&mut h);
+    let content_id = format!("{:016x}", h.finish());
+
+    // pick primary device: greatest capturedAt with >=1 record
+    let mut unions = device_unions;
+    unions.sort_by_key(|d| std::cmp::Reverse(d.union_doc["capturedAt"].as_u64().unwrap_or(0)));
+    let primary_idx = unions.iter().position(|d|
+        d.union_doc["records"].as_array().map(|r| !r.is_empty()).unwrap_or(false));
+
+    let mut referenced: Vec<String> = vec![];
+    let device = primary_idx.map(|i| {
+        let doc = &unions[i].union_doc;
+        let tabs: Vec<Value> = doc["records"].as_array().unwrap().iter().map(|rec| {
+            let panes: Vec<Value> = rec["panes"].as_array().cloned().unwrap_or_default().iter().map(|pane| {
+                let payload = &pane["payload"];
+                let snap_ref = payload.get("sessionRef").filter(|v| !v.is_null()).cloned();
+                let (ledger_state, eff_ref) = match &snap_ref {
+                    None => ("unknown", None),
+                    Some(r) => {
+                        let (p, s) = (r["provider"].as_str().unwrap_or(""), r["sessionId"].as_str().unwrap_or(""));
+                        match resolve(p, s, &by_key) {
+                            Verdict::Bound(bp, bs) => ("bound", Some(json!({"provider": bp, "sessionId": bs}))),
+                            Verdict::Closed => ("closed", None),
+                            Verdict::GcExpired => ("gc_expired", Some(r.clone())),
+                            Verdict::Unknown => ("unknown", Some(r.clone())),
+                        }
+                    }
+                };
+                if let Some(er) = &eff_ref {
+                    referenced.push(ref_key(er["provider"].as_str().unwrap_or(""), er["sessionId"].as_str().unwrap_or("")));
+                }
+                json!({
+                    "paneId": pane["paneId"], "kind": pane["kind"],
+                    "mode": payload.get("mode").cloned().unwrap_or(Value::Null),
+                    "shell": payload.get("shell").cloned().unwrap_or(Value::Null),
+                    "cwd": payload.get("initialCwd").cloned().unwrap_or(Value::Null),
+                    "payload": payload.clone(),
+                    "sessionRef": eff_ref.unwrap_or(Value::Null),
+                    "ledgerState": ledger_state,
+                })
+            }).collect();
+            json!({"tabKey": rec["tabKey"], "tabName": rec["tabName"], "panes": panes})
+        }).collect();
+        json!({"deviceId": doc["deviceId"], "deviceLabel": doc["deviceLabel"],
+               "capturedAt": doc["capturedAt"], "tabs": tabs})
+    });
+
+    let other_devices: Vec<Value> = unions.iter().enumerate()
+        .filter(|(i, _)| Some(*i) != primary_idx)
+        .filter(|(_, d)| d.union_doc["records"].as_array().map(|r| !r.is_empty()).unwrap_or(false))
+        .map(|(_, d)| {
+            let pane_count: u64 = d.union_doc["records"].as_array().unwrap().iter()
+                .map(|r| r["panes"].as_array().map(|p| p.len() as u64).unwrap_or(0)).sum();
+            json!({"deviceId": d.union_doc["deviceId"], "deviceLabel": d.union_doc["deviceLabel"],
+                   "capturedAt": d.union_doc["capturedAt"], "paneCount": pane_count})
+        }).collect();
+
+    let ledger_only: Vec<Value> = bindings.iter()
+        .filter(|r| row_is_bound(r))
+        .filter(|r| !referenced.contains(&ref_key(&row_provider(r), &row_session_id(r))))
+        .map(|r| json!({"provider": row_provider(r), "sessionId": row_session_id(r),
+                        "mode": row_mode(r), "cwd": row_cwd(r)}))
+        .collect();
+
+    let recoverable = device.is_some() || !ledger_only.is_empty();
+    json!({"recoverable": recoverable, "contentId": content_id,
+           "device": device.unwrap_or(Value::Null),
+           "otherDevices": other_devices, "ledgerOnly": ledger_only})
+}
+```
+
+The `row_*` accessor helpers (`row_provider`, `row_session_id`, `row_is_bound`, `row_reason_is_closed`, `row_successor`, `row_mode`, `row_cwd`, `row_updated_at`) are thin one-line wrappers over the actual `BindingRow` fields/enums — write them against the real definitions in `pane_ledger.rs:93` (they exist so this module compiles against whatever the exact enum spellings are; each is a single field access, not logic).
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-server recovery_inventory`
+Expected: PASS (all 6 tests).
+
+- [ ] **Step 5: Format, lint, commit**
+
+```bash
+cargo fmt --all && cargo clippy -p freshell-server --all-targets -- -D warnings
+git add crates/freshell-server/src/recovery_inventory.rs crates/freshell-server/src/recovery_inventory_tests.rs crates/freshell-server/src/main.rs
+git commit -m "feat(server): pure recovery-inventory builder joining snapshots with pane-ledger (B3/P1.9)"
+```
+
+---
+
+### Task 2: Server — `GET /api/recovery/inventory` route
+
+**Files:**
+- Modify: `crates/freshell-server/src/recovery_inventory.rs` (add state/router/handler)
+- Modify: `crates/freshell-server/src/recovery_inventory_tests.rs` (add route tests)
+- Modify: `crates/freshell-server/src/main.rs` (one `.merge(...)` in the router assembly at ~`main.rs:759+`)
+
+**Interfaces:**
+- Consumes: `freshell_ws::tabs_persist::{list_snapshot_devices, read_device_overview, read_generations_union_by_ids}` (sync `io::Result`, must run in `spawn_blocking`); `freshell_ws::pane_ledger::PaneLedger::list_bindings()` (sync, memory-only, callable directly); the per-handler auth helper used by `tabs_snapshots.rs` handlers (`is_authed(&headers, &state.auth_token)` — copy the exact import from that file); `build_inventory` from Task 1.
+- Produces: `pub struct RecoveryInventoryState { pub auth_token: String, pub snapshots_dir: Option<std::path::PathBuf>, pub ledger: std::sync::Arc<freshell_ws::pane_ledger::PaneLedger> }` (`#[derive(Clone)]`) and `pub fn router(state: RecoveryInventoryState) -> axum::Router`. Route: `GET /api/recovery/inventory?clientInstanceId=<id>`.
+
+Handler behavior: 401 without valid token (same check as every other handler); with `snapshots_dir: None` or missing dir → inventory built from ledger only; snapshot reads: `spawn_blocking` over `(dir, exclude_client)` doing — `list_snapshot_devices(&dir)` → for each device `read_device_overview(&dir, &device)` → from the overview's generation list select generation ids whose `clientInstanceId` != `exclude_client` → `read_generations_union_by_ids(&dir, &device, &ids)` → collect `DeviceUnion`. Devices with zero foreign generations are skipped. IO errors and `JoinError` → 500 + `tracing::error!` (fail-loud, three-arm match, same shape as the dryRun path at `tabs_snapshots.rs:330`). Then `build_inventory(unions, state.ledger.list_bindings())` → `Json(...)`.
+
+- [ ] **Step 1: Write the failing route tests**
+
+Append to `recovery_inventory_tests.rs` (reuse the `oneshot` helper pattern from `tabs_snapshots_tests.rs:79` — a `async fn get(router, uri, auth) -> (StatusCode, Value)` helper using `tower::ServiceExt::oneshot`). Snapshot fixture files are written directly with the store's real layout — `<dir>/<device>/<client>-<capturedAt:020>-r<rev:012>.json` (alphanumeric device/client ids need no escaping):
+
+```rust
+fn write_snapshot(dir: &std::path::Path, device: &str, client: &str, captured_at: u64, rev: u64, records: serde_json::Value) {
+    let doc = json!({
+        "deviceId": device, "deviceLabel": format!("label-{device}"), "clientInstanceId": client,
+        "serverInstanceId": "srv-test", "snapshotRevision": rev, "capturedAt": captured_at,
+        "records": records
+    });
+    let d = dir.join(device);
+    std::fs::create_dir_all(&d).unwrap();
+    std::fs::write(d.join(format!("{client}-{captured_at:020}-r{rev:012}.json")),
+                   serde_json::to_vec(&doc).unwrap()).unwrap();
+}
+
+fn test_state(dir: Option<std::path::PathBuf>, ledger_root: Option<std::path::PathBuf>) -> RecoveryInventoryState {
+    RecoveryInventoryState {
+        auth_token: "tok".into(),
+        snapshots_dir: dir,
+        ledger: std::sync::Arc::new(freshell_ws::pane_ledger::PaneLedger::new_locked(ledger_root)),
+    }
+}
+
+#[tokio::test]
+async fn route_requires_auth_and_serves_inventory() {
+    let tmp = tempfile::tempdir().unwrap();
+    write_snapshot(tmp.path(), "dev1", "clientA", 1000, 1, json!([
+        {"tabKey":"k1","tabId":"t1","tabName":"work","status":"open","revision":1,"updatedAt":1000,
+         "paneCount":1,"panes":[{"paneId":"p1","kind":"terminal","payload":{"mode":"shell","initialCwd":"/w"}}]}
+    ]));
+    let router = router(test_state(Some(tmp.path().to_path_buf()), None));
+    // house convention: 401 case asserted alongside the happy path
+    let (code, _) = get(router.clone(), "/api/recovery/inventory?clientInstanceId=me", None).await;
+    assert_eq!(code, axum::http::StatusCode::UNAUTHORIZED);
+    let (code, body) = get(router, "/api/recovery/inventory?clientInstanceId=me", Some("tok")).await;
+    assert_eq!(code, axum::http::StatusCode::OK);
+    assert_eq!(body["recoverable"], true);
+    assert_eq!(body["device"]["deviceId"], "dev1");
+    assert_eq!(body["device"]["tabs"][0]["panes"][0]["cwd"], "/w");
+}
+
+#[tokio::test]
+async fn route_excludes_requesting_clients_own_generations() {
+    let tmp = tempfile::tempdir().unwrap();
+    write_snapshot(tmp.path(), "dev1", "oldclient", 1000, 1, json!([
+        {"tabKey":"k1","tabId":"t1","tabName":"work","status":"open","revision":1,"updatedAt":1000,
+         "paneCount":1,"panes":[{"paneId":"p1","kind":"terminal","payload":{"mode":"shell"}}]}
+    ]));
+    write_snapshot(tmp.path(), "dev1", "me", 2000, 1, json!([
+        {"tabKey":"junk","tabId":"tj","tabName":"junk","status":"open","revision":1,"updatedAt":2000,
+         "paneCount":1,"panes":[{"paneId":"pj","kind":"terminal","payload":{"mode":"shell"}}]}
+    ]));
+    let router = router(test_state(Some(tmp.path().to_path_buf()), None));
+    let (_, body) = get(router, "/api/recovery/inventory?clientInstanceId=me", Some("tok")).await;
+    let tabs = body["device"]["tabs"].as_array().unwrap();
+    assert!(tabs.iter().all(|t| t["tabKey"] != "junk"), "requester's own push must be filtered out");
+    assert!(tabs.iter().any(|t| t["tabKey"] == "k1"));
+}
+
+#[tokio::test]
+async fn route_serves_ledger_only_recovery_without_snapshots() {
+    // Seed a binding file the ledger boot-scan will load (BindingRow camelCase JSON).
+    let home = tempfile::tempdir().unwrap();
+    let broot = home.path().join("pane-ledger");
+    std::fs::create_dir_all(broot.join("bindings").join("claude")).unwrap();
+    std::fs::write(broot.join("bindings").join("claude").join("S1.json"), serde_json::to_vec(&json!({
+        "ledgerVersion": 1, "provider": "claude", "sessionId": "S1", "mode": "claude",
+        "cwd": "/w", "createdAt": 1, "updatedAt": 1, "lastObservedAt": 1, "state": "bound"
+    })).unwrap()).unwrap();
+    let router = router(test_state(None, Some(broot)));
+    let (_, body) = get(router, "/api/recovery/inventory?clientInstanceId=me", Some("tok")).await;
+    assert_eq!(body["recoverable"], true);
+    assert_eq!(body["ledgerOnly"][0]["sessionId"], "S1");
+}
+```
+
+(If the on-disk binding filename/JSON differs, copy the exact shape from `pane_ledger_tests.rs` fixtures — the test contract stands: a pre-seeded bound row surfaces in `ledgerOnly`.)
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test -p freshell-server recovery_inventory`
+Expected: FAIL to compile on missing `router`/`RecoveryInventoryState` — add compiling stubs (handler returns 500) — then FAIL on assertions.
+
+- [ ] **Step 3: Implement state, router, handler**
+
+```rust
+use axum::{extract::{Query, State}, http::HeaderMap, response::{IntoResponse, Response}, routing::get, Json, Router};
+
+#[derive(Clone)]
+pub struct RecoveryInventoryState {
+    pub auth_token: String,
+    pub snapshots_dir: Option<std::path::PathBuf>,
+    pub ledger: std::sync::Arc<freshell_ws::pane_ledger::PaneLedger>,
+}
+
+#[derive(serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct InventoryQuery { client_instance_id: Option<String> }
+
+pub fn router(state: RecoveryInventoryState) -> Router {
+    Router::new().route("/api/recovery/inventory", get(inventory_handler)).with_state(state)
+}
+
+async fn inventory_handler(State(state): State<RecoveryInventoryState>, headers: HeaderMap, Query(q): Query<InventoryQuery>) -> Response {
+    if !is_authed(&headers, &state.auth_token) { return unauthorized(); } // same helper as tabs_snapshots.rs
+    let exclude = q.client_instance_id.unwrap_or_default();
+    let unions = match state.snapshots_dir.clone() {
+        None => vec![],
+        Some(dir) => {
+            let job = tokio::task::spawn_blocking(move || read_foreign_unions(&dir, &exclude));
+            match job.await {
+                Ok(Ok(u)) => u,
+                Ok(Err(e)) => { tracing::error!(error = %e, "recovery inventory snapshot read failed"); return internal_error(); }
+                Err(e) => { tracing::error!(error = %e, "recovery inventory join failed"); return internal_error(); }
+            }
+        }
+    };
+    Json(build_inventory(unions, state.ledger.list_bindings())).into_response()
+}
+
+fn read_foreign_unions(dir: &std::path::Path, exclude_client: &str) -> std::io::Result<Vec<DeviceUnion>> {
+    use freshell_ws::tabs_persist::{list_snapshot_devices, read_device_overview, read_generations_union_by_ids};
+    let mut out = vec![];
+    if !dir.is_dir() { return Ok(out); }
+    for device in list_snapshot_devices(dir)? {
+        let Some((_, generations)) = read_device_overview(dir, &device)? else { continue };
+        let foreign: Vec<String> = generations.iter()
+            .filter(|g| g["clientInstanceId"].as_str() != Some(exclude_client))
+            .filter_map(|g| g["generationId"].as_str().map(String::from))
+            .collect();
+        if foreign.is_empty() { continue; }
+        match read_generations_union_by_ids(dir, &device, &foreign) {
+            Ok(union) => out.push(DeviceUnion { device_id: device, union_doc: union_value(union) }),
+            Err(e) => return Err(e),
+        }
+    }
+    Ok(out)
+}
+```
+
+Notes for the implementer: `unauthorized()`/`internal_error()`/`is_authed` — import or replicate exactly what `tabs_snapshots.rs` handlers use (auth check is the first statement, constant-time compare, `x-auth-token` header then cookie). `read_generations_union_by_ids` returns a `ComponentsUnion` — `union_value(...)` is whatever accessor yields the union `Value` (see how the restore endpoint consumes it); if `Missing` is a variant, treat as skip-device. If the overview generation entries name the id field differently (e.g. `id`), match the actual field — the Step 1 tests, driven by real files, are the arbiter.
+
+Wire in `main.rs` next to the existing `tabs_snapshots` merge (~`:783-795`):
+
+```rust
+.merge(recovery_inventory::router(recovery_inventory::RecoveryInventoryState {
+    auth_token: auth_token.clone(),
+    snapshots_dir: tabs_snapshots_dir.clone(),          // same value the tabs_snapshots state receives
+    ledger: std::sync::Arc::clone(&pane_ledger),        // created at main.rs:426
+}))
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-server recovery_inventory`
+Expected: PASS (all route + builder tests).
+
+- [ ] **Step 5: Full crate check, commit**
+
+```bash
+cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings && cargo test -p freshell-server
+git add -A crates/freshell-server/src
+git commit -m "feat(server): GET /api/recovery/inventory - device-scoped recoverable-state read API (B3/P1.9)"
+```
+
+---
+
+### Task 3: Client — boot eligibility + dismissal persistence
+
+**Files:**
+- Create: `src/lib/recovery/boot-state.ts`
+- Create: `src/lib/recovery/dismissal.ts`
+- Create: `test/unit/client/lib/recovery/boot-state.test.ts`
+- Create: `test/unit/client/lib/recovery/dismissal.test.ts`
+
+**Interfaces:**
+- Consumes: `window.localStorage` (jsdom provides it in tests; clear it yourself — `console.error` throws in `afterEach`).
+- Produces:
+  - `boot-state.ts`: `export function computeHadPersistedLayout(storage: Pick<Storage, 'getItem'>): boolean` and `export const hadPersistedLayoutAtBoot: boolean` (evaluated at module import).
+  - `dismissal.ts`: `export function isDismissed(contentId: string): boolean`, `export function recordDismissal(contentId: string): void` (cap 20, newest kept), `export function getPendingOffer(): string | null`, `export function setPendingOffer(contentId: string): void`, `export function clearPendingOffer(): void`.
+
+- [ ] **Step 1: Write the failing tests**
+
+`test/unit/client/lib/recovery/boot-state.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import { computeHadPersistedLayout } from '@/lib/recovery/boot-state'
+
+const store = (entries: Record<string, string>) => ({ getItem: (k: string) => entries[k] ?? null })
+
+describe('computeHadPersistedLayout', () => {
+  beforeEach(() => localStorage.clear())
+
+  it('empty-never: no layout keys at all -> false (offer-eligible)', () => {
+    expect(computeHadPersistedLayout(store({}))).toBe(false)
+  })
+
+  it('empty-cleared: only unrelated keys survive a clear -> false (offer-eligible)', () => {
+    expect(computeHadPersistedLayout(store({ 'freshell.device-id.v2': 'dev' }))).toBe(false)
+  })
+
+  it('populated: layout key present -> true (no offer)', () => {
+    expect(computeHadPersistedLayout(store({ 'freshell.layout.v3': '{"tabs":[{"id":"t1"}]}' }))).toBe(true)
+  })
+
+  it('deliberately emptied: layout key present with zero tabs -> true (no offer)', () => {
+    expect(computeHadPersistedLayout(store({ 'freshell.layout.v3': '{"tabs":[]}' }))).toBe(true)
+  })
+
+  it('backup key alone counts as persisted layout', () => {
+    expect(computeHadPersistedLayout(store({ 'freshell.layout.v3.bak': '{}' }))).toBe(true)
+  })
+})
+
+describe('hadPersistedLayoutAtBoot capture', () => {
+  it('is captured at module import time, before later writes', async () => {
+    localStorage.clear()
+    const { hadPersistedLayoutAtBoot } = await import('@/lib/recovery/boot-state?fresh=' + Date.now())
+    localStorage.setItem('freshell.layout.v3', '{"tabs":[{"id":"auto"}]}') // simulates auto-tab persist
+    expect(hadPersistedLayoutAtBoot).toBe(false)
+  })
+})
+```
+
+`test/unit/client/lib/recovery/dismissal.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import { isDismissed, recordDismissal, getPendingOffer, setPendingOffer, clearPendingOffer } from '@/lib/recovery/dismissal'
+
+describe('recovery dismissal persistence', () => {
+  beforeEach(() => localStorage.clear())
+
+  it('unknown contentId is not dismissed', () => expect(isDismissed('abc')).toBe(false))
+
+  it('recordDismissal persists across module state (localStorage-backed)', () => {
+    recordDismissal('abc')
+    expect(isDismissed('abc')).toBe(true)
+    expect(isDismissed('xyz')).toBe(false)
+  })
+
+  it('caps at 20, evicting oldest', () => {
+    for (let i = 0; i < 21; i++) recordDismissal(`id-${i}`)
+    expect(isDismissed('id-0')).toBe(false)
+    expect(isDismissed('id-20')).toBe(true)
+  })
+
+  it('tolerates corrupt stored JSON', () => {
+    localStorage.setItem('freshell.recovery.dismissed.v1', '{not json')
+    expect(isDismissed('abc')).toBe(false)
+    recordDismissal('abc')
+    expect(isDismissed('abc')).toBe(true)
+  })
+
+  it('pending offer round-trips and clears', () => {
+    expect(getPendingOffer()).toBeNull()
+    setPendingOffer('abc')
+    expect(getPendingOffer()).toBe('abc')
+    clearPendingOffer()
+    expect(getPendingOffer()).toBeNull()
+  })
+})
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npm run test:vitest -- run test/unit/client/lib/recovery/`
+Expected: FAIL — modules don't exist ("Failed to resolve import").
+
+- [ ] **Step 3: Implement both modules**
+
+`src/lib/recovery/boot-state.ts`:
+
+```ts
+const LAYOUT_KEY = 'freshell.layout.v3'
+const LAYOUT_BAK_KEY = 'freshell.layout.v3.bak'
+
+export function computeHadPersistedLayout(storage: Pick<Storage, 'getItem'>): boolean {
+  return storage.getItem(LAYOUT_KEY) !== null || storage.getItem(LAYOUT_BAK_KEY) !== null
+}
+
+// Captured at module import — before the auto-created shell tab and the 500ms
+// persist debounce can write a layout key (see docs/plans/2026-07-26-recover-my-panes.md D1).
+export const hadPersistedLayoutAtBoot: boolean =
+  typeof window !== 'undefined' && computeHadPersistedLayout(window.localStorage)
+```
+
+`src/lib/recovery/dismissal.ts` (same pattern as `src/lib/setup-wizard-dismissal.ts`):
+
+```ts
+const DISMISSED_KEY = 'freshell.recovery.dismissed.v1'
+const PENDING_KEY = 'freshell.recovery.pending.v1'
+const CAP = 20
+
+function readDismissed(): string[] {
+  try {
+    const raw = localStorage.getItem(DISMISSED_KEY)
+    const parsed = raw ? JSON.parse(raw) : []
+    return Array.isArray(parsed) ? parsed.filter((x) => typeof x === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+export function isDismissed(contentId: string): boolean {
+  return readDismissed().includes(contentId)
+}
+
+export function recordDismissal(contentId: string): void {
+  const next = [...readDismissed().filter((id) => id !== contentId), contentId].slice(-CAP)
+  localStorage.setItem(DISMISSED_KEY, JSON.stringify(next))
+}
+
+export function getPendingOffer(): string | null {
+  return localStorage.getItem(PENDING_KEY)
+}
+
+export function setPendingOffer(contentId: string): void {
+  localStorage.setItem(PENDING_KEY, contentId)
+}
+
+export function clearPendingOffer(): void {
+  localStorage.removeItem(PENDING_KEY)
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npm run test:vitest -- run test/unit/client/lib/recovery/`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/lib/recovery/boot-state.ts src/lib/recovery/dismissal.ts test/unit/client/lib/recovery/
+git commit -m "feat(client): recovery trigger eligibility (boot-captured) and dismissal persistence (B3/P1.9)"
+```
+
+---
+
+### Task 4: Client — inventory types, API helper, recovery-plan builder (authority chain)
+
+**Files:**
+- Create: `src/lib/recovery/types.ts`
+- Create: `src/lib/recovery/build-recovery-plan.ts`
+- Modify: `src/lib/api.ts` (add `getRecoveryInventory` next to `getBootstrap` at `api.ts:287-289`)
+- Create: `test/unit/client/lib/recovery/build-recovery-plan.test.ts`
+
+**Interfaces:**
+- Consumes: `PaneNode` / `TerminalPaneContent` from `@/store/paneTypes` (`PaneNode = leaf{id, content} | split{id, direction, children:[PaneNode,PaneNode], sizes:[number,number]}`, `paneTypes.ts:274-276`; terminal content fields incl. `initialCwd`, `sessionRef: {provider, sessionId}`, non-optional `createRequestId`/`status`); `nanoid`; `api.get` + `buildQueryString` (`api.ts:276-285`).
+- Produces:
+  - `types.ts`: `RecoveryInventory`, `RecoveryPane` (`{paneId, kind, mode: string|null, shell: string|null, cwd: string|null, payload: Record<string, unknown>, sessionRef: {provider, sessionId}|null, ledgerState: 'bound'|'closed'|'gc_expired'|'unknown'}`), `RecoveryTab`, `LedgerOnlyEntry` — mirroring Task 1's response shape.
+  - `api.ts`: `export async function getRecoveryInventory(clientInstanceId: string): Promise<RecoveryInventory>` → `api.get<RecoveryInventory>('/api/recovery/inventory' + buildQueryString({ clientInstanceId }))`.
+  - `build-recovery-plan.ts`:
+
+```ts
+export interface RecoveryTabPlan { tabId: string; title: string; layout: PaneNode; paneTitles: Record<string, string> }
+export function countRecoverablePanes(inv: RecoveryInventory): number
+export function buildRecoveryPlan(inv: RecoveryInventory): RecoveryTabPlan[]
+```
+
+Rules: one `RecoveryTabPlan` per inventory tab (tabId = `nanoid()`); pane list → right-leaning binary split chain (`direction: 'horizontal'`, `sizes: [50, 50]`); terminal leaf content `{kind:'terminal', createRequestId: nanoid(), status: 'creating', mode, shell, initialCwd: cwd, sessionRef: sessionRef ?? undefined}` (fields with `null` inventory values omitted; `restoreLayout` re-mints ids/status — that's expected); non-terminal leaf content = `{...payload, kind}` passthrough (the `reopenClosedTab` restore path normalizes it); `ledgerOnly` entries, if any, become one extra final tab titled `Recovered sessions` whose panes are terminal content with `mode: entry.mode`, `initialCwd: entry.cwd ?? undefined`, `sessionRef: {provider, sessionId}`. `countRecoverablePanes` = device panes + ledgerOnly length.
+
+- [ ] **Step 1: Write the failing tests**
+
+`test/unit/client/lib/recovery/build-recovery-plan.test.ts`:
+
+```ts
+import { describe, it, expect, vi } from 'vitest'
+import { buildRecoveryPlan, countRecoverablePanes } from '@/lib/recovery/build-recovery-plan'
+import type { RecoveryInventory } from '@/lib/recovery/types'
+
+vi.mock('nanoid', () => { let n = 0; return { nanoid: () => `nid-${++n}` } })
+
+const pane = (over: Partial<RecoveryInventory['device']['tabs'][0]['panes'][0]> = {}) => ({
+  paneId: 'p1', kind: 'terminal', mode: 'shell', shell: null, cwd: '/w',
+  payload: {}, sessionRef: null, ledgerState: 'unknown' as const, ...over,
+})
+const inv = (panes: unknown[], ledgerOnly: unknown[] = []): RecoveryInventory => ({
+  recoverable: true, contentId: 'cid',
+  device: { deviceId: 'd', deviceLabel: 'l', capturedAt: 1, tabs: [{ tabKey: 'k', tabName: 'work', panes }] },
+  otherDevices: [], ledgerOnly,
+} as RecoveryInventory)
+
+describe('buildRecoveryPlan', () => {
+  it('single terminal pane -> one tab, leaf layout, cwd + mode carried', () => {
+    const [tab] = buildRecoveryPlan(inv([pane()]))
+    expect(tab.title).toBe('work')
+    expect(tab.layout.type).toBe('leaf')
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content).toMatchObject({ kind: 'terminal', mode: 'shell', initialCwd: '/w' })
+    expect(content.sessionRef).toBeUndefined()
+  })
+
+  it('ledger-corrected sessionRef is used verbatim (authority chain applied server-side)', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ sessionRef: { provider: 'claude', sessionId: 'S2' }, ledgerState: 'bound', mode: 'claude' })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content.sessionRef).toEqual({ provider: 'claude', sessionId: 'S2' })
+  })
+
+  it('closed panes come back fresh: no sessionRef, same cwd/mode', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ ledgerState: 'closed', mode: 'claude' })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content.sessionRef).toBeUndefined()
+    expect(content).toMatchObject({ mode: 'claude', initialCwd: '/w' })
+  })
+
+  it('three panes -> right-leaning binary split chain', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ paneId: 'a' }), pane({ paneId: 'b' }), pane({ paneId: 'c' })]))
+    expect(tab.layout.type).toBe('split')
+    const root = tab.layout as { children: [{ type: string }, { type: string }] }
+    expect(root.children[0].type).toBe('leaf')
+    expect(root.children[1].type).toBe('split')
+  })
+
+  it('non-terminal kinds pass payload through', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ kind: 'browser', payload: { url: 'https://x.test' }, mode: null, cwd: null })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content).toMatchObject({ kind: 'browser', url: 'https://x.test' })
+  })
+
+  it('ledgerOnly entries get a trailing Recovered sessions tab', () => {
+    const plans = buildRecoveryPlan(inv([pane()], [{ provider: 'codex', sessionId: 'C9', mode: 'codex', cwd: '/x' }]))
+    expect(plans).toHaveLength(2)
+    expect(plans[1].title).toBe('Recovered sessions')
+    const content = (plans[1].layout as { content: Record<string, unknown> }).content
+    expect(content).toMatchObject({ kind: 'terminal', mode: 'codex', initialCwd: '/x', sessionRef: { provider: 'codex', sessionId: 'C9' } })
+  })
+
+  it('countRecoverablePanes sums device panes and ledgerOnly', () => {
+    expect(countRecoverablePanes(inv([pane(), pane({ paneId: 'p2' })], [{ provider: 'codex', sessionId: 'C9', mode: 'codex', cwd: null }]))).toBe(3)
+  })
+})
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npm run test:vitest -- run test/unit/client/lib/recovery/build-recovery-plan.test.ts`
+Expected: FAIL — module missing.
+
+- [ ] **Step 3: Implement types + builder + api helper**
+
+`src/lib/recovery/types.ts` per the Interfaces block above. `src/lib/recovery/build-recovery-plan.ts`:
+
+```ts
+import { nanoid } from 'nanoid'
+import type { PaneNode, PaneContent } from '@/store/paneTypes'
+import type { RecoveryInventory, RecoveryPane, LedgerOnlyEntry } from './types'
+
+function terminalContent(p: { mode: string | null; shell: string | null; cwd: string | null; sessionRef: { provider: string; sessionId: string } | null }): PaneContent {
+  return {
+    kind: 'terminal',
+    createRequestId: nanoid(), // re-minted by restoreLayout normalization; required by the type
+    status: 'creating',
+    ...(p.mode ? { mode: p.mode } : {}),
+    ...(p.shell ? { shell: p.shell } : {}),
+    ...(p.cwd ? { initialCwd: p.cwd } : {}),
+    ...(p.sessionRef ? { sessionRef: p.sessionRef } : {}),
+  } as PaneContent
+}
+
+function paneContent(p: RecoveryPane): PaneContent {
+  if (p.kind === 'terminal') return terminalContent(p)
+  return { ...p.payload, kind: p.kind } as PaneContent
+}
+
+function leaf(content: PaneContent): PaneNode {
+  return { type: 'leaf', id: nanoid(), content } as PaneNode
+}
+
+function chain(leaves: PaneNode[]): PaneNode {
+  if (leaves.length === 1) return leaves[0]
+  const [head, ...rest] = leaves
+  return { type: 'split', id: nanoid(), direction: 'horizontal', children: [head, chain(rest)], sizes: [50, 50] } as PaneNode
+}
+
+export interface RecoveryTabPlan { tabId: string; title: string; layout: PaneNode; paneTitles: Record<string, string> }
+
+export function countRecoverablePanes(inv: RecoveryInventory): number {
+  const device = inv.device?.tabs.reduce((n, t) => n + t.panes.length, 0) ?? 0
+  return device + inv.ledgerOnly.length
+}
+
+export function buildRecoveryPlan(inv: RecoveryInventory): RecoveryTabPlan[] {
+  const plans: RecoveryTabPlan[] = (inv.device?.tabs ?? [])
+    .filter((t) => t.panes.length > 0)
+    .map((t) => ({ tabId: nanoid(), title: t.tabName || 'Recovered', layout: chain(t.panes.map((p) => leaf(paneContent(p)))), paneTitles: {} }))
+  if (inv.ledgerOnly.length > 0) {
+    plans.push({
+      tabId: nanoid(),
+      title: 'Recovered sessions',
+      layout: chain(inv.ledgerOnly.map((e: LedgerOnlyEntry) =>
+        leaf(terminalContent({ mode: e.mode, shell: null, cwd: e.cwd, sessionRef: { provider: e.provider, sessionId: e.sessionId } })))),
+      paneTitles: {},
+    })
+  }
+  return plans
+}
+```
+
+In `src/lib/api.ts`, next to `getBootstrap`:
+
+```ts
+export async function getRecoveryInventory(clientInstanceId: string): Promise<RecoveryInventory> {
+  return api.get<RecoveryInventory>(`/api/recovery/inventory${buildQueryString({ clientInstanceId })}`)
+}
+```
+
+(Import the type; match `getBootstrap`'s exact call style including any options argument.)
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npm run test:vitest -- run test/unit/client/lib/recovery/`
+Expected: PASS. Also run `npx tsc --noEmit -p tsconfig.json` if a typecheck script isn't already part of `npm run check`; fix type mismatches against the real `paneTypes.ts` definitions (the casts above are the seam — prefer removing casts by matching the real types).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/lib/recovery/ src/lib/api.ts test/unit/client/lib/recovery/build-recovery-plan.test.ts
+git commit -m "feat(client): recovery inventory types, API helper, and recovery-plan builder honoring the ledger authority chain (B3/P1.9)"
+```
+
+---
+
+### Task 5: Client — RecoveryOfferPanel component (fetch, offer, accept, decline)
+
+**Files:**
+- Create: `src/components/RecoveryOfferPanel.tsx`
+- Modify: `src/store/tabRegistrySync.ts` (export the existing module-private clientInstanceId getter — a 2-line visibility change, e.g. `export function getClientInstanceId(): string` wrapping what the push envelope already uses; do not change its behavior)
+- Create: `test/unit/client/components/RecoveryOfferPanel.test.tsx`
+
+**Interfaces:**
+- Consumes: `hadPersistedLayoutAtBoot`, dismissal module (Task 3), `getRecoveryInventory` (Task 4), `buildRecoveryPlan`/`countRecoverablePanes` (Task 4), `addTab` (`tabsSlice.ts:274-290` — payload accepts `id`; `activeTabId` set unconditionally), `restoreLayout` (`panesSlice.ts:910-926` — no-ops if the tab already has a layout), `addTerminalRestoreRequestId` (`src/lib/terminal-restore.ts`), `getClientInstanceId`.
+- Produces: `export function RecoveryOfferPanel(): JSX.Element | null` — fully self-gating (no props), rendered unconditionally from App. Also `export function armRecoveredTerminalRestores(state: RootState, tabIds: string[]): void` — walks each tab's post-normalization layout in `state.panes`, and for every terminal leaf whose content has a `sessionRef`, calls `addTerminalRestoreRequestId(content.createRequestId)`.
+
+Behavior:
+1. On mount: if `(hadPersistedLayoutAtBoot && !getPendingOffer())` → render null forever. Otherwise fetch `getRecoveryInventory(getClientInstanceId())` once; on error or `recoverable: false` or `isDismissed(contentId)` → render null; else `setPendingOffer(contentId)` and show the panel.
+2. Panel (modal-style, reuse the portal/overlay/focus pattern of `src/components/ui/confirm-modal.tsx`): heading `Restore N panes from server memory?` (N = `countRecoverablePanes`), a list of recoverable items — for device panes: `{tabName}: {mode ?? kind}` plus cwd when present; for ledgerOnly: `{mode} session — {cwd ?? 'unknown directory'}`; buttons `Restore` and `Not now`.
+3. Accept: `clearPendingOffer()`; for each `RecoveryTabPlan`: `dispatch(addTab({ id: plan.tabId, title: plan.title }))`, `dispatch(restoreLayout({ tabId: plan.tabId, layout: plan.layout, paneTitles: plan.paneTitles }))`; then `armRecoveredTerminalRestores(store.getState(), planTabIds)`; hide panel.
+4. Decline: `recordDismissal(contentId)`; `clearPendingOffer()`; hide panel. No further renders this or future visits for this contentId.
+5. A11y: dialog has `role="dialog"`, `aria-modal="true"`, `aria-labelledby` pointing at the heading id; list is a `<ul>`; both buttons are real `<button>` elements with visible text. `data-testid="recovery-offer-panel"`, `data-testid="recovery-accept"`, `data-testid="recovery-decline"` for e2e.
+
+- [ ] **Step 1: Write the failing tests**
+
+`test/unit/client/components/RecoveryOfferPanel.test.tsx` — per-test `configureStore` with the real `tabs` + `panes` reducers (import the same reducer wiring an existing store test uses); mock the api module:
+
+```tsx
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Provider } from 'react-redux'
+
+vi.mock('@/lib/api', async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  getRecoveryInventory: vi.fn(),
+}))
+vi.mock('@/lib/recovery/boot-state', () => ({
+  computeHadPersistedLayout: () => false,
+  hadPersistedLayoutAtBoot: false, // simulate empty boot; per-test override via vi.mocked where needed
+}))
+vi.mock('@/store/tabRegistrySync', async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  getClientInstanceId: () => 'client-me',
+}))
+
+import { getRecoveryInventory } from '@/lib/api'
+import { RecoveryOfferPanel } from '@/components/RecoveryOfferPanel'
+import { configureStore } from '@reduxjs/toolkit'
+import tabsReducer from '@/store/tabsSlice'
+import panesReducer from '@/store/panesSlice'
+
+// Local helper, defined in THIS test file (match default-export names to the real slice files):
+function makeTestStore() {
+  return configureStore({ reducer: { tabs: tabsReducer, panes: panesReducer } })
+}
+
+const INVENTORY = {
+  recoverable: true, contentId: 'cid-1',
+  device: { deviceId: 'd', deviceLabel: 'l', capturedAt: 1, tabs: [{ tabKey: 'k', tabName: 'work', panes: [
+    { paneId: 'p1', kind: 'terminal', mode: 'claude', shell: null, cwd: '/w', payload: {},
+      sessionRef: { provider: 'claude', sessionId: 'S2' }, ledgerState: 'bound' },
+  ] }] },
+  otherDevices: [], ledgerOnly: [],
+}
+
+describe('RecoveryOfferPanel', () => {
+  beforeEach(() => { localStorage.clear(); vi.mocked(getRecoveryInventory).mockReset() })
+
+  it('offers when eligible and inventory is recoverable', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    expect(await screen.findByRole('dialog')).toBeInTheDocument()
+    expect(screen.getByText(/restore 1 pane/i)).toBeInTheDocument()
+    expect(screen.getByText(/work/)).toBeInTheDocument()
+  })
+
+  it('accept creates the tabs and hides the panel', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    const store = makeTestStore()
+    render(<Provider store={store}><RecoveryOfferPanel /></Provider>)
+    await userEvent.click(await screen.findByTestId('recovery-accept'))
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+    // Recreated pane carries the ledger-corrected ref (adjust access to the real slice shapes):
+    expect(JSON.stringify(store.getState().tabs)).toContain('"work"')
+    expect(JSON.stringify(store.getState().panes)).toContain('"S2"')
+  })
+
+  it('decline hides, records dismissal, and a remount stays quiet', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    const store = makeTestStore()
+    const first = render(<Provider store={store}><RecoveryOfferPanel /></Provider>)
+    await userEvent.click(await screen.findByTestId('recovery-decline'))
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+    first.unmount()
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    await waitFor(() => expect(vi.mocked(getRecoveryInventory)).toHaveBeenCalled())
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('renders nothing when inventory is not recoverable', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue({ ...INVENTORY, recoverable: false, device: null })
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    await waitFor(() => expect(vi.mocked(getRecoveryInventory)).toHaveBeenCalled())
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+})
+```
+
+Adjust the state-shape assertions in the accept test to the real `tabs`/`panes` slice shapes (assert: at least one new tab exists whose title is `work`, and the panes layout for it contains a terminal leaf with `sessionRef.sessionId === 'S2'`). Also add a test that `hadPersistedLayoutAtBoot: true` + no pending flag renders nothing and never fetches (use a second mock variant via `vi.doMock` + dynamic import, or split into a separate test file with a different boot-state mock — whichever matches house style).
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npm run test:vitest -- run test/unit/client/components/RecoveryOfferPanel.test.tsx`
+Expected: FAIL — component missing.
+
+- [ ] **Step 3: Implement the component**
+
+Implement per the Behavior contract above. Structure:
+
+```tsx
+export function RecoveryOfferPanel() {
+  const dispatch = useAppDispatch()
+  const store = useStore<RootState>()
+  const [inventory, setInventory] = useState<RecoveryInventory | null>(null)
+  const [resolved, setResolved] = useState(false)
+
+  useEffect(() => {
+    if (hadPersistedLayoutAtBoot && !getPendingOffer()) { setResolved(true); return }
+    let cancelled = false
+    getRecoveryInventory(getClientInstanceId())
+      .then((inv) => {
+        if (cancelled) return
+        if (!inv.recoverable || isDismissed(inv.contentId)) { setResolved(true); return }
+        setPendingOffer(inv.contentId)
+        setInventory(inv)
+      })
+      .catch(() => { if (!cancelled) setResolved(true) })
+    return () => { cancelled = true }
+  }, [])
+
+  const accept = () => {
+    if (!inventory) return
+    clearPendingOffer()
+    const plans = buildRecoveryPlan(inventory)
+    for (const plan of plans) {
+      dispatch(addTab({ id: plan.tabId, title: plan.title }))
+      dispatch(restoreLayout({ tabId: plan.tabId, layout: plan.layout, paneTitles: plan.paneTitles }))
+    }
+    armRecoveredTerminalRestores(store.getState(), plans.map((p) => p.tabId))
+    setInventory(null); setResolved(true)
+  }
+
+  const decline = () => {
+    if (inventory) recordDismissal(inventory.contentId)
+    clearPendingOffer()
+    setInventory(null); setResolved(true)
+  }
+  // render: null unless inventory; else portal dialog per Behavior item 2/5
+}
+```
+
+`armRecoveredTerminalRestores(state, tabIds)`: for each tabId, read the tab's layout from the panes slice state, walk the tree, and for each leaf with `content.kind === 'terminal' && content.sessionRef` call `addTerminalRestoreRequestId(content.createRequestId)` (post-normalization id — the reducer re-minted it). Match how `App.tsx:1069` arms restores. Export it for direct unit testing if the component tests don't already cover it.
+
+Export `getClientInstanceId` from `tabRegistrySync.ts` by adding `export` to (or a thin exported wrapper around) the existing private accessor the push envelope uses — no behavior change.
+
+- [ ] **Step 4: Run tests + a11y lint**
+
+Run: `npm run test:vitest -- run test/unit/client/components/RecoveryOfferPanel.test.tsx && npm run lint`
+Expected: PASS, no jsx-a11y violations.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/components/RecoveryOfferPanel.tsx src/store/tabRegistrySync.ts test/unit/client/components/
+git commit -m "feat(client): self-gating recover-my-panes offer panel with accept/decline (B3/P1.9)"
+```
+
+---
+
+### Task 6: Client — App.tsx wiring (distinct Lane B3 region)
+
+**Files:**
+- Modify: `src/App.tsx` (ONLY: one import + one JSX line adjacent to the `SetupWizard` render at ~`App.tsx:1347-1362`; do NOT touch regions 811-898, 900-981, 1002-1090, 1283-1325)
+- Modify: `test/unit/client/components/RecoveryOfferPanel.test.tsx` (no changes expected; listed for the re-run)
+
+**Interfaces:**
+- Consumes: `RecoveryOfferPanel` (Task 5).
+- Produces: the panel mounted app-wide.
+
+- [ ] **Step 1: Make the change**
+
+Import at the top of `App.tsx`:
+
+```tsx
+import { RecoveryOfferPanel } from '@/components/RecoveryOfferPanel'
+```
+
+Adjacent to the `SetupWizard` JSX:
+
+```tsx
+{/* LANE B3 (recover-my-panes): self-gating recovery offer — see docs/plans/2026-07-26-recover-my-panes.md */}
+<RecoveryOfferPanel />
+```
+
+(The component is fully self-gating, so unconditional render is correct and keeps the App.tsx footprint to two lines — mechanical-merge-friendly with Lane B1.)
+
+- [ ] **Step 2: Verify nothing regressed**
+
+Run: `env -u FRESHELL_BIND_HOST FRESHELL_TEST_SUMMARY="B3 recover-my-panes: app wiring" npm run test:vitest -- run test/unit/client/`
+Expected: PASS. Then `npm run lint` — PASS.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/App.tsx
+git commit -m "feat(client): mount recovery offer panel in App (Lane B3 region) (B3/P1.9)"
+```
+
+---
+
+### Task 7: Client — full coordinated suite checkpoint
+
+**Files:** none new — verification gate before e2e work.
+
+- [ ] **Step 1: Run the coordinated full suite**
+
+Run: `env -u FRESHELL_BIND_HOST FRESHELL_TEST_SUMMARY="B3 recover-my-panes: pre-e2e checkpoint" npm test`
+(WAIT if the coordinator gate is held by a sibling lane — check `npm run test:status`; never kill a foreign holder.)
+Expected: green. Fix any breakage this lane introduced before proceeding (do not touch failures owned by other lanes' files — if a failure is in fenced files, record it and re-check `npm run test:status` for an advisory baseline before concluding it's ours).
+
+- [ ] **Step 2: Run the Rust workspace suite**
+
+Run: `cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace`
+Expected: green.
+
+- [ ] **Step 3: Commit (only if fixes were needed)**
+
+```bash
+git add -A && git commit -m "test: stabilize recover-my-panes unit/integration coverage (B3)"
+```
+
+---
+
+### Task 8: E2E — the browser-loss recovery spec
+
+**Files:**
+- Create: `test/e2e-browser/specs/recover-my-panes-rust.spec.ts`
+- Modify: the two registration lists that `pane-ledger-restart-rust.spec.ts` appears in — `RUST_ONLY_SPECS` and the `rust-chromium` project `testMatch` (grep for `pane-ledger-restart-rust` to find both; add this spec the same way)
+
+**Interfaces:**
+- Consumes: `RustServer` (`test/e2e-browser/helpers/rust-server.ts` — `homeDir` defaults to a fresh mkdtemp; `findFreePort()`; `restart()`), the fake-CLI installation + claude-pane creation pattern from `test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts:1-80` (`installFakeCli()` + fixtures `fake-claude-cli.mjs`), fresh-context storage-wipe pattern from `tabs-client-retire.spec.ts:6-38` (`browser.newContext()` = empty localStorage), `?token=<t>&e2e=1` URL scheme, `data-testid="recovery-offer-panel"` / `recovery-accept` / `recovery-decline` from Task 5.
+- Produces: the campaign's first browser-loss recovery e2e.
+
+Scenarios (all inside one spec file sharing one owned `RustServer` on an ephemeral port — NEVER 3001/3002; ESM imports use `.js` extensions):
+
+**Scenario 1 — lose the browser, recover the panes (accept path):**
+1. Start `RustServer` with its own `homeDir` and `installFakeCli()` (mirror `pane-ledger-restart-rust.spec.ts` setup).
+2. Context A: `browser.newContext()` → `page.goto(baseUrl + '/?token=' + token + '&e2e=1')` → create a claude CLI pane exactly the way `pane-ledger-restart-rust.spec.ts` does (fake CLI) and let it bind (that spec's readiness waits) — this produces a ledger binding AND layout state.
+3. Wait for a snapshot to exist on disk: poll `fs.readdir(path.join(homeDir, '.freshell', 'tabs-snapshots'))` until a device dir with ≥1 `.json` generation appears (timeout 30s — pushes fire on ready + every 5s).
+4. `await contextA.close()` — the "lost browser".
+5. `await server.restart()` — the campaign scenario restarts the server too.
+6. Context B: fresh `browser.newContext()` (empty storage = new machine) → `goto` the same URL.
+7. `await expect(pageB.getByTestId('recovery-offer-panel')).toBeVisible({ timeout: 15000 })` and assert the heading matches `/restore \d+ pane/i`.
+8. `await pageB.getByTestId('recovery-accept').click()` → panel disappears → assert a recreated terminal pane renders and the fake claude session RESUMES (reuse the exact resumed-session assertion from `pane-ledger-restart-rust.spec.ts` — e.g. the fake CLI's resume marker text appearing in the recreated pane's terminal).
+9. Same-browser reload guard: `await pageB.reload()` → wait for app ready → `await expect(pageB.getByTestId('recovery-offer-panel')).toHaveCount(0)` (localStorage now has a layout — no offer).
+
+**Scenario 2 — decline path:**
+1. Fresh context C against the same server (which still has snapshots + ledger rows from scenario 1's context A... note: context B's accepted layout also pushed snapshots — that is fine; recoverable state still exists).
+2. Offer appears → `recovery-decline` click → panel gone → assert no recovered tabs were added (tab strip shows only the auto-created default tab).
+
+Dismissal-across-reload persistence is proven at unit level (Task 3/5); e2e scenario 2 proves the user-visible decline behavior.
+
+- [ ] **Step 1: Write the failing spec**
+
+Write the spec per the scenarios above, copying the harness scaffolding verbatim from `pane-ledger-restart-rust.spec.ts` (imports with `.js` extensions, `ensureRustServerBuilt`, server lifecycle in `test.beforeAll`/`afterAll`, fake CLI install). Register it in both lists.
+
+- [ ] **Step 2: Run to verify it fails only on the new assertions**
+
+Run: `npx playwright test test/e2e-browser/specs/recover-my-panes-rust.spec.ts --project=rust-chromium`
+Expected at this point: PASS (the feature is already implemented in Tasks 1-6) — but run it BEFORE trusting it: if it passes, deliberately verify the test tests something by temporarily commenting out the `<RecoveryOfferPanel />` line in `App.tsx` and re-running — it must FAIL on step 7's visibility assertion. Restore the line. (This is the red-verification for an e2e written after its feature tasks; do not skip it.)
+
+- [ ] **Step 3: Stabilize**
+
+Fix selector/timing issues until the spec passes 2 consecutive runs. Common traps already known: the auto-created shell tab races the offer (irrelevant — eligibility is boot-captured); snapshot push cadence is 5s (the fs poll in step 3 handles it); `RustServer` restart keeps the port.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add test/e2e-browser/
+git commit -m "test(e2e): browser-loss recover-my-panes proof - offer, accept-resume, reload guard, decline (B3/P1.9)"
+```
+
+---
+
+### Task 9: Delete the operator restore endpoint + marker/fence machinery (kata h9vt cleanup)
+
+**Files:**
+- Modify: `crates/freshell-server/src/tabs_snapshots.rs` (remove the `POST /api/tabs-sync/restore` route + handler, `restore_lock`, the exactly-one-browser gate, marker usage, the delivery fence including the `send_capture_to` call at `tabs_snapshots.rs:241`, and `pane_to_create_body` usage; KEEP anything the crate still needs — if nothing remains, delete the file and its `mod` decl)
+- Delete: `crates/freshell-server/src/tabs_snapshots_marker.rs`, `crates/freshell-server/src/tabs_snapshots_create_body.rs`, `crates/freshell-server/src/tabs_snapshots_selectors.rs` (the restore-body selector parser — delete only after confirming the inventory endpoint doesn't import it), their test siblings, `scripts/restore-tabs.sh`
+- Modify: `crates/freshell-server/src/main.rs` (remove the restore route merge + dead `mod` decls)
+- Modify: `crates/freshell-server/src/screenshot.rs` — ONLY if removing the fence caller makes `send_capture_to` dead (compiler/clippy will say): delete it and its now-dead helpers in the same commit (P2.17 sanctions exactly this deletion)
+
+**Interfaces:**
+- Consumes: nothing new. Preserves: `freshell_ws::tabs_persist` read selectors (used by Task 2) and the entire write path (untouched).
+- Produces: no `POST /api/tabs-sync/restore`; the store's only consumers are the push write path and `GET /api/recovery/inventory`.
+
+- [ ] **Step 1: Confirm the blast radius**
+
+```bash
+grep -rn "tabs-sync/restore\|tabs_snapshots_marker\|restore-tabs.sh\|pane_to_create_body\|send_capture_to" --include='*.rs' --include='*.sh' --include='*.ts' --include='*.md' crates/ scripts/ src/ test/ docs/development/ | grep -v docs/plans/
+```
+Expected consumers: the endpoint's own module/tests, `main.rs` wiring, the script, `screenshot.rs:244`. If ANYTHING else consumes these (another route, a doc under `docs/development/` describing operator procedure), list it in the commit message and update/delete it too. If a consumer exists that the UI flow does not replace — STOP and report (that would reopen the h9vt disposition).
+
+- [ ] **Step 2: Delete, then let the compiler drive**
+
+Remove the route merge from `main.rs` first, then the handler + machinery, then the files. Iterate `cargo check -p freshell-server` until clean; every `dead_code` warning that appears in touched modules is machinery the fence/marker existed for — delete it (context poison), do not `#[allow]` it.
+
+- [ ] **Step 3: Verify the full workspace + client suites stay green**
+
+Run: `cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace`
+Expected: PASS with the restore/marker test files gone; if any REMAINING test fails because it exercised restore machinery, that test belonged to the deleted feature — delete it; if it fails for any other reason, fix the code, not the test.
+Run: `npx playwright test test/e2e-browser/specs/recover-my-panes-rust.spec.ts --project=rust-chromium`
+Expected: PASS (proves the UI flow never depended on the deleted machinery).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add -A
+git commit -m "refactor(server): delete operator tabs-sync restore endpoint, write-ahead marker, and screenshot delivery fence
+
+Kata h9vt disposition: Option A. The tabs-snapshots store is now load-bearing
+via GET /api/recovery/inventory + the client recover-my-panes flow. The
+server-push restore machinery (marker, one-browser gate, delivery fence,
+scripts/restore-tabs.sh) served only the blind operator push and has no UI-flow
+consumer; the unreachable fence was flagged for deletion in campaign P2.17."
+```
+
+---
+
+### Task 10: Final verification + push
+
+**Files:** none.
+
+- [ ] **Step 1: Full gates, in order**
+
+```bash
+cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace
+npm run lint
+env -u FRESHELL_BIND_HOST FRESHELL_TEST_SUMMARY="B3 recover-my-panes: final verification" npm run check
+npx playwright test test/e2e-browser/specs/recover-my-panes-rust.spec.ts --project=rust-chromium
+```
+Expected: all green. (`npm run check` = typecheck + coordinated full suite; WAIT on the coordinator gate if held.)
+
+- [ ] **Step 2: Push the branch — STOP before any PR**
+
+```bash
+git push -u origin feat/recover-my-panes
+```
+Do NOT run `gh pr create` — PR creation is not approved for this lane.
+
+- [ ] **Step 3: Report**
+
+The lane's final report must include: branch name, the green-suite evidence (commands + outcomes), the e2e proof summary, and this kata disposition statement: **"Kata h9vt resolved as Option A: tabs-snapshots is now load-bearing (layout half of the recover-my-panes flow via GET /api/recovery/inventory); the operator POST /api/tabs-sync/restore endpoint, write-ahead marker, exactly-one-browser gate, screenshot delivery fence, and scripts/restore-tabs.sh were deleted as UI-flow-irrelevant per the 'reuse what serves the UI flow, delete what doesn't' directive and P2.17."**
+
+---
+
+## Self-Review Record
+
+**1. Spec coverage:** (1) recover-my-panes flow — offer/trigger D1-D3 + Tasks 3/5/6; accept recreation honoring §4.2 D4-D5 + Tasks 1/4/5; decline remembered Task 3/5. (2) kata h9vt — disposition section + Task 9 (Option A kept, honest evaluation recorded; Option B rejected with reason: ledger has no layout). (3) read API — Tasks 1/2, device-scoped via snapshot device dirs + self-pollution filter, auth'd, fed by ledger + newest-generation union selectors. TDD red-first for trigger conditions, inventory API, authority chain, dismissal — Tasks 1-5 all test-first; Task 8's e2e includes an explicit red-verification step. E2E browser-loss scenario with own RustServer/ephemeral ports/server restart/fresh context/decline/same-browser-reload — Task 8. Scope fence, a11y lint, PR policy — Global Constraints + Task 10.
+
+**1b. No silent deferrals:** no stubs or fake providers stand in for required behavior — the e2e uses the repo's established fake-CLI fixture (the same production-path proof used by the existing ledger restart e2e; it exercises the real create/resume path). Non-terminal pane recreation reuses the production `reopenClosedTab` restore path (passthrough, D5) — recreated, not deferred. Split geometry is not in the store (D6) — a data fact, not a deferral. No UNRESOLVED COVERAGE GAPS.
+
+**2. Placeholder scan:** the `row_*` accessors (Task 1) and `union_value` (Task 2) are named single-field adapters against real definitions the implementer opens — each is bound to a concrete file/line source, with tests as the arbiter; no TBD/TODO/"handle edge cases" items remain.
+
+**3. Type consistency:** `DeviceUnion`/`build_inventory` (Task 1) consumed verbatim in Task 2; `RecoveryInventory`/`RecoveryPane`/`RecoveryTabPlan` (Task 4) consumed in Task 5; `getClientInstanceId` exported in Task 5 and consumed there; testids `recovery-offer-panel`/`recovery-accept`/`recovery-decline` defined in Task 5, consumed in Task 8; `ledgerState` values (`bound|closed|gc_expired|unknown`) match between Task 1 output, Task 4 types, and tests.

From 5319d7502cfe69857047ebb3b319cf37f57504f8 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 02:38:25 -0700
Subject: [PATCH 04/87] docs: add implementation plan for codex-rollout-locator
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../plans/2026-07-26-codex-rollout-locator.md | 2056 +++++++++++++++++
 1 file changed, 2056 insertions(+)
 create mode 100644 docs/plans/2026-07-26-codex-rollout-locator.md

diff --git a/docs/plans/2026-07-26-codex-rollout-locator.md b/docs/plans/2026-07-26-codex-rollout-locator.md
new file mode 100644
index 000000000..554e89c97
--- /dev/null
+++ b/docs/plans/2026-07-26-codex-rollout-locator.md
@@ -0,0 +1,2056 @@
+# Codex Server-Side Rollout Identity Locator Implementation Plan
+
+> **For agentic workers:** This plan is executed task-by-task by the
+> workflow's execute stage: a fresh implementer per task, with a spec +
+> quality review after each task. Steps use checkbox (`- [ ]`) syntax
+> for tracking.
+
+**Goal:** Give the Rust server its own authoritative identity source for fresh
+codex terminal panes — a server-side locator that detects the new
+`rollout-<ts>-<threadId>.jsonl` appearing under the codex sessions root,
+binds the pane to that thread id (identity registry + terminal meta + durable
+pane ledger + activity hub), and retires the client-driven
+`terminal.codex.candidate.persisted` channel so exactly one writer owns codex
+identity facts (campaign item P1.12, plan §2.3.2).
+
+**Architecture:** A third sibling locator following the amplifier/opencode
+precedent (a provider-parameterized locator was explicitly rejected by spec —
+see `crates/freshell-ws/src/lib.rs` doc on `opencode_locator`). Pure detection
+lives in `crates/freshell-sessions/src/codex_locator.rs` (sync, `Mutex`-guarded,
+injected clock, filesystem-snapshot correlation); a thin async controller lives
+in `crates/freshell-ws/src/codex_association.rs` (arm at create, submit seam,
+150 ms sweep, resolve → adopt). The adoption tail (identity upsert → registry
+meta → ledger resolve → pinned broadcasts → activity bind + rollout attach) is
+extracted from `codex_candidate.rs` into a shared `codex_identity.rs` before
+the candidate channel is deleted. The wire message stays in the protocol enum
+but becomes accept-and-ignore-with-debug-log.
+
+**Tech Stack:** Rust (freshell-sessions, freshell-ws, freshell-server crates),
+serde_json, tokio; Playwright e2e (`test/e2e-browser/`, RustServer harness);
+Node .mjs fake-CLI fixture.
+
+## Global Constraints
+
+- Base: `origin/main` @ `2dfbba58`. Work only inside the worktree
+  `/home/dan/code/freshell/.worktrees/codex-rollout-locator`. All paths below
+  are relative to the worktree root.
+- SCOPE FENCE (Lane B2 of a 4-lane wave). You own:
+  `crates/freshell-ws/src/codex_candidate.rs` (retirement), the new locator
+  modules, the minimal `crates/freshell-ws/src/terminal.rs` call sites,
+  freshell-activity codex identity-bind touchpoints, ledger write calls, plus
+  the unavoidable wiring in `crates/freshell-server/src/main.rs` and
+  `crates/freshell-ws/src/lib.rs`. Do NOT touch:
+  `crates/freshell-ws/src/reconcile.rs`, `crates/freshell-ws/src/existence.rs`,
+  `src/lib/ws-client*`, `src/App.tsx` (Lane B1); `tabs_snapshots.rs` + recovery
+  UI (Lane B3); ANY file under `crates/freshell-freshagent/` (Lane B4);
+  opencode files beyond reading. No kimi/gemini work.
+- The frozen client is untouched: `src/components/TerminalView.tsx`'s candidate
+  sender stays; the server accepts-and-ignores its frame with a debug log —
+  never an error to the client.
+- Rust CI gate: `cargo fmt --all --check` and
+  `cargo clippy --workspace --all-targets -- -D warnings` (toolchain 1.96.0).
+  `cargo test` is a local-only gate — run it anyway, every task.
+- Coordinated TS suites: `env -u FRESHELL_BIND_HOST npm test` waits on the
+  shared coordinator gate — if another agent holds it, WAIT (3 sibling lanes
+  run concurrently). Set `FRESHELL_TEST_SUMMARY="lane B2 codex locator"` for
+  broad runs. Focused runs go through `npm run test:vitest -- ...`.
+- E2E: every spec owns its RustServer instances on ephemeral ports
+  (`findFreePort()`), NEVER 3001/3002. NEVER restart the user's self-hosted
+  Freshell server. NEVER use broad kill patterns.
+- Worktree may need `npm ci` and the tsx symlink:
+  `ln -s ../node_modules/tsx node_modules/tsx` (only if `npm test` complains).
+- ~78 GB disk free — halt and report on any ENOSPC.
+- PR POLICY: NOT approved. Push the branch, STOP before `gh pr create`, report
+  branch + proof.
+- Server TS uses NodeNext/ESM (relative imports need `.js`) — no server TS is
+  modified in this plan; the new fixture is a self-contained `.mjs`.
+
+## Premise Corrections (verified against the codebase — trust these over the task prose)
+
+1. **There is no per-terminal isolated CODEX_HOME.** `CODEX_HOME` is a
+   process-global env read (`codex_sessions_root()`, resolved once at boot,
+   `crates/freshell-server/src/main.rs:412-417`). All codex terminals of a
+   server share ONE sessions tree:
+   `<CODEX_HOME|~/.codex>/sessions/YYYY/MM/DD/rollout-<ts>-<threadId>.jsonl`
+   (flat `<id>.jsonl` also supported, used by tests). Pane↔rollout attribution
+   therefore needs a disambiguator: arm-time known-files snapshot + the
+   rollout's own `session_meta.payload.cwd` + ambiguity refusal.
+2. **"One watcher, two consumers" is not feasible for discovery.** The wave-2
+   status watcher (`activity.rs:349`) watches a SINGLE already-known rollout
+   file, NonRecursive, and only exists once identity is known — chicken-and-egg
+   for discovery. The locator therefore polls (bounded scan, only while a
+   terminal is armed — the opencode/amplifier precedent), and at resolve it
+   hands the discovered path to the EXISTING status watcher via
+   `attach_codex_rollout` — one file-watcher, both consumers downstream.
+   The parsers ARE reused (`first_line_owns`'s ownership predicate shape,
+   1 MB bounded first-line read).
+3. **`bind_terminal_session` does not exist.** The activity-hub bind path is
+   `ActivityHub::bind_codex_session(terminal_id, session_id)`
+   (`crates/freshell-ws/src/activity.rs:251`) →
+   `CodexActivityTracker::bind_session` (`crates/freshell-activity/src/codex.rs:207`).
+4. **The candidate channel is production-DORMANT on the Rust server** — its
+   sole trigger (`terminal.codex.durability.updated`) has no Rust emitter.
+   Retiring it costs zero Rust production behavior; its only exercisers are
+   two Rust integration tests that inject the frame over a raw socket.
+5. **The two candidate restore-contract-wall pins are NOT codex-shaped**:
+   `:1679` is claude-based, `:1803` is opencode-based. Do not flip pins
+   blindly — Task 11 evaluates them by running the wall (Playwright turns an
+   unexpected PASS into a hard failure, which is the flip signal).
+6. **REST-created codex panes (freshell-freshagent) do not arm in this lane.**
+   Arming the shared locator instance from `terminal_tabs.rs` (the way
+   opencode does) requires touching `crates/freshell-freshagent/` — explicitly
+   forbidden by the scope fence (Lane B4 owns those crates). WS-created panes
+   (the frozen client's only path) are covered. This is a spec-directed
+   boundary, not a deferral: record it in the final commit message.
+
+## File Structure
+
+| File | Action | Responsibility |
+|---|---|---|
+| `crates/freshell-sessions/src/codex_locator.rs` | Create | Pure detection: arm/disarm/note_submit/tick over a filesystem-snapshot substrate |
+| `crates/freshell-sessions/src/lib.rs` | Modify | `pub mod codex_locator;` |
+| `crates/freshell-sessions/src/opencode_locator.rs` | Modify (1 line) | `fn normalize_cwd` → `pub(crate) fn` for reuse |
+| `crates/freshell-ws/src/codex_identity.rs` | Create | Shared adoption tail `adopt_codex_identity` + `codex_sessions_root` (moved) |
+| `crates/freshell-ws/src/codex_association.rs` | Create | Controller: maybe_arm / note_possible_submit / drain_and_associate / sweep |
+| `crates/freshell-ws/src/codex_candidate.rs` | Delete (Task 7) | Retired client candidate channel |
+| `crates/freshell-ws/src/lib.rs` | Modify | mod decls, `pub use`, `WsState.codex_locator` field |
+| `crates/freshell-ws/src/terminal.rs` | Modify | arm-at-create, submit seam, exit disarm, candidate match arm → debug log |
+| `crates/freshell-ws/src/invariants.rs` | Modify (docs) | identity-unresolved alarm doc names the codex locator |
+| `crates/freshell-server/src/main.rs` | Modify | Locator construction + WsState field + sweep spawn |
+| `crates/freshell-ws/tests/codex_locator_activity.rs` | Create | Fresh pane → locator → turn.complete carries sessionId |
+| `crates/freshell-ws/tests/codex_candidate_inert.rs` | Create | Candidate frame is accepted, ignored, logged; no identity written |
+| `crates/freshell-ws/tests/codex_candidate_persisted.rs` | Delete (Task 7) | Superseded by inert test + locator tests |
+| `crates/freshell-ws/tests/codex_candidate_activity.rs` | Delete (Task 7) | Superseded by `codex_locator_activity.rs` |
+| `test/e2e-browser/fixtures/fake-codex-terminal.mjs` | Create | Fake codex CLI that writes a real rollout JSONL |
+| `test/e2e-browser/specs/codex-terminal-restore-rust.spec.ts` | Create | Fresh codex pane → server-side identity → restart → `resume <id>` |
+| `test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts` | Modify | Codex SIGKILL-inside-window fresh-by-race ledger wall |
+| `test/e2e-browser/playwright.config.ts` | Modify | Register the new rust-only spec (two places) |
+
+Key existing reference files (read, don't modify beyond what tasks say):
+`crates/freshell-sessions/src/opencode_locator.rs` (the detection template),
+`crates/freshell-ws/src/opencode_association.rs` (the controller template),
+`crates/freshell-ws/src/codex_reconcile.rs` (`locate_codex_rollout`,
+`first_line_owns`), `crates/freshell-ws/src/pane_ledger.rs`
+(`ledger_resolve_identity`), `test/e2e-browser/specs/opencode-terminal-restore-rust.spec.ts`
+(the e2e template).
+
+---
+
+### Task 1: CodexLocator skeleton — types, arm gates, scan substrate, spawn-window happy path
+
+**Files:**
+- Create: `crates/freshell-sessions/src/codex_locator.rs`
+- Modify: `crates/freshell-sessions/src/lib.rs` (add `pub mod codex_locator;` alphabetically among the existing `pub mod` lines)
+- Modify: `crates/freshell-sessions/src/opencode_locator.rs` (make `fn normalize_cwd` → `pub(crate) fn normalize_cwd`; it is currently private at ~`:369`)
+- Test: in-file `mod tests` in `codex_locator.rs`
+
+**Interfaces:**
+- Consumes: `crate::opencode_locator::normalize_cwd(&str) -> String`
+- Produces (later tasks rely on these EXACT signatures):
+
+```rust
+pub const CODEX_WINDOW_MS: i64 = 2_000;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Located {
+    pub terminal_id: String,
+    pub thread_id: String,
+    pub rollout_path: std::path::PathBuf,
+    pub cwd: String,
+}
+
+pub struct CodexLocator { /* private */ }
+
+impl CodexLocator {
+    pub fn new(sessions_root: std::path::PathBuf) -> Self;
+    pub fn with_config(sessions_root: std::path::PathBuf, window_ms: i64) -> Self;
+    pub fn armed_count(&self) -> usize;
+    pub fn fs_scan_count(&self) -> u64;
+    pub fn arm(&self, terminal_id: &str, mode: &str, status_running: bool,
+               resume_session_id: Option<&str>, cwd: Option<&str>, now_ms: i64) -> bool;
+    pub fn disarm(&self, terminal_id: &str);
+    pub fn note_submit(&self, terminal_id: &str, at_ms: i64) -> bool;
+    pub fn tick(&self, now_ms: i64) -> Vec<Located>;
+}
+```
+
+Design notes to encode in the module doc (deliberate deviations from the
+opencode locator, each with rationale):
+- Substrate is a filesystem snapshot-diff, not SQLite row-diff: codex persists
+  one JSONL rollout file per session under the sessions root.
+- There is NO `pre_epsilon_ms` and NO created-at time bound: filesystems have
+  no reliable cross-platform creation time. The arm-time `known_files`
+  snapshot is the sole (and primary — same as opencode's `known_ids`) safety:
+  a file already present at arm can never bind to this terminal.
+- Window semantics are otherwise identical to opencode: deadline is
+  `arm_ms + spawn_window_ms` until a submit lands, then `enter_ms + window_ms`;
+  submits only extend, never shorten; evaluation happens once per open window
+  (`resolved` flag), and a later Enter re-opens it.
+- Scans happen ONLY at arm time and at deadline evaluations (never on idle
+  ticks — proven by `fs_scan_count`), bounded to walk depth 5 (the tree is
+  `sessions/YYYY/MM/DD/rollout-*.jsonl`; flat `<id>.jsonl` in tests). Measured
+  35-55 ms warm on a real 8k-file tree; callers run `tick()` in
+  `spawn_blocking`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `crates/freshell-sessions/src/codex_locator.rs` with ONLY the test
+module and a `#![allow(dead_code)]`-free skeleton that does not yet exist —
+i.e. write the tests first; the file will not compile until Step 3 adds the
+implementation above the tests. Test module:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::{Path, PathBuf};
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    static TEST_DIR_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+    /// Same convention as opencode_locator.rs tests: no tempfile crate.
+    fn unique_temp_dir(label: &str) -> PathBuf {
+        let n = TEST_DIR_COUNTER.fetch_add(1, Ordering::SeqCst);
+        let dir = std::env::temp_dir().join(format!(
+            "freshell-codex-locator-test-{label}-{}-{n}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&dir).expect("create test dir");
+        dir
+    }
+
+    /// Write a rollout file whose FIRST line is the session_meta identity
+    /// record, exactly the shape the real codex CLI writes
+    /// (payload.id = identity; payload.cwd = the session's working dir).
+    fn write_rollout(root: &Path, rel_dir: &str, thread_id: &str, cwd: Option<&str>) -> PathBuf {
+        let dir = root.join(rel_dir);
+        std::fs::create_dir_all(&dir).expect("create rollout dir");
+        let file = dir.join(format!("rollout-2026-07-26T08-00-00-{thread_id}.jsonl"));
+        let payload = match cwd {
+            Some(c) => format!(r#"{{"id":"{thread_id}","cwd":"{c}"}}"#),
+            None => format!(r#"{{"id":"{thread_id}"}}"#),
+        };
+        let line = format!(
+            r#"{{"timestamp":"2026-07-26T08:00:00.000Z","type":"session_meta","payload":{payload}}}"#
+        );
+        std::fs::write(&file, format!("{line}\n")).expect("write rollout");
+        file
+    }
+
+    const TID: &str = "11111111-2222-3333-4444-555555555555";
+
+    #[test]
+    fn fresh_rollout_written_at_spawn_resolves_via_spawn_window() {
+        let root = unique_temp_dir("spawn-happy");
+        let cwd = root.join("project");
+        std::fs::create_dir_all(&cwd).unwrap();
+        let cwd_s = cwd.to_string_lossy().to_string();
+        let locator = CodexLocator::new(root.clone());
+
+        assert!(locator.arm("t1", "codex", true, None, Some(&cwd_s), 1_000));
+        // Rollout appears AFTER arm, BEFORE the spawn deadline — no Enter at all.
+        let path = write_rollout(&root, "2026/07/26", TID, Some(&cwd_s));
+
+        // Before the deadline: nothing yet (evaluation happens at deadline).
+        assert!(locator.tick(1_000 + CODEX_WINDOW_MS - 1).is_empty());
+        let located = locator.tick(1_000 + CODEX_WINDOW_MS);
+        assert_eq!(
+            located,
+            vec![Located {
+                terminal_id: "t1".into(),
+                thread_id: TID.into(),
+                rollout_path: path,
+                cwd: crate::opencode_locator::normalize_cwd(&cwd_s),
+            }]
+        );
+        // Success fully resolves and disarms; tick() drains.
+        assert_eq!(locator.armed_count(), 0);
+        assert!(locator.tick(1_000 + CODEX_WINDOW_MS + 1).is_empty());
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn arm_admission_gates() {
+        let root = unique_temp_dir("gates");
+        let locator = CodexLocator::new(root.clone());
+        // wrong mode
+        assert!(!locator.arm("t1", "opencode", true, None, Some("/tmp"), 0));
+        // not running
+        assert!(!locator.arm("t1", "codex", false, None, Some("/tmp"), 0));
+        // resume id present — the ONLY already-bound gate (no restore flag)
+        assert!(!locator.arm("t1", "codex", true, Some(TID), Some("/tmp"), 0));
+        // missing / empty cwd
+        assert!(!locator.arm("t1", "codex", true, None, None, 0));
+        assert!(!locator.arm("t1", "codex", true, None, Some(""), 0));
+        // happy arm, then idempotent re-arm returns false
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(!locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn disarmed_terminal_never_resolves() {
+        let root = unique_temp_dir("disarm");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        locator.disarm("t1");
+        assert!(locator.tick(CODEX_WINDOW_MS + 1).is_empty());
+        assert_eq!(locator.armed_count(), 0);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn tick_while_unarmed_performs_zero_fs_scans() {
+        let root = unique_temp_dir("idle");
+        let locator = CodexLocator::new(root.clone());
+        // Construction must not scan eagerly either.
+        assert_eq!(locator.fs_scan_count(), 0);
+        assert!(locator.tick(10_000).is_empty());
+        assert_eq!(locator.fs_scan_count(), 0);
+        // Arming scans once (the known-files snapshot)…
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert_eq!(locator.fs_scan_count(), 1);
+        // …but a tick BEFORE any deadline is due still scans nothing.
+        let before = locator.fs_scan_count();
+        assert!(locator.tick(1).is_empty());
+        assert_eq!(locator.fs_scan_count(), before);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+```bash
+cd /home/dan/code/freshell/.worktrees/codex-rollout-locator
+cargo test -p freshell-sessions codex_locator 2>&1 | tail -20
+```
+Expected: COMPILE ERROR — `CodexLocator` / `Located` / `CODEX_WINDOW_MS` not
+found (the module exists with only tests). A compile failure of the new test
+module is the RED state for a new module.
+
+- [ ] **Step 3: Write the implementation (above the test module, same file)**
+
+```rust
+//! Server-side codex terminal-pane session locator (Lane B2, campaign §2.3.2).
+//!
+//! Third sibling of `amplifier_locator` / `opencode_locator` (a
+//! provider-parameterized locator was explicitly rejected — the substrates
+//! share zero code). Substrate: codex persists ONE JSONL rollout file per
+//! session under a process-global sessions root
+//! (`<CODEX_HOME|~/.codex>/sessions/YYYY/MM/DD/rollout-<ts>-<threadId>.jsonl`,
+//! flat `<id>.jsonl` in tests). A new session is a NEW FILE — so the locator
+//! does a snapshot-diff of the file set, not a row-diff.
+//!
+//! Deliberate deviations from the opencode locator, with rationale:
+//! - NO `pre_epsilon_ms` and NO created-at time bound: filesystems have no
+//!   reliable cross-platform creation time (mtime moves on every append).
+//!   The arm-time `known_files` snapshot is the sole safety — a file already
+//!   present at arm can never bind to this terminal. (For opencode the
+//!   snapshot is ALSO the primary safety; the time bound there is
+//!   defense-in-depth the fs cannot provide.)
+//! - Attribution disambiguator: the rollout's own first-line
+//!   `session_meta.payload.cwd` (when present) must match the armed
+//!   terminal's cwd. When absent, ambiguity refusal still protects
+//!   concurrent spawns (see `tick`).
+//! - Ownership is proven ONLY by `payload.id` on line 1 — NEVER the filename
+//!   (prefilter-grade at best), NEVER `payload.session_id` (fork/resume
+//!   LINEAGE: matches a FOREIGN session in 54/144 sampled real rollouts) —
+//!   same predicate as `freshell-ws`'s `first_line_owns`.
+//!
+//! Zero cost when idle: scans happen only at arm and at deadline
+//! evaluations, proven by `fs_scan_count`. Callers run `tick()` inside
+//! `tokio::task::spawn_blocking`.
+
+use std::collections::{HashMap, HashSet};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Mutex;
+
+use crate::opencode_locator::normalize_cwd;
+
+/// Correlation window after a submit (Enter-anchored deadline), and the
+/// spawn-anchored fallback window (spawn_window_ms := window_ms, kept
+/// distinct for clarity — same convention as the opencode locator).
+pub const CODEX_WINDOW_MS: i64 = 2_000;
+
+/// Bounded first-line read cap — real rollouts reach 152 MB; observed real
+/// first lines are ≤ 22.4 KB. Mirrors `codex_reconcile.rs`.
+const MAX_FIRST_LINE_BYTES: u64 = 1024 * 1024;
+
+/// Bounded walk depth — `sessions/YYYY/MM/DD/` is depth 3; 5 mirrors
+/// `locate_codex_rollout`.
+const MAX_WALK_DEPTH: u8 = 5;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Located {
+    pub terminal_id: String,
+    pub thread_id: String,
+    pub rollout_path: PathBuf,
+    pub cwd: String,
+}
+
+#[derive(Debug, Clone)]
+struct Armed {
+    cwd_normalized: String,
+    arm_ms: i64,
+    known_files: HashSet<PathBuf>,
+    enter_ms: Option<i64>,
+    resolved: bool,
+}
+
+#[derive(Default)]
+struct Inner {
+    armed: HashMap<String, Armed>,
+}
+
+pub struct CodexLocator {
+    sessions_root: PathBuf,
+    window_ms: i64,
+    spawn_window_ms: i64,
+    inner: Mutex<Inner>,
+    fs_scan_count: AtomicU64,
+}
+
+impl CodexLocator {
+    pub fn new(sessions_root: PathBuf) -> Self {
+        Self::with_config(sessions_root, CODEX_WINDOW_MS)
+    }
+
+    pub fn with_config(sessions_root: PathBuf, window_ms: i64) -> Self {
+        Self {
+            sessions_root,
+            window_ms,
+            spawn_window_ms: window_ms,
+            inner: Mutex::new(Inner::default()),
+            fs_scan_count: AtomicU64::new(0),
+        }
+    }
+
+    pub fn armed_count(&self) -> usize {
+        self.inner.lock().unwrap().armed.len()
+    }
+
+    pub fn fs_scan_count(&self) -> u64 {
+        self.fs_scan_count.load(Ordering::SeqCst)
+    }
+
+    /// Admission rules (mirrors `OpencodeLocator::arm`): codex mode, running,
+    /// NO resume id (the only already-bound gate — never a restore flag, so
+    /// restore-created identity-less panes re-arm for free), non-empty cwd,
+    /// not already armed. On success takes the arm-time known-files snapshot.
+    pub fn arm(
+        &self,
+        terminal_id: &str,
+        mode: &str,
+        status_running: bool,
+        resume_session_id: Option<&str>,
+        cwd: Option<&str>,
+        now_ms: i64,
+    ) -> bool {
+        if mode != "codex" || !status_running || resume_session_id.is_some() {
+            return false;
+        }
+        let Some(cwd) = cwd.filter(|c| !c.is_empty()) else {
+            return false;
+        };
+        let mut inner = self.inner.lock().unwrap();
+        if inner.armed.contains_key(terminal_id) {
+            return false;
+        }
+        let known_files = self.scan_rollout_files();
+        inner.armed.insert(
+            terminal_id.to_string(),
+            Armed {
+                cwd_normalized: normalize_cwd(cwd),
+                arm_ms: now_ms,
+                known_files,
+                enter_ms: None,
+                resolved: false,
+            },
+        );
+        true
+    }
+
+    pub fn disarm(&self, terminal_id: &str) {
+        self.inner.lock().unwrap().armed.remove(terminal_id);
+    }
+
+    /// Enter re-open semantics (mirrors opencode): a mid-turn Enter never
+    /// re-opens a still-pending evaluation; a resolved (zero-candidate /
+    /// ambiguous) terminal gets a fresh Enter-anchored deadline.
+    pub fn note_submit(&self, terminal_id: &str, at_ms: i64) -> bool {
+        let mut inner = self.inner.lock().unwrap();
+        let Some(armed) = inner.armed.get_mut(terminal_id) else {
+            return false;
+        };
+        if !armed.resolved && armed.enter_ms.is_some() {
+            return false;
+        }
+        armed.enter_ms = Some(at_ms);
+        armed.resolved = false;
+        true
+    }
+
+    fn deadline(&self, armed: &Armed) -> i64 {
+        match armed.enter_ms {
+            Some(enter_ms) => enter_ms + self.window_ms,
+            None => armed.arm_ms + self.spawn_window_ms,
+        }
+    }
+
+    /// One evaluation per open window, at (or after) its deadline. Outcomes:
+    /// 0 candidates → keep watching (stays armed, `resolved = true`);
+    /// >1 candidates for one terminal → WARN + refuse (never guess);
+    /// one candidate claimed by ≥2 terminals in the same tick → WARN + refuse
+    /// ALL claimants (concurrent same-cwd spawns are indistinguishable);
+    /// exactly one clean match → emit `Located` and disarm. `tick()` drains.
+    pub fn tick(&self, now_ms: i64) -> Vec<Located> {
+        {
+            let inner = self.inner.lock().unwrap();
+            if inner.armed.is_empty() {
+                return Vec::new();
+            }
+            if !inner
+                .armed
+                .values()
+                .any(|a| !a.resolved && now_ms >= self.deadline(a))
+            {
+                return Vec::new();
+            }
+        }
+        let current = self.scan_rollout_files();
+        let mut inner = self.inner.lock().unwrap();
+
+        // Pass 1: per-terminal candidate evaluation.
+        let mut claims: Vec<(String, Located)> = Vec::new();
+        for (terminal_id, armed) in inner.armed.iter_mut() {
+            if armed.resolved || now_ms < self.deadline(armed) {
+                continue;
+            }
+            armed.resolved = true;
+            let mut matches: Vec<(PathBuf, RolloutMeta)> = Vec::new();
+            for path in current.difference(&armed.known_files) {
+                let Some(meta) = probe_rollout(path) else {
+                    continue;
+                };
+                if let Some(cwd) = &meta.cwd {
+                    if normalize_cwd(cwd) != armed.cwd_normalized {
+                        continue;
+                    }
+                }
+                matches.push((path.clone(), meta));
+            }
+            match matches.len() {
+                0 => {} // keep watching
+                1 => {
+                    let (path, meta) = matches.remove(0);
+                    claims.push((
+                        terminal_id.clone(),
+                        Located {
+                            terminal_id: terminal_id.clone(),
+                            thread_id: meta.thread_id,
+                            rollout_path: path,
+                            cwd: armed.cwd_normalized.clone(),
+                        },
+                    ));
+                }
+                n => {
+                    tracing::warn!(
+                        terminal_id = %terminal_id,
+                        candidates = n,
+                        "codex_locator_ambiguous: multiple new rollouts in one window; refusing to bind"
+                    );
+                }
+            }
+        }
+
+        // Pass 2: cross-terminal conflict — the same rollout (or thread id)
+        // claimed by two armed terminals in one tick is unattributable.
+        let mut located = Vec::new();
+        for (terminal_id, candidate) in &claims {
+            let contested = claims.iter().any(|(other_tid, other)| {
+                other_tid != terminal_id
+                    && (other.rollout_path == candidate.rollout_path
+                        || other.thread_id == candidate.thread_id)
+            });
+            if contested {
+                tracing::warn!(
+                    terminal_id = %terminal_id,
+                    thread_id = %candidate.thread_id,
+                    "codex_locator_contested: rollout claimed by multiple armed terminals; refusing to bind"
+                );
+                continue;
+            }
+            located.push(candidate.clone());
+        }
+        for l in &located {
+            inner.armed.remove(&l.terminal_id);
+        }
+        located
+    }
+
+    fn scan_rollout_files(&self) -> HashSet<PathBuf> {
+        self.fs_scan_count.fetch_add(1, Ordering::SeqCst);
+        fn walk(dir: &Path, depth: u8, out: &mut HashSet<PathBuf>) {
+            if depth > MAX_WALK_DEPTH {
+                return;
+            }
+            let Ok(entries) = std::fs::read_dir(dir) else {
+                return; // missing/corrupt root tolerated, never a panic
+            };
+            for entry in entries.flatten() {
+                let path = entry.path();
+                if path.is_dir() {
+                    walk(&path, depth + 1, out);
+                } else if path
+                    .file_name()
+                    .and_then(|n| n.to_str())
+                    .map(|n| n.ends_with(".jsonl"))
+                    .unwrap_or(false)
+                {
+                    out.insert(path);
+                }
+            }
+        }
+        let mut out = HashSet::new();
+        walk(&self.sessions_root, 0, &mut out);
+        out
+    }
+}
+
+struct RolloutMeta {
+    thread_id: String,
+    cwd: Option<String>,
+}
+
+/// Identity probe: bounded first-line read; the line must be a
+/// `session_meta` whose `payload.id` is a bare hyphenated UUID. Anything
+/// else (foreign shapes, oversized lines, non-JSON) is silently not a
+/// candidate — the locator never errors on foreign files in a shared tree.
+fn probe_rollout(path: &Path) -> Option<RolloutMeta> {
+    use std::io::BufRead;
+    let file = std::fs::File::open(path).ok()?;
+    let mut reader = std::io::BufReader::new(file).take(MAX_FIRST_LINE_BYTES);
+    let mut first_line = Vec::new();
+    reader.read_until(b'\n', &mut first_line).ok()?;
+    if first_line.len() as u64 >= MAX_FIRST_LINE_BYTES && !first_line.ends_with(b"\n") {
+        return None;
+    }
+    let record: serde_json::Value = serde_json::from_slice(&first_line).ok()?;
+    if record.get("type").and_then(|v| v.as_str()) != Some("session_meta") {
+        return None;
+    }
+    let thread_id = record.pointer("/payload/id").and_then(|v| v.as_str())?;
+    if !is_uuid_shaped(thread_id) {
+        return None;
+    }
+    let cwd = record
+        .pointer("/payload/cwd")
+        .and_then(|v| v.as_str())
+        .map(str::to_string);
+    Some(RolloutMeta {
+        thread_id: thread_id.to_string(),
+        cwd,
+    })
+}
+
+/// Bare hyphenated 36-char UUID shape gate (deliberate small duplicate of
+/// `freshell-ws`'s predicate — this crate sits below it in the dep graph).
+fn is_uuid_shaped(s: &str) -> bool {
+    let bytes = s.as_bytes();
+    if bytes.len() != 36 {
+        return false;
+    }
+    for (i, b) in bytes.iter().enumerate() {
+        let is_hyphen_pos = matches!(i, 8 | 13 | 18 | 23);
+        if is_hyphen_pos {
+            if *b != b'-' {
+                return false;
+            }
+        } else if !b.is_ascii_hexdigit() {
+            return false;
+        }
+    }
+    true
+}
+```
+
+Also add to `crates/freshell-sessions/src/lib.rs`: `pub mod codex_locator;`
+and in `crates/freshell-sessions/src/opencode_locator.rs` change
+`fn normalize_cwd(input: &str) -> String` to
+`pub(crate) fn normalize_cwd(input: &str) -> String`.
+
+Check whether `tracing` is already a dependency of `freshell-sessions`
+(`grep tracing crates/freshell-sessions/Cargo.toml`); if not, add
+`tracing = { workspace = true }` (matching how other crates declare it).
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p freshell-sessions codex_locator`
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Format, lint, commit**
+
+```bash
+cargo fmt --all
+cargo clippy -p freshell-sessions --all-targets -- -D warnings
+git add crates/freshell-sessions/src/codex_locator.rs crates/freshell-sessions/src/lib.rs crates/freshell-sessions/src/opencode_locator.rs crates/freshell-sessions/Cargo.toml
+git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot substrate, spawn-window resolve"
+```
+(Omit `Cargo.toml` from the add list if it was not modified.)
+
+---
+
+### Task 2: CodexLocator window semantics and correlation guards
+
+**Files:**
+- Modify: `crates/freshell-sessions/src/codex_locator.rs` (test module only — the Task 1 implementation is expected to already satisfy these; any test that fails RED-for-real reveals an implementation gap to fix minimally)
+- Test: same file, `mod tests`
+
+**Interfaces:**
+- Consumes: Task 1's full `CodexLocator` API and test helpers (`unique_temp_dir`, `write_rollout`, `TID`).
+- Produces: no new API — behavioral pins later tasks and reviewers rely on.
+
+- [ ] **Step 1: Write the tests (append to `mod tests`)**
+
+```rust
+    const TID2: &str = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+
+    #[test]
+    fn rollout_present_at_arm_is_never_a_candidate() {
+        let root = unique_temp_dir("snapshot");
+        // File exists BEFORE arm — the known-files snapshot must exclude it
+        // forever, regardless of any timing.
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 1_000));
+        assert!(locator.tick(1_000 + CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1); // zero candidates → keep watching
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn foreign_cwd_rollout_is_never_a_candidate() {
+        let root = unique_temp_dir("cwd");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/home/me/project-a"), 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/home/me/project-b"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn rollout_without_cwd_field_still_resolves_when_unambiguous() {
+        let root = unique_temp_dir("no-cwd");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        write_rollout(&root, "2026/07/26", TID, None);
+        let located = locator.tick(CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn two_new_rollouts_in_one_window_refuse_to_bind() {
+        let root = unique_temp_dir("ambiguous");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // Refusal marks the evaluation resolved but stays armed…
+        assert_eq!(locator.armed_count(), 1);
+        // …and a later Enter re-opens a fresh window (both files are now
+        // still absent from known_files, so still ambiguous — proves the
+        // refusal is repeatable, never a guess).
+        assert!(locator.note_submit("t1", CODEX_WINDOW_MS + 100));
+        assert!(locator.tick(CODEX_WINDOW_MS + 100 + CODEX_WINDOW_MS).is_empty());
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn same_rollout_claimed_by_two_armed_terminals_refuses_both() {
+        let root = unique_temp_dir("contested");
+        let locator = CodexLocator::new(root.clone());
+        // Two panes, SAME cwd, armed concurrently; ONE new rollout.
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(locator.arm("t2", "codex", true, None, Some("/tmp"), 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 2);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn rollout_written_lazily_after_first_enter_resolves_via_enter_window() {
+        let root = unique_temp_dir("enter");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        // Spawn window expires with zero candidates → keep watching.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // Enter long after the spawn window; rollout appears just after it.
+        let enter_at = 10 * CODEX_WINDOW_MS;
+        assert!(locator.note_submit("t1", enter_at));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let located = locator.tick(enter_at + CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn mid_turn_enter_never_reopens_a_pending_evaluation() {
+        let root = unique_temp_dir("midturn");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(locator.note_submit("t1", 100));
+        // Second Enter while the first evaluation is still pending: no-op.
+        assert!(!locator.note_submit("t1", 200));
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn non_session_meta_or_malformed_first_line_is_never_a_candidate() {
+        let root = unique_temp_dir("badmeta");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        std::fs::write(
+            dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl")),
+            format!("{{\"type\":\"event_msg\",\"payload\":{{\"id\":\"{TID}\"}}}}\n"),
+        )
+        .unwrap();
+        std::fs::write(
+            dir.join(format!("rollout-2026-07-26T08-00-01-{TID2}.jsonl")),
+            "not json at all\n",
+        )
+        .unwrap();
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn missing_sessions_root_is_tolerated_and_resolves_once_it_appears() {
+        let base = unique_temp_dir("missing-root");
+        let root = base.join("does-not-exist-yet");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty()); // no panic, keep watching
+        assert_eq!(locator.armed_count(), 1);
+        assert!(locator.note_submit("t1", 2 * CODEX_WINDOW_MS));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let located = locator.tick(3 * CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        let _ = std::fs::remove_dir_all(&base);
+    }
+
+    #[test]
+    fn flat_test_shape_rollout_resolves() {
+        // locate_codex_rollout supports flat `<id>.jsonl`; the locator's walk
+        // must too (integration fixtures seed this shape).
+        let root = unique_temp_dir("flat");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        write_rollout(&root, ".", TID, Some("/tmp"));
+        let located = locator.tick(CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+```
+
+- [ ] **Step 2: Run the new tests, observe each result honestly**
+
+Run: `cargo test -p freshell-sessions codex_locator`
+Expected: most pass against Task 1's implementation (these are pins of
+designed behavior). Any failure is a real implementation gap — fix the
+implementation minimally (never weaken a test) and note which test caught it
+in the commit message.
+
+- [ ] **Step 3: Format, lint, commit**
+
+```bash
+cargo fmt --all
+cargo clippy -p freshell-sessions --all-targets -- -D warnings
+git add crates/freshell-sessions/src/codex_locator.rs
+git commit -m "test(sessions): pin CodexLocator window semantics and correlation guards"
+```
+
+---
+
+### Task 3: Extract the shared adoption tail into `codex_identity.rs`
+
+**Files:**
+- Create: `crates/freshell-ws/src/codex_identity.rs`
+- Modify: `crates/freshell-ws/src/codex_candidate.rs` (handler delegates its adoption tail; `codex_sessions_root` moves out)
+- Modify: `crates/freshell-ws/src/lib.rs` (add `pub(crate) mod codex_identity;` after the `codex_candidate` line at `:26`; change `:42` to `pub use codex_identity::codex_sessions_root;`)
+- Test: existing `crates/freshell-ws/tests/codex_candidate_persisted.rs` and `codex_candidate_activity.rs` are the refactor guard
+
+**Interfaces:**
+- Consumes: `crate::pane_ledger::ledger_resolve_identity` (`pane_ledger.rs:699`),
+  `state.identity.upsert` / `state.identity.find_by_session_including_retired`
+  (`identity.rs:65`, `:176-188`), `state.registry.set_meta`,
+  `ActivityHub::bind_codex_session` / `attach_codex_rollout` (`activity.rs:251`, `:271`),
+  the existing broadcast frames (`TerminalSessionAssociated`, `TerminalMetaUpdated`).
+- Produces (Tasks 5-7 rely on these EXACT signatures):
+
+```rust
+// crates/freshell-ws/src/codex_identity.rs
+pub fn codex_sessions_root() -> Option<std::path::PathBuf>;           // moved verbatim
+
+pub(crate) struct CodexAdoption<'a> {
+    pub terminal_id: &'a str,
+    pub thread_id: &'a str,
+    pub rollout_path: Option<&'a std::path::Path>,
+    pub cwd: Option<&'a str>,
+}
+
+/// Bind a codex identity into every home, in the load-bearing order.
+/// Returns false (and adopts nothing) when the session is already bound to a
+/// DIFFERENT terminal — retired-INCLUSIVE (ledger A8), preserving the
+/// cross-pane hijack defense the candidate channel had.
+pub(crate) async fn adopt_codex_identity(state: &crate::WsState, a: CodexAdoption<'_>) -> bool;
+```
+
+- [ ] **Step 1: Establish the green refactor baseline**
+
+Run:
+```bash
+cargo test -p freshell-ws --test codex_candidate_persisted --test codex_candidate_activity -- --nocapture 2>&1 | tail -5
+```
+Expected: PASS (these integration tests are the refactor's safety net).
+If not green on the base, STOP and report — do not refactor on red.
+
+- [ ] **Step 2: Create `codex_identity.rs` by MOVING code (not copying)**
+
+Move from `codex_candidate.rs` into the new module:
+1. `pub fn codex_sessions_root()` (`codex_candidate.rs:102-114`) — verbatim,
+   including its doc comment.
+2. The private `fn broadcast_terminal_session_associated(...)`
+   (`codex_candidate.rs:260-296`) — verbatim, including the PINNED-ORDER doc
+   comment (`terminal.session.associated` FIRST, `terminal.meta.updated`
+   SECOND; the integration tests await them in exactly this order).
+3. The adoption tail (`codex_candidate.rs:204-250`) — reshaped into:
+
+```rust
+pub(crate) struct CodexAdoption<'a> {
+    pub terminal_id: &'a str,
+    pub thread_id: &'a str,
+    pub rollout_path: Option<&'a std::path::Path>,
+    pub cwd: Option<&'a str>,
+}
+
+pub(crate) async fn adopt_codex_identity(state: &crate::WsState, a: CodexAdoption<'_>) -> bool {
+    // Cross-pane hijack / replay defense, retired-INCLUSIVE (ledger A8): a
+    // victim's binding retires at exit, so a live-only lookup would allow
+    // replaying a DEAD pane's identity onto a fresh terminal. Copied from
+    // candidate guard 3b (codex_candidate.rs:167-186) — keep the exact
+    // comparison semantics that code uses today; re-adopting the SAME
+    // terminal is an idempotent allow.
+    if let Some(existing) = state
+        .identity
+        .find_by_session_including_retired("codex", a.thread_id)
+    {
+        if existing != a.terminal_id {
+            tracing::warn!(
+                terminal_id = %a.terminal_id,
+                thread_id = %a.thread_id,
+                "codex_adopt_rejected: session_bound_elsewhere"
+            );
+            return false;
+        }
+    }
+    // Both identity homes — different consumers (see opencode_association.rs:135-148).
+    state.identity.upsert(a.terminal_id, Some("codex"), Some(a.thread_id), a.cwd, now_ms());
+    state.registry.set_meta(
+        a.terminal_id,
+        None,
+        None,
+        Some("codex".to_string()),
+        Some(a.thread_id.to_string()),
+    );
+    // Durable ledger: binding row FIRST, pending marker delete SECOND —
+    // awaited before the broadcast (fsync-before-announce).
+    crate::pane_ledger::ledger_resolve_identity(state, a.terminal_id, "codex", a.thread_id, a.cwd)
+        .await;
+    broadcast_terminal_session_associated(state, a.terminal_id, a.thread_id, a.cwd.map(str::to_string));
+    // Activity hub (channel-deferred, safe off the dispatch path): G3 —
+    // codex.activity.updated / terminal.turn.complete carry the sessionId;
+    // G9 — the rollout reconcile lane gets its file.
+    if let Some(hub) = &state.activity {
+        hub.bind_codex_session(a.terminal_id, a.thread_id);
+        if let Some(path) = a.rollout_path {
+            hub.attach_codex_rollout(a.terminal_id, a.thread_id, path);
+        }
+    }
+    true
+}
+```
+
+IMPORTANT adaptation notes for the mover:
+- `find_by_session_including_retired`'s exact return type and comparison are
+  whatever `codex_candidate.rs:167-186` does today — transplant that code, do
+  not re-derive it. Same for the `now_ms()` helper import and the exact
+  `identity.upsert` / `set_meta` argument forms at `codex_candidate.rs:204-218`.
+- `attach_codex_rollout` at the old site passed the CLIENT's path; here the
+  path is server-discovered. The hub signature takes `&Path` — pass it through.
+
+4. Rewrite `handle_codex_candidate_persisted` so that after guards 0-3a it
+   calls `adopt_codex_identity(state, CodexAdoption { terminal_id: &msg.terminal_id, thread_id, rollout_path: Some(Path::new(&msg.rollout_path)), cwd: row.cwd.as_deref() }).await`
+   — deleting the now-duplicated guard 3b block and the old inline tail.
+   Guard 4 (`verify_rollout_path`) STAYS in the handler for now (client paths
+   are untrusted; the locator never uses it) — it is deleted with the whole
+   file in Task 7.
+5. Update `lib.rs` as listed above. `main.rs` continues to compile unchanged
+   because the `pub use ...::codex_sessions_root` re-export path is stable.
+
+- [ ] **Step 3: Verify the refactor is behavior-preserving**
+
+Run:
+```bash
+cargo test -p freshell-ws --test codex_candidate_persisted --test codex_candidate_activity
+cargo test -p freshell-ws
+```
+Expected: PASS, same tests as Step 1. (The `session_bound_elsewhere` reject
+now logs target `codex_identity` instead of `codex_candidate` — the
+integration test asserts silence-to-client, not log text, so it stays green.)
+
+- [ ] **Step 4: Format, lint, commit**
+
+```bash
+cargo fmt --all
+cargo clippy -p freshell-ws --all-targets -- -D warnings
+git add crates/freshell-ws/src/codex_identity.rs crates/freshell-ws/src/codex_candidate.rs crates/freshell-ws/src/lib.rs
+git commit -m "refactor(ws): extract adopt_codex_identity shared adoption tail from the candidate channel"
+```
+
+---
+
+### Task 4: Controller module + wiring (WsState, main.rs, terminal.rs call sites)
+
+**Files:**
+- Create: `crates/freshell-ws/src/codex_association.rs`
+- Modify: `crates/freshell-ws/src/lib.rs` (mod decl + `WsState.codex_locator` field)
+- Modify: `crates/freshell-ws/src/terminal.rs` (arm at create, submit seam, exit disarm)
+- Modify: `crates/freshell-server/src/main.rs` (construct + field + sweep)
+- Test: in-file `mod tests` in `codex_association.rs`
+
+**Interfaces:**
+- Consumes: `freshell_sessions::codex_locator::CodexLocator` (Task 1),
+  `crate::codex_identity::{codex_sessions_root, adopt_codex_identity, CodexAdoption}` (Task 3).
+- Produces (Task 5 relies on these EXACT signatures):
+
+```rust
+// crates/freshell-ws/src/codex_association.rs
+pub(crate) fn is_submit_input(data: &str) -> bool;
+pub(crate) fn maybe_arm(state: &WsState, terminal_id: &str, mode: &str,
+                        cwd: Option<&str>, resume_session_id: Option<&str>);
+pub(crate) fn note_possible_submit(state: &WsState, terminal_id: &str, data: &str);
+pub(crate) async fn drain_and_associate(state: &WsState);
+pub fn spawn_codex_locator_sweep(state: WsState, interval: std::time::Duration);
+```
+plus the new state field:
+```rust
+// crates/freshell-ws/src/lib.rs (next to opencode_locator at ~:242)
+pub codex_locator: Option<Arc<freshell_sessions::codex_locator::CodexLocator>>,
+```
+
+- [ ] **Step 1: Write the failing controller unit tests**
+
+Create `codex_association.rs` containing (initially) only the test module.
+Mirror `opencode_association.rs`'s test harness EXACTLY: copy its
+`state_with_locator(...)` helper (`opencode_association.rs:227+` builds a full
+literal `WsState` with `pane_ledger: PaneLedger::disabled()`), adapting the
+locator field to `codex_locator: Some(Arc::new(CodexLocator::new(data_home)))`
+(and `opencode_locator: None`). Tests:
+
+```rust
+    #[test]
+    fn is_submit_input_matches_enter_only_sequences() {
+        for yes in ["\r", "\n", "\r\n", "\r\r\n\n"] {
+            assert!(is_submit_input(yes), "{yes:?} should be a submit");
+        }
+        for no in ["", "hello", "hello\r\n", "\u{1b}[A"] {
+            assert!(!is_submit_input(no), "{no:?} should not be a submit");
+        }
+    }
+
+    #[test]
+    fn maybe_arm_arms_a_fresh_codex_terminal_and_ignores_others() {
+        let dir = unique_temp_dir("assoc-arm");
+        let (state, _rx) = state_with_locator(dir.clone());
+        let locator = state.codex_locator.as_ref().unwrap().clone();
+        maybe_arm(&state, "t1", "opencode", Some("/tmp"), None); // wrong mode
+        assert_eq!(locator.armed_count(), 0);
+        maybe_arm(&state, "t1", "codex", Some("/tmp"), Some("resume-id")); // resuming
+        assert_eq!(locator.armed_count(), 0);
+        maybe_arm(&state, "t1", "codex", Some("/tmp"), None); // fresh
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn note_possible_submit_feeds_only_enter_sequences() {
+        let dir = unique_temp_dir("assoc-submit");
+        let (state, _rx) = state_with_locator(dir.clone());
+        let locator = state.codex_locator.as_ref().unwrap().clone();
+        maybe_arm(&state, "t1", "codex", Some("/tmp"), None);
+        note_possible_submit(&state, "t1", "hello");
+        // Observable proof via the locator's own seam: "hello" must not have
+        // consumed the window — a direct note_submit still returns true.
+        assert!(locator.note_submit("t1", freshell_sessions::time::now_ms()));
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+```
+
+(If `opencode_association.rs`'s tests source `now_ms` differently, copy that
+exact form — the harness copy is authoritative over this sketch.)
+
+- [ ] **Step 2: Run to verify RED**
+
+Run: `cargo test -p freshell-ws codex_association`
+Expected: COMPILE ERROR (module functions and `codex_locator` field missing).
+
+- [ ] **Step 3: Implement the controller + wiring**
+
+`codex_association.rs` implementation — transplant `opencode_association.rs`
+(`:38-225`) with these substitutions; the drain body defers adoption to
+`adopt_codex_identity`:
+
+```rust
+//! Codex terminal-pane association controller (Lane B2): arm the
+//! CodexLocator at create, feed Enter submits, and on resolution adopt the
+//! identity through the shared `codex_identity::adopt_codex_identity` tail.
+//! Structure mirrors `opencode_association.rs` — deliberately (spec §5-shape
+//! duplication over a premature provider-generic controller).
+
+use crate::WsState;
+
+/// Deliberate one-line duplicate of `opencode_association::is_submit_input`.
+pub(crate) fn is_submit_input(data: &str) -> bool {
+    !data.is_empty() && data.chars().all(|c| c == '\r' || c == '\n')
+}
+
+pub(crate) fn maybe_arm(
+    state: &WsState,
+    terminal_id: &str,
+    mode: &str,
+    cwd: Option<&str>,
+    resume_session_id: Option<&str>,
+) {
+    if mode != "codex" {
+        return;
+    }
+    if let Some(locator) = &state.codex_locator {
+        locator.arm(terminal_id, mode, true, resume_session_id, cwd, now_ms());
+    }
+}
+
+pub(crate) fn note_possible_submit(state: &WsState, terminal_id: &str, data: &str) {
+    if !is_submit_input(data) {
+        return;
+    }
+    if let Some(locator) = &state.codex_locator {
+        locator.note_submit(terminal_id, now_ms());
+    }
+}
+
+pub(crate) async fn drain_and_associate(state: &WsState) {
+    let Some(locator) = state.codex_locator.clone() else {
+        return;
+    };
+    // The tick does bounded filesystem walks + first-line reads — never on
+    // an async worker (same discipline as the opencode sweep).
+    let located = match tokio::task::spawn_blocking(move || locator.tick(now_ms())).await {
+        Ok(located) => located,
+        Err(err) => {
+            tracing::warn!(error = %err, "codex_locator_tick_panicked; skipping cycle");
+            return;
+        }
+    };
+    for hit in located {
+        // Defense-in-depth rejects against registry truth (mirrors
+        // opencode_association.rs:105-133).
+        let Some(entry) = state.registry.directory().into_iter().find(|e| e.id == hit.terminal_id) else {
+            tracing::warn!(terminal_id = %hit.terminal_id, "codex_association_rejected: terminal_missing");
+            continue;
+        };
+        if entry.mode.as_deref() != Some("codex")
+            || entry.status != freshell_terminal::TerminalRunStatus::Running
+        {
+            tracing::warn!(terminal_id = %hit.terminal_id, "codex_association_rejected: terminal_not_codex_or_not_running");
+            continue;
+        }
+        if entry.resume_session_id.is_some() {
+            tracing::warn!(terminal_id = %hit.terminal_id, "codex_association_rejected: terminal_already_bound");
+            continue;
+        }
+        crate::codex_identity::adopt_codex_identity(
+            state,
+            crate::codex_identity::CodexAdoption {
+                terminal_id: &hit.terminal_id,
+                thread_id: &hit.thread_id,
+                rollout_path: Some(&hit.rollout_path),
+                cwd: entry.cwd.as_deref(),
+            },
+        )
+        .await;
+    }
+}
+
+pub fn spawn_codex_locator_sweep(state: WsState, interval: std::time::Duration) {
+    tokio::spawn(async move {
+        let mut ticker = tokio::time::interval(interval);
+        loop {
+            ticker.tick().await;
+            drain_and_associate(&state).await;
+        }
+    });
+}
+```
+
+CRITICAL adaptation instruction: the registry access pattern, the exact
+`directory()` entry field names/types, and the `now_ms()` import in the sketch
+above MUST be transplanted from `opencode_association.rs:86-169` — that file
+is the compile-truth for those forms. Where the sketch and the transplant
+disagree, the transplant wins.
+
+Wiring edits:
+
+1. `crates/freshell-ws/src/lib.rs`:
+   - `pub mod codex_association;` (next to `opencode_association` at `:36`-ish, alphabetical)
+   - Add the `codex_locator` field to `WsState` next to `opencode_locator`
+     (~`:242`), doc comment mirroring opencode's ("correlates a fresh codex
+     PTY's spawn/first-Enter with the new rollout JSONL codex writes under the
+     sessions root, so the terminal can be bound and `terminal.rs`'s generic
+     resume derivation can drive `codex resume <id>` on restart").
+   - The compiler will enumerate every literal `WsState` constructor that now
+     misses the field (association tests, other in-crate tests, main.rs).
+     Add `codex_locator: None,` everywhere except the sites Tasks 4-5 say
+     otherwise.
+2. `crates/freshell-server/src/main.rs`:
+   - Next to the opencode locator construction (`:340-345` area):
+     ```rust
+     // Lane B2 (campaign §2.3.2): server-side codex identity locator. Same
+     // sessions root the resume-time rollout locator below walks. `None`
+     // when HOME/CODEX_HOME are unresolvable — every codex_association
+     // entry point no-ops in that case.
+     let codex_locator = freshell_ws::codex_sessions_root().map(|root| {
+         std::sync::Arc::new(freshell_sessions::codex_locator::CodexLocator::new(root))
+     });
+     ```
+   - Add `codex_locator: codex_locator.clone(),` to the `WsState` literal.
+   - Next to the opencode sweep spawn (`:634-640`):
+     ```rust
+     // Lane B2: codex locator sweep — same cadence as the sibling sweeps.
+     if codex_locator.is_some() {
+         freshell_ws::codex_association::spawn_codex_locator_sweep(
+             ws_state.clone(),
+             AMPLIFIER_LOCATOR_SWEEP_INTERVAL,
+         );
+     }
+     ```
+3. `crates/freshell-ws/src/terminal.rs`:
+   - Arm at create — immediately after the opencode `maybe_arm` (`:1518-1527`):
+     ```rust
+     // Lane B2: arm the codex rollout locator for a FRESH (non-resuming)
+     // codex pane. Restore-created panes WITHOUT identity arm too — arm()
+     // gates on resume_session_id, never a restore flag (the wave-A re-arm
+     // contract).
+     crate::codex_association::maybe_arm(
+         state,
+         &terminal_id,
+         &mode,
+         resolved_cwd.as_deref(),
+         resume_session_id.as_deref(),
+     );
+     ```
+   - Submit seam — after the opencode `note_possible_submit` (`:542-546`):
+     ```rust
+     crate::codex_association::note_possible_submit(state, &input.terminal_id, &input.data);
+     ```
+   - Exit disarm — in the `ExitHook` closure (`:1354`, `:1377-1379` pattern):
+     clone `let codex_locator = state.codex_locator.clone();` next to the
+     opencode clone, and inside the closure after the opencode disarm add
+     `if let Some(locator) = &codex_locator { locator.disarm(&tid); }`.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+```bash
+cargo test -p freshell-ws codex_association
+cargo test -p freshell-ws
+cargo test -p freshell-server 2>&1 | tail -3
+```
+Expected: PASS (new tests + no regressions across the two crates).
+
+- [ ] **Step 5: Format, lint, commit**
+
+```bash
+cargo fmt --all
+cargo clippy --workspace --all-targets -- -D warnings
+git add crates/freshell-ws/src/codex_association.rs crates/freshell-ws/src/lib.rs crates/freshell-ws/src/terminal.rs crates/freshell-server/src/main.rs
+git commit -m "feat(ws): codex locator controller + arm/submit/disarm seams + 150ms sweep wiring"
+```
+(Include any other files the WsState-field compile sweep touched.)
+
+---
+
+### Task 5: drain_and_associate end-to-end behavior (identity, ledger, broadcasts, re-arm, hijack)
+
+**Files:**
+- Modify: `crates/freshell-ws/src/codex_association.rs` (test module)
+- Test: same file
+
+**Interfaces:**
+- Consumes: everything from Tasks 1-4; `PaneLedger::new(Some(dir))`,
+  `state.pane_ledger` (`pane_ledger.rs`), broadcast receiver from the harness.
+- Produces: behavioral pins (no new API).
+
+- [ ] **Step 1: Write the failing tests**
+
+Copy the two `#[tokio::test]` patterns from `opencode_association.rs:434` and
+`:530` (they spawn a REAL shell PTY via `freshell_platform::build_spawn_spec`
++ `registry.create`, then poll `drain_and_associate` up to 40× / 100 ms) and
+adapt to codex. Also copy `state_with_locator_and_ledger(data_home, ledger_dir)`
+(`opencode_association.rs` harness) so the ledger assertions run against a
+REAL `PaneLedger::new(Some(dir))`. The codex adaptations, per test:
+
+```rust
+    /// Fresh codex pane: rollout appears after arm → sweep binds identity,
+    /// writes the durable binding row, and broadcasts both frames in the
+    /// pinned order.
+    #[tokio::test]
+    async fn drain_and_associate_binds_identity_ledger_and_broadcasts() {
+        // Harness: state_with_locator_and_ledger; register a real PTY as
+        // terminal "t1" with mode "codex" and cwd <dir> exactly the way the
+        // opencode sibling test does; maybe_arm(&state, "t1", "codex",
+        // Some(&cwd), None).
+        //
+        // Then write the rollout the locator must find:
+        //   write a file <sessions_root>/2026/07/26/rollout-2026-07-26T08-00-00-<TID>.jsonl
+        //   whose first line is {"timestamp":"...","type":"session_meta",
+        //   "payload":{"id":"<TID>","cwd":"<the pane's cwd>"}}
+        // (reuse the write_rollout shape from codex_locator.rs tests inline).
+        //
+        // Poll drain_and_associate until resolution, then assert:
+        //   state.identity.session_ref_for("t1") == Some(codex/<TID>)  (provider + id)
+        //   registry directory entry for t1: resume_session_id == Some(<TID>)
+        //   ledger.lookup_by_session("codex", <TID>).unwrap().row.live_terminal_id == Some("t1")
+        //   ledger.pending_for_terminal("t1").is_none()
+        //   broadcast rx yields terminal.session.associated THEN terminal.meta.updated
+        //   (frame type assertions exactly as the opencode sibling does them)
+    }
+
+    /// Wave-A re-arm contract (the codex mirror of P1.10): a restore-created
+    /// pane WITHOUT identity (resume None) arms like a fresh pane, records a
+    /// pending marker, and resolves into the ledger — binding row first,
+    /// marker gone after.
+    #[tokio::test]
+    async fn restore_created_pane_without_identity_arms_and_resolves_into_the_ledger() {
+        // Mirror opencode_association.rs:530 verbatim, swapping: mode "codex",
+        // the rollout-file seed above instead of the sqlite row, and provider
+        // "codex" in the ledger lookups. Record the pending marker via
+        // state.pane_ledger.record_pending("t1", "codex", Some(cwd), now)
+        // before resolution, exactly as the sibling does.
+    }
+
+    /// One-writer defense survives the channel swap: a session already bound
+    /// to ANOTHER terminal (including a retired binding) is never re-adopted.
+    #[tokio::test]
+    async fn located_session_bound_elsewhere_is_rejected() {
+        // Arrange: state_with_locator; upsert identity for terminal "victim"
+        // with ("codex", <TID>) via state.identity.upsert(...), then retire it
+        // via state.identity.retire("victim") (the exit-path call —
+        // terminal.rs:1370 area shows the exact form).
+        // Register a real PTY "t1" (codex mode), arm it, seed the rollout for
+        // <TID>, poll drain_and_associate past the window.
+        // Assert: t1 gained NO identity (state.identity.session_ref_for("t1")
+        // is None) and its registry entry's resume_session_id is None.
+    }
+```
+
+Write these as REAL tests (full bodies) by transplanting the opencode sibling
+bodies — the comments above are the complete adaptation delta, and the
+opencode file is the compile-truth for harness forms. Do not invent new
+harness helpers; copy.
+
+- [ ] **Step 2: Run to verify RED-for-the-right-reason**
+
+Run: `cargo test -p freshell-ws codex_association -- --nocapture`
+Expected: the first two tests FAIL only if Tasks 1-4 left a real gap —
+otherwise they PASS immediately, which for TRANSPLANTED pins of
+already-implemented behavior is acceptable ONLY after you verify each test
+can fail: temporarily invert one core assertion per test (e.g. assert the
+identity is `None`), watch it fail, restore it. Record "verified-red by
+inversion" in the commit message. The third test (bound-elsewhere) exercises
+Task 3's new guard end-to-end for the first time — if it passes first try,
+apply the same inversion check.
+
+- [ ] **Step 3: Fix any real gaps minimally; re-run to GREEN**
+
+Run: `cargo test -p freshell-ws`
+Expected: PASS.
+
+- [ ] **Step 4: Format, lint, commit**
+
+```bash
+cargo fmt --all
+cargo clippy -p freshell-ws --all-targets -- -D warnings
+git add crates/freshell-ws/src/codex_association.rs
+git commit -m "test(ws): codex drain_and_associate binds identity+ledger+broadcasts; re-arm and hijack pins"
+```
+
+---
+
+### Task 6: Fresh-pane turn.complete carries sessionId (activity integration)
+
+**Files:**
+- Create: `crates/freshell-ws/tests/codex_locator_activity.rs`
+- Test: same file
+
+**Interfaces:**
+- Consumes: the full server harness helpers in
+  `crates/freshell-ws/tests/codex_candidate_activity.rs` (`spawn_server`,
+  `write_fake_codex()` + `codex_capture_spec()`, frame-await helpers — copy
+  them; that file is deleted next task, so this new file must be
+  self-contained) and the locator pipeline from Tasks 1-5.
+- Produces: the closing pin for the identity-less status gap — fresh codex
+  panes' `codex.activity.updated` / `terminal.turn.complete` carry
+  `sessionId` with NO client candidate frame.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `crates/freshell-ws/tests/codex_locator_activity.rs`:
+
+```rust
+//! Lane B2: a FRESH codex terminal (no resume id, NO client candidate frame)
+//! gains identity from the server-side rollout locator, and its activity
+//! frames carry the sessionId — closing the "terminals created before any
+//! candidate" status gap.
+//!
+//! Harness copied from the (retired) codex_candidate_activity.rs: real
+//! server, real socket, real PTY running a fake codex binary, CODEX_HOME
+//! pointed at a tempdir.
+```
+
+Body (single `#[tokio::test(flavor = "multi_thread")] #[cfg(unix)]`), copied
+from `codex_candidate_activity.rs::adopted_candidate_identity_reaches_codex_activity`
+(`:133+`) with this exact delta:
+1. Keep: `CODEX_HOME` tempdir env, server spawn, fake codex
+   binary/`codex_capture_spec()`, creating a FRESH codex terminal over the
+   socket, the `codex.activity.updated` await helper.
+2. DELETE the candidate-frame send. Instead, AFTER the terminal is created
+   (locator armed at create), write the rollout file the locator must find:
+   `<CODEX_HOME>/sessions/2026/07/24/rollout-2026-07-24T12-00-00-<THREAD>.jsonl`
+   with first line
+   `{"timestamp":"2026-07-24T12:00:00.000Z","type":"session_meta","payload":{"id":"<THREAD>","cwd":"<terminal cwd>"}}`
+   — the terminal's cwd is whatever the harness passed to terminal.create;
+   use that same value.
+3. Await `codex.activity.updated` carrying `sessionId == <THREAD>` (the sweep
+   runs every 150 ms in the real server; give the await the same generous
+   timeout the donor test used).
+4. Then append two task-event lines to the SAME rollout file (copy the
+   `event_msg` line shapes from `activity.rs`'s `codex_event_line` helper,
+   `:2381-2385` — `task_started` then `task_complete`, timestamps now-ish),
+   and await a `terminal.turn.complete` frame asserting
+   `provider == "codex"` AND `session_id == Some(<THREAD>)` — this proves the
+   locator's `attach_codex_rollout` handed the file to the status watcher and
+   completions are stamped.
+
+Note on determinism: the fresh terminal never receives an Enter in this test,
+so resolution rides the SPAWN window — create the rollout file promptly after
+`terminal.created` arrives. If flake appears because the 2 s spawn window
+elapses before the file lands, send a single `terminal.input` of `"\r"` after
+writing the file (Enter re-opens the window — pinned by Task 2's
+`rollout_written_lazily_after_first_enter_resolves_via_enter_window`).
+
+- [ ] **Step 2: Run to verify it fails for the right reason**
+
+Run: `cargo test -p freshell-ws --test codex_locator_activity -- --nocapture`
+Expected: with Tasks 1-5 landed this may already PASS — apply the inversion
+check (assert `session_id` is `None`, watch it fail, restore). If it fails
+for a REAL reason (e.g. `turn.complete` lacks sessionId because
+`attach_codex_rollout` wasn't reached), that is the red this task exists to
+fix — fix in the Task 3/4 modules, minimally.
+
+- [ ] **Step 3: Run to GREEN**
+
+Run: `cargo test -p freshell-ws --test codex_locator_activity`
+Expected: PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+cargo fmt --all
+cargo clippy -p freshell-ws --all-targets -- -D warnings
+git add crates/freshell-ws/tests/codex_locator_activity.rs
+git commit -m "test(ws): fresh codex pane turn.complete carries sessionId via server-side locator"
+```
+
+---
+
+### Task 7: Retire the client candidate channel
+
+**Files:**
+- Modify: `crates/freshell-ws/src/terminal.rs:511-517` (match arm → accept-and-ignore + debug log)
+- Delete: `crates/freshell-ws/src/codex_candidate.rs`
+- Delete: `crates/freshell-ws/tests/codex_candidate_persisted.rs`, `crates/freshell-ws/tests/codex_candidate_activity.rs`
+- Create: `crates/freshell-ws/tests/codex_candidate_inert.rs`
+- Modify: `crates/freshell-ws/src/lib.rs` (remove `pub(crate) mod codex_candidate;` at `:26`)
+- Modify: `crates/freshell-ws/src/invariants.rs` (doc text only)
+- Test: `crates/freshell-ws/tests/codex_candidate_inert.rs`
+
+**Interfaces:**
+- Consumes: `TerminalCodexCandidatePersisted` protocol struct — which STAYS in
+  `crates/freshell-protocol` (wire-compat: the frozen client still sends it;
+  contract inventory files stay valid).
+- Produces: the message is out of the accepted-writer set. One writer per
+  codex identity fact: the server locator (plus create-time resume ids).
+
+- [ ] **Step 1: Write the failing inert-channel test**
+
+Create `crates/freshell-ws/tests/codex_candidate_inert.rs` by copying the
+server/socket harness AND the `send_candidate_expect_silence` ping/pong helper
+from `codex_candidate_persisted.rs` (`:112-131`, before deleting it), plus its
+`CODEX_HOME` tempdir setup. Single test:
+
+```rust
+//! Lane B2 / campaign §2.3.2: terminal.codex.candidate.persisted is RETIRED
+//! as a writer. The frozen client still SENDS it (TerminalView.tsx:4009-4018),
+//! so the server must accept-and-ignore with a debug log — never an error to
+//! the client, and NEVER an identity write.
+
+#[tokio::test(flavor = "multi_thread")]
+#[cfg(unix)]
+async fn candidate_frame_is_accepted_ignored_and_writes_nothing() {
+    // 1. Spawn the real server; create a REAL fresh codex terminal t1 (fake
+    //    codex binary, exactly as the donor harness does).
+    // 2. Seed a VALID rollout on disk for thread id T (the donor's
+    //    session_meta seed) — i.e. a frame that would have passed all four
+    //    old guards.
+    // 3. Send terminal.codex.candidate.persisted{terminalId: t1,
+    //    candidateThreadId: T, rolloutPath: <seeded>, capturedAt: now}.
+    // 4. send_candidate_expect_silence-style ping/pong round trip: nothing
+    //    is sent back, the connection stays healthy.
+    // 5. Assert NO identity was written: create/list probe shows t1 with no
+    //    sessionRef and no resume_session_id (use the same identity-probe
+    //    assertion form the donor test used for its REJECT paths).
+    // 6. The terminal still works: send terminal.input "\r" and expect no
+    //    protocol error.
+}
+```
+
+IMPORTANT: seed the rollout in a cwd that does NOT match t1's cwd, or create
+the terminal with `resume_session_id` unset and the rollout BEFORE the
+terminal exists — otherwise the LOCATOR may legitimately adopt the identity
+and turn step 5 into a false failure. Simplest deterministic arrangement:
+write the rollout file BEFORE creating the terminal (arm-time snapshot then
+excludes it forever).
+
+- [ ] **Step 2: Run to verify RED**
+
+Run: `cargo test -p freshell-ws --test codex_candidate_inert -- --nocapture`
+Expected: FAIL — today the handler ADOPTS the valid candidate, so step 5's
+no-identity assertion fails. (If it fails to compile because the harness
+helpers were copied wrong, fix the copy first; the RED must be the adoption.)
+
+- [ ] **Step 3: Retire the channel**
+
+1. `crates/freshell-ws/src/terminal.rs:511-517` — replace the match arm body:
+   ```rust
+   // RETIRED (campaign §2.3.2, Lane B2): codex identity has exactly one
+   // writer — the server-side rollout locator (codex_association). The
+   // frozen client still sends this frame (TerminalView.tsx durability
+   // handler), so accept-and-ignore with a debug breadcrumb; never an
+   // error to the client, never an identity write.
+   ClientMessage::TerminalCodexCandidatePersisted(candidate) => {
+       tracing::debug!(
+           terminal_id = %candidate.terminal_id,
+           "codex_candidate_ignored: client candidate channel retired (server locator is authoritative)"
+       );
+       true
+   }
+   ```
+2. Delete `crates/freshell-ws/src/codex_candidate.rs` and its `lib.rs` mod
+   line. (`verify_rollout_path` and `is_uuid_shaped` die with it: the locator
+   proves ownership from paths it discovered itself under the sessions root,
+   with its own shape gate — the containment check existed only for
+   client-supplied paths. Coverage re-homes: ownership predicate edges live in
+   `codex_locator.rs` probe tests + `codex_reconcile.rs`'s decoy test.)
+3. Delete `crates/freshell-ws/tests/codex_candidate_persisted.rs` and
+   `crates/freshell-ws/tests/codex_candidate_activity.rs` (superseded by
+   `codex_candidate_inert.rs` and `codex_locator_activity.rs`). Dead code is
+   context poison — no commented-out remnants, no "reference" copies.
+4. `crates/freshell-ws/src/invariants.rs` — update the
+   `terminal_identity_unresolved` doc comment (`:39-47` area): the grace
+   window (`IDENTITY_RESOLUTION_GRACE_MS = 5 × AMPLIFIER_DIR_APPEAR_WINDOW_MS`
+   = 10 s) now also covers the codex locator (`CODEX_WINDOW_MS` = 2 s — same
+   magnitude, no numeric change); mention that fresh codex panes are expected
+   to resolve via `codex_association` within grace. Doc text only — no logic
+   change.
+
+- [ ] **Step 4: Run to GREEN + full-crate regression**
+
+Run:
+```bash
+cargo test -p freshell-ws --test codex_candidate_inert
+cargo test -p freshell-ws --test codex_session_ref_resume   # restore path UNCHANGED: sessionRef → `codex … resume <id>` argv
+cargo test --workspace 2>&1 | tail -5
+```
+Expected: all PASS. The `codex_session_ref_resume` run is the explicit
+"restore path unchanged" verification the spec demands.
+
+- [ ] **Step 5: Format, lint, commit**
+
+```bash
+cargo fmt --all
+cargo clippy --workspace --all-targets -- -D warnings
+git add -A crates/freshell-ws
+git commit -m "feat(ws)!: retire terminal.codex.candidate.persisted writer - accept-and-ignore with debug log
+
+One writer per codex identity fact (campaign §2.3.2): the server-side
+rollout locator is authoritative. The protocol variant stays for
+wire-compat with the frozen client; the write path, its four guards,
+and both candidate integration tests are deleted (superseded by
+codex_candidate_inert.rs and codex_locator_activity.rs)."
+```
+
+---
+
+### Task 8: E2E fixture — fake codex terminal CLI that writes a real rollout
+
+**Files:**
+- Create: `test/e2e-browser/fixtures/fake-codex-terminal.mjs`
+
+**Interfaces:**
+- Consumes: env `CODEX_HOME` (set per-server by the RustServer harness),
+  `FAKE_CODEX_TERMINAL_ARGV_LOG`, `FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH`.
+- Produces (Tasks 9-10 rely on these EXACT behaviors):
+  - fresh mode: prints `codex> `, and on FIRST stdin data writes
+    `<CODEX_HOME|~/.codex>/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl`
+    (first line `session_meta` with `payload.id` + `payload.cwd`) then prints
+    `codex: session <uuid> started`;
+  - gate: when `FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH` is set, the write
+    waits (50 ms poll) until that file exists — a never-created gate makes
+    "identity never resolves" deterministic;
+  - resume mode (`resume` anywhere in argv): prints
+    `codex: resumed session <id>`, writes NO rollout;
+  - always mirrors argv as JSONL to `FAKE_CODEX_TERMINAL_ARGV_LOG`.
+
+- [ ] **Step 1: Write the fixture (the e2e spec in Task 9 is its failing test)**
+
+```js
+#!/usr/bin/env node
+// Fake codex TERMINAL CLI for the rollout-locator e2e specs (Lane B2).
+// Mirrors fake-opencode-terminal.mjs's contract, on codex's substrate: the
+// identity artifact is a rollout JSONL under CODEX_HOME/sessions whose FIRST
+// line is the session_meta ownership record (payload.id — never the
+// filename — is the identity; payload.cwd is the locator's disambiguator).
+// - fresh: prints `codex> `; on FIRST stdin data writes the rollout (gated
+//   by FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH when set) and prints
+//   `codex: session <uuid> started`.
+// - resume (`resume` ANYWHERE in argv — resumeArgs are appended LAST after
+//   `-c` overrides): prints `codex: resumed session <id>`, writes nothing.
+// - argv mirrored to FAKE_CODEX_TERMINAL_ARGV_LOG as JSONL.
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+const argv = process.argv.slice(2)
+
+function appendArgvLog() {
+  const logPath = process.env.FAKE_CODEX_TERMINAL_ARGV_LOG
+  if (!logPath) return
+  fs.mkdirSync(path.dirname(logPath), { recursive: true })
+  fs.appendFileSync(logPath, `${JSON.stringify({ pid: process.pid, t: Date.now(), argv })}\n`)
+}
+appendArgvLog()
+
+function codexSessionsDir() {
+  const home = process.env.CODEX_HOME && process.env.CODEX_HOME.length > 0
+    ? process.env.CODEX_HOME
+    : path.join(process.env.HOME ?? '', '.codex')
+  const now = new Date()
+  const yyyy = String(now.getUTCFullYear())
+  const mm = String(now.getUTCMonth() + 1).padStart(2, '0')
+  const dd = String(now.getUTCDate()).padStart(2, '0')
+  return path.join(home, 'sessions', yyyy, mm, dd)
+}
+
+function writeRollout(threadId) {
+  const now = new Date()
+  const ts = now.toISOString().slice(0, 19).replace(/:/g, '-')
+  const dir = codexSessionsDir()
+  fs.mkdirSync(dir, { recursive: true })
+  const file = path.join(dir, `rollout-${ts}-${threadId}.jsonl`)
+  const meta = {
+    timestamp: now.toISOString(),
+    type: 'session_meta',
+    payload: { id: threadId, cwd: process.cwd() },
+  }
+  fs.writeFileSync(file, `${JSON.stringify(meta)}\n`)
+}
+
+const resumeIndex = argv.indexOf('resume')
+if (resumeIndex !== -1) {
+  const sessionId = argv[resumeIndex + 1] ?? ''
+  process.stdout.write(`codex: resumed session ${sessionId}\r\n`)
+} else {
+  process.stdout.write('codex> \r\n')
+  let wrote = false
+  process.stdin.on('data', () => {
+    if (wrote) return
+    wrote = true
+    const threadId = crypto.randomUUID()
+    const finish = () => {
+      writeRollout(threadId)
+      process.stdout.write(`codex: session ${threadId} started\r\n`)
+    }
+    const gate = process.env.FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH
+    if (gate) {
+      const poll = setInterval(() => {
+        if (fs.existsSync(gate)) {
+          clearInterval(poll)
+          finish()
+        }
+      }, 50)
+    } else {
+      finish()
+    }
+  })
+}
+process.stdin.resume()
+```
+
+- [ ] **Step 2: Smoke the fixture standalone (cheap sanity, not the real test)**
+
+Run:
+```bash
+cd /home/dan/code/freshell/.worktrees/codex-rollout-locator
+CODEX_HOME=/tmp/fake-codex-home-$$ node test/e2e-browser/fixtures/fake-codex-terminal.mjs <<'EOF'
+hello
+EOF
+find /tmp/fake-codex-home-$$ -name 'rollout-*.jsonl' -exec head -c 200 {} \; ; rm -rf /tmp/fake-codex-home-$$
+```
+Expected: prints `codex> `, then `codex: session <uuid> started`, and the
+find shows one rollout whose first line is the `session_meta` JSON with the
+uuid and cwd. (stdin EOF ends the process.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add test/e2e-browser/fixtures/fake-codex-terminal.mjs
+git commit -m "test(e2e): fake codex terminal fixture that writes a real gated rollout JSONL"
+```
+
+---
+
+### Task 9: E2E — fresh codex pane gains server-side identity and resumes across restart
+
+**Files:**
+- Create: `test/e2e-browser/specs/codex-terminal-restore-rust.spec.ts`
+- Modify: `test/e2e-browser/playwright.config.ts` (TWO edits — see step 3)
+
+**Interfaces:**
+- Consumes: `test/e2e-browser/specs/opencode-terminal-restore-rust.spec.ts`
+  (the donor — copy its helper set verbatim; helpers are per-spec-owned by
+  convention, copied not imported), the Task 8 fixture, the RustServer
+  harness (`createE2eServerHandle`, isolated HOME, ephemeral port).
+- Produces: the end-to-end user-story proof: fresh codex terminal → identity
+  captured SERVER-SIDE with no client candidate → restart → relaunched with
+  `codex … resume <id>`.
+
+- [ ] **Step 1: Write the spec (this IS the failing e2e test)**
+
+Create the spec by copying `opencode-terminal-restore-rust.spec.ts` wholesale
+and applying this delta (everything not listed stays structurally identical —
+boot, harness waits, leaf-diff pane identification, `persist/flushNow`,
+restart-same-port, negative control):
+
+1. Header comment: codex Lane B2; rust-only (legacy has no codex terminal
+   locator).
+2. Fixture install:
+   ```ts
+   const FAKE_CODEX_TERMINAL_SOURCE = path.resolve(__dirname, '../fixtures/fake-codex-terminal.mjs')
+   // installFakeCli(source, 'codex', binDir) — copy the donor's helper.
+   ```
+3. Server env: `CODEX_CMD: fakeCodexPath`,
+   `FAKE_CODEX_TERMINAL_ARGV_LOG: argLogPath` (no gate var — this is the
+   positive path).
+4. `setupHome` seeds `settings.codingCli.enabledProviders: ['codex']`.
+5. Pane open: picker button `/^Codex CLI$/i` (manifest label is "Codex CLI" —
+   `/^Codex$/` matches nothing), then the Starting-directory combobox Enter,
+   exactly the donor's `openOpencodePaneAndGetLeaf` flow renamed for codex;
+   wait for `codex> ` in the buffer.
+6. Submit: type `hello codex` + Enter → fixture writes the rollout and prints
+   `codex: session <uuid> started`.
+7. Identity assertion (the server-side capture proof): poll
+   `leaf.content.sessionRef?.sessionId ?? leaf.content.resumeSessionId` until
+   it matches `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i`
+   and `sessionRef.provider === 'codex'`. NO client candidate can exist here:
+   the Rust server never emits `terminal.codex.durability.updated`, so the
+   frozen client's candidate sender never fires — identity arriving at all IS
+   the server-locator proof. State this in a comment.
+8. Restart + reload (donor flow). Post-restart positive proofs (BOTH):
+   - buffer contains `codex: resumed session <id>`;
+   - the argv log's post-restart entries contain the ADJACENT PAIR
+     `resume, <id>`:
+     ```ts
+     const entries = await readArgvLog(argLogPath)
+     const resumed = entries.some((e) => {
+       const i = e.argv.indexOf('resume')
+       return i !== -1 && e.argv[i + 1] === associatedSessionId
+     })
+     expect(resumed).toBe(true)
+     ```
+     (codex's `resumeArgs: ["resume", "{{sessionId}}"]` is a subcommand
+     appended LAST — never assert `argv[0]`.)
+9. Negative control (donor's shape): a second codex pane that NEVER submits —
+   the fixture writes no rollout, so after restart it restores fresh:
+   `sessionRef`/`resumeSessionId` both undefined, status not `error`, fresh
+   `codex> ` in the buffer.
+
+- [ ] **Step 2: Run to verify RED-then-GREEN honestly**
+
+The spec is new; with Tasks 1-7 landed it should pass. Prove it tests the
+right thing exactly like the wall convention does: first run it, and if it
+passes first try, re-run once with the gate env
+(`FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH` pointed at a never-created path)
+temporarily added to the server env — the identity poll in step 7 must then
+time out (RED), proving the assertion depends on the real locator resolution.
+Remove the temporary gate. Run:
+```bash
+cd /home/dan/code/freshell/.worktrees/codex-rollout-locator
+npx playwright test -c test/e2e-browser/playwright.config.ts --project=rust-chromium codex-terminal-restore-rust
+```
+Expected: 1 passed (after the deliberate gate-RED check).
+Note: e2e builds `freshell-server` in release mode on first run — allow a
+long timeout (10+ min) for the first invocation.
+
+- [ ] **Step 3: Register the spec (two edits, both required)**
+
+In `test/e2e-browser/playwright.config.ts`:
+1. Add to `RUST_ONLY_SPECS` (`:81-130`):
+   ```ts
+   // Lane B2 codex rollout locator: rust-only (legacy has no codex terminal
+   // locator); imports the RustServer-backed harness for same-port restart.
+   /codex-terminal-restore-rust\.spec\.ts$/,
+   ```
+2. Repeat the same regex (with the same comment) in the `rust-chromium`
+   project's explicit `testMatch` array (`:183-287`). Do NOT add to
+   `MATRIX_SPECS`.
+Re-run the Step 2 command; also run
+`npx playwright test -c test/e2e-browser/playwright.config.ts --project=chromium --list | grep -c codex-terminal-restore`
+Expected: rust-chromium runs it (1 passed); the chromium `--list` count is 0
+(ignored in match-all projects).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add test/e2e-browser/specs/codex-terminal-restore-rust.spec.ts test/e2e-browser/playwright.config.ts
+git commit -m "test(e2e): fresh codex pane gains server-side identity and resumes via 'codex resume <id>' across restart"
+```
+
+---
+
+### Task 10: E2E — SIGKILL inside the codex locator window leaves a durable fresh-by-race marker
+
+**Files:**
+- Modify: `test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts`
+
+**Interfaces:**
+- Consumes: that file's own helpers (`installFakeCli(binDir, name, source)` —
+  NOTE the argument order differs from the Task 9 donor; `seedConfig()`,
+  `openCliPane`, `listFiles`, `within5s`, `selectShellIfPickerShowing`), the
+  Task 8 fixture with `FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH`.
+- Produces: the codex fresh-by-race durability pin — pending marker survives
+  SIGKILL, zero binding rows.
+
+- [ ] **Step 1: Write the failing-shaped test**
+
+Append a sibling of the opencode test at `:194` (copy its body verbatim,
+then apply this delta):
+
+```ts
+  test('SIGKILL inside the codex locator window leaves a durable fresh-by-race marker', async ({ page, e2eServerKind }) => {
+    expect(e2eServerKind).toBe('rust')
+    // Delta from the opencode sibling above:
+    // - fixture: fake-codex-terminal.mjs installed as 'codex'
+    //   (this file's installFakeCli argument order: (binDir, name, source)).
+    // - env: CODEX_CMD + FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH pointed at a
+    //   path we NEVER create — the rollout deterministically never lands, so
+    //   identity provably cannot resolve pre-kill and the pending marker is
+    //   the only evidence.
+    // - pane: openCliPane(page, /^Codex CLI$/i), then click the pane's xterm
+    //   and type + Enter (the codex locator marker exists from spawn — codex
+    //   is already in MARKER_MODES — but the typed Enter also opens the
+    //   locator window, making this a true inside-the-window kill).
+    // - assertions: identical — pending/*.json survives restartAbrupt(),
+    //   bindings/ has zero *.json.
+  })
+```
+
+Write the FULL body (no elisions) by transplanting `:194-255` with the delta
+above.
+
+- [ ] **Step 2: Run it**
+
+```bash
+npx playwright test -c test/e2e-browser/playwright.config.ts --project=rust-chromium pane-ledger-restart-rust
+```
+Expected: ALL tests in the file pass, including the new codex one and the
+pre-existing codex pending-marker test at `:149`. The new test's premise is
+made deterministic by the never-created gate (mirror of the opencode
+DETERMINISM note). If the new test passes first try, verify it can fail:
+temporarily flip the bindings assertion to `toBeGreaterThan(0)`, watch it
+fail, restore.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts
+git commit -m "test(e2e): codex SIGKILL-inside-locator-window leaves durable fresh-by-race pending marker"
+```
+
+---
+
+### Task 11: Full verification, contract-wall pin evaluation, push (STOP before PR)
+
+**Files:**
+- Possibly modify: `test/e2e-browser/specs/restore-contract-wall-rust.spec.ts` (pin deletions ONLY if the wall run demands them)
+
+**Interfaces:**
+- Consumes: everything above.
+- Produces: green evidence across all gates; pushed branch; NO PR.
+
+- [ ] **Step 1: Rust gates (the CI-exact commands)**
+
+```bash
+cd /home/dan/code/freshell/.worktrees/codex-rollout-locator
+cargo fmt --all --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
+```
+Expected: all clean/PASS. Fix anything real; never `#[allow]` your way past
+clippy without a stated reason in the code comment.
+
+- [ ] **Step 2: Coordinated TS suites**
+
+```bash
+FRESHELL_TEST_SUMMARY="lane B2 codex rollout locator - full verification" env -u FRESHELL_BIND_HOST npm test
+```
+Expected: PASS. If the coordinator gate is held by a sibling lane, WAIT (check
+`npm run test:status`) — never kill a foreign holder. If the worktree lacks
+deps: `npm ci` and, if tsx is missing, `ln -s ../node_modules/tsx node_modules/tsx`.
+
+- [ ] **Step 3: E2E suite for the touched specs + the contract wall**
+
+```bash
+npx playwright test -c test/e2e-browser/playwright.config.ts --project=rust-chromium \
+  codex-terminal-restore-rust pane-ledger-restart-rust codex-terminal-bounce-rust compound-restart-rust
+npx playwright test -c test/e2e-browser/playwright.config.ts --project=rust-chromium restore-contract-wall-rust
+```
+Expected for the first command: all pass — `codex-terminal-bounce-rust` and
+`compound-restart-rust` pin `not.toContain('terminal_identity_unresolved')`,
+which the locator must keep green.
+
+Contract-wall interpretation (Playwright semantics: a `test.fail`-pinned test
+that PASSES is reported as a hard failure — that is the flip signal):
+- Pins `:1679` (claude-shaped) and `:1803` (opencode-shaped) are expected to
+  STILL FAIL-AS-PINNED — this lane's locator is codex-scoped. Leave them.
+- If any pinned test reports "passed unexpectedly", DELETE that test's
+  `test.fail(...)` line (nothing else), re-run the wall, and name the flipped
+  pin in the commit message.
+- The un-pinned codex contracts `:738` (sessionRef-bound codex resumes with
+  `resume <id>` after SIGKILL) and `:925` (freshcodex rebind) MUST still pass
+  — any regression here is a stop-the-line bug in this lane.
+
+- [ ] **Step 4: Commit any pin flips (only if Step 3 demanded them)**
+
+```bash
+git add test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
+git commit -m "test(e2e): flip restore-contract-wall pins now green under the codex server-side locator"
+```
+
+- [ ] **Step 5: Push the branch and STOP**
+
+```bash
+git log --oneline origin/main..HEAD          # review the task commits
+git push -u origin "$(git branch --show-current)"
+```
+Then STOP — PR creation is NOT approved. Report: branch name, the commit
+list, and the proof summary (cargo gates, coordinated suite result, e2e
+results incl. wall disposition, and the scope-fence note that REST-lane
+(freshell-freshagent) arming is deferred to Lane B4 by the wave's fence).
+
+---
+
+## Self-Review (performed at plan-writing time)
+
+**1. Spec coverage:**
+- Server-side rollout-appear locator, arm at create, correlation window per
+  opencode precedent (spawn window + submit extension) → Tasks 1-2, 4.
+- Reuse-don't-duplicate the wave-2 watcher → Premise Correction 2: discovery
+  cannot ride the per-file status watcher (verified structural fact); the
+  locator polls only-while-armed and hands the discovered path to the
+  EXISTING watcher via `attach_codex_rollout` (Task 3/6) — one file-watcher,
+  two consumers downstream, parsers' ownership predicate reused.
+- Ledger pending marker at spawn → already live (`MARKER_MODES` includes
+  "codex", `terminal.rs:101`/`:1604`); binding row at resolve → Task 3
+  (`ledger_resolve_identity` inside adopt), pinned by Task 5 + Task 10.
+- Broadcasts `terminal.session.associated` + `terminal.meta.updated` (pinned
+  order) → Task 3 (moved verbatim), pinned by Task 5.
+- Activity-hub identity bind → Task 3 (`bind_codex_session` — the real name
+  of the spec's "bind_terminal_session path"), pinned by Task 6.
+- Retire candidate channel: accept-and-ignore + debug log, never an error;
+  write path deleted; dead code removed; reusable helpers kept only where
+  reused → Task 7 (protocol variant retained for wire-compat; containment
+  helper deleted WITH its only consumer; ownership-predicate coverage
+  re-homed).
+- Invariants reflect the locator → Task 7 step 3.4.
+- Restore path (sessionRef → codex resume argv) unchanged → Task 7 step 4
+  runs `codex_session_ref_resume` explicitly; Task 9 proves it end-to-end.
+- Re-arm on restore-created identity-less panes → arm() gates on
+  resume_session_id only (Task 1 gate test), controller comment (Task 4),
+  end-to-end pin (Task 5 test 2).
+- TDD red-first list: locator-resolves-fresh (T1), SIGKILL-inside-window
+  fresh-by-race pending-marker-no-binding (T10 e2e + T5 ledger pins),
+  resolve-after-submit-extension (T2), candidate inert (T7), binding row at
+  resolve (T5), turn.complete carries sessionId (T6). E2E fixture + fresh →
+  no-candidate → restart → `resume <id>` (T8-9). Pin flips (T11).
+- Scope fence → Global Constraints + Premise Correction 6 (freshell-freshagent
+  untouched; REST-lane arming named in the final report, not silently
+  dropped).
+
+**1b. No silent deferrals:** Every user-facing behavior lands with production
+code and a real end-to-end proof (Task 9 drives a real browser, real server,
+real PTY, restart, argv evidence). The fixtures are test doubles for the
+external codex binary only — the identity substrate they write (rollout JSONL
+with session_meta first line) is the REAL production artifact shape, verified
+against the repo's own real-data documentation (`durability.rs:9`,
+`codex_reconcile.rs` tests). REST-created panes not arming is a spec-directed
+scope fence (Lane B4 owns those crates), surfaced loudly in Task 11's report
+— not silently deferred. No other requirement is stubbed.
+
+**2. Placeholder scan:** Two tests in Task 5 and one in Task 10 direct
+transplantation from a named donor test with a complete, enumerated delta
+instead of repeating ~80-line harness bodies whose exact forms (55-field
+WsState literals) only the donor file can supply — each names the donor
+file:line and every changed element, and instructs "the transplant wins" on
+any conflict. No TBDs, no "handle edge cases", no undefined names: every
+type/function a later task uses is defined in an earlier task's Interfaces
+block or exists on main at a cited file:line.
+
+**3. Type consistency:** `Located { terminal_id, thread_id, rollout_path, cwd }`
+(T1) is consumed field-for-field in T4's drain; `CodexAdoption`/`adopt_codex_identity`
+(T3) match T4's call site; `spawn_codex_locator_sweep(WsState, Duration)` (T4)
+matches main.rs wiring; `with_config(PathBuf, i64)` has no pre-epsilon
+anywhere; fixture env names (`FAKE_CODEX_TERMINAL_ARGV_LOG`,
+`FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH`) are identical across T8/T9/T10.

From 0303db51b91b101d66a9adae462683691c79a28b Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 03:30:15 -0700
Subject: [PATCH 05/87] docs(plan): fix reconcile-client-adoption plan per
 load-bearing assumption validation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

9 falsified assumptions fixed: reconcileEpoch re-fire mechanism for same-createRequestId
verdict folds; error-frame/reconnect fallback instead of assuming results always arrive;
lease code relocated to crates/freshell-terminal/src/registry.rs; Task 6 drops the
redundant ledger write (already on the create path); deferral awaits the index sweep
(warming banner expected on cold boots); TTL rebased as explicit env-tunable backstop;
fold ownership via existing ws.onMessage; client test paths corrected to
test/unit/client/; playwright rust-chromium spec registration added. Ledger:
.the-usual-logs/reconcile-client-adoption/load-bearing-ledger.md

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../2026-07-26-reconcile-client-adoption.md   | 340 ++++++++++++------
 1 file changed, 230 insertions(+), 110 deletions(-)

diff --git a/docs/plans/2026-07-26-reconcile-client-adoption.md b/docs/plans/2026-07-26-reconcile-client-adoption.md
index 7f0ae5f79..97ccdde6a 100644
--- a/docs/plans/2026-07-26-reconcile-client-adoption.md
+++ b/docs/plans/2026-07-26-reconcile-client-adoption.md
@@ -28,7 +28,7 @@ Every task's requirements implicitly include this section.
   `🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)` + `Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>`.
 
 **Scope fence (sibling lanes are working concurrently on other branches):**
-- You own: `src/lib/ws-client.ts`, client verdict folding (`App.tsx` recovery region + new `src/lib/pane-reconcile.ts` + minimal support edits in `panesSlice.ts` / `paneTypes.ts` / `terminal-restore.ts` / `TerminalView.tsx` / `shared/ws-protocol.ts` + the new `DeadSessionPanel` component), `crates/freshell-ws/src/reconcile.rs`, `crates/freshell-ws/src/existence.rs` (+ the concrete probe in `crates/freshell-server/src/existence.rs` for warming/provider-unavailable), `crates/freshell-ws/src/terminal.rs` create/reconcile paths, `crates/freshell-ws/src/registry.rs` reservation, and the ledger WRITE at respawn-winner bind (the wave-A ledger API).
+- You own: `src/lib/ws-client.ts`, client verdict folding (`App.tsx` recovery region + new `src/lib/pane-reconcile.ts` + minimal support edits in `panesSlice.ts` / `paneTypes.ts` / `terminal-restore.ts` / `TerminalView.tsx` / `shared/ws-protocol.ts` + the new `DeadSessionPanel` component), `crates/freshell-ws/src/reconcile.rs`, `crates/freshell-ws/src/existence.rs` (+ the concrete probe in `crates/freshell-server/src/existence.rs` for warming/provider-unavailable), `crates/freshell-ws/src/terminal.rs` create/reconcile paths, `crates/freshell-terminal/src/registry.rs` reservation, and the REGISTRY sessionRef→terminalId binding at respawn-winner bind (the ledger write already exists on the create path — `terminal.rs:1575-1603` — this lane does NOT add one).
 - Do NOT touch: `codex_candidate.rs` / rollout locator (Lane B2), `tabs_snapshots.rs` + tabs-snapshot recovery UI (Lane B3), `freshell-freshagent` crates + fresh-agent verdict support (Lane B4). `reconcile.rs` keeps rejecting `kind: fresh-agent` (`reconcile.rs:169` `unsupported_kind`) this slice — keep edits near that dispatch match-arm minimal and tight (B4 merges a new arm there; expect a trivial merge conflict). No kimi/gemini work.
 
 **Council-gated behavioral invariants (from the restart-resilience analysis §4.3 — every rule here is binding):**
@@ -38,7 +38,7 @@ Every task's requirements implicitly include this section.
 4. A known provider with no home on this machine is NOT warming — it gets `error` with `reason: "provider_unavailable"`, immediately (no deferral).
 5. Under a post-restart storm, warming notices batch into ONE banner ("Waiting for session index — N panes"), same anti-N-modal rule as `dead_session`.
 6. Multi-client single-flight is per `sessionRef`, not just per `createRequestId`. The first respawn winner binds `sessionRef → new terminalId` (registry + ledger); every other client's reconcile/create for the same `sessionRef` — regardless of `createRequestId` — receives `attach {terminalId}` to the winner.
-7. The sessionRef reservation is a liveness-bound LEASE: released on spawn complete (bind), spawn fail (error), or holder connection death; a wall-clock TTL (~2× spawn budget) backstops a hung holder. TTL expiry is KILL-BEFORE-RELEASE: kill the holder's in-flight spawn and confirm death before releasing; if the kill cannot be confirmed, the lease is NOT released (fail loud, hold closed).
+7. The sessionRef reservation is a liveness-bound LEASE: released on spawn complete (bind), spawn fail (error), or holder connection death; a wall-clock TTL (an explicit 20s backstop constant, env-tunable — NOT derived from any spawn budget; see Tasks 5/6) backstops a hung holder. TTL expiry is KILL-BEFORE-RELEASE: kill the holder's in-flight spawn (via the registry's PTY handle — group-kill discipline, never a raw single-pid SIGKILL) and confirm death before releasing; if the kill cannot be confirmed, the lease is NOT released (fail loud, hold closed). NOTE (refined mechanics): the DOMINANT hung-spawn case — stuck in `spawn_blocking` (`terminal.rs:1411-1415`) — is pid-less and resolves HOLD-CLOSED or via holder-connection-death release; the kill path covers only the spawn-returned→complete window.
 8. Losers get an `error` frame `{code: SESSION_RESERVED, retryAfterMs}`; the client retries via a bounded re-drive loop whose total window exceeds the lease TTL + margin. Exhaustion resolves AUTOMATICALLY against current state: binding exists → silently attach; winner failed → dead_session/fresh-recovery flow with a visible notice. Never a dead button, never a silent wedge, never a duplicate.
 9. A ≥2-live-PTYs-per-sessionRef backstop detector alarms (ERROR-level invariant log).
 10. `corrected: true` on any verdict is ALWAYS user-visible (a pane notice), never a silent identity switch. `duplicate` on an attach verdict is a non-destructive "duplicate detected and ignored" notice; the client is never switched off its live terminal (I6).
@@ -65,8 +65,9 @@ Every task's requirements implicitly include this section.
 - Modify: `crates/freshell-ws/src/reconcile.rs` — verdict derivation: `error` reasons, sessionRef-level attach, keep the `unsupported_kind` arm untouched.
 - Modify: `crates/freshell-ws/src/existence.rs` — `SessionExistence::ProviderUnavailable` variant.
 - Modify: `crates/freshell-server/src/existence.rs` — concrete probe returns `ProviderUnavailable` when a known provider's session root is missing.
-- Modify: `crates/freshell-ws/src/registry.rs` — sessionRef lease + binding map + duplicate-PTY detector.
-- Modify: `crates/freshell-ws/src/terminal.rs` — bounded warming deferral in `handle_pane_reconcile`; lease acquire/release in the create path; ledger `record_binding` at winner bind.
+- Modify: `crates/freshell-terminal/src/registry.rs` — sessionRef lease + binding map + duplicate-PTY detector (`TerminalRegistry` struct :409, impl :485; `keyed_create_inflight` field :452, init :502; `begin_keyed_create` :1599-1604, `end_keyed_create` :1608-1613; existing duplicate detector `warn_on_duplicate_live_ptys` :1618).
+  PLACEMENT NOTE: dep direction is freshell-ws → freshell-terminal → freshell-protocol. The lease/binding map/detector live in freshell-terminal (`SessionLocator` comes from freshell-protocol, which freshell-terminal already deps); anything needing `TerminalIdentityRegistry` (`crates/freshell-ws/src/identity.rs`) stays in freshell-ws.
+- Modify: `crates/freshell-ws/src/terminal.rs` — bounded warming deferral in `handle_pane_reconcile`; lease acquire/release in the create path; REGISTRY sessionRef→terminalId binding at winner bind (the ledger `record_binding` write already exists on the create path — `terminal.rs:1575-1603`).
 - Modify: `crates/freshell-ws/tests/pane_reconcile.rs` — updated retry-era tests + warming tests.
 - Create: `crates/freshell-ws/tests/session_ref_singleflight.rs` — D8 wire-level tests.
 
@@ -82,10 +83,11 @@ Every task's requirements implicitly include this section.
 - Create: `src/components/DeadSessionPanel.tsx` — the ONE batched adjudication panel.
 - Create: `src/components/ReconcileWarmingBanner.tsx` — the ONE warming banner (small; may be folded into App if <40 lines, implementer's call, but it must remain a single banner).
 
-**Tests (client/e2e):**
-- Create: `test/unit/lib/pane-reconcile.test.ts`, `test/unit/store/panesSlice.reconcile.test.ts`, `test/unit/lib/ws-client.reconcile.test.ts`, `test/unit/App.reconcile-adoption.test.tsx`, `test/unit/components/DeadSessionPanel.test.tsx`, `test/unit/components/TerminalView.session-reserved.test.tsx`.
+**Tests (client/e2e):** (client tests follow the live convention `test/unit/client/{lib,store,components}/`; existing suites live there too — e.g. `test/unit/client/store/panesSlice.test.ts`; `test/unit/lib/terminal-restore.test.ts` is the one legacy-bucket exception, correct as-is)
+- Create: `test/unit/client/lib/pane-reconcile.test.ts`, `test/unit/client/store/panesSlice.reconcile.test.ts`, `test/unit/client/lib/ws-client.reconcile.test.ts`, `test/unit/client/components/App.reconcile-adoption.test.tsx`, `test/unit/client/components/DeadSessionPanel.test.tsx`, `test/unit/client/components/TerminalView.session-reserved.test.tsx`.
 - Modify: `test/e2e-browser/specs/restore-contract-wall-rust.spec.ts` — flip the P1.7 pin (:1877-1880), update the double-restart guard (:2042).
 - Create: `test/e2e-browser/specs/reconcile-client-adoption-rust.spec.ts`.
+- Modify: `test/e2e-browser/playwright.config.ts` — register the new spec in `RUST_ONLY_SPECS` (:81+) AND the `rust-chromium` project's explicit `testMatch` (:183+).
 
 ---
 
@@ -117,7 +119,7 @@ Expected: all green (2dfbba58 is a merged main state).
 - [ ] **Step 3: Focused client baseline (cheap sanity, not the coordinated suite)**
 
 ```bash
-npm run test:vitest -- run test/unit/lib/terminal-restore.test.ts test/unit/store/panesSlice.test.ts
+npm run test:vitest -- run test/unit/lib/terminal-restore.test.ts test/unit/client/store/panesSlice.test.ts
 ```
 Expected: PASS. (The full coordinated suite runs in Task 15; the workspace stage already verified base green.)
 
@@ -222,14 +224,26 @@ let warming = |vs: &[PaneVerdict]| vs.iter().any(|v|
     matches!(v.verdict, ReconcileVerdict::Error)
         && v.reason.as_deref() == Some("index_warming"));
 if warming(&verdicts) {
-    // SINGLE deferral: release any locks held for derivation, wait the
-    // budget once, re-derive once. Never loop.
-    tokio::time::sleep(Duration::from_millis(state.reconcile_deferral_budget_ms)).await;
+    // SINGLE deferral: release any locks held for derivation, wait ONCE
+    // bounded by the budget, re-derive once. Never loop.
+    //
+    // PREFERRED shape: AWAIT the in-flight index sweep completion, bounded
+    // by the budget (e.g. tokio::time::timeout(budget, index.sweep_complete())
+    // or whatever completion signal the SessionIndex API exposes) — a single
+    // bounded await, NOT a blind fixed sleep. Inspect the SessionIndex API
+    // first; if no sweep-completion signal is observable, fall back to:
+    //     tokio::time::sleep(Duration::from_millis(state.reconcile_deferral_budget_ms)).await;
+    // The budget knob default stays 2000ms (council-pinned single deferral).
+    defer_bounded(&state).await;
     verdicts = derive_verdicts(&rebuild_deps(&state), &request.panes);
 }
 // send pane.reconcile.result as before
 ```
-IMPORTANT: `derive_verdicts` is a pure read over `ReconcileDeps { registry, identity, existence }` — make sure no registry/identity lock is held across the `sleep` (rebuild the deps after the await; the existing call site shows how they are built).
+IMPORTANT: `derive_verdicts` is a pure read over `ReconcileDeps { registry, identity, existence }` — make sure no registry/identity lock is held across the await (rebuild the deps after the await; the existing call site shows how they are built).
+
+HONEST EXPECTATION (evidence: truly-cold index scan is minutes — `directory_index.rs:574,1073`; typical warm restart ≈2.0–3.5s, dominated by the opencode sqlite marker query at 1.16–2.66s every boot): the 2s single deferral will often NOT be enough. The warming banner is EXPECTED on cold boots (not exceptional), and the manual Retry affordance (Task 13) is the recovery path. opencode cache persistence is an out-of-scope follow-up.
+
+STALL SCOPE (verified, with caveat): the inline deferral stalls only THIS connection's `tokio::select!` loop (inbound + fan-out + ping arm). Keepalive interval is 30s, so nothing false-kills; `conn_rx` is unbounded, so the stall is delay-only. CAUTION: the bounded output queue can evict frames under heavy output during the stall (`backpressure.rs:30-33`) — acceptable because reconcile precedes attaches post-restart, but keep the stall bounded (never exceed the budget).
 
 - [ ] **Step 4: Run the full crate test suite**
 
@@ -322,12 +336,15 @@ git commit -m "feat(ws): provider_unavailable existence state yields immediate h
 ### Task 4: Server — sessionRef-level attach in verdict derivation + duplicate-PTY backstop detector
 
 **Files:**
-- Modify: `crates/freshell-ws/src/registry.rs`
+- Modify: `crates/freshell-terminal/src/registry.rs` (`TerminalRegistry` struct :409, impl :485; existing duplicate detector `warn_on_duplicate_live_ptys` :1618 — extend/mirror its pattern)
 - Modify: `crates/freshell-ws/src/reconcile.rs`
-- Test: `crates/freshell-ws/tests/pane_reconcile.rs` and `registry.rs` `#[cfg(test)]`
+- Possibly modify: `crates/freshell-ws/src/identity.rs` (if the lookup goes through the identity registry — see Step 3)
+- Test: `crates/freshell-ws/tests/pane_reconcile.rs` and `crates/freshell-terminal/src/registry.rs` `#[cfg(test)]`
+
+PLACEMENT NOTE: dep direction is freshell-ws → freshell-terminal → freshell-protocol. Registry-side code lives in freshell-terminal (`SessionLocator` comes from freshell-protocol, which freshell-terminal already deps); anything needing `TerminalIdentityRegistry` (`crates/freshell-ws/src/identity.rs`) stays in freshell-ws.
 
 **Interfaces:**
-- Consumes: the identity registry (`ReconcileDeps.identity`) mapping live terminals ↔ `SessionLocator` (stamping landed in commit 80772ff2 — locate the live lookup with `rg -n "SessionLocator" crates/freshell-ws/src/identity.rs crates/freshell-ws/src/registry.rs`).
+- Consumes: the identity registry (`ReconcileDeps.identity`) mapping live terminals ↔ `SessionLocator` (stamping landed in commit 80772ff2 — locate the live lookup with `rg -n "SessionLocator" crates/freshell-ws/src/identity.rs crates/freshell-terminal/src/registry.rs`). VALIDATOR-CORRECTED FACT: registry rows do NOT carry a `session_ref` field usable here — `inventory()` hardcodes `session_ref: None` (`registry.rs:269`; the :834/:889 mentions are attach params). Row identity = `mode` + `resume_session_id: Option<String>`.
 - Produces: `TerminalRegistry::live_terminal_for_session_ref(&SessionLocator) -> Option<String>`; `derive_verdicts` returns `attach{terminalId}` for a pane claiming a `sessionRef` that a live terminal already carries, regardless of `createRequestId`; `TerminalRegistry::alarm_if_duplicate_session_ref(&SessionLocator)` ERROR-logs when ≥2 live PTYs carry one sessionRef. Task 5/6 use both.
 
 - [ ] **Step 1: Write the failing tests**
@@ -352,22 +369,29 @@ async fn different_create_request_id_same_session_ref_gets_attach_to_winner() {
 }
 ```
 
-And a registry unit test: seed two live terminals stamped with the same sessionRef → `alarm_if_duplicate_session_ref` returns `true` (and, by inspection, emits `tracing::error!` with target `"invariant"` and message containing `duplicate_pty_for_session_ref`); with one live terminal → `false`.
+And a registry unit test (in `crates/freshell-terminal/src/registry.rs` `#[cfg(test)]`): seed two live terminals stamped with the same sessionRef → `alarm_if_duplicate_session_ref` returns `true` (and, by inspection, emits `tracing::error!` with target `"invariant"` and message containing `duplicate_pty_for_session_ref`); with one live terminal → `false`. Mirror the pattern of the existing duplicate detector `warn_on_duplicate_live_ptys` (`registry.rs:1618`) — extend it rather than duplicating its scan if it already counts per resume_session_id.
 
 - [ ] **Step 2: Run to verify failure**
 
 ```bash
 cargo test -p freshell-ws --test pane_reconcile different_create_request_id
-cargo test -p freshell-ws duplicate_session_ref
+cargo test -p freshell-terminal duplicate_session_ref
 ```
 Expected: FAIL (today derivation keys on `createRequestId` only — `newest_live_by_create_request_id`).
 
 - [ ] **Step 3: Implement**
-  - `registry.rs`:
+  - `crates/freshell-terminal/src/registry.rs`:
 
 ```rust
-/// Live terminal currently identity-stamped with this sessionRef, if any.
-pub fn live_terminal_for_session_ref(&self, locator: &SessionLocator) -> Option<String> { /* scan live rows joined with identity */ }
+/// Live terminal currently carrying this sessionRef, if any.
+/// LOOKUP DESIGN (validator-corrected): registry rows have NO usable
+/// session_ref field (inventory() hardcodes session_ref: None, :269).
+/// Either join over registry rows on
+///   (mode == locator.provider && resume_session_id == Some(locator.session_id) && status Running),
+/// or (in freshell-ws/src/identity.rs) add a LIVE-ONLY variant of
+/// `find_by_session_including_retired` (only the retired-inclusive variant
+/// exists today) and route the lookup through ReconcileDeps.identity.
+pub fn live_terminal_for_session_ref(&self, locator: &SessionLocator) -> Option<String> { /* join per above */ }
 
 /// D8 backstop: >=2 live PTYs carrying one sessionRef is the two-writers
 /// corruption shape. Alarm loudly; never kill silently.
@@ -382,13 +406,13 @@ pub fn alarm_if_duplicate_session_ref(&self, locator: &SessionLocator) -> bool {
     false
 }
 ```
-Where identity lives (registry rows vs the separate identity registry) — follow how `derive_verdicts`' existing rows resolve identity today (`ReconcileDeps.identity`); put the lookup where the data actually is and expose it through whichever of the two structs `ReconcileDeps` already carries.
+Where identity lives (registry rows vs the separate identity registry) — follow how `derive_verdicts`' existing rows resolve identity today (`ReconcileDeps.identity`); put the lookup where the data actually is and expose it through whichever of the two structs `ReconcileDeps` already carries. Remember the crate boundary: the row-join variant lives on `TerminalRegistry` in freshell-terminal; an identity-registry variant lives in `crates/freshell-ws/src/identity.rs` (freshell-terminal cannot depend on freshell-ws).
   - `reconcile.rs`: in the per-pane derivation for `kind: terminal`, BEFORE the existing `createRequestId`-keyed resolution: if the pane claims a `sessionRef` and `live_terminal_for_session_ref` returns `Some(tid)` → verdict `attach{terminalId: tid, sessionRef: <server's ref>}`, with `corrected: true` iff the client's claimed `sessionRef`/`terminalId` disagreed with the server's truth (follow the existing corrected-computation pattern used by the current attach arm). Do NOT touch the `unsupported_kind` arm at :169.
 
 - [ ] **Step 4: Run tests**
 
 ```bash
-cargo test -p freshell-ws
+cargo test -p freshell-terminal && cargo test -p freshell-ws
 ```
 Expected: PASS (all existing decision-table tests still green — the new branch only fires when a live terminal carries the claimed ref, which previously produced `attach` via the createRequestId path or a wrong `respawn`; if any existing test asserted `respawn` in that situation, that test was pinning D8 itself — update it and say so in the commit).
 
@@ -405,22 +429,33 @@ git commit -m "feat(ws): sessionRef-level attach in verdict derivation + duplica
 ### Task 5: Server — sessionRef liveness-bound lease in the registry
 
 **Files:**
-- Modify: `crates/freshell-ws/src/registry.rs`
-- Test: `crates/freshell-ws/src/registry.rs` `#[cfg(test)]` (unit level; wire level is Task 6)
+- Modify: `crates/freshell-terminal/src/registry.rs` (`TerminalRegistry` struct :409, impl :485)
+- Test: `crates/freshell-terminal/src/registry.rs` `#[cfg(test)]` (unit level; wire level is Task 6)
+
+PLACEMENT NOTE: the lease lives in freshell-terminal (dep direction ws → terminal → protocol; `SessionLocator` comes from freshell-protocol, which freshell-terminal already deps). Anything needing `TerminalIdentityRegistry` (`crates/freshell-ws/src/identity.rs`) stays in freshell-ws.
 
 **Interfaces:**
-- Consumes: `TerminalRegistry` internals (existing `keyed_create_inflight` pattern at `registry.rs:1599-1608` is the shape to mirror), `SessionLocator`.
+- Consumes: `TerminalRegistry` internals (existing `keyed_create_inflight` pattern is the shape to mirror — field `registry.rs:452`, init :502, `begin_keyed_create` :1599-1604, `end_keyed_create` :1608-1613), `SessionLocator`.
 - Produces (exact API Task 6 calls):
 
 ```rust
-pub const SESSION_REF_LEASE_TTL_MS: u64 = 20_000; // ~2x the 10s spawn budget
+/// Explicit wall-clock backstop for a hung holder. NOT derived from any
+/// "spawn budget" — the 10s constant at create_limit.rs:49 (spawn_timeout_ms,
+/// env FRESHELL_SPAWN_GATE_TIMEOUT_MS) bounds the spawn-GATE PERMIT wait,
+/// not spawn duration; spawns run unbounded in spawn_blocking. Task 6 makes
+/// this env-tunable and adds spawn-duration instrumentation to tune it on
+/// evidence.
+pub const SESSION_REF_LEASE_TTL_MS: u64 = 20_000;
 pub const SESSION_RESERVED_RETRY_AFTER_MS: u64 = 1_000;
 
 pub enum SessionRefClaim {
     Acquired,
     Held { retry_after_ms: u64 },
-    /// TTL expired on a holder with a recorded child: caller must kill pid,
-    /// CONFIRM death, then call force_release_after_confirmed_kill and re-claim.
+    /// TTL expired on a holder with a recorded child: caller must kill the
+    /// holder's spawn via the REGISTRY handle (group-kill discipline,
+    /// pty.rs:352-386 — never a raw single-pid SIGKILL), CONFIRM death, then
+    /// call force_release_after_confirmed_kill and re-claim. The pid is for
+    /// ESRCH-confirmation, not for raw kill().
     ExpiredNeedsKill { pid: u32 },
     BoundElsewhere { terminal_id: String },
 }
@@ -511,12 +546,14 @@ fn hung_holder_without_pid_is_revoked_and_held_closed() {
     assert!(!reg.complete_session_ref_claim(&s, "cr-A", "term-late"));
 }
 ```
-(`test_registry()`/`locator()` helpers: copy the construction pattern from the existing registry tests — `rg -n "fn test" crates/freshell-ws/src/registry.rs`.)
+(`test_registry()`/`locator()` helpers: copy the construction pattern from the existing registry tests — `rg -n "fn test" crates/freshell-terminal/src/registry.rs`.)
+
+KILL-MECHANICS NOTE (verified with load-bearing caveats, applies here and in Task 6): TTL-expiry kills go through the REGISTRY's PTY handle (group-kill discipline, `pty.rs:352-386`), never a raw single-pid SIGKILL. ESRCH polling is a viable confirmation because a dedicated waiter thread reaps children promptly (`pty.rs:260-269`). The DOMINANT hung-spawn case — stuck in `spawn_blocking` (`terminal.rs:1411-1415`) — is pid-less and resolves HOLD-CLOSED (fail loud) or via holder-connection-death release; the kill path covers only the spawn-returned→complete window. (Wire-level D8 spawns are Task 6; its test recipe uses the claude sleeper-spec harness.)
 
 - [ ] **Step 2: Run to verify failure**
 
 ```bash
-cargo test -p freshell-ws claim_session_ref -- --nocapture || cargo test -p freshell-ws session_ref
+cargo test -p freshell-terminal claim_session_ref -- --nocapture || cargo test -p freshell-terminal session_ref
 ```
 Expected: FAIL — compile errors (API absent).
 
@@ -525,7 +562,7 @@ Expected: FAIL — compile errors (API absent).
 - [ ] **Step 4: Run tests**
 
 ```bash
-cargo test -p freshell-ws
+cargo test -p freshell-terminal && cargo test -p freshell-ws
 ```
 Expected: PASS.
 
@@ -534,35 +571,40 @@ Expected: PASS.
 ```bash
 cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
 git add -A crates/
-git commit -m "feat(ws): sessionRef liveness-bound lease with TTL kill-before-release semantics"
+git commit -m "feat(terminal): sessionRef liveness-bound lease with TTL kill-before-release semantics"
 ```
 
 ---
 
-### Task 6: Server — create-path lease integration, `SESSION_RESERVED` error, ledger write at winner bind
+### Task 6: Server — create-path lease integration, `SESSION_RESERVED` error, registry binding at winner bind
 
 **Files:**
 - Modify: `crates/freshell-protocol/src/` (add `SESSION_RESERVED` error code + additive `retryAfterMs: Option<u64>` on `ErrorMsg`, `skip_serializing_if = "Option::is_none"`)
 - Modify: `crates/freshell-ws/src/terminal.rs` (create path around the `KeyedCreateGuard` at :907 and adopt loop :937-976; connection-close cleanup site)
+- Modify: `crates/freshell-terminal/src/registry.rs` (make `SESSION_REF_LEASE_TTL_MS` env-tunable — Step 3 item 7)
 - Test: Create `crates/freshell-ws/tests/session_ref_singleflight.rs`
 
 **Interfaces:**
-- Consumes: Task 5 lease API; `KeyedCreateGuard` (`terminal.rs:907`); pane-ledger write API from wave A — `record_binding(&BindingWrite) -> io::Result<()>` with `BindingWrite { provider, session_id, terminal_id, mode, cwd, create_request_id, now_ms }` (locate the handle the inventory-stamping read path already uses: `rg -n "record_binding\|pane_ledger\|lookup_by_session" crates/`).
-- Produces: on a `paneReconcileV1`-negotiated connection, a `terminal.create` carrying a resume `sessionRef` runs the lease discipline; losers receive `error{code: SESSION_RESERVED, requestId: <createRequestId>, retryAfterMs: 1000}`; the winner's successful spawn binds sessionRef→terminalId in registry AND ledger. Non-negotiated (frozen legacy) connections are byte-for-byte unchanged.
+- Consumes: Task 5 lease API (from `crates/freshell-terminal/src/registry.rs`); `KeyedCreateGuard` (`terminal.rs:907`). VALIDATOR-CORRECTED FACT: the pane-ledger write is NOT new work — the create path ALREADY calls `ledger.record_binding` for EVERY resume/restore create, awaited before `terminal.created` (`crates/freshell-ws/src/terminal.rs:1575-1603`). This task does NOT add a ledger write.
+- Produces: on a `paneReconcileV1`-negotiated connection, a `terminal.create` carrying a resume `sessionRef` runs the lease discipline; losers receive `error{code: SESSION_RESERVED, requestId: <createRequestId>, retryAfterMs: 1000}`; the winner's successful spawn binds sessionRef→terminalId in the REGISTRY binding map (the ledger write already happens on the create path — pre-existing behavior, not this task's). Also: `SESSION_REF_LEASE_TTL_MS` made env-tunable alongside the gate timeout, plus spawn-duration instrumentation (log elapsed spawn time at winner bind) so the TTL constant can be tuned on evidence. Non-negotiated (frozen legacy) connections are byte-for-byte unchanged.
 
-- [ ] **Step 1: Write the failing wire-level tests** in the new `tests/session_ref_singleflight.rs` (copy the helper mod from `tests/pane_reconcile.rs`):
+- [ ] **Step 1: Write the failing wire-level tests** in the new `tests/session_ref_singleflight.rs` (copy the helper mod from `tests/pane_reconcile.rs`).
+
+TEST RECIPE (verified viable, V7): `mod common;` + `spawn_server_with_specs(vec![sleeper_cli_spec("claude")])` (`tests/common/mod.rs:45-91`) spawns real resume-create→live-PTY round trips; existing precedent `claude_restore_with_session_ref_resumes` (`tests/claude_restore_unavailable.rs:79`, verified passing). REQUIREMENTS: (a) shared sessionIds in these D8 tests MUST be canonical-UUID-shaped — the restore gate rejects non-UUID with `RESTORE_UNAVAILABLE` before spawn; (b) prefer the claude sleeper-spec path over codex `CODEX_CMD` env mutation (process-global env races in concurrent tests); (c) count live PTYs per sessionRef via `registry.identity_probe_rows()` (`crates/freshell-terminal/src/registry.rs:1322`), counting Running rows with the `resume_session_id`.
 
 ```rust
 /// two-clients-same-sessionRef (council red test): two negotiated
 /// connections, DIFFERENT createRequestIds, same sessionRef resume ->
 /// exactly one PTY; the loser is reserved then attaches to the winner.
+/// SessionIds are UUID-shaped (restore gate rejects non-UUID pre-spawn).
 #[tokio::test]
 async fn two_clients_same_session_ref_yield_exactly_one_pty() {
-    let server = spawn_server_default().await;
+    const SESS_DUP: &str = "11111111-1111-4111-8111-111111111111";
+    let server = spawn_server_with_specs(vec![sleeper_cli_spec("claude")]).await;
     let mut a = connect(&server.url, true).await;
     let mut b = connect(&server.url, true).await;
-    a.send_json(terminal_create_resume("cr-A", "claude", "sess-dup")).await;
-    b.send_json(terminal_create_resume("cr-B", "claude", "sess-dup")).await;
+    a.send_json(terminal_create_resume("cr-A", "claude", SESS_DUP)).await;
+    b.send_json(terminal_create_resume("cr-B", "claude", SESS_DUP)).await;
     // One connection gets terminal.created (spawn); collect both outcomes.
     let (created, other) = race_created_and_error(&mut a, &mut b).await;
     let tid = created["terminalId"].as_str().unwrap().to_string();
@@ -576,33 +618,43 @@ async fn two_clients_same_session_ref_yield_exactly_one_pty() {
     } else {
         assert_eq!(other["terminalId"], tid);
     }
-    assert_eq!(server.live_pty_count_for_session("claude", "sess-dup").await, 1);
+    assert_eq!(server.live_pty_count_for_session("claude", SESS_DUP).await, 1);
 }
 
 /// Legacy connections (no capability) never see SESSION_RESERVED — the
 /// frozen-client create path is byte-for-byte unchanged.
 #[tokio::test]
 async fn legacy_connection_create_path_unchanged() {
-    let server = spawn_server_default().await;
+    const SESS_LEGACY: &str = "22222222-2222-4222-8222-222222222222";
+    let server = spawn_server_with_specs(vec![sleeper_cli_spec("claude")]).await;
     let mut legacy = connect(&server.url, false).await;
-    legacy.send_json(terminal_create_resume("cr-L", "claude", "sess-legacy")).await;
+    legacy.send_json(terminal_create_resume("cr-L", "claude", SESS_LEGACY)).await;
     let created = next_frame_of_type(&mut legacy, "terminal.created").await;
     assert!(created["terminalId"].is_string());
 }
 
-/// Winner bind writes the ledger: after the winner's terminal.created,
-/// lookup_by_session resolves sessionRef -> that terminalId.
+/// Winner bind populates the REGISTRY binding map: after the winner's
+/// terminal.created, a second client's claim for the same sessionRef gets
+/// BoundElsewhere/attach to that terminalId. This is the NEW behavior this
+/// task adds (RED first). The pane-ledger write is PRE-EXISTING create-path
+/// behavior (terminal.rs:1575-1603) — optionally pin it below as an
+/// existing-behavior assertion, but it is NOT part of the red test.
 #[tokio::test]
-async fn winner_bind_writes_ledger_binding() {
-    let server = spawn_server_default().await;
+async fn winner_bind_populates_registry_binding() {
+    const SESS_LED: &str = "33333333-3333-4333-8333-333333333333";
+    let server = spawn_server_with_specs(vec![sleeper_cli_spec("claude")]).await;
     let mut a = connect(&server.url, true).await;
-    a.send_json(terminal_create_resume("cr-A", "claude", "sess-led")).await;
+    a.send_json(terminal_create_resume("cr-A", "claude", SESS_LED)).await;
     let created = next_frame_of_type(&mut a, "terminal.created").await;
-    let resolved = server.ledger_lookup("claude", "sess-led").await;
-    assert_eq!(resolved.as_deref(), Some(created["terminalId"].as_str().unwrap()));
+    let tid = created["terminalId"].as_str().unwrap();
+    // NEW behavior (red): the registry binding map answers for this sessionRef.
+    assert_eq!(server.registry_binding_for("claude", SESS_LED).await.as_deref(), Some(tid));
+    // Existing behavior pin (should already pass — NOT the red assertion):
+    // let resolved = server.ledger_lookup("claude", SESS_LED).await;
+    // assert_eq!(resolved.as_deref(), Some(tid));
 }
 ```
-Helper notes: `terminal_create_resume` builds the same `terminal.create` JSON the client sends for resume (copy field names from an existing create-with-resume test or `shared/ws-protocol.ts` `TerminalCreateSchema:301` — it is `.strict()`, so it IS the wire truth). `live_pty_count_for_session` / `ledger_lookup` are small test accessors — expose them via the existing test-server handle pattern (the harness owns the state). Headless mode (`headless()`) keeps spawns cheap.
+Helper notes: `terminal_create_resume` builds the same `terminal.create` JSON the client sends for resume (copy field names from an existing create-with-resume test or `shared/ws-protocol.ts` `TerminalCreateSchema:301` — it is `.strict()`, so it IS the wire truth). `live_pty_count_for_session` counts Running rows carrying the `resume_session_id` via `registry.identity_probe_rows()` (`crates/freshell-terminal/src/registry.rs:1322`); `registry_binding_for` (and the optional `ledger_lookup`) are small test accessors — expose them via the existing test-server handle pattern (the harness owns the state). The `sleeper_cli_spec("claude")` harness keeps spawns cheap and real.
 
 - [ ] **Step 2: Run to verify failure**
 
@@ -617,19 +669,11 @@ Expected: FAIL — today both creates spawn (two PTYs), no SESSION_RESERVED code
     1. If the create carries a resume `sessionRef` (provider + sessionId resolvable from the create body): `claim_session_ref(...)` with the connection's id and `now_ms`.
     2. `BoundElsewhere{terminal_id}` → emit `terminal.created` for that existing terminal (mirror the adopt loop's emission — attach to the winner, spawn nothing).
     3. `Held{retry_after_ms}` → send `error{SESSION_RESERVED, requestId: create.request_id, retryAfterMs}`; do not spawn; do not charge the rate limiter (adopt precedent: `create_protection.rs:250`).
-    4. `ExpiredNeedsKill{pid}` → kill the pid (SIGKILL), confirm death by polling `kill(pid, 0)` for ESRCH up to 500ms; confirmed → `force_release_after_confirmed_kill` then re-claim and proceed; NOT confirmed → treat as `Held` + `tracing::error!` (hold closed).
-    5. `Acquired` → proceed to spawn; immediately after the PTY child exists call `set_session_ref_lease_pid`; on success call `complete_session_ref_claim` — if it returns `false` (revoked), kill the just-spawned child, confirm, and answer the create with a plain error (fail loud); on spawn failure call `fail_session_ref_claim`.
-    6. On `complete_session_ref_claim == true`, write the ledger binding (best-effort, NEVER blocks the create):
-
-```rust
-if let Err(e) = ledger.record_binding(&BindingWrite {
-    provider, session_id, terminal_id, mode, cwd, create_request_id, now_ms,
-}) {
-    tracing::error!(target: "invariant", error = %e,
-        "pane-ledger record_binding failed at respawn-winner bind");
-}
-```
-  - Connection-close cleanup (find where the ws connection teardown already releases per-conn resources): call `release_session_ref_leases_for_conn(conn)`; for returned pid-carrying entries, kill + confirm + `force_release_after_confirmed_kill` (same discipline as step 4).
+    4. `ExpiredNeedsKill{pid}` → kill the holder's spawn via the REGISTRY handle (group-kill discipline, `pty.rs:352-386` — NEVER a raw single-pid SIGKILL), confirm death by polling `kill(pid, 0)` for ESRCH up to 500ms (viable: a dedicated waiter thread reaps promptly, `pty.rs:260-269`); confirmed → `force_release_after_confirmed_kill` then re-claim and proceed; NOT confirmed → treat as `Held` + `tracing::error!` (hold closed). NOTE: the DOMINANT hung-spawn case — stuck in `spawn_blocking` (`terminal.rs:1411-1415`) — is pid-less and resolves HOLD-CLOSED (fail loud) or via holder-connection-death release; this kill path covers only the spawn-returned→complete window.
+    5. `Acquired` → proceed to spawn; immediately after the PTY child exists call `set_session_ref_lease_pid`; on success call `complete_session_ref_claim` — if it returns `false` (revoked), kill the just-spawned child via the registry handle, confirm, and answer the create with a plain error (fail loud); on spawn failure call `fail_session_ref_claim`.
+    6. On `complete_session_ref_claim == true`, the REGISTRY sessionRef→terminalId binding is recorded (inside `complete_session_ref_claim`, Task 5). Do NOT add a ledger write here — the create path ALREADY calls `ledger.record_binding` for every resume/restore create, awaited before `terminal.created` (`terminal.rs:1575-1603`). At winner bind, log the elapsed spawn duration (`tracing::info!` with the ms since claim) — this is the instrumentation that lets `SESSION_REF_LEASE_TTL_MS` be tuned on evidence.
+    7. Make `SESSION_REF_LEASE_TTL_MS` env-tunable (e.g. `FRESHELL_SESSION_REF_LEASE_TTL_MS`) alongside the spawn-gate timeout (`FRESHELL_SPAWN_GATE_TIMEOUT_MS`, `create_limit.rs:49`), constants co-located so the client's 30s re-drive window derivation (Task 12: window > TTL + margin) stays visible.
+  - Connection-close cleanup (find where the ws connection teardown already releases per-conn resources): call `release_session_ref_leases_for_conn(conn)`; for returned pid-carrying entries, kill via the registry handle + confirm + `force_release_after_confirmed_kill` (same discipline as step 4).
 
 - [ ] **Step 4: Run tests**
 
@@ -643,7 +687,7 @@ Expected: PASS including `create_protection.rs` and `pane_reconcile.rs` suites.
 ```bash
 cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
 git add -A crates/
-git commit -m "feat(ws): per-sessionRef single-flight on the create path with SESSION_RESERVED + ledger bind (closes D8 server-side)"
+git commit -m "feat(ws): per-sessionRef single-flight on the create path with SESSION_RESERVED + registry bind (closes D8 server-side)"
 ```
 
 ---
@@ -663,7 +707,7 @@ git commit -m "feat(ws): per-sessionRef single-flight on the create path with SE
   - `PaneVerdictSchema` with `verdict: z.enum(['attach','respawn','fresh','dead_session','invalid','error'])`, `PaneReconcileResultSchema`, types `PaneVerdict`, `PaneReconcileResultMessage` (+ in the `ServerMessage` union),
   - `ReadyCapabilitiesSchema = z.object({ paneReconcileV1: z.literal(true).optional() }).optional()` merged into the ready message type,
   - error-frame type gains optional `retryAfterMs?: number` and the `SESSION_RESERVED` code string.
-  - `TerminalPaneContent` gains: `reconcileNotice?: string` and `pendingReconcile?: 'respawn' | 'fresh'`.
+  - `TerminalPaneContent` gains: `reconcileNotice?: string`, `pendingReconcile?: 'respawn' | 'fresh'`, and `reconcileEpoch?: number` (volatile fold counter — VALIDATOR-CORRECTED FACT: same-`createRequestId` folds do NOT re-fire TerminalView's create-or-attach effect, whose deps key on `terminalContent?.createRequestId` only (`TerminalView.tsx:4486`; ":4471 terminalId intentionally NOT in dependencies"); legacy recovery works only because `clearTerminalContentForRecreate` mints a NEW id (`panesSlice.ts:551,556`). Reconcile folds must NOT re-mint (council rule 2), so they bump `reconcileEpoch` instead and Task 12 adds it to the effect dependency array).
 
 - [ ] **Step 1: Write the failing test**
 
@@ -714,20 +758,22 @@ npm run test:vitest -- run test/unit/shared/ws-protocol.reconcile.test.ts
 ```
 Expected: FAIL — exports don't exist.
 
-- [ ] **Step 3: Implement** the schemas per the Produces block (follow the file's existing style; the request schema mirrors the Rust wire exactly — field names camelCase, `panes: z.array(ReconcilePaneSchema).max(200)`). Add the two `TerminalPaneContent` fields with doc comments:
+- [ ] **Step 3: Implement** the schemas per the Produces block (follow the file's existing style; the request schema mirrors the Rust wire exactly — field names camelCase, `panes: z.array(ReconcilePaneSchema).max(200)`). Add the three `TerminalPaneContent` fields with doc comments:
 
 ```ts
 /** One-shot user-visible reconcile notice (corrected identity, fresh-by-reason, duplicate ignored). Rendered then cleared by TerminalView. */
 reconcileNotice?: string
 /** Set by verdict folding; consumed by TerminalView when it sends terminal.create. 'respawn' = create-with-resume from sessionRef; 'fresh' = clean create. */
 pendingReconcile?: 'respawn' | 'fresh'
+/** VOLATILE fold counter. Incremented by applyReconcileAttach / resetPaneForReconcileCreate so a fold on an already-mounted pane (same createRequestId — never re-minted) re-fires TerminalView's create-or-attach effect (Task 12 adds it to the dep array). Stripped from persistence (Task 8). */
+reconcileEpoch?: number
 ```
-Check `normalizePaneContent` (`panesSlice.ts:61`) — if it whitelists fields, add both.
+Check `normalizePaneContent` (`panesSlice.ts:61`) — if it whitelists fields, add all three.
 
 - [ ] **Step 4: Run tests**
 
 ```bash
-npm run test:vitest -- run test/unit/shared/ws-protocol.reconcile.test.ts test/unit/store/panesSlice.test.ts
+npm run test:vitest -- run test/unit/shared/ws-protocol.reconcile.test.ts test/unit/client/store/panesSlice.test.ts
 ```
 Expected: PASS.
 
@@ -744,7 +790,8 @@ git commit -m "feat(protocol): pane.reconcile client schemas, ready capabilities
 
 **Files:**
 - Modify: `src/store/panesSlice.ts`
-- Test: Create `test/unit/store/panesSlice.reconcile.test.ts`
+- Modify: `src/store/persistMiddleware.ts` (volatile-field stripping)
+- Test: Create `test/unit/client/store/panesSlice.reconcile.test.ts`
 
 **Interfaces:**
 - Consumes: `TerminalPaneContent` fields from Task 7; existing helpers in `panesSlice.ts` for locating a pane's content by `(tabId, paneId)` (see how `clearTerminalContentForRecreate` :544-568 walks the layout — reuse its lookup, NOT its body).
@@ -755,8 +802,11 @@ git commit -m "feat(protocol): pane.reconcile client schemas, ready capabilities
   - `setDeadSessionAdjudication(entries: DeadSessionEntry[])` / `resolveDeadSessionEntry({tabId, paneId})` / `clearDeadSessionAdjudication()` — non-persisted state field `deadSessionAdjudication: DeadSessionEntry[]` where `DeadSessionEntry = {tabId, paneId, title: string, mode: string, sessionRef?: {provider, sessionId}, reason?: string}`
   - `setReconcileWarming({count, paneRefs: {tabId, paneId}[]})` / `clearReconcileWarming()` — non-persisted field `reconcileWarming: {count: number, paneRefs: {tabId: string, paneId: string}[]} | null`
 - CRITICAL: none of these reducers may mint a `createRequestId`. `resetPaneForReconcileCreate` PRESERVES the existing `createRequestId` (this is the load-bearing difference from `clearTerminalContentForRecreate`, which mints — D4).
+- CRITICAL (A1 fix): `applyReconcileAttach` and `resetPaneForReconcileCreate` each INCREMENT the pane's volatile `reconcileEpoch` (`(content.reconcileEpoch ?? 0) + 1`). Same-`createRequestId` folds do NOT re-fire TerminalView's create-or-attach effect on their own (deps key on `createRequestId` only, `TerminalView.tsx:4486`); the epoch bump is what makes the fold observable — Task 12 adds it to the effect dep array. `createRequestId` is still never re-minted (council rule 2 intact).
+- Persistence (A19 decision): `pendingReconcile`, `reconcileNotice`, and `reconcileEpoch` are VOLATILE — strip all three in the persistence path (`stripTabVolatileFields`, `persistMiddleware.ts:75`) alongside the slice-level strips. AND clear `pendingReconcile` when `terminal.created` lands for the pane (belt and braces — stale respawn-intent must not survive a reload): extend the existing reducer that folds `terminal.created` into pane content (locate with `rg -n "terminal.created\|setTerminalId" src/store/panesSlice.ts`).
+- Invariant (respawn folds, shared with Task 12): a `respawn` fold must guarantee `sessionRef.provider === pane mode` — the server create path filters on it (`terminal.rs:1047`) and a mismatch spawns identity-less. `resetPaneForReconcileCreate({intent:'respawn'})` should assert/guard this (loud console.error + treat as fresh-with-notice rather than silently mismatching).
 
-- [ ] **Step 1: Write the failing tests** (copy store-construction boilerplate from `test/unit/store/panesSlice.test.ts`):
+- [ ] **Step 1: Write the failing tests** (copy store-construction boilerplate from `test/unit/client/store/panesSlice.test.ts`):
 
 ```ts
 describe('reconcile reducers', () => {
@@ -768,6 +818,15 @@ describe('reconcile reducers', () => {
     expect(c.status).toBe('running')
     expect(c.createRequestId).toBe('cr-keep')   // council rule: never re-minted
     expect(c.restoreError).toBeUndefined()
+    expect(c.reconcileEpoch).toBe(1)            // A1 fix: fold bumps the volatile epoch
+  })
+  it('every fold bumps reconcileEpoch monotonically (createRequestId untouched)', () => {
+    let s = stateWithTerminalPane({ createRequestId: 'cr-keep' })
+    s = panesReducer(s, applyReconcileAttach({ tabId: 'tab1', paneId: 'p1', terminalId: 't1' }))
+    s = panesReducer(s, resetPaneForReconcileCreate({ tabId: 'tab1', paneId: 'p1', intent: 'fresh' }))
+    const c = terminalContent(s, 'tab1', 'p1')
+    expect(c.reconcileEpoch).toBe(2)
+    expect(c.createRequestId).toBe('cr-keep')
   })
   it('applyReconcileAttach with corrected sets a visible notice', () => {
     const next = panesReducer(stateWithTerminalPane({}), applyReconcileAttach({ tabId: 'tab1', paneId: 'p1', terminalId: 't', corrected: true }))
@@ -807,7 +866,7 @@ describe('reconcile reducers', () => {
 - [ ] **Step 2: Run to verify failure**
 
 ```bash
-npm run test:vitest -- run test/unit/store/panesSlice.reconcile.test.ts
+npm run test:vitest -- run test/unit/client/store/panesSlice.reconcile.test.ts
 ```
 Expected: FAIL — actions don't exist.
 
@@ -815,19 +874,19 @@ Expected: FAIL — actions don't exist.
   - corrected: `Session identity corrected by server — this pane now points at its live session.`
   - duplicate: `A duplicate terminal for this session was detected and ignored.`
   - fresh with reason: `` `Started fresh (${reason}).` ``
-  Ensure `deadSessionAdjudication` and `reconcileWarming` are stripped from persistence (check `persistMiddleware.ts:484`'s strip list — it already strips `restoreFallbackAttemptsByPane`; add these two the same way).
+  Ensure `deadSessionAdjudication` and `reconcileWarming` are stripped from persistence (check `persistMiddleware.ts:484`'s strip list — it already strips `restoreFallbackAttemptsByPane`; add these two the same way). ALSO strip the three per-pane volatile fields — `pendingReconcile`, `reconcileNotice`, `reconcileEpoch` — in `stripTabVolatileFields` (`persistMiddleware.ts:75`), AND clear `pendingReconcile` in the reducer that folds `terminal.created` into pane content (A19: stale respawn-intent must never survive a reload). Add tests for both (persist strip + clear-on-created).
 
 - [ ] **Step 4: Run tests**
 
 ```bash
-npm run test:vitest -- run test/unit/store/panesSlice.reconcile.test.ts test/unit/store/panesSlice.test.ts test/unit/store/createRequestIdStability.test.ts
+npm run test:vitest -- run test/unit/client/store/panesSlice.reconcile.test.ts test/unit/client/store/panesSlice.test.ts test/unit/client/store/createRequestIdStability.test.ts
 ```
 Expected: PASS (the stability suite proves we didn't regress P1.6).
 
 - [ ] **Step 5: Commit**
 
 ```bash
-git add src/store/panesSlice.ts src/store/persistMiddleware.ts test/unit/store/panesSlice.reconcile.test.ts
+git add src/store/panesSlice.ts src/store/persistMiddleware.ts test/unit/client/store/panesSlice.reconcile.test.ts
 git commit -m "feat(store): reconcile verdict fold reducers - attach/reset without createRequestId re-mint, batched dead-session state"
 ```
 
@@ -837,7 +896,7 @@ git commit -m "feat(store): reconcile verdict fold reducers - attach/reset witho
 
 **Files:**
 - Create: `src/lib/pane-reconcile.ts`
-- Test: Create `test/unit/lib/pane-reconcile.test.ts`
+- Test: Create `test/unit/client/lib/pane-reconcile.test.ts`
 
 **Interfaces:**
 - Consumes: Task 7 schemas/types; Task 8 actions; the pane-tree walk — reuse/extract the logic of `collectTerminalPaneTargets` (`App.tsx:811`) rather than re-deriving it (either import it if exported, or move it into this module and re-export for App).
@@ -851,6 +910,7 @@ export function foldVerdicts(dispatch: AppDispatch, request: PaneReconcileReques
 export function paneKeyFor(tabId: string, paneId: string): string   // `${tabId}:${paneId}`
 ```
 - Rules: panes without a terminal content or without `createRequestId` are skipped; >200 panes → `console.error` breadcrumb + first 200 sent; `foldVerdicts` FIRST checks cardinality (`verdicts.length === request.panes.length` AND every `paneKey` matches 1:1) — on violation it dispatches NOTHING except the outcome flag (the caller falls back to the legacy census, Task 11); `paneKey` is parsed back via the request's own pane list (index paneKey→{tabId,paneId} from the request, never by string-splitting server input).
+- FOLD-OWNERSHIP RULE (pinned; applies to every consumer — Tasks 11/12/13): the correlation mechanism is the EXISTING `ws.onMessage` broadcast subscription (`src/lib/ws-client.ts:616-618`), already used by components to correlate self-initiated requests (e.g. `TerminalView.tsx:3044`) — NO new correlator module. Each requester (App boot reconcile, TerminalView exhaustion auto-resolve, warming-banner Retry) folds ONLY results whose `reconcileId` it minted, silently skipping foreign ones — this prevents double-folds.
 
 - [ ] **Step 1: Write the failing tests**
 
@@ -912,7 +972,7 @@ describe('foldVerdicts', () => {
 - [ ] **Step 2: Run to verify failure**
 
 ```bash
-npm run test:vitest -- run test/unit/lib/pane-reconcile.test.ts
+npm run test:vitest -- run test/unit/client/lib/pane-reconcile.test.ts
 ```
 Expected: FAIL — module doesn't exist.
 
@@ -928,14 +988,14 @@ Expected: FAIL — module doesn't exist.
 - [ ] **Step 4: Run tests**
 
 ```bash
-npm run test:vitest -- run test/unit/lib/pane-reconcile.test.ts
+npm run test:vitest -- run test/unit/client/lib/pane-reconcile.test.ts
 ```
 Expected: PASS.
 
 - [ ] **Step 5: Commit**
 
 ```bash
-git add src/lib/pane-reconcile.ts test/unit/lib/pane-reconcile.test.ts src/store/panesSlice.ts
+git add src/lib/pane-reconcile.ts test/unit/client/lib/pane-reconcile.test.ts src/store/panesSlice.ts
 git commit -m "feat(client): pane-reconcile module - request builder, verdict folding, cardinality invariant"
 ```
 
@@ -945,11 +1005,13 @@ git commit -m "feat(client): pane-reconcile module - request builder, verdict fo
 
 **Files:**
 - Modify: `src/lib/ws-client.ts` (hello :343, ready handling in `handleIncomingMessage` :148, replay :195-205)
-- Test: Create `test/unit/lib/ws-client.reconcile.test.ts`
+- Modify: `shared/ws-protocol.ts` (`HelloSchema` capabilities object :267-279)
+- Test: Create `test/unit/client/lib/ws-client.reconcile.test.ts`
 
 **Interfaces:**
 - Consumes: `getWsClient()` (:643), `resetWsClientForTests()` (:652), `receiveMessageForTest` (:631) — the existing test seams.
 - Produces: hello carries `paneReconcileV1: true`; `getWsClient().getServerCapabilities(): {paneReconcileV1?: true}` (empty object until a ready with capabilities arrives; RESET on disconnect so a downgraded server is honored); when `paneReconcileV1` was acked on the CURRENT socket's ready, the blind `inFlightCreates` replay is skipped (verdicts, not resends, decide — `preReadyCreateQueue` flush is unchanged: those are new user-initiated creates).
+- REQUIRED (A20 corollary): the `paneReconcileV1` key must be EXPLICITLY added to `HelloSchema`'s `capabilities` object in `shared/ws-protocol.ts` (:267-279) — Zod's default (non-strict) objects silently STRIP unknown keys, so without the schema addition the capability would silently no-op. The legacy TS server then simply ignores the key (verified safe: `ws-handler.ts` `safeParse` is non-strict). `test/server/ws-handshake-snapshot.test.ts` does NOT pin the client hello shape (it constructs its own hello) — no update needed there.
 
 - [ ] **Step 1: Write the failing tests** (drive with `resetWsClientForTests` + `receiveMessageForTest`; mock the WebSocket the way existing ws-client tests do — `rg -l "resetWsClientForTests" test/` and copy the newest pattern):
 
@@ -980,11 +1042,12 @@ it('keeps the legacy replay when the server does not ack (old server)', () => {
 - [ ] **Step 2: Run to verify failure**
 
 ```bash
-npm run test:vitest -- run test/unit/lib/ws-client.reconcile.test.ts
+npm run test:vitest -- run test/unit/client/lib/ws-client.reconcile.test.ts
 ```
 Expected: FAIL.
 
 - [ ] **Step 3: Implement**
+  - `shared/ws-protocol.ts` `HelloSchema` capabilities (:267-279): add `paneReconcileV1: z.literal(true).optional()` next to the existing `uiScreenshotV1`/`terminalOutputBatchV1` keys (REQUIRED — non-strict Zod strips unknown keys silently).
   - `:343`: `capabilities: { uiScreenshotV1: true, terminalOutputBatchV1: true, paneReconcileV1: true },`
   - In the `ready` branch of `handleIncomingMessage`: `this.serverCapabilities = msg.capabilities ?? {}` BEFORE the replay block; clear it in the disconnect path (`onDisconnect`/`scheduleReconnect` entry).
   - Wrap the `inFlightCreates` replay (:195-205): `if (!this.serverCapabilities.paneReconcileV1) { /* existing replay */ }`.
@@ -993,14 +1056,14 @@ Expected: FAIL.
 - [ ] **Step 4: Run tests** (new + any existing ws-client/bootstrap suites)
 
 ```bash
-npm run test:vitest -- run test/unit/lib/ws-client.reconcile.test.ts test/unit/App.ws-bootstrap.test.tsx
+npm run test:vitest -- run test/unit/client/lib/ws-client.reconcile.test.ts test/unit/client/components/App.ws-bootstrap.test.tsx
 ```
 Expected: PASS.
 
 - [ ] **Step 5: Commit**
 
 ```bash
-git add src/lib/ws-client.ts test/unit/lib/ws-client.reconcile.test.ts
+git add src/lib/ws-client.ts shared/ws-protocol.ts test/unit/client/lib/ws-client.reconcile.test.ts
 git commit -m "feat(client): advertise paneReconcileV1, surface ready capabilities, gate blind create replay"
 ```
 
@@ -1011,13 +1074,18 @@ git commit -m "feat(client): advertise paneReconcileV1, surface ready capabiliti
 **Files:**
 - Modify: `src/App.tsx` (ReadyMessageSchema :149; inventory census block :1018-1091)
 - Modify: `src/lib/terminal-restore.ts`
-- Test: Create `test/unit/App.reconcile-adoption.test.tsx`; Modify `test/unit/lib/terminal-restore.test.ts`
+- Test: Create `test/unit/client/components/App.reconcile-adoption.test.tsx`; Modify `test/unit/lib/terminal-restore.test.ts`
 
 **Interfaces:**
 - Consumes: Task 9 `buildReconcileRequest`/`foldVerdicts`, Task 10 capabilities, Task 8 actions.
-- Produces: on every `ready` whose `capabilities.paneReconcileV1 === true`: `setPaneReconcileActive(true)` + build & send `pane.reconcile.request` + register the one-shot result fold (matched on `reconcileId`); the destructive census (`clearDeadTerminals` + restore-arming walk) runs ONLY when the capability is absent (`setLiveTerminalIds` + `setServerRestarted(false)` stay unconditional); cardinality violation → `console.error` + run the legacy census once for THIS inventory cycle (fail-safe); `terminal-restore.ts` exports `setPaneReconcileActive(v: boolean)` and, when active, `consumeTerminalRestoreRequestId` / `consumeTerminalFreshRecoveryRequest` report not-armed.
+- Produces: on every `ready` whose `capabilities.paneReconcileV1 === true`: `setPaneReconcileActive(true)` + build & send `pane.reconcile.request` + register the one-shot result fold (matched on `reconcileId`; fold-ownership rule from Task 9 — App folds only reconcileIds IT minted, skipping foreign ones); the destructive census (`clearDeadTerminals` + restore-arming walk) runs ONLY when the capability is absent (`setLiveTerminalIds` + `setServerRestarted(false)` stay unconditional); cardinality violation → `console.error` + run the legacy census once for THIS inventory cycle (fail-safe); `terminal-restore.ts` exports `setPaneReconcileActive(v: boolean)` and, when active, `consumeTerminalRestoreRequestId` / `consumeTerminalFreshRecoveryRequest` report not-armed.
+- A RESULT IS NOT GUARANTEED (A2 falsified — server has live-socket error-instead-of-result paths: `RECONCILE_TOO_LARGE` at `terminal.rs:1917` and `RECONCILE_UNAVAILABLE` on derivation panic at :1936-1950, both carrying `requestId = reconcileId`):
+  - (a) an error frame with `requestId === pendingReconcileRef.current?.reconcileId` is TERMINAL for that reconcile — loud `console.error` + fall back to the legacy census (same path as a cardinality violation);
+  - (b) the census fallback MUST run from the CACHED `liveTerminalIds` — on the real wire `terminal.inventory` ALWAYS precedes any reconcile result (handshake order: ready → settings.updated → perf.logging → [config.fallback] → terminal.inventory, `lib.rs:368-427`), so the inventory has already arrived by the time the error lands;
+  - (c) the reconcile request is re-sent on EVERY `ready` (capability re-captured per connection) — reconnect covers loss windows;
+  - (d) NO wall-clock timeout on the pending reconcile — it would false-trip on legitimate 2s deferrals.
 
-- [ ] **Step 1: Write the failing tests.** App-level: copy the store/ws mocking scaffold from `test/unit/App.ws-bootstrap.test.tsx` (it already boots App against a scripted ws).
+- [ ] **Step 1: Write the failing tests.** App-level: copy the store/ws mocking scaffold from `test/unit/client/components/App.ws-bootstrap.test.tsx` (it already boots App against a scripted ws).
 
 ```ts
 it('sends pane.reconcile.request after ready-with-capability and does NOT run the census', async () => {
@@ -1042,23 +1110,42 @@ it('folds a matching pane.reconcile.result', async () => {
   await receiveServerFrame(attachResultFor(req, 'term-77'))
   expect(dispatched.types).toContain(applyReconcileAttach.type)
 })
-it('cardinality violation falls back to the census, loudly', async () => {
+it('cardinality violation falls back to the census, loudly (real wire order: inventory BEFORE result)', async () => {
   seedPersistedTerminalPane({ createRequestId: 'cr-1' })
   const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
   const { sentFrames, dispatched } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
   const req = sentFrames.find(f => f.type === 'pane.reconcile.request')!
-  await receiveServerFrame({ type: 'pane.reconcile.result', reconcileId: req.reconcileId, bootId: 'b', serverInstanceId: 's', verdicts: [] })
+  // Real handshake order (lib.rs:368-427): terminal.inventory ALWAYS precedes
+  // any reconcile result — inject it FIRST; the fallback census must run from
+  // the CACHED liveTerminalIds.
   await receiveInventory({ liveTerminalIds: [] })
+  await receiveServerFrame({ type: 'pane.reconcile.result', reconcileId: req.reconcileId, bootId: 'b', serverInstanceId: 's', verdicts: [] })
   expect(errSpy).toHaveBeenCalled()
   expect(dispatched.types).toContain(clearDeadTerminals.type)
 })
+it('a correlated error frame is TERMINAL for the reconcile — census fallback from cached inventory', async () => {
+  seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+  const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+  const { sentFrames, dispatched } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+  const req = sentFrames.find(f => f.type === 'pane.reconcile.request')!
+  await receiveInventory({ liveTerminalIds: [] })  // inventory first — real wire order
+  await receiveServerFrame({ type: 'error', code: 'RECONCILE_UNAVAILABLE', requestId: req.reconcileId })
+  expect(errSpy).toHaveBeenCalled()
+  expect(dispatched.types).toContain(clearDeadTerminals.type)  // census ran from cached liveTerminalIds
+})
+it('re-sends the reconcile request on EVERY ready (reconnect covers loss windows)', async () => {
+  seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+  const { sentFrames } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+  await simulateReconnectWithReady({ capabilities: { paneReconcileV1: true } })
+  expect(sentFrames.filter(f => f.type === 'pane.reconcile.request')).toHaveLength(2)
+})
 ```
 `terminal-restore.test.ts` additions: after `setPaneReconcileActive(true)`, `addTerminalRestoreRequestId('cr-x')` then `consumeTerminalRestoreRequestId('cr-x')` → falsy; after `setPaneReconcileActive(false)` the latch behaves as before.
 
 - [ ] **Step 2: Run to verify failure**
 
 ```bash
-npm run test:vitest -- run test/unit/App.reconcile-adoption.test.tsx test/unit/lib/terminal-restore.test.ts
+npm run test:vitest -- run test/unit/client/components/App.reconcile-adoption.test.tsx test/unit/lib/terminal-restore.test.ts
 ```
 Expected: FAIL.
 
@@ -1077,7 +1164,8 @@ if (paneReconcile) {
   }
 }
 ```
-  - Message handler: on `pane.reconcile.result` with `reconcileId === pendingReconcileRef.current?.reconcileId` → `const outcome = foldVerdicts(dispatch, pendingReconcileRef.current, msg)`; clear the ref; if `outcome.cardinalityViolation` → `console.error('[reconcile] cardinality violation — falling back to legacy census')` + `paneReconcileActiveRef.current = false` + `setPaneReconcileActive(false)` (re-set true on the next ready).
+  - Message handler: on `pane.reconcile.result` with `reconcileId === pendingReconcileRef.current?.reconcileId` → `const outcome = foldVerdicts(dispatch, pendingReconcileRef.current, msg)`; clear the ref; results with a foreign `reconcileId` are SKIPPED (fold-ownership rule, Task 9); if `outcome.cardinalityViolation` → `console.error('[reconcile] cardinality violation — falling back to legacy census')` + `paneReconcileActiveRef.current = false` + `setPaneReconcileActive(false)` (re-set true on the next ready).
+  - Error-frame handler (A2): on an `error` frame with `requestId === pendingReconcileRef.current?.reconcileId` (e.g. `RECONCILE_TOO_LARGE`, `RECONCILE_UNAVAILABLE`) → treat as TERMINAL for that reconcile: `console.error('[reconcile] server error — falling back to legacy census', msg.code)`, clear the ref, and run the legacy census from the CACHED `liveTerminalIds` (inventory has already arrived — real wire order) via the same fallback path as the cardinality violation. Do NOT add a wall-clock timeout (it would false-trip on legitimate 2s deferrals); the request is re-sent on every ready, so reconnect covers loss windows.
   - Census block (:1018-1091): wrap ONLY the destructive part (`clearDeadTerminals` dispatch + the `addTerminalRestoreRequestId`/`addTerminalFreshRecoveryRequestId` walk) in `if (!paneReconcileActiveRef.current) { ... }`.
   - `terminal-restore.ts`:
 
@@ -1091,14 +1179,14 @@ if (paneReconcileActive) return undefined  // (or false — match each fn's retu
 - [ ] **Step 4: Run tests**
 
 ```bash
-npm run test:vitest -- run test/unit/App.reconcile-adoption.test.tsx test/unit/lib/terminal-restore.test.ts test/unit/App.ws-bootstrap.test.tsx test/unit/App.restart-signals.test.tsx
+npm run test:vitest -- run test/unit/client/components/App.reconcile-adoption.test.tsx test/unit/lib/terminal-restore.test.ts test/unit/client/components/App.ws-bootstrap.test.tsx test/unit/client/components/App.restart-signals.test.tsx
 ```
 Expected: PASS (existing App suites prove the legacy path is intact).
 
 - [ ] **Step 5: Commit**
 
 ```bash
-git add src/App.tsx src/lib/terminal-restore.ts test/unit/App.reconcile-adoption.test.tsx test/unit/lib/terminal-restore.test.ts
+git add src/App.tsx src/lib/terminal-restore.ts test/unit/client/components/App.reconcile-adoption.test.tsx test/unit/lib/terminal-restore.test.ts
 git commit -m "feat(client): reconcile on ready-with-capability; census becomes the capability-gated fallback (F3/F4)"
 ```
 
@@ -1107,21 +1195,39 @@ git commit -m "feat(client): reconcile on ready-with-capability; census becomes
 ### Task 12: Client — TerminalView: verdict-driven create, SESSION_RESERVED + INVALID_TERMINAL_ID bounded retry, exhaustion auto-resolve
 
 **Files:**
-- Modify: `src/components/TerminalView.tsx` (create send site :2789-2825; error-frame handling — locate with `rg -n "INVALID_TERMINAL_ID" src/`)
-- Test: Create `test/unit/components/TerminalView.session-reserved.test.tsx`
+- Modify: `src/components/TerminalView.tsx` (create send site :2789-2825; create-or-attach effect dependency array :4486; error-frame handling — locate with `rg -n "INVALID_TERMINAL_ID" src/`)
+- Test: Create `test/unit/client/components/TerminalView.session-reserved.test.tsx`
 
 **Interfaces:**
 - Consumes: `pendingReconcile`/`reconcileNotice` (Task 7/8), `getCreateSessionStateFromRef` (`src/components/terminal-view-utils.ts:9`), `buildReconcileRequestForPanes` + `foldVerdicts` (Task 9), `writeLocalXtermNotice` (:909), server error frames `{code: 'SESSION_RESERVED', requestId, retryAfterMs}` (Task 6).
 - Produces:
-  - Create args: when `pendingReconcile === 'respawn'` → resume args come from `content.sessionRef` (the server-named ref — precedence over any other inference) with `restore: true`; when `'fresh'` → no resume fields; field cleared when `terminal.created` arrives.
-  - `RESERVE_RETRY_WINDOW_MS = 30_000` (> lease TTL 20s + margin, council rule) and `RESERVE_RETRY_FLOOR_MS = 250`: on `SESSION_RESERVED` matching this pane's `createRequestId`, re-send the same `terminal.create` after `max(retryAfterMs, floor)`, until the window is spent.
-  - Exhaustion auto-resolve: after the window, send `buildReconcileRequestForPanes(state, [thisPane])` and fold the single verdict — binding exists → attach silently; winner failed → dead_session/fresh flow with visible notice. Never a permanent error, never a dead button. (This is the client half of `loser-exhausts-then-holder-fails`.)
+  - EFFECT RE-FIRE (A1 fix, load-bearing): add `terminalContent?.reconcileEpoch` to the create-or-attach effect dependency array (`TerminalView.tsx:4486`; the file notes ":4471 terminalId intentionally NOT in dependencies" — keep that; `createRequestId` is still NEVER re-minted, council rule 2 intact). Without this, folding a verdict into an already-mounted pane (same `createRequestId`) does NOT re-fire the effect and the fold is inert. KNOWN SIDE EFFECTS of the re-run: teardown/reattach (`:4455-4463`) and parser resets (`:2735-2740`) — desired for respawn/fresh, acceptable for attach. VERIFY AT IMPLEMENTATION: the ref-sync effect (`:960-990`) must run before the create-or-attach effect (declaration order).
+  - Create args: when `pendingReconcile === 'respawn'` → resume args come from `content.sessionRef` (the server-named ref — precedence over any other inference) with `restore: true`; when `'fresh'` → no resume fields; field cleared when `terminal.created` arrives. Invariant (shared with Task 8): a respawn create must have `sessionRef.provider === pane mode` (`terminal.rs:1047` filters on it — mismatch spawns identity-less); guard loudly.
+  - `RESERVE_RETRY_WINDOW_MS = 30_000` (> lease TTL 20s + margin; the TTL is an explicit wall-clock backstop constant, env-tunable — NOT "2× a spawn budget"; keep the window > TTL + margin if the TTL env knob changes defaults) and `RESERVE_RETRY_FLOOR_MS = 250`: on `SESSION_RESERVED` matching this pane's `createRequestId`, re-send the same `terminal.create` after `max(retryAfterMs, floor)`, until the window is spent.
+  - Exhaustion auto-resolve: after the window, send `buildReconcileRequestForPanes(state, [thisPane])` via the EXISTING `ws.onMessage` broadcast subscription (`ws-client.ts:616-618`, the same mechanism TerminalView already uses at `:3044` — no new correlator module) and fold ONLY the result whose `reconcileId` this pane minted (fold-ownership rule, Task 9) — binding exists → attach silently; winner failed → dead_session/fresh flow with visible notice. Never a permanent error, never a dead button. (This is the client half of `loser-exhausts-then-holder-fails`.)
   - F9: launch-time `INVALID_TERMINAL_ID` for this pane → bounded retry (5 attempts, 500ms apart) through the same re-drive helper before surfacing `status:'error'`.
   - `reconcileNotice` rendered once via `writeLocalXtermNotice` after attach, then `clearPaneReconcileNotice`.
 
-- [ ] **Step 1: Write the failing tests** (fake timers; mock ws-client send; copy mounting scaffold from `test/unit/components/TerminalView.restore-flag-persistence.test.tsx`):
+- [ ] **Step 1: Write the failing tests** (fake timers; mock ws-client send; copy mounting scaffold from `test/unit/client/components/TerminalView.restore-flag-persistence.test.tsx`):
 
 ```ts
+/// REQUIRED red test (A1 fix): folding a verdict into an ALREADY-MOUNTED pane
+/// (same createRequestId — never re-minted) must re-fire the create-or-attach
+/// effect via the reconcileEpoch bump. Without the dep-array change this is
+/// inert (deps key on createRequestId only, TerminalView.tsx:4486).
+it('respawn fold into a mounted pane re-fires the effect (second terminal.create sent)', async () => {
+  const { store } = mountPane({ status: 'running', createRequestId: 'cr-1', terminalId: 'term-old' })
+  store.dispatch(resetPaneForReconcileCreate({ tabId: 'tab1', paneId: 'p1', intent: 'respawn', sessionRef: { provider: 'claude', sessionId: 'server-truth' } }))
+  await flushEffects()
+  expect(countSentOfType('terminal.create')).toBe(2)              // effect re-fired
+  expect(lastSentOfType('terminal.create').requestId).toBe('cr-1') // never re-minted
+})
+it('attach fold into a mounted pane re-fires the effect (xterm attaches to the new terminalId)', async () => {
+  const { store } = mountPane({ status: 'running', createRequestId: 'cr-1', terminalId: 'term-old' })
+  store.dispatch(applyReconcileAttach({ tabId: 'tab1', paneId: 'p1', terminalId: 'term-new' }))
+  await flushEffects()
+  expect(lastAttachedTerminalId()).toBe('term-new')
+})
 it('respawn create uses the server-named sessionRef with restore:true', () => {
   mountPane({ pendingReconcile: 'respawn', sessionRef: { provider: 'claude', sessionId: 'server-truth' }, status: 'creating', createRequestId: 'cr-1' })
   const create = lastSentOfType('terminal.create')
@@ -1158,9 +1264,9 @@ it('INVALID_TERMINAL_ID at launch is retried bounded (F9), not a permanent error
 - [ ] **Step 2: Run to verify failure**
 
 ```bash
-npm run test:vitest -- run test/unit/components/TerminalView.session-reserved.test.tsx
+npm run test:vitest -- run test/unit/client/components/TerminalView.session-reserved.test.tsx
 ```
-Expected: FAIL.
+Expected: FAIL (the two fold-on-mounted tests fail specifically because `reconcileEpoch` is not yet in the effect deps — proving the red is real, not vacuous).
 
 - [ ] **Step 3: Implement.** One small internal helper owns both retries:
 
@@ -1170,18 +1276,19 @@ Expected: FAIL.
 // On exhaustion: single-pane reconcile -> fold (auto-resolve, council rule 8).
 ```
 At the create site, resume-arg precedence: `pendingReconcile === 'respawn'` → `getCreateSessionStateFromRef(content.sessionRef)` result wins; `'fresh'` → omit resume fields entirely. Clear `pendingReconcile` on `terminal.created`. After attach, if `content.reconcileNotice` → `writeLocalXtermNotice(term, content.reconcileNotice)` + dispatch `clearPaneReconcileNotice`.
+Dep-array change (A1 fix): add `terminalContent?.reconcileEpoch` to the create-or-attach effect dependency array at `TerminalView.tsx:4486` — do NOT add `terminalId` (the ":4471" comment stays true) and NEVER re-mint `createRequestId`. Before landing, verify the ref-sync effect (`:960-990`) is declared BEFORE the create-or-attach effect so it runs first on each re-fire.
 
 - [ ] **Step 4: Run tests**
 
 ```bash
-npm run test:vitest -- run test/unit/components/TerminalView.session-reserved.test.tsx test/unit/components/TerminalView.restore-flag-persistence.test.tsx
+npm run test:vitest -- run test/unit/client/components/TerminalView.session-reserved.test.tsx test/unit/client/components/TerminalView.restore-flag-persistence.test.tsx
 ```
 Expected: PASS.
 
 - [ ] **Step 5: Commit**
 
 ```bash
-git add src/components/TerminalView.tsx test/unit/components/TerminalView.session-reserved.test.tsx
+git add src/components/TerminalView.tsx test/unit/client/components/TerminalView.session-reserved.test.tsx
 git commit -m "feat(client): verdict-driven create args; bounded SESSION_RESERVED/INVALID_TERMINAL_ID re-drive with auto-resolve exhaustion"
 ```
 
@@ -1193,11 +1300,11 @@ git commit -m "feat(client): verdict-driven create args; bounded SESSION_RESERVE
 - Create: `src/components/DeadSessionPanel.tsx`
 - Create: `src/components/ReconcileWarmingBanner.tsx`
 - Modify: `src/App.tsx` (render both near the existing modal/banner region)
-- Test: Create `test/unit/components/DeadSessionPanel.test.tsx` (covers both components)
+- Test: Create `test/unit/client/components/DeadSessionPanel.test.tsx` (covers both components)
 
 **Interfaces:**
 - Consumes: `deadSessionAdjudication` / `reconcileWarming` state + `resolveDeadSessionEntry` / `clearDeadSessionAdjudication` / `clearReconcileWarming` / `resetPaneForReconcileCreate` (Task 8); pane-close action (locate the existing close-pane dispatch: `rg -n "closePane" src/store/panesSlice.ts`); `buildReconcileRequestForPanes` (Task 9).
-- Produces: `DeadSessionPanel` — a single `role="dialog"` (aria-label "Dead sessions") listing ALL entries with per-row semantic `<button>`s **Start fresh here** (dispatch `resetPaneForReconcileCreate({intent:'fresh'})` — same `createRequestId`, I7) and **Close pane**, plus **Dismiss** (keeps per-pane restoreError cards; nothing auto-closed). `ReconcileWarmingBanner` — one `role="status"` banner: `Waiting for session index — N pane(s)` + **Retry now** button that re-sends a reconcile request for exactly the warming panes. A11y rules from AGENTS.md apply (semantic buttons, aria-labels, no div-onClick).
+- Produces: `DeadSessionPanel` — a single `role="dialog"` (aria-label "Dead sessions") listing ALL entries with per-row semantic `<button>`s **Start fresh here** (dispatch `resetPaneForReconcileCreate({intent:'fresh'})` — same `createRequestId`, I7) and **Close pane**, plus **Dismiss** (keeps per-pane restoreError cards; nothing auto-closed). `ReconcileWarmingBanner` — one `role="status"` banner: `Waiting for session index — N pane(s)` + **Retry now** button that re-sends a reconcile request for exactly the warming panes (via the EXISTING `ws.onMessage` broadcast subscription — no new correlator module; the banner folds ONLY results whose `reconcileId` its own Retry minted, skipping foreign ones — fold-ownership rule, Task 9). The banner is EXPECTED on cold boots (the index scan can take minutes; see Task 2) — Retry is the recovery path, so it must be prominent, not an edge-case afterthought. A11y rules from AGENTS.md apply (semantic buttons, aria-labels, no div-onClick).
 
 - [ ] **Step 1: Write the failing tests**
 
@@ -1236,7 +1343,7 @@ it('Retry now re-sends a reconcile request for exactly the warming panes', async
 - [ ] **Step 2: Run to verify failure**
 
 ```bash
-npm run test:vitest -- run test/unit/components/DeadSessionPanel.test.tsx
+npm run test:vitest -- run test/unit/client/components/DeadSessionPanel.test.tsx
 ```
 Expected: FAIL.
 
@@ -1245,7 +1352,7 @@ Expected: FAIL.
 - [ ] **Step 4: Run tests + lint (a11y is CI-gated)**
 
 ```bash
-npm run test:vitest -- run test/unit/components/DeadSessionPanel.test.tsx
+npm run test:vitest -- run test/unit/client/components/DeadSessionPanel.test.tsx
 npm run lint
 ```
 Expected: PASS, no new a11y violations.
@@ -1253,7 +1360,7 @@ Expected: PASS, no new a11y violations.
 - [ ] **Step 5: Commit**
 
 ```bash
-git add src/components/DeadSessionPanel.tsx src/components/ReconcileWarmingBanner.tsx src/App.tsx test/unit/components/DeadSessionPanel.test.tsx
+git add src/components/DeadSessionPanel.tsx src/components/ReconcileWarmingBanner.tsx src/App.tsx test/unit/client/components/DeadSessionPanel.test.tsx
 git commit -m "feat(client): batched dead-session adjudication panel + single warming banner with manual retry"
 ```
 
@@ -1264,6 +1371,7 @@ git commit -m "feat(client): batched dead-session adjudication panel + single wa
 **Files:**
 - Create: `test/e2e-browser/specs/reconcile-client-adoption-rust.spec.ts`
 - Modify: `test/e2e-browser/specs/restore-contract-wall-rust.spec.ts` (:1877-1880 pin; :2042 guard)
+- Modify: `test/e2e-browser/playwright.config.ts` (register the new spec — `RUST_ONLY_SPECS` :81+ AND rust-chromium `testMatch` :183+)
 
 **Interfaces:**
 - Consumes: `RustServer` (`test/e2e-browser/helpers/rust-server.ts` — `start()`, `restart()`, `restartAbrupt()`, `stop()`, `info {port, baseUrl, wsUrl, token, homeDir}`); the wall spec's existing fixture-session + `browser.newContext()` patterns (read the wall spec's two-clients test at :1867-1961 and its fixture setup before writing anything).
@@ -1305,7 +1413,9 @@ test('double-restart mid-reconcile converges with no duplicates', async ({ brows
 ```
 These comments are the scenario contract; the bodies must be real Playwright code following the wall spec's helpers (settle-loops, `expect.poll` on `/api/terminals`). Robust additional experiments (e.g. killing one browser context mid-retry) are encouraged as extra tests, not replacements.
 
-- [ ] **Step 4: Run the touched e2e suites**
+- [ ] **Step 4: Register the new spec in the playwright config.** Edit `test/e2e-browser/playwright.config.ts`: add `/reconcile-client-adoption-rust\.spec\.ts$/` to BOTH the `RUST_ONLY_SPECS` array (config line ~81) AND the `rust-chromium` project's explicit `testMatch` (config :183+). WARNING: unregistered = ZERO tests collected under `--project=rust-chromium` (a silent false green for this task) AND the spec would wrongly run under the legacy `chromium` project (match-all minus `RUST_ONLY_SPECS`). Verify collection with `npx playwright test --config test/e2e-browser/playwright.config.ts --project=rust-chromium --list test/e2e-browser/specs/reconcile-client-adoption-rust.spec.ts` — it must list a non-zero test count.
+
+- [ ] **Step 5: Run the touched e2e suites**
 
 ```bash
 npx playwright test --config test/e2e-browser/playwright.config.ts --project=rust-chromium \
@@ -1315,10 +1425,12 @@ npx playwright test --config test/e2e-browser/playwright.config.ts --project=rus
 ```
 Expected: new spec PASS; wall spec PASS including the unpinned two-clients test (this is the headline red→green) and the rewritten double-restart guard. Iterate here until green — this task is the integration proof of the whole lane.
 
-- [ ] **Step 5: Commit**
+- [ ] **Step 6: Wall audit (A12 mitigation).** After flipping the P1.7 pin, the Step-5 full wall-spec run doubles as an audit: if any OTHER `test.fail` pin in `restore-contract-wall-rust.spec.ts` unexpectedly PASSES (an unexpected pass is a HARD suite failure — never leave it), delete that pin in the same commit with a one-line justification, and record the cross-lane ownership note in the task report (the behavior it pinned may belong to a sibling lane).
+
+- [ ] **Step 7: Commit**
 
 ```bash
-git add test/e2e-browser/specs/
+git add test/e2e-browser/specs/ test/e2e-browser/playwright.config.ts
 git commit -m "test(e2e): reconcile client adoption proofs; flip P1.7 D8 pin - two clients one sessionRef now yields exactly 1 PTY"
 ```
 
@@ -1381,8 +1493,8 @@ Do NOT run `gh pr create` (not approved). Report: branch name, commit list, and
 | PROVIDER_UNAVAILABLE for known provider w/o home | 3 |
 | Warming storm → ONE banner | 13 (`restart-storm-all-panes-warming`) |
 | Red test warming-never-completes | 2 |
-| SessionRef-level single-flight; winner binds registry + ledger; others attach | 4, 5, 6 |
-| Liveness-bound lease, TTL kill-before-release, hold-closed on unconfirmed kill | 5, 6 |
+| SessionRef-level single-flight; winner binds the REGISTRY binding map (ledger write pre-exists on the create path, `terminal.rs:1575-1603` — not added by this lane); others attach | 4, 5, 6 |
+| Liveness-bound lease, TTL kill-before-release (registry-handle group-kill; pid-less hang → hold-closed), hold-closed on unconfirmed kill | 5, 6 |
 | Losers: SESSION_RESERVED + retryAfterMs; client window > TTL + margin | 6, 12 |
 | Exhaustion auto-resolves (attach silently / dead-fresh with notice) | 12 (`loser-exhausts-then-holder-fails`) |
 | ≥2-live-PTYs-per-sessionRef alarm | 4 |
@@ -1391,5 +1503,13 @@ Do NOT run `gh pr create` (not approved). Report: branch name, commit list, and
 | Flip P1.7 pins | 14 |
 | E2E: mixed restart / two contexts one sessionRef / dead-session panel / double restart | 14 (two-contexts = the unpinned wall test) |
 | B4 conflict kept tight (reconcile.rs dispatch arm untouched) | 2, 3, 4 (explicit non-goals) |
+| Same-createRequestId folds re-fire the mounted pane (volatile `reconcileEpoch` bump in reducers + effect dep-array add + red fold-on-mounted tests) | 7, 8, 12 |
+| Result-not-guaranteed fallback: correlated error frame is terminal → census from CACHED liveTerminalIds; request re-sent per ready; NO wall-clock timeout | 11 |
+| Volatile reconcile fields stripped from persistence; `pendingReconcile` cleared on `terminal.created` | 8 |
+| respawn folds guarantee `sessionRef.provider === pane mode` (terminal.rs:1047) | 8, 12 |
+| Fold ownership: requesters fold only their own reconcileId (no double-folds; existing ws.onMessage broadcast, no new correlator) | 9, 11, 12, 13 |
+| New e2e spec registered in playwright config (RUST_ONLY_SPECS + rust-chromium testMatch — no false green) | 14 |
+| Wall audit: any OTHER unexpectedly-passing `test.fail` pin deleted in the same commit with justification | 14 |
+| Lease TTL is an explicit env-tunable backstop constant + spawn-duration instrumentation at winner bind | 5, 6 |
 
 No unresolved coverage gaps.

From c13ee24c66b7386414b7b396fcd5679cf026b272 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 03:43:21 -0700
Subject: [PATCH 06/87] docs: harden recover-my-panes plan after load-bearing
 assumption validation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Validated 15 load-bearing assumptions (3 verified, 12 falsified) and fixed
the plan accordingly:
- liveness: inventory joins the terminal registry; live panes recreated
  without resume; new Task 2b adds a guard on the direct sessionRef rung
  (no-restart browser loss would otherwise silently duplicate live sessions)
- ledgerOnly matched across ALL device unions and excludes live rows
- 15-min staleness rule stops stale clientInstanceIds resurrecting closed tabs
- contentId re-keyed to sha256 over timestamp-free substance (DefaultHasher
  churned on 5-min heartbeats and is unstable across Rust releases)
- D1 boot-capture rationale corrected; storage-migration import-order pinned
- per-kind recovery adapter (editor content default, restoreError strip)
- freshopencode fresh-start known limitation documented (fenced B4 crate)
- Task 8 resume proof rebuilt from fake-CLI argv log (cited assertion did
  not exist); browser-pane + no-restart scenarios added
- Task 9: parse_selector/GET snapshot API kept, deploy-tab-diff script+spec
  handled, explicit freshell-ws screenshot broker audit table

Ledger: .worktrees/.the-usual-logs/recover-my-panes/load-bearing-ledger.md

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 docs/plans/2026-07-26-recover-my-panes.md | 530 ++++++++++++++++++----
 1 file changed, 443 insertions(+), 87 deletions(-)

diff --git a/docs/plans/2026-07-26-recover-my-panes.md b/docs/plans/2026-07-26-recover-my-panes.md
index 8f9d8d90e..f255e5caf 100644
--- a/docs/plans/2026-07-26-recover-my-panes.md
+++ b/docs/plans/2026-07-26-recover-my-panes.md
@@ -7,7 +7,7 @@
 
 **Goal:** When a browser connects with no local layout while the server holds recoverable state (pane-identity ledger bindings and/or tabs-snapshots), offer the user "Restore N panes from server memory?" — accept recreates the panes (snapshot = layout, ledger = identity per the §4.2 authority chain), decline is remembered. This resolves campaign item P1.9 and kata h9vt.
 
-**Architecture:** A new authenticated `GET /api/recovery/inventory` endpoint (axum, `crates/freshell-server/src/recovery_inventory.rs`) joins the newest tabs-snapshot generation union (excluding the requesting client's own pushes) with pane-ledger bindings and returns a recoverable inventory. The client captures "had persisted layout at boot" at module load, fetches the inventory when eligible, and shows a self-gating offer panel; accept recreates tabs client-side through the existing `addTab` + `restoreLayout` path (the same path `reopenClosedTab` uses). The operator-only `POST /api/tabs-sync/restore` endpoint and its marker/fence machinery are deleted (kata h9vt Option A disposition, see below).
+**Architecture:** A new authenticated `GET /api/recovery/inventory` endpoint (axum, `crates/freshell-server/src/recovery_inventory.rs`) joins the newest tabs-snapshot generation union (excluding the requesting client's own pushes and stale rotated clients) with pane-ledger bindings and read-only terminal-registry liveness, and returns a recoverable inventory. The client captures "had persisted layout at boot" at module load, fetches the inventory when eligible, and shows a self-gating offer panel; accept recreates tabs client-side through the existing `addTab` + `restoreLayout` path (the same path `reopenClosedTab` uses). The operator-only `POST /api/tabs-sync/restore` endpoint and its marker/fence machinery are deleted (kata h9vt Option A disposition, see below).
 
 **Tech Stack:** Rust (axum 0.8, tokio, serde_json), React 18 + Redux Toolkit + Vitest/Testing Library, Playwright e2e with owned `RustServer` instances.
 
@@ -16,13 +16,13 @@
 **Option A — the tabs-snapshots store becomes load-bearing.** Snapshots are the only durable source of *layout* (the ledger has identity but no layout; localStorage is exactly what's lost in the browser-loss scenario), so ledger-only recovery (Option B) cannot restore tabs/splits/cwd — the store stays.
 
 Within Option A, per the directive "reuse what serves the UI flow, DELETE what doesn't":
-- **REUSED:** the write path (`tabs_persist.rs`, untouched), and the read selectors (`list_snapshot_devices`, `read_device_overview`, `read_generations_union_by_ids`) which feed the new inventory endpoint.
+- **REUSED:** the write path (`tabs_persist.rs`, untouched), the read selectors (`list_snapshot_devices`, `read_device_overview`, `read_generations_union_by_ids`) which feed the new inventory endpoint, and the `GET /api/tabs-sync/snapshots[/{device_id}]` HTTP read API together with `parse_selector` + `Selector` (`tabs_snapshots_selectors.rs`), which its surviving `get_snapshot` handler consumes at `tabs_snapshots.rs:129` — external consumers: `scripts/deploy-tab-diff.sh:53,66,88` curls those endpoints, and the read tests cover them.
 - **DELETED (Task 9):** `POST /api/tabs-sync/restore`, the write-ahead marker module (`tabs_snapshots_marker.rs`), the exactly-one-browser gate, the screenshot delivery-fence (explicitly flagged for deletion — an unreachable fence is context poison), `scripts/restore-tabs.sh`, and `tabs_snapshots_create_body.rs`. Rationale: all of that machinery exists to make a *blind server-push* to an operator-invisible browser safe. The UI flow is client-driven — the client fetches the inventory and recreates panes itself through the normal create path — so there is no server-push, no ambiguous target browser, nothing for a marker or fence to protect.
 
 ## Design Decisions
 
 **D1 — Trigger conditions (Principle 4 compliance).** The offer appears iff ALL of:
-1. `localStorage` had NO layout key (`freshell.layout.v3` and `freshell.layout.v3.bak` both absent) **captured at module load**, before the auto-shell-tab (`App.tsx:1423-1427`) and the 500 ms persist debounce can write one — OR a pending-offer flag from a prior undecided visit is set (see D3).
+1. `localStorage` had NO layout key (`freshell.layout.v3` and `freshell.layout.v3.bak` both absent) **captured at module load**, before the asynchronous writers — the auto-shell-tab (`App.tsx:1423-1427`) and the 500 ms persist debounce — can write one, OR a pending-offer flag from a prior undecided visit is set (see D3). Synchronous module-load writers of `freshell.layout.v3` DO exist (`storage-migration.ts:332/431`, self-executing via `main.tsx`'s first import, and `migrateV2ToV3` at `persistedState.ts:594` during tabsSlice module eval), but each fires only when durable layout data ALREADY existed — so key-presence at boot-state module eval remains the correct "had layout" signal, and the capture design stands. Two invariants are pinned in Task 3: `import '@/store/storage-migration'` stays the FIRST import in `main.tsx` (it re-materializes `freshell.layout.v3` from the `.backup-before-fresh-agent-centralization` key before capture — which is why boot-state checks only v3 + .bak), and `boot-state.ts` is never imported from `main.tsx` above that line.
 2. `GET /api/recovery/inventory` reports `recoverable: true`.
 3. The inventory `contentId` is not in the dismissed list.
 
@@ -30,19 +30,25 @@ Consequences: *empty-never* and *empty-cleared* browsers (both have no layout ke
 
 **D2 — Self-pollution filter.** A fresh browser context mints a fresh per-window `clientInstanceId` (sessionStorage) and starts pushing snapshots (auto shell tab) within seconds. The inventory request carries `?clientInstanceId=<current>`; the server excludes that client's generations when building each device union, so the requester's own junk pushes never appear as "recoverable." (A fresh browser also mints a fresh `deviceId`, so its pushes usually land in a different device dir — the filter covers the selective-clear case where the deviceId survived.)
 
-**D3 — Dismissal + pending persistence.** Decline writes the inventory `contentId` to `localStorage["freshell.recovery.dismissed.v1"]` (array, capped at 20). While the offer is shown but undecided, `localStorage["freshell.recovery.pending.v1"] = contentId` so a reload mid-decision (which by then has a persisted auto-tab layout) re-offers instead of silently losing the recovery chance; accept/decline clears it.
+**D3 — Dismissal + pending persistence.** Decline writes the inventory `contentId` to `localStorage["freshell.recovery.dismissed.v1"]` (array, capped at 20). While the offer is shown but undecided, `localStorage["freshell.recovery.pending.v1"] = contentId` so a reload mid-decision (which by then has a persisted auto-tab layout) re-offers instead of silently losing the recovery chance; accept/decline clears it. "Decline is remembered" means: remembered until the recoverable SUBSTANCE changes. The `contentId` is a sha256 over timestamp-free substance (Task 1), so a dismissal survives server heartbeat re-pushes (which stamp a new `capturedAt` every ≤5 min whenever a second client is connected), server restarts, and Rust upgrades; only a real change to the recoverable panes/sessions re-offers.
 
 **D4 — Authority chain (§4.2): ledger identity beats snapshot claim.** For each snapshot pane with a `sessionRef`, the server joins the ledger and reports a verdict; the client uses `effectiveSessionRef`:
 - ledger row chain (following `supersededBy`, max 10 hops) ends at a `bound` row → resume the **ledger's** `{provider, sessionId}` (snapshot claim overridden).
-- row `retired` with reason `gc_expired` (no live successor) → keep the snapshot ref (the server attach path adjudicates revival — `pane_ledger_auto_resume`).
+- row `retired` with reason `gc_expired` (no live successor) → keep the snapshot ref; the resume happens via the direct wire-`sessionRef` rung in the WS create handler (`terminal.rs:1047`, `:1074-1078`) — the `createRequestId`-keyed ladder (including `pane_ledger_auto_resume`) never runs when a `sessionRef` is sent.
 - row `retired` with reason `closed` → no resume; recreate a fresh pane in the same cwd/mode.
 - no ledger row (e.g. fresh-agent sessions — the ledger has no rows for them) → the snapshot claim stands.
 
-Bound ledger rows referenced by **no** snapshot pane are returned as `ledgerOnly` and recreated in an extra "Recovered sessions" tab, so ledger-known sessions are never dropped just because layout was lost.
+Claude resume requires canonical-UUID session ids (`is_canonical_claude_session_id`, `terminal.rs:1652-1660`): a non-canonical claude ref fails LOUD per-pane with `RestoreUnavailable` (`terminal.rs:1104-1117`) — acceptable, not silent.
 
-**D5 — Recreation path.** Accept dispatches, per inventory tab: `addTab({id: nanoid(), title: tabName})` then `restoreLayout({tabId, layout, paneTitles})` — the exact path `reopenClosedTab` already exercises. `restoreLayout` re-mints `createRequestId`/`status` and strips `terminalId`, so after dispatch we read the post-normalization layout back from the store and arm terminal restore via `addTerminalRestoreRequestId(...)` for every terminal leaf carrying a `sessionRef` (the `App.tsx:1069` / `terminal-restore.ts` pattern) so the create goes out as a restore. Terminal panes get the D4 treatment; non-terminal kinds (`browser`, `editor`, `fresh-agent`, `extension`, `picker`) are recreated by passing the snapshot pane payload through as content (`{kind, ...payload}`) — the same normalize/strip path handles them, exactly as it does for `reopenClosedTab`. The auto-created empty shell tab from `App.tsx:1423` is left in place (deliberate: removing it would touch tab-lifecycle code other lanes own; it is one empty shell tab).
+Bound ledger rows whose `(provider, sessionId)` matches no **effective** pane ref in ANY device union (not just the primary) and that are not owned by a currently-Running terminal (see D7) are returned as `ledgerOnly` and recreated in an extra "Recovered sessions" tab, so ledger-known sessions are never dropped just because layout was lost. Residual: primary-device selection is argmax `capturedAt` and can pick a device the user didn't lose; mitigation — the offer shows `deviceLabel` + `otherDevices`, and decline is cheap.
 
-**D6 — Snapshot records have no split geometry** (flat `panes[]` per tab record), so recreation builds a right-leaning binary split chain (`direction: 'horizontal'`, `sizes: [50, 50]`) — panes come back, geometry is a default. This is what the store contains; not a deferral.
+**D5 — Recreation path.** Accept dispatches, per inventory tab: `addTab({id: nanoid(), title: tabName})` then `restoreLayout({tabId, layout, paneTitles})` — the exact path `reopenClosedTab` already exercises. `restoreLayout` re-mints `createRequestId`/`status` and strips `terminalId`, so after dispatch we read the post-normalization layout back from the store and arm terminal restore via `addTerminalRestoreRequestId(...)` for every terminal leaf carrying a `sessionRef` (the `App.tsx:1069` / `terminal-restore.ts` pattern) so the create goes out as a restore. Panes the inventory marks `live: true` carry no `sessionRef` after Task 4's strip, so they are recreated fresh and never armed (see D7). Terminal panes get the D4 treatment; non-terminal kinds (`browser`, `editor`, `fresh-agent`, `extension`, `picker`) are recreated by passing the snapshot pane payload through as content (`{kind, ...payload}`) with a minimal per-kind adapter (Task 4/A10: `editor` gains the required `content: ''` default per D6; `fresh-agent` drops `restoreError` so normalize keeps the sessionRef) — the same normalize/strip path handles them, exactly as it does for `reopenClosedTab`. The auto-created empty shell tab from `App.tsx:1423` is left in place (deliberate: removing it would touch tab-lifecycle code other lanes own; it is one empty shell tab).
+
+**D6 — Snapshot records have no split geometry** (flat `panes[]` per tab record), so recreation builds a right-leaning binary split chain (`direction: 'horizontal'`, `sizes: [50, 50]`) — panes come back, geometry is a default. This is what the store contains; not a deferral. Likewise a data fact: snapshots never capture editor buffer content (scratch-pad text is not persisted), while `EditorPaneContent.content` is a required field client-side (`paneTypes.ts:116-130`) — recovered editor panes therefore come back with an empty buffer (Task 4 supplies the required `content: ''` default).
+
+**D7 — Live sessions are surfaced, not resumed.** The inventory joins terminal-registry liveness (read-only): every response pane carries `live: true|false` (true iff its effective `(provider, sessionId)` is owned by a currently-Running terminal), and `ledgerOnly` excludes live rows. Panes with `live: true` are recreated WITHOUT resume — `build-recovery-plan` strips their `sessionRef`, they are never armed for terminal restore, and the offer panel notes that sessions still running on the server were left untouched; layout/cwd/mode are still recreated. Attach-to-live was considered and REJECTED: the attach path from a fresh browser is unverified and collides with Lane B1's attach-gate/reconcile ownership. Why this matters: the direct wire-`sessionRef` rung (`terminal.rs:1074-1078`) bypasses the ladder that holds every existing live-guard (`terminal.rs:1690-1745`), so a create carrying a live session's ref would silently spawn a duplicate `claude --resume S` while the original live PTY owns S — the repo's own corruption doctrine (`terminal.rs:1671-1674` "silently wrong"; `:933` one-JSONL-writer). The server-side liveness guard on that direct rung (Task 2b) is defense-in-depth: it closes the inventory-fetch→accept race that client-side stripping alone cannot.
+
+**Known limitation — freshopencode recovers fresh.** Recovered `freshopencode` panes start FRESH: `opencode_ws.rs` `handle_create` never reads `resume_session_id` — a pre-existing bug shared with `reopenClosedTab`, and `crates/freshell-freshagent` is Lane B4's fenced crate, so this lane cannot fix it. We keep the `sessionRef` passthrough anyway (forward-compatible: recovery becomes resume-correct the moment B4 fixes the handler), and Task 10 Step 3's final report must flag this to B4. Claude and codex fresh-agent resume are verified working (`claude.rs:224`, `codex.rs:369-391`).
 
 ## Global Constraints
 
@@ -68,9 +74,17 @@ Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.co
 | `crates/freshell-server/src/recovery_inventory.rs` (create) | Pure inventory builder + axum router/handler for `GET /api/recovery/inventory` |
 | `crates/freshell-server/src/recovery_inventory_tests.rs` (create) | Sibling test module (house convention) |
 | `crates/freshell-server/src/main.rs` (modify) | `mod recovery_inventory;` + one `.merge(...)` |
-| `crates/freshell-server/src/tabs_snapshots.rs` (modify, Task 9) | Restore endpoint deleted; file shrinks to whatever the read side still needs |
-| `crates/freshell-server/src/tabs_snapshots_marker.rs`, `tabs_snapshots_create_body.rs`, `tabs_snapshots_selectors.rs` (delete, Task 9) | Server-push machinery — no UI-flow consumer |
+| `crates/freshell-ws/src/terminal.rs` (modify, Task 2b) | Liveness guard on the direct wire-sessionRef rung (D7 defense-in-depth) |
+| `crates/freshell-ws/tests/live_session_ref_guard.rs` (create, Task 2b) | Integration proof: live session + sessionRef create ⇒ loud refusal, no duplicate spawn |
+| `src/main.tsx` (modify, Task 3) | Comment only — pins the storage-migration-first import-order invariant (D1/A8) |
+| `crates/freshell-server/src/tabs_snapshots.rs` (modify, Task 9) | Restore endpoint deleted; the GET read side (incl. `get_snapshot`) survives |
+| `crates/freshell-server/src/tabs_snapshots_marker.rs`, `tabs_snapshots_create_body.rs` (delete, Task 9) | Server-push machinery — no UI-flow consumer |
+| `crates/freshell-server/src/tabs_snapshots_selectors.rs` (modify, Task 9) | Delete `parse_restore_selection` only; `parse_selector`/`Selector` survive (surviving GET read API) |
+| `crates/freshell-ws/src/screenshot.rs` (modify, Task 9) | Delete client-directed delivery methods per the audit table; broadcast broker survives |
 | `scripts/restore-tabs.sh` (delete, Task 9) | Operator curl wrapper for the deleted endpoint |
+| `scripts/deploy-tab-diff.sh` (modify, Task 9) | Remediation text repointed at the UI recovery flow |
+| `test/e2e-browser/specs/deploy-tab-diff-rust.spec.ts` (modify, Task 9) | Drop restore-tabs.sh execution/assertions; preserve diff-detection coverage |
+| `test/e2e-browser/specs/snapshot-restore-rust.spec.ts` (delete, Task 9) | Drives the deleted endpoint; mixed-kind + resume-argv coverage moves to Task 8 |
 | `src/lib/recovery/boot-state.ts` (create) | Boot-time "had persisted layout" capture |
 | `src/lib/recovery/dismissal.ts` (create) | Dismissed/pending localStorage persistence |
 | `src/lib/recovery/types.ts` (create) | `RecoveryInventory` TS types |
@@ -91,10 +105,11 @@ Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.co
 - Create: `crates/freshell-server/src/recovery_inventory.rs`
 - Create: `crates/freshell-server/src/recovery_inventory_tests.rs`
 - Modify: `crates/freshell-server/src/main.rs` (add `mod recovery_inventory;` only)
+- Modify: `crates/freshell-server/Cargo.toml` (only if `sha2`/hex aren't already dependencies — needed by `digest16`)
 
 **Interfaces:**
 - Consumes: `freshell_ws::pane_ledger::BindingRow` (fields serialize camelCase: `provider`, `sessionId`, `mode`, `cwd`, `state: bound|retired`, `retiredReason?: superseded|closed|gc_expired`, `supersededBy?: {provider, sessionId}`, `updatedAt`). Snapshot union doc shape (from `tabs_persist.rs`): `{deviceId, deviceLabel, capturedAt, records: [{tabKey, tabId, tabName, revision, updatedAt, paneCount, panes: [{paneId, kind, payload: {mode?, shell?, initialCwd?, sessionRef?: {provider, sessionId}, createRequestId?, ...}}]}]}`.
-- Produces: `pub struct DeviceUnion { pub device_id: String, pub union_doc: serde_json::Value }` and `pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow>) -> serde_json::Value` returning:
+- Produces: `pub struct DeviceUnion { pub device_id: String, pub union_doc: serde_json::Value }`, `pub fn select_foreign_recent_generation_ids(generations: &[serde_json::Value], exclude_client: &str) -> Vec<String>` (the A15 staleness filter, consumed by Task 2), and `pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow>, live_session_keys: HashSet<(String, String)>) -> serde_json::Value` — the third input is the set of `(provider, sessionId)` pairs owned by a currently-Running terminal (Task 2 feeds it from the terminal registry, read-only) — returning:
 
 ```json
 {
@@ -108,7 +123,7 @@ Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.co
           { "paneId": "p1", "kind": "terminal", "mode": "claude", "shell": null,
             "cwd": "/home/dan/proj", "payload": { "...": "verbatim snapshot payload" },
             "sessionRef": { "provider": "claude", "sessionId": "S2" },
-            "ledgerState": "bound" }
+            "ledgerState": "bound", "live": false }
         ] }
     ]
   },
@@ -117,7 +132,14 @@ Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.co
 }
 ```
 
-Rules encoded: `device` = the union with the greatest `capturedAt` that has ≥1 record; every pane's `sessionRef` in the response is the **effective** ref per Design Decision D4 (`ledgerState` ∈ `bound|closed|gc_expired|unknown`; `closed` ⇒ `sessionRef: null`); `ledgerOnly` = `state == bound` rows whose `(provider, sessionId)` matches no effective pane ref in the primary device; `contentId` = hex of `std::hash::DefaultHasher` over the sorted list of `<deviceId>:<capturedAt>` for all unions plus sorted `<provider>:<sessionId>:<updatedAt>` for all bound rows (`DefaultHasher::new()` is deterministic across runs); `recoverable` = primary device exists OR `ledgerOnly` non-empty. Empty input ⇒ `{"recoverable": false, "contentId": "...", "device": null, "otherDevices": [], "ledgerOnly": []}`.
+Rules encoded:
+- `device` = the union with the greatest `capturedAt` that has ≥1 record.
+- Every pane's `sessionRef` in the response is the **effective** ref per Design Decision D4 (`ledgerState` ∈ `bound|closed|gc_expired|unknown`; `closed` ⇒ `sessionRef: null`).
+- Every pane carries `"live": true|false` — true iff its effective `(provider, sessionId)` ∈ `live_session_keys` (D7).
+- `ledgerOnly` = `state == bound` rows whose `(provider, sessionId)` matches no effective pane ref in ANY device union (not just the primary — a two-device steady state must not report the other device's sessions as orphaned) AND that is not in the live set (D7).
+- `contentId` = sha256 truncated to 16 hex chars (reuse the repo's digest convention — `digest_value`/`snapshot_content_id`, `tabs_persist.rs:70-87`) over the TIMESTAMP-FREE canonical substance: the sorted list of `(deviceId, tabKey, paneId, kind, effective provider:sessionId or "-")` for every pane in every included device union, plus sorted `provider:sessionId` for the `ledgerOnly` rows. `capturedAt`/`updatedAt` are EXCLUDED by design: the server heartbeat re-pushes stamp a new `capturedAt` every ≤5 min with any second connected client, and that churn must not defeat dismissal (D3).
+- `recoverable` = primary device exists OR `ledgerOnly` non-empty. Empty input ⇒ `{"recoverable": false, "contentId": "...", "device": null, "otherDevices": [], "ledgerOnly": []}`.
+- `select_foreign_recent_generation_ids` (A15 staleness rule, applied by Task 2 when composing each device's union): drop the requester's own generations, then drop every client whose newest generation `capturedAt` is more than 15 minutes older than that device's max `capturedAt` **computed over the remaining foreign clients** (the requester's just-pushed junk must never stale-out real recovery data). Rationale: every connected window force-pushes a heartbeat at least every 5 min (`tabRegistrySync.ts:21, 475-477`), so any client silent for >15 min is closed or rotated; this suppresses resurrection of closed tabs via the purely-additive union (closed tabs leave no durable trace — only open records are persisted). Post-filtering generations here leaves the `tabs_persist` write path untouched.
 
 - [ ] **Step 1: Write the failing tests**
 
@@ -126,6 +148,15 @@ Create `crates/freshell-server/src/recovery_inventory_tests.rs`. Use the sibling
 ```rust
 use super::*;
 use serde_json::json;
+use std::collections::HashSet;
+
+fn no_live() -> HashSet<(String, String)> {
+    HashSet::new()
+}
+
+fn live(pairs: &[(&str, &str)]) -> HashSet<(String, String)> {
+    pairs.iter().map(|(p, s)| (p.to_string(), s.to_string())).collect()
+}
 
 fn union_doc(device: &str, captured_at: u64, panes: serde_json::Value) -> serde_json::Value {
     json!({
@@ -137,7 +168,7 @@ fn union_doc(device: &str, captured_at: u64, panes: serde_json::Value) -> serde_
 
 #[test]
 fn empty_inputs_not_recoverable() {
-    let out = build_inventory(vec![], vec![]);
+    let out = build_inventory(vec![], vec![], no_live());
     assert_eq!(out["recoverable"], false);
     assert!(out["device"].is_null());
     assert_eq!(out["ledgerOnly"].as_array().unwrap().len(), 0);
@@ -147,10 +178,11 @@ fn empty_inputs_not_recoverable() {
 fn newest_device_wins_others_summarized() {
     let old = DeviceUnion { device_id: "dev0".into(), union_doc: union_doc("dev0", 500, json!([{ "paneId": "p0", "kind": "terminal", "payload": {"mode": "shell"} }])) };
     let new = DeviceUnion { device_id: "dev1".into(), union_doc: union_doc("dev1", 1000, json!([{ "paneId": "p1", "kind": "terminal", "payload": {"mode": "shell", "initialCwd": "/w"} }])) };
-    let out = build_inventory(vec![old, new], vec![]);
+    let out = build_inventory(vec![old, new], vec![], no_live());
     assert_eq!(out["recoverable"], true);
     assert_eq!(out["device"]["deviceId"], "dev1");
     assert_eq!(out["device"]["tabs"][0]["panes"][0]["cwd"], "/w");
+    assert_eq!(out["device"]["tabs"][0]["panes"][0]["live"], false);
     assert_eq!(out["otherDevices"][0]["deviceId"], "dev0");
     assert_eq!(out["otherDevices"][0]["paneCount"], 1);
 }
@@ -165,7 +197,7 @@ fn ledger_bound_row_overrides_snapshot_claim_via_superseded_chain() {
         binding_row("claude", "S1", retired_superseded_by("claude", "S2")),
         binding_row("claude", "S2", bound()),
     ];
-    let out = build_inventory(vec![d], bindings);
+    let out = build_inventory(vec![d], bindings, no_live());
     let pane = &out["device"]["tabs"][0]["panes"][0];
     assert_eq!(pane["ledgerState"], "bound");
     assert_eq!(pane["sessionRef"]["sessionId"], "S2"); // ledger identity beat the snapshot claim
@@ -183,7 +215,7 @@ fn closed_row_strips_resume_gc_expired_keeps_snapshot_ref_unknown_passes_through
         binding_row("claude", "CLOSED", retired_closed()),
         binding_row("codex", "EXPIRED", retired_gc_expired()),
     ];
-    let out = build_inventory(vec![d], bindings);
+    let out = build_inventory(vec![d], bindings, no_live());
     let panes = out["device"]["tabs"][0]["panes"].as_array().unwrap();
     assert_eq!(panes[0]["ledgerState"], "closed");
     assert!(panes[0]["sessionRef"].is_null());
@@ -195,22 +227,84 @@ fn closed_row_strips_resume_gc_expired_keeps_snapshot_ref_unknown_passes_through
 
 #[test]
 fn unreferenced_bound_rows_become_ledger_only() {
-    let out = build_inventory(vec![], vec![binding_row("codex", "C9", bound())]);
+    let out = build_inventory(vec![], vec![binding_row("codex", "C9", bound())], no_live());
     assert_eq!(out["recoverable"], true);
     assert_eq!(out["ledgerOnly"][0]["sessionId"], "C9");
 }
 
+#[test]
+fn bound_row_referenced_by_non_primary_device_is_not_ledger_only() {
+    // A4: a two-device steady state must not report the OTHER device's sessions as orphaned.
+    let newer = DeviceUnion { device_id: "dev1".into(), union_doc: union_doc("dev1", 1000,
+        json!([{ "paneId": "p1", "kind": "terminal", "payload": {"mode": "shell"} }])) };
+    let older = DeviceUnion { device_id: "dev0".into(), union_doc: union_doc("dev0", 500,
+        json!([{ "paneId": "p0", "kind": "terminal",
+                 "payload": { "mode": "codex", "sessionRef": { "provider": "codex", "sessionId": "C9" } } }])) };
+    let out = build_inventory(vec![newer, older], vec![binding_row("codex", "C9", bound())], no_live());
+    assert_eq!(out["device"]["deviceId"], "dev1"); // dev0 is NON-primary
+    assert_eq!(out["ledgerOnly"].as_array().unwrap().len(), 0,
+        "C9 is referenced by dev0's union - not orphaned");
+}
+
+#[test]
+fn live_effective_ref_marks_pane_live_and_live_rows_never_ledger_only() {
+    // D7: pane resolves (via ledger chain) to S2, which a Running terminal owns;
+    // a second live bound row C9 is referenced by no pane.
+    let d = DeviceUnion { device_id: "dev1".into(), union_doc: union_doc("dev1", 1000,
+        json!([{ "paneId": "p1", "kind": "terminal",
+                 "payload": { "mode": "claude", "sessionRef": { "provider": "claude", "sessionId": "S1" } } }])) };
+    let bindings = vec![
+        binding_row("claude", "S1", retired_superseded_by("claude", "S2")),
+        binding_row("claude", "S2", bound()),
+        binding_row("codex", "C9", bound()),
+    ];
+    let out = build_inventory(vec![d], bindings, live(&[("claude", "S2"), ("codex", "C9")]));
+    let pane = &out["device"]["tabs"][0]["panes"][0];
+    assert_eq!(pane["live"], true);
+    assert_eq!(pane["sessionRef"]["sessionId"], "S2"); // ref still reported; the CLIENT strips it (Task 4, D7)
+    assert_eq!(out["ledgerOnly"].as_array().unwrap().len(), 0, "live bound rows are excluded from ledgerOnly");
+}
+
 #[test]
 fn content_id_is_stable_and_input_sensitive() {
-    let a = build_inventory(vec![], vec![binding_row("codex", "C9", bound())]);
-    let b = build_inventory(vec![], vec![binding_row("codex", "C9", bound())]);
-    let c = build_inventory(vec![], vec![binding_row("codex", "C8", bound())]);
+    let a = build_inventory(vec![], vec![binding_row("codex", "C9", bound())], no_live());
+    let b = build_inventory(vec![], vec![binding_row("codex", "C9", bound())], no_live());
+    let c = build_inventory(vec![], vec![binding_row("codex", "C8", bound())], no_live());
     assert_eq!(a["contentId"], b["contentId"]);
     assert_ne!(a["contentId"], c["contentId"]);
 }
+
+#[test]
+fn content_id_ignores_timestamp_churn() {
+    // A5/A6: heartbeat re-pushes bump capturedAt/updatedAt every <=5 min - dismissal must survive.
+    let doc = |captured_at| union_doc("dev1", captured_at,
+        json!([{ "paneId": "p1", "kind": "terminal", "payload": {"mode": "shell"} }]));
+    let a = build_inventory(vec![DeviceUnion { device_id: "dev1".into(), union_doc: doc(1000) }],
+        vec![binding_row_at("codex", "C9", bound(), 1000)], no_live());
+    let b = build_inventory(vec![DeviceUnion { device_id: "dev1".into(), union_doc: doc(2000) }],
+        vec![binding_row_at("codex", "C9", bound(), 2000)], no_live());
+    assert_eq!(a["contentId"], b["contentId"],
+        "bumping only capturedAt/updatedAt must not change contentId");
+}
+
+#[test]
+fn stale_clients_generations_are_dropped() {
+    // A15: any client silent >15 min (heartbeat is 5 min) is closed or rotated - drop it.
+    let t_max: u64 = 100_000_000;
+    let gens = vec![
+        json!({"generationId": "gA", "clientInstanceId": "fresh", "capturedAt": t_max}),
+        json!({"generationId": "gB", "clientInstanceId": "fresh", "capturedAt": t_max - 60_000}),
+        json!({"generationId": "gC", "clientInstanceId": "stale", "capturedAt": t_max - 16 * 60 * 1000}),
+        json!({"generationId": "gD", "clientInstanceId": "me",    "capturedAt": t_max}),
+    ];
+    let ids = select_foreign_recent_generation_ids(&gens, "me");
+    assert!(ids.contains(&"gA".to_string()) && ids.contains(&"gB".to_string()));
+    assert!(!ids.contains(&"gC".to_string()), "stale rotated client must not resurrect closed tabs");
+    assert!(!ids.contains(&"gD".to_string()), "requester's own generations are excluded");
+}
 ```
 
-Write small local helpers `binding_row(provider, session_id, state_parts)`, `bound()`, `retired_closed()`, `retired_gc_expired()`, `retired_superseded_by(p, s)` that construct real `BindingRow` values (copy field names/enums from `crates/freshell-ws/src/pane_ledger.rs:93`; fill required timestamps with constants like `1000`).
+Write small local helpers `binding_row(provider, session_id, state_parts)`, `binding_row_at(provider, session_id, state_parts, updated_at)` (same, with a settable `updatedAt` — the timestamp-churn test needs it), `bound()`, `retired_closed()`, `retired_gc_expired()`, `retired_superseded_by(p, s)` that construct real `BindingRow` values (copy field names/enums from `crates/freshell-ws/src/pane_ledger.rs:93`; fill required timestamps with constants like `1000`).
 
 Create `crates/freshell-server/src/recovery_inventory.rs` containing ONLY the types + an `unimplemented!()`-free stub that compiles but returns `json!(null)`, plus the test include:
 
@@ -232,13 +326,37 @@ Expected: FAIL — assertions fail against the `null` stub (compilation must suc
 In `recovery_inventory.rs`:
 
 ```rust
-use std::collections::HashMap;
-use std::hash::{DefaultHasher, Hash, Hasher};
+use std::collections::{HashMap, HashSet};
 use freshell_ws::pane_ledger::BindingRow;
 use serde_json::{json, Value};
 
 pub struct DeviceUnion { pub device_id: String, pub union_doc: Value }
 
+const STALE_CLIENT_MS: u64 = 15 * 60 * 1000; // heartbeat cadence is 5 min (tabRegistrySync.ts:21, 475-477)
+
+/// A15 staleness rule: drop the requester's own generations, then drop clients whose
+/// newest generation is >15 min older than the device max over the REMAINING foreign
+/// clients (the requester's just-pushed junk must never stale-out real recovery data).
+pub fn select_foreign_recent_generation_ids(generations: &[Value], exclude_client: &str) -> Vec<String> {
+    let foreign: Vec<&Value> = generations.iter()
+        .filter(|g| g["clientInstanceId"].as_str() != Some(exclude_client)).collect();
+    let mut newest_by_client: HashMap<&str, u64> = HashMap::new();
+    for g in &foreign {
+        let c = g["clientInstanceId"].as_str().unwrap_or("");
+        let t = g["capturedAt"].as_u64().unwrap_or(0);
+        let e = newest_by_client.entry(c).or_insert(0);
+        if t > *e { *e = t; }
+    }
+    let device_max = newest_by_client.values().copied().max().unwrap_or(0);
+    foreign.iter()
+        .filter(|g| {
+            let c = g["clientInstanceId"].as_str().unwrap_or("");
+            newest_by_client.get(c).copied().unwrap_or(0) + STALE_CLIENT_MS >= device_max
+        })
+        .filter_map(|g| g["generationId"].as_str().map(String::from))
+        .collect()
+}
+
 fn ref_key(provider: &str, session_id: &str) -> String { format!("{provider}\u{1}{session_id}") }
 
 enum Verdict { Bound(String, String), Closed, GcExpired, Unknown }
@@ -258,30 +376,26 @@ fn resolve(provider: &str, session_id: &str, by_key: &HashMap<String, &BindingRo
     Verdict::GcExpired
 }
 
-pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow>) -> Value {
+pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow>,
+                       live_session_keys: HashSet<(String, String)>) -> Value {
     let by_key: HashMap<String, &BindingRow> = bindings.iter()
         .map(|r| (ref_key(&row_provider(r), &row_session_id(r)), r)).collect();
+    let is_live = |p: &str, s: &str| live_session_keys.contains(&(p.to_string(), s.to_string()));
 
-    // contentId over ALL inputs (stable, order-independent)
-    let mut ids: Vec<String> = device_unions.iter()
-        .map(|d| format!("{}:{}", d.device_id, d.union_doc["capturedAt"])).collect();
-    ids.extend(bindings.iter().filter(|r| row_is_bound(r))
-        .map(|r| format!("{}:{}:{}", row_provider(r), row_session_id(r), row_updated_at(r))));
-    ids.sort();
-    let mut h = DefaultHasher::new();
-    ids.hash(&mut h);
-    let content_id = format!("{:016x}", h.finish());
-
-    // pick primary device: greatest capturedAt with >=1 record
+    // sort newest-first; primary device = greatest capturedAt with >=1 record
     let mut unions = device_unions;
     unions.sort_by_key(|d| std::cmp::Reverse(d.union_doc["capturedAt"].as_u64().unwrap_or(0)));
-    let primary_idx = unions.iter().position(|d|
-        d.union_doc["records"].as_array().map(|r| !r.is_empty()).unwrap_or(false));
 
-    let mut referenced: Vec<String> = vec![];
-    let device = primary_idx.map(|i| {
-        let doc = &unions[i].union_doc;
-        let tabs: Vec<Value> = doc["records"].as_array().unwrap().iter().map(|rec| {
+    // Pass 1 - resolve EVERY pane in EVERY union (not just the primary): effective refs
+    // feed the cross-device ledgerOnly rule (A4) and the contentId substance (A5/A6);
+    // the primary union's tabs feed `device`.
+    let mut referenced: HashSet<String> = HashSet::new();
+    let mut substance: Vec<String> = Vec::new();
+    let mut tabs_per_union: Vec<Vec<Value>> = Vec::new();
+    for d in &unions {
+        let doc = &d.union_doc;
+        let device_id = doc["deviceId"].as_str().unwrap_or("").to_string();
+        let tabs: Vec<Value> = doc["records"].as_array().cloned().unwrap_or_default().iter().map(|rec| {
             let panes: Vec<Value> = rec["panes"].as_array().cloned().unwrap_or_default().iter().map(|pane| {
                 let payload = &pane["payload"];
                 let snap_ref = payload.get("sessionRef").filter(|v| !v.is_null()).cloned();
@@ -297,9 +411,19 @@ pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow
                         }
                     }
                 };
+                let eff_str = eff_ref.as_ref()
+                    .map(|r| format!("{}:{}", r["provider"].as_str().unwrap_or(""), r["sessionId"].as_str().unwrap_or("")))
+                    .unwrap_or_else(|| "-".into());
+                let live = eff_ref.as_ref()
+                    .map(|r| is_live(r["provider"].as_str().unwrap_or(""), r["sessionId"].as_str().unwrap_or("")))
+                    .unwrap_or(false);
                 if let Some(er) = &eff_ref {
-                    referenced.push(ref_key(er["provider"].as_str().unwrap_or(""), er["sessionId"].as_str().unwrap_or("")));
+                    referenced.insert(ref_key(er["provider"].as_str().unwrap_or(""), er["sessionId"].as_str().unwrap_or("")));
                 }
+                // TIMESTAMP-FREE substance line: capturedAt/updatedAt deliberately absent (D3)
+                substance.push(format!("{}\u{1}{}\u{1}{}\u{1}{}\u{1}{}",
+                    device_id, rec["tabKey"].as_str().unwrap_or(""),
+                    pane["paneId"].as_str().unwrap_or(""), pane["kind"].as_str().unwrap_or(""), eff_str));
                 json!({
                     "paneId": pane["paneId"], "kind": pane["kind"],
                     "mode": payload.get("mode").cloned().unwrap_or(Value::Null),
@@ -308,12 +432,21 @@ pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow
                     "payload": payload.clone(),
                     "sessionRef": eff_ref.unwrap_or(Value::Null),
                     "ledgerState": ledger_state,
+                    "live": live,
                 })
             }).collect();
             json!({"tabKey": rec["tabKey"], "tabName": rec["tabName"], "panes": panes})
         }).collect();
+        tabs_per_union.push(tabs);
+    }
+
+    let primary_idx = unions.iter().position(|d|
+        d.union_doc["records"].as_array().map(|r| !r.is_empty()).unwrap_or(false));
+
+    let device = primary_idx.map(|i| {
+        let doc = &unions[i].union_doc;
         json!({"deviceId": doc["deviceId"], "deviceLabel": doc["deviceLabel"],
-               "capturedAt": doc["capturedAt"], "tabs": tabs})
+               "capturedAt": doc["capturedAt"], "tabs": tabs_per_union[i].clone()})
     });
 
     let other_devices: Vec<Value> = unions.iter().enumerate()
@@ -328,11 +461,20 @@ pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow
 
     let ledger_only: Vec<Value> = bindings.iter()
         .filter(|r| row_is_bound(r))
+        // vs effective refs across ALL unions (A4), not just the primary device
         .filter(|r| !referenced.contains(&ref_key(&row_provider(r), &row_session_id(r))))
+        // live rows are excluded: sessions still running are never offered for resume (D7)
+        .filter(|r| !is_live(&row_provider(r), &row_session_id(r)))
         .map(|r| json!({"provider": row_provider(r), "sessionId": row_session_id(r),
                         "mode": row_mode(r), "cwd": row_cwd(r)}))
         .collect();
 
+    // contentId: sha256 over the sorted TIMESTAMP-FREE substance (A5/A6, D3)
+    substance.extend(ledger_only.iter().map(|e|
+        format!("{}:{}", e["provider"].as_str().unwrap_or(""), e["sessionId"].as_str().unwrap_or(""))));
+    substance.sort();
+    let content_id = digest16(&substance);
+
     let recoverable = device.is_some() || !ledger_only.is_empty();
     json!({"recoverable": recoverable, "contentId": content_id,
            "device": device.unwrap_or(Value::Null),
@@ -340,12 +482,14 @@ pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow
 }
 ```
 
-The `row_*` accessor helpers (`row_provider`, `row_session_id`, `row_is_bound`, `row_reason_is_closed`, `row_successor`, `row_mode`, `row_cwd`, `row_updated_at`) are thin one-line wrappers over the actual `BindingRow` fields/enums — write them against the real definitions in `pane_ledger.rs:93` (they exist so this module compiles against whatever the exact enum spellings are; each is a single field access, not logic).
+The `row_*` accessor helpers (`row_provider`, `row_session_id`, `row_is_bound`, `row_reason_is_closed`, `row_successor`, `row_mode`, `row_cwd`) are thin one-line wrappers over the actual `BindingRow` fields/enums — write them against the real definitions in `pane_ledger.rs:93` (they exist so this module compiles against whatever the exact enum spellings are; each is a single field access, not logic).
+
+`digest16(parts: &[String]) -> String` is the contentId digest: sha256 over the parts joined with `\u{1}`, hex-encoded, truncated to 16 chars. Reuse the repo's digest convention — copy the shape of `digest_value`/`snapshot_content_id` from `crates/freshell-ws/src/tabs_persist.rs:70-87` and its `sha2`/hex approach (add the dependency to `freshell-server`'s `Cargo.toml` if it isn't already there).
 
 - [ ] **Step 4: Run tests to verify they pass**
 
 Run: `cargo test -p freshell-server recovery_inventory`
-Expected: PASS (all 6 tests).
+Expected: PASS (all 10 tests).
 
 - [ ] **Step 5: Format, lint, commit**
 
@@ -363,12 +507,13 @@ git commit -m "feat(server): pure recovery-inventory builder joining snapshots w
 - Modify: `crates/freshell-server/src/recovery_inventory.rs` (add state/router/handler)
 - Modify: `crates/freshell-server/src/recovery_inventory_tests.rs` (add route tests)
 - Modify: `crates/freshell-server/src/main.rs` (one `.merge(...)` in the router assembly at ~`main.rs:759+`)
+- Modify (only if needed): the terminal registry in `crates/freshell-terminal/` — a read-only row-listing accessor for the liveness join, if none is public today (no behavior change)
 
 **Interfaces:**
-- Consumes: `freshell_ws::tabs_persist::{list_snapshot_devices, read_device_overview, read_generations_union_by_ids}` (sync `io::Result`, must run in `spawn_blocking`); `freshell_ws::pane_ledger::PaneLedger::list_bindings()` (sync, memory-only, callable directly); the per-handler auth helper used by `tabs_snapshots.rs` handlers (`is_authed(&headers, &state.auth_token)` — copy the exact import from that file); `build_inventory` from Task 1.
-- Produces: `pub struct RecoveryInventoryState { pub auth_token: String, pub snapshots_dir: Option<std::path::PathBuf>, pub ledger: std::sync::Arc<freshell_ws::pane_ledger::PaneLedger> }` (`#[derive(Clone)]`) and `pub fn router(state: RecoveryInventoryState) -> axum::Router`. Route: `GET /api/recovery/inventory?clientInstanceId=<id>`.
+- Consumes: `freshell_ws::tabs_persist::{list_snapshot_devices, read_device_overview, read_generations_union_by_ids}` (sync `io::Result`, must run in `spawn_blocking`); `freshell_ws::pane_ledger::PaneLedger::list_bindings()` (sync, memory-only, callable directly); the shared terminal-registry handle (read-only — the same instance the WS server state receives; copy the exact type + binding name from `main.rs`) for the liveness join; `select_foreign_recent_generation_ids` and `build_inventory` from Task 1; the per-handler auth helper used by `tabs_snapshots.rs` handlers (`is_authed(&headers, &state.auth_token)` — copy the exact import from that file).
+- Produces: `pub struct RecoveryInventoryState { pub auth_token: String, pub snapshots_dir: Option<std::path::PathBuf>, pub ledger: std::sync::Arc<freshell_ws::pane_ledger::PaneLedger>, pub registry: /* shared terminal-registry handle, same type main.rs wires into the WS state */ }` (`#[derive(Clone)]`) and `pub fn router(state: RecoveryInventoryState) -> axum::Router`. Route: `GET /api/recovery/inventory?clientInstanceId=<id>`.
 
-Handler behavior: 401 without valid token (same check as every other handler); with `snapshots_dir: None` or missing dir → inventory built from ledger only; snapshot reads: `spawn_blocking` over `(dir, exclude_client)` doing — `list_snapshot_devices(&dir)` → for each device `read_device_overview(&dir, &device)` → from the overview's generation list select generation ids whose `clientInstanceId` != `exclude_client` → `read_generations_union_by_ids(&dir, &device, &ids)` → collect `DeviceUnion`. Devices with zero foreign generations are skipped. IO errors and `JoinError` → 500 + `tracing::error!` (fail-loud, three-arm match, same shape as the dryRun path at `tabs_snapshots.rs:330`). Then `build_inventory(unions, state.ledger.list_bindings())` → `Json(...)`.
+Handler behavior: 401 without valid token (same check as every other handler); with `snapshots_dir: None` or missing dir → inventory built from ledger only; snapshot reads: `spawn_blocking` over `(dir, exclude_client)` doing — `list_snapshot_devices(&dir)` → for each device `read_device_overview(&dir, &device)` → select generation ids via `select_foreign_recent_generation_ids(&generations, &exclude_client)` (Task 1 — drops the requester's own generations AND stale clients per the A15 recency rule) → `read_generations_union_by_ids(&dir, &device, &ids)` → collect `DeviceUnion`. Devices with zero surviving generations are skipped. IO errors and `JoinError` → 500 + `tracing::error!` (fail-loud, three-arm match, same shape as the dryRun path at `tabs_snapshots.rs:330`). Then build the live set from the registry (read-only): `live_session_keys(&state.registry)` collects `(provider = mode, sessionId)` for every currently-Running terminal row — the same row fields the ladder's A13 guard reads at `terminal.rs:1690-1745`; if the registry lacks a public row-listing accessor, add a read-only one to `freshell-terminal` (no behavior change). Finally `build_inventory(unions, state.ledger.list_bindings(), live)` → `Json(...)`.
 
 - [ ] **Step 1: Write the failing route tests**
 
@@ -392,6 +537,9 @@ fn test_state(dir: Option<std::path::PathBuf>, ledger_root: Option<std::path::Pa
         auth_token: "tok".into(),
         snapshots_dir: dir,
         ledger: std::sync::Arc::new(freshell_ws::pane_ledger::PaneLedger::new_locked(ledger_root)),
+        // fresh EMPTY terminal registry - construct it exactly the way main.rs does (copy the
+        // type + constructor); no running terminals => every pane comes back `live: false`
+        registry: test_registry(),
     }
 }
 
@@ -446,6 +594,27 @@ async fn route_serves_ledger_only_recovery_without_snapshots() {
     assert_eq!(body["recoverable"], true);
     assert_eq!(body["ledgerOnly"][0]["sessionId"], "S1");
 }
+
+#[tokio::test]
+async fn route_drops_stale_rotated_clients() {
+    // A15: a client silent >15 min (heartbeat is 5 min) is closed or rotated - its
+    // resurrected tab must not enter the inventory union.
+    let tmp = tempfile::tempdir().unwrap();
+    let t_max: u64 = 100_000_000;
+    write_snapshot(tmp.path(), "dev1", "fresh", t_max, 1, json!([
+        {"tabKey":"k1","tabId":"t1","tabName":"work","status":"open","revision":1,"updatedAt":t_max,
+         "paneCount":1,"panes":[{"paneId":"p1","kind":"terminal","payload":{"mode":"shell"}}]}
+    ]));
+    write_snapshot(tmp.path(), "dev1", "stale", t_max - 16 * 60 * 1000, 1, json!([
+        {"tabKey":"zombie","tabId":"tz","tabName":"zombie","status":"open","revision":1,"updatedAt":t_max - 16 * 60 * 1000,
+         "paneCount":1,"panes":[{"paneId":"pz","kind":"terminal","payload":{"mode":"shell"}}]}
+    ]));
+    let router = router(test_state(Some(tmp.path().to_path_buf()), None));
+    let (_, body) = get(router, "/api/recovery/inventory?clientInstanceId=me", Some("tok")).await;
+    let tabs = body["device"]["tabs"].as_array().unwrap();
+    assert!(tabs.iter().all(|t| t["tabKey"] != "zombie"), "stale client's tab must be dropped");
+    assert!(tabs.iter().any(|t| t["tabKey"] == "k1"));
+}
 ```
 
 (If the on-disk binding filename/JSON differs, copy the exact shape from `pane_ledger_tests.rs` fixtures — the test contract stands: a pre-seeded bound row surfaces in `ledgerOnly`.)
@@ -465,6 +634,9 @@ pub struct RecoveryInventoryState {
     pub auth_token: String,
     pub snapshots_dir: Option<std::path::PathBuf>,
     pub ledger: std::sync::Arc<freshell_ws::pane_ledger::PaneLedger>,
+    // read-only liveness join (D7): the SAME shared terminal-registry handle the WS
+    // server state receives - copy the exact type + binding name from main.rs
+    pub registry: /* shared terminal-registry handle */,
 }
 
 #[derive(serde::Deserialize)]
@@ -489,7 +661,17 @@ async fn inventory_handler(State(state): State<RecoveryInventoryState>, headers:
             }
         }
     };
-    Json(build_inventory(unions, state.ledger.list_bindings())).into_response()
+    let live = live_session_keys(&state.registry);
+    Json(build_inventory(unions, state.ledger.list_bindings(), live)).into_response()
+}
+
+/// Read-only liveness join (D7): (provider = mode, sessionId) for every currently-Running
+/// terminal row - the same row fields the ladder's A13 guard reads (terminal.rs:1690-1745,
+/// mode + resume/preallocated session id, status == TerminalRunStatus::Running). If the
+/// registry lacks a public row-listing accessor, add a read-only one to freshell-terminal
+/// (no behavior change).
+fn live_session_keys(registry: &/* registry handle type */) -> std::collections::HashSet<(String, String)> {
+    /* iterate rows; keep Running rows with a session identity; collect (mode, session_id) */
 }
 
 fn read_foreign_unions(dir: &std::path::Path, exclude_client: &str) -> std::io::Result<Vec<DeviceUnion>> {
@@ -498,10 +680,8 @@ fn read_foreign_unions(dir: &std::path::Path, exclude_client: &str) -> std::io::
     if !dir.is_dir() { return Ok(out); }
     for device in list_snapshot_devices(dir)? {
         let Some((_, generations)) = read_device_overview(dir, &device)? else { continue };
-        let foreign: Vec<String> = generations.iter()
-            .filter(|g| g["clientInstanceId"].as_str() != Some(exclude_client))
-            .filter_map(|g| g["generationId"].as_str().map(String::from))
-            .collect();
+        // Task 1 helper: drops the requester's own generations AND stale clients (A15)
+        let foreign: Vec<String> = select_foreign_recent_generation_ids(&generations, exclude_client);
         if foreign.is_empty() { continue; }
         match read_generations_union_by_ids(dir, &device, &foreign) {
             Ok(union) => out.push(DeviceUnion { device_id: device, union_doc: union_value(union) }),
@@ -521,6 +701,7 @@ Wire in `main.rs` next to the existing `tabs_snapshots` merge (~`:783-795`):
     auth_token: auth_token.clone(),
     snapshots_dir: tabs_snapshots_dir.clone(),          // same value the tabs_snapshots state receives
     ledger: std::sync::Arc::clone(&pane_ledger),        // created at main.rs:426
+    registry: /* clone of the shared terminal-registry handle the WS state receives */,
 }))
 ```
 
@@ -539,13 +720,61 @@ git commit -m "feat(server): GET /api/recovery/inventory - device-scoped recover
 
 ---
 
+### Task 2b: Server — liveness guard on the direct wire-sessionRef rung (defense-in-depth for D7)
+
+> Inserted after Task 2 during load-bearing-assumption validation (A2). Later tasks keep
+> their original numbers — all existing cross-references remain valid.
+
+**Files:**
+- Modify: `crates/freshell-ws/src/terminal.rs` (`handle_create` — the direct wire-`sessionRef` rung at `:1047`, `:1074-1078`; NOT the fenced reconcile modules)
+- Create: `crates/freshell-ws/tests/live_session_ref_guard.rs`
+
+**Interfaces:**
+- Consumes: the ladder's A13 guard semantics as the model (`terminal.rs:1690-1745`: rung-1 Running-row check, identity-registry owner check `:1717-1727`, REST-shaped registry-row check `:1728-1745`); the `RestoreUnavailable` error-frame shape (`terminal.rs:1104-1117`); the integration-test harness patterns of `crates/freshell-ws/tests/claude_restore_unavailable.rs` and `tests/pane_ledger_restore.rs`.
+- Produces: `terminal.create` with `restore: true` + a wire `sessionRef` whose `(provider, sessionId)` is already owned by a currently-Running terminal is REFUSED with a loud `RestoreUnavailable`-style error frame — never a second spawn.
+
+Why this task exists: every existing live-guard lives inside the `createRequestId`-keyed ladder, and the direct rung (`:1074-1078`) bypasses the ladder entirely (`:1099-1101` runs only when `resume_session_id` is still `None`). The D5 recreation path always sends a wire `sessionRef` with a re-minted `createRequestId`, so without this guard a session that goes live between the inventory fetch and the user's accept would silently spawn a duplicate `claude --resume S` while the original live PTY owns S — the repo's own corruption doctrine (`terminal.rs:1671-1674` "silently wrong"; `:933` one-JSONL-writer). Client-side live handling (Tasks 4/5) prevents the common case; this guard closes the fetch→accept race (D7).
+
+- [ ] **Step 1: Write the failing integration test**
+
+Create `crates/freshell-ws/tests/live_session_ref_guard.rs`, mirroring the harness of `claude_restore_unavailable.rs` / `pane_ledger_restore.rs` (same server bootstrap, same WS client helpers, same fake-CLI arrangement those tests use). Body:
+1. Create a claude terminal the way those tests do and let it reach Running, owning session `S` (read `S` back the way `pane_ledger_restore.rs` does).
+2. Send `terminal.create { restore: true, sessionRef: { provider: "claude", sessionId: S }, requestId: <fresh nanoid-style id> }` — the exact wire shape the D5 recovery path produces.
+3. Assert: an error frame comes back (`RestoreUnavailable`-style code, message naming the live session), NO `terminal.created` for the request, and the registry still holds exactly ONE terminal owning `S` (no duplicate spawn).
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `cargo test -p freshell-ws --test live_session_ref_guard`
+Expected: FAIL — today the create succeeds and spawns a duplicate (the falsified A2 behavior).
+
+- [ ] **Step 3: Implement the guard**
+
+In `handle_create`, after `resume_session_id` derivation (`:1074-1096`) and before any spawn work: when `resume_session_id` was derived from the wire `sessionRef`, check whether a currently-Running terminal already owns `(provider = mode, resume_session_id)` — mirror the exact row-matching the ladder's A13 guard performs (`:1728-1745`, plus the claude identity-registry check `:1717-1727`). If live, send the `RestoreUnavailable`-style error frame (same shape as `:1104-1117`, message e.g. "Session is still running on the server.") and abort the create. Mode-generic (claude/codex/opencode/amplifier), matching the direct rung's scope — codex/opencode have no live-guard on ANY path today, so this closes their gap too.
+
+- [ ] **Step 4: Run the full guard + restore test set**
+
+Run: `cargo test -p freshell-ws --test live_session_ref_guard --test claude_restore_unavailable --test pane_ledger_restore --test codex_session_ref_resume`
+Expected: PASS — the new refusal plus all 9 existing tests stay green (after a server restart the old terminal is not Running, so post-restart recovery resumes are unaffected).
+
+- [ ] **Step 5: Format, lint, commit**
+
+```bash
+cargo fmt --all && cargo clippy -p freshell-ws --all-targets -- -D warnings
+git add crates/freshell-ws/src/terminal.rs crates/freshell-ws/tests/live_session_ref_guard.rs
+git commit -m "feat(ws): refuse sessionRef restore while a Running terminal owns the session (B3/P1.9, D7 guard)"
+```
+
+---
+
 ### Task 3: Client — boot eligibility + dismissal persistence
 
 **Files:**
 - Create: `src/lib/recovery/boot-state.ts`
 - Create: `src/lib/recovery/dismissal.ts`
+- Modify: `src/main.tsx` (comment only — pin the import-order invariant on the existing first import; no code change)
 - Create: `test/unit/client/lib/recovery/boot-state.test.ts`
 - Create: `test/unit/client/lib/recovery/dismissal.test.ts`
+- Create: `test/unit/client/lib/recovery/main-import-order.test.ts`
 
 **Interfaces:**
 - Consumes: `window.localStorage` (jsdom provides it in tests; clear it yourself — `console.error` throws in `afterEach`).
@@ -597,6 +826,30 @@ describe('hadPersistedLayoutAtBoot capture', () => {
 })
 ```
 
+`test/unit/client/lib/recovery/main-import-order.test.ts` — pins the two D1/A8 ordering invariants (cheap source-text assertions; synchronous module-load migration writers exist, so ordering is load-bearing):
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+
+describe('boot-state capture ordering invariants (D1/A8)', () => {
+  const src = readFileSync('src/main.tsx', 'utf8')
+
+  it('storage-migration is the FIRST import in main.tsx', () => {
+    // It re-materializes freshell.layout.v3 from the
+    // `.backup-before-fresh-agent-centralization` key BEFORE any capture can run —
+    // which is why boot-state checks only v3 + .bak.
+    const firstImport = src.match(/^import .*$/m)?.[0] ?? ''
+    expect(firstImport).toContain('@/store/storage-migration')
+  })
+
+  it('boot-state is never imported from main.tsx', () => {
+    // boot-state must load AFTER migrations (it reaches the DOM via App → RecoveryOfferPanel)
+    expect(src).not.toMatch(/lib\/recovery\/boot-state/)
+  })
+})
+```
+
 `test/unit/client/lib/recovery/dismissal.test.ts`:
 
 ```ts
@@ -654,12 +907,28 @@ export function computeHadPersistedLayout(storage: Pick<Storage, 'getItem'>): bo
   return storage.getItem(LAYOUT_KEY) !== null || storage.getItem(LAYOUT_BAK_KEY) !== null
 }
 
-// Captured at module import — before the auto-created shell tab and the 500ms
-// persist debounce can write a layout key (see docs/plans/2026-07-26-recover-my-panes.md D1).
+// Captured at module import. Synchronous module-load writers of freshell.layout.v3 DO
+// exist (storage-migration.ts:332/431 — self-executing via main.tsx's FIRST import — and
+// migrateV2ToV3, persistedState.ts:594, during tabsSlice module eval), but each fires only
+// when durable layout data ALREADY existed, so key-presence here remains the correct
+// "had layout" signal. storage-migration also re-materializes freshell.layout.v3 from the
+// `.backup-before-fresh-agent-centralization` key BEFORE this module can load — which is
+// why we check only v3 + .bak. Invariants (pinned by main-import-order.test.ts): the
+// storage-migration import stays FIRST in main.tsx; main.tsx never imports this module.
+// The asynchronous writers (auto shell tab App.tsx:1423-1427, 500ms persist debounce)
+// land long after module eval (see docs/plans/2026-07-26-recover-my-panes.md D1).
 export const hadPersistedLayoutAtBoot: boolean =
   typeof window !== 'undefined' && computeHadPersistedLayout(window.localStorage)
 ```
 
+In `src/main.tsx`, add a comment on the existing `import '@/store/storage-migration'` line (no code change):
+
+```ts
+// MUST stay the FIRST import: recover-my-panes boot-state (D1) depends on migrations
+// having re-materialized freshell.layout.v3 BEFORE any capture runs — see
+// docs/plans/2026-07-26-recover-my-panes.md and main-import-order.test.ts.
+```
+
 `src/lib/recovery/dismissal.ts` (same pattern as `src/lib/setup-wizard-dismissal.ts`):
 
 ```ts
@@ -707,7 +976,7 @@ Expected: PASS.
 - [ ] **Step 5: Commit**
 
 ```bash
-git add src/lib/recovery/boot-state.ts src/lib/recovery/dismissal.ts test/unit/client/lib/recovery/
+git add src/lib/recovery/boot-state.ts src/lib/recovery/dismissal.ts src/main.tsx test/unit/client/lib/recovery/
 git commit -m "feat(client): recovery trigger eligibility (boot-captured) and dismissal persistence (B3/P1.9)"
 ```
 
@@ -724,7 +993,7 @@ git commit -m "feat(client): recovery trigger eligibility (boot-captured) and di
 **Interfaces:**
 - Consumes: `PaneNode` / `TerminalPaneContent` from `@/store/paneTypes` (`PaneNode = leaf{id, content} | split{id, direction, children:[PaneNode,PaneNode], sizes:[number,number]}`, `paneTypes.ts:274-276`; terminal content fields incl. `initialCwd`, `sessionRef: {provider, sessionId}`, non-optional `createRequestId`/`status`); `nanoid`; `api.get` + `buildQueryString` (`api.ts:276-285`).
 - Produces:
-  - `types.ts`: `RecoveryInventory`, `RecoveryPane` (`{paneId, kind, mode: string|null, shell: string|null, cwd: string|null, payload: Record<string, unknown>, sessionRef: {provider, sessionId}|null, ledgerState: 'bound'|'closed'|'gc_expired'|'unknown'}`), `RecoveryTab`, `LedgerOnlyEntry` — mirroring Task 1's response shape.
+  - `types.ts`: `RecoveryInventory`, `RecoveryPane` (`{paneId, kind, mode: string|null, shell: string|null, cwd: string|null, payload: Record<string, unknown>, sessionRef: {provider, sessionId}|null, ledgerState: 'bound'|'closed'|'gc_expired'|'unknown', live: boolean}`), `RecoveryTab`, `LedgerOnlyEntry` — mirroring Task 1's response shape.
   - `api.ts`: `export async function getRecoveryInventory(clientInstanceId: string): Promise<RecoveryInventory>` → `api.get<RecoveryInventory>('/api/recovery/inventory' + buildQueryString({ clientInstanceId }))`.
   - `build-recovery-plan.ts`:
 
@@ -734,7 +1003,7 @@ export function countRecoverablePanes(inv: RecoveryInventory): number
 export function buildRecoveryPlan(inv: RecoveryInventory): RecoveryTabPlan[]
 ```
 
-Rules: one `RecoveryTabPlan` per inventory tab (tabId = `nanoid()`); pane list → right-leaning binary split chain (`direction: 'horizontal'`, `sizes: [50, 50]`); terminal leaf content `{kind:'terminal', createRequestId: nanoid(), status: 'creating', mode, shell, initialCwd: cwd, sessionRef: sessionRef ?? undefined}` (fields with `null` inventory values omitted; `restoreLayout` re-mints ids/status — that's expected); non-terminal leaf content = `{...payload, kind}` passthrough (the `reopenClosedTab` restore path normalizes it); `ledgerOnly` entries, if any, become one extra final tab titled `Recovered sessions` whose panes are terminal content with `mode: entry.mode`, `initialCwd: entry.cwd ?? undefined`, `sessionRef: {provider, sessionId}`. `countRecoverablePanes` = device panes + ledgerOnly length.
+Rules: one `RecoveryTabPlan` per inventory tab (tabId = `nanoid()`); pane list → right-leaning binary split chain (`direction: 'horizontal'`, `sizes: [50, 50]`); terminal leaf content `{kind:'terminal', createRequestId: nanoid(), status: 'creating', mode, shell, initialCwd: cwd, sessionRef: sessionRef ?? undefined}` (fields with `null` inventory values omitted; `restoreLayout` re-mints ids/status — that's expected), and panes with `live: true` get their `sessionRef` STRIPPED (recreated without resume, D7 — layout/cwd/mode still carried, and with no `sessionRef` they are never armed for terminal restore); non-terminal kinds go through a small per-kind adapter (A10): `editor` panes supply the required `content: ''` default (`EditorPaneContent.content` is required by `paneTypes.ts:116-130` but absent from snapshot payloads — buffer text is never captured, D6); `fresh-agent` panes strip `restoreError` before passthrough (normalize's `existingRestoreError` branch would drop `sessionRef`; normalize re-validates canonical claude refs itself); all other kinds (`browser`, `extension`, `picker`) = `{...payload, kind}` passthrough (the `reopenClosedTab` restore path normalizes it); `ledgerOnly` entries, if any, become one extra final tab titled `Recovered sessions` whose panes are terminal content with `mode: entry.mode`, `initialCwd: entry.cwd ?? undefined`, `sessionRef: {provider, sessionId}` (live rows never reach the client — the server excludes them). `countRecoverablePanes` = device panes + ledgerOnly length.
 
 - [ ] **Step 1: Write the failing tests**
 
@@ -749,7 +1018,7 @@ vi.mock('nanoid', () => { let n = 0; return { nanoid: () => `nid-${++n}` } })
 
 const pane = (over: Partial<RecoveryInventory['device']['tabs'][0]['panes'][0]> = {}) => ({
   paneId: 'p1', kind: 'terminal', mode: 'shell', shell: null, cwd: '/w',
-  payload: {}, sessionRef: null, ledgerState: 'unknown' as const, ...over,
+  payload: {}, sessionRef: null, ledgerState: 'unknown' as const, live: false, ...over,
 })
 const inv = (panes: unknown[], ledgerOnly: unknown[] = []): RecoveryInventory => ({
   recoverable: true, contentId: 'cid',
@@ -788,12 +1057,43 @@ describe('buildRecoveryPlan', () => {
     expect(root.children[1].type).toBe('split')
   })
 
+  it('live panes are recreated WITHOUT resume: sessionRef stripped, cwd/mode kept (D7)', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ sessionRef: { provider: 'claude', sessionId: 'S2' }, ledgerState: 'bound', mode: 'claude', live: true })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content.sessionRef).toBeUndefined()
+    expect(content).toMatchObject({ kind: 'terminal', mode: 'claude', initialCwd: '/w' })
+  })
+
   it('non-terminal kinds pass payload through', () => {
     const [tab] = buildRecoveryPlan(inv([pane({ kind: 'browser', payload: { url: 'https://x.test' }, mode: null, cwd: null })]))
     const content = (tab.layout as { content: Record<string, unknown> }).content
     expect(content).toMatchObject({ kind: 'browser', url: 'https://x.test' })
   })
 
+  it('editor panes get the required content default (buffer text is never captured)', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ kind: 'editor', payload: { filePath: '/f.txt' }, mode: null, cwd: null })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content).toMatchObject({ kind: 'editor', filePath: '/f.txt', content: '' })
+  })
+
+  it('fresh-agent restoreError is stripped so normalize keeps the sessionRef', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ kind: 'fresh-agent',
+      payload: { sessionRef: { provider: 'freshclaude', sessionId: 'F1' }, restoreError: 'stale' }, mode: null, cwd: null })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content.restoreError).toBeUndefined()
+    expect(content).toMatchObject({ kind: 'fresh-agent', sessionRef: { provider: 'freshclaude', sessionId: 'F1' } })
+  })
+
+  it('extension and picker payloads pass through', () => {
+    const [tab] = buildRecoveryPlan(inv([
+      pane({ paneId: 'x1', kind: 'extension', payload: { extensionId: 'ext.foo' }, mode: null, cwd: null }),
+      pane({ paneId: 'x2', kind: 'picker', payload: {}, mode: null, cwd: null }),
+    ]))
+    const root = tab.layout as { children: [{ content: Record<string, unknown> }, { content: Record<string, unknown> }] }
+    expect(root.children[0].content).toMatchObject({ kind: 'extension', extensionId: 'ext.foo' })
+    expect(root.children[1].content).toMatchObject({ kind: 'picker' })
+  })
+
   it('ledgerOnly entries get a trailing Recovered sessions tab', () => {
     const plans = buildRecoveryPlan(inv([pane()], [{ provider: 'codex', sessionId: 'C9', mode: 'codex', cwd: '/x' }]))
     expect(plans).toHaveLength(2)
@@ -822,7 +1122,7 @@ import { nanoid } from 'nanoid'
 import type { PaneNode, PaneContent } from '@/store/paneTypes'
 import type { RecoveryInventory, RecoveryPane, LedgerOnlyEntry } from './types'
 
-function terminalContent(p: { mode: string | null; shell: string | null; cwd: string | null; sessionRef: { provider: string; sessionId: string } | null }): PaneContent {
+function terminalContent(p: { mode: string | null; shell: string | null; cwd: string | null; sessionRef: { provider: string; sessionId: string } | null; live: boolean }): PaneContent {
   return {
     kind: 'terminal',
     createRequestId: nanoid(), // re-minted by restoreLayout normalization; required by the type
@@ -830,12 +1130,24 @@ function terminalContent(p: { mode: string | null; shell: string | null; cwd: st
     ...(p.mode ? { mode: p.mode } : {}),
     ...(p.shell ? { shell: p.shell } : {}),
     ...(p.cwd ? { initialCwd: p.cwd } : {}),
-    ...(p.sessionRef ? { sessionRef: p.sessionRef } : {}),
+    // D7: live sessions are left untouched - recreate the pane WITHOUT resume
+    ...(p.sessionRef && !p.live ? { sessionRef: p.sessionRef } : {}),
   } as PaneContent
 }
 
 function paneContent(p: RecoveryPane): PaneContent {
   if (p.kind === 'terminal') return terminalContent(p)
+  if (p.kind === 'editor') {
+    // EditorPaneContent.content is required (paneTypes.ts:116-130) but snapshots never
+    // capture buffer text - recreate with an empty buffer (data fact, D6)
+    return { content: '', ...p.payload, kind: 'editor' } as PaneContent
+  }
+  if (p.kind === 'fresh-agent') {
+    // normalize's existingRestoreError branch would drop sessionRef; strip restoreError
+    // and let normalize re-validate the ref itself (A10)
+    const { restoreError: _restoreError, ...payload } = p.payload
+    return { ...payload, kind: 'fresh-agent' } as PaneContent
+  }
   return { ...p.payload, kind: p.kind } as PaneContent
 }
 
@@ -865,7 +1177,7 @@ export function buildRecoveryPlan(inv: RecoveryInventory): RecoveryTabPlan[] {
       tabId: nanoid(),
       title: 'Recovered sessions',
       layout: chain(inv.ledgerOnly.map((e: LedgerOnlyEntry) =>
-        leaf(terminalContent({ mode: e.mode, shell: null, cwd: e.cwd, sessionRef: { provider: e.provider, sessionId: e.sessionId } })))),
+        leaf(terminalContent({ mode: e.mode, shell: null, cwd: e.cwd, sessionRef: { provider: e.provider, sessionId: e.sessionId }, live: false })))),
       paneTitles: {},
     })
   }
@@ -910,8 +1222,8 @@ git commit -m "feat(client): recovery inventory types, API helper, and recovery-
 
 Behavior:
 1. On mount: if `(hadPersistedLayoutAtBoot && !getPendingOffer())` → render null forever. Otherwise fetch `getRecoveryInventory(getClientInstanceId())` once; on error or `recoverable: false` or `isDismissed(contentId)` → render null; else `setPendingOffer(contentId)` and show the panel.
-2. Panel (modal-style, reuse the portal/overlay/focus pattern of `src/components/ui/confirm-modal.tsx`): heading `Restore N panes from server memory?` (N = `countRecoverablePanes`), a list of recoverable items — for device panes: `{tabName}: {mode ?? kind}` plus cwd when present; for ledgerOnly: `{mode} session — {cwd ?? 'unknown directory'}`; buttons `Restore` and `Not now`.
-3. Accept: `clearPendingOffer()`; for each `RecoveryTabPlan`: `dispatch(addTab({ id: plan.tabId, title: plan.title }))`, `dispatch(restoreLayout({ tabId: plan.tabId, layout: plan.layout, paneTitles: plan.paneTitles }))`; then `armRecoveredTerminalRestores(store.getState(), planTabIds)`; hide panel.
+2. Panel (modal-style, reuse the portal/overlay/focus pattern of `src/components/ui/confirm-modal.tsx`): heading `Restore N panes from server memory?` (N = `countRecoverablePanes`), the device label (`inventory.device.deviceLabel`, when a device is present), a list of recoverable items — for device panes: `{tabName}: {mode ?? kind}` plus cwd when present; for ledgerOnly: `{mode} session — {cwd ?? 'unknown directory'}`; buttons `Restore` and `Not now`. When any device pane has `live: true`, also render a note with `data-testid="recovery-live-note"` (copy flexible, e.g. `Some sessions are still running on the server — they were left untouched; their panes reopen without resuming.`) per D7.
+3. Accept: `clearPendingOffer()`; for each `RecoveryTabPlan`: `dispatch(addTab({ id: plan.tabId, title: plan.title }))`, `dispatch(restoreLayout({ tabId: plan.tabId, layout: plan.layout, paneTitles: plan.paneTitles }))`; then `armRecoveredTerminalRestores(store.getState(), planTabIds)`; hide panel. (Live panes carry no `sessionRef` after Task 4's strip, so the walk never arms them — no component-level special-casing needed.)
 4. Decline: `recordDismissal(contentId)`; `clearPendingOffer()`; hide panel. No further renders this or future visits for this contentId.
 5. A11y: dialog has `role="dialog"`, `aria-modal="true"`, `aria-labelledby` pointing at the heading id; list is a `<ul>`; both buttons are real `<button>` elements with visible text. `data-testid="recovery-offer-panel"`, `data-testid="recovery-accept"`, `data-testid="recovery-decline"` for e2e.
 
@@ -953,7 +1265,7 @@ const INVENTORY = {
   recoverable: true, contentId: 'cid-1',
   device: { deviceId: 'd', deviceLabel: 'l', capturedAt: 1, tabs: [{ tabKey: 'k', tabName: 'work', panes: [
     { paneId: 'p1', kind: 'terminal', mode: 'claude', shell: null, cwd: '/w', payload: {},
-      sessionRef: { provider: 'claude', sessionId: 'S2' }, ledgerState: 'bound' },
+      sessionRef: { provider: 'claude', sessionId: 'S2' }, ledgerState: 'bound', live: false },
   ] }] },
   otherDevices: [], ledgerOnly: [],
 }
@@ -1001,7 +1313,7 @@ describe('RecoveryOfferPanel', () => {
 })
 ```
 
-Adjust the state-shape assertions in the accept test to the real `tabs`/`panes` slice shapes (assert: at least one new tab exists whose title is `work`, and the panes layout for it contains a terminal leaf with `sessionRef.sessionId === 'S2'`). Also add a test that `hadPersistedLayoutAtBoot: true` + no pending flag renders nothing and never fetches (use a second mock variant via `vi.doMock` + dynamic import, or split into a separate test file with a different boot-state mock — whichever matches house style).
+Adjust the state-shape assertions in the accept test to the real `tabs`/`panes` slice shapes (assert: at least one new tab exists whose title is `work`, and the panes layout for it contains a terminal leaf with `sessionRef.sessionId === 'S2'`). Also add: (a) a test that `hadPersistedLayoutAtBoot: true` + no pending flag renders nothing and never fetches (use a second mock variant via `vi.doMock` + dynamic import, or split into a separate test file with a different boot-state mock — whichever matches house style); (b) a live-note test — render with an inventory whose pane has `live: true` and assert `recovery-live-note` is visible, and that after accept the recreated pane's content has NO `sessionRef` (D7).
 
 - [ ] **Step 2: Run tests to verify they fail**
 
@@ -1143,20 +1455,23 @@ git add -A && git commit -m "test: stabilize recover-my-panes unit/integration c
 - Modify: the two registration lists that `pane-ledger-restart-rust.spec.ts` appears in — `RUST_ONLY_SPECS` and the `rust-chromium` project `testMatch` (grep for `pane-ledger-restart-rust` to find both; add this spec the same way)
 
 **Interfaces:**
-- Consumes: `RustServer` (`test/e2e-browser/helpers/rust-server.ts` — `homeDir` defaults to a fresh mkdtemp; `findFreePort()`; `restart()`), the fake-CLI installation + claude-pane creation pattern from `test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts:1-80` (`installFakeCli()` + fixtures `fake-claude-cli.mjs`), fresh-context storage-wipe pattern from `tabs-client-retire.spec.ts:6-38` (`browser.newContext()` = empty localStorage), `?token=<t>&e2e=1` URL scheme, `data-testid="recovery-offer-panel"` / `recovery-accept` / `recovery-decline` from Task 5.
+- Consumes: `RustServer` (`test/e2e-browser/helpers/rust-server.ts` — `homeDir` defaults to a fresh mkdtemp; `findFreePort()`; `restart()`), the fake-CLI installation + claude-pane creation pattern from `test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts:1-80` (`installFakeCli()` + fixtures `fake-claude-cli.mjs`), the `FAKE_CLAUDE_ARGV_LOG` JSONL and the `--session-id` extraction pattern (`pane-ledger-restart-rust.spec.ts:162-168`), the adjacent-pair `hasResumePair(argv, sessionId)` helper pattern from `snapshot-restore-rust.spec.ts:66-70` (COPY it into this spec now — Task 9 deletes that file), the fake CLI's resume marker `claude: resumed session <id>` (`fake-claude-cli.mjs:26-30`), fresh-context storage-wipe pattern from `tabs-client-retire.spec.ts:6-38` (`browser.newContext()` = empty localStorage), `?token=<t>&e2e=1` URL scheme, `data-testid="recovery-offer-panel"` / `recovery-accept` / `recovery-decline` / `recovery-live-note` from Task 5.
 - Produces: the campaign's first browser-loss recovery e2e.
 
 Scenarios (all inside one spec file sharing one owned `RustServer` on an ephemeral port — NEVER 3001/3002; ESM imports use `.js` extensions):
 
 **Scenario 1 — lose the browser, recover the panes (accept path):**
 1. Start `RustServer` with its own `homeDir` and `installFakeCli()` (mirror `pane-ledger-restart-rust.spec.ts` setup).
-2. Context A: `browser.newContext()` → `page.goto(baseUrl + '/?token=' + token + '&e2e=1')` → create a claude CLI pane exactly the way `pane-ledger-restart-rust.spec.ts` does (fake CLI) and let it bind (that spec's readiness waits) — this produces a ledger binding AND layout state.
+2. Context A: `browser.newContext()` → `page.goto(baseUrl + '/?token=' + token + '&e2e=1')` → create a claude CLI pane exactly the way `pane-ledger-restart-rust.spec.ts` does (fake CLI) and let it bind (that spec's readiness waits) — this produces a ledger binding AND layout state. Record the pane's `sessionId` from the argv log's `--session-id` pair (the `pane-ledger-restart-rust.spec.ts:162-168` extraction). ALSO create a browser pane pointed at `https://example.com` in the same tab (reuse whatever existing e2e helper/spec creates a browser pane; if none does it via UI, split the pane and pick the browser kind the way a user would) — this replaces the mixed-kind restore coverage that dies with `snapshot-restore-rust.spec.ts` (A12).
 3. Wait for a snapshot to exist on disk: poll `fs.readdir(path.join(homeDir, '.freshell', 'tabs-snapshots'))` until a device dir with ≥1 `.json` generation appears (timeout 30s — pushes fire on ready + every 5s).
 4. `await contextA.close()` — the "lost browser".
 5. `await server.restart()` — the campaign scenario restarts the server too.
 6. Context B: fresh `browser.newContext()` (empty storage = new machine) → `goto` the same URL.
 7. `await expect(pageB.getByTestId('recovery-offer-panel')).toBeVisible({ timeout: 15000 })` and assert the heading matches `/restore \d+ pane/i`.
-8. `await pageB.getByTestId('recovery-accept').click()` → panel disappears → assert a recreated terminal pane renders and the fake claude session RESUMES (reuse the exact resumed-session assertion from `pane-ledger-restart-rust.spec.ts` — e.g. the fake CLI's resume marker text appearing in the recreated pane's terminal).
+8. `await pageB.getByTestId('recovery-accept').click()` → panel disappears → assert a recreated terminal pane renders, then build the resume proof directly (`pane-ledger-restart-rust.spec.ts` has NO resume assertion to reuse — it only polls ledger files and checks `--session-id` preallocation):
+   - PRIMARY: poll the `FAKE_CLAUDE_ARGV_LOG` JSONL until an entry's argv contains the adjacent pair `--resume <sessionId>` for the sessionId recorded in step 2 (the `hasResumePair` pattern copied from `snapshot-restore-rust.spec.ts:66-70`).
+   - SECONDARY: the recreated pane's xterm text shows `claude: resumed session <id>` (`fake-claude-cli.mjs:26-30` emits it at CLI startup; scrollback replay delivers it to the late-attaching context).
+   Also assert the browser pane from step 2 was recreated in context B (a browser-kind pane rendering `example.com` — assert via its testid/iframe src the way existing browser-pane specs do).
 9. Same-browser reload guard: `await pageB.reload()` → wait for app ready → `await expect(pageB.getByTestId('recovery-offer-panel')).toHaveCount(0)` (localStorage now has a layout — no offer).
 
 **Scenario 2 — decline path:**
@@ -1165,6 +1480,12 @@ Scenarios (all inside one spec file sharing one owned `RustServer` on an ephemer
 
 Dismissal-across-reload persistence is proven at unit level (Task 3/5); e2e scenario 2 proves the user-visible decline behavior.
 
+**Scenario 3 — no-restart browser loss (live session ⇒ recreate WITHOUT resume, D7):**
+1. Fresh context D against the SAME still-running server (do NOT restart): create a new fake-claude pane (scenario 1's pattern), record its `sessionId` from the argv log (`--session-id` extraction) and the argv log's current entry count, and wait for a snapshot generation that includes it.
+2. `await contextD.close()` WITHOUT restarting the server — the claude PTY stays Running (registry-owned, not connection-owned).
+3. Fresh context E → the offer appears (the new session changed the recoverable substance, so scenario 2's dismissal does not suppress it) → assert the live-session note `recovery-live-note` is visible.
+4. `recovery-accept` click → panel disappears → a terminal pane is recreated → assert NO new `--resume <thatSessionId>` adjacent pair was appended to `FAKE_CLAUDE_ARGV_LOG` beyond the entry count recorded in step 1 (the live pane was recreated WITHOUT resume; the running session was left untouched — D7).
+
 - [ ] **Step 1: Write the failing spec**
 
 Write the spec per the scenarios above, copying the harness scaffolding verbatim from `pane-ledger-restart-rust.spec.ts` (imports with `.js` extensions, `ensureRustServerBuilt`, server lifecycle in `test.beforeAll`/`afterAll`, fake CLI install). Register it in both lists.
@@ -1182,7 +1503,7 @@ Fix selector/timing issues until the spec passes 2 consecutive runs. Common trap
 
 ```bash
 git add test/e2e-browser/
-git commit -m "test(e2e): browser-loss recover-my-panes proof - offer, accept-resume, reload guard, decline (B3/P1.9)"
+git commit -m "test(e2e): browser-loss recover-my-panes proof - offer, accept-resume, mixed-kind, reload guard, decline, live no-restart (B3/P1.9)"
 ```
 
 ---
@@ -1190,10 +1511,14 @@ git commit -m "test(e2e): browser-loss recover-my-panes proof - offer, accept-re
 ### Task 9: Delete the operator restore endpoint + marker/fence machinery (kata h9vt cleanup)
 
 **Files:**
-- Modify: `crates/freshell-server/src/tabs_snapshots.rs` (remove the `POST /api/tabs-sync/restore` route + handler, `restore_lock`, the exactly-one-browser gate, marker usage, the delivery fence including the `send_capture_to` call at `tabs_snapshots.rs:241`, and `pane_to_create_body` usage; KEEP anything the crate still needs — if nothing remains, delete the file and its `mod` decl)
-- Delete: `crates/freshell-server/src/tabs_snapshots_marker.rs`, `crates/freshell-server/src/tabs_snapshots_create_body.rs`, `crates/freshell-server/src/tabs_snapshots_selectors.rs` (the restore-body selector parser — delete only after confirming the inventory endpoint doesn't import it), their test siblings, `scripts/restore-tabs.sh`
+- Modify: `crates/freshell-server/src/tabs_snapshots.rs` (remove the `POST /api/tabs-sync/restore` route + handler, `restore_lock`, the exactly-one-browser gate, marker usage, the delivery fence including the `send_capture_to` call at `tabs_snapshots.rs:241`, and `pane_to_create_body` usage; KEEP the read side — the `GET /api/tabs-sync/snapshots[/{device_id}]` routes and `get_snapshot` SURVIVE)
+- Modify: `crates/freshell-server/src/tabs_snapshots_selectors.rs` — NOT deleted wholesale: KEEP `parse_selector` + `Selector` (consumed by the surviving `get_snapshot` handler at `tabs_snapshots.rs:129`; the GET endpoints have live external consumers — `scripts/deploy-tab-diff.sh:53,66,88` curls them, and the read tests `tabs_snapshots_tests.rs:105-195` cover the selector cases); DELETE only `parse_restore_selection` (`tabs_snapshots_selectors.rs:66-118`) and its tests
+- Delete: `crates/freshell-server/src/tabs_snapshots_marker.rs`, `crates/freshell-server/src/tabs_snapshots_create_body.rs`, their test siblings, `scripts/restore-tabs.sh`
+- Delete: `test/e2e-browser/specs/snapshot-restore-rust.spec.ts` (drives the deleted endpoint end-to-end) and remove it from both registration lists — its unique coverage already moved in Task 8 (browser-pane mixed-kind recreation; the `hasResumePair` argv pattern)
+- Modify: `scripts/deploy-tab-diff.sh` (`:279-303` — the remediation text tells the operator to run `scripts/restore-tabs.sh`; rewrite it to point at the UI recovery flow)
+- Modify: `test/e2e-browser/specs/deploy-tab-diff-rust.spec.ts` (`:216` asserts the old remediation message — update to the new text; `:238,267,413` actually EXECUTE `restore-tabs.sh` — those sections belong to the deleted machinery: rework or delete them while PRESERVING the spec's diff-detection coverage)
 - Modify: `crates/freshell-server/src/main.rs` (remove the restore route merge + dead `mod` decls)
-- Modify: `crates/freshell-server/src/screenshot.rs` — ONLY if removing the fence caller makes `send_capture_to` dead (compiler/clippy will say): delete it and its now-dead helpers in the same commit (P2.17 sanctions exactly this deletion)
+- Modify: `crates/freshell-ws/src/screenshot.rs` per the Step 2 audit table (the broker lives in the freshell-ws LIBRARY crate — `crates/freshell-server/src/screenshot.rs` does NOT exist, and `crates/freshell-server/src/screenshots.rs`, the `POST /api/screenshots` REST handler, SURVIVES; P2.17 sanctions the fence-machinery deletion)
 
 **Interfaces:**
 - Consumes: nothing new. Preserves: `freshell_ws::tabs_persist` read selectors (used by Task 2) and the entire write path (untouched).
@@ -1202,20 +1527,44 @@ git commit -m "test(e2e): browser-loss recover-my-panes proof - offer, accept-re
 - [ ] **Step 1: Confirm the blast radius**
 
 ```bash
-grep -rn "tabs-sync/restore\|tabs_snapshots_marker\|restore-tabs.sh\|pane_to_create_body\|send_capture_to" --include='*.rs' --include='*.sh' --include='*.ts' --include='*.md' crates/ scripts/ src/ test/ docs/development/ | grep -v docs/plans/
+grep -rn "tabs-sync/restore\|tabs_snapshots_marker\|restore-tabs.sh\|pane_to_create_body\|send_capture_to\|parse_selector\|parse_restore_selection\|tabs_snapshots_selectors\|deploy-tab-diff\|snapshot-restore-rust" --include='*.rs' --include='*.sh' --include='*.ts' --include='*.md' crates/ scripts/ src/ test/ docs/development/ | grep -v docs/plans/
 ```
-Expected consumers: the endpoint's own module/tests, `main.rs` wiring, the script, `screenshot.rs:244`. If ANYTHING else consumes these (another route, a doc under `docs/development/` describing operator procedure), list it in the commit message and update/delete it too. If a consumer exists that the UI flow does not replace — STOP and report (that would reopen the h9vt disposition).
+Expected consumers (all accounted for by this task — the STOP branch must not fire on these):
+- the endpoint's own module/tests, `main.rs` wiring (`:785-794`), `scripts/restore-tabs.sh`;
+- the fence caller `tabs_snapshots.rs:241` → broker method `crates/freshell-ws/src/screenshot.rs:244` (see the Step 2 audit table);
+- `parse_selector` consumed by the SURVIVING `get_snapshot` (`tabs_snapshots.rs:129`) + the read tests (`tabs_snapshots_tests.rs:105-195`) — KEPT, not deleted;
+- the two deploy-tab-diff consumers: `scripts/deploy-tab-diff.sh:279-303` (remediation text — REWRITTEN to the UI flow) and `test/e2e-browser/specs/deploy-tab-diff-rust.spec.ts:216,238,267,413` (REWORKED, diff-detection coverage preserved);
+- `test/e2e-browser/specs/snapshot-restore-rust.spec.ts` (DELETED — drives the endpoint; coverage moved in Task 8);
+- stale doc comments only: `crates/freshell-freshagent/src/terminal_tabs.rs:191,614` (comments in the FENCED B4 crate — leave them, note in the final report) and `crates/freshell-ws/src/tabs_persist_validation_tests.rs:113` (update the comment).
 
-- [ ] **Step 2: Delete, then let the compiler drive**
+If ANYTHING else consumes these (another route, a doc under `docs/development/` describing operator procedure), list it in the commit message and update/delete it too. If a consumer exists that the UI flow does not replace — STOP and report (that would reopen the h9vt disposition).
 
-Remove the route merge from `main.rs` first, then the handler + machinery, then the files. Iterate `cargo check -p freshell-server` until clean; every `dead_code` warning that appears in touched modules is machinery the fence/marker existed for — delete it (context poison), do not `#[allow]` it.
+- [ ] **Step 2: Delete — audit table for freshell-ws, compiler-driven WITHIN freshell-server**
+
+Remove the route merge from `main.rs` first, then the handler + machinery, then the files. Iterate `cargo check -p freshell-server` until clean; WITHIN `freshell-server` every `dead_code` warning that appears in touched modules is machinery the fence/marker existed for — delete it (context poison), do not `#[allow]` it.
+
+In `tabs_snapshots_selectors.rs`, delete ONLY `parse_restore_selection` (`:66-118`) and its tests; `parse_selector` + `Selector` stay (the surviving `get_snapshot` consumes them at `tabs_snapshots.rs:129` — deleting them is a hard compile error AND breaks the surviving GET API).
+
+For `crates/freshell-ws/src/screenshot.rs` the compiler CANNOT drive: `pub` items in a library crate get no `dead_code` lint when their cross-crate consumer dies — `exclusive_client_id` and `has_client` are already consumer-less today under the required `-D warnings` CI gate, proving the compiler stays silent on exactly this surface. Apply this explicit audit table instead:
+
+| Item in `crates/freshell-ws/src/screenshot.rs` | Fate | Reason |
+|---|---|---|
+| `send_capture_to` (`:244`) | DELETE + its unit tests | only consumer was the fence caller, `tabs_snapshots.rs:241` |
+| `register_for_client` (`:138`) | DELETE + its unit tests | only consumer `tabs_snapshots.rs:238` |
+| `send_to_client` (`:200`) | DELETE + its unit tests | all consumers die with `tabs_snapshots.rs` (`:578,:581,:629,:672,:803`) |
+| `client_snapshot` (`:115`) | DELETE + its unit tests | only consumer `tabs_snapshots.rs:430` |
+| `exclusive_client_id` (`:110`), `has_client` (`:124`) | DELETE + their unit tests | consumer-less already today |
+| `register`, `send_capture`, `cancel`, `resolve_from`, `add_capable_client`, `remove_capable_client`, `has_capable_client`, `ScreenshotBroker::new` | KEEP | live consumers survive: `crates/freshell-server/src/screenshots.rs:104-128` (the surviving `POST /api/screenshots` REST handler) and `crates/freshell-ws/src/terminal.rs:178,436,681` |
+| `register_expected` (`:146`, private) | KEEP | shared helper of the surviving `register` |
+
+Rewrite `scripts/deploy-tab-diff.sh:279-303`: the remediation instructions must stop referencing `scripts/restore-tabs.sh` and instead direct the operator to the UI recovery flow (open a fresh browser context against the server — the recover-my-panes offer surfaces the snapshot; wording flexible). Update `test/e2e-browser/specs/deploy-tab-diff-rust.spec.ts` to match: `:216` asserts the old message — update it to the new text; `:238,267,413` EXECUTE `restore-tabs.sh` — rework or delete those sections while PRESERVING the spec's diff-detection coverage. Delete `test/e2e-browser/specs/snapshot-restore-rust.spec.ts` and its entries in both registration lists (its unique coverage moved in Task 8).
 
 - [ ] **Step 3: Verify the full workspace + client suites stay green**
 
 Run: `cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace`
 Expected: PASS with the restore/marker test files gone; if any REMAINING test fails because it exercised restore machinery, that test belonged to the deleted feature — delete it; if it fails for any other reason, fix the code, not the test.
-Run: `npx playwright test test/e2e-browser/specs/recover-my-panes-rust.spec.ts --project=rust-chromium`
-Expected: PASS (proves the UI flow never depended on the deleted machinery).
+Run: `npx playwright test test/e2e-browser/specs/recover-my-panes-rust.spec.ts test/e2e-browser/specs/deploy-tab-diff-rust.spec.ts --project=rust-chromium`
+Expected: PASS (proves the UI flow never depended on the deleted machinery, and the reworked deploy-tab-diff spec still covers diff detection).
 
 - [ ] **Step 4: Commit**
 
@@ -1226,8 +1575,11 @@ git commit -m "refactor(server): delete operator tabs-sync restore endpoint, wri
 Kata h9vt disposition: Option A. The tabs-snapshots store is now load-bearing
 via GET /api/recovery/inventory + the client recover-my-panes flow. The
 server-push restore machinery (marker, one-browser gate, delivery fence,
-scripts/restore-tabs.sh) served only the blind operator push and has no UI-flow
-consumer; the unreachable fence was flagged for deletion in campaign P2.17."
+scripts/restore-tabs.sh, parse_restore_selection) served only the blind
+operator push and has no UI-flow consumer; the unreachable fence was flagged
+for deletion in campaign P2.17. The GET snapshots read API, parse_selector,
+and the broadcast screenshot broker survive (audit table in the plan);
+deploy-tab-diff remediation now points at the UI recovery flow."
 ```
 
 ---
@@ -1255,16 +1607,20 @@ Do NOT run `gh pr create` — PR creation is not approved for this lane.
 
 - [ ] **Step 3: Report**
 
-The lane's final report must include: branch name, the green-suite evidence (commands + outcomes), the e2e proof summary, and this kata disposition statement: **"Kata h9vt resolved as Option A: tabs-snapshots is now load-bearing (layout half of the recover-my-panes flow via GET /api/recovery/inventory); the operator POST /api/tabs-sync/restore endpoint, write-ahead marker, exactly-one-browser gate, screenshot delivery fence, and scripts/restore-tabs.sh were deleted as UI-flow-irrelevant per the 'reuse what serves the UI flow, delete what doesn't' directive and P2.17."**
+The lane's final report must include: branch name, the green-suite evidence (commands + outcomes), the e2e proof summary, and this kata disposition statement: **"Kata h9vt resolved as Option A: tabs-snapshots is now load-bearing (layout half of the recover-my-panes flow via GET /api/recovery/inventory); the operator POST /api/tabs-sync/restore endpoint, write-ahead marker, exactly-one-browser gate, screenshot delivery fence, and scripts/restore-tabs.sh were deleted as UI-flow-irrelevant per the 'reuse what serves the UI flow, delete what doesn't' directive and P2.17. The GET /api/tabs-sync/snapshots read API and parse_selector survive (deploy-tab-diff consumes them), and deploy-tab-diff's remediation now points at the UI recovery flow."**
+
+The final report must ALSO state:
+1. **The D1 Principle-4 reconciliation, for explicit owner ratification:** the empty-client offer is sanctioned by campaign §4.4, which prescribes exactly "offer 'restore N panes from server memory?'" for this trigger; Decision 6's "recovery is automatic, never offered" scope list omits §4.4, so this plan reads the offer as the sanctioned behavior for the empty-client case. The owner should ratify (or overturn) that reading.
+2. **The freshopencode fresh-start limitation, flagged to Lane B4:** recovered `freshopencode` panes start FRESH because `opencode_ws.rs` `handle_create` never reads `resume_session_id` (pre-existing bug, shared with `reopenClosedTab`; `crates/freshell-freshagent` is B4's fenced crate). The `sessionRef` passthrough is kept, so recovery becomes resume-correct the moment B4 fixes the handler.
 
 ---
 
 ## Self-Review Record
 
-**1. Spec coverage:** (1) recover-my-panes flow — offer/trigger D1-D3 + Tasks 3/5/6; accept recreation honoring §4.2 D4-D5 + Tasks 1/4/5; decline remembered Task 3/5. (2) kata h9vt — disposition section + Task 9 (Option A kept, honest evaluation recorded; Option B rejected with reason: ledger has no layout). (3) read API — Tasks 1/2, device-scoped via snapshot device dirs + self-pollution filter, auth'd, fed by ledger + newest-generation union selectors. TDD red-first for trigger conditions, inventory API, authority chain, dismissal — Tasks 1-5 all test-first; Task 8's e2e includes an explicit red-verification step. E2E browser-loss scenario with own RustServer/ephemeral ports/server restart/fresh context/decline/same-browser-reload — Task 8. Scope fence, a11y lint, PR policy — Global Constraints + Task 10.
+**1. Spec coverage:** (1) recover-my-panes flow — offer/trigger D1-D3 + Tasks 3/5/6 (boot-capture rationale corrected per A8, with the import-order invariants pinned and tested in Task 3); accept recreation honoring §4.2 D4-D5 + Tasks 1/4/5, including the A10 per-kind adapter (editor `content: ''` default, fresh-agent `restoreError` strip) with unit tests for editor/extension/picker; decline remembered Task 3/5, with the A5/A6 fix — `contentId` is sha256 over timestamp-free substance, so dismissal survives heartbeats, restarts, and Rust upgrades (tested: capturedAt/updatedAt bumps don't change it). (2) Liveness (A2/D7) — Task 1's third `live_session_keys` input + per-pane `live` flag, Task 2's read-only registry join, Task 2b's server-side guard on the direct sessionRef rung (failing integration test first), Task 4's sessionRef strip for live panes, Task 5's live note, Task 8 Scenario 3's no-restart proof (no new `--resume` pair). (3) Inventory correctness — `ledgerOnly` matched against effective refs across ALL device unions and excluding live rows (A4, tested), the A15 staleness rule dropping >15-min-silent clients (pure helper test + route test), self-pollution filter, auth'd. (4) kata h9vt — disposition section + Task 9 (Option A kept; Option B rejected with reason: ledger has no layout; the GET read API + `parse_selector` explicitly REUSED per A11; deploy-tab-diff remediation + spec reworked per A12; freshell-ws screenshot broker handled via the explicit A13 audit table since the compiler is silent for pub library items). TDD red-first for trigger conditions, inventory API, authority chain, liveness guard, dismissal — Tasks 1-5 + 2b all test-first; Task 8's e2e includes an explicit red-verification step. E2E — Task 8: three scenarios (restart accept-resume with argv-pair proof + browser-pane mixed-kind recreation, decline, no-restart live loss) with own RustServer/ephemeral ports/fresh contexts/same-browser-reload guard. Scope fence, a11y lint, PR policy — Global Constraints + Task 10 (which also carries the AD-1 §4.4 ratification statement and the B4 flag).
 
-**1b. No silent deferrals:** no stubs or fake providers stand in for required behavior — the e2e uses the repo's established fake-CLI fixture (the same production-path proof used by the existing ledger restart e2e; it exercises the real create/resume path). Non-terminal pane recreation reuses the production `reopenClosedTab` restore path (passthrough, D5) — recreated, not deferred. Split geometry is not in the store (D6) — a data fact, not a deferral. No UNRESOLVED COVERAGE GAPS.
+**1b. No silent deferrals:** no stubs or fake providers stand in for required behavior — the e2e uses the repo's established fake-CLI fixture (the same production-path proof used by the existing ledger restart e2e; it exercises the real create/resume path), and the Task 8 resume proof is built from the argv log + fixture marker (the previously-cited assertion did not exist — A14). Non-terminal pane recreation reuses the production `reopenClosedTab` restore path with a minimal per-kind adapter (D5/A10) — recreated, not deferred. Split geometry (D6) and editor buffer content (D6/A5) are not in the store — data facts, not deferrals. Two DOCUMENTED decisions with recorded rationale, not silent deferrals: (a) the freshopencode fresh-start limitation (Known-limitation note: fenced B4 crate owns the `opencode_ws.rs` bug; sessionRef passthrough kept forward-compatible; flagged to B4 in Task 10 Step 3); (b) live sessions are surfaced but NOT resumed (D7: attach-to-live rejected as unverified and colliding with Lane B1 ownership; server guard as defense-in-depth). No UNRESOLVED COVERAGE GAPS.
 
-**2. Placeholder scan:** the `row_*` accessors (Task 1) and `union_value` (Task 2) are named single-field adapters against real definitions the implementer opens — each is bound to a concrete file/line source, with tests as the arbiter; no TBD/TODO/"handle edge cases" items remain.
+**2. Placeholder scan:** the `row_*` accessors, `digest16`, and `select_foreign_recent_generation_ids` (Task 1), `union_value`, `live_session_keys`, and the registry-handle type (Task 2), and the guard's row-matching (Task 2b) are named adapters against real definitions the implementer opens — each is bound to a concrete file/line source (`pane_ledger.rs:93`, `tabs_persist.rs:70-87`, `terminal.rs:1690-1745`, main.rs wiring), with tests as the arbiter. Task 9's freshell-ws deletions are an explicit per-method audit table, not a "compiler will say" hope. No TBD/TODO/"handle edge cases" items remain.
 
-**3. Type consistency:** `DeviceUnion`/`build_inventory` (Task 1) consumed verbatim in Task 2; `RecoveryInventory`/`RecoveryPane`/`RecoveryTabPlan` (Task 4) consumed in Task 5; `getClientInstanceId` exported in Task 5 and consumed there; testids `recovery-offer-panel`/`recovery-accept`/`recovery-decline` defined in Task 5, consumed in Task 8; `ledgerState` values (`bound|closed|gc_expired|unknown`) match between Task 1 output, Task 4 types, and tests.
+**3. Type consistency:** `DeviceUnion`/`select_foreign_recent_generation_ids`/`build_inventory` (Task 1, 3-arg signature) consumed verbatim in Task 2; the `live` field appears in Task 1's output schema, Task 4's `RecoveryPane` type and test fixtures, Task 5's `INVENTORY` fixture and live-note behavior, and Task 8 Scenario 3's assertions; `RecoveryInventory`/`RecoveryPane`/`RecoveryTabPlan` (Task 4) consumed in Task 5; `getClientInstanceId` exported in Task 5 and consumed there; testids `recovery-offer-panel`/`recovery-accept`/`recovery-decline`/`recovery-live-note` defined in Task 5, consumed in Task 8; `ledgerState` values (`bound|closed|gc_expired|unknown`) match between Task 1 output, Task 4 types, and tests; Task 2b's refusal frame mirrors the existing `RestoreUnavailable` shape consumed by the harness Task 2b's test copies.

From 881a64c9e22aa3e25ca392674812fceba0e291ee Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 03:46:20 -0700
Subject: [PATCH 07/87] docs(plan): harden codex-rollout-locator plan per
 load-bearing validation

Validated against codex source @rust-v0.145.0, a 3,858-rollout corpus,
and the frozen client (evidence: .the-usual-logs ledger + reports).
Falsified assumptions fixed:
- A1: real codex materializes the rollout only at the first user prompt
  -> windows are Enter-anchored only; spawn window removed (was a pure
  foreign-capture window).
- A3: create->session_meta gap (git-info await, worst ~10s) -> unparsable
  new files become bind-blocking pending candidates with a 10s re-probe
  grace (PENDING_FIRST_LINE_GRACE_MS).
- A4 (critical): same-cwd foreign rollouts could misbind -> cwd is now
  required (no-cwd never binds), cross-tick contested-cwd refusal,
  already-bound thread-id refusal; freshagent same-cwd residual documented
  (fix fenced to Lane B4).
- A5: arm site is post-PTY-spawn -> safe because Enter-anchored; rationale
  made explicit; arm scan moved into spawn_blocking (A6 cold-cache
  insurance; measured perf numbers replace the stale 35-55ms claim).
Verified premises recorded in a new Validated Premises section; Task 11
gains a mechanical one-writer merge-time gate (A8).
---
 .../plans/2026-07-26-codex-rollout-locator.md | 818 ++++++++++++++----
 1 file changed, 652 insertions(+), 166 deletions(-)

diff --git a/docs/plans/2026-07-26-codex-rollout-locator.md b/docs/plans/2026-07-26-codex-rollout-locator.md
index 554e89c97..ecafebf44 100644
--- a/docs/plans/2026-07-26-codex-rollout-locator.md
+++ b/docs/plans/2026-07-26-codex-rollout-locator.md
@@ -73,8 +73,9 @@ Node .mjs fake-CLI fixture.
    server share ONE sessions tree:
    `<CODEX_HOME|~/.codex>/sessions/YYYY/MM/DD/rollout-<ts>-<threadId>.jsonl`
    (flat `<id>.jsonl` also supported, used by tests). Pane↔rollout attribution
-   therefore needs a disambiguator: arm-time known-files snapshot + the
-   rollout's own `session_meta.payload.cwd` + ambiguity refusal.
+   therefore needs a disambiguator set: arm-time known-files snapshot +
+   Enter-anchored windows + REQUIRED-cwd match + pending-first-line
+   bind-blocking + contested-cwd refusal (see Validated Premises below).
 2. **"One watcher, two consumers" is not feasible for discovery.** The wave-2
    status watcher (`activity.rs:349`) watches a SINGLE already-known rollout
    file, NonRecursive, and only exists once identity is known — chicken-and-egg
@@ -103,6 +104,81 @@ Node .mjs fake-CLI fixture.
    (the frozen client's only path) are covered. This is a spec-directed
    boundary, not a deferral: record it in the final commit message.
 
+### Validated Premises (load-bearing validation, 2026-07-26 — trust these over any stale task prose)
+
+Evidence sources: codex source @ tag `rust-v0.145.0` + installed
+`codex-cli 0.145.0`; a 3,858-rollout local corpus (100% first-line parse);
+frozen-client code inspection. Full reports:
+`.worktrees/.the-usual-logs/codex-rollout-locator/reports/validator-*.md`.
+A codex upgrade re-opens every codex-behavior item below.
+
+7. **(A1, FALSIFIED spawn premise) Rollout files are Enter-anchored.** Codex
+   creates the rollout file ONLY when the first user prompt is recorded
+   (`RolloutRecorder` defers file creation to `persist()`, materialized via
+   `ensure_rollout_materialized()`). A rollout can NEVER legitimately appear
+   for a pane's own codex before Enter — so the locator has NO spawn window:
+   windows open only on `note_submit`. Arm still snapshots immediately.
+8. **(A3, FALSIFIED one-shot read) Create→meta-line gap is real.** After
+   creating the file codex awaits git-info collection (subprocesses, 5 s
+   timeout each; typically ms, worst ~10 s) BEFORE writing the session_meta
+   first line. A new file with an empty/incomplete first line is therefore a
+   PENDING, BIND-BLOCKING candidate re-probed up to
+   `PENDING_FIRST_LINE_GRACE_MS = 10_000` — never dropped by a one-shot read,
+   and never outvoted by a readable foreign file while pending.
+9. **(A4, FALSIFIED — misbind defenses insufficient as originally planned.)**
+   The original snapshot+cwd+same-tick-ambiguity trio allowed clean misbinds
+   (same-cwd foreign codex/exec/fork, staggered same-cwd panes, the
+   spawn-window pure-foreign capture). Mandatory hardenings, all encoded in
+   Tasks 1-3: Enter-only windows (item 7); cwd REQUIRED — a no-cwd
+   session_meta NEVER binds (`SessionMeta.cwd` is non-optional at 0.145.0,
+   3,858/3,858 corpus; a permissive no-cwd rule is pure attack surface);
+   pending-candidate bind-blocking (item 8); CROSS-TICK contested-cwd
+   refusal — while ≥2 armed terminals share a normalized cwd nothing binds
+   for any of them; and the adoption tail refuses a thread id already bound
+   to another terminal (retired-inclusive; idempotent same-terminal re-adopt
+   allowed).
+10. **(A4 residual risk — documented, NOT solvable in this lane.)** A
+    freshell-freshagent codex agent session started in the SAME cwd during a
+    pane's open window can still misbind as a sole candidate: freshagent's
+    `codex app-server` sidecar writes rollouts into the same
+    `$HOME/.codex/sessions` root. Recommended future fix (Lane B4
+    coordination): exclude freshagent-known thread ids (`thread/start`
+    results) at adoption. Recorded here so the risk is owned, not silent.
+11. **(A5) The post-spawn arm site is safe — but only because of item 7.**
+    The planned `maybe_arm` call site (terminal.rs ~:1521-1527) runs AFTER
+    the PTY spawn, with awaits in between. Enter-anchored discovery makes
+    the spawn→arm gap harmless: the pane's own rollout cannot exist yet. Do
+    not describe the snapshot as preceding spawn — it doesn't need to.
+12. **(A6, verified with corrections) Walk performance.** Real tree
+    (3,858 files): 7-9 ms warm. Synthetic 100k files: p95 96 ms warm, worst
+    117 ms under 8-way concurrency (native ext4, WSL2). The earlier
+    "35-55 ms on an 8k-file tree" figure did NOT reproduce — do not cite it.
+    Cold cache is unmeasured (needs sudo): run BOTH `arm()` and `tick()`
+    scans inside `spawn_blocking`, never on the WS dispatch path.
+13. **(A2/A9, confirmed) cwd + shape + resume argv.** `payload.cwd` is the
+    codex process's physical `getcwd` path recorded verbatim (no
+    canonicalization codex-side); equality holds BECAUSE freshell's
+    `normalize_cwd` opportunistically canonicalizes the pane side — that
+    canonicalize is load-bearing. `payload.id` == the filename threadId, a
+    36-char UUID; `codex resume <uuid>` positional is first-class. 0.145.0
+    source contains `.jsonl.zst` rollout compression — fresh sessions still
+    write plain `.jsonl`; the `.jsonl` suffix filter excludes compressed
+    artifacts. Filename timestamp and `YYYY/MM/DD` dir are precomputed at
+    session construction — can predate on-disk creation by the whole idle
+    gap / cross midnight; the locator never filters on either. Resumed
+    sessions append to their existing file (no new file) — consistent with
+    the arm gate refusing resume panes.
+14. **(A10/A7, confirmed) Env + frozen client.** The PTY child inherits the
+    server env minus a STRIP_ENV list that touches neither `CODEX_HOME` nor
+    `HOME`, and codex is exec'd directly (no shell rc) — the shared
+    sessions-root premise holds. Residual (noted, not fixed): a per-terminal
+    `envOverrides` containing `CODEX_HOME` would diverge the child's root.
+    The frozen client applies `terminal.session.associated`
+    provider-generically (`App.tsx:1004-1017` → panesSlice `sessionRef`) and
+    its candidate sender is dormant against the Rust server; its conflict
+    guard drops a push only when the pane already holds a DIFFERENT
+    sessionRef — impossible for the fresh panes the locator arms.
+
 ## File Structure
 
 | File | Action | Responsibility |
@@ -136,7 +212,7 @@ Key existing reference files (read, don't modify beyond what tasks say):
 
 ---
 
-### Task 1: CodexLocator skeleton — types, arm gates, scan substrate, spawn-window happy path
+### Task 1: CodexLocator skeleton — types, arm gates, scan substrate, Enter-anchored happy path
 
 **Files:**
 - Create: `crates/freshell-sessions/src/codex_locator.rs`
@@ -150,6 +226,7 @@ Key existing reference files (read, don't modify beyond what tasks say):
 
 ```rust
 pub const CODEX_WINDOW_MS: i64 = 2_000;
+pub const PENDING_FIRST_LINE_GRACE_MS: i64 = 10_000;
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Located {
@@ -167,7 +244,7 @@ impl CodexLocator {
     pub fn armed_count(&self) -> usize;
     pub fn fs_scan_count(&self) -> u64;
     pub fn arm(&self, terminal_id: &str, mode: &str, status_running: bool,
-               resume_session_id: Option<&str>, cwd: Option<&str>, now_ms: i64) -> bool;
+               resume_session_id: Option<&str>, cwd: Option<&str>) -> bool;
     pub fn disarm(&self, terminal_id: &str);
     pub fn note_submit(&self, terminal_id: &str, at_ms: i64) -> bool;
     pub fn tick(&self, now_ms: i64) -> Vec<Located>;
@@ -175,22 +252,60 @@ impl CodexLocator {
 ```
 
 Design notes to encode in the module doc (deliberate deviations from the
-opencode locator, each with rationale):
+opencode locator, each with rationale — the codex-behavior facts below are
+validated against codex source @ rust-v0.145.0 and a 3,858-rollout local
+corpus; see "Validated Premises" above):
 - Substrate is a filesystem snapshot-diff, not SQLite row-diff: codex persists
   one JSONL rollout file per session under the sessions root.
 - There is NO `pre_epsilon_ms` and NO created-at time bound: filesystems have
   no reliable cross-platform creation time. The arm-time `known_files`
   snapshot is the sole (and primary — same as opencode's `known_ids`) safety:
-  a file already present at arm can never bind to this terminal.
-- Window semantics are otherwise identical to opencode: deadline is
-  `arm_ms + spawn_window_ms` until a submit lands, then `enter_ms + window_ms`;
-  submits only extend, never shorten; evaluation happens once per open window
-  (`resolved` flag), and a later Enter re-opens it.
+  a file already present at arm can never bind to this terminal. The locator
+  also never filters by the FILENAME timestamp or by today's `YYYY/MM/DD`
+  directory: the filename timestamp is precomputed at codex session
+  construction and can predate on-disk creation by the entire user idle gap,
+  and the dated dir can be a previous day across midnight — the full-tree
+  snapshot-diff sidesteps both.
+- Windows are ENTER-ANCHORED ONLY — there is NO spawn-anchored window (a
+  deliberate deviation from opencode). Real codex (0.145.0) defers rollout
+  file creation until the first user prompt is recorded (`RolloutRecorder`
+  defers to `persist()`, materialized via `ensure_rollout_materialized()`),
+  so a rollout can NEVER legitimately appear for this pane's codex before
+  Enter — a spawn window would be a pure FOREIGN-capture window. `arm()`
+  still takes the known-files snapshot immediately; it schedules no deadline
+  until `note_submit`. Deadline is `enter_ms + window_ms`; evaluation happens
+  once per open window (`resolved` flag), and a later Enter re-opens it.
+- cwd is REQUIRED: a first line whose `session_meta.payload` lacks `cwd` is
+  never a candidate (`SessionMeta.cwd` is non-optional at 0.145.0;
+  3,858/3,858 real rollouts carry it — a no-cwd rule would be pure foreign
+  attack surface). The cwd match relies on `normalize_cwd`'s opportunistic
+  `fs::canonicalize` of the pane side being load-bearing: `payload.cwd` is
+  the codex process's physical `getcwd` path, recorded verbatim.
+- Pending first-line grace: codex CREATES the file, then awaits git-info
+  collection (subprocesses, 5 s timeout each, worst ~10 s) BEFORE writing the
+  `session_meta` line — a deadline scan can see an empty/incomplete first
+  line. Such a NEW file is a PENDING candidate: re-probed each sweep up to
+  `PENDING_FIRST_LINE_GRACE_MS`, and while ANY pending candidate exists the
+  terminal binds NOTHING (bind-blocking — a readable foreign file must not
+  win while the pane's own file sits in its git-info gap). An Enter→creation
+  latency exceeding the 2 s window (slow first-prompt recording) is mitigated
+  by this grace plus window re-open on a later Enter.
+- Contested-cwd refusal is CROSS-TICK: while ≥2 armed terminals share a
+  normalized cwd, no candidate with that cwd binds for any of them —
+  staggered deadlines must not let one pane grab a sibling's rollout
+  uncontested.
+- Resumed codex sessions append to their EXISTING rollout file (no new file)
+  — consistent with the arm gate refusing resume panes. Compressed rollout
+  artifacts (`.jsonl.zst`, present in 0.145.0 source) are excluded by the
+  `.jsonl` suffix filter; fresh sessions always write plain `.jsonl`.
 - Scans happen ONLY at arm time and at deadline evaluations (never on idle
-  ticks — proven by `fs_scan_count`), bounded to walk depth 5 (the tree is
-  `sessions/YYYY/MM/DD/rollout-*.jsonl`; flat `<id>.jsonl` in tests). Measured
-  35-55 ms warm on a real 8k-file tree; callers run `tick()` in
-  `spawn_blocking`.
+  ticks — proven by `fs_scan_count`; a pending candidate keeps its window's
+  evaluation due, so re-probes ride the same gate), bounded to walk depth 5
+  (the tree is `sessions/YYYY/MM/DD/rollout-*.jsonl`; flat `<id>.jsonl` in
+  tests). Measured (A6, native ext4 under WSL2): 7-9 ms on the real
+  3.8k-file tree; synthetic 100k files p95 96 ms warm, worst 117 ms under
+  8-way concurrency. Cold-cache is unmeasured — callers run BOTH `arm()` and
+  `tick()` inside `spawn_blocking`.
 
 - [ ] **Step 1: Write the failing tests**
 
@@ -240,20 +355,24 @@ mod tests {
     const TID: &str = "11111111-2222-3333-4444-555555555555";
 
     #[test]
-    fn fresh_rollout_written_at_spawn_resolves_via_spawn_window() {
-        let root = unique_temp_dir("spawn-happy");
+    fn fresh_rollout_after_first_enter_resolves_via_enter_window() {
+        let root = unique_temp_dir("enter-happy");
         let cwd = root.join("project");
         std::fs::create_dir_all(&cwd).unwrap();
         let cwd_s = cwd.to_string_lossy().to_string();
         let locator = CodexLocator::new(root.clone());
 
-        assert!(locator.arm("t1", "codex", true, None, Some(&cwd_s), 1_000));
-        // Rollout appears AFTER arm, BEFORE the spawn deadline — no Enter at all.
+        assert!(locator.arm("t1", "codex", true, None, Some(&cwd_s)));
+        // No submit yet -> no deadline exists; nothing to evaluate.
+        assert!(locator.tick(10_000).is_empty());
+        // Enter at 20_000; the rollout appears AFTER the submit (real codex
+        // materializes the file only when the first user prompt is recorded).
+        assert!(locator.note_submit("t1", 20_000));
         let path = write_rollout(&root, "2026/07/26", TID, Some(&cwd_s));
 
-        // Before the deadline: nothing yet (evaluation happens at deadline).
-        assert!(locator.tick(1_000 + CODEX_WINDOW_MS - 1).is_empty());
-        let located = locator.tick(1_000 + CODEX_WINDOW_MS);
+        // Before the Enter-anchored deadline: nothing yet.
+        assert!(locator.tick(20_000 + CODEX_WINDOW_MS - 1).is_empty());
+        let located = locator.tick(20_000 + CODEX_WINDOW_MS);
         assert_eq!(
             located,
             vec![Located {
@@ -265,7 +384,25 @@ mod tests {
         );
         // Success fully resolves and disarms; tick() drains.
         assert_eq!(locator.armed_count(), 0);
-        assert!(locator.tick(1_000 + CODEX_WINDOW_MS + 1).is_empty());
+        assert!(locator.tick(20_000 + CODEX_WINDOW_MS + 1).is_empty());
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn rollout_after_arm_without_submit_is_never_bound_and_never_scanned() {
+        // A1 (validated): real codex creates the rollout ONLY at the first
+        // user prompt, so before Enter every new same-cwd rollout is by
+        // construction FOREIGN. With no submit there is NO window: the file
+        // must never bind and no deadline scans may run.
+        let root = unique_temp_dir("no-submit");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert_eq!(locator.fs_scan_count(), 1); // the arm snapshot
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert!(locator.tick(100 * CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        assert_eq!(locator.fs_scan_count(), 1); // still only the arm snapshot
         let _ = std::fs::remove_dir_all(&root);
     }
 
@@ -274,17 +411,17 @@ mod tests {
         let root = unique_temp_dir("gates");
         let locator = CodexLocator::new(root.clone());
         // wrong mode
-        assert!(!locator.arm("t1", "opencode", true, None, Some("/tmp"), 0));
+        assert!(!locator.arm("t1", "opencode", true, None, Some("/tmp")));
         // not running
-        assert!(!locator.arm("t1", "codex", false, None, Some("/tmp"), 0));
+        assert!(!locator.arm("t1", "codex", false, None, Some("/tmp")));
         // resume id present — the ONLY already-bound gate (no restore flag)
-        assert!(!locator.arm("t1", "codex", true, Some(TID), Some("/tmp"), 0));
+        assert!(!locator.arm("t1", "codex", true, Some(TID), Some("/tmp")));
         // missing / empty cwd
-        assert!(!locator.arm("t1", "codex", true, None, None, 0));
-        assert!(!locator.arm("t1", "codex", true, None, Some(""), 0));
+        assert!(!locator.arm("t1", "codex", true, None, None));
+        assert!(!locator.arm("t1", "codex", true, None, Some("")));
         // happy arm, then idempotent re-arm returns false
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
-        assert!(!locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(!locator.arm("t1", "codex", true, None, Some("/tmp")));
         assert_eq!(locator.armed_count(), 1);
         let _ = std::fs::remove_dir_all(&root);
     }
@@ -293,7 +430,8 @@ mod tests {
     fn disarmed_terminal_never_resolves() {
         let root = unique_temp_dir("disarm");
         let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
         write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
         locator.disarm("t1");
         assert!(locator.tick(CODEX_WINDOW_MS + 1).is_empty());
@@ -310,9 +448,10 @@ mod tests {
         assert!(locator.tick(10_000).is_empty());
         assert_eq!(locator.fs_scan_count(), 0);
         // Arming scans once (the known-files snapshot)…
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
         assert_eq!(locator.fs_scan_count(), 1);
-        // …but a tick BEFORE any deadline is due still scans nothing.
+        // …and a tick BEFORE any Enter-anchored deadline is due (here: no
+        // submit at all, so no deadline exists) still scans nothing.
         let before = locator.fs_scan_count();
         assert!(locator.tick(1).is_empty());
         assert_eq!(locator.fs_scan_count(), before);
@@ -345,25 +484,59 @@ module is the RED state for a new module.
 //! flat `<id>.jsonl` in tests). A new session is a NEW FILE — so the locator
 //! does a snapshot-diff of the file set, not a row-diff.
 //!
+//! Codex-behavior facts below are validated against codex source @
+//! rust-v0.145.0 and a 3,858-rollout corpus; a codex upgrade re-opens them.
+//!
 //! Deliberate deviations from the opencode locator, with rationale:
+//! - Windows are ENTER-ANCHORED ONLY — no spawn window. Real codex defers
+//!   rollout file creation until the first user prompt is recorded
+//!   (`RolloutRecorder` defers to `persist()`, materialized via
+//!   `ensure_rollout_materialized()`), so before the pane's first Enter every
+//!   new same-cwd rollout is by construction FOREIGN. `arm()` takes the
+//!   known-files snapshot immediately but schedules NO deadline until
+//!   `note_submit`.
 //! - NO `pre_epsilon_ms` and NO created-at time bound: filesystems have no
 //!   reliable cross-platform creation time (mtime moves on every append).
-//!   The arm-time `known_files` snapshot is the sole safety — a file already
-//!   present at arm can never bind to this terminal. (For opencode the
-//!   snapshot is ALSO the primary safety; the time bound there is
-//!   defense-in-depth the fs cannot provide.)
+//!   The arm-time `known_files` snapshot is the primary safety — a file
+//!   already present at arm can never bind to this terminal. The FILENAME
+//!   timestamp and the dated `YYYY/MM/DD` dir are never used as filters
+//!   either: both are precomputed at codex session construction and can
+//!   predate on-disk creation by the entire user idle gap (the dir can even
+//!   be "yesterday" across midnight). The full-tree snapshot-diff sidesteps
+//!   both.
 //! - Attribution disambiguator: the rollout's own first-line
-//!   `session_meta.payload.cwd` (when present) must match the armed
-//!   terminal's cwd. When absent, ambiguity refusal still protects
-//!   concurrent spawns (see `tick`).
+//!   `session_meta.payload.cwd` is REQUIRED and must match the armed
+//!   terminal's cwd (`SessionMeta.cwd` is non-optional at 0.145.0;
+//!   3,858/3,858 real rollouts carry it — accepting a no-cwd line would be
+//!   pure foreign attack surface). `payload.cwd` is the codex process's
+//!   physical `getcwd` path recorded verbatim; equality holds because
+//!   `normalize_cwd` opportunistically canonicalizes the pane side — that
+//!   canonicalize is load-bearing for symlinked spawn dirs.
+//! - Pending first-line grace: codex CREATES the file, then awaits git-info
+//!   collection (subprocesses, 5 s timeout each, worst ~10 s) BEFORE writing
+//!   the `session_meta` line. A NEW file whose first line is empty/incomplete
+//!   is a PENDING candidate: re-probed each sweep up to
+//!   `PENDING_FIRST_LINE_GRACE_MS`, and while ANY pending candidate exists
+//!   this terminal binds NOTHING (bind-blocking — a readable foreign file
+//!   must not win while the pane's own file sits in its git-info gap).
+//!   Enter→creation latency beyond the 2 s window is mitigated by this grace
+//!   plus window re-open on a later Enter.
+//! - Contested-cwd refusal is CROSS-TICK: while ≥2 armed terminals share a
+//!   normalized cwd, no candidate with that cwd binds for any of them.
 //! - Ownership is proven ONLY by `payload.id` on line 1 — NEVER the filename
 //!   (prefilter-grade at best), NEVER `payload.session_id` (fork/resume
 //!   LINEAGE: matches a FOREIGN session in 54/144 sampled real rollouts) —
 //!   same predicate as `freshell-ws`'s `first_line_owns`.
+//! - Resumed codex sessions append to their EXISTING rollout file (no new
+//!   file) — consistent with the arm gate refusing resume panes. Compressed
+//!   artifacts (`.jsonl.zst`, present in 0.145.0 source) fail the `.jsonl`
+//!   suffix filter; fresh sessions always write plain `.jsonl`.
 //!
-//! Zero cost when idle: scans happen only at arm and at deadline
-//! evaluations, proven by `fs_scan_count`. Callers run `tick()` inside
-//! `tokio::task::spawn_blocking`.
+//! Zero cost when idle: scans happen only at arm and at due Enter-anchored
+//! evaluations (a pending candidate keeps its evaluation due, so re-probes
+//! ride the same gate), proven by `fs_scan_count`. Callers run BOTH `arm()`
+//! and `tick()` inside `tokio::task::spawn_blocking` (cold dentry cache is
+//! the one unmeasured tail — A6).
 
 use std::collections::{HashMap, HashSet};
 use std::path::{Path, PathBuf};
@@ -372,11 +545,19 @@ use std::sync::Mutex;
 
 use crate::opencode_locator::normalize_cwd;
 
-/// Correlation window after a submit (Enter-anchored deadline), and the
-/// spawn-anchored fallback window (spawn_window_ms := window_ms, kept
-/// distinct for clarity — same convention as the opencode locator).
+/// Correlation window after a submit (Enter-anchored deadline). There is NO
+/// spawn-anchored window: real codex (0.145.0) creates the rollout file only
+/// when the first user prompt is recorded, so before the pane's first Enter
+/// every new same-cwd rollout is by construction foreign.
 pub const CODEX_WINDOW_MS: i64 = 2_000;
 
+/// Bounded re-probe grace for a NEW file whose first line is not yet
+/// readable: codex creates the file, then awaits git-info collection
+/// (subprocesses, 5 s timeout each, worst ~10 s) before writing the
+/// `session_meta` line. Matches codex's worst case and the magnitude of the
+/// existing `IDENTITY_RESOLUTION_GRACE_MS`.
+pub const PENDING_FIRST_LINE_GRACE_MS: i64 = 10_000;
+
 /// Bounded first-line read cap — real rollouts reach 152 MB; observed real
 /// first lines are ≤ 22.4 KB. Mirrors `codex_reconcile.rs`.
 const MAX_FIRST_LINE_BYTES: u64 = 1024 * 1024;
@@ -396,10 +577,15 @@ pub struct Located {
 #[derive(Debug, Clone)]
 struct Armed {
     cwd_normalized: String,
-    arm_ms: i64,
     known_files: HashSet<PathBuf>,
     enter_ms: Option<i64>,
     resolved: bool,
+    /// NEW files whose first line was empty/incomplete when probed, keyed to
+    /// first-seen ms. While any un-expired entry exists, this terminal binds
+    /// NOTHING (bind-blocking); entries older than
+    /// `PENDING_FIRST_LINE_GRACE_MS` are merged into `known_files`
+    /// (permanently excluded — fail toward refusal).
+    pending_first_line: HashMap<PathBuf, i64>,
 }
 
 #[derive(Default)]
@@ -410,7 +596,6 @@ struct Inner {
 pub struct CodexLocator {
     sessions_root: PathBuf,
     window_ms: i64,
-    spawn_window_ms: i64,
     inner: Mutex<Inner>,
     fs_scan_count: AtomicU64,
 }
@@ -424,7 +609,6 @@ impl CodexLocator {
         Self {
             sessions_root,
             window_ms,
-            spawn_window_ms: window_ms,
             inner: Mutex::new(Inner::default()),
             fs_scan_count: AtomicU64::new(0),
         }
@@ -442,6 +626,8 @@ impl CodexLocator {
     /// NO resume id (the only already-bound gate — never a restore flag, so
     /// restore-created identity-less panes re-arm for free), non-empty cwd,
     /// not already armed. On success takes the arm-time known-files snapshot.
+    /// Arming schedules NO deadline — windows open only on `note_submit`
+    /// (Enter-anchored; see module doc).
     pub fn arm(
         &self,
         terminal_id: &str,
@@ -449,7 +635,6 @@ impl CodexLocator {
         status_running: bool,
         resume_session_id: Option<&str>,
         cwd: Option<&str>,
-        now_ms: i64,
     ) -> bool {
         if mode != "codex" || !status_running || resume_session_id.is_some() {
             return false;
@@ -466,10 +651,10 @@ impl CodexLocator {
             terminal_id.to_string(),
             Armed {
                 cwd_normalized: normalize_cwd(cwd),
-                arm_ms: now_ms,
                 known_files,
                 enter_ms: None,
                 resolved: false,
+                pending_first_line: HashMap::new(),
             },
         );
         true
@@ -479,9 +664,11 @@ impl CodexLocator {
         self.inner.lock().unwrap().armed.remove(terminal_id);
     }
 
-    /// Enter re-open semantics (mirrors opencode): a mid-turn Enter never
-    /// re-opens a still-pending evaluation; a resolved (zero-candidate /
-    /// ambiguous) terminal gets a fresh Enter-anchored deadline.
+    /// The FIRST submit is what opens a window at all (windows are
+    /// Enter-anchored — arm schedules no deadline). Re-open semantics mirror
+    /// opencode: a mid-turn Enter never re-opens a still-pending evaluation;
+    /// a resolved (zero-candidate / ambiguous / contested) terminal gets a
+    /// fresh Enter-anchored deadline.
     pub fn note_submit(&self, terminal_id: &str, at_ms: i64) -> bool {
         let mut inner = self.inner.lock().unwrap();
         let Some(armed) = inner.armed.get_mut(terminal_id) else {
@@ -495,18 +682,25 @@ impl CodexLocator {
         true
     }
 
-    fn deadline(&self, armed: &Armed) -> i64 {
-        match armed.enter_ms {
-            Some(enter_ms) => enter_ms + self.window_ms,
-            None => armed.arm_ms + self.spawn_window_ms,
-        }
+    /// A terminal is due only when an Enter-anchored deadline exists and has
+    /// passed. No submit -> no window -> never evaluated (see module doc).
+    fn due(&self, armed: &Armed, now_ms: i64) -> bool {
+        matches!(armed.enter_ms, Some(enter_ms) if !armed.resolved && now_ms >= enter_ms + self.window_ms)
     }
 
-    /// One evaluation per open window, at (or after) its deadline. Outcomes:
+    /// Evaluation at (or after) an Enter-anchored deadline. Outcomes:
+    /// any NEW file with an empty/incomplete first line (codex's
+    /// create→session_meta git-info gap) → PENDING: bind NOTHING for this
+    /// terminal, stay unresolved, re-probe each sweep up to
+    /// `PENDING_FIRST_LINE_GRACE_MS` (grace-expired files are permanently
+    /// excluded);
     /// 0 candidates → keep watching (stays armed, `resolved = true`);
     /// >1 candidates for one terminal → WARN + refuse (never guess);
+    /// exactly one candidate but ≥2 ARMED terminals share this cwd → WARN +
+    /// refuse (contested cwd — cross-tick, so staggered deadlines can't grab
+    /// a sibling's rollout uncontested);
     /// one candidate claimed by ≥2 terminals in the same tick → WARN + refuse
-    /// ALL claimants (concurrent same-cwd spawns are indistinguishable);
+    /// ALL claimants (defense-in-depth behind the cwd census);
     /// exactly one clean match → emit `Located` and disarm. `tick()` drains.
     pub fn tick(&self, now_ms: i64) -> Vec<Located> {
         {
@@ -514,49 +708,88 @@ impl CodexLocator {
             if inner.armed.is_empty() {
                 return Vec::new();
             }
-            if !inner
-                .armed
-                .values()
-                .any(|a| !a.resolved && now_ms >= self.deadline(a))
-            {
+            if !inner.armed.values().any(|a| self.due(a, now_ms)) {
                 return Vec::new();
             }
         }
         let current = self.scan_rollout_files();
         let mut inner = self.inner.lock().unwrap();
 
+        // Cross-tick contested-cwd census over ALL armed terminals (not just
+        // the due ones): two armed same-cwd panes are indistinguishable on
+        // this substrate, whatever their deadlines.
+        let mut cwd_counts: HashMap<String, usize> = HashMap::new();
+        for a in inner.armed.values() {
+            *cwd_counts.entry(a.cwd_normalized.clone()).or_insert(0) += 1;
+        }
+
         // Pass 1: per-terminal candidate evaluation.
         let mut claims: Vec<(String, Located)> = Vec::new();
         for (terminal_id, armed) in inner.armed.iter_mut() {
-            if armed.resolved || now_ms < self.deadline(armed) {
+            if !matches!(armed.enter_ms, Some(e) if !armed.resolved && now_ms >= e + self.window_ms)
+            {
                 continue;
             }
-            armed.resolved = true;
+            let new_paths: Vec<PathBuf> =
+                current.difference(&armed.known_files).cloned().collect();
             let mut matches: Vec<(PathBuf, RolloutMeta)> = Vec::new();
-            for path in current.difference(&armed.known_files) {
-                let Some(meta) = probe_rollout(path) else {
-                    continue;
-                };
-                if let Some(cwd) = &meta.cwd {
-                    if normalize_cwd(cwd) != armed.cwd_normalized {
-                        continue;
+            let mut pending_blocking = false;
+            for path in new_paths {
+                match probe_rollout(&path) {
+                    Probe::Candidate(meta) => {
+                        armed.pending_first_line.remove(&path);
+                        if normalize_cwd(&meta.cwd) == armed.cwd_normalized {
+                            matches.push((path, meta));
+                        }
                     }
+                    Probe::NotYet => {
+                        let first_seen =
+                            *armed.pending_first_line.entry(path.clone()).or_insert(now_ms);
+                        if now_ms - first_seen >= PENDING_FIRST_LINE_GRACE_MS {
+                            // Grace exhausted: permanently excluded (fail
+                            // toward refusal — A4 hardening 1).
+                            armed.pending_first_line.remove(&path);
+                            armed.known_files.insert(path);
+                        } else {
+                            pending_blocking = true;
+                        }
+                    }
+                    Probe::Never => {}
                 }
-                matches.push((path.clone(), meta));
             }
+            if pending_blocking {
+                // A new file is still inside codex's create→session_meta gap
+                // (git-info collection, worst ~10 s). It may be THIS pane's
+                // rollout — binding any other candidate now could hand the
+                // window to a foreign file while the true owner is unreadable.
+                // Bind nothing, stay unresolved, re-probe next sweep.
+                tracing::debug!(
+                    terminal_id = %terminal_id,
+                    "codex_locator_pending: new rollout first line not yet readable; deferring evaluation"
+                );
+                continue;
+            }
+            armed.resolved = true;
             match matches.len() {
                 0 => {} // keep watching
                 1 => {
-                    let (path, meta) = matches.remove(0);
-                    claims.push((
-                        terminal_id.clone(),
-                        Located {
-                            terminal_id: terminal_id.clone(),
-                            thread_id: meta.thread_id,
-                            rollout_path: path,
-                            cwd: armed.cwd_normalized.clone(),
-                        },
-                    ));
+                    if cwd_counts.get(&armed.cwd_normalized).copied().unwrap_or(0) >= 2 {
+                        tracing::warn!(
+                            terminal_id = %terminal_id,
+                            "codex_locator_contested_cwd: >=2 armed terminals share this cwd; refusing to bind"
+                        );
+                    } else {
+                        let (path, meta) = matches.remove(0);
+                        claims.push((
+                            terminal_id.clone(),
+                            Located {
+                                terminal_id: terminal_id.clone(),
+                                thread_id: meta.thread_id,
+                                rollout_path: path,
+                                cwd: armed.cwd_normalized.clone(),
+                            },
+                        ));
+                    }
                 }
                 n => {
                     tracing::warn!(
@@ -568,8 +801,10 @@ impl CodexLocator {
             }
         }
 
-        // Pass 2: cross-terminal conflict — the same rollout (or thread id)
-        // claimed by two armed terminals in one tick is unattributable.
+        // Pass 2: same-tick cross-terminal conflict — the same rollout (or
+        // thread id) claimed by two armed terminals in one tick is
+        // unattributable. (Defense-in-depth: the contested-cwd census above
+        // already refuses same-cwd claimants across ticks.)
         let mut located = Vec::new();
         for (terminal_id, candidate) in &claims {
             let contested = claims.iter().any(|(other_tid, other)| {
@@ -624,37 +859,67 @@ impl CodexLocator {
 
 struct RolloutMeta {
     thread_id: String,
-    cwd: Option<String>,
+    /// REQUIRED — `SessionMeta.cwd` is non-optional at codex 0.145.0
+    /// (3,858/3,858 real rollouts carry it); a no-cwd first line is a
+    /// foreign shape, never a candidate (A4 hardening).
+    cwd: String,
+}
+
+/// Tri-state probe result. The distinction between `NotYet` and `Never` is
+/// load-bearing: codex writes the whole session_meta line + '\n' in one
+/// write-then-flush, so a COMPLETE (newline-terminated) line that fails the
+/// candidate shape will never become one, while an empty file or a line
+/// without its trailing newline is codex's create→meta gap (or a raced
+/// write) — "not yet", not "never" (A3, validated).
+enum Probe {
+    /// Parseable `session_meta` with a bare-UUID `payload.id` AND a
+    /// `payload.cwd` — a real candidate shape.
+    Candidate(RolloutMeta),
+    /// Empty file, transient open/read failure, or first line still missing
+    /// its trailing newline — re-probe within the pending grace.
+    NotYet,
+    /// Complete first line that is not a codex session_meta candidate
+    /// (non-JSON, wrong type, non-UUID id, missing cwd, oversized) — never
+    /// a candidate; the locator stays silent on foreign files.
+    Never,
 }
 
-/// Identity probe: bounded first-line read; the line must be a
-/// `session_meta` whose `payload.id` is a bare hyphenated UUID. Anything
-/// else (foreign shapes, oversized lines, non-JSON) is silently not a
-/// candidate — the locator never errors on foreign files in a shared tree.
-fn probe_rollout(path: &Path) -> Option<RolloutMeta> {
+/// Identity probe: bounded first-line read (see `Probe` for the tri-state
+/// semantics).
+fn probe_rollout(path: &Path) -> Probe {
     use std::io::BufRead;
-    let file = std::fs::File::open(path).ok()?;
+    let Ok(file) = std::fs::File::open(path) else {
+        return Probe::NotYet;
+    };
     let mut reader = std::io::BufReader::new(file).take(MAX_FIRST_LINE_BYTES);
     let mut first_line = Vec::new();
-    reader.read_until(b'\n', &mut first_line).ok()?;
+    if reader.read_until(b'\n', &mut first_line).is_err() {
+        return Probe::NotYet;
+    }
     if first_line.len() as u64 >= MAX_FIRST_LINE_BYTES && !first_line.ends_with(b"\n") {
-        return None;
+        return Probe::Never; // oversized: will never fit the cap
+    }
+    if first_line.is_empty() || !first_line.ends_with(b"\n") {
+        return Probe::NotYet; // create→meta gap, or a raced partial write
     }
-    let record: serde_json::Value = serde_json::from_slice(&first_line).ok()?;
+    let Ok(record) = serde_json::from_slice::<serde_json::Value>(&first_line) else {
+        return Probe::Never;
+    };
     if record.get("type").and_then(|v| v.as_str()) != Some("session_meta") {
-        return None;
+        return Probe::Never;
     }
-    let thread_id = record.pointer("/payload/id").and_then(|v| v.as_str())?;
+    let Some(thread_id) = record.pointer("/payload/id").and_then(|v| v.as_str()) else {
+        return Probe::Never;
+    };
     if !is_uuid_shaped(thread_id) {
-        return None;
+        return Probe::Never;
     }
-    let cwd = record
-        .pointer("/payload/cwd")
-        .and_then(|v| v.as_str())
-        .map(str::to_string);
-    Some(RolloutMeta {
+    let Some(cwd) = record.pointer("/payload/cwd").and_then(|v| v.as_str()) else {
+        return Probe::Never; // cwd REQUIRED (A4 hardening)
+    };
+    Probe::Candidate(RolloutMeta {
         thread_id: thread_id.to_string(),
-        cwd,
+        cwd: cwd.to_string(),
     })
 }
 
@@ -691,7 +956,7 @@ Check whether `tracing` is already a dependency of `freshell-sessions`
 - [ ] **Step 4: Run tests to verify they pass**
 
 Run: `cargo test -p freshell-sessions codex_locator`
-Expected: PASS (4 tests).
+Expected: PASS (6 tests).
 
 - [ ] **Step 5: Format, lint, commit**
 
@@ -699,7 +964,7 @@ Expected: PASS (4 tests).
 cargo fmt --all
 cargo clippy -p freshell-sessions --all-targets -- -D warnings
 git add crates/freshell-sessions/src/codex_locator.rs crates/freshell-sessions/src/lib.rs crates/freshell-sessions/src/opencode_locator.rs crates/freshell-sessions/Cargo.toml
-git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot substrate, spawn-window resolve"
+git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot substrate, Enter-anchored resolve with pending-first-line grace"
 ```
 (Omit `Cargo.toml` from the add list if it was not modified.)
 
@@ -727,7 +992,8 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
         // forever, regardless of any timing.
         write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
         let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 1_000));
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 1_000));
         assert!(locator.tick(1_000 + CODEX_WINDOW_MS).is_empty());
         assert_eq!(locator.armed_count(), 1); // zero candidates → keep watching
         let _ = std::fs::remove_dir_all(&root);
@@ -737,7 +1003,8 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
     fn foreign_cwd_rollout_is_never_a_candidate() {
         let root = unique_temp_dir("cwd");
         let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/home/me/project-a"), 0));
+        assert!(locator.arm("t1", "codex", true, None, Some("/home/me/project-a")));
+        assert!(locator.note_submit("t1", 0));
         write_rollout(&root, "2026/07/26", TID, Some("/home/me/project-b"));
         assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
         assert_eq!(locator.armed_count(), 1);
@@ -745,14 +1012,18 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
     }
 
     #[test]
-    fn rollout_without_cwd_field_still_resolves_when_unambiguous() {
+    fn rollout_without_cwd_field_never_binds() {
+        // cwd is REQUIRED (A4 hardening): `SessionMeta.cwd` is non-optional
+        // at codex 0.145.0 and 3,858/3,858 + 500/500 real rollouts carry it.
+        // A no-cwd first line is a foreign shape — accepting it would be
+        // pure attack surface (a location-blind universal candidate).
         let root = unique_temp_dir("no-cwd");
         let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
         write_rollout(&root, "2026/07/26", TID, None);
-        let located = locator.tick(CODEX_WINDOW_MS);
-        assert_eq!(located.len(), 1);
-        assert_eq!(located[0].thread_id, TID);
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
         let _ = std::fs::remove_dir_all(&root);
     }
 
@@ -760,7 +1031,8 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
     fn two_new_rollouts_in_one_window_refuse_to_bind() {
         let root = unique_temp_dir("ambiguous");
         let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
         write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
         write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
         assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
@@ -778,9 +1050,13 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
     fn same_rollout_claimed_by_two_armed_terminals_refuses_both() {
         let root = unique_temp_dir("contested");
         let locator = CodexLocator::new(root.clone());
-        // Two panes, SAME cwd, armed concurrently; ONE new rollout.
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
-        assert!(locator.arm("t2", "codex", true, None, Some("/tmp"), 0));
+        // Two panes, SAME cwd, armed concurrently, submitting in the same
+        // tick; ONE new rollout. The contested-cwd census refuses both
+        // (Pass 2's same-tick claim check remains as defense-in-depth).
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.arm("t2", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        assert!(locator.note_submit("t2", 0));
         write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
         assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
         assert_eq!(locator.armed_count(), 2);
@@ -788,13 +1064,45 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
     }
 
     #[test]
-    fn rollout_written_lazily_after_first_enter_resolves_via_enter_window() {
-        let root = unique_temp_dir("enter");
+    fn staggered_same_cwd_armed_terminals_never_bind_uncontested() {
+        // Cross-tick contested guard (A4 hardening): ambiguity refusal must
+        // not be same-tick-only. While ≥2 ARMED terminals share a normalized
+        // cwd, NO candidate with that cwd binds for any of them — staggered
+        // deadlines must not let pane A grab pane B's rollout uncontested.
+        let root = unique_temp_dir("staggered");
         let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
-        // Spawn window expires with zero candidates → keep watching.
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.arm("t2", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        assert!(locator.note_submit("t2", 5_000));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        // t1's deadline fires alone: contested cwd → refuse.
         assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        // Enter long after the spawn window; rollout appears just after it.
+        // t2's deadline: still contested → refuse.
+        assert!(locator.tick(5_000 + CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 2);
+        // One pane exits (disarm); the survivor re-opens with a fresh Enter
+        // and may now bind — re-evaluation is legitimate once uncontested.
+        locator.disarm("t2");
+        assert!(locator.note_submit("t1", 10_000));
+        let located = locator.tick(10_000 + CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].terminal_id, "t1");
+        assert_eq!(located[0].thread_id, TID);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn zero_candidate_window_keeps_watching_and_later_enter_reopens() {
+        let root = unique_temp_dir("reopen");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        // Window closes with zero candidates → keep watching (stays armed).
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        // A later Enter re-opens; the rollout appears; resolves via the new
+        // Enter-anchored window.
         let enter_at = 10 * CODEX_WINDOW_MS;
         assert!(locator.note_submit("t1", enter_at));
         write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
@@ -808,7 +1116,7 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
     fn mid_turn_enter_never_reopens_a_pending_evaluation() {
         let root = unique_temp_dir("midturn");
         let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
         assert!(locator.note_submit("t1", 100));
         // Second Enter while the first evaluation is still pending: no-op.
         assert!(!locator.note_submit("t1", 200));
@@ -817,9 +1125,14 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
 
     #[test]
     fn non_session_meta_or_malformed_first_line_is_never_a_candidate() {
+        // COMPLETE (newline-terminated) garbage lines are `Probe::Never` —
+        // not pending: codex writes the whole meta line + '\n' in one
+        // write-then-flush, so a complete non-candidate line never becomes
+        // one. (Empty/torn lines are the pending case — see the tests below.)
         let root = unique_temp_dir("badmeta");
         let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
         let dir = root.join("2026/07/26");
         std::fs::create_dir_all(&dir).unwrap();
         std::fs::write(
@@ -833,6 +1146,91 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
         )
         .unwrap();
         assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn empty_first_line_file_is_pending_and_binds_once_meta_lands() {
+        // A3 (validated): codex CREATES the rollout file, then awaits
+        // git-info collection (subprocesses, 5 s timeout each, worst ~10 s)
+        // BEFORE writing the session_meta first line. A deadline scan can
+        // observe the empty file — it must be a re-probed PENDING candidate,
+        // never dropped by a one-shot read.
+        let root = unique_temp_dir("pending");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        let file = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
+        std::fs::write(&file, "").unwrap(); // created, meta not yet written
+        // Deadline scan: pending candidate → bind NOTHING, stay unresolved.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        // Meta line lands (well within grace); the next sweep binds it.
+        // (write_rollout reuses the same filename — same ts, same TID.)
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let located = locator.tick(CODEX_WINDOW_MS + 300);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID);
+        assert_eq!(locator.armed_count(), 0);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn readable_candidate_never_binds_while_another_new_file_is_pending() {
+        // A4 (validated, CRITICAL): the pane's OWN rollout can sit
+        // unreadable in the git-info gap while a FOREIGN same-cwd rollout is
+        // already readable. Pending candidates are BIND-BLOCKING — the
+        // readable file must not win the window.
+        let root = unique_temp_dir("pending-block");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        // Pane's own file: created, first line not yet written.
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        let own = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
+        std::fs::write(&own, "").unwrap();
+        // Foreign file: fully readable, same cwd.
+        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
+        // Deadline: NOTHING binds while the pending file exists.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        // Own meta line lands → TWO candidates → ambiguity refusal (fail
+        // toward refusal, never a guess).
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS + 300).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn pending_file_that_never_parses_expires_after_grace() {
+        // Grace is bounded (A4 hardening 1): once PENDING_FIRST_LINE_GRACE_MS
+        // elapses without a readable first line, the file is permanently
+        // excluded and stops blocking; a surviving sole candidate may then
+        // bind.
+        let root = unique_temp_dir("pending-expiry");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        let own = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
+        std::fs::write(&own, "").unwrap(); // never gains a first line
+        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
+        // First due scan sees the pending file (grace clock starts here).
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // Still blocked just before grace expiry…
+        assert!(locator
+            .tick(CODEX_WINDOW_MS + PENDING_FIRST_LINE_GRACE_MS - 1)
+            .is_empty());
+        // …then the never-parsed file expires and the sole survivor binds.
+        let located = locator.tick(CODEX_WINDOW_MS + PENDING_FIRST_LINE_GRACE_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID2);
         let _ = std::fs::remove_dir_all(&root);
     }
 
@@ -841,7 +1239,9 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
         let base = unique_temp_dir("missing-root");
         let root = base.join("does-not-exist-yet");
         let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        // arm() scans the missing root — tolerated, never a panic.
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
         assert!(locator.tick(CODEX_WINDOW_MS).is_empty()); // no panic, keep watching
         assert_eq!(locator.armed_count(), 1);
         assert!(locator.note_submit("t1", 2 * CODEX_WINDOW_MS));
@@ -857,7 +1257,8 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
         // must too (integration fixtures seed this shape).
         let root = unique_temp_dir("flat");
         let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp"), 0));
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
         write_rollout(&root, ".", TID, Some("/tmp"));
         let located = locator.tick(CODEX_WINDOW_MS);
         assert_eq!(located.len(), 1);
@@ -952,7 +1353,10 @@ pub(crate) async fn adopt_codex_identity(state: &crate::WsState, a: CodexAdoptio
     // replaying a DEAD pane's identity onto a fresh terminal. Copied from
     // candidate guard 3b (codex_candidate.rs:167-186) — keep the exact
     // comparison semantics that code uses today; re-adopting the SAME
-    // terminal is an idempotent allow.
+    // terminal is an idempotent allow. This guard is also a REQUIRED A4
+    // misbind hardening for the locator path: the adoption tail must refuse
+    // a thread id already bound to another terminal (Validated Premise 9),
+    // so it must never be weakened when the candidate channel is deleted.
     if let Some(existing) = state
         .identity
         .find_by_session_including_retired("codex", a.thread_id)
@@ -1128,7 +1532,11 @@ Expected: COMPILE ERROR (module functions and `codex_locator` field missing).
 //! CodexLocator at create, feed Enter submits, and on resolution adopt the
 //! identity through the shared `codex_identity::adopt_codex_identity` tail.
 //! Structure mirrors `opencode_association.rs` — deliberately (spec §5-shape
-//! duplication over a premature provider-generic controller).
+//! duplication over a premature provider-generic controller). One deliberate
+//! deviation: the locator's windows are ENTER-ANCHORED ONLY (no spawn
+//! window) — real codex materializes its rollout only at the first user
+//! prompt, so `maybe_arm` only takes the snapshot and `note_possible_submit`
+//! is what opens a correlation window.
 
 use crate::WsState;
 
@@ -1148,7 +1556,7 @@ pub(crate) fn maybe_arm(
         return;
     }
     if let Some(locator) = &state.codex_locator {
-        locator.arm(terminal_id, mode, true, resume_session_id, cwd, now_ms());
+        locator.arm(terminal_id, mode, true, resume_session_id, cwd);
     }
 }
 
@@ -1226,10 +1634,12 @@ Wiring edits:
 1. `crates/freshell-ws/src/lib.rs`:
    - `pub mod codex_association;` (next to `opencode_association` at `:36`-ish, alphabetical)
    - Add the `codex_locator` field to `WsState` next to `opencode_locator`
-     (~`:242`), doc comment mirroring opencode's ("correlates a fresh codex
-     PTY's spawn/first-Enter with the new rollout JSONL codex writes under the
-     sessions root, so the terminal can be bound and `terminal.rs`'s generic
-     resume derivation can drive `codex resume <id>` on restart").
+     (~`:242`), doc comment mirroring opencode's shape but Enter-anchored
+     ("correlates a fresh codex PTY's first Enter with the new rollout JSONL
+     codex writes under the sessions root — real codex materializes the file
+     only at the first user prompt — so the terminal can be bound and
+     `terminal.rs`'s generic resume derivation can drive `codex resume <id>`
+     on restart").
    - The compiler will enumerate every literal `WsState` constructor that now
      misses the field (association tests, other in-crate tests, main.rs).
      Add `codex_locator: None,` everywhere except the sites Tasks 4-5 say
@@ -1263,14 +1673,40 @@ Wiring edits:
      // codex pane. Restore-created panes WITHOUT identity arm too — arm()
      // gates on resume_session_id, never a restore flag (the wave-A re-arm
      // contract).
-     crate::codex_association::maybe_arm(
-         state,
-         &terminal_id,
-         &mode,
-         resolved_cwd.as_deref(),
-         resume_session_id.as_deref(),
-     );
+     //
+     // ORDERING NOTE (A5, validated): this arm runs AFTER the PTY spawn
+     // (registry.create + adopt() have already awaited above). That is safe
+     // ONLY because windows are Enter-anchored: real codex materializes its
+     // rollout at the first user prompt, never in the spawn→arm gap, so the
+     // snapshot cannot miss the pane's own file. Do not reinterpret this as
+     // "snapshot precedes spawn" — it does not need to.
+     //
+     // The arm() snapshot walks the sessions tree; run it on the blocking
+     // pool, not the WS dispatch path (A6: warm walks are 7-9 ms today and
+     // ~100 ms at 100k files, but cold dentry cache after a reboot is the
+     // one unmeasured tail).
+     {
+         let state = state.clone();
+         let terminal_id = terminal_id.clone();
+         let mode = mode.clone();
+         let cwd = resolved_cwd.clone();
+         let resume = resume_session_id.clone();
+         let _ = tokio::task::spawn_blocking(move || {
+             crate::codex_association::maybe_arm(
+                 &state,
+                 &terminal_id,
+                 &mode,
+                 cwd.as_deref(),
+                 resume.as_deref(),
+             );
+         })
+         .await;
+     }
      ```
+     (Adapt the exact clone set to the local variable types at the call site
+     — the compile-truth is the surrounding function; the requirement is that
+     `maybe_arm` executes on the blocking pool and completes before the
+     create handler returns.)
    - Submit seam — after the opencode `note_possible_submit` (`:542-546`):
      ```rust
      crate::codex_association::note_possible_submit(state, &input.terminal_id, &input.data);
@@ -1339,6 +1775,11 @@ REAL `PaneLedger::new(Some(dir))`. The codex adaptations, per test:
         //   "payload":{"id":"<TID>","cwd":"<the pane's cwd>"}}
         // (reuse the write_rollout shape from codex_locator.rs tests inline).
         //
+        // Then OPEN THE WINDOW: note_possible_submit(&state, "t1", "\r") —
+        // windows are Enter-anchored (no spawn window), so resolution
+        // requires a submit. The 40×100 ms drain poll comfortably covers the
+        // 2 s Enter-anchored deadline.
+        //
         // Poll drain_and_associate until resolution, then assert:
         //   state.identity.session_ref_for("t1") == Some(codex/<TID>)  (provider + id)
         //   registry directory entry for t1: resume_session_id == Some(<TID>)
@@ -1358,7 +1799,9 @@ REAL `PaneLedger::new(Some(dir))`. The codex adaptations, per test:
         // the rollout-file seed above instead of the sqlite row, and provider
         // "codex" in the ledger lookups. Record the pending marker via
         // state.pane_ledger.record_pending("t1", "codex", Some(cwd), now)
-        // before resolution, exactly as the sibling does.
+        // before resolution, exactly as the sibling does. As in the first
+        // test, add note_possible_submit(&state, "t1", "\r") after seeding
+        // the rollout — Enter-anchored windows need the submit.
     }
 
     /// One-writer defense survives the channel swap: a session already bound
@@ -1370,7 +1813,8 @@ REAL `PaneLedger::new(Some(dir))`. The codex adaptations, per test:
         // via state.identity.retire("victim") (the exit-path call —
         // terminal.rs:1370 area shows the exact form).
         // Register a real PTY "t1" (codex mode), arm it, seed the rollout for
-        // <TID>, poll drain_and_associate past the window.
+        // <TID>, note_possible_submit(&state, "t1", "\r") to open the
+        // Enter-anchored window, poll drain_and_associate past the window.
         // Assert: t1 gained NO identity (state.identity.session_ref_for("t1")
         // is None) and its registry entry's resume_session_id is None.
     }
@@ -1452,7 +1896,10 @@ from `codex_candidate_activity.rs::adopted_candidate_identity_reaches_codex_acti
    with first line
    `{"timestamp":"2026-07-24T12:00:00.000Z","type":"session_meta","payload":{"id":"<THREAD>","cwd":"<terminal cwd>"}}`
    — the terminal's cwd is whatever the harness passed to terminal.create;
-   use that same value.
+   use that same value. THEN send a single `terminal.input` of `"\r"` over
+   the socket: windows are Enter-anchored (validated A1 — real codex
+   materializes the rollout only at the first user prompt; there is no spawn
+   window), so the submit is what opens the 2 s evaluation window.
 3. Await `codex.activity.updated` carrying `sessionId == <THREAD>` (the sweep
    runs every 150 ms in the real server; give the await the same generous
    timeout the donor test used).
@@ -1464,12 +1911,12 @@ from `codex_candidate_activity.rs::adopted_candidate_identity_reaches_codex_acti
    locator's `attach_codex_rollout` handed the file to the status watcher and
    completions are stamped.
 
-Note on determinism: the fresh terminal never receives an Enter in this test,
-so resolution rides the SPAWN window — create the rollout file promptly after
-`terminal.created` arrives. If flake appears because the 2 s spawn window
-elapses before the file lands, send a single `terminal.input` of `"\r"` after
-writing the file (Enter re-opens the window — pinned by Task 2's
-`rollout_written_lazily_after_first_enter_resolves_via_enter_window`).
+Note on determinism: resolution REQUIRES the Enter — there is no spawn
+window. Write the rollout file first, then send the `"\r"`; the
+Enter-anchored deadline (2 s later, swept every 150 ms) evaluates and binds.
+If flake appears because of ordering, send another `"\r"` — a later Enter
+re-opens the window (pinned by Task 2's
+`zero_candidate_window_keeps_watching_and_later_enter_reopens`).
 
 - [ ] **Step 2: Run to verify it fails for the right reason**
 
@@ -1591,9 +2038,13 @@ helpers were copied wrong, fix the copy first; the RED must be the adoption.)
 4. `crates/freshell-ws/src/invariants.rs` — update the
    `terminal_identity_unresolved` doc comment (`:39-47` area): the grace
    window (`IDENTITY_RESOLUTION_GRACE_MS = 5 × AMPLIFIER_DIR_APPEAR_WINDOW_MS`
-   = 10 s) now also covers the codex locator (`CODEX_WINDOW_MS` = 2 s — same
-   magnitude, no numeric change); mention that fresh codex panes are expected
-   to resolve via `codex_association` within grace. Doc text only — no logic
+   = 10 s) now also covers the codex locator (`CODEX_WINDOW_MS` = 2 s,
+   Enter-anchored, plus `PENDING_FIRST_LINE_GRACE_MS` = 10 s that applies
+   ONLY in the anomalous empty-first-line gap — no numeric change here);
+   mention that fresh codex panes are expected to resolve via
+   `codex_association` within grace of their first Enter, and that a
+   maximally slow codex git-info gap can legitimately outlast the alarm
+   grace (the alarm is advisory in that case). Doc text only — no logic
    change.
 
 - [ ] **Step 4: Run to GREEN + full-crate regression**
@@ -1797,7 +2248,12 @@ restart-same-port, negative control):
    and `sessionRef.provider === 'codex'`. NO client candidate can exist here:
    the Rust server never emits `terminal.codex.durability.updated`, so the
    frozen client's candidate sender never fires — identity arriving at all IS
-   the server-locator proof. State this in a comment.
+   the server-locator proof. State this in a comment, citing the validated
+   client path (A7): the frozen client applies `terminal.session.associated`
+   provider-generically (`App.tsx:1004-1017` → panesSlice `sessionRef`,
+   `resumeSessionId` cleared), and its conflict guard only drops a push when
+   the pane ALREADY holds a different sessionRef — impossible for fresh panes
+   (the locator arms only unbound panes).
 8. Restart + reload (donor flow). Post-restart positive proofs (BOTH):
    - buffer contains `codex: resumed session <id>`;
    - the argv log's post-restart entries contain the ADJACENT PAIR
@@ -1889,9 +2345,10 @@ then apply this delta):
     //   identity provably cannot resolve pre-kill and the pending marker is
     //   the only evidence.
     // - pane: openCliPane(page, /^Codex CLI$/i), then click the pane's xterm
-    //   and type + Enter (the codex locator marker exists from spawn — codex
-    //   is already in MARKER_MODES — but the typed Enter also opens the
-    //   locator window, making this a true inside-the-window kill).
+    //   and type + Enter (the codex ledger pending marker exists from spawn —
+    //   codex is already in MARKER_MODES — and the typed Enter is what opens
+    //   the locator window at all: windows are Enter-anchored, so this is a
+    //   true inside-the-window kill).
     // - assertions: identical — pending/*.json survives restartAbrupt(),
     //   bindings/ has zero *.json.
   })
@@ -1979,7 +2436,26 @@ git add test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
 git commit -m "test(e2e): flip restore-contract-wall pins now green under the codex server-side locator"
 ```
 
-- [ ] **Step 5: Push the branch and STOP**
+- [ ] **Step 5: One-writer merge-time gate (mechanical, before push)**
+
+Sibling lanes run concurrently; the "one writer per codex identity fact"
+claim must be re-proven against the integration base, not just this
+worktree. After rebasing/merging onto the integration base (and again if the
+base moves before push), run:
+
+```bash
+rg "adopt_codex_identity|ledger_resolve_identity|codex.candidate|session\.associated" crates/ --type rust
+git diff "$(git merge-base origin/main HEAD)"..HEAD -- crates/freshell-ws/src/terminal.rs
+```
+
+Confirm: (a) the only codex identity writers are `codex_identity.rs` /
+`codex_association.rs` and the create-time resume path — no sibling lane
+added another; (b) no sibling lane moved the `terminal.rs` seams this lane
+edited (arm at create, submit seam, exit disarm, retired candidate match
+arm). Investigate ANY unexpected hit BEFORE the final "one writer" commit
+message is written; do not push over an unexplained conflict.
+
+- [ ] **Step 6: Push the branch and STOP**
 
 ```bash
 git log --oneline origin/main..HEAD          # review the task commits
@@ -1995,8 +2471,15 @@ results incl. wall disposition, and the scope-fence note that REST-lane
 ## Self-Review (performed at plan-writing time)
 
 **1. Spec coverage:**
-- Server-side rollout-appear locator, arm at create, correlation window per
-  opencode precedent (spawn window + submit extension) → Tasks 1-2, 4.
+- Server-side rollout-appear locator, arm at create, Enter-anchored
+  correlation windows (Validated Premise 7: real codex materializes the
+  rollout only at the first user prompt — there is no spawn window; arm
+  takes only the snapshot) → Tasks 1-2, 4.
+- Misbind hardenings from the A4 adversarial validation (required cwd,
+  pending-first-line bind-blocking grace, cross-tick contested-cwd refusal,
+  bound-elsewhere adoption refusal) → Tasks 1-3, pinned by Task 2's guard
+  tests and Task 5 test 3; the freshagent same-cwd residual is documented in
+  Validated Premise 10 and named in Task 11's report, not silently absorbed.
 - Reuse-don't-duplicate the wave-2 watcher → Premise Correction 2: discovery
   cannot ride the per-file status watcher (verified structural fact); the
   locator polls only-while-armed and hands the discovered path to the
@@ -2020,11 +2503,14 @@ results incl. wall disposition, and the scope-fence note that REST-lane
 - Re-arm on restore-created identity-less panes → arm() gates on
   resume_session_id only (Task 1 gate test), controller comment (Task 4),
   end-to-end pin (Task 5 test 2).
-- TDD red-first list: locator-resolves-fresh (T1), SIGKILL-inside-window
-  fresh-by-race pending-marker-no-binding (T10 e2e + T5 ledger pins),
-  resolve-after-submit-extension (T2), candidate inert (T7), binding row at
-  resolve (T5), turn.complete carries sessionId (T6). E2E fixture + fresh →
-  no-candidate → restart → `resume <id>` (T8-9). Pin flips (T11).
+- TDD red-first list: locator-resolves-after-first-Enter (T1),
+  no-submit-never-binds (T1), SIGKILL-inside-window fresh-by-race
+  pending-marker-no-binding (T10 e2e + T5 ledger pins), window re-open on a
+  later Enter (T2), no-cwd-never-binds (T2), pending-first-line
+  bind-blocking + grace expiry (T2), staggered contested-cwd refusal (T2),
+  candidate inert (T7), binding row at resolve (T5), turn.complete carries
+  sessionId (T6). E2E fixture + fresh → no-candidate → restart →
+  `resume <id>` (T8-9). Pin flips + one-writer merge gate (T11).
 - Scope fence → Global Constraints + Premise Correction 6 (freshell-freshagent
   untouched; REST-lane arming named in the final report, not silently
   dropped).

From f9edd5db08a102f8ae13b0a63f2fe9ef9a2939c8 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 03:59:12 -0700
Subject: [PATCH 08/87] docs: fix Task 3 import-order invariant to match actual
 main.tsx imports

Fresh-eyes review (iteration 1) found the pinned main-import-order.test.ts
asserted storage-migration is the FIRST import of src/main.tsx, but the
actual first import is React (storage-migration is 4th, after the
side-effect-free react/react-dom/react-redux library imports), so the
test could never pass while Task 3 forbids changing main.tsx.

- main-import-order.test.ts spec now asserts storage-migration is
  imported before the @/store/store and @/App imports (the real
  invariant: it runs before any module that could touch the layout keys)
- D1 prose, the file-structure table, Task 3's files list, the
  boot-state.ts comment block, and the pinned main.tsx comment text no
  longer claim storage-migration is the first import
---
 docs/plans/2026-07-26-recover-my-panes.md | 43 ++++++++++++++---------
 1 file changed, 27 insertions(+), 16 deletions(-)

diff --git a/docs/plans/2026-07-26-recover-my-panes.md b/docs/plans/2026-07-26-recover-my-panes.md
index f255e5caf..c686c66e9 100644
--- a/docs/plans/2026-07-26-recover-my-panes.md
+++ b/docs/plans/2026-07-26-recover-my-panes.md
@@ -22,7 +22,7 @@ Within Option A, per the directive "reuse what serves the UI flow, DELETE what d
 ## Design Decisions
 
 **D1 — Trigger conditions (Principle 4 compliance).** The offer appears iff ALL of:
-1. `localStorage` had NO layout key (`freshell.layout.v3` and `freshell.layout.v3.bak` both absent) **captured at module load**, before the asynchronous writers — the auto-shell-tab (`App.tsx:1423-1427`) and the 500 ms persist debounce — can write one, OR a pending-offer flag from a prior undecided visit is set (see D3). Synchronous module-load writers of `freshell.layout.v3` DO exist (`storage-migration.ts:332/431`, self-executing via `main.tsx`'s first import, and `migrateV2ToV3` at `persistedState.ts:594` during tabsSlice module eval), but each fires only when durable layout data ALREADY existed — so key-presence at boot-state module eval remains the correct "had layout" signal, and the capture design stands. Two invariants are pinned in Task 3: `import '@/store/storage-migration'` stays the FIRST import in `main.tsx` (it re-materializes `freshell.layout.v3` from the `.backup-before-fresh-agent-centralization` key before capture — which is why boot-state checks only v3 + .bak), and `boot-state.ts` is never imported from `main.tsx` above that line.
+1. `localStorage` had NO layout key (`freshell.layout.v3` and `freshell.layout.v3.bak` both absent) **captured at module load**, before the asynchronous writers — the auto-shell-tab (`App.tsx:1423-1427`) and the 500 ms persist debounce — can write one, OR a pending-offer flag from a prior undecided visit is set (see D3). Synchronous module-load writers of `freshell.layout.v3` DO exist (`storage-migration.ts:332/431`, self-executing via `main.tsx`'s side-effect import at `main.tsx:4`, and `migrateV2ToV3` at `persistedState.ts:594` during tabsSlice module eval), but each fires only when durable layout data ALREADY existed — so key-presence at boot-state module eval remains the correct "had layout" signal, and the capture design stands. Two invariants are pinned in Task 3: `import '@/store/storage-migration'` stays ahead of the `@/store/store` and `@/App` imports in `main.tsx` (the only imports above it — react, react-dom/client, react-redux — are pure library imports with no localStorage side effects; storage-migration re-materializes `freshell.layout.v3` from the `.backup-before-fresh-agent-centralization` key before capture — which is why boot-state checks only v3 + .bak), and `boot-state.ts` is never imported from `main.tsx` at all.
 2. `GET /api/recovery/inventory` reports `recoverable: true`.
 3. The inventory `contentId` is not in the dismissed list.
 
@@ -76,7 +76,7 @@ Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.co
 | `crates/freshell-server/src/main.rs` (modify) | `mod recovery_inventory;` + one `.merge(...)` |
 | `crates/freshell-ws/src/terminal.rs` (modify, Task 2b) | Liveness guard on the direct wire-sessionRef rung (D7 defense-in-depth) |
 | `crates/freshell-ws/tests/live_session_ref_guard.rs` (create, Task 2b) | Integration proof: live session + sessionRef create ⇒ loud refusal, no duplicate spawn |
-| `src/main.tsx` (modify, Task 3) | Comment only — pins the storage-migration-first import-order invariant (D1/A8) |
+| `src/main.tsx` (modify, Task 3) | Comment only — pins the storage-migration-before-store/App import-order invariant (D1/A8) |
 | `crates/freshell-server/src/tabs_snapshots.rs` (modify, Task 9) | Restore endpoint deleted; the GET read side (incl. `get_snapshot`) survives |
 | `crates/freshell-server/src/tabs_snapshots_marker.rs`, `tabs_snapshots_create_body.rs` (delete, Task 9) | Server-push machinery — no UI-flow consumer |
 | `crates/freshell-server/src/tabs_snapshots_selectors.rs` (modify, Task 9) | Delete `parse_restore_selection` only; `parse_selector`/`Selector` survive (surviving GET read API) |
@@ -771,7 +771,7 @@ git commit -m "feat(ws): refuse sessionRef restore while a Running terminal owns
 **Files:**
 - Create: `src/lib/recovery/boot-state.ts`
 - Create: `src/lib/recovery/dismissal.ts`
-- Modify: `src/main.tsx` (comment only — pin the import-order invariant on the existing first import; no code change)
+- Modify: `src/main.tsx` (comment only — pin the import-order invariant on the existing `import '@/store/storage-migration'` line (currently `main.tsx:4`, after the react/react-dom/react-redux library imports); no code change)
 - Create: `test/unit/client/lib/recovery/boot-state.test.ts`
 - Create: `test/unit/client/lib/recovery/dismissal.test.ts`
 - Create: `test/unit/client/lib/recovery/main-import-order.test.ts`
@@ -835,12 +835,20 @@ import { readFileSync } from 'node:fs'
 describe('boot-state capture ordering invariants (D1/A8)', () => {
   const src = readFileSync('src/main.tsx', 'utf8')
 
-  it('storage-migration is the FIRST import in main.tsx', () => {
+  it('storage-migration is imported before the store and App in main.tsx', () => {
     // It re-materializes freshell.layout.v3 from the
     // `.backup-before-fresh-agent-centralization` key BEFORE any capture can run —
-    // which is why boot-state checks only v3 + .bak.
-    const firstImport = src.match(/^import .*$/m)?.[0] ?? ''
-    expect(firstImport).toContain('@/store/storage-migration')
+    // which is why boot-state checks only v3 + .bak. The imports above it
+    // (react, react-dom/client, react-redux) are pure library imports with no
+    // localStorage side effects, so "before store/App" is the real invariant.
+    const migrationIdx = src.indexOf("import '@/store/storage-migration'")
+    const storeIdx = src.indexOf("from '@/store/store'")
+    const appIdx = src.indexOf("from '@/App'")
+    expect(migrationIdx).toBeGreaterThan(-1)
+    expect(storeIdx).toBeGreaterThan(-1)
+    expect(appIdx).toBeGreaterThan(-1)
+    expect(migrationIdx).toBeLessThan(storeIdx)
+    expect(migrationIdx).toBeLessThan(appIdx)
   })
 
   it('boot-state is never imported from main.tsx', () => {
@@ -908,13 +916,15 @@ export function computeHadPersistedLayout(storage: Pick<Storage, 'getItem'>): bo
 }
 
 // Captured at module import. Synchronous module-load writers of freshell.layout.v3 DO
-// exist (storage-migration.ts:332/431 — self-executing via main.tsx's FIRST import — and
-// migrateV2ToV3, persistedState.ts:594, during tabsSlice module eval), but each fires only
-// when durable layout data ALREADY existed, so key-presence here remains the correct
-// "had layout" signal. storage-migration also re-materializes freshell.layout.v3 from the
-// `.backup-before-fresh-agent-centralization` key BEFORE this module can load — which is
-// why we check only v3 + .bak. Invariants (pinned by main-import-order.test.ts): the
-// storage-migration import stays FIRST in main.tsx; main.tsx never imports this module.
+// exist (storage-migration.ts:332/431 — self-executing via main.tsx's side-effect import
+// at main.tsx:4 — and migrateV2ToV3, persistedState.ts:594, during tabsSlice module eval),
+// but each fires only when durable layout data ALREADY existed, so key-presence here
+// remains the correct "had layout" signal. storage-migration also re-materializes
+// freshell.layout.v3 from the `.backup-before-fresh-agent-centralization` key BEFORE this
+// module can load — which is why we check only v3 + .bak. Invariants (pinned by
+// main-import-order.test.ts): the storage-migration import stays ahead of the store/App
+// imports in main.tsx (the imports above it are side-effect-free library imports);
+// main.tsx never imports this module.
 // The asynchronous writers (auto shell tab App.tsx:1423-1427, 500ms persist debounce)
 // land long after module eval (see docs/plans/2026-07-26-recover-my-panes.md D1).
 export const hadPersistedLayoutAtBoot: boolean =
@@ -924,8 +934,9 @@ export const hadPersistedLayoutAtBoot: boolean =
 In `src/main.tsx`, add a comment on the existing `import '@/store/storage-migration'` line (no code change):
 
 ```ts
-// MUST stay the FIRST import: recover-my-panes boot-state (D1) depends on migrations
-// having re-materialized freshell.layout.v3 BEFORE any capture runs — see
+// MUST stay ahead of the store/App imports: recover-my-panes boot-state (D1) depends on
+// migrations having re-materialized freshell.layout.v3 BEFORE any capture runs (the
+// react/react-dom/react-redux imports above are side-effect-free) — see
 // docs/plans/2026-07-26-recover-my-panes.md and main-import-order.test.ts.
 ```
 

From 75d99a8db374b5dd666a64c4d93d104c1dc67eb8 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 03:59:29 -0700
Subject: [PATCH 09/87] docs(plan): harden B4 freshagent-verdicts-resume plan
 with load-bearing validation findings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Executed 10 parallel evidence-gathering validators over Lane B4 implementation plan
(fresh-agent verdicts + settings-from-ledger resume). Incorporated validation findings:

1. PaneIdentitySink writes now awaited (durable-before-answer, wave-A policy conformance)
2. G3 supersession linkage written at codex crash-respawn + verdict arm resolves session refs to the supersession-chain terminus
3. SETTINGS_RESET alarm gated to previously-recorded sessions only (no spam for historical/pre-ship sessions, no defaults-laundering refresh writes)
4. restart/resume topology corrected — post-reload the frozen client sends create{resumeSessionId}, so opencode handle_create now honors resume_session_id (the actual P1.13 pin-flip target) and e2e assertions are create-shaped
5. e2e seeding for codex/claude switched from REST (rejects agent≠opencode) to raw WS freshAgent.create
6. opencode fake audit assertions fixed to event==='prompt_async' + fake extended to audit the prompt body
7. codex fake crash staging redesigned to a single static behavior with a crash-once marker knob
8. B1 lane-coexistence hardening (DELETE-AT-MERGE annotation, ProviderUnavailable→Unknown mapping, B1-first merge order, snapshot-built-once)
9. respawn cap reworked to respawn-answers-only with reset-on-live
10. stale client citations fixed + alarm frame shape pinned (top-level sessionType/provider + message)

Plus codex zero-turn/compression caveats and Task 13 harness notes.

Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../2026-07-26-freshagent-verdicts-resume.md  | 999 +++++++++++++-----
 1 file changed, 740 insertions(+), 259 deletions(-)

diff --git a/docs/plans/2026-07-26-freshagent-verdicts-resume.md b/docs/plans/2026-07-26-freshagent-verdicts-resume.md
index c7edff1e1..231eaf697 100644
--- a/docs/plans/2026-07-26-freshagent-verdicts-resume.md
+++ b/docs/plans/2026-07-26-freshagent-verdicts-resume.md
@@ -20,9 +20,10 @@
 - E2E: own `RustServer` instances on ephemeral ports only. NEVER ports 3001/3002. NEVER touch the user's self-hosted server. No broad kill patterns.
 - SCOPE FENCE — do NOT touch: the rest of `crates/freshell-ws/src/reconcile.rs` beyond the single dispatch arm + one `ReconcileDeps` field + inverting the `unsupported_kind` unit test (Lane B1 owns the rest, incl. retry-verdict deletion — a trivial merge conflict at the arm is expected and fine); `crates/freshell-ws/src/existence.rs` (B1; read-only use is fine); codex_candidate/rollout locator (B2); tabs_snapshots + recovery UI (B3); ALL client code (`src/`, ws-client, App.tsx) — client folding of fresh-agent verdicts is the NEXT wave. No kimi/gemini work.
 - `LEDGER_VERSION` stays `1`. All new `BindingRow` fields are `Option` with `skip_serializing_if` — no `deny_unknown_fields`, no required non-defaulted fields.
-- Ledger writes are sync + fsync: async call sites MUST wrap them in `tokio::task::spawn_blocking` (module doc `pane_ledger.rs:34-43`).
+- Ledger writes are sync + fsync: async call sites MUST wrap them in `tokio::task::spawn_blocking` AND `.await` the handle before replying/proceeding — durable-before-answer, the wave-A rule every shipped async write site already follows (`terminal.rs:1589/1613/2252`; module doc `pane_ledger.rs:34-43`). Write failures are never silent warn-and-drop: surface them user-visibly at the call site, then proceed (a failed write never blocks the identity event — campaign §4.2 policy, per V8/A11).
+- B1 COEXISTENCE (V9/A12 — evidence is B1's written plan in worktree `reconcile-client-adoption`; B1 has NO code commits yet): B1 will DELETE `ReconcileVerdict::Retry` + `PaneVerdict.retry_after_ms` and ADD `SessionExistence::ProviderUnavailable`; both lanes edit `handle_pane_reconcile`. Hardening rules for this lane: keep exactly ONE `PaneVerdict` construction point in `reconcile_freshagent.rs` (`base()`), with its `retry_after_ms: None` line annotated `// DELETE-AT-MERGE: B1 removes this field`; NEVER construct/match `ReconcileVerdict::Retry` or assert `retryAfterMs` in any B4 test; keep every `SessionExistence` match exhaustive (no catch-all) with the pre-decided merge mapping `SessionExistence::ProviderUnavailable => FreshAgentPresence::Unknown`; the fresh-agent snapshot is built ONCE per reconcile request and REUSED if deps are re-derived (B1's warming deferral re-derives via `rebuild_deps` — rebuilding the snapshot would double-burn the respawn counter). Merge order: B1 lands first, B4 rebases (expected fixes: one field line + one match arm + one `fresh_agent` field in B1's `rebuild_deps`).
 - TypeScript (e2e specs): NodeNext/ESM — relative imports include `.js` where the repo convention requires (spec files follow the sibling specs' import style).
-- Alarm/degradation frames use `freshAgent.error` event codes that are NOT `INVALID_SESSION_ID` and do NOT start with `RESTORE_` (that combination renders the persistent amber `role="alert"` banner in today's frozen client, `src/lib/fresh-agent-ws.ts:307-318` → `FreshAgentView.tsx:2046`).
+- Alarm/degradation frames use `freshAgent.error` event codes that are NOT `INVALID_SESSION_ID` (that code dispatches `markSessionLost`, not the banner) and do NOT start with `RESTORE_` (RESTORE_-prefixed codes ALSO render the banner but additionally trip the client's restore-failure state — wrong semantics for our alarms; V1/A1). Frozen-client chain (verified, V1): `src/lib/fresh-agent-ws.ts:325-335` → `src/store/freshAgentSlice.ts:444` (`lastError`, set unconditionally, never cleared by any reducer) → `src/components/fresh-agent/FreshAgentView.tsx:1700/2046` → `FreshAgentApprovalBanner` (amber, `role="alert"`). Every alarm frame MUST carry top-level `sessionType` + `provider` (locator resolution, V1/A2) and a user-facing `message` (the banner shows the message, never the code; code-only frames render "Agent error: Unknown error"). The banner is in-memory Redux state: it does NOT survive page reload — e2e must assert before any reload.
 - PR POLICY: NOT approved. Push the branch, STOP before `gh pr create`.
 - ~78GB disk free — halt on ENOSPC.
 - Reference (read-only context, do not commit): campaign plan at `/home/dan/code/freshell/docs/plans/2026-07-24-restart-resilience-architecture-analysis.md` (untracked, absolute path).
@@ -33,20 +34,21 @@
 
 | File | Change | Responsibility |
 |---|---|---|
-| `crates/freshell-ws/src/pane_ledger.rs` | Modify | `BindingRow` optional resume-settings fields; `FreshAgentBindingWrite` + `record_fresh_agent_binding` upsert |
-| `crates/freshell-freshagent/src/identity_sink.rs` | Create | `PaneIdentitySink` trait, `FreshAgentSettings`, `FreshAgentBindingUpsert`, `FakeIdentitySink` (cfg(test)) |
-| `crates/freshell-freshagent/src/lib.rs` | Modify | `pub mod identity_sink;` + re-exports |
-| `crates/freshell-freshagent/src/codex.rs` | Modify | sink field/setter; ledger writes at identity events; settings-from-ledger on R1/R2/R3; degradation frame |
-| `crates/freshell-freshagent/src/opencode_ws.rs` | Modify | sink field/setter; pending + binding writes; settings-from-ledger resume |
+| `crates/freshell-ws/src/pane_ledger.rs` | Modify | `BindingRow` optional resume-settings fields; `FreshAgentBindingWrite` (incl. `supersedes`) + `record_fresh_agent_binding` upsert with G3 supersession retire |
+| `crates/freshell-freshagent/src/identity_sink.rs` | Create | `PaneIdentitySink` trait (awaited writes), `FreshAgentSettings`, `FreshAgentBindingUpsert`, `FakeIdentitySink` (cfg(test)) |
+| `crates/freshell-freshagent/src/lib.rs` | Modify | `pub mod identity_sink;` + re-exports; `FreshAgentState` sink field/setter; REST send-keys materialization binding write |
+| `crates/freshell-freshagent/src/codex.rs` | Modify | sink field/setter; awaited ledger writes at identity events (crash-respawn supersedes); `emit_fresh_agent_error`; settings-from-ledger on R1/R2/R3; degradation frame |
+| `crates/freshell-freshagent/src/opencode_ws.rs` | Modify | sink field/setter; pending + binding writes; `handle_create` honors `resumeSessionId`; settings-from-ledger resume |
 | `crates/freshell-freshagent/src/claude.rs` | Modify | sink field/setter; binding write at `sdk.session.init`; settings-from-ledger resume |
-| `crates/freshell-server/src/identity_sink.rs` | Create | `LedgerIdentitySink: PaneIdentitySink` over `Arc<PaneLedger>` |
-| `crates/freshell-server/src/main.rs` | Modify | construct + inject the sink into the three states |
-| `crates/freshell-ws/src/reconcile_freshagent.rs` | Create | snapshot types, async snapshot builder, pure verdict mapping, respawn cap, dedupe |
+| `crates/freshell-server/src/identity_sink.rs` | Create | `LedgerIdentitySink: PaneIdentitySink` over `Arc<PaneLedger>` (awaited spawn_blocking writes) |
+| `crates/freshell-server/src/main.rs` | Modify | construct + inject the sink into the three provider states + `FreshAgentState` (REST surface) |
+| `crates/freshell-ws/src/reconcile_freshagent.rs` | Create | snapshot types, async snapshot builder (supersession-chain resolution, respawn cap w/ reset-on-live), pure verdict mapping, dedupe |
 | `crates/freshell-ws/src/reconcile.rs` | Modify (minimal) | one `ReconcileDeps` field + one match arm + invert one unit test |
 | `crates/freshell-ws/src/lib.rs` | Modify | `mod reconcile_freshagent;`, `paneReconcileFreshAgentV1` capability parse/echo, `WsState.fresh_agent_respawn_counts` |
 | `crates/freshell-ws/src/terminal.rs` | Modify | thread capability bool; build fresh-agent snapshot in `handle_pane_reconcile` |
 | `crates/freshell-ws/tests/pane_reconcile_freshagent.rs` | Create | direct-WS integration tests for the fresh-agent arm |
-| `test/e2e-browser/fixtures/coding-cli/…/fake-app-server.mjs` (`test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs`) | Modify | crash-on-marker behavior knob |
+| `test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs` | Modify | `crashOnPromptMarker` + cross-process once-marker knob (crash ONCE, exit 1) |
+| `test/e2e-browser/fixtures/fake-opencode.cjs` | Modify | audit the parsed `prompt_async` body (model/effort) — today it is discarded (V4) |
 | `test/e2e-browser/specs/freshagent-settings-resume-rust.spec.ts` | Create | per-provider settings-survive-restart + codex degradation banner |
 | `test/e2e-browser/playwright.config.ts` | Modify | register new spec in `RUST_ONLY_SPECS` + `rust-chromium` `testMatch` |
 | `test/e2e-browser/specs/restore-contract-wall-rust.spec.ts` | Modify | flip/narrow the P1.13 freshopencode pin |
@@ -63,8 +65,8 @@
 - Consumes: existing `BindingRow`, `RowState`, `PaneLedger` internals (`record_binding` at `pane_ledger.rs:315` is the structural donor).
 - Produces (later tasks rely on these EXACT names):
   - `BindingRow` new pub fields: `pane_kind: Option<String>`, `model: Option<String>`, `sandbox: Option<String>`, `permission_mode: Option<String>`, `effort: Option<String>` (serde camelCase: `paneKind`, `model`, `sandbox`, `permissionMode`, `effort`).
-  - `pub struct FreshAgentBindingWrite<'a>` (fields below).
-  - `pub fn PaneLedger::record_fresh_agent_binding(&self, w: &FreshAgentBindingWrite<'_>) -> std::io::Result<()>`.
+  - `pub struct FreshAgentBindingWrite<'a>` (fields below, incl. `supersedes: Option<&'a str>` — the OLD session id this binding replaces; G3 supersession per V8/A14).
+  - `pub fn PaneLedger::record_fresh_agent_binding(&self, w: &FreshAgentBindingWrite<'_>) -> std::io::Result<()>` — upsert + (when `supersedes` is Some) retire-and-link of the old row.
 
 - [ ] **Step 1: Write the failing tests**
 
@@ -85,6 +87,7 @@ fn fresh_agent_binding_roundtrips_settings_and_pane_kind() {
             sandbox: Some("workspace-write"),
             permission_mode: Some("on-request"),
             effort: Some("high"),
+            supersedes: None,
             now_ms: 1_000,
         })
         .unwrap();
@@ -111,6 +114,7 @@ fn fresh_agent_binding_upsert_preserves_created_at_and_refreshes_settings() {
         sandbox: None,
         permission_mode: None,
         effort: Some("low"),
+        supersedes: None,
         now_ms: 1_000,
     };
     ledger.record_fresh_agent_binding(&base).unwrap();
@@ -124,6 +128,49 @@ fn fresh_agent_binding_upsert_preserves_created_at_and_refreshes_settings() {
     assert_eq!(row.effort, None, "settings are a full snapshot, not a merge");
 }
 
+#[test]
+fn supersedes_retires_the_old_row_and_links_the_chain() {
+    // G3 supersession (V8/A14): codex crash-respawn must retire the OLD
+    // thread row and link it to the new one — never leave two Bound rows.
+    let (ledger, _tmp) = test_ledger();
+    let base = FreshAgentBindingWrite {
+        provider: "codex",
+        session_id: "old-thread",
+        mode: "freshcodex",
+        cwd: Some("/w"),
+        create_request_id: None,
+        model: Some("m"),
+        sandbox: None,
+        permission_mode: None,
+        effort: None,
+        supersedes: None,
+        now_ms: 1_000,
+    };
+    ledger.record_fresh_agent_binding(&base).unwrap();
+    ledger
+        .record_fresh_agent_binding(&FreshAgentBindingWrite {
+            session_id: "new-thread",
+            supersedes: Some("old-thread"),
+            now_ms: 2_000,
+            ..base
+        })
+        .unwrap();
+    let old = ledger.load_binding("codex", "old-thread").expect("old row kept");
+    assert_eq!(old.state, RowState::Retired, "old row retired, never left Bound");
+    assert_eq!(
+        old.superseded_by.as_ref().map(|l| l.session_id.as_str()),
+        Some("new-thread"),
+        "supersededBy links old → new"
+    );
+    let res = ledger.lookup_by_session("codex", "old-thread").expect("chain resolves");
+    assert!(res.corrected, "claiming the old id is a corrected resolution");
+    assert_eq!(res.row.session_id, "new-thread", "resolution lands at the terminus");
+}
+// (Match the EXACT `RowState`/`RetiredReason` variant names and `Resolution`
+// field names from pane_ledger.rs:107-148 / :450-484 — verify at implementation;
+// the retire semantics donor is record_binding_locked's supersession block at
+// pane_ledger.rs:372-388.)
+
 #[test]
 fn old_terminal_rows_without_settings_fields_still_deserialize() {
     // A wave-A row serialized before this change has none of the new fields.
@@ -182,6 +229,10 @@ pub struct FreshAgentBindingWrite<'a> {
     pub sandbox: Option<&'a str>,
     pub permission_mode: Option<&'a str>,
     pub effort: Option<&'a str>,
+    /// G3 supersession (V8/A14): the OLD session id this binding replaces
+    /// (codex crash-respawn). When `Some`, the old `(provider, supersedes)`
+    /// row is retired and linked AFTER the new row persists.
+    pub supersedes: Option<&'a str>,
     pub now_ms: i64,
 }
 ```
@@ -190,6 +241,8 @@ pub struct FreshAgentBindingWrite<'a> {
 - Upsert keyed `(provider, session_id)`: if a row exists, keep its `created_at`; otherwise `created_at = w.now_ms`.
 - Always set: `state: RowState::Bound`, `retired_reason: None`, `pane_kind: Some("fresh-agent".into())`, `updated_at = w.now_ms`, `last_observed_at = w.now_ms`, `live_terminal_id: None` (fresh-agent panes have no terminal), full settings snapshot from `w` (`model/sandbox/permission_mode/effort/cwd`), `create_request_id` from `w` (preserve the existing row's value when `w.create_request_id` is `None`), `superseded_by: None`.
 
+(d) Supersession (G3, V8/A14): when `w.supersedes` is `Some(old)` and `old != w.session_id`, AFTER the new Bound row is persisted (G3 order pinned: write the new bound row FIRST, then retire the old), retire the old `(provider, old)` row exactly as `record_binding_locked`'s supersession block does at `pane_ledger.rs:372-388` — `state: Retired`, `retired_reason: Superseded`, `superseded_by: Some(SessionLocator { provider, session_id: <new id> })`, persisted through the same row-persist helper. A missing old row is a silent no-op. Do this inside the same locked section as the upsert. (Readers: `load_binding` is state-agnostic so the retired row keeps serving settings; `lookup_by_session` at `pane_ledger.rs:450-484` follows the chain — the verdict arm consumes it in Task 13.)
+
 - [ ] **Step 4: Run tests to verify they pass**
 
 Run: `cargo test -p freshell-ws pane_ledger`
@@ -209,7 +262,7 @@ git commit -m "feat(ledger): resume-invocation record fields + fresh-agent bindi
 
 **Files:**
 - Create: `crates/freshell-freshagent/src/identity_sink.rs`
-- Modify: `crates/freshell-freshagent/src/lib.rs` (module decl + re-export)
+- Modify: `crates/freshell-freshagent/src/lib.rs` (module decl + re-export; `FreshAgentState` field + setter — the opencode REST surface state also needs the sink, see Task 7's REST materialization site)
 - Modify: `crates/freshell-freshagent/src/codex.rs`, `crates/freshell-freshagent/src/opencode_ws.rs`, `crates/freshell-freshagent/src/claude.rs` (field + setter only in this task)
 - Test: `#[cfg(test)]` in `identity_sink.rs`
 
@@ -218,6 +271,12 @@ git commit -m "feat(ledger): resume-invocation record fields + fresh-agent bindi
 - Produces (exact, used by Tasks 3-10):
 
 ```rust
+/// Write-completion future. Boxed-future trait methods are this repo's
+/// established dyn-compatible async-trait style (`BoxFuture` aliases at
+/// freshell-opencode/src/serve.rs:44 and freshell-codex/src/app_server.rs:62);
+/// the workspace has NO `async-trait` dependency — do not add one.
+pub type SinkWrite = std::pin::Pin<Box<dyn std::future::Future<Output = std::io::Result<()>> + Send + 'static>>;
+
 pub struct FreshAgentSettings {
     pub model: Option<String>,
     pub sandbox: Option<String>,
@@ -231,15 +290,25 @@ pub struct FreshAgentBindingUpsert {
     pub mode: String,
     pub create_request_id: Option<String>,
     pub resolves_pending: Option<String>,
+    /// G3 supersession (V8/A14): OLD session id this binding replaces
+    /// (codex crash-respawn passes the old thread id; everyone else None).
+    pub supersedes: Option<String>,
     pub settings: FreshAgentSettings,
 }
 pub trait PaneIdentitySink: Send + Sync {
-    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>);
-    fn record_binding(&self, upsert: FreshAgentBindingUpsert);
+    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>) -> SinkWrite;
+    fn record_binding(&self, upsert: FreshAgentBindingUpsert) -> SinkWrite;
     fn load_settings(&self, provider: &str, session_id: &str) -> Option<FreshAgentSettings>;
+    /// True iff a fresh-agent binding row was EVER recorded for this key —
+    /// the SETTINGS_RESET alarm gate (V7/A10): alarm only when the ledger
+    /// proves prior recording; never for never-recorded sessions.
+    fn was_recorded(&self, provider: &str, session_id: &str) -> bool;
 }
 ```
-- Produces on each of `FreshCodexState`, `FreshOpencodeState`, `FreshClaudeState`:
+
+WRITE CONTRACT (V8/A11 — conforms to wave-A's durable-before-answer policy): callers `.await` the returned future BEFORE replying/broadcasting/proceeding past the identity event. Implementations run the fsync work on `spawn_blocking` and propagate failures as `Err` — never swallow them. All planned call sites (Tasks 4-10) are in async contexts (verified by V8: codex `codex.rs:462/:565/:1064/:1283/:1675`; opencode REST send + WS `handle_send`; claude's async consumer task), so awaiting is always legal.
+
+- Produces on each of `FreshCodexState`, `FreshOpencodeState`, `FreshClaudeState`, AND `FreshAgentState` (the opencode REST surface in `lib.rs` — its send-keys materialization is an identity event, Task 7):
   - `pub fn set_identity_sink(&self, sink: std::sync::Arc<dyn PaneIdentitySink>)`
   - private `fn identity_sink(&self) -> Option<std::sync::Arc<dyn PaneIdentitySink>>`
 
@@ -253,16 +322,19 @@ mod tests {
     use super::*;
     use std::sync::Arc;
 
-    #[test]
-    fn fake_sink_records_and_serves_settings() {
+    #[tokio::test]
+    async fn fake_sink_records_and_serves_settings() {
         let fake = Arc::new(FakeIdentitySink::default());
-        fake.record_pending("freshopencode-r1", "freshopencode", Some("/w"));
+        fake.record_pending("freshopencode-r1", "freshopencode", Some("/w"))
+            .await
+            .expect("pending write ok");
         fake.record_binding(FreshAgentBindingUpsert {
             provider: "opencode".into(),
             session_id: "ses_1".into(),
             mode: "freshopencode".into(),
             create_request_id: Some("r1".into()),
             resolves_pending: Some("freshopencode-r1".into()),
+            supersedes: None,
             settings: FreshAgentSettings {
                 model: Some("m".into()),
                 sandbox: None,
@@ -270,13 +342,27 @@ mod tests {
                 effort: Some("low".into()),
                 cwd: Some("/w".into()),
             },
-        });
+        })
+        .await
+        .expect("binding write ok");
         let s = fake.load_settings("opencode", "ses_1").expect("settings");
         assert_eq!(s.model.as_deref(), Some("m"));
         assert_eq!(s.effort.as_deref(), Some("low"));
         assert_eq!(fake.pendings.lock().unwrap().len(), 1);
         assert_eq!(fake.bindings.lock().unwrap().len(), 1);
         assert!(fake.load_settings("opencode", "nope").is_none());
+        assert!(fake.was_recorded("opencode", "ses_1"));
+        assert!(!fake.was_recorded("opencode", "nope"));
+    }
+
+    #[tokio::test]
+    async fn fake_sink_failure_knob_returns_err() {
+        let fake = Arc::new(FakeIdentitySink::default());
+        fake.fail_writes.store(true, std::sync::atomic::Ordering::SeqCst);
+        assert!(fake
+            .record_pending("p", "freshopencode", None)
+            .await
+            .is_err(), "failure must surface as Err, never be swallowed");
     }
 }
 ```
@@ -322,53 +408,95 @@ pub struct FreshAgentBindingUpsert {
     pub settings: FreshAgentSettings,
 }
 
-/// Fire-and-forget writes (implementations must not block the caller;
-/// ledger fsync work belongs on `spawn_blocking`), memory-fast reads.
+/// Write-completion future (see Interfaces block for the style citation:
+/// BoxFuture aliases at freshell-opencode/src/serve.rs:44 /
+/// freshell-codex/src/app_server.rs:62; no async-trait dep in the workspace).
+pub type SinkWrite =
+    std::pin::Pin<Box<dyn std::future::Future<Output = std::io::Result<()>> + Send + 'static>>;
+
+/// AWAITED writes (wave-A durable-before-answer policy, V8/A11): callers
+/// `.await` the returned future before replying/broadcasting/proceeding.
+/// Implementations run fsync work on `spawn_blocking` and propagate failures
+/// as `Err` — call sites surface them user-visibly, then proceed (a write
+/// failure never blocks the identity event). Reads are memory-fast + sync.
 pub trait PaneIdentitySink: Send + Sync {
-    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>);
-    fn record_binding(&self, upsert: FreshAgentBindingUpsert);
+    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>) -> SinkWrite;
+    fn record_binding(&self, upsert: FreshAgentBindingUpsert) -> SinkWrite;
     fn load_settings(&self, provider: &str, session_id: &str) -> Option<FreshAgentSettings>;
+    fn was_recorded(&self, provider: &str, session_id: &str) -> bool;
 }
 
 pub type SharedPaneIdentitySink = Arc<dyn PaneIdentitySink>;
 
-/// In-memory sink for tests, crate-wide.
+/// In-memory sink for tests, crate-wide. Mutations happen synchronously
+/// before the (already-completed) future is returned, so tests can assert
+/// immediately after `.await`.
 #[cfg(test)]
 #[derive(Default)]
 pub(crate) struct FakeIdentitySink {
     pub pendings: std::sync::Mutex<Vec<(String, String, Option<String>)>>,
     pub bindings: std::sync::Mutex<Vec<FreshAgentBindingUpsert>>,
     pub settings: std::sync::Mutex<std::collections::HashMap<(String, String), FreshAgentSettings>>,
+    /// Keys ever recorded (or seeded) — backs `was_recorded`.
+    pub recorded: std::sync::Mutex<std::collections::HashSet<(String, String)>>,
+    /// When true, write futures resolve to Err — for failure-surfacing tests.
+    pub fail_writes: std::sync::atomic::AtomicBool,
 }
 
 #[cfg(test)]
 impl FakeIdentitySink {
     pub fn seed(&self, provider: &str, session_id: &str, s: FreshAgentSettings) {
+        self.recorded.lock().unwrap().insert((provider.into(), session_id.into()));
         self.settings.lock().unwrap().insert((provider.into(), session_id.into()), s);
     }
+    /// Mark a key as previously recorded WITHOUT a recoverable snapshot —
+    /// the SETTINGS_RESET-alarm-positive fixture (V7/A10 gating).
+    pub fn seed_recorded_only(&self, provider: &str, session_id: &str) {
+        self.recorded.lock().unwrap().insert((provider.into(), session_id.into()));
+    }
+    fn write_result(&self) -> SinkWrite {
+        if self.fail_writes.load(std::sync::atomic::Ordering::SeqCst) {
+            Box::pin(std::future::ready(Err(std::io::Error::other("fake write failure"))))
+        } else {
+            Box::pin(std::future::ready(Ok(())))
+        }
+    }
 }
 
 #[cfg(test)]
 impl PaneIdentitySink for FakeIdentitySink {
-    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>) {
-        self.pendings.lock().unwrap().push((placeholder_id.into(), mode.into(), cwd.map(Into::into)));
+    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>) -> SinkWrite {
+        if !self.fail_writes.load(std::sync::atomic::Ordering::SeqCst) {
+            self.pendings.lock().unwrap().push((placeholder_id.into(), mode.into(), cwd.map(Into::into)));
+        }
+        self.write_result()
     }
-    fn record_binding(&self, upsert: FreshAgentBindingUpsert) {
-        self.settings
-            .lock()
-            .unwrap()
-            .insert((upsert.provider.clone(), upsert.session_id.clone()), upsert.settings.clone());
-        self.bindings.lock().unwrap().push(upsert);
+    fn record_binding(&self, upsert: FreshAgentBindingUpsert) -> SinkWrite {
+        if !self.fail_writes.load(std::sync::atomic::Ordering::SeqCst) {
+            self.recorded
+                .lock()
+                .unwrap()
+                .insert((upsert.provider.clone(), upsert.session_id.clone()));
+            self.settings
+                .lock()
+                .unwrap()
+                .insert((upsert.provider.clone(), upsert.session_id.clone()), upsert.settings.clone());
+            self.bindings.lock().unwrap().push(upsert);
+        }
+        self.write_result()
     }
     fn load_settings(&self, provider: &str, session_id: &str) -> Option<FreshAgentSettings> {
         self.settings.lock().unwrap().get(&(provider.into(), session_id.into())).cloned()
     }
+    fn was_recorded(&self, provider: &str, session_id: &str) -> bool {
+        self.recorded.lock().unwrap().contains(&(provider.into(), session_id.into()))
+    }
 }
 ```
 
-In `lib.rs`: `pub mod identity_sink;` and `pub use identity_sink::{FreshAgentBindingUpsert, FreshAgentSettings, PaneIdentitySink, SharedPaneIdentitySink};`
+In `lib.rs`: `pub mod identity_sink;` and `pub use identity_sink::{FreshAgentBindingUpsert, FreshAgentSettings, PaneIdentitySink, SharedPaneIdentitySink, SinkWrite};`
 
-On EACH of the three states (`FreshCodexState`, `FreshOpencodeState`, `FreshClaudeState`) add a clone-shared, set-once field (states are cloned into consumer tasks, so the `OnceLock` must sit behind an `Arc`):
+On EACH of the four states (`FreshCodexState`, `FreshOpencodeState`, `FreshClaudeState`, and `FreshAgentState` in `lib.rs` — the opencode REST surface, whose materialization site Task 7 instruments) add a clone-shared, set-once field (states are cloned into consumer tasks, so the `OnceLock` must sit behind an `Arc`):
 
 ```rust
 identity_sink: std::sync::Arc<std::sync::OnceLock<SharedPaneIdentitySink>>,
@@ -412,8 +540,8 @@ git commit -m "feat(freshagent): PaneIdentitySink trait - crate-boundary bridge
 - Test: `#[cfg(test)]` in `crates/freshell-server/src/identity_sink.rs`
 
 **Interfaces:**
-- Consumes: `PaneLedger::{record_pending, record_fresh_agent_binding, delete_pending, load_binding}` (Task 1), `freshell_freshagent::{PaneIdentitySink, FreshAgentBindingUpsert, FreshAgentSettings}` (Task 2).
-- Produces: `pub struct LedgerIdentitySink; pub fn LedgerIdentitySink::new(ledger: Arc<PaneLedger>) -> Self`.
+- Consumes: `PaneLedger::{record_pending, record_fresh_agent_binding, delete_pending, load_binding}` (Task 1), `freshell_freshagent::{PaneIdentitySink, FreshAgentBindingUpsert, FreshAgentSettings, SinkWrite}` (Task 2).
+- Produces: `pub struct LedgerIdentitySink; pub fn LedgerIdentitySink::new(ledger: Arc<PaneLedger>) -> Self`. Writes are AWAITED `spawn_blocking` (durable-before-answer, V8/A11) — the returned future completes only after the fsync, and failures come back as `Err`.
 
 - [ ] **Step 1: Write the failing test**
 
@@ -425,7 +553,6 @@ mod tests {
     use super::*;
     use freshell_freshagent::{FreshAgentBindingUpsert, FreshAgentSettings, PaneIdentitySink};
     use std::sync::Arc;
-    use std::time::Duration;
 
     #[tokio::test(flavor = "multi_thread")]
     async fn writes_through_to_ledger_and_reads_back() {
@@ -438,6 +565,7 @@ mod tests {
             mode: "freshcodex".into(),
             create_request_id: None,
             resolves_pending: None,
+            supersedes: None,
             settings: FreshAgentSettings {
                 model: Some("gpt-5.3-codex".into()),
                 sandbox: Some("workspace-write".into()),
@@ -445,16 +573,15 @@ mod tests {
                 effort: None,
                 cwd: Some("/w".into()),
             },
-        });
-        // record_binding is fire-and-forget via spawn_blocking: poll.
-        let mut got = None;
-        for _ in 0..50 {
-            if let Some(s) = sink.load_settings("codex", "t1") { got = Some(s); break; }
-            tokio::time::sleep(Duration::from_millis(20)).await;
-        }
-        let s = got.expect("binding visible within 1s");
+        })
+        .await
+        .expect("awaited write succeeds");
+        // Awaited write => durable and readable IMMEDIATELY, no polling.
+        let s = sink.load_settings("codex", "t1").expect("binding visible after await");
         assert_eq!(s.model.as_deref(), Some("gpt-5.3-codex"));
         assert_eq!(s.sandbox.as_deref(), Some("workspace-write"));
+        assert!(sink.was_recorded("codex", "t1"));
+        assert!(!sink.was_recorded("codex", "nope"));
         let row = ledger.load_binding("codex", "t1").unwrap();
         assert_eq!(row.pane_kind.as_deref(), Some("fresh-agent"));
     }
@@ -477,7 +604,7 @@ Expected: COMPILE ERROR (module/type not defined).
 //! freshell-freshagent cannot see the ledger (crate cycle), so main.rs
 //! injects this adapter at wiring time.
 
-use freshell_freshagent::{FreshAgentBindingUpsert, FreshAgentSettings, PaneIdentitySink};
+use freshell_freshagent::{FreshAgentBindingUpsert, FreshAgentSettings, PaneIdentitySink, SinkWrite};
 use freshell_ws::pane_ledger::{FreshAgentBindingWrite, PaneLedger};
 use std::sync::Arc;
 
@@ -501,53 +628,84 @@ fn now_ms() -> i64 {
 }
 
 impl PaneIdentitySink for LedgerIdentitySink {
-    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>) {
+    // Writes are AWAITED spawn_blocking (durable-before-answer, V8/A11) —
+    // exactly the shape terminal.rs:1589 already ships. Timestamps are taken
+    // at EVENT time (before the hop), so `updated_at` reflects event order
+    // (V8's out-of-order aggravator).
+    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>) -> SinkWrite {
         let ledger = self.ledger.clone();
         let (p, m, c) = (placeholder_id.to_string(), mode.to_string(), cwd.map(str::to_string));
-        tokio::task::spawn_blocking(move || {
-            if let Err(e) = ledger.record_pending(&p, &m, c.as_deref(), now_ms()) {
-                tracing::warn!(error = %e, placeholder = %p, "pane_ledger.fresh_agent.pending_write_failed");
-            }
-        });
+        let now = now_ms();
+        Box::pin(async move {
+            tokio::task::spawn_blocking(move || ledger.record_pending(&p, &m, c.as_deref(), now))
+                .await
+                .map_err(std::io::Error::other)? // JoinError (incl. closure panic) surfaces as Err
+        })
     }
 
-    fn record_binding(&self, upsert: FreshAgentBindingUpsert) {
+    fn record_binding(&self, upsert: FreshAgentBindingUpsert) -> SinkWrite {
         let ledger = self.ledger.clone();
-        tokio::task::spawn_blocking(move || {
-            let w = FreshAgentBindingWrite {
-                provider: &upsert.provider,
-                session_id: &upsert.session_id,
-                mode: &upsert.mode,
-                cwd: upsert.settings.cwd.as_deref(),
-                create_request_id: upsert.create_request_id.as_deref(),
-                model: upsert.settings.model.as_deref(),
-                sandbox: upsert.settings.sandbox.as_deref(),
-                permission_mode: upsert.settings.permission_mode.as_deref(),
-                effort: upsert.settings.effort.as_deref(),
-                now_ms: now_ms(),
-            };
-            if let Err(e) = ledger.record_fresh_agent_binding(&w) {
-                tracing::warn!(error = %e, provider = %upsert.provider, session = %upsert.session_id,
-                    "pane_ledger.fresh_agent.binding_write_failed");
-            }
-            if let Some(p) = upsert.resolves_pending.as_deref() {
-                if let Err(e) = ledger.delete_pending(p) {
-                    tracing::warn!(error = %e, placeholder = %p, "pane_ledger.fresh_agent.pending_delete_failed");
+        let now = now_ms();
+        Box::pin(async move {
+            tokio::task::spawn_blocking(move || {
+                let w = FreshAgentBindingWrite {
+                    provider: &upsert.provider,
+                    session_id: &upsert.session_id,
+                    mode: &upsert.mode,
+                    cwd: upsert.settings.cwd.as_deref(),
+                    create_request_id: upsert.create_request_id.as_deref(),
+                    model: upsert.settings.model.as_deref(),
+                    sandbox: upsert.settings.sandbox.as_deref(),
+                    permission_mode: upsert.settings.permission_mode.as_deref(),
+                    effort: upsert.settings.effort.as_deref(),
+                    supersedes: upsert.supersedes.as_deref(),
+                    now_ms: now,
+                };
+                ledger.record_fresh_agent_binding(&w)?; // binding-write failure propagates
+                if let Some(p) = upsert.resolves_pending.as_deref() {
+                    // Cosmetic on failure: an orphaned marker is TTL-swept at 30d
+                    // (V6/A15) — warn, do not fail the identity event over it.
+                    if let Err(e) = ledger.delete_pending(p) {
+                        tracing::warn!(error = %e, placeholder = %p, "pane_ledger.fresh_agent.pending_delete_failed");
+                    }
                 }
-            }
-        });
+                Ok(())
+            })
+            .await
+            .map_err(std::io::Error::other)?
+        })
     }
 
     fn load_settings(&self, provider: &str, session_id: &str) -> Option<FreshAgentSettings> {
         // Reads are memory-only against the write-through index — safe inline.
         let row = self.ledger.load_binding(provider, session_id)?;
-        Some(FreshAgentSettings {
+        // Terminal-lineage rows (wave-A codex_candidate etc.) are NOT resume
+        // records — only fresh-agent rows serve settings (V7/A10 gating).
+        if row.pane_kind.as_deref() != Some("fresh-agent") {
+            return None;
+        }
+        let s = FreshAgentSettings {
             model: row.model,
             sandbox: row.sandbox,
             permission_mode: row.permission_mode,
             effort: row.effort,
             cwd: row.cwd,
-        })
+        };
+        // A fully blank snapshot is "nothing recoverable" (real creates always
+        // carry at least cwd): None here + was_recorded()==true is exactly the
+        // SETTINGS_RESET alarm condition (V7/A10).
+        if s == FreshAgentSettings::default() {
+            return None;
+        }
+        Some(s)
+    }
+
+    fn was_recorded(&self, provider: &str, session_id: &str) -> bool {
+        // State-agnostic (load_binding serves Retired/GcExpired rows too, V6/A9).
+        self.ledger
+            .load_binding(provider, session_id)
+            .map(|r| r.pane_kind.as_deref() == Some("fresh-agent"))
+            .unwrap_or(false)
     }
 }
 ```
@@ -560,9 +718,10 @@ let fresh_agent_identity_sink: freshell_freshagent::SharedPaneIdentitySink =
 fresh_codex.set_identity_sink(fresh_agent_identity_sink.clone());
 fresh_claude.set_identity_sink(fresh_agent_identity_sink.clone());
 fresh_opencode.set_identity_sink(fresh_agent_identity_sink.clone());
+fresh_agent_state.set_identity_sink(fresh_agent_identity_sink.clone()); // opencode REST surface (Task 7's materialization site; V10 A13-N1)
 ```
 
-(Use the actual local variable names from main.rs — the states are the ones placed into `WsState` fields `fresh_codex` / `fresh_claude` / `fresh_opencode`; if `WsState` is already constructed by line 426, call the setters on the state handles before they're moved, or via `state.fresh_codex.set_identity_sink(...)` — the field is `Arc<OnceLock>` so either handle works. `pane_ledger` in main.rs may be a value, not `Arc` — wrap once: `let pane_ledger = Arc::new(pane_ledger);` mirroring how `session_existence` receives it at `main.rs:440-449`, adapting the `WsState` field if it takes the Arc.)
+(Use the actual local variable names from main.rs — the states are the ones placed into `WsState` fields `fresh_codex` / `fresh_claude` / `fresh_opencode`, plus the `FreshAgentState` handed to `freshell_freshagent::router(...)` (constructed ~`main.rs:234`, V10). If `WsState` is already constructed by line 426, call the setters on the state handles before they're moved, or via `state.fresh_codex.set_identity_sink(...)` — the field is `Arc<OnceLock>` so either handle works. `pane_ledger` is ALREADY `Arc<PaneLedger>` in main.rs (`Arc::new(PaneLedger::new_locked(...))` at ~`:431`, verified by V10) — `LedgerIdentitySink::new(pane_ledger.clone())` works as written. All clones of each state share the `Arc<OnceLock>` field, so setter injection covers every route's clone — main.rs:209/219/239 are the ONLY production constructions (V10/A13).)
 
 - [ ] **Step 4: Run tests to verify they pass**
 
@@ -587,8 +746,11 @@ git commit -m "feat(server): wire pane ledger into fresh-agent states via Ledger
 - Test: inline `#[cfg(test)]` tests in `codex.rs` (harness: `ENV_LOCK` + `configure_fake_codex_cmd` at `codex.rs:4975/4979`, `create_real_fake_session` at `:4988`)
 
 **Interfaces:**
-- Consumes: `FakeIdentitySink` / `set_identity_sink` (Task 2). `CodexSession` fields (`codex.rs:163-199`): `model: String`, `effort: Option<String>`, `cwd: Option<String>`, `sandbox: Option<String>`, `permission_mode: Option<String>`.
-- Produces: private helper `fn record_codex_binding(&self, session_id: &str, create_request_id: Option<&str>, model: &str, sandbox: Option<&str>, permission_mode: Option<&str>, effort: Option<&str>, cwd: Option<&str>)` on `FreshCodexState`, called at all five identity sites. Codex ledger rows use `provider: "codex"`, `mode: "freshcodex"`.
+- Consumes: `FakeIdentitySink` / `set_identity_sink` (Task 2; writes are AWAITED — all five sites below are `async fn`, verified by V8: `codex.rs:462/:565/:1064/:1283/:1675`). `CodexSession` fields (`codex.rs:163-199`): `model: String`, `effort: Option<String>`, `cwd: Option<String>`, `sandbox: Option<String>`, `permission_mode: Option<String>`.
+- Produces:
+  - private helper `async fn record_codex_binding(&self, session_id: &str, create_request_id: Option<&str>, model: &str, sandbox: Option<&str>, permission_mode: Option<&str>, effort: Option<&str>, cwd: Option<&str>, supersedes: Option<&str>)` on `FreshCodexState`, called (`.await`ed) at all five identity sites. Codex ledger rows use `provider: "codex"`, `mode: "freshcodex"`.
+  - `fn emit_fresh_agent_error(&self, session_id: &str, code: &str, message: &str)` on `FreshCodexState` (defined HERE — Tasks 5/6 consume it): builds the same outer envelope the consumer uses to forward sidecar `freshAgent.error` events, byte-compatible so the frozen client's banner path fires. Required wire shape (V1/A2, verified against `fresh-agent-ws.ts:182-193`): `{ "type": "freshAgent.event", "sessionId": "<id>", "sessionType": "freshcodex", "provider": "codex", "event": { "type": "freshAgent.error", "code": "<code>", "message": "<message>" } }` — top-level `sessionType`/`provider` are REQUIRED (locator resolution) and `message` must be user-facing (the banner shows the message, never the code). Locate the consumer's existing sidecar-event forwarding and reuse its envelope construction; verify byte-compatibility during implementation.
+  - Alarm code `"LEDGER_WRITE_FAILED"` (write-failure surfacing, Global Constraints awaited-writes policy).
 
 - [ ] **Step 1: Write the failing test**
 
@@ -624,17 +786,31 @@ async fn create_records_fresh_agent_binding_with_settings() {
 
 (The comment lines describe which existing helper to reuse — the implementer replaces them with the harness's real invocation, keeping the four explicit settings values and all five assertions exactly as written. The existing create tests in `codex.rs` show the exact `freshAgent.create` message shape; wire params are camelCase: `requestId`, `sessionType`, `cwd`, `model`, `permissionMode`, `sandbox`, `effort`, `resumeSessionId`.)
 
+Also add the write-failure surfacing test (awaited-writes policy — failures are user-visible, never warn-and-drop):
+
+```rust
+#[tokio::test(flavor = "multi_thread")]
+async fn ledger_write_failure_is_surfaced_as_a_live_frame() {
+    // Same harness as above, but with a bus receiver and
+    // fake.fail_writes.store(true, SeqCst) BEFORE driving the create.
+    // Drive the create; then drain the bus (bounded, as in the alarm tests)
+    // and assert a frame containing "LEDGER_WRITE_FAILED" was broadcast,
+    // AND the create still succeeded (the session exists / created frame sent)
+    // — a write failure never blocks the identity event.
+}
+```
+
 - [ ] **Step 2: Run test to verify it fails**
 
 Run: `cargo test -p freshell-freshagent create_records_fresh_agent_binding`
-Expected: FAIL — `bindings` is empty (no ledger write exists yet).
+Expected: FAIL — `bindings` is empty (no ledger write exists yet). The write-failure test fails with no `LEDGER_WRITE_FAILED` frame.
 
 - [ ] **Step 3: Implement**
 
-(a) Add the shared helper on `FreshCodexState`:
+(a) Add the shared helper on `FreshCodexState` (async — the write is AWAITED per the Global Constraints durable-before-answer policy; failures are surfaced live, then the identity event proceeds):
 
 ```rust
-fn record_codex_binding(
+async fn record_codex_binding(
     &self,
     session_id: &str,
     create_request_id: Option<&str>,
@@ -643,31 +819,52 @@ fn record_codex_binding(
     permission_mode: Option<&str>,
     effort: Option<&str>,
     cwd: Option<&str>,
+    supersedes: Option<&str>,
 ) {
     let Some(sink) = self.identity_sink() else { return };
-    sink.record_binding(crate::identity_sink::FreshAgentBindingUpsert {
-        provider: "codex".into(),
-        session_id: session_id.into(),
-        mode: "freshcodex".into(),
-        create_request_id: create_request_id.map(Into::into),
-        resolves_pending: None,
-        settings: crate::identity_sink::FreshAgentSettings {
-            model: if model.is_empty() { None } else { Some(model.into()) },
-            sandbox: sandbox.map(Into::into),
-            permission_mode: permission_mode.map(Into::into),
-            effort: effort.map(Into::into),
-            cwd: cwd.map(Into::into),
-        },
-    });
+    let settings = crate::identity_sink::FreshAgentSettings {
+        model: if model.is_empty() { None } else { Some(model.into()) },
+        sandbox: sandbox.map(Into::into),
+        permission_mode: permission_mode.map(Into::into),
+        effort: effort.map(Into::into),
+        cwd: cwd.map(Into::into),
+    };
+    // No-laundering guard (V7/A10): never persist an all-blank snapshot —
+    // it would mask a genuine record miss forever. Real creates always carry
+    // at least cwd; a supersession write always goes through (G3 linkage).
+    if settings == crate::identity_sink::FreshAgentSettings::default() && supersedes.is_none() {
+        return;
+    }
+    if let Err(e) = sink
+        .record_binding(crate::identity_sink::FreshAgentBindingUpsert {
+            provider: "codex".into(),
+            session_id: session_id.into(),
+            mode: "freshcodex".into(),
+            create_request_id: create_request_id.map(Into::into),
+            resolves_pending: None,
+            supersedes: supersedes.map(Into::into),
+            settings,
+        })
+        .await
+    {
+        tracing::warn!(error = %e, session = %session_id, "freshagent.codex.ledger_write_failed");
+        self.emit_fresh_agent_error(
+            session_id,
+            "LEDGER_WRITE_FAILED",
+            "Failed to persist this session's resume record - settings may not survive a server restart.",
+        );
+    }
 }
 ```
 
-(b) Call it immediately after each of the five `sessions.insert` construction sites, passing that site's just-inserted values:
-1. `finish_create` (`codex.rs:603-619`) — the healthy create; `session_id` = `started.thread_id` (durable at create, born at `codex.rs:398`); `create_request_id` = the create message's `requestId`.
-2. `handle_create_resume` (R1, `codex.rs:462`…).
-3. `ensure_session_alive` (R2, `codex.rs:1064`…) — refresh write, same id.
-4. `ensure_session_resumable` (R3, `codex.rs:1675`…) — refresh write (its settings become real in Task 5).
-5. `respawn_as_new_thread_after_crash` (`codex.rs:1283`, re-key at `:1325-1347`) — NEW row under the new thread id (`codex.rs:1307`).
+Also define `emit_fresh_agent_error` here (exact wire shape + byte-compat requirement in the Interfaces block above; built on the state's broadcast path).
+
+(b) Call it (`.await`) immediately after each of the five `sessions.insert` construction sites, passing that site's just-inserted values (all five enclosing fns are `async fn` — V8: `:565/:462/:1064/:1675/:1283`) and BEFORE the site's reply/broadcast goes out (durable-before-answer):
+1. `finish_create` (`codex.rs:603-619`) — the healthy create; `session_id` = `started.thread_id` (durable at create, born at `codex.rs:398`); `create_request_id` = the create message's `requestId`; `supersedes: None`.
+2. `handle_create_resume` (R1, `codex.rs:462`…) — `supersedes: None`.
+3. `ensure_session_alive` (R2, `codex.rs:1064`…) — refresh write, same id, `supersedes: None`. Refresh writes snapshot the LIVE in-session values (which originate from a real create/user change); the no-laundering guard in (a) skips the write if they are all blank.
+4. `ensure_session_resumable` (R3, `codex.rs:1675`…) — refresh write, `supersedes: None`. Until Task 5 lands, R3 registers blanks, so the guard makes this call a no-op; Task 5 supplies the recovered values (and additionally gates this call on `recovered.is_some()` — never write a defaults row for a never-recorded historical session, V7).
+5. `respawn_as_new_thread_after_crash` (`codex.rs:1283`, re-key at `:1325-1347`) — NEW row under the new thread id (`codex.rs:1307`), with `supersedes: Some(&old_thread_id)` — the G3 supersession linkage (V8/A14): the ledger retires the old row and links it to the new one. This is the ONLY site that ever knows both ids; the edge is unrecoverable if not written here.
 
 - [ ] **Step 4: Run tests to verify they pass**
 
@@ -691,8 +888,8 @@ git commit -m "feat(codex): write fresh-agent ledger binding rows at every ident
 - Test: inline `#[cfg(test)]` in `codex.rs`
 
 **Interfaces:**
-- Consumes: `identity_sink().load_settings("codex", id)` (Task 2); fake app server request recorder (`appendThreadOperationLogPath` → JSONL `{method, threadId, params}` per `thread/*` RPC, `fake-app-server.mjs:360-374`; behavior via `FAKE_CODEX_APP_SERVER_BEHAVIOR`).
-- Produces: private `fn emit_fresh_agent_error(&self, session_id: &str, code: &str, message: &str)` on `FreshCodexState`; alarm code string `"SETTINGS_RESET"` (shared vocabulary with Tasks 8 and 10).
+- Consumes: `identity_sink().load_settings("codex", id)` + `was_recorded("codex", id)` (Task 2); `emit_fresh_agent_error` (Task 4); fake app server request recorder (`appendThreadOperationLogPath` → JSONL `{method, threadId, params}` per `thread/*` RPC, `fake-app-server.mjs:360-374`; behavior via `FAKE_CODEX_APP_SERVER_BEHAVIOR`).
+- Produces: alarm code string `"SETTINGS_RESET"` (shared vocabulary with Tasks 8 and 10), GATED per V7/A10: emitted ONLY when the ledger proves the session was previously recorded as a fresh-agent session (`was_recorded` true) yet no snapshot is recoverable (`load_settings` None). NEVER for never-recorded sessions (pre-ship, historical, sidebar-opened — `snapshot_runtime_for`'s own doc, `codex.rs:1574-1581`, says R3 exists FOR historical sessions): those resume silently with defaults exactly as today.
 
 **Known defect being fixed:** `ensure_session_resumable` (`codex.rs:1675`, restart/reload path — reached from attach-untracked `:1017` and REST snapshot `:1584`) resumes with `model/sandbox/approval_policy = None` (`:1721-1727`) and registers `model: String::new(), effort/sandbox/permission_mode: None` (`:1791-1799`); every post-restart turn silently runs on defaults forever.
 
@@ -741,22 +938,57 @@ async fn resume_after_restart_reapplies_settings_from_ledger() {
 }
 
 #[tokio::test(flavor = "multi_thread")]
-async fn resume_with_no_ledger_record_emits_settings_reset_alarm() {
+async fn resume_of_a_never_recorded_session_is_silent_and_writes_no_defaults_row() {
+    // V7/A10: record misses are ROUTINE (pre-ship sessions, sidebar-opened
+    // historical threads — R3 exists FOR them, codex.rs:1574-1581). They must
+    // resume silently with defaults exactly as today, and must NOT launder a
+    // defaults row into the ledger.
     let _guard = ENV_LOCK.lock().await;
     configure_fake_codex_cmd(/* resume-succeeds behavior */);
     let (state, mut bus_rx) = state_with_bus(); // subscribe to the broadcast bus
     let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default()); // deliberately empty
-    state.set_identity_sink(fake);
+    state.set_identity_sink(fake.clone());
 
     // Same R3 entry point as above for an untracked "thread-x".
 
-    // Drain broadcast frames (bounded) and find the alarm:
+    // Bounded drain: NO SETTINGS_RESET frame may appear.
+    while let Ok(frame) = tokio::time::timeout(std::time::Duration::from_secs(1), bus_rx.recv()).await {
+        let Ok(text) = frame else { break };
+        assert!(!text.contains("SETTINGS_RESET"), "never-recorded resume must stay silent");
+    }
+    // No defaults laundering (V7 §2): no binding row was written for thread-x.
+    assert!(
+        !fake.bindings.lock().unwrap().iter().any(|b| b.session_id == "thread-x"),
+        "a load_settings miss must not write a defaults row"
+    );
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn resume_with_a_prior_record_but_unrecoverable_settings_alarms_settings_reset() {
+    // The genuine anomaly: the ledger PROVES prior fresh-agent recording,
+    // yet no snapshot is recoverable — the only case that alarms (V7/A10).
+    let _guard = ENV_LOCK.lock().await;
+    configure_fake_codex_cmd(/* resume-succeeds behavior */);
+    let (state, mut bus_rx) = state_with_bus();
+    let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+    fake.seed_recorded_only("codex", "thread-y"); // was_recorded=true, load_settings=None
+    state.set_identity_sink(fake);
+
+    // Same R3 entry point, attaching untracked "thread-y".
+
     let mut found = false;
     while let Ok(frame) = tokio::time::timeout(std::time::Duration::from_secs(2), bus_rx.recv()).await {
         let Ok(text) = frame else { break };
-        if text.contains("SETTINGS_RESET") { found = true; break; }
+        if text.contains("SETTINGS_RESET") {
+            // A2 qualification (V1): the frame must carry top-level
+            // sessionType/provider and a user-facing message.
+            assert!(text.contains("freshcodex") && text.contains("codex"));
+            assert!(text.contains("Reconfirm your settings"));
+            found = true;
+            break;
+        }
     }
-    assert!(found, "missing-record resume must broadcast a SETTINGS_RESET freshAgent.error");
+    assert!(found, "recorded-but-unrecoverable resume must broadcast SETTINGS_RESET");
 }
 ```
 
@@ -765,40 +997,34 @@ async fn resume_with_no_ledger_record_emits_settings_reset_alarm() {
 - [ ] **Step 2: Run tests to verify they fail**
 
 Run: `cargo test -p freshell-freshagent resume_after_restart_reapplies_settings`
-Expected: FAIL — registered session has `model == ""` and the op-log resume params lack model/sandbox. The alarm test FAILS with no SETTINGS_RESET frame.
+Expected: FAIL — registered session has `model == ""` and the op-log resume params lack model/sandbox. The recorded-but-unrecoverable test FAILS with no SETTINGS_RESET frame. (The silent-defaults test may pass trivially pre-implementation — keep it as the permanent regression guard for V7's no-spam rule.)
 
 - [ ] **Step 3: Implement**
 
-(a) Alarm helper on `FreshCodexState` — deliver through the same broadcast path the consumer already uses to forward sidecar-originated `freshAgent.error` events to clients (locate the consumer's event forwarding; the frame on the wire must be byte-compatible with a sidecar-produced error event so the frozen client's banner path fires). The event payload is exactly:
-
-```json
-{ "type": "freshAgent.error", "sessionId": "<id>", "code": "<code>", "message": "<message>" }
-```
+(a) `ensure_session_resumable` (R3): before issuing `thread/resume`, load the record with the V7/A10 gate (`emit_fresh_agent_error` comes from Task 4):
 
 ```rust
-fn emit_fresh_agent_error(&self, session_id: &str, code: &str, message: &str) {
-    // Build the envelope the same way the consumer forwards sidecar events
-    // (same outer frame the client's fresh-agent-ws.ts event router reads),
-    // with the payload above, and send it via self.broadcast / broadcast_tx.
-}
-```
-
-(b) `ensure_session_resumable` (R3): before issuing `thread/resume`, load the record:
-
-```rust
-let recovered = self.identity_sink().and_then(|s| s.load_settings("codex", durable_id));
+let sink = self.identity_sink();
+let recovered = sink.as_ref().and_then(|s| s.load_settings("codex", durable_id));
 if recovered.is_none() {
-    tracing::warn!(session = %durable_id, "freshagent.codex.settings_record_missing");
-    self.emit_fresh_agent_error(
-        durable_id,
-        "SETTINGS_RESET",
-        "Session settings could not be recovered after restart - the agent is running with default model and permissions. Reconfirm your settings.",
-    );
+    if sink.as_ref().is_some_and(|s| s.was_recorded("codex", durable_id)) {
+        // The ledger PROVES prior fresh-agent recording, yet nothing is
+        // recoverable — the genuine "never-happens" anomaly. Alarm.
+        tracing::warn!(session = %durable_id, "freshagent.codex.settings_record_unrecoverable");
+        self.emit_fresh_agent_error(
+            durable_id,
+            "SETTINGS_RESET",
+            "Session settings could not be recovered after restart - the agent is running with default model and permissions. Reconfirm your settings.",
+        );
+    }
+    // else: never recorded (pre-ship / historical / sidebar-opened — the
+    // populations R3 exists to serve, codex.rs:1574-1581) → resume silently
+    // with defaults exactly as today. NO alarm, NO defaults write (V7).
 }
-let rec = recovered.unwrap_or_default();
+let rec = recovered.clone().unwrap_or_default();
 ```
 
-Then replace the three `None`s at `:1721-1727` with `rec.model` / `rec.sandbox` / `rec.permission_mode` (the resume request's approval-policy param) — and pass `rec.effort` wherever the healthy create passes effort. Replace the blank registration at `:1791-1799` with `model: rec.model.clone().unwrap_or_default(), sandbox: rec.sandbox.clone(), permission_mode: rec.permission_mode.clone(), effort: rec.effort.clone(), cwd: <existing cwd source>.or(rec.cwd.clone())`. Delete the stale comment claiming `handle_send` repairs settings (it only reads, `:733-777`). The Task-4 `record_codex_binding` call at this site now persists the recovered values.
+(b) Then replace the three `None`s at `:1721-1727` with `rec.model` / `rec.sandbox` / `rec.permission_mode` (the resume request's approval-policy param) — and pass `rec.effort` wherever the healthy create passes effort. Replace the blank registration at `:1791-1799` with `model: rec.model.clone().unwrap_or_default(), sandbox: rec.sandbox.clone(), permission_mode: rec.permission_mode.clone(), effort: rec.effort.clone(), cwd: <existing cwd source>.or(rec.cwd.clone())`. Delete the stale comment claiming `handle_send` repairs settings (it only reads, `:733-777`). Gate the Task-4 `record_codex_binding` call at this site on `recovered.is_some()` — the refresh write re-persists the RECOVERED live values; on a miss it must not run (writing would launder blank defaults into the ledger and permanently mask the miss — V7 §2's laundering finding).
 
 (c) `ensure_session_alive` (R2): where it forwards stored settings, add a ledger fallback for the blank case:
 
@@ -844,7 +1070,7 @@ git commit -m "fix(codex): resume paths reapply model/sandbox/permission/effort
 - Test: extend the existing crash tests (`send_after_crash_falls_back_to_mint_new_thread…` at `codex.rs:5145`, siblings at `:5224/:4625`)
 
 **Interfaces:**
-- Consumes: `emit_fresh_agent_error` (Task 5), `record_codex_binding` (Task 4).
+- Consumes: `emit_fresh_agent_error` (Task 4 — frame carries top-level `sessionType: "freshcodex"` / `provider: "codex"` + user-facing `message`, the A2 qualification; e2e test 4's banner matches on the message text), `record_codex_binding` (Task 4 — the crash-respawn call at this site passes `supersedes: Some(&old_thread_id)`, writing the G3 retire+link).
 - Produces: alarm code string `"THREAD_MEMORY_LOST"`.
 
 **Known defect being fixed:** `respawn_as_new_thread_after_crash` (`codex.rs:1283`) silently discards conversation memory — the only signal is `tracing::warn!(… "freshagent.crash_recovery.minted_new")` at `:1362-1366`, server-log only.
@@ -908,11 +1134,12 @@ git commit -m "feat(codex): user-visible THREAD_MEMORY_LOST degradation frame on
 
 **Files:**
 - Modify: `crates/freshell-freshagent/src/opencode_ws.rs`
-- Test: inline `#[cfg(test)]` using the existing in-crate trait fakes (`FakeHttp` etc. at `opencode_ws.rs:866-1076`, harnesses `:1080-1111`)
+- Modify: `crates/freshell-freshagent/src/lib.rs` (REST send-keys materialization write — `FreshAgentState` got its sink field in Task 2, injected in Task 3)
+- Test: inline `#[cfg(test)]` using the existing in-crate trait fakes (`FakeHttp` etc. at `opencode_ws.rs:866-1076`, harnesses `:1080-1111`); REST-path test in `lib.rs`'s existing test module
 
 **Interfaces:**
-- Consumes: `set_identity_sink`/`FakeIdentitySink` (Task 2). Sites: create `handle_create` (`opencode_ws.rs:243-247`, placeholder `freshopencode-<requestId>` at `:245`); materialization (durable `ses_*` id assigned `:359`, cwd upgraded `:360-364`, `freshAgent.session.materialized` broadcast `:373-384`); settings commit in `handle_send` (`session.model = model; session.effort = effort;` at `:397-398`).
-- Produces: opencode ledger rows use `provider: "opencode"`, `mode: "freshopencode"`.
+- Consumes: `set_identity_sink`/`FakeIdentitySink` (Task 2; writes AWAITED — all sites are async: WS `handle_create`/`handle_send`, REST send-keys handler). Sites: create `handle_create` (`opencode_ws.rs:243-247`, placeholder `freshopencode-<requestId>` at `:245`); WS materialization (durable `ses_*` id assigned `:359`, cwd upgraded `:360-364`, `freshAgent.session.materialized` broadcast `:373-384`); settings commit in `handle_send` (`session.model = model; session.effort = effort;` at `:397-398`); REST materialization (`lib.rs` send-keys handler — durable id persisted onto the pane + `FreshAgentSessionMaterialized` broadcast, the block near `lib.rs:1477-1516`; REST-created sessions otherwise bypass the sink entirely, V10 A13-N1 — and e2e Task 14 test 2 seeds via REST, so this site is load-bearing).
+- Produces: opencode ledger rows use `provider: "opencode"`, `mode: "freshopencode"`; `fn emit_fresh_agent_error(&self, session_id: &str, code: &str, message: &str)` on `FreshOpencodeState` (same envelope contract as Task 4's codex helper — top-level `sessionType: "freshopencode"` / `provider: "opencode"` + user-facing message — built on `FreshOpencodeState::broadcast`, `opencode_ws.rs:194-196`; Task 8 consumes it).
 
 - [ ] **Step 1: Write the failing test**
 
@@ -966,33 +1193,48 @@ Expected: FAIL — no pendings, no bindings recorded.
 
 - [ ] **Step 3: Implement**
 
-1. `handle_create` (`:243-247`): after registering the placeholder session:
+All writes are AWAITED before the site's broadcast/reply goes out (durable-before-answer); on `Err`, `tracing::warn!` + `emit_fresh_agent_error(<id>, "LEDGER_WRITE_FAILED", ...)` (define the opencode helper in this task — envelope contract in the Interfaces block), then proceed.
+
+1. `handle_create` (`:243-247`): after registering the placeholder session, BEFORE the `FreshAgentCreated` broadcast:
 ```rust
 if let Some(sink) = self.identity_sink() {
-    sink.record_pending(&placeholder_id, "freshopencode", session_cwd.as_deref());
+    if let Err(e) = sink.record_pending(&placeholder_id, "freshopencode", session_cwd.as_deref()).await {
+        tracing::warn!(error = %e, placeholder = %placeholder_id, "freshagent.opencode.pending_write_failed");
+        self.emit_fresh_agent_error(&placeholder_id, "LEDGER_WRITE_FAILED",
+            "Failed to persist this pane's identity marker - identity may not survive a crash.");
+    }
 }
 ```
-2. Materialization (`:359-369`, right after the durable id is assigned and cwd upgraded, before/alongside the `materialized` broadcast):
+2. WS materialization (`:359-369`, right after the durable id is assigned and cwd upgraded, BEFORE the `materialized` broadcast):
 ```rust
 if let Some(sink) = self.identity_sink() {
-    sink.record_binding(crate::identity_sink::FreshAgentBindingUpsert {
-        provider: "opencode".into(),
-        session_id: durable_id.clone(),
-        mode: "freshopencode".into(),
-        create_request_id: Some(request_id.clone()),
-        resolves_pending: Some(placeholder_id.clone()),
-        settings: crate::identity_sink::FreshAgentSettings {
-            model: session.model.clone(),
-            sandbox: None,
-            permission_mode: None,
-            effort: session.effort.clone(),
-            cwd: session.cwd.clone(),
-        },
-    });
+    if let Err(e) = sink
+        .record_binding(crate::identity_sink::FreshAgentBindingUpsert {
+            provider: "opencode".into(),
+            session_id: durable_id.clone(),
+            mode: "freshopencode".into(),
+            create_request_id: Some(request_id.clone()),
+            resolves_pending: Some(placeholder_id.clone()),
+            supersedes: None,
+            settings: crate::identity_sink::FreshAgentSettings {
+                model: session.model.clone(),
+                sandbox: None,
+                permission_mode: None,
+                effort: session.effort.clone(),
+                cwd: session.cwd.clone(),
+            },
+        })
+        .await
+    {
+        tracing::warn!(error = %e, session = %durable_id, "freshagent.opencode.binding_write_failed");
+        self.emit_fresh_agent_error(&durable_id, "LEDGER_WRITE_FAILED",
+            "Failed to persist this session's resume record - settings may not survive a server restart.");
+    }
 }
 ```
 (Adapt local variable names at the site; opencode has no sandbox/permission concepts — always `None`.)
-3. `handle_send` commit (`:397-398`): after `session.model = model.clone(); session.effort = effort.clone();`, if the session id is durable (`starts_with("ses_")`), record a refresh binding (same construction as above with `resolves_pending: None`, `create_request_id: None`).
+3. `handle_send` commit (`:397-398`): after `session.model = model.clone(); session.effort = effort.clone();`, if the session id is durable (`starts_with("ses_")`), record a refresh binding (same awaited construction as above with `resolves_pending: None`, `create_request_id: None`, `supersedes: None`).
+4. REST materialization (`crates/freshell-freshagent/src/lib.rs`, the send-keys handler's cold-start block that persists `entry.durable_id` and broadcasts `FreshAgentSessionMaterialized`, near `lib.rs:1477-1516`): record the same binding through `FreshAgentState`'s sink (field added in Task 2, injected in Task 3) — `session_id: durable_id`, `mode: "freshopencode"`, `create_request_id: None`, `resolves_pending: Some(pane.placeholder_id.clone())`, settings from the pane record (`pane.model` / `pane.effort` / `pane.cwd`), awaited BEFORE the materialized broadcast (the handler is async). On `Err`, warn + broadcast the same `LEDGER_WRITE_FAILED` error-frame shape via `state.broadcast`. Without this site, REST-created sessions (Task 14 e2e test 2's seeding surface) never get a resume record (V10 A13-N1). Add an inline test in `lib.rs`'s existing test module, modeled on the existing send-keys materialization (AGENT-08 continuity) test — locate the donor at implementation time — asserting the `FakeIdentitySink` received a binding carrying the REST create's model/effort.
 
 - [ ] **Step 4: Run tests to verify they pass**
 
@@ -1016,10 +1258,12 @@ git commit -m "feat(opencode): pending marker at create, binding row at ses_* ma
 - Test: inline `#[cfg(test)]`
 
 **Interfaces:**
-- Consumes: `load_settings("opencode", id)` (Task 2); `emit`-style broadcast via `FreshOpencodeState::broadcast` (`opencode_ws.rs:194-196`); alarm code `"SETTINGS_RESET"` (same vocabulary as Task 5).
-- Site: `resume_durable_session` (`opencode_ws.rs:662-696`) — sole caller `handle_attach` (`:598-600`).
+- Consumes: `load_settings("opencode", id)` + `was_recorded` (Task 2); `emit_fresh_agent_error` (Task 7); alarm code `"SETTINGS_RESET"` (same vocabulary + same V7/A10 gating as Task 5: alarm ONLY when `was_recorded` is true and `load_settings` misses; never-recorded sessions resume silently with defaults).
+- Sites: `resume_durable_session` (`opencode_ws.rs:662-696`) — caller `handle_attach` (`:598-600`); AND `handle_create` (`opencode_ws.rs:216-280`).
 
-**Known defect being fixed:** `resume_durable_session` builds `OpencodeSession::new(session_id, cwd.map(...), None, None)` at `:681` — model and effort hard-`None`; `cwd` comes from the attach message, not the session's real directory; the serve `GET /session/:id` body is fetched then discarded at `:678` (`let _ = info;`).
+**Known defects being fixed:**
+1. `resume_durable_session` builds `OpencodeSession::new(session_id, cwd.map(...), None, None)` at `:681` — model and effort hard-`None`; `cwd` comes from the attach message, not the session's real directory; the serve `GET /session/:id` body is fetched then discarded at `:678` (`let _ = info;`).
+2. `handle_create` IGNORES `resume_session_id` entirely (zero non-test reads of the field in the file — V2/A4) and always mints a fresh `freshopencode-{requestId}` placeholder. This is THE P1.13 wall-pin mechanism: after `page.reload()` the frozen client never sends `freshAgent.attach` — it sends `freshAgent.create{resumeSessionId: ses_*}` (persistMiddleware strips `sessionId`, so both attach effects are gated off; `persistMiddleware.ts:245-264`, `FreshAgentView.tsx:1099-1154`). Attach fires only on `ws.onReconnect` WITHOUT reload. Codex/claude already honor resume-in-create; opencode does not — fixing it here is what makes Task 15's pin flip achievable.
 
 - [ ] **Step 1: Write the failing tests**
 
@@ -1049,11 +1293,37 @@ async fn resume_durable_session_reapplies_settings_from_ledger() {
 }
 
 #[tokio::test]
-async fn resume_without_record_emits_settings_reset_and_uses_serve_directory() {
-    // Same harness; NO seed. RealisticServeHttp's GET /session/:id returns a
-    // directory — assert it is now used instead of being discarded, and that
-    // a SETTINGS_RESET freshAgent.error frame was broadcast.
-    // (bus subscription pattern as in Task 5's alarm test)
+async fn resume_without_record_is_silent_and_uses_serve_directory() {
+    // Same harness; NO seed (never-recorded session — the ROUTINE case, V7:
+    // handle_attach's own doc at opencode_ws.rs:581-590 describes it).
+    // Assert: RealisticServeHttp's GET /session/:id directory is now used
+    // instead of being discarded; NO SETTINGS_RESET frame was broadcast
+    // (bounded bus drain finds none — pattern from Task 5); and NO refresh
+    // binding was written for the session (no defaults laundering).
+}
+
+#[tokio::test]
+async fn resume_with_prior_record_but_unrecoverable_settings_alarms() {
+    // fake.seed_recorded_only("opencode", DURABLE_ID) — was_recorded=true,
+    // load_settings=None. Drive the same attach; assert a SETTINGS_RESET
+    // freshAgent.error frame WITH top-level sessionType "freshopencode" +
+    // provider "opencode" and a user-facing message (bus pattern from Task 5).
+}
+
+#[tokio::test]
+async fn create_with_resume_session_id_rebinds_the_durable_session() {
+    // V2/A4: the frozen client's ONLY post-reload resume vehicle is
+    // freshAgent.create{resumeSessionId: ses_*} — donor shape: codex's
+    // handle_create_with_resume_session_id_resumes_the_same_thread (codex.rs:4381).
+    // Same RealisticServeHttp harness; seed the ledger fake with settings for
+    // DURABLE_ID; drive handle_create with resume_session_id: Some(DURABLE_ID).
+    let sessions = state.sessions.lock().await;
+    assert!(sessions.contains_key(DURABLE_ID), "rebound to the surviving ses_*");
+    let s = sessions.get(DURABLE_ID).unwrap().lock().await;
+    assert_eq!(s.model.as_deref(), Some("big-model"), "settings-from-ledger applied on the create path");
+    drop(s); drop(sessions);
+    // And the FreshAgentCreated broadcast answered with the ses_* id (not a
+    // freshopencode-* placeholder) — capture it via the bus receiver.
 }
 ```
 
@@ -1064,26 +1334,32 @@ Expected: FAIL — model/effort are `None`, cwd is the attach message's.
 
 - [ ] **Step 3: Implement**
 
-In `resume_durable_session` (`:662-696`):
+(a) In `resume_durable_session` (`:662-696`), with the V7/A10 alarm gate:
 
 ```rust
-let recovered = self.identity_sink().and_then(|s| s.load_settings("opencode", &session_id));
-if recovered.is_none() {
-    tracing::warn!(session = %session_id, "freshagent.opencode.settings_record_missing");
+let sink = self.identity_sink();
+let recovered = sink.as_ref().and_then(|s| s.load_settings("opencode", &session_id));
+if recovered.is_none() && sink.as_ref().is_some_and(|s| s.was_recorded("opencode", &session_id)) {
+    // Recorded before, unrecoverable now — the genuine anomaly. Never-recorded
+    // sessions (pre-ship / serve-known-but-ledger-unknown, the ROUTINE attach
+    // population per opencode_ws.rs:581-590) resume silently with defaults.
+    tracing::warn!(session = %session_id, "freshagent.opencode.settings_record_unrecoverable");
     self.emit_fresh_agent_error(
         &session_id,
         "SETTINGS_RESET",
         "Session settings could not be recovered after restart - the agent is running with default model and effort. Reconfirm your settings.",
     );
 }
-let rec = recovered.unwrap_or_default();
+let rec = recovered.clone().unwrap_or_default();
 // :678 — stop discarding the serve body; parse its `directory` field:
 let serve_dir = info_directory; // extract from `info` instead of `let _ = info;`
 let cwd = rec.cwd.clone().or(serve_dir).or(attach_msg_cwd);
 let session = OpencodeSession::new(session_id.clone(), cwd, rec.model.clone(), rec.effort.clone());
 ```
 
-(`emit_fresh_agent_error` is a small helper mirroring Task 5's codex helper — same name, same `freshAgent.error` payload shape — built on `FreshOpencodeState::broadcast`. Model/effort take effect on the next turn because opencode sends them per-turn in the `prompt_async` body, `serve.rs:936-953` — the session fields are the source those sends read, plus Task 7's refresh keeps the ledger current.) After a successful resume, record a refresh binding (Task 7 construction, `resolves_pending: None`).
+(`emit_fresh_agent_error` comes from Task 7. Model/effort take effect on the next turn because opencode sends them per-turn in the `prompt_async` body, `serve.rs:936-953` — the session fields are the source those sends read, plus Task 7's refresh keeps the ledger current.) After a successful resume, record a refresh binding (Task 7's awaited construction, `resolves_pending: None`) ONLY when `recovered.is_some()` — never launder a defaults row for a never-recorded session (V7).
+
+(b) In `handle_create` (`:216-280`) — honor `resume_session_id` (V2/A4; this is the actual P1.13 pin-flip target): when `msg.resume_session_id` (or `msg.session_ref.as_ref().map(|r| &r.session_id)`) names a durable id (`starts_with("ses_")`), do NOT mint a `freshopencode-{requestId}` placeholder. Instead rebind to the surviving `ses_*`: route through the same resume machinery as (a) (`resume_durable_session`, which applies settings-from-ledger), register the session under the durable id, and answer `FreshAgentCreated` with `session_id`/`session_ref` = the durable id (keep the requestId dedup-cache behavior, recording the durable id). Explicit client params on the create win over the ledger record (mirror Task 5(d)'s precedence). Verify the exact created/materialized frame sequence the frozen client expects against the wall test's assertions (`restore-contract-wall-rust.spec.ts:1006-1020`) during implementation — the client must end up re-keyed to the `ses_*` id, not a placeholder.
 
 - [ ] **Step 4: Run tests to verify they pass**
 
@@ -1107,8 +1383,10 @@ git commit -m "fix(opencode): resume reapplies model/effort/cwd from the ledger
 - Test: inline `#[cfg(test)]` using `FakeClaudeSidecarEnv` (`claude.rs:1518-1578`) + `CLAUDE_ENV_LOCK` (`:1463`)
 
 **Interfaces:**
-- Consumes: Task 2 sink. Sites: healthy create request built inline in `handle_create` (`claude.rs:216-225`, keys `cwd`, `model`, `permissionMode`, `effort`, `resumeSessionId`); `sdk.session.init` handled in `spawn_consumer`'s task (cliSessionId recorded into `cli_index`, `claude.rs:605-618`; in scope there: `broadcast_tx`, `sessions`, `cli_index` clones at `:593-595`).
-- Produces: `spawn_consumer` gains two params: `mode: String` (from `session_type_str`, `claude.rs:700-705` — preserves the `"freshclaude"` vs `"kilroy"` flavour; provider is always `"claude"`, `claude.rs:66`) and `settings: crate::identity_sink::FreshAgentSettings`. All `spawn_consumer` call sites updated.
+- Consumes: Task 2 sink (writes AWAITED — the `sdk.session.init` arm runs on the async consumer task, so `.await` is legal there; V8). Sites: healthy create request built inline in `handle_create` (`claude.rs:216-225`, keys `cwd`, `model`, `permissionMode`, `effort`, `resumeSessionId`); `sdk.session.init` handled in `spawn_consumer`'s task (cliSessionId recorded into `cli_index`, `claude.rs:605-618`; in scope there: `broadcast_tx`, `sessions`, `cli_index` clones at `:593-595`).
+- Produces:
+  - `spawn_consumer` gains two params: `mode: String` (from `session_type_str`, `claude.rs:700-705` — preserves the `"freshclaude"` vs `"kilroy"` flavour; provider is always `"claude"`, `claude.rs:66`) and `settings: Option<crate::identity_sink::FreshAgentSettings>` — `Some` = record a binding at init (create path / resume-with-record); `None` = do NOT record (resume of a never-recorded session — writing would launder a blank row under the new cliSessionId, V7/A10). All `spawn_consumer` call sites updated.
+  - `fn emit_fresh_agent_error(&self, session_id: &str, session_type: &str, code: &str, message: &str)` on `FreshClaudeState` (same envelope contract as Task 4's codex helper — top-level `sessionType` param preserves the freshclaude/kilroy flavour, `provider: "claude"` — built on claude's direct broadcast, `claude.rs:173-177`; Task 10 consumes it).
 
 - [ ] **Step 1: Write the failing test**
 
@@ -1147,21 +1425,30 @@ Expected: FAIL — no bindings recorded.
 
 - [ ] **Step 3: Implement**
 
-1. In `handle_create`: build `let settings = crate::identity_sink::FreshAgentSettings { model: msg.model.clone(), sandbox: None, permission_mode: msg.permission_mode.clone(), effort: msg.effort.clone(), cwd: resolved_cwd.clone() };` (claude has no sandbox concept — always `None`; use the resolved cwd the create request actually sends at `:216-225`). Pass `session_type_str(&msg).to_string()` and `settings` into `spawn_consumer`.
-2. In `spawn_consumer`'s `sdk.session.init` arm (`:605-618`), after `cli_index` is updated:
+1. In `handle_create`: build `let settings = crate::identity_sink::FreshAgentSettings { model: msg.model.clone(), sandbox: None, permission_mode: msg.permission_mode.clone(), effort: msg.effort.clone(), cwd: resolved_cwd.clone() };` (claude has no sandbox concept — always `None`; use the resolved cwd the create request actually sends at `:216-225`). Pass `session_type_str(&msg).to_string()` and `Some(settings)` into `spawn_consumer`.
+2. In `spawn_consumer`'s `sdk.session.init` arm (`:605-618`), after `cli_index` is updated — the arm runs on the async consumer task, so the write is AWAITED there (durable before the init-driven broadcasts proceed), and failures are surfaced:
 ```rust
-if let Some(sink) = identity_sink.clone() { // clone the Option<Arc> into the task alongside broadcast_tx/sessions/cli_index
-    sink.record_binding(crate::identity_sink::FreshAgentBindingUpsert {
-        provider: "claude".into(),
-        session_id: cli_session_id.clone(),
-        mode: mode.clone(),
-        create_request_id: None,
-        resolves_pending: None,
-        settings: settings.clone(),
-    });
+if let (Some(sink), Some(settings)) = (identity_sink.clone(), settings.as_ref()) {
+    // clone the Option<Arc> + settings into the task alongside broadcast_tx/sessions/cli_index
+    if let Err(e) = sink
+        .record_binding(crate::identity_sink::FreshAgentBindingUpsert {
+            provider: "claude".into(),
+            session_id: cli_session_id.clone(),
+            mode: mode.clone(),
+            create_request_id: None,
+            resolves_pending: None,
+            supersedes: None,
+            settings: settings.clone(),
+        })
+        .await
+    {
+        tracing::warn!(error = %e, session = %cli_session_id, "freshagent.claude.binding_write_failed");
+        // emit_fresh_agent_error(cli_session_id, &mode, "LEDGER_WRITE_FAILED", ...) — helper defined in this task
+    }
 }
 ```
-3. Update every `spawn_consumer` call site (create and resume paths) — the resume path passes the settings it resolves in Task 10; until Task 10 lands, pass `FreshAgentSettings::default()` there so this task compiles and its test passes.
+(`settings: None` ⇒ no write — the resume-of-a-never-recorded-session case, Task 10: recording there would launder a blank row under the new cliSessionId, V7/A10.)
+3. Update every `spawn_consumer` call site (create and resume paths) — the resume path passes the `Option` it resolves in Task 10; until Task 10 lands, pass `None` there so this task compiles, its test passes, and no blank rows are written.
 
 - [ ] **Step 4: Run tests to verify they pass**
 
@@ -1185,7 +1472,7 @@ git commit -m "feat(claude): record fresh-agent binding row with create settings
 - Test: inline `#[cfg(test)]`
 
 **Interfaces:**
-- Consumes: `load_settings("claude", durable)` (Task 2); the fake sidecar spawn log — the scripted Node fake logs the WHOLE create-request JSON per spawn to `FRESHELL_TEST_CLAUDE_SPAWN_LOG` (`claude.rs:1474-1516`), so asserting reapplied settings needs no new plumbing.
+- Consumes: `load_settings("claude", durable)` + `was_recorded` (Task 2); `emit_fresh_agent_error` (Task 9); alarm code `"SETTINGS_RESET"` with the same V7/A10 gating as Tasks 5/8 (alarm ONLY when `was_recorded` is true and `load_settings` misses — never-recorded transcripts, including every claude-CLI-created and pre-ship session in the shared `~/.claude/projects` store, resume silently with nulls exactly as today); the fake sidecar spawn log — the scripted Node fake logs the WHOLE create-request JSON per spawn to `FRESHELL_TEST_CLAUDE_SPAWN_LOG` (`claude.rs:1474-1516`), so asserting reapplied settings needs no new plumbing.
 - Site: `resume_for_attach` (`claude.rs:470-562`; signature `(&self, msg: &FreshAgentAttach, durable: &str) -> Result<(), ResumeClaudeError>`; sole caller `handle_attach` `:454` under the `resuming` single-flight). The Null-settings create request is built at `:502-511` (`"model": Null, "permissionMode": Null, "effort": Null`) — an independent duplicate of the create-path `json!` at `:216-225`.
 
 **Known defect being fixed:** `ClaudeSession` (`claude.rs:112-134`) tracks no settings at all; resume-in-place sends Nulls, so a restarted freshclaude/kilroy pane silently reverts model/permissionMode/effort.
@@ -1220,11 +1507,22 @@ async fn resume_for_attach_reapplies_settings_from_ledger() {
 }
 
 #[tokio::test(flavor = "multi_thread")]
-async fn resume_without_record_emits_settings_reset_and_sends_nulls() {
-    // Same flow, no seed: assert the spawn-logged create request has null
-    // model/permissionMode/effort (today's behavior preserved as fallback)
-    // AND a SETTINGS_RESET freshAgent.error frame was broadcast
-    // (bus subscription pattern from Task 5).
+async fn resume_without_record_is_silent_and_sends_nulls() {
+    // Same flow, no seed (never-recorded transcript — the ROUTINE case:
+    // resume_for_attach exists precisely to serve never-tracked transcripts,
+    // claude.rs:430-436/:495-499; V7). Assert the spawn-logged create request
+    // has null model/permissionMode/effort (today's behavior preserved as the
+    // silent fallback), NO SETTINGS_RESET frame was broadcast (bounded bus
+    // drain, pattern from Task 5), and NO binding was recorded under the new
+    // cliSessionId (settings: None ⇒ no laundered blank row — Task 9).
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn resume_with_prior_record_but_unrecoverable_settings_alarms() {
+    // fake.seed_recorded_only("claude", DURABLE) — was_recorded=true,
+    // load_settings=None. Same resume flow; assert a SETTINGS_RESET
+    // freshAgent.error frame WITH top-level sessionType/provider and a
+    // user-facing message (bus pattern from Task 5).
 }
 ```
 
@@ -1235,22 +1533,27 @@ Expected: FAIL — logged create request has nulls despite the seeded record.
 
 - [ ] **Step 3: Implement**
 
-In `resume_for_attach`, before building the create request at `:502-511`:
+In `resume_for_attach`, before building the create request at `:502-511`, with the V7/A10 alarm gate:
 
 ```rust
-let recovered = self.identity_sink().and_then(|s| s.load_settings("claude", durable));
-if recovered.is_none() {
-    tracing::warn!(session = %durable, "freshagent.claude.settings_record_missing");
+let sink = self.identity_sink();
+let recovered = sink.as_ref().and_then(|s| s.load_settings("claude", durable));
+if recovered.is_none() && sink.as_ref().is_some_and(|s| s.was_recorded("claude", durable)) {
+    // Recorded before, unrecoverable now — the genuine anomaly. Never-recorded
+    // transcripts (the entire pre-existing ~/.claude/projects population,
+    // claude.rs:430-436 — resume_for_attach exists FOR them) stay silent.
+    tracing::warn!(session = %durable, "freshagent.claude.settings_record_unrecoverable");
     self.emit_fresh_agent_error(
         durable,
+        session_type_str(msg.session_type), // preserves freshclaude vs kilroy in the frame
         "SETTINGS_RESET",
         "Session settings could not be recovered after restart - the agent is running with default model and permissions. Reconfirm your settings.",
     );
 }
-let rec = recovered.unwrap_or_default();
+let rec = recovered.clone().unwrap_or_default();
 ```
 
-Replace the three `Null`s: `"model": rec.model, "permissionMode": rec.permission_mode, "effort": rec.effort` (`serde_json::json!` serializes `None` as `null`, preserving today's fallback wire shape exactly). Keep the existing deliberate cwd handling (`:487-497`) as the primary, with `rec.cwd` as a final fallback only if both existing sources are absent. Pass `mode:` derived via the existing `session_type_str` helper (`claude.rs:700-705`) applied to the attach message's sessionType (defaulting to `"freshclaude"` when absent) and `settings: rec.clone()` into this path's `spawn_consumer` call (Task 9 threading), so the re-init re-records the row under any new cliSessionId. `emit_fresh_agent_error` is the same helper shape as Task 5's, built on claude's direct broadcast (`claude.rs:173-177`).
+Replace the three `Null`s: `"model": rec.model, "permissionMode": rec.permission_mode, "effort": rec.effort` (`serde_json::json!` serializes `None` as `null`, preserving today's fallback wire shape exactly). Keep the existing deliberate cwd handling (`:487-497`) as the primary, with `rec.cwd` as a final fallback only if both existing sources are absent. Pass `mode:` = `session_type_str(msg.session_type).to_string()` — `sessionType` is a REQUIRED typed field on `FreshAgentAttach` (`client_messages.rs:492-502`, verified by V2/A17: a frame without it fails deserialization), so there is NO "absent → default freshclaude" branch to write — and `settings: recovered.clone()` (the `Option` itself, Task 9 threading) into this path's `spawn_consumer` call: `Some(rec)` re-records the row under any new cliSessionId (the old durable's row keeps serving `load_settings`, so later attaches with the old id still resolve — no repeat-fire, V7 §4); `None` records nothing (no laundered blank row under the new id).
 
 - [ ] **Step 4: Run tests to verify they pass**
 
@@ -1280,7 +1583,7 @@ git commit -m "fix(claude): resume-in-place reapplies model/permissionMode/effor
 
 - [ ] **Step 1: Write the failing test**
 
-Create `crates/freshell-ws/tests/pane_reconcile_freshagent.rs`. Copy the harness from `crates/freshell-ws/tests/pane_reconcile.rs` (`spawn_server()` at `:62-125` — full `WsState` literal, `NoIndexProbe`, `PaneLedger::disabled()`, ephemeral `127.0.0.1:0` axum; `connect()` at `:133-165`; `next_frame_of_type()`; `reconcile_request()`), with `connect` extended:
+Create `crates/freshell-ws/tests/pane_reconcile_freshagent.rs` — this file does NOT exist on main; it is CREATED here from the donors and extended in Task 13 (V10/A16). Copy the harness from `crates/freshell-ws/tests/pane_reconcile.rs` (`spawn_server()` at `:62-125` — full `WsState` literal, `NoIndexProbe`, `PaneLedger::disabled()`, ephemeral `127.0.0.1:0` axum; `connect()` at `:133-165`; `next_frame_of_type()`; `reconcile_request()`), with `connect` extended:
 
 ```rust
 async fn connect(url: &str, pane_reconcile_v1: bool, fresh_agent_v1: bool) -> (TestWs, serde_json::Value) {
@@ -1354,7 +1657,7 @@ git commit -m "feat(ws): paneReconcileFreshAgentV1 capability - parsed, threaded
 - Test: unit tests inline in the new module
 
 **Interfaces:**
-- Consumes: `freshell_protocol` types `ReconcilePane`, `PaneVerdict`, `ReconcileVerdict`, `SessionLocator` (verdict wire names: `attach`/`respawn`/`fresh`/`dead_session`/`invalid`; `PaneVerdict` fields `pane_key`, `verdict`, `terminal_id`, `session_ref`, `corrected`, `reason`, `retry_after_ms`, `duplicate` — optionals absent, never null).
+- Consumes: `freshell_protocol` types `ReconcilePane`, `PaneVerdict`, `ReconcileVerdict`, `SessionLocator` (verdict wire names: `attach`/`respawn`/`fresh`/`dead_session`/`invalid`; `PaneVerdict` fields `pane_key`, `verdict`, `terminal_id`, `session_ref`, `corrected`, `reason`, `retry_after_ms` (B1 deletes this field at merge — see Global Constraints), `duplicate` — optionals absent, never null; never construct/match `ReconcileVerdict::Retry`).
 - Produces (exact, used by Task 13):
 
 ```rust
@@ -1362,12 +1665,19 @@ pub const FRESH_AGENT_RESPAWN_CAP: u32 = 3;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum FreshAgentPresence { Live, OnDisk, GoneObserved, NeverObserved, Unknown }
+// B1 pre-decision (V9/A12): when B1's `SessionExistence::ProviderUnavailable`
+// lands, it maps to FreshAgentPresence::Unknown (conservative: respawn-with-cap,
+// never dead_session). Keep every SessionExistence match exhaustive, no catch-all.
 
 #[derive(Debug, Clone, PartialEq)]
 pub struct FreshAgentPaneFacts {
     pub presence: FreshAgentPresence,
     pub duplicate_of: Option<String>, // paneKey of the earlier pane claiming the same session
     pub respawn_exhausted: bool,
+    /// G3 supersession terminus (V8/A14): when the claimed sessionRef resolved
+    /// through the ledger's supersededBy chain to a DIFFERENT id, this is the
+    /// terminus id — the verdict answers with it + `corrected: true`.
+    pub resolved_session_id: Option<String>,
 }
 
 #[derive(Debug, Default)]
@@ -1462,9 +1772,28 @@ mod tests {
         assert_eq!(v.verdict, ReconcileVerdict::DeadSession);
         assert_eq!(v.reason.as_deref(), Some("respawn_exhausted"));
     }
+
+    #[test]
+    fn superseded_claim_is_answered_from_the_chain_terminus_with_corrected() {
+        // G3 reader rule (V8/A14): a client claiming a superseded ref is
+        // answered from the chain terminus — never respawn the retired ref.
+        // Facts built directly: presence OnDisk, resolved_session_id Some("t2").
+        let mut s = snap(&[("p", FreshAgentPresence::OnDisk, None, false)]);
+        s.facts.get_mut("p").unwrap().resolved_session_id = Some("t2".into());
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("codex", "t1"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Respawn);
+        assert_eq!(
+            v.session_ref.as_ref().unwrap().session_id,
+            "t2",
+            "answer carries the terminus id, not the retired claim"
+        );
+        assert_eq!(v.corrected, Some(true));
+    }
 }
 ```
 
+(The `snap` helper keeps its 4-tuple shape and fills `resolved_session_id: None`; tests that need the terminus mutate the entry, as above. `PaneVerdict.corrected` already exists on the wire — `server_messages.rs:697-722`; donor semantics `contradicting_claim_is_corrected_on_respawn`, `reconcile.rs:671-674` — no new wire field is added.)
+
 - [ ] **Step 2: Run tests to verify they fail**
 
 Run: `cargo test -p freshell-ws reconcile_freshagent`
@@ -1479,12 +1808,26 @@ Expected: COMPILE ERROR (module doesn't exist).
 //! states. All async work (session maps, probes) happens in the snapshot
 //! builder (Task 13); this module is pure + sync so it stays legal inside
 //! derive_verdicts' catch_unwind.
-
-use freshell_protocol::/* the same paths reconcile.rs imports for */ {PaneVerdict, ReconcilePane, ReconcileVerdict};
+//!
+//! Verdict-mapping caveats (V5/A8, documented here for future readers):
+//! - Zero-turn codex threads have NO rollout file until the first PERSISTED
+//!   user message (vendor deferred materialization, verified at rust-v0.145.0)
+//!   → the probe answers Absent → verdict `fresh` (identity never observed)
+//!   or `dead_session` (ledger already bound it). Acceptable either way:
+//!   zero turns means there is no conversation content to lose.
+//! - WATCH: codex `.jsonl.zst` cold-rollout compression (vendor feature,
+//!   default-OFF today) would hide ≥7-day-old sessions from the `.jsonl`-only
+//!   index walk → false Absent. Revisit if the vendor flag graduates.
+//! - WATCH: CLAUDE_CONFIG_DIR/CLAUDE_HOME reader/writer split (pre-existing
+//!   wave-A exposure, out of scope this lane).
+
+use freshell_protocol::/* the same paths reconcile.rs imports for */ {PaneVerdict, ReconcilePane, ReconcileVerdict, SessionLocator};
 
 pub const FRESH_AGENT_RESPAWN_CAP: u32 = 3;
 // … types exactly as the Interfaces block above …
 
+/// The SINGLE PaneVerdict construction point in this module (B1-coexistence
+/// hardening, V9/A12 — keep it that way).
 fn base(pane: &ReconcilePane, verdict: ReconcileVerdict) -> PaneVerdict {
     PaneVerdict {
         pane_key: pane.pane_key.clone(),
@@ -1493,7 +1836,7 @@ fn base(pane: &ReconcilePane, verdict: ReconcileVerdict) -> PaneVerdict {
         session_ref: None,
         corrected: None,
         reason: None,
-        retry_after_ms: None,
+        retry_after_ms: None, // DELETE-AT-MERGE: B1 removes this field
         duplicate: None,
     }
 }
@@ -1521,10 +1864,21 @@ pub fn verdict_for_pane(snapshot: Option<&FreshAgentReconcileSnapshot>, pane: &R
         v.duplicate = Some(winner.clone());
         return v;
     }
+    // G3 reader rule (V8/A14): when the claim resolved through the ledger's
+    // supersession chain, every echoed session_ref carries the TERMINUS id
+    // and the verdict is marked corrected (never answer the retired ref).
+    let (sref, corrected) = match &facts.resolved_session_id {
+        Some(terminus) if *terminus != sref.session_id => (
+            SessionLocator { provider: sref.provider.clone(), session_id: terminus.clone() },
+            Some(true),
+        ),
+        _ => (sref, None),
+    };
     match facts.presence {
         FreshAgentPresence::Live => {
             let mut v = base(pane, ReconcileVerdict::Attach);
             v.session_ref = Some(sref);
+            v.corrected = corrected;
             v
         }
         FreshAgentPresence::OnDisk | FreshAgentPresence::Unknown => {
@@ -1532,10 +1886,12 @@ pub fn verdict_for_pane(snapshot: Option<&FreshAgentReconcileSnapshot>, pane: &R
                 let mut v = base(pane, ReconcileVerdict::DeadSession);
                 v.reason = Some("respawn_exhausted".into());
                 v.session_ref = Some(sref);
+                v.corrected = corrected;
                 v
             } else {
                 let mut v = base(pane, ReconcileVerdict::Respawn);
                 v.session_ref = Some(sref);
+                v.corrected = corrected;
                 v
             }
         }
@@ -1543,6 +1899,7 @@ pub fn verdict_for_pane(snapshot: Option<&FreshAgentReconcileSnapshot>, pane: &R
             let mut v = base(pane, ReconcileVerdict::DeadSession);
             v.reason = Some("session_not_on_disk".into());
             v.session_ref = Some(sref);
+            v.corrected = corrected;
             v
         }
         FreshAgentPresence::NeverObserved => {
@@ -1559,7 +1916,7 @@ pub fn verdict_for_pane(snapshot: Option<&FreshAgentReconcileSnapshot>, pane: &R
 - [ ] **Step 4: Run tests to verify they pass**
 
 Run: `cargo test -p freshell-ws reconcile_freshagent`
-Expected: PASS (9 unit tests).
+Expected: PASS (10 unit tests).
 
 - [ ] **Step 5: Commit**
 
@@ -1579,16 +1936,16 @@ git commit -m "feat(ws): reconcile_freshagent - pure fresh-agent verdict mapping
 - Test: `crates/freshell-ws/tests/pane_reconcile_freshagent.rs` (extend)
 
 **Interfaces:**
-- Consumes: `SessionExistenceProbe` (`crates/freshell-ws/src/existence.rs:23-44`, READ-ONLY — B1 owns the file): `enum SessionExistence { Present, Absent, Unknown }`; sync `fn exists(&self, provider: &str, session_id: &str) -> SessionExistence` and `fn ever_observed(&self, provider: &str, session_id: &str) -> bool`. `PaneLedger::ever_bound`. Task 12 types. `ReconcileDeps` (`reconcile.rs:28-32`: `registry`, `identity`, `existence`), built at `terminal.rs:1932-1936`.
+- Consumes: `SessionExistenceProbe` (`crates/freshell-ws/src/existence.rs:23-44`, READ-ONLY — B1 owns the file): `enum SessionExistence { Present, Absent, Unknown }`; sync `fn exists(&self, provider: &str, session_id: &str) -> SessionExistence` and `fn ever_observed(&self, provider: &str, session_id: &str) -> bool`. `PaneLedger::ever_bound` AND `PaneLedger::lookup_by_session` (`pane_ledger.rs:450-484` — public, memory-only, follows the `supersededBy` chain with a 32-hop cap; returns `Resolution { row, corrected }`). Task 12 types. `ReconcileDeps` (`reconcile.rs:28-32`: `registry`, `identity`, `existence`), built at `terminal.rs:1932-1936`. Probe/ledger inject via the pub `WsState.session_existence` / `WsState.pane_ledger` fields — confirmed by V10/A16, no new injection point needed.
 - Produces:
-  - `pub async fn FreshCodexState::has_live_session(&self, session_id: &str) -> bool` (map contains id AND `!exited.load(SeqCst)`), `pub async fn FreshOpencodeState::has_live_session(&self, session_id: &str) -> bool` (sessions map contains the durable key — it is keyed by placeholder AND durable id, `opencode_ws.rs:96`), `pub async fn FreshClaudeState::has_live_session(&self, session_id: &str) -> bool` (`cli_index` durable → mapkey → sessions contains, `claude.rs:81-86`).
+  - `pub async fn FreshCodexState::has_live_session(&self, session_id: &str) -> bool` (map contains id AND `!exited.load(SeqCst)`), `pub async fn FreshOpencodeState::has_live_session(&self, session_id: &str) -> bool` (sessions map contains the durable key — it is keyed by placeholder AND durable id, `opencode_ws.rs:96`), `pub async fn FreshClaudeState::has_live_session(&self, session_id: &str) -> bool` (`cli_index` durable → mapkey → sessions contains, `claude.rs:81-86`; read the sessions map UNFILTERED — no session_type filter, so kilroy sessions count for free, V2 N-A17-1).
   - `pub async fn reconcile_freshagent::build_snapshot(state: &WsState, panes: &[ReconcilePane]) -> FreshAgentReconcileSnapshot`.
-  - `WsState.fresh_agent_respawn_counts: std::sync::Arc<std::sync::Mutex<std::collections::HashMap<(String, String), u32>>>` (per-boot, in-memory).
+  - `WsState.fresh_agent_respawn_counts: std::sync::Arc<std::sync::Mutex<std::collections::HashMap<(String, String), u32>>>` (per-boot, in-memory; counts RESPAWN ANSWERS only, cleared when presence resolves Live — V2/A7).
   - `ReconcileDeps.fresh_agent: Option<&'a FreshAgentReconcileSnapshot>`.
 
 - [ ] **Step 1: Write the failing integration tests**
 
-Extend `crates/freshell-ws/tests/pane_reconcile_freshagent.rs`. Add a scripted probe (the trait is public in freshell-ws) and pass it into `spawn_server` (extend the donor's `spawn_server` to accept a probe + a real temp-root `PaneLedger`, exposing both on the returned `Server` — same pattern as it already exposes `registry`/`identity`):
+Extend `crates/freshell-ws/tests/pane_reconcile_freshagent.rs` (CREATED in Task 11 from the donors — it does not exist on main; V10/A16). Harness notes (V10, confirmed): the probe and ledger inject via the pub `WsState.session_existence` / `WsState.pane_ledger` fields at the test's struct-literal construction — NO new injection point is needed; the live-session tests drive the fake claude sidecar via env vars (`FRESHELL_CLAUDE_SIDECAR` etc.), which are process-global — replicate `freshagent_claude_attach.rs`'s file-local `CLAUDE_ENV_LOCK` mutex serialization (attach donor `:24`; env installer `:64-99`; it also flips `settings.freshAgent.enabled: true` in BOTH seeding spots, `:120/:151`). Add a scripted probe (the trait is public in freshell-ws) and pass it into `spawn_server` (extend the donor's `spawn_server` to accept a probe + a real temp-root `PaneLedger` (`PaneLedger::new_locked(Some(temp_root))`), exposing both — plus a clone of the `fresh_agent_respawn_counts` Arc — on the returned `Server`, same pattern as it already exposes `registry`/`identity`):
 
 ```rust
 #[derive(Default)]
@@ -1664,7 +2021,9 @@ async fn duplicate_session_claims_dedupe_within_one_request() {
 
 #[tokio::test]
 async fn respawn_cap_turns_the_fourth_answer_into_dead_session() {
-    // probe: ("codex","cap") Present; 4 sequential single-pane requests:
+    // probe: ("codex","cap") Present — the session stays Present-but-never-live,
+    // so every answer maps to respawn; only RESPAWN ANSWERS burn the cap (V2/A7).
+    // 4 sequential single-pane requests:
     for i in 0..4 {
         let verdicts = reconcile_request(&mut ws, serde_json::json!([
             { "paneKey": "p", "kind": "fresh-agent", "sessionRef": {"provider": "codex", "sessionId": "cap"} }
@@ -1677,6 +2036,49 @@ async fn respawn_cap_turns_the_fourth_answer_into_dead_session() {
         }
     }
 }
+
+#[tokio::test]
+async fn a_session_resolving_live_clears_the_respawn_counter() {
+    // Reset-on-live (V2/A7): a successful respawn is OBSERVED as the session
+    // going live; the counter must clear so healthy sessions are never
+    // exhausted by reconnect/reload storms.
+    // 1. Fake claude sidecar env (donor freshagent_claude_attach.rs, under
+    //    CLAUDE_ENV_LOCK) whose scripted sdk.session.init emits a cliSessionId
+    //    the test controls (or read it from the created frame).
+    // 2. Probe: ("claude", <id>) Present. TWO reconcile requests while the
+    //    session is NOT yet live → both answer "respawn"; assert
+    //    server.respawn_counts contains ("claude", <id>) == 2.
+    // 3. Drive freshAgent.create through the fake sidecar (donor flow from
+    //    live_fresh_agent_session_gets_attach) so has_live_session is true.
+    // 4. Reconcile again → "attach"; assert server.respawn_counts no longer
+    //    contains the key (cleared, not merely un-incremented).
+}
+
+#[tokio::test]
+async fn old_thread_claim_after_crash_respawn_answers_the_new_terminus() {
+    // G3 reader rule end-to-end (V8/A14). Seed the REAL temp-root ledger:
+    let now = 1_000;
+    server.pane_ledger.record_fresh_agent_binding(&FreshAgentBindingWrite {
+        provider: "codex", session_id: "old-t", mode: "freshcodex",
+        cwd: Some("/w"), create_request_id: None, model: Some("m"),
+        sandbox: None, permission_mode: None, effort: None,
+        supersedes: None, now_ms: now,
+    }).unwrap();
+    server.pane_ledger.record_fresh_agent_binding(&FreshAgentBindingWrite {
+        provider: "codex", session_id: "new-t", mode: "freshcodex",
+        cwd: Some("/w"), create_request_id: None, model: Some("m"),
+        sandbox: None, permission_mode: None, effort: None,
+        supersedes: Some("old-t"), now_ms: now + 1,
+    }).unwrap();
+    // probe: ("codex","new-t") Present (the old rollout may ALSO still exist
+    // on disk — the point is we never answer the retired ref).
+    let verdicts = reconcile_request(&mut ws, serde_json::json!([
+        { "paneKey": "p", "kind": "fresh-agent", "sessionRef": {"provider": "codex", "sessionId": "old-t"} }
+    ])).await;
+    assert_eq!(verdicts[0]["verdict"], "respawn");
+    assert_eq!(verdicts[0]["sessionRef"]["sessionId"], "new-t", "answer from the chain terminus");
+    assert_eq!(verdicts[0]["corrected"], true);
+}
 ```
 
 - [ ] **Step 2: Run tests to verify they fail**
@@ -1701,30 +2103,44 @@ pub async fn build_snapshot(
     let mut claimed: std::collections::HashMap<(String, String), String> = std::collections::HashMap::new();
     for pane in panes.iter().filter(|p| p.kind.as_deref() == Some("fresh-agent")) {
         let Some(sref) = pane.session_ref.as_ref() else { continue }; // verdict fn answers no_recoverable_identity
-        let key = (sref.provider.clone(), sref.session_id.clone());
+        // G3 reader rule (V8/A14): resolve the CLAIM through the ledger's
+        // supersession chain FIRST — dedupe, liveness, existence, and the
+        // respawn counter all key on the TERMINUS id (lookup_by_session is
+        // public + memory-only, pane_ledger.rs:450-484).
+        let resolved = state
+            .pane_ledger
+            .lookup_by_session(&sref.provider, &sref.session_id)
+            .filter(|r| r.corrected)
+            .map(|r| r.row.session_id);
+        let session_id = resolved.clone().unwrap_or_else(|| sref.session_id.clone());
+        let key = (sref.provider.clone(), session_id.clone());
         if let Some(winner) = claimed.get(&key) {
             facts.insert(pane.pane_key.clone(), FreshAgentPaneFacts {
                 presence: FreshAgentPresence::Unknown,
                 duplicate_of: Some(winner.clone()),
                 respawn_exhausted: false,
+                resolved_session_id: resolved,
             });
             continue;
         }
         claimed.insert(key.clone(), pane.pane_key.clone());
         let live = match sref.provider.as_str() {
-            "codex" => state.fresh_codex.has_live_session(&sref.session_id).await,
-            "claude" => state.fresh_claude.has_live_session(&sref.session_id).await,
-            "opencode" => state.fresh_opencode.has_live_session(&sref.session_id).await,
+            "codex" => state.fresh_codex.has_live_session(&session_id).await,
+            "claude" => state.fresh_claude.has_live_session(&session_id).await,
+            "opencode" => state.fresh_opencode.has_live_session(&session_id).await,
             _ => false,
         };
         use crate::existence::SessionExistence as E;
         let presence = if live {
             FreshAgentPresence::Live
         } else {
-            match state.session_existence.exists(&sref.provider, &sref.session_id) {
+            // Exhaustive match, NO catch-all (B1 hardening: when B1 adds
+            // E::ProviderUnavailable this goes non-exhaustive — add the
+            // pre-decided arm `E::ProviderUnavailable => FreshAgentPresence::Unknown`).
+            match state.session_existence.exists(&sref.provider, &session_id) {
                 E::Present => FreshAgentPresence::OnDisk,
                 E::Absent => {
-                    if state.session_existence.ever_observed(&sref.provider, &sref.session_id) {
+                    if state.session_existence.ever_observed(&sref.provider, &session_id) {
                         FreshAgentPresence::GoneObserved
                     } else {
                         FreshAgentPresence::NeverObserved
@@ -1732,7 +2148,7 @@ pub async fn build_snapshot(
                 }
                 E::Unknown => {
                     // The ledger is positive evidence the session existed.
-                    if state.pane_ledger.ever_bound(&sref.provider, &sref.session_id) {
+                    if state.pane_ledger.ever_bound(&sref.provider, &session_id) {
                         FreshAgentPresence::OnDisk
                     } else {
                         FreshAgentPresence::Unknown
@@ -1740,25 +2156,54 @@ pub async fn build_snapshot(
                 }
             }
         };
-        let respawn_exhausted = if matches!(presence, FreshAgentPresence::OnDisk | FreshAgentPresence::Unknown) {
-            let mut counts = state.fresh_agent_respawn_counts.lock().expect("respawn counts poisoned");
-            let c = counts.entry(key).or_insert(0);
-            *c += 1;
-            *c > FRESH_AGENT_RESPAWN_CAP
-        } else {
-            false
+        // Respawn cap (V2/A7 — reworked): count only answers that actually
+        // come back `respawn`, and CLEAR the counter when presence resolves
+        // Live (a successful respawn is OBSERVED as the session going live).
+        // The counting lives HERE because for non-duplicate panes the verdict
+        // is fully determined by presence: OnDisk/Unknown + !exhausted ⇒
+        // respawn (see verdict_for_pane) — so "this answer will be respawn"
+        // is known at increment time. Mutation stays in this async builder,
+        // OUTSIDE derive_verdicts' catch_unwind.
+        let respawn_exhausted = match presence {
+            FreshAgentPresence::Live => {
+                state
+                    .fresh_agent_respawn_counts
+                    .lock()
+                    .expect("respawn counts poisoned")
+                    .remove(&key); // reset-on-live
+                false
+            }
+            FreshAgentPresence::OnDisk | FreshAgentPresence::Unknown => {
+                let mut counts = state.fresh_agent_respawn_counts.lock().expect("respawn counts poisoned");
+                let c = counts.entry(key).or_insert(0);
+                if *c >= FRESH_AGENT_RESPAWN_CAP {
+                    true // this answer becomes dead_session{respawn_exhausted}; no burn
+                } else {
+                    *c += 1; // this answer goes out as `respawn` — burn one
+                    false
+                }
+            }
+            FreshAgentPresence::GoneObserved | FreshAgentPresence::NeverObserved => false,
         };
-        facts.insert(pane.pane_key.clone(), FreshAgentPaneFacts { presence, duplicate_of: None, respawn_exhausted });
+        facts.insert(pane.pane_key.clone(), FreshAgentPaneFacts {
+            presence,
+            duplicate_of: None,
+            respawn_exhausted,
+            resolved_session_id: resolved,
+        });
     }
     FreshAgentReconcileSnapshot { facts }
 }
 ```
 
-(Adapt the `state.pane_ledger` access to how `WsState` actually holds the ledger — direct field per `pane_ledger: :476` in main.rs wiring. Cap semantics: each respawn-candidate ANSWER burns one attempt per (provider, sessionId) per boot; after `FRESH_AGENT_RESPAWN_CAP` answers, `dead_session{respawn_exhausted}` — mirroring the terminal wall's protection so a client stuck in a respawn loop cannot spin forever.)
+(Adapt the `state.pane_ledger` access to how `WsState` actually holds the ledger — direct field per `pane_ledger: :476` in main.rs wiring. Cap rationale (V2/A7): the terminal donor counts actual process exits within a liveness window and RESETS on survival (`registry.rs:1271-1283`) — per-answer burning without decay would let 3 reloads kill a healthy session. Counting respawn ANSWERS with reset-on-live means only a genuinely non-recovering loop trips the cap. Residual A19 (accepted): the next-wave client's reconcile cadence is unpinned — REVISIT the cap value/semantics when that client lands; leave this note in the module.)
 
 (d) `terminal.rs` `handle_pane_reconcile` (before the `catch_unwind` at `:1932`):
 
 ```rust
+// Built ONCE per reconcile request and reused for any re-derivation of deps
+// (B1's warming deferral re-derives via rebuild_deps — rebuilding the
+// snapshot would double-burn the respawn counter; V9 §3.6).
 let fresh_agent_snapshot = if pane_reconcile_fresh_agent_v1
     && request.panes.iter().any(|p| p.kind.as_deref() == Some("fresh-agent"))
 {
@@ -1768,7 +2213,7 @@ let fresh_agent_snapshot = if pane_reconcile_fresh_agent_v1
 };
 ```
 
-and add `fresh_agent: fresh_agent_snapshot.as_ref()` to the `ReconcileDeps` literal.
+and add `fresh_agent: fresh_agent_snapshot.as_ref()` to the `ReconcileDeps` literal. ALSO update the `pane.reconcile.request` doc comment above `handle_pane_reconcile` (`terminal.rs:1905-1910`, "a PURE READ over the terminal registry × identity registry × disk index"): the terminal sources remain a pure read, but the capability-gated fresh-agent snapshot now mutates the per-boot respawn counter (bounded per (provider, sessionId); reset when the session resolves Live) — say exactly that in the comment so the documented invariant stays truthful (V2/A7's secondary finding).
 
 (e) `reconcile.rs` — the WHOLE diff (plus the field):
 
@@ -1802,74 +2247,107 @@ git commit -m "feat(ws): fresh-agent panes enter the reconcile verdict system be
 ### Task 14: E2E — settings survive restart (3 providers) + codex crash degradation banner
 
 **Files:**
-- Modify: `test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs` (crash knob)
+- Modify: `test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs` (crash-once knob)
+- Modify: `test/e2e-browser/fixtures/fake-opencode.cjs` (audit the parsed prompt body — V4/A5)
 - Create: `test/e2e-browser/specs/freshagent-settings-resume-rust.spec.ts`
 - Modify: `test/e2e-browser/playwright.config.ts` (add the spec to BOTH `RUST_ONLY_SPECS` (~line 90) and the `rust-chromium` project `testMatch` (~line 250))
 
 **Interfaces:**
-- Consumes: `RustServer` (`test/e2e-browser/helpers/rust-server.ts`): `start()`, `restartAbrupt()` (SIGKILL + reboot on same home/port/token), `{env, setupHome}` options. `bootWall(page, {env, setupHome})` from the wall spec's helper pattern. Fakes: `CODEX_CMD="node <fake-app-server.mjs>"` + `FAKE_CODEX_APP_SERVER_BEHAVIOR` (JSON, supports `appendThreadOperationLogPath` → JSONL `{method, threadId, params}`); `OPENCODE_CMD` + `FAKE_OPENCODE_AUDIT_LOG`; `FRESHELL_CLAUDE_SIDECAR` + `FAKE_CLAUDE_SIDECAR_LOG` (JSONL of every inbound message). REST agent API: `POST /api/tabs` with `agent`/`model`/`effort` params; `POST /api/panes/:id/send-keys`.
-- Primary donor spec: `test/e2e-browser/specs/freshclaude-restart-parity-rust.spec.ts:212-310` — copy its boot, pane-creation, send, restart, and re-attach patterns verbatim; the NEW content of each test is its final assertion block, given below in full.
+- Consumes: `RustServer` (`test/e2e-browser/helpers/rust-server.ts`): `start()`, `restartAbrupt()` (SIGKILL + reboot on same home/port/token), `{env, setupHome}` options. `bootWall(page, {env, setupHome})` from the wall spec's helper pattern (test 4 only — tests 1-3 drive the server directly, no browser page needed). Fakes: `CODEX_CMD="node <fake-app-server.mjs>"` + `FAKE_CODEX_APP_SERVER_BEHAVIOR` (inline env JSON, STATIC per server boot — nothing can be rewritten between sidecar spawns, V4/A6; supports `appendThreadOperationLogPath` → JSONL `{method, threadId, params}`); `OPENCODE_CMD` + `FAKE_OPENCODE_AUDIT_LOG` (JSONL entries keyed by `event` field — there is NO `path` field, V4/A5); `FRESHELL_CLAUDE_SIDECAR` + `FAKE_CLAUDE_SIDECAR_LOG` (JSONL of every inbound message).
+- SEEDING SURFACES (V3/A3 — REST `POST /api/tabs` rejects `agent != "opencode"` with 400, `crates/freshell-freshagent/src/lib.rs:1268`; REST send-keys/capture 404 for codex/claude sessions, which never enter the REST `panes` map):
+  - **codex + claude (tests 1/3/4 creation):** raw WS `freshAgent.create` (schema `crates/freshell-protocol/src/client_messages.rs:457-488`, camelCase: `requestId`, `sessionType`, `cwd`, `model`, `effort`, `permissionMode`, `sandbox`, `resumeSessionId`; codex carries model/sandbox/approvalPolicy on `thread/start` and effort per `turn/start`; claude forwards model/permissionMode/effort to the sidecar verbatim), driven via `freshAgent.send`. Dispatch is gated on `settings.freshAgent.enabled=true` (`terminal.rs:567`) — PATCH settings first. Donor for the whole flow (settings-PATCH + raw create + created-wait): `crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs` (raw create at `:295`); port the same message sequence to the spec's Node context (`fetch` + `WebSocket`), following the hello/ready handshake the sibling specs use — verify exact PATCH endpoint shape against the donor during implementation.
+  - **opencode (test 2):** keeps REST `POST /api/tabs` `{ agent: 'opencode', model, effort }` + `POST /api/panes/:id/send-keys` (the REST surface is opencode-only and honors model/effort per-turn, V3 §2).
+- RESUME TOPOLOGY (V2/A4 — after `page.reload()` the frozen client NEVER sends `freshAgent.attach`; it sends `freshAgent.create{resumeSessionId, sessionRef}` (persistMiddleware strips `sessionId`). Attach fires only on `ws.onReconnect` WITHOUT reload. Each test below states which path it exercises and why.)
+- Donor spec for boot/env/restart plumbing: `test/e2e-browser/specs/freshclaude-restart-parity-rust.spec.ts:212-310`; donor for banner/UI flow (test 4): the wall/restore-matrix pane-creation patterns.
 
-- [ ] **Step 1: Add the crash knob to the codex fake (test infra, no prod code)**
+- [ ] **Step 1: Extend the two fakes (test infra, no prod code)**
 
-In `fake-app-server.mjs`, where inbound prompt/turn requests are handled, honor a new behavior field:
+(a) `fake-app-server.mjs` — crash-ONCE knob (V4/A6: behavior is inline env JSON, static per server boot; the existing `exitProcessAfterMethodsOnce` is unsuitable — it exits 0 AFTER responding and its per-process "once" set makes the respawned sidecar exit again, looping). In the single socket message handler (`:415-572`), before dispatching `turn/start`:
 
 ```js
-// behavior.crashOnPromptMarker: if the inbound turn text contains this
-// marker, hard-exit to simulate a sidecar crash mid-session.
-if (behavior.crashOnPromptMarker && promptText.includes(behavior.crashOnPromptMarker)) {
+// behavior.crashOnPromptMarker + behavior.crashOnPromptMarkerOnceMarkerPath:
+// if the inbound turn input contains the marker AND this process wins the
+// cross-process once-claim (reuse the existing claimCrossProcessOnce helper,
+// :376-391 — 'wx' marker file), hard-exit(1) to simulate a mid-turn crash.
+// The respawned process finds the marker file and proceeds normally.
+if (
+  method === 'turn/start' &&
+  behavior.crashOnPromptMarker &&
+  JSON.stringify(message.params?.input ?? '').includes(behavior.crashOnPromptMarker) &&
+  claimCrossProcessOnce(behavior.crashOnPromptMarkerOnceMarkerPath, 'crashOnPromptMarker')
+) {
   process.exit(1);
 }
 ```
 
+(b) `fake-opencode.cjs` — audit the parsed prompt body (V4/A5: today the `prompt_async` handler parses the body but audits only `{event:'prompt_async', sessionId, routeDirectory, directory, prompt}`; `model`/`effort`/`reasoningEffort` are DISCARDED). In the prompt POST handler (`:776-809`), add the parsed body fields to the `appendAudit` payload at `:793-799`, e.g. `body: { model: body.model, effort: body.effort, reasoningEffort: body.reasoningEffort }` (~2 lines).
+
 - [ ] **Step 2: Write the four e2e tests (they fail against pre-fix behavior only where the fix is server-side; write them to assert the FIXED contract)**
 
 `freshagent-settings-resume-rust.spec.ts` — one `test.describe` with four tests, each booting its own `RustServer` on an ephemeral port with the provider's fake wired via env (donor patterns), each cleaning up in `finally`/`afterEach`:
 
-1. **`codex: restart → attach resumes with the user's model, not defaults`**
-   - Boot with `CODEX_CMD` fake + behavior including `appendThreadOperationLogPath: <tmp>/codex-ops.jsonl` and a resume-succeeds script.
-   - Create a codex fresh-agent pane WITH an explicit model (donor pane-creation pattern; if the creation surface in the donor doesn't carry model, use the REST agent API: `POST ${baseUrl}/api/tabs` with `{ agent: 'codex', model: 'gpt-5.3-codex' }` and the auth token).
-   - Send one message; wait for the reply (donor wait pattern).
-   - `await server.restartAbrupt()`; `await page.reload()`; wait for the pane to re-attach (donor wait).
+1. **`codex: create-shaped resume after restart carries the recorded model`** — exercises the CREATE-resume path (R1 + ledger-fill), the exact wire shape the frozen client sends after `page.reload()` (V2/A4). No browser page.
+   - Boot with `CODEX_CMD` fake + static behavior including `appendThreadOperationLogPath: <tmp>/codex-ops.jsonl` (resume succeeds by default).
+   - PATCH `settings.freshAgent.enabled=true`; open a raw WS; `freshAgent.create` with `{ sessionType: 'freshcodex', model: 'gpt-5.3-codex', sandbox: 'workspace-write', cwd: <tmp> }`; await `freshAgent.created` (capture the durable thread id); one `freshAgent.send`; await the turn.
+   - `await server.restartAbrupt()`; open a NEW raw WS; send `freshAgent.create` with `{ sessionType: 'freshcodex', resumeSessionId: <thread id> }` and NO model/sandbox — proving the values come from the LEDGER (R1 fills gaps, Task 5(d)), not from the message; await the created/attach-equivalent reply.
    - Assertion block:
    ```ts
    const ops = fs.readFileSync(opLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
    const resume = ops.find((o) => o.method === 'thread/resume')
    expect(resume, 'restart must resume the durable thread').toBeTruthy()
    expect(resume.params.model, 'resume must carry the recorded model, not null').toBe('gpt-5.3-codex')
+   expect(resume.params.sandbox, 'resume must carry the recorded sandbox').toBe('workspace-write')
    ```
-   (Sandbox/permissionMode reapplication is pinned at the Rust layer in Task 5 — the creation surface here only carries `model`/`effort`.)
 
-2. **`opencode: restart → attach → next send carries the recorded model/effort`**
+2. **`opencode: create-shaped resume after restart → next send carries the recorded model/effort`** — REST seeding (V3: opencode-only surface) + the create-shaped resume the frozen client sends post-reload (V2/A4; honored server-side by Task 8(b) — the P1.13 pin mechanism). No browser page.
    - Boot with `OPENCODE_CMD` fake + `FAKE_OPENCODE_AUDIT_LOG`.
-   - Create an opencode pane with `{ agent: 'opencode', model: 'big-model', effort: 'high' }`; send once (materializes `ses_*`); `restartAbrupt()`; reload; wait for re-attach; send a second message.
+   - REST `POST /api/tabs` `{ agent: 'opencode', model: 'big-model', effort: 'high' }`; REST send-keys once (materializes `ses_*` — Task 7's REST-site ledger write records the settings; read the `ses_*` id from the audit log's `prompt_async` entry `sessionId`).
+   - `restartAbrupt()` (the REST panes map is in-memory and gone — post-restart driving is via WS). Open a raw WS (settings PATCH as in test 1); send `freshAgent.create{ sessionType: 'freshopencode', resumeSessionId: <ses_*> }` with NO model/effort; await created (must answer the `ses_*` id, not a placeholder); `freshAgent.send` one message with NO per-send settings.
    - Assertion block:
    ```ts
    const audit = fs.readFileSync(auditLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
-   const prompts = audit.filter((e) => e.path && String(e.path).includes('/message')) // the prompt_async POSTs (match the fake's actual audit shape)
+   const prompts = audit.filter((e) => e.event === 'prompt_async') // V4: entries have `event`, never `path`
    const afterRestart = prompts[prompts.length - 1]
-   expect(JSON.stringify(afterRestart), 'post-restart send must carry the recorded model').toContain('big-model')
-   expect(JSON.stringify(afterRestart), 'post-restart send must carry the recorded effort').toContain('high')
+   expect(afterRestart.body?.model ? JSON.stringify(afterRestart.body.model) : '', 'post-restart send must carry the recorded model').toContain('big-model')
+   expect(JSON.stringify(afterRestart.body ?? {}), 'post-restart send must carry the recorded effort').toContain('high')
    ```
+   (`body` is the field added in Step 1(b); assert on the audited body fields, matching the fake's actual shape at implementation time.)
 
-3. **`claude: restart → attach resume request carries model/permissionMode`**
+3. **`claude: attach resume request carries model/permissionMode`** — exercises the ATTACH path (`resume_for_attach`, Task 10's fix target). Attach is the no-reload restart topology: the frozen client sends it on `ws.onReconnect` without reload (V2/A4), and the donor spec proves attach-on-the-wire for claude. No browser page.
    - Boot with `FRESHELL_CLAUDE_SIDECAR` fake + `FAKE_CLAUDE_SIDECAR_LOG` (exactly the donor's env, `rust-server.ts` + donor `:212-310`).
-   - Create a freshclaude pane with an explicit model (donor creation; REST `{ agent: 'claude', model: 'opus-x' }` if the donor path doesn't carry model); send once; `restartAbrupt()`; reload; wait for the resume (donor wait — it already proves transcript parity).
+   - Settings PATCH; raw WS `freshAgent.create` `{ sessionType: 'freshclaude', model: 'opus-x', permissionMode: 'plan', cwd: <tmp> }`; await created + `sdk.session.init` handling (donor wait); capture the durable session id; one send.
+   - `restartAbrupt()`; new raw WS; send `freshAgent.attach { sessionId: <durable>, sessionType: 'freshclaude' }` (raw-attach donor: `crates/freshell-ws/tests/freshagent_claude_attach.rs:112`); await the resume.
    - Assertion block:
    ```ts
    const msgs = fs.readFileSync(sidecarLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
    const resumeCreate = msgs.filter((m) => m.msg && m.msg.resumeSessionId).pop()
    expect(resumeCreate, 'restart must issue a resume create').toBeTruthy()
    expect(resumeCreate.msg.model, 'resume must carry the recorded model, not null').toBe('opus-x')
+   expect(resumeCreate.msg.permissionMode, 'resume must carry the recorded permissionMode').toBe('plan')
    ```
 
-4. **`codex: crash respawn shows a visible memory-loss notice`**
-   - Boot with the codex fake, behavior `{ crashOnPromptMarker: 'CRASH_NOW', … }` and a follow-up behavior (rewritten between spawns, as the Rust tests do via the behavior file) whose `thread/resume` answers not-found so the respawn mints a new thread.
-   - Create a codex pane; send `CRASH_NOW` (sidecar exits); send another message (triggers crash-recovery respawn).
+4. **`codex: crash respawn shows a visible memory-loss notice`** — browser test (the banner is client UI); NO reload anywhere (the banner is in-memory Redux and does not survive reload — V1 N3).
+   - Boot with the codex fake and ONE static behavior for the whole test (V4/A6):
+   ```json
+   {
+     "overrides": { "thread/resume": { "error": { "code": -32602, "message": "thread not found" } } },
+     "crashOnPromptMarker": "CRASH_NOW",
+     "crashOnPromptMarkerOnceMarkerPath": "<tmp>/crash.once",
+     "appendThreadOperationLogPath": "<tmp>/thread-ops.jsonl"
+   }
+   ```
+   (The static `thread/resume` error is fine: the first spawn goes through `thread/start` — a fresh session never resumes — and the only resume attempt is the post-crash one, which must fail so the respawn mints a new thread.)
+   - `bootWall(page, …)`; create a codex fresh-agent pane through the client UI (donor pane-creation pattern from the wall/restore-matrix specs — no model needed here); send `CRASH_NOW` via the pane composer (sidecar exits 1, once); send another message (triggers crash-recovery respawn: `thread/resume` → not-found → new `thread/start`).
    - Assertion block:
    ```ts
    const banner = page.getByRole('alert').filter({ hasText: 'no longer has memory' })
    await expect(banner, 'memory loss must be user-visible, not just a server warn').toBeVisible({ timeout: 15000 })
+   // "New thread minted" = TWO thread/start entries in the op log. The fake
+   // reuses the same thread id (threadStartThreadId default) and errored
+   // thread/resume ops are NOT logged — do NOT assert id inequality or a
+   // logged resume (V4/A6).
+   const ops = fs.readFileSync(threadOpsPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
+   expect(ops.filter((o) => o.method === 'thread/start').length, 'respawn must mint a second thread').toBe(2)
    ```
 
 - [ ] **Step 3: Register the spec and run it**
@@ -1883,6 +2361,7 @@ Expected: ALL FOUR PASS (the server-side fixes landed in Tasks 4-10/13). If a te
 
 ```bash
 git add test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs \
+        test/e2e-browser/fixtures/fake-opencode.cjs \
         test/e2e-browser/specs/freshagent-settings-resume-rust.spec.ts \
         test/e2e-browser/playwright.config.ts
 git commit -m "test(e2e): per-provider settings survive restart + codex crash memory-loss banner (P1.13)"
@@ -1905,8 +2384,8 @@ npx playwright test --config test/e2e-browser/playwright.config.ts \
   --project=rust-chromium restore-contract-wall-rust -g "freshopencode: SIGKILL restore keeps"
 ```
 
-- If it reports an UNEXPECTED PASS (the pin now fails the run): the server-side fixes flipped it — go to Step 2a.
-- If it still fails inside the pin: read the failure; if the residual cause is client-side re-mint folding (next wave's scope), go to Step 2b.
+- EXPECTED OUTCOME (V2/A4): an UNEXPECTED PASS (the pin now fails the run) — the pin's mechanism is exactly Task 8(b)'s server-side fix: post-reload the frozen client sends `freshAgent.create{resumeSessionId: ses_*}` (never attach), and opencode's `handle_create` previously ignored `resume_session_id` and re-minted a placeholder. With the create path honoring it, the flip is achievable server-side. Go to Step 2a.
+- If it still fails inside the pin: read the failure; if the residual cause is genuinely client-side (next wave's scope), go to Step 2b — but do NOT narrow without evidence from the failure output; the attach-path story is no longer a valid reason (the client does not attach after reload).
 
 - [ ] **Step 2a: Flip — delete the pin**
 
@@ -1914,7 +2393,7 @@ Delete the `test.fail(e2eServerKind === 'rust', 'P1.8/P1.13 …')` line (and its
 
 - [ ] **Step 2b: Narrow — server side fixed, client folding pending**
 
-Update the pin's reason string to: `'P1.8 (§2.7, client folding — next wave): server resume now reapplies the ledger record (P1.13 done); post-reload client still re-mints a freshopencode-* placeholder'` and update the pin comment's dated observation + FLIP clause to name the client-folding lane. Re-run Step 1's command; expected: the pinned test is an expected failure (suite green).
+Only if Step 1 showed a genuinely client-side residual failure (NOT the placeholder re-mint — Task 8(b) fixed that server-side; V2): update the pin's reason string to name the ACTUAL observed residual cause, prefixed `'P1.8 (§2.7, client folding — next wave): server create-path resume + settings-from-ledger landed (P1.13 done); residual: <observed cause>'`, and update the pin comment's dated observation + FLIP clause to name the client-folding lane. Re-run Step 1's command; expected: the pinned test is an expected failure (suite green).
 
 - [ ] **Step 3: Full verification gates**
 
@@ -1944,12 +2423,14 @@ git commit -m "test(wall): flip/narrow P1.13 freshopencode settings pin - fresh-
 |---|---|
 | Ledger rows at codex thread/start, opencode session.materialized (+pending before), claude sdk.session.init | Tasks 4/7/9 Rust tests |
 | Resume-invocation record persisted + updated on user change (§4.2) | Task 1 round-trip; Task 7 `send_with_changed_settings_refreshes_the_binding` |
-| Codex resume-after-restart runs with user's model/sandbox (defect §2.6c) | Task 5 wire-level op-log test + Task 14 e2e test 1 |
-| Opencode resume keeps model/effort/cwd (defect §2.7b) | Task 8 Rust test + Task 14 e2e test 2 |
-| Claude resume keeps model/permissionMode/effort | Task 10 spawn-log test + Task 14 e2e test 3 |
-| "settings reset — reconfirm" breadcrumb = missing-record ALARM only | Tasks 5/8/10 SETTINGS_RESET alarm tests (frame emitted ONLY when the record is absent) |
+| Codex resume-after-restart runs with user's model/sandbox (defect §2.6c) | Task 5 wire-level op-log test + Task 14 e2e test 1 (create-shaped resume) |
+| Opencode resume keeps model/effort/cwd (defect §2.7b) + create path honors `resumeSessionId` (V2/A4) | Task 8 Rust tests (`resume_durable_session_reapplies…`, `create_with_resume_session_id_rebinds…`) + Task 14 e2e test 2 |
+| Claude resume keeps model/permissionMode/effort | Task 10 spawn-log test + Task 14 e2e test 3 (attach path) |
+| "settings reset — reconfirm" breadcrumb = anomaly ALARM only (V7/A10) | Tasks 5/8/10 tests: frame emitted ONLY when the ledger proves prior fresh-agent recording (`was_recorded` true) yet no snapshot is recoverable; never-recorded sessions (pre-ship/historical/sidebar) resume silently with defaults and write no defaults row |
+| Ledger write failures surfaced live, never silent (awaited-writes policy, V8/A11) | Task 2 fake Err test + Task 3 awaited round-trip + Task 4 `ledger_write_failure_is_surfaced…` |
+| G3 supersession on codex crash-respawn: retire+link written, claims answered from the chain terminus with `corrected` (V8/A14) | Task 1 `supersedes_retires_the_old_row…` + Task 12 `superseded_claim_is_answered…` + Task 13 `old_thread_claim_after_crash_respawn…` |
 | reconcile accepts kind:fresh-agent with attach/respawn/dead_session/fresh | Task 12 unit + Task 13 direct-WS tests (live / killed-resumable / transcript-deleted / never-existed) |
-| Dedupe + respawn caps for fresh agents | Task 13 `duplicate_session_claims…` + `respawn_cap_turns_the_fourth…` |
+| Dedupe + respawn cap (respawn ANSWERS only, reset-on-live — V2/A7; revisit cadence with next-wave client, residual A19) | Task 13 `duplicate_session_claims…` + `respawn_cap_turns_the_fourth…` + `a_session_resolving_live_clears…` |
 | Capability-gated; frozen client unaffected | Task 11 `without_the_capability…` (permanent regression guard) |
 | Codex crash-respawn degradation frame, user-visible TODAY | Task 6 broadcast test + Task 14 e2e banner test |
 | Flip P1.13-tagged wall pins this lane fixes | Task 15 |

From cc0444c112ef5b216081e5b0c6e5a6920362330a Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:01:46 -0700
Subject: [PATCH 10/87] feat(ws): delete retry verdict; bounded index-warming
 deferral yields error{index_warming}
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Task 2 of the reconcile-client-adoption plan: `retry` is deleted from the
pane.reconcile wire.

- freshell-protocol: `ReconcileVerdict::Retry` -> `ReconcileVerdict::Error`
  (wire "error", terminal per-pane error state, reason "index_warming" |
  "provider_unavailable"); `PaneVerdict.retry_after_ms` removed.
- freshell-ws reconcile: the Unknown-existence arm now derives
  error{index_warming}; RETRY_AFTER_MS repurposed as
  RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT (2000ms).
- freshell-ws terminal: handle_pane_reconcile performs at most ONE bounded
  deferral (WsState.reconcile_deferral_budget_ms, default 2000ms) when a
  derivation comes back warming, then re-derives exactly once - never loops.
  Plain bounded sleep: SessionIndex exposes no awaitable sweep-completion
  signal (peek()/is_fresh() are sync by design; a cold snapshot().await is
  unbounded), and the index-backed probe already kicks a detached refresh on
  every non-fresh read, so the sweep converges during the wait when it can.
- e2e synthetic client: reconcileUntilStable re-requests on
  error{index_warming} instead of the deleted retry verdict.

Honest expectation (pinned in the brief): a truly cold index scan exceeds
the budget, so error{index_warming} remains EXPECTED on cold boots; the
manual retry affordance (task 13) is the recovery path.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../freshell-protocol/src/server_messages.rs  |   9 +-
 .../freshell-protocol/tests/pane_reconcile.rs |  15 ++-
 crates/freshell-server/src/main.rs            |   3 +
 .../freshell-ws/src/amplifier_association.rs  |   1 +
 crates/freshell-ws/src/existence.rs           |   3 +-
 crates/freshell-ws/src/lib.rs                 |   9 ++
 .../freshell-ws/src/opencode_association.rs   |   1 +
 crates/freshell-ws/src/reconcile.rs           |  25 ++--
 crates/freshell-ws/src/terminal.rs            |  60 +++++++--
 .../tests/codex_managed_launch_e2e.rs         |   1 +
 .../tests/codex_session_ref_resume.rs         |   1 +
 crates/freshell-ws/tests/common/mod.rs        |   4 +
 .../tests/diag01_lifecycle_events.rs          |   1 +
 .../tests/freshagent_claude_attach.rs         |   1 +
 .../tests/freshagent_claude_kill_interrupt.rs |   1 +
 crates/freshell-ws/tests/hello_timeout.rs     |   1 +
 crates/freshell-ws/tests/keepalive.rs         |   1 +
 crates/freshell-ws/tests/max_payload.rs       |   1 +
 crates/freshell-ws/tests/origin_policy.rs     |   1 +
 crates/freshell-ws/tests/pane_reconcile.rs    | 127 +++++++++++++++++-
 .../tests/safe08_restore_diagnostics.rs       |   1 +
 .../freshell-ws/tests/term09_output_queue.rs  |   1 +
 .../specs/reconcile-handshake-rust.spec.ts    |  15 ++-
 23 files changed, 241 insertions(+), 42 deletions(-)

diff --git a/crates/freshell-protocol/src/server_messages.rs b/crates/freshell-protocol/src/server_messages.rs
index e16b8776c..240d8c032 100644
--- a/crates/freshell-protocol/src/server_messages.rs
+++ b/crates/freshell-protocol/src/server_messages.rs
@@ -688,8 +688,10 @@ pub enum ReconcileVerdict {
     Respawn,
     Fresh,
     DeadSession,
-    Retry,
     Invalid,
+    /// Terminal per-pane error state (replaces the deleted `retry`):
+    /// reason is one of "index_warming" | "provider_unavailable".
+    Error,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
@@ -708,12 +710,9 @@ pub struct PaneVerdict {
     /// Present iff the server overrode a differing client claim.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub corrected: Option<bool>,
-    /// fresh / dead_session / retry / invalid: machine-readable code.
+    /// fresh / dead_session / error / invalid: machine-readable code.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub reason: Option<String>,
-    /// retry only.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub retry_after_ms: Option<i64>,
     /// Row 2b (invariant I6): a newer duplicate generation exists for the same
     /// `createRequestId`; the client stays on its live attachment and this
     /// merely flags the duplicate `terminalId`.
diff --git a/crates/freshell-protocol/tests/pane_reconcile.rs b/crates/freshell-protocol/tests/pane_reconcile.rs
index d2d9701a9..4daa9b089 100644
--- a/crates/freshell-protocol/tests/pane_reconcile.rs
+++ b/crates/freshell-protocol/tests/pane_reconcile.rs
@@ -164,7 +164,6 @@ fn reconcile_result_serializes_verdicts_with_optional_fields_omitted() {
                 }),
                 corrected: Some(true),
                 reason: None,
-                retry_after_ms: None,
                 duplicate: None,
             },
             PaneVerdict {
@@ -174,7 +173,6 @@ fn reconcile_result_serializes_verdicts_with_optional_fields_omitted() {
                 session_ref: None,
                 corrected: None,
                 reason: Some("no_recoverable_identity".to_string()),
-                retry_after_ms: None,
                 duplicate: None,
             },
         ],
@@ -201,7 +199,7 @@ fn reconcile_verdict_wire_names_are_snake_case() {
         (ReconcileVerdict::Respawn, "respawn"),
         (ReconcileVerdict::Fresh, "fresh"),
         (ReconcileVerdict::DeadSession, "dead_session"),
-        (ReconcileVerdict::Retry, "retry"),
+        (ReconcileVerdict::Error, "error"),
         (ReconcileVerdict::Invalid, "invalid"),
     ] {
         assert_eq!(serde_json::to_value(verdict).unwrap(), json!(name));
@@ -209,20 +207,23 @@ fn reconcile_verdict_wire_names_are_snake_case() {
 }
 
 #[test]
-fn retry_verdict_carries_retry_after_ms() {
+fn error_verdict_carries_reason_and_no_retry_after_ms() {
+    // `retry` is deleted from the wire: the terminal per-pane error state
+    // replaces it and carries only a machine-readable reason — never a
+    // `retryAfterMs` cadence hint.
     let verdict = PaneVerdict {
         pane_key: "p".to_string(),
-        verdict: ReconcileVerdict::Retry,
+        verdict: ReconcileVerdict::Error,
         terminal_id: None,
         session_ref: None,
         corrected: None,
         reason: Some("index_warming".to_string()),
-        retry_after_ms: Some(2000),
         duplicate: None,
     };
     let wire = serde_json::to_value(&verdict).expect("serializes");
-    assert_eq!(wire["retryAfterMs"], 2000);
+    assert_eq!(wire["verdict"], "error");
     assert_eq!(wire["reason"], "index_warming");
+    assert!(wire.get("retryAfterMs").is_none());
 }
 
 // --- error codes --------------------------------------------------------------
diff --git a/crates/freshell-server/src/main.rs b/crates/freshell-server/src/main.rs
index 3457cffc7..9eab13f14 100644
--- a/crates/freshell-server/src/main.rs
+++ b/crates/freshell-server/src/main.rs
@@ -447,6 +447,9 @@ async fn main() -> ExitCode {
             )),
             None => std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
         },
+        // §5.3 row 5: the ONE bounded index-warming deferral's budget
+        // (council-pinned single deferral, default 2000ms).
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
         auth_token: Arc::clone(&auth_token),
         // Shared (not moved) so `GET /api/health` reports the SAME `instanceId`.
         server_instance_id: Arc::clone(&server_instance_id),
diff --git a/crates/freshell-ws/src/amplifier_association.rs b/crates/freshell-ws/src/amplifier_association.rs
index 35c08f49c..6f3a83e9b 100644
--- a/crates/freshell-ws/src/amplifier_association.rs
+++ b/crates/freshell-ws/src/amplifier_association.rs
@@ -316,6 +316,7 @@ mod tests {
             config_fallback: None,
             amplifier_locator: Some(StdArc::new(AmplifierLocator::new(amplifier_home))),
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+            reconcile_deferral_budget_ms: crate::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
             opencode_locator: None,
             activity: None,
         };
diff --git a/crates/freshell-ws/src/existence.rs b/crates/freshell-ws/src/existence.rs
index bc88eaa44..8e110facf 100644
--- a/crates/freshell-ws/src/existence.rs
+++ b/crates/freshell-ws/src/existence.rs
@@ -9,7 +9,8 @@
 //!   downstream), never `Unknown`.
 //! * [`SessionExistence::Unknown`] is reserved strictly for a *cold index on a
 //!   known provider* (boot sweep not finished / index unavailable) — it is
-//!   what makes the `retry` verdict honest instead of guessing (§5.3 row 5).
+//!   what makes the `error{index_warming}` verdict honest instead of
+//!   guessing (§5.3 row 5).
 //!
 //! Trait-shaped so crate tests inject a fake; the real implementation is
 //! backed by the shared `freshell_sessions::directory_index::SessionIndex`
diff --git a/crates/freshell-ws/src/lib.rs b/crates/freshell-ws/src/lib.rs
index d1b9d9f8d..4323a3b89 100644
--- a/crates/freshell-ws/src/lib.rs
+++ b/crates/freshell-ws/src/lib.rs
@@ -229,6 +229,14 @@ pub struct WsState {
     /// of `identity` and the locator handles); [`crate::existence::NoIndexProbe`]
     /// when no provider home resolves.
     pub session_existence: crate::existence::SharedExistenceProbe,
+    /// Reconciliation handshake (design §5.3 row 5): the budget, in
+    /// milliseconds, for `handle_pane_reconcile`'s ONE bounded deferral when
+    /// a derivation comes back `error{index_warming}` — wait at most this
+    /// long, re-derive once, answer. Never loops. Default
+    /// [`crate::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT`] (2000ms);
+    /// tests shrink it so the warming paths are observable without a real
+    /// 2s wait (mirrors `ping_interval_ms` / `hello_timeout_ms`).
+    pub reconcile_deferral_budget_ms: u64,
     /// The opencode terminal-pane session locator (restore-across-restart fix,
     /// `docs/plans/2026-07-18-opencode-terminal-restore-spec.md`): correlates a
     /// fresh opencode PTY's first Enter/submit (or a row written at spawn) with
@@ -741,6 +749,7 @@ mod tests {
             opencode_locator: None,
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+            reconcile_deferral_budget_ms: crate::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
         }
     }
 
diff --git a/crates/freshell-ws/src/opencode_association.rs b/crates/freshell-ws/src/opencode_association.rs
index df20d50a6..a8231163b 100644
--- a/crates/freshell-ws/src/opencode_association.rs
+++ b/crates/freshell-ws/src/opencode_association.rs
@@ -291,6 +291,7 @@ mod tests {
             opencode_locator: Some(StdArc::new(OpencodeLocator::new(data_home))),
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+            reconcile_deferral_budget_ms: crate::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
         };
         (state, rx)
     }
diff --git a/crates/freshell-ws/src/reconcile.rs b/crates/freshell-ws/src/reconcile.rs
index b82eef02e..c4340df55 100644
--- a/crates/freshell-ws/src/reconcile.rs
+++ b/crates/freshell-ws/src/reconcile.rs
@@ -18,10 +18,11 @@ use crate::identity::TerminalIdentityRegistry;
 /// never silently truncated.
 pub const MAX_RECONCILE_PANES: usize = 200;
 
-/// §5.3 row 5 placeholder cadence for `retry(index_warming)` (the retry
-/// mechanism itself is an OPEN user decision, design §8.0 — this implements
-/// the documented placeholder).
-pub const RETRY_AFTER_MS: i64 = 2000;
+/// §5.3 row 5 default budget for the handler's ONE bounded deferral before
+/// re-deriving verdicts once (council-pinned single deferral): when a
+/// derivation comes back `error{index_warming}`, `handle_pane_reconcile`
+/// waits at most this long, re-derives once, and answers — never loops.
+pub const RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT: u64 = 2000;
 
 /// The read-only inputs of the derivation (§5.1) — all shared handles that
 /// already live on [`crate::WsState`].
@@ -60,7 +61,6 @@ fn invalid(pane: &ReconcilePane, reason: &str) -> PaneVerdict {
         session_ref: None,
         corrected: None,
         reason: Some(reason.to_string()),
-        retry_after_ms: None,
         duplicate: None,
     }
 }
@@ -73,7 +73,6 @@ fn base(pane: &ReconcilePane, verdict: ReconcileVerdict) -> PaneVerdict {
         session_ref: None,
         corrected: None,
         reason: None,
-        retry_after_ms: None,
         duplicate: None,
     }
 }
@@ -248,8 +247,7 @@ fn verdict_for_pane(deps: &ReconcileDeps<'_>, pane: &ReconcilePane) -> PaneVerdi
         }
         SessionExistence::Unknown => PaneVerdict {
             reason: Some("index_warming".to_string()),
-            retry_after_ms: Some(RETRY_AFTER_MS),
-            ..base(pane, ReconcileVerdict::Retry)
+            ..base(pane, ReconcileVerdict::Error)
         },
     }
 }
@@ -477,18 +475,19 @@ mod tests {
         );
     }
 
-    /// Row 5 (§9.1 test 6): cold index on a known provider → honest retry,
-    /// never dead_session, never optimistic respawn.
+    /// Row 5 (§9.1 test 6): cold index on a known provider → honest
+    /// error{index_warming}, never dead_session, never optimistic respawn.
+    /// (`retry` is deleted from the wire; the handler's bounded single
+    /// deferral is the recovery attempt, `terminal.rs`.)
     #[test]
-    fn row5_unknown_existence_yields_retry_with_backoff() {
+    fn row5_unknown_existence_yields_error_index_warming() {
         let f = Fixture::new();
         f.probe.set("claude", "s-cold", SessionExistence::Unknown);
         let mut p = pane("cr-5");
         p.session_ref = Some(sref("claude", "s-cold"));
         let v = f.one(p);
-        assert_eq!(v.verdict, ReconcileVerdict::Retry);
+        assert_eq!(v.verdict, ReconcileVerdict::Error);
         assert_eq!(v.reason.as_deref(), Some("index_warming"));
-        assert_eq!(v.retry_after_ms, Some(RETRY_AFTER_MS));
     }
 
     /// Row 6: no terminalId at all, just a claim that IS on disk → respawn
diff --git a/crates/freshell-ws/src/terminal.rs b/crates/freshell-ws/src/terminal.rs
index eec05ee2b..6e10e1b9c 100644
--- a/crates/freshell-ws/src/terminal.rs
+++ b/crates/freshell-ws/src/terminal.rs
@@ -1926,16 +1926,21 @@ async fn handle_pane_reconcile(
         )
         .await;
     }
-    let deps = crate::reconcile::ReconcileDeps {
-        registry: &state.registry,
-        identity: &state.identity,
-        existence: state.session_existence.as_ref(),
-    };
     // §8 frame-level failure: a panicking derivation (poisoned lock) must
-    // surface as an explicit error frame, never silence.
-    let verdicts = match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-        crate::reconcile::derive_verdicts(&deps, &request.panes)
-    })) {
+    // surface as an explicit error frame, never silence. The deps are rebuilt
+    // per derivation so nothing borrowed for the pure read is ever held
+    // across the deferral await below.
+    let derive = || {
+        let deps = crate::reconcile::ReconcileDeps {
+            registry: &state.registry,
+            identity: &state.identity,
+            existence: state.session_existence.as_ref(),
+        };
+        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            crate::reconcile::derive_verdicts(&deps, &request.panes)
+        }))
+    };
+    let mut verdicts = match derive() {
         Ok(verdicts) => verdicts,
         Err(_) => {
             return send_create_error(
@@ -1947,6 +1952,41 @@ async fn handle_pane_reconcile(
             .await;
         }
     };
+    // §5.3 row 5: ONE bounded deferral when the index is still warming, then
+    // exactly one re-derivation — never a loop. The wait is a plain bounded
+    // sleep: the `SessionIndex` behind the probe exposes no sweep-completion
+    // signal to await (`peek()`/`is_fresh()` are sync and non-blocking by
+    // design, and `snapshot().await` on a truly cold index runs the sweep
+    // inline for potentially minutes — unbounded, so unusable here). The
+    // honest expectation stands: a truly cold scan takes far longer than the
+    // budget, so `error{index_warming}` is EXPECTED on cold boots and the
+    // client's manual retry affordance is the recovery path. The stall is
+    // delay-only and scoped to THIS connection's select loop, bounded by the
+    // budget (default 2000ms, shrunk in tests).
+    let warming = |vs: &[freshell_protocol::PaneVerdict]| {
+        vs.iter().any(|v| {
+            matches!(v.verdict, freshell_protocol::ReconcileVerdict::Error)
+                && v.reason.as_deref() == Some("index_warming")
+        })
+    };
+    if warming(&verdicts) {
+        tokio::time::sleep(std::time::Duration::from_millis(
+            state.reconcile_deferral_budget_ms,
+        ))
+        .await;
+        verdicts = match derive() {
+            Ok(verdicts) => verdicts,
+            Err(_) => {
+                return send_create_error(
+                    ws_tx,
+                    ErrorCode::ReconcileUnavailable,
+                    "reconcile derivation failed; keep current state and re-send".to_string(),
+                    &request.reconcile_id,
+                )
+                .await;
+            }
+        };
+    }
     let result = ServerMessage::PaneReconcileResult(freshell_protocol::PaneReconcileResult {
         reconcile_id: request.reconcile_id,
         boot_id: state.boot_id.as_ref().clone(),
@@ -3195,6 +3235,7 @@ mod terminals_changed_tests {
             opencode_locator: None,
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+            reconcile_deferral_budget_ms: crate::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
         };
         (state, rx)
     }
@@ -3402,6 +3443,7 @@ mod terminal_meta_created_tests {
             opencode_locator: None,
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+            reconcile_deferral_budget_ms: crate::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
         };
         (state, rx)
     }
diff --git a/crates/freshell-ws/tests/codex_managed_launch_e2e.rs b/crates/freshell-ws/tests/codex_managed_launch_e2e.rs
index 3c87985f9..46aaad290 100644
--- a/crates/freshell-ws/tests/codex_managed_launch_e2e.rs
+++ b/crates/freshell-ws/tests/codex_managed_launch_e2e.rs
@@ -155,6 +155,7 @@ async fn spawn_server() -> (String, freshell_terminal::TerminalRegistry) {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/codex_session_ref_resume.rs b/crates/freshell-ws/tests/codex_session_ref_resume.rs
index 57bc9d155..71e3cbefc 100644
--- a/crates/freshell-ws/tests/codex_session_ref_resume.rs
+++ b/crates/freshell-ws/tests/codex_session_ref_resume.rs
@@ -148,6 +148,7 @@ async fn spawn_server() -> (String, freshell_terminal::TerminalRegistry) {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/common/mod.rs b/crates/freshell-ws/tests/common/mod.rs
index 778e734e1..ce58395af 100644
--- a/crates/freshell-ws/tests/common/mod.rs
+++ b/crates/freshell-ws/tests/common/mod.rs
@@ -136,6 +136,7 @@ pub async fn spawn_server_with_specs(
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
@@ -216,6 +217,7 @@ pub async fn spawn_server_with_ledger(
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
@@ -292,6 +294,7 @@ pub async fn spawn_server_with_specs_and_activity(
         opencode_locator: None,
         activity: Some(activity_hub.clone()),
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
@@ -357,6 +360,7 @@ pub async fn spawn_server_with_create_protect(
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/diag01_lifecycle_events.rs b/crates/freshell-ws/tests/diag01_lifecycle_events.rs
index 912db6baf..5e787e8ed 100644
--- a/crates/freshell-ws/tests/diag01_lifecycle_events.rs
+++ b/crates/freshell-ws/tests/diag01_lifecycle_events.rs
@@ -172,6 +172,7 @@ async fn spawn_server(ping_interval_ms: u64) -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/freshagent_claude_attach.rs b/crates/freshell-ws/tests/freshagent_claude_attach.rs
index 6014b3f3b..d9a2151df 100644
--- a/crates/freshell-ws/tests/freshagent_claude_attach.rs
+++ b/crates/freshell-ws/tests/freshagent_claude_attach.rs
@@ -176,6 +176,7 @@ async fn spawn_server() -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs b/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs
index df44c89ef..03045e0a2 100644
--- a/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs
+++ b/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs
@@ -207,6 +207,7 @@ async fn spawn_server() -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/hello_timeout.rs b/crates/freshell-ws/tests/hello_timeout.rs
index c3d08eec0..e66e01be6 100644
--- a/crates/freshell-ws/tests/hello_timeout.rs
+++ b/crates/freshell-ws/tests/hello_timeout.rs
@@ -92,6 +92,7 @@ async fn spawn_server(hello_timeout_ms: u64) -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/keepalive.rs b/crates/freshell-ws/tests/keepalive.rs
index 37132e772..fff709e98 100644
--- a/crates/freshell-ws/tests/keepalive.rs
+++ b/crates/freshell-ws/tests/keepalive.rs
@@ -93,6 +93,7 @@ async fn spawn_server(
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/max_payload.rs b/crates/freshell-ws/tests/max_payload.rs
index aa9a0b06c..e4e169c72 100644
--- a/crates/freshell-ws/tests/max_payload.rs
+++ b/crates/freshell-ws/tests/max_payload.rs
@@ -93,6 +93,7 @@ async fn spawn_server(ws_max_payload_bytes: usize) -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/origin_policy.rs b/crates/freshell-ws/tests/origin_policy.rs
index b8f197f4f..311dae044 100644
--- a/crates/freshell-ws/tests/origin_policy.rs
+++ b/crates/freshell-ws/tests/origin_policy.rs
@@ -83,6 +83,7 @@ async fn spawn_server(allowed_origins: Vec<String>) -> (String, String) {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/pane_reconcile.rs b/crates/freshell-ws/tests/pane_reconcile.rs
index c1db5b723..a070b4852 100644
--- a/crates/freshell-ws/tests/pane_reconcile.rs
+++ b/crates/freshell-ws/tests/pane_reconcile.rs
@@ -57,10 +57,64 @@ struct Server {
     identity: freshell_ws::identity::TerminalIdentityRegistry,
 }
 
+/// Test probe that answers `exists` from a scripted sequence (pops from the
+/// Vec, repeats the last answer forever) — how the deferral tests simulate an
+/// index that warms up (or never does) between derivations.
+struct FlippingProbe {
+    answers: std::sync::Mutex<std::collections::VecDeque<freshell_ws::existence::SessionExistence>>,
+    last: std::sync::Mutex<freshell_ws::existence::SessionExistence>,
+}
+
+impl FlippingProbe {
+    fn new(answers: Vec<freshell_ws::existence::SessionExistence>) -> Self {
+        let last = *answers.last().expect("at least one scripted answer");
+        Self {
+            answers: std::sync::Mutex::new(answers.into_iter().collect()),
+            last: std::sync::Mutex::new(last),
+        }
+    }
+}
+
+impl freshell_ws::existence::SessionExistenceProbe for FlippingProbe {
+    fn exists(
+        &self,
+        _provider: &str,
+        _session_id: &str,
+    ) -> freshell_ws::existence::SessionExistence {
+        match self.answers.lock().unwrap().pop_front() {
+            Some(answer) => answer,
+            None => *self.last.lock().unwrap(),
+        }
+    }
+
+    fn ever_observed(&self, _provider: &str, _session_id: &str) -> bool {
+        false
+    }
+}
+
 /// Real axum server on an ephemeral loopback port. Returns handles to the
 /// SHARED registry + identity registry so tests can seed generations
 /// deterministically (the §9.1 headless convention).
 async fn spawn_server() -> Server {
+    spawn_server_with(|_| {}).await
+}
+
+/// [`spawn_server`] with a state mutator (e.g. shrink the deferral budget so
+/// the warming tests never wait a real 2s).
+async fn spawn_server_with(mutate: impl FnOnce(&mut WsState)) -> Server {
+    spawn_server_with_probe(
+        std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        mutate,
+    )
+    .await
+}
+
+/// [`spawn_server_with`] with an injected existence probe (design §5.1: the
+/// disk-truth input is a test fake).
+async fn spawn_server_with_probe(
+    probe: freshell_ws::existence::SharedExistenceProbe,
+    mutate: impl FnOnce(&mut WsState),
+) -> Server {
     let auth_token = Arc::new(AUTH_TOKEN.to_string());
     let broadcast_tx = Arc::new(tokio::sync::broadcast::channel::<String>(64).0);
     let settings =
@@ -68,7 +122,7 @@ async fn spawn_server() -> Server {
     let registry = freshell_terminal::TerminalRegistry::new();
     let identity = freshell_ws::identity::TerminalIdentityRegistry::new();
 
-    let state = WsState {
+    let mut state = WsState {
         pane_ledger: std::sync::Arc::new(freshell_ws::pane_ledger::PaneLedger::disabled()),
         identity: identity.clone(),
         auth_token: Arc::clone(&auth_token),
@@ -106,8 +160,10 @@ async fn spawn_server() -> Server {
         amplifier_locator: None,
         opencode_locator: None,
         activity: None,
-        session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        session_existence: probe,
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
+    mutate(&mut state);
 
     let router = freshell_ws::router(state);
     let listener = TcpListener::bind("127.0.0.1:0")
@@ -193,6 +249,21 @@ fn reconcile_request(reconcile_id: &str, panes: serde_json::Value) -> WsMessage
     )
 }
 
+/// One-pane request whose only recoverable identity is a structured claim —
+/// existence-probe-driven rows (5/warming) are reached deterministically.
+fn reconcile_request_with_session_ref(provider: &str, session_id: &str) -> WsMessage {
+    reconcile_request(
+        "rec-warming",
+        serde_json::json!([{
+            "paneKey": "pk-warm",
+            "kind": "terminal",
+            "mode": provider,
+            "createRequestId": format!("cr-{session_id}"),
+            "sessionRef": { "provider": provider, "sessionId": session_id }
+        }]),
+    )
+}
+
 fn headless(server: &Server, id: &str, key: Option<&str>, mode: &str, created_at: i64) {
     server
         .registry
@@ -537,3 +608,55 @@ async fn frozen_client_create_path_is_unchanged_no_dedupe() {
     server.registry.kill(&id1);
     server.registry.kill(&id2);
 }
+
+// --- 9.1.6 index warming: error{index_warming} + bounded single deferral ----------
+
+/// warming-never-completes (council red test): a probe pinned to Unknown
+/// forever must yield error{index_warming} after ONE bounded deferral —
+/// never a hang, never a fake fresh/dead_session.
+#[tokio::test]
+async fn warming_never_completes_yields_error_index_warming() {
+    // Server with deferral budget shrunk for tests (50ms) and the default
+    // NoIndexProbe (always Unknown for known providers).
+    let server = spawn_server_with(|state| state.reconcile_deferral_budget_ms = 50).await;
+    let (mut ws, _ready) = connect(&server.url, true).await;
+    let started = std::time::Instant::now();
+    ws.send(reconcile_request_with_session_ref("claude", "sess-1"))
+        .await
+        .expect("send request");
+    let result = next_frame_of_type(&mut ws, "pane.reconcile.result").await;
+    assert!(
+        started.elapsed() < std::time::Duration::from_secs(2),
+        "bounded, single deferral"
+    );
+    let v = &result["verdicts"][0];
+    assert_eq!(v["verdict"], "error");
+    assert_eq!(v["reason"], "index_warming");
+    assert!(
+        v.get("retryAfterMs").is_none(),
+        "retry is deleted from the wire"
+    );
+}
+
+/// The deferral is real: index warms during the wait -> the SECOND derivation
+/// answers with the warm verdict, not error.
+#[tokio::test]
+async fn warming_resolves_during_deferral_rederives() {
+    // Fake probe: first call Unknown, subsequent calls Absent (never observed
+    // -> per existing rules the verdict for a never-observed identity is
+    // fresh{identity_never_observed}).
+    let probe = FlippingProbe::new(vec![
+        freshell_ws::existence::SessionExistence::Unknown,
+        freshell_ws::existence::SessionExistence::Absent,
+    ]);
+    let server = spawn_server_with_probe(std::sync::Arc::new(probe), |state| {
+        state.reconcile_deferral_budget_ms = 50
+    })
+    .await;
+    let (mut ws, _ready) = connect(&server.url, true).await;
+    ws.send(reconcile_request_with_session_ref("claude", "sess-2"))
+        .await
+        .expect("send request");
+    let result = next_frame_of_type(&mut ws, "pane.reconcile.result").await;
+    assert_ne!(result["verdicts"][0]["verdict"], "error");
+}
diff --git a/crates/freshell-ws/tests/safe08_restore_diagnostics.rs b/crates/freshell-ws/tests/safe08_restore_diagnostics.rs
index c0a949981..d20f6024a 100644
--- a/crates/freshell-ws/tests/safe08_restore_diagnostics.rs
+++ b/crates/freshell-ws/tests/safe08_restore_diagnostics.rs
@@ -179,6 +179,7 @@ async fn spawn_server() -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/term09_output_queue.rs b/crates/freshell-ws/tests/term09_output_queue.rs
index 9edcedb52..4e546a5b7 100644
--- a/crates/freshell-ws/tests/term09_output_queue.rs
+++ b/crates/freshell-ws/tests/term09_output_queue.rs
@@ -86,6 +86,7 @@ async fn spawn_server(term09: Term09Config) -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
     };
 
     let router = freshell_ws::router(state);
diff --git a/test/e2e-browser/specs/reconcile-handshake-rust.spec.ts b/test/e2e-browser/specs/reconcile-handshake-rust.spec.ts
index a6805a103..8dbc7c267 100644
--- a/test/e2e-browser/specs/reconcile-handshake-rust.spec.ts
+++ b/test/e2e-browser/specs/reconcile-handshake-rust.spec.ts
@@ -123,9 +123,10 @@ class SyntheticClient {
   }
 
   /**
-   * One reconcile round-trip. The retry verdict is part of the protocol
-   * (cold index → `retry(index_warming)`); `reconcileUntilStable` below is
-   * the client-side re-request loop the design prescribes.
+   * One reconcile round-trip. A cold index yields `error{index_warming}`
+   * after the server's ONE bounded deferral (`retry` is deleted from the
+   * wire); `reconcileUntilStable` below is this harness's bounded
+   * re-request loop so the tests stay robust on slow cold-index machines.
    */
   async reconcile(panes: Array<Record<string, unknown>>): Promise<Frame[]> {
     const reconcileId = `rec-${Math.random().toString(36).slice(2)}`
@@ -136,12 +137,16 @@ class SyntheticClient {
     return (result as { verdicts: Frame[] }).verdicts
   }
 
-  /** Re-request while any verdict is `retry` (bounded), per §5.3 row 5. */
+  /** Re-request while any verdict is `error{index_warming}` (bounded), per §5.3 row 5. */
   async reconcileUntilStable(panes: Array<Record<string, unknown>>): Promise<Frame[]> {
     let verdicts: Frame[] = []
     for (let attempt = 0; attempt < 40; attempt++) {
       verdicts = await this.reconcile(panes)
-      if (!verdicts.some((v) => (v as { verdict?: string }).verdict === 'retry')) return verdicts
+      const warming = (v: Frame) => {
+        const { verdict, reason } = v as { verdict?: string; reason?: string }
+        return verdict === 'error' && reason === 'index_warming'
+      }
+      if (!verdicts.some(warming)) return verdicts
       await new Promise((r) => setTimeout(r, 250))
     }
     return verdicts

From be3cf329726eb6b421a99e6e7cf56637990123ed Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:16:35 -0700
Subject: [PATCH 11/87] feat(ws): provider_unavailable existence state yields
 immediate honest error verdict
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A known provider whose session root does not exist on this machine is NOT
warming — it will never warm up. New SessionExistence::ProviderUnavailable:
IndexExistenceProbe checks the provider's session root (the same paths the
index sources use) before the cold-peek Unknown; the derivation answers
error{provider_unavailable} immediately, and the handler's single warming
deferral (index_warming only) never fires for it. NoIndexProbe unchanged.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-server/src/existence.rs    | 72 ++++++++++++++++++++--
 crates/freshell-server/src/main.rs         | 20 ++++++
 crates/freshell-ws/src/existence.rs        |  4 ++
 crates/freshell-ws/src/reconcile.rs        | 23 +++++++
 crates/freshell-ws/tests/pane_reconcile.rs | 28 +++++++++
 5 files changed, 142 insertions(+), 5 deletions(-)

diff --git a/crates/freshell-server/src/existence.rs b/crates/freshell-server/src/existence.rs
index 4494657eb..ed15366ac 100644
--- a/crates/freshell-server/src/existence.rs
+++ b/crates/freshell-server/src/existence.rs
@@ -15,7 +15,8 @@
 //! feeds a monotone observed-set, so "disk has seen this identity at least
 //! once (this boot)" survives the session later disappearing from disk.
 
-use std::collections::HashSet;
+use std::collections::{HashMap, HashSet};
+use std::path::PathBuf;
 use std::sync::{Arc, Mutex};
 
 use freshell_sessions::directory_index::SessionIndex;
@@ -33,17 +34,25 @@ pub struct IndexExistenceProbe {
     /// memory — survives restarts, so a transcript deleted while the server
     /// was down yields loud dead_session, not silent fresh.
     ledger: Option<Arc<freshell_ws::pane_ledger::PaneLedger>>,
+    /// Each known provider's session root on THIS machine (the same paths
+    /// `main.rs` hands the index sources). A known provider whose root does
+    /// not exist will never warm up — the cold-index answer for it is
+    /// `ProviderUnavailable`, not the deferrable `Unknown`. A provider with
+    /// no entry keeps the plain `Unknown` cold answer.
+    provider_roots: HashMap<String, PathBuf>,
 }
 
 impl IndexExistenceProbe {
     pub fn new(
         index: Arc<SessionIndex>,
         ledger: Option<Arc<freshell_ws::pane_ledger::PaneLedger>>,
+        provider_roots: HashMap<String, PathBuf>,
     ) -> Self {
         Self {
             index,
             observed: Mutex::new(HashSet::new()),
             ledger,
+            provider_roots,
         }
     }
 
@@ -78,7 +87,19 @@ impl SessionExistenceProbe for IndexExistenceProbe {
             self.kick_refresh();
         }
         match self.index.peek() {
-            None => SessionExistence::Unknown,
+            None => {
+                // Cold index: a known provider whose session root does not
+                // exist on this machine will NEVER warm up — that's an
+                // immediate, honest provider_unavailable, not index_warming.
+                if self
+                    .provider_roots
+                    .get(provider)
+                    .is_some_and(|root| !root.exists())
+                {
+                    return SessionExistence::ProviderUnavailable;
+                }
+                SessionExistence::Unknown
+            }
             Some(items) => {
                 self.record_observed(&items);
                 let hit = items
@@ -152,7 +173,14 @@ mod tests {
             Duration::from_millis(50),
             None, // no persistent parse-cache — fully isolated temp home
         ));
-        (IndexExistenceProbe::new(Arc::clone(&index), None), index)
+        (
+            IndexExistenceProbe::new(
+                Arc::clone(&index),
+                None,
+                HashMap::from([("claude".to_string(), home.to_path_buf())]),
+            ),
+            index,
+        )
     }
 
     /// Construct a probe exactly as `main.rs` does — over an index whose
@@ -164,11 +192,11 @@ mod tests {
     ) -> IndexExistenceProbe {
         let home = temp_claude_home("with-ledger");
         let index = Arc::new(SessionIndex::with_ttl_and_cache_path(
-            vec![Arc::new(ClaudeSource::new(home)) as Arc<dyn SessionSource>],
+            vec![Arc::new(ClaudeSource::new(home.clone())) as Arc<dyn SessionSource>],
             Duration::from_millis(50),
             None,
         ));
-        IndexExistenceProbe::new(index, ledger)
+        IndexExistenceProbe::new(index, ledger, HashMap::from([("claude".to_string(), home)]))
     }
 
     #[test]
@@ -240,6 +268,40 @@ mod tests {
         let _ = std::fs::remove_dir_all(&home);
     }
 
+    /// A known provider whose session root does NOT exist on this machine
+    /// will never warm up — the probe answers `ProviderUnavailable`, not the
+    /// deferrable `Unknown`.
+    #[tokio::test]
+    async fn missing_provider_root_is_provider_unavailable_not_unknown() {
+        let home = temp_claude_home("root-missing");
+        let gone = home.join("never-created-claude-root");
+        let index = Arc::new(SessionIndex::with_ttl_and_cache_path(
+            vec![Arc::new(ClaudeSource::new(gone.clone())) as Arc<dyn SessionSource>],
+            Duration::from_millis(50),
+            None,
+        ));
+        let probe = IndexExistenceProbe::new(
+            index,
+            None,
+            std::collections::HashMap::from([("claude".to_string(), gone)]),
+        );
+        assert_eq!(
+            probe.exists("claude", "s-any"),
+            SessionExistence::ProviderUnavailable
+        );
+        let _ = std::fs::remove_dir_all(&home);
+    }
+
+    /// The counterpart boundary: the root EXISTS but the index is still cold
+    /// → `Unknown` (warming), unchanged by the ProviderUnavailable check.
+    #[tokio::test]
+    async fn existing_but_cold_provider_root_stays_unknown() {
+        let home = temp_claude_home("root-cold");
+        let (probe, _index) = probe_over(&home);
+        assert_eq!(probe.exists("claude", "s-cold"), SessionExistence::Unknown);
+        let _ = std::fs::remove_dir_all(&home);
+    }
+
     /// §9.1 test 13 — real-index staleness: a `provider:sessionId` written to
     /// disk AFTER a cold read must resolve `Present` on re-query; a stale
     /// `Absent` must never latch.
diff --git a/crates/freshell-server/src/main.rs b/crates/freshell-server/src/main.rs
index 9eab13f14..4cb8a3a9c 100644
--- a/crates/freshell-server/src/main.rs
+++ b/crates/freshell-server/src/main.rs
@@ -444,6 +444,26 @@ async fn main() -> ExitCode {
                 // transcript deleted while the server was DOWN still derives
                 // loud dead_session (per-boot observed set is empty then).
                 Some(std::sync::Arc::clone(&pane_ledger)),
+                // Provider session roots resolved with the SAME helpers the
+                // `session_index` sources above use — a known provider whose
+                // root does not exist on this machine derives an immediate
+                // `error{provider_unavailable}`, never `index_warming`.
+                session_directory::provider_home()
+                    .map(|h| {
+                        std::collections::HashMap::from([
+                            ("claude".to_string(), session_directory::claude_home(&h)),
+                            ("codex".to_string(), session_directory::codex_home(&h)),
+                            (
+                                "opencode".to_string(),
+                                freshell_sessions::parse::default_opencode_data_home(),
+                            ),
+                            (
+                                "amplifier".to_string(),
+                                freshell_sessions::amplifier::amplifier_home(&h),
+                            ),
+                        ])
+                    })
+                    .unwrap_or_default(),
             )),
             None => std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
         },
diff --git a/crates/freshell-ws/src/existence.rs b/crates/freshell-ws/src/existence.rs
index 8e110facf..afd455ebc 100644
--- a/crates/freshell-ws/src/existence.rs
+++ b/crates/freshell-ws/src/existence.rs
@@ -29,6 +29,10 @@ pub enum SessionExistence {
     Absent,
     /// Known provider, but the index cannot answer yet (cold/unavailable).
     Unknown,
+    /// Known provider whose session root does not exist on this machine —
+    /// it will never warm up, so downstream answers an immediate
+    /// `error{provider_unavailable}` with NO deferral (never `index_warming`).
+    ProviderUnavailable,
 }
 
 /// The reconcile derivation's read-only view of disk session truth.
diff --git a/crates/freshell-ws/src/reconcile.rs b/crates/freshell-ws/src/reconcile.rs
index c4340df55..460731f81 100644
--- a/crates/freshell-ws/src/reconcile.rs
+++ b/crates/freshell-ws/src/reconcile.rs
@@ -249,6 +249,13 @@ fn verdict_for_pane(deps: &ReconcileDeps<'_>, pane: &ReconcilePane) -> PaneVerdi
             reason: Some("index_warming".to_string()),
             ..base(pane, ReconcileVerdict::Error)
         },
+        // A known provider with no home on this machine is NOT warming — the
+        // honest, immediate provider_unavailable (the handler's single
+        // deferral fires only on index_warming, `terminal.rs`).
+        SessionExistence::ProviderUnavailable => PaneVerdict {
+            reason: Some("provider_unavailable".to_string()),
+            ..base(pane, ReconcileVerdict::Error)
+        },
     }
 }
 
@@ -490,6 +497,22 @@ mod tests {
         assert_eq!(v.reason.as_deref(), Some("index_warming"));
     }
 
+    /// A known provider whose session root does not exist on this machine →
+    /// immediate error{provider_unavailable} — never index_warming (which
+    /// would trigger the handler's deferral), never dead_session.
+    #[test]
+    fn provider_unavailable_existence_yields_error_provider_unavailable() {
+        let f = Fixture::new();
+        f.probe
+            .set("codex", "s-pu", SessionExistence::ProviderUnavailable);
+        let mut p = pane("cr-pu");
+        p.mode = Some("codex".to_string());
+        p.session_ref = Some(sref("codex", "s-pu"));
+        let v = f.one(p);
+        assert_eq!(v.verdict, ReconcileVerdict::Error);
+        assert_eq!(v.reason.as_deref(), Some("provider_unavailable"));
+    }
+
     /// Row 6: no terminalId at all, just a claim that IS on disk → respawn
     /// (restore-after-persist-cycle). The claim matched, so no `corrected`.
     #[test]
diff --git a/crates/freshell-ws/tests/pane_reconcile.rs b/crates/freshell-ws/tests/pane_reconcile.rs
index a070b4852..d63bb2ad9 100644
--- a/crates/freshell-ws/tests/pane_reconcile.rs
+++ b/crates/freshell-ws/tests/pane_reconcile.rs
@@ -638,6 +638,34 @@ async fn warming_never_completes_yields_error_index_warming() {
     );
 }
 
+/// A known provider with no home on this machine is NOT warming — it gets
+/// the honest provider_unavailable label, immediately (no 2s deferral).
+#[tokio::test]
+async fn provider_unavailable_is_immediate_and_honest() {
+    // A single scripted answer repeats forever — "always ProviderUnavailable".
+    let probe = FlippingProbe::new(vec![
+        freshell_ws::existence::SessionExistence::ProviderUnavailable,
+    ]);
+    // Deliberately LARGE budget: proves no deferral happens for this reason.
+    let server = spawn_server_with_probe(std::sync::Arc::new(probe), |state| {
+        state.reconcile_deferral_budget_ms = 30_000
+    })
+    .await;
+    let (mut ws, _ready) = connect(&server.url, true).await;
+    let started = std::time::Instant::now();
+    ws.send(reconcile_request_with_session_ref("codex", "sess-9"))
+        .await
+        .expect("send request");
+    let result = next_frame_of_type(&mut ws, "pane.reconcile.result").await;
+    assert!(
+        started.elapsed() < std::time::Duration::from_secs(2),
+        "provider_unavailable must never trigger the warming deferral"
+    );
+    let v = &result["verdicts"][0];
+    assert_eq!(v["verdict"], "error");
+    assert_eq!(v["reason"], "provider_unavailable");
+}
+
 /// The deferral is real: index warms during the wait -> the SECOND derivation
 /// answers with the warm verdict, not error.
 #[tokio::test]

From 6c3e32c9527910d707e666283febdffbed691c05 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:21:49 -0700
Subject: [PATCH 12/87] docs(plan): fix fresheyes iteration-1 blocking issues
 in B4 plan

Independent cross-model review (fresheyes iter 1) found 3 blocking majors;
all fixed against verified repository behavior:

1. Task 14 opencode e2e (test 2): the wire body carries model as a
   {providerID, modelID} OBJECT only for provider/model-shaped ids
   (split_opencode_model returns None for slashless) and effort as
   'variant' - never 'effort'/'reasoningEffort'. Switched the test model
   to 'fakeprov/big-model', the fake's audit fields to {model, variant},
   and the assertions to the actual wire shape.

2. Task 14 raw-WS templates: added the required 'provider' field to every
   freshAgent.create template (dispatch silently drops provider: None)
   and to the freshAgent.attach template (provider is a required field -
   deserialization fails without it); corrected the raw-attach donor
   citation to freshagent_claude_attach.rs:276.

3. Task 1: tests belong in the sibling file pane_ledger_tests.rs (pulled
   in via #[path] at pane_ledger.rs:797-799), constructed via the real
   helpers (temp_root(label) + PaneLedger::new(Some(root)) + manual
   remove_dir_all cleanup) instead of the nonexistent test_ledger();
   added pane_ledger_tests.rs to Task 1's git add so the TDD evidence
   is committed.
---
 .../2026-07-26-freshagent-verdicts-resume.md  | 43 +++++++++++--------
 1 file changed, 26 insertions(+), 17 deletions(-)

diff --git a/docs/plans/2026-07-26-freshagent-verdicts-resume.md b/docs/plans/2026-07-26-freshagent-verdicts-resume.md
index 231eaf697..af4976906 100644
--- a/docs/plans/2026-07-26-freshagent-verdicts-resume.md
+++ b/docs/plans/2026-07-26-freshagent-verdicts-resume.md
@@ -59,7 +59,7 @@
 
 **Files:**
 - Modify: `crates/freshell-ws/src/pane_ledger.rs`
-- Test: inline `#[cfg(test)] mod` in the same file (follow the existing test module, e.g. `record_binding_roundtrips_all_fields`)
+- Test: `crates/freshell-ws/src/pane_ledger_tests.rs` — the tests live in this sibling file, pulled in by `#[cfg(test)] #[path = "pane_ledger_tests.rs"] mod tests;` at `pane_ledger.rs:797-799` (follow the existing tests there, e.g. `record_binding_roundtrips_all_fields` at `pane_ledger_tests.rs:41`)
 
 **Interfaces:**
 - Consumes: existing `BindingRow`, `RowState`, `PaneLedger` internals (`record_binding` at `pane_ledger.rs:315` is the structural donor).
@@ -70,12 +70,13 @@
 
 - [ ] **Step 1: Write the failing tests**
 
-Add to the existing `#[cfg(test)]` module in `pane_ledger.rs` (reuse the module's existing temp-root helper — the same one `record_binding_roundtrips_all_fields` uses):
+Add to `crates/freshell-ws/src/pane_ledger_tests.rs` (the sibling tests file — `pane_ledger.rs:797-799` declares `#[cfg(test)] #[path = "pane_ledger_tests.rs"] mod tests;`). There is NO combined ledger-constructor helper; follow the file's existing convention (see `record_binding_roundtrips_all_fields`): `let root = temp_root("<label>"); let ledger = PaneLedger::new(Some(root.clone()));` with a manual trailing `std::fs::remove_dir_all(&root).ok();` (the `temp_root(label: &str) -> PathBuf` helper at `pane_ledger_tests.rs:8-20` returns a plain `PathBuf` — no Drop guard):
 
 ```rust
 #[test]
 fn fresh_agent_binding_roundtrips_settings_and_pane_kind() {
-    let (ledger, _tmp) = test_ledger(); // the module's existing temp-root constructor helper
+    let root = temp_root("fresh-agent-roundtrip"); // existing helper, pane_ledger_tests.rs:8-20
+    let ledger = PaneLedger::new(Some(root.clone()));
     ledger
         .record_fresh_agent_binding(&FreshAgentBindingWrite {
             provider: "codex",
@@ -99,11 +100,13 @@ fn fresh_agent_binding_roundtrips_settings_and_pane_kind() {
     assert_eq!(row.effort.as_deref(), Some("high"));
     assert_eq!(row.cwd.as_deref(), Some("/home/u/proj"));
     assert_eq!(row.created_at, 1_000);
+    std::fs::remove_dir_all(&root).ok();
 }
 
 #[test]
 fn fresh_agent_binding_upsert_preserves_created_at_and_refreshes_settings() {
-    let (ledger, _tmp) = test_ledger();
+    let root = temp_root("fresh-agent-upsert");
+    let ledger = PaneLedger::new(Some(root.clone()));
     let base = FreshAgentBindingWrite {
         provider: "opencode",
         session_id: "ses_abc",
@@ -126,13 +129,15 @@ fn fresh_agent_binding_upsert_preserves_created_at_and_refreshes_settings() {
     assert_eq!(row.updated_at, 2_000);
     assert_eq!(row.model.as_deref(), Some("m2"));
     assert_eq!(row.effort, None, "settings are a full snapshot, not a merge");
+    std::fs::remove_dir_all(&root).ok();
 }
 
 #[test]
 fn supersedes_retires_the_old_row_and_links_the_chain() {
     // G3 supersession (V8/A14): codex crash-respawn must retire the OLD
     // thread row and link it to the new one — never leave two Bound rows.
-    let (ledger, _tmp) = test_ledger();
+    let root = temp_root("fresh-agent-supersedes");
+    let ledger = PaneLedger::new(Some(root.clone()));
     let base = FreshAgentBindingWrite {
         provider: "codex",
         session_id: "old-thread",
@@ -165,6 +170,7 @@ fn supersedes_retires_the_old_row_and_links_the_chain() {
     let res = ledger.lookup_by_session("codex", "old-thread").expect("chain resolves");
     assert!(res.corrected, "claiming the old id is a corrected resolution");
     assert_eq!(res.row.session_id, "new-thread", "resolution lands at the terminus");
+    std::fs::remove_dir_all(&root).ok();
 }
 // (Match the EXACT `RowState`/`RetiredReason` variant names and `Resolution`
 // field names from pane_ledger.rs:107-148 / :450-484 — verify at implementation;
@@ -252,7 +258,7 @@ Expected: PASS (all three new tests plus every pre-existing pane_ledger test).
 
 ```bash
 cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
-git add crates/freshell-ws/src/pane_ledger.rs
+git add crates/freshell-ws/src/pane_ledger.rs crates/freshell-ws/src/pane_ledger_tests.rs
 git commit -m "feat(ledger): resume-invocation record fields + fresh-agent binding upsert (P1.13)"
 ```
 
@@ -2255,7 +2261,7 @@ git commit -m "feat(ws): fresh-agent panes enter the reconcile verdict system be
 **Interfaces:**
 - Consumes: `RustServer` (`test/e2e-browser/helpers/rust-server.ts`): `start()`, `restartAbrupt()` (SIGKILL + reboot on same home/port/token), `{env, setupHome}` options. `bootWall(page, {env, setupHome})` from the wall spec's helper pattern (test 4 only — tests 1-3 drive the server directly, no browser page needed). Fakes: `CODEX_CMD="node <fake-app-server.mjs>"` + `FAKE_CODEX_APP_SERVER_BEHAVIOR` (inline env JSON, STATIC per server boot — nothing can be rewritten between sidecar spawns, V4/A6; supports `appendThreadOperationLogPath` → JSONL `{method, threadId, params}`); `OPENCODE_CMD` + `FAKE_OPENCODE_AUDIT_LOG` (JSONL entries keyed by `event` field — there is NO `path` field, V4/A5); `FRESHELL_CLAUDE_SIDECAR` + `FAKE_CLAUDE_SIDECAR_LOG` (JSONL of every inbound message).
 - SEEDING SURFACES (V3/A3 — REST `POST /api/tabs` rejects `agent != "opencode"` with 400, `crates/freshell-freshagent/src/lib.rs:1268`; REST send-keys/capture 404 for codex/claude sessions, which never enter the REST `panes` map):
-  - **codex + claude (tests 1/3/4 creation):** raw WS `freshAgent.create` (schema `crates/freshell-protocol/src/client_messages.rs:457-488`, camelCase: `requestId`, `sessionType`, `cwd`, `model`, `effort`, `permissionMode`, `sandbox`, `resumeSessionId`; codex carries model/sandbox/approvalPolicy on `thread/start` and effort per `turn/start`; claude forwards model/permissionMode/effort to the sidecar verbatim), driven via `freshAgent.send`. Dispatch is gated on `settings.freshAgent.enabled=true` (`terminal.rs:567`) — PATCH settings first. Donor for the whole flow (settings-PATCH + raw create + created-wait): `crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs` (raw create at `:295`); port the same message sequence to the spec's Node context (`fetch` + `WebSocket`), following the hello/ready handshake the sibling specs use — verify exact PATCH endpoint shape against the donor during implementation.
+  - **codex + claude (tests 1/3/4 creation):** raw WS `freshAgent.create` (schema `crates/freshell-protocol/src/client_messages.rs:457-488`, camelCase: `requestId`, `sessionType`, `provider`, `cwd`, `model`, `effort`, `permissionMode`, `sandbox`, `resumeSessionId`; `provider` is `Option<AgentProvider>` in the schema but the dispatch at `terminal.rs:566-586` matches only `Some(Codex|Claude|Opencode)` and SILENTLY DROPS `provider: None` — every raw create in this spec MUST include `provider: 'codex' | 'opencode' | 'claude'`. `FreshAgentAttach.provider` is REQUIRED (non-Option, `client_messages.rs:492-503`) — an attach frame without it fails deserialization outright; codex carries model/sandbox/approvalPolicy on `thread/start` and effort per `turn/start`; claude forwards model/permissionMode/effort to the sidecar verbatim), driven via `freshAgent.send`. Dispatch is gated on `settings.freshAgent.enabled=true` (`terminal.rs:567`) — PATCH settings first. Donor for the whole flow (settings-PATCH + raw create + created-wait): `crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs` (raw create at `:295`); port the same message sequence to the spec's Node context (`fetch` + `WebSocket`), following the hello/ready handshake the sibling specs use — verify exact PATCH endpoint shape against the donor during implementation.
   - **opencode (test 2):** keeps REST `POST /api/tabs` `{ agent: 'opencode', model, effort }` + `POST /api/panes/:id/send-keys` (the REST surface is opencode-only and honors model/effort per-turn, V3 §2).
 - RESUME TOPOLOGY (V2/A4 — after `page.reload()` the frozen client NEVER sends `freshAgent.attach`; it sends `freshAgent.create{resumeSessionId, sessionRef}` (persistMiddleware strips `sessionId`). Attach fires only on `ws.onReconnect` WITHOUT reload. Each test below states which path it exercises and why.)
 - Donor spec for boot/env/restart plumbing: `test/e2e-browser/specs/freshclaude-restart-parity-rust.spec.ts:212-310`; donor for banner/UI flow (test 4): the wall/restore-matrix pane-creation patterns.
@@ -2280,7 +2286,7 @@ if (
 }
 ```
 
-(b) `fake-opencode.cjs` — audit the parsed prompt body (V4/A5: today the `prompt_async` handler parses the body but audits only `{event:'prompt_async', sessionId, routeDirectory, directory, prompt}`; `model`/`effort`/`reasoningEffort` are DISCARDED). In the prompt POST handler (`:776-809`), add the parsed body fields to the `appendAudit` payload at `:793-799`, e.g. `body: { model: body.model, effort: body.effort, reasoningEffort: body.reasoningEffort }` (~2 lines).
+(b) `fake-opencode.cjs` — audit the parsed prompt body (V4/A5: today the `prompt_async` handler parses the body but audits only `{event:'prompt_async', sessionId, routeDirectory, directory, prompt}`; the settings fields are DISCARDED). WIRE SHAPE (verified against `build_prompt_body`, `crates/freshell-opencode/src/serve.rs:939-955`): the body carries `model` as an OBJECT `{ providerID, modelID }` — included only when `split_opencode_model` succeeds, i.e. the model id is `provider/model`-shaped (`crates/freshell-opencode/src/model.rs:141-155` returns `None` for blank/slashless/edge-slash values, so the caller omits `model` entirely) — and effort as the string field `variant` (only when non-empty). There is NO `effort` or `reasoningEffort` key on the wire. In the prompt POST handler (`:776-809`), add the parsed body fields to the `appendAudit` payload at `:793-799`: `body: { model: body.model, variant: body.variant }` (~2 lines).
 
 - [ ] **Step 2: Write the four e2e tests (they fail against pre-fix behavior only where the fix is server-side; write them to assert the FIXED contract)**
 
@@ -2288,8 +2294,8 @@ if (
 
 1. **`codex: create-shaped resume after restart carries the recorded model`** — exercises the CREATE-resume path (R1 + ledger-fill), the exact wire shape the frozen client sends after `page.reload()` (V2/A4). No browser page.
    - Boot with `CODEX_CMD` fake + static behavior including `appendThreadOperationLogPath: <tmp>/codex-ops.jsonl` (resume succeeds by default).
-   - PATCH `settings.freshAgent.enabled=true`; open a raw WS; `freshAgent.create` with `{ sessionType: 'freshcodex', model: 'gpt-5.3-codex', sandbox: 'workspace-write', cwd: <tmp> }`; await `freshAgent.created` (capture the durable thread id); one `freshAgent.send`; await the turn.
-   - `await server.restartAbrupt()`; open a NEW raw WS; send `freshAgent.create` with `{ sessionType: 'freshcodex', resumeSessionId: <thread id> }` and NO model/sandbox — proving the values come from the LEDGER (R1 fills gaps, Task 5(d)), not from the message; await the created/attach-equivalent reply.
+   - PATCH `settings.freshAgent.enabled=true`; open a raw WS; `freshAgent.create` with `{ provider: 'codex', sessionType: 'freshcodex', model: 'gpt-5.3-codex', sandbox: 'workspace-write', cwd: <tmp> }`; await `freshAgent.created` (capture the durable thread id); one `freshAgent.send`; await the turn.
+   - `await server.restartAbrupt()`; open a NEW raw WS; send `freshAgent.create` with `{ provider: 'codex', sessionType: 'freshcodex', resumeSessionId: <thread id> }` and NO model/sandbox — proving the values come from the LEDGER (R1 fills gaps, Task 5(d)), not from the message; await the created/attach-equivalent reply.
    - Assertion block:
    ```ts
    const ops = fs.readFileSync(opLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
@@ -2301,22 +2307,25 @@ if (
 
 2. **`opencode: create-shaped resume after restart → next send carries the recorded model/effort`** — REST seeding (V3: opencode-only surface) + the create-shaped resume the frozen client sends post-reload (V2/A4; honored server-side by Task 8(b) — the P1.13 pin mechanism). No browser page.
    - Boot with `OPENCODE_CMD` fake + `FAKE_OPENCODE_AUDIT_LOG`.
-   - REST `POST /api/tabs` `{ agent: 'opencode', model: 'big-model', effort: 'high' }`; REST send-keys once (materializes `ses_*` — Task 7's REST-site ledger write records the settings; read the `ses_*` id from the audit log's `prompt_async` entry `sessionId`).
-   - `restartAbrupt()` (the REST panes map is in-memory and gone — post-restart driving is via WS). Open a raw WS (settings PATCH as in test 1); send `freshAgent.create{ sessionType: 'freshopencode', resumeSessionId: <ses_*> }` with NO model/effort; await created (must answer the `ses_*` id, not a placeholder); `freshAgent.send` one message with NO per-send settings.
+   - REST `POST /api/tabs` `{ agent: 'opencode', model: 'fakeprov/big-model', effort: 'high' }` — the model id MUST be `provider/model`-shaped: `split_opencode_model` (`crates/freshell-opencode/src/model.rs:141-155`) returns `None` for slashless ids, in which case `build_prompt_body` omits `model` from the wire entirely and the assertions below can never pass; REST send-keys once (materializes `ses_*` — Task 7's REST-site ledger write records the settings; read the `ses_*` id from the audit log's `prompt_async` entry `sessionId`).
+   - `restartAbrupt()` (the REST panes map is in-memory and gone — post-restart driving is via WS). Open a raw WS (settings PATCH as in test 1); send `freshAgent.create{ provider: 'opencode', sessionType: 'freshopencode', resumeSessionId: <ses_*> }` with NO model/effort; await created (must answer the `ses_*` id, not a placeholder); `freshAgent.send` one message with NO per-send settings.
    - Assertion block:
    ```ts
    const audit = fs.readFileSync(auditLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
    const prompts = audit.filter((e) => e.event === 'prompt_async') // V4: entries have `event`, never `path`
    const afterRestart = prompts[prompts.length - 1]
-   expect(afterRestart.body?.model ? JSON.stringify(afterRestart.body.model) : '', 'post-restart send must carry the recorded model').toContain('big-model')
-   expect(JSON.stringify(afterRestart.body ?? {}), 'post-restart send must carry the recorded effort').toContain('high')
+   // On the wire (build_prompt_body, serve.rs:939-955): model is the OBJECT
+   // { providerID: 'fakeprov', modelID: 'big-model' }, effort is the string
+   // field `variant` — never `effort`/`reasoningEffort`.
+   expect(afterRestart.body?.model, 'post-restart send must carry the recorded model').toEqual({ providerID: 'fakeprov', modelID: 'big-model' })
+   expect(afterRestart.body?.variant, 'post-restart send must carry the recorded effort (wire field: variant)').toBe('high')
    ```
-   (`body` is the field added in Step 1(b); assert on the audited body fields, matching the fake's actual shape at implementation time.)
+   (`body` is the field added in Step 1(b) — `{ model, variant }`; if the fake's parsed-body key names differ at implementation time, keep asserting the same VALUES — a `{providerID, modelID}` model object and `variant: 'high'` — against the fake's actual shape.)
 
 3. **`claude: attach resume request carries model/permissionMode`** — exercises the ATTACH path (`resume_for_attach`, Task 10's fix target). Attach is the no-reload restart topology: the frozen client sends it on `ws.onReconnect` without reload (V2/A4), and the donor spec proves attach-on-the-wire for claude. No browser page.
    - Boot with `FRESHELL_CLAUDE_SIDECAR` fake + `FAKE_CLAUDE_SIDECAR_LOG` (exactly the donor's env, `rust-server.ts` + donor `:212-310`).
-   - Settings PATCH; raw WS `freshAgent.create` `{ sessionType: 'freshclaude', model: 'opus-x', permissionMode: 'plan', cwd: <tmp> }`; await created + `sdk.session.init` handling (donor wait); capture the durable session id; one send.
-   - `restartAbrupt()`; new raw WS; send `freshAgent.attach { sessionId: <durable>, sessionType: 'freshclaude' }` (raw-attach donor: `crates/freshell-ws/tests/freshagent_claude_attach.rs:112`); await the resume.
+   - Settings PATCH; raw WS `freshAgent.create` `{ provider: 'claude', sessionType: 'freshclaude', model: 'opus-x', permissionMode: 'plan', cwd: <tmp> }`; await created + `sdk.session.init` handling (donor wait); capture the durable session id; one send.
+   - `restartAbrupt()`; new raw WS; send `freshAgent.attach { provider: 'claude', sessionId: <durable>, sessionType: 'freshclaude' }` — `provider` is a REQUIRED attach field; omitting it fails deserialization (raw-attach donor: the inline `json!` frame at `crates/freshell-ws/tests/freshagent_claude_attach.rs:276`, `{type, provider: "claude", sessionId, sessionType: "freshclaude"}`); await the resume.
    - Assertion block:
    ```ts
    const msgs = fs.readFileSync(sidecarLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))

From b988e8f8127f46bb7816f77316f73c08bb130a5c Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:23:03 -0700
Subject: [PATCH 13/87] docs(plan): fix fresh-eyes iteration 1 blocking issues
 in codex-rollout-locator plan

Blocking issue 1 (Task 6 could not pass as written): the shared test
harness spawn helpers build WsState with no locators and never spawn a
sweep, so the planned integration test could never resolve identity.
Task 6 now adds a locator-wired spawn helper to tests/common/mod.rs
(codex_locator set + 150 ms sweep spawned before router), the File
Structure table and Task 4's compile-sweep instruction name the harness,
and the failure-triage note points at the harness first.

Blocking issue 2 (Premise 10 understated the misbind surface): added the
FIRST-submit known_files re-snapshot hardening - strictly safe by
Premise 7 - closing the arm-to-first-Enter foreign-capture gap. Encoded
in Task 1 (note_submit re-snapshot + new test), Task 2 (re-open keeps
the frozen snapshot pin), Task 4 (async note_possible_submit awaited
BEFORE the PTY write - ordering is load-bearing because codex
materializes the rollout in response to that very Enter), Task 5/6
(seed-after-submit orderings), and Task 8 (fixture writes the rollout
on first Enter, not first stdin data). Premises 9/10 and the plan
Self-Review updated to match.
---
 .../plans/2026-07-26-codex-rollout-locator.md | 399 ++++++++++++++----
 1 file changed, 314 insertions(+), 85 deletions(-)

diff --git a/docs/plans/2026-07-26-codex-rollout-locator.md b/docs/plans/2026-07-26-codex-rollout-locator.md
index ecafebf44..c718f8893 100644
--- a/docs/plans/2026-07-26-codex-rollout-locator.md
+++ b/docs/plans/2026-07-26-codex-rollout-locator.md
@@ -73,7 +73,8 @@ Node .mjs fake-CLI fixture.
    server share ONE sessions tree:
    `<CODEX_HOME|~/.codex>/sessions/YYYY/MM/DD/rollout-<ts>-<threadId>.jsonl`
    (flat `<id>.jsonl` also supported, used by tests). Pane↔rollout attribution
-   therefore needs a disambiguator set: arm-time known-files snapshot +
+   therefore needs a disambiguator set: known-files snapshot (taken at arm,
+   re-snapshotted at the first Enter) +
    Enter-anchored windows + REQUIRED-cwd match + pending-first-line
    bind-blocking + contested-cwd refusal (see Validated Premises below).
 2. **"One watcher, two consumers" is not feasible for discovery.** The wave-2
@@ -129,19 +130,33 @@ A codex upgrade re-opens every codex-behavior item below.
    The original snapshot+cwd+same-tick-ambiguity trio allowed clean misbinds
    (same-cwd foreign codex/exec/fork, staggered same-cwd panes, the
    spawn-window pure-foreign capture). Mandatory hardenings, all encoded in
-   Tasks 1-3: Enter-only windows (item 7); cwd REQUIRED — a no-cwd
+   Tasks 1-4: Enter-only windows (item 7); cwd REQUIRED — a no-cwd
    session_meta NEVER binds (`SessionMeta.cwd` is non-optional at 0.145.0,
    3,858/3,858 corpus; a permissive no-cwd rule is pure attack surface);
    pending-candidate bind-blocking (item 8); CROSS-TICK contested-cwd
    refusal — while ≥2 armed terminals share a normalized cwd nothing binds
-   for any of them; and the adoption tail refuses a thread id already bound
+   for any of them; the adoption tail refuses a thread id already bound
    to another terminal (retired-inclusive; idempotent same-terminal re-adopt
-   allowed).
-10. **(A4 residual risk — documented, NOT solvable in this lane.)** A
-    freshell-freshagent codex agent session started in the SAME cwd during a
-    pane's open window can still misbind as a sole candidate: freshagent's
-    `codex app-server` sidecar writes rollouts into the same
-    `$HOME/.codex/sessions` root. Recommended future fix (Lane B4
+   allowed); and a FIRST-SUBMIT `known_files` re-snapshot — the first
+   `note_submit` replaces the arm-time snapshot with a fresh scan, strictly
+   safe by item 7 (the pane's own rollout cannot exist before its first
+   Enter), closing the arm→first-Enter foreign-capture gap. The re-snapshot
+   is sound ONLY if it completes BEFORE the Enter byte is written to the
+   PTY (codex materializes the rollout in response to that very Enter) —
+   Task 4's submit seam encodes this ordering; later window re-opens NEVER
+   re-snapshot (the pane's own slow-materializing rollout must stay a
+   candidate).
+10. **(A4 residual risk — documented, NOT solvable in this lane.)** The
+    first-submit re-snapshot (item 9) closes the arm→first-Enter capture
+    gap, but a foreign same-cwd rollout created AFTER the pane's first
+    Enter can still misbind as a sole candidate: every window from the
+    first Enter onward diffs against the first-submit snapshot, and there
+    is deliberately no time bound (item 7's re-open mitigation depends on
+    that). Realistic same-cwd writer: a freshell-freshagent codex agent
+    session — freshagent's `codex app-server` sidecar writes rollouts into
+    the same `$HOME/.codex/sessions` root — combined with a later bare
+    Enter on the pane (empty composer or a codex dialog; `is_submit_input`
+    treats any pure CR/LF as a submit). Recommended future fix (Lane B4
     coordination): exclude freshagent-known thread ids (`thread/start`
     results) at adoption. Recorded here so the risk is owned, not silent.
 11. **(A5) The post-spawn arm site is safe — but only because of item 7.**
@@ -153,7 +168,8 @@ A codex upgrade re-opens every codex-behavior item below.
     (3,858 files): 7-9 ms warm. Synthetic 100k files: p95 96 ms warm, worst
     117 ms under 8-way concurrency (native ext4, WSL2). The earlier
     "35-55 ms on an 8k-file tree" figure did NOT reproduce — do not cite it.
-    Cold cache is unmeasured (needs sudo): run BOTH `arm()` and `tick()`
+    Cold cache is unmeasured (needs sudo): run the `arm()`, first-submit
+    `note_submit()`, and `tick()`
     scans inside `spawn_blocking`, never on the WS dispatch path.
 13. **(A2/A9, confirmed) cwd + shape + resume argv.** `payload.cwd` is the
     codex process's physical `getcwd` path recorded verbatim (no
@@ -193,6 +209,7 @@ A codex upgrade re-opens every codex-behavior item below.
 | `crates/freshell-ws/src/terminal.rs` | Modify | arm-at-create, submit seam, exit disarm, candidate match arm → debug log |
 | `crates/freshell-ws/src/invariants.rs` | Modify (docs) | identity-unresolved alarm doc names the codex locator |
 | `crates/freshell-server/src/main.rs` | Modify | Locator construction + WsState field + sweep spawn |
+| `crates/freshell-ws/tests/common/mod.rs` | Modify (Task 6) | New spawn helper wiring a codex locator + 150 ms sweep (existing helpers have no locator and spawn no sweep) |
 | `crates/freshell-ws/tests/codex_locator_activity.rs` | Create | Fresh pane → locator → turn.complete carries sessionId |
 | `crates/freshell-ws/tests/codex_candidate_inert.rs` | Create | Candidate frame is accepted, ignored, logged; no identity written |
 | `crates/freshell-ws/tests/codex_candidate_persisted.rs` | Delete (Task 7) | Superseded by inert test + locator tests |
@@ -258,14 +275,27 @@ corpus; see "Validated Premises" above):
 - Substrate is a filesystem snapshot-diff, not SQLite row-diff: codex persists
   one JSONL rollout file per session under the sessions root.
 - There is NO `pre_epsilon_ms` and NO created-at time bound: filesystems have
-  no reliable cross-platform creation time. The arm-time `known_files`
-  snapshot is the sole (and primary — same as opencode's `known_ids`) safety:
-  a file already present at arm can never bind to this terminal. The locator
+  no reliable cross-platform creation time. The `known_files` snapshot is the
+  primary safety (same as opencode's `known_ids`): a file already present in
+  the snapshot can never bind to this terminal. The locator
   also never filters by the FILENAME timestamp or by today's `YYYY/MM/DD`
   directory: the filename timestamp is precomputed at codex session
   construction and can predate on-disk creation by the entire user idle gap,
   and the dated dir can be a previous day across midnight — the full-tree
   snapshot-diff sidesteps both.
+- FIRST-SUBMIT re-snapshot (A4 hardening; fresh-eyes iteration 1): the first
+  `note_submit` replaces `known_files` with a fresh scan. Strictly safe by
+  the Enter-anchored premise — the pane's own rollout cannot exist before its
+  first Enter, so everything that appeared between arm and the first Enter is
+  foreign by construction (freshagent sidecar, `codex exec`, codex outside
+  freshell). SOUNDNESS PRECONDITION: the caller must complete the first
+  `note_submit` BEFORE the Enter byte is written to the PTY — codex
+  materializes the rollout in response to that very Enter, so a re-snapshot
+  racing after the write could capture (and permanently exclude) the pane's
+  own file. Task 4's submit seam encodes this ordering. Later window
+  re-opens NEVER re-snapshot: the slow-materialization mitigation (a >2 s
+  Enter→creation latency recovered by a later Enter) depends on the pane's
+  own late file staying a candidate.
 - Windows are ENTER-ANCHORED ONLY — there is NO spawn-anchored window (a
   deliberate deviation from opencode). Real codex (0.145.0) defers rollout
   file creation until the first user prompt is recorded (`RolloutRecorder`
@@ -298,7 +328,8 @@ corpus; see "Validated Premises" above):
   — consistent with the arm gate refusing resume panes. Compressed rollout
   artifacts (`.jsonl.zst`, present in 0.145.0 source) are excluded by the
   `.jsonl` suffix filter; fresh sessions always write plain `.jsonl`.
-- Scans happen ONLY at arm time and at deadline evaluations (never on idle
+- Scans happen ONLY at arm time, at the FIRST `note_submit` (the re-snapshot
+  above), and at deadline evaluations (never on idle
   ticks — proven by `fs_scan_count`; a pending candidate keeps its window's
   evaluation due, so re-probes ride the same gate), bounded to walk depth 5
   (the tree is `sessions/YYYY/MM/DD/rollout-*.jsonl`; flat `<id>.jsonl` in
@@ -406,6 +437,27 @@ mod tests {
         let _ = std::fs::remove_dir_all(&root);
     }
 
+    #[test]
+    fn rollout_created_between_arm_and_first_enter_never_binds() {
+        // A4 hardening (first-submit re-snapshot): Premise 7 guarantees the
+        // pane's own rollout cannot exist before its first Enter, so EVERY
+        // file that appears between arm and the first submit is foreign by
+        // construction (freshagent sidecar, `codex exec`, codex outside
+        // freshell in the same cwd). The FIRST note_submit re-snapshots
+        // known_files, so a bare Enter (empty composer, trust dialog) can
+        // never hand the window to that foreign file as a sole candidate.
+        let root = unique_temp_dir("resnapshot");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        // Foreign rollout lands AFTER arm but BEFORE the first Enter.
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.note_submit("t1", 1_000)); // first submit re-snapshots
+        assert_eq!(locator.fs_scan_count(), 2); // arm + first-submit scans
+        assert!(locator.tick(1_000 + CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1); // zero candidates → keep watching
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
     #[test]
     fn arm_admission_gates() {
         let root = unique_temp_dir("gates");
@@ -497,13 +549,23 @@ module is the RED state for a new module.
 //!   `note_submit`.
 //! - NO `pre_epsilon_ms` and NO created-at time bound: filesystems have no
 //!   reliable cross-platform creation time (mtime moves on every append).
-//!   The arm-time `known_files` snapshot is the primary safety — a file
-//!   already present at arm can never bind to this terminal. The FILENAME
+//!   The `known_files` snapshot is the primary safety — a file
+//!   already present in the snapshot can never bind to this terminal. The FILENAME
 //!   timestamp and the dated `YYYY/MM/DD` dir are never used as filters
 //!   either: both are precomputed at codex session construction and can
 //!   predate on-disk creation by the entire user idle gap (the dir can even
 //!   be "yesterday" across midnight). The full-tree snapshot-diff sidesteps
 //!   both.
+//! - FIRST-SUBMIT re-snapshot (A4 hardening): the first `note_submit`
+//!   replaces `known_files` with a fresh scan — strictly safe because the
+//!   pane's own rollout cannot exist before its first Enter, so everything
+//!   that appeared between arm and the first Enter is foreign by
+//!   construction. SOUNDNESS PRECONDITION: the caller completes the first
+//!   `note_submit` BEFORE the Enter byte is written to the PTY (codex
+//!   materializes the rollout in response to that very Enter) — the
+//!   `codex_association` submit seam encodes this ordering. Later window
+//!   re-opens NEVER re-snapshot: a >2 s Enter→creation latency is recovered
+//!   by a later Enter only if the pane's own late file stays a candidate.
 //! - Attribution disambiguator: the rollout's own first-line
 //!   `session_meta.payload.cwd` is REQUIRED and must match the armed
 //!   terminal's cwd (`SessionMeta.cwd` is non-optional at 0.145.0;
@@ -532,11 +594,12 @@ module is the RED state for a new module.
 //!   artifacts (`.jsonl.zst`, present in 0.145.0 source) fail the `.jsonl`
 //!   suffix filter; fresh sessions always write plain `.jsonl`.
 //!
-//! Zero cost when idle: scans happen only at arm and at due Enter-anchored
+//! Zero cost when idle: scans happen only at arm, at the FIRST `note_submit`
+//! (the re-snapshot), and at due Enter-anchored
 //! evaluations (a pending candidate keeps its evaluation due, so re-probes
-//! ride the same gate), proven by `fs_scan_count`. Callers run BOTH `arm()`
-//! and `tick()` inside `tokio::task::spawn_blocking` (cold dentry cache is
-//! the one unmeasured tail — A6).
+//! ride the same gate), proven by `fs_scan_count`. Callers run `arm()`,
+//! `note_submit()`, and `tick()` inside `tokio::task::spawn_blocking` (cold
+//! dentry cache is the one unmeasured tail — A6).
 
 use std::collections::{HashMap, HashSet};
 use std::path::{Path, PathBuf};
@@ -665,10 +728,15 @@ impl CodexLocator {
     }
 
     /// The FIRST submit is what opens a window at all (windows are
-    /// Enter-anchored — arm schedules no deadline). Re-open semantics mirror
+    /// Enter-anchored — arm schedules no deadline), and it RE-SNAPSHOTS
+    /// `known_files` (see module doc: strictly safe because the pane's own
+    /// rollout cannot exist before its first Enter; the caller must complete
+    /// this call BEFORE the Enter byte reaches the PTY, and must run it on
+    /// the blocking pool — the re-snapshot walks the sessions tree).
+    /// Re-open semantics mirror
     /// opencode: a mid-turn Enter never re-opens a still-pending evaluation;
     /// a resolved (zero-candidate / ambiguous / contested) terminal gets a
-    /// fresh Enter-anchored deadline.
+    /// fresh Enter-anchored deadline. Re-opens NEVER re-snapshot.
     pub fn note_submit(&self, terminal_id: &str, at_ms: i64) -> bool {
         let mut inner = self.inner.lock().unwrap();
         let Some(armed) = inner.armed.get_mut(terminal_id) else {
@@ -677,6 +745,15 @@ impl CodexLocator {
         if !armed.resolved && armed.enter_ms.is_some() {
             return false;
         }
+        if armed.enter_ms.is_none() {
+            // FIRST submit: everything that appeared between arm and this
+            // Enter is foreign by construction (A1/A4) — replace the
+            // snapshot. Holding the lock across the scan is deliberate and
+            // bounded (warm walks are 7-9 ms — A6; callers are on the
+            // blocking pool); it also keeps the re-snapshot atomic with the
+            // window open.
+            armed.known_files = self.scan_rollout_files();
+        }
         armed.enter_ms = Some(at_ms);
         armed.resolved = false;
         true
@@ -1112,6 +1189,31 @@ git commit -m "feat(sessions): CodexLocator skeleton - arm gates, fs-snapshot su
         let _ = std::fs::remove_dir_all(&root);
     }
 
+    #[test]
+    fn later_enter_reopen_keeps_the_first_submit_snapshot() {
+        // Slow materialization (>2 s Enter→creation) is recovered by a later
+        // Enter ONLY if re-opens never re-snapshot: the pane's own late
+        // rollout appears between the first window's close and the second
+        // Enter, and must STAY a candidate. Only the FIRST submit
+        // re-snapshots (pinned via fs_scan_count).
+        let root = unique_temp_dir("reopen-snapshot");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0)); // first submit: re-snapshot
+        // First window closes empty.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // The pane's own rollout lands LATE — after the window, before the
+        // next Enter.
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let scans_before = locator.fs_scan_count();
+        assert!(locator.note_submit("t1", 10_000)); // re-open: NO re-snapshot
+        assert_eq!(locator.fs_scan_count(), scans_before);
+        let located = locator.tick(10_000 + CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
     #[test]
     fn mid_turn_enter_never_reopens_a_pending_evaluation() {
         let root = unique_temp_dir("midturn");
@@ -1455,7 +1557,10 @@ git commit -m "refactor(ws): extract adopt_codex_identity shared adoption tail f
 pub(crate) fn is_submit_input(data: &str) -> bool;
 pub(crate) fn maybe_arm(state: &WsState, terminal_id: &str, mode: &str,
                         cwd: Option<&str>, resume_session_id: Option<&str>);
-pub(crate) fn note_possible_submit(state: &WsState, terminal_id: &str, data: &str);
+// async, unlike the opencode sibling: the FIRST submit re-snapshots
+// known_files on the blocking pool, and the caller must await completion
+// BEFORE writing the Enter to the PTY (see the submit seam below).
+pub(crate) async fn note_possible_submit(state: &WsState, terminal_id: &str, data: &str);
 pub(crate) async fn drain_and_associate(state: &WsState);
 pub fn spawn_codex_locator_sweep(state: WsState, interval: std::time::Duration);
 ```
@@ -1499,13 +1604,13 @@ locator field to `codex_locator: Some(Arc::new(CodexLocator::new(data_home)))`
         let _ = std::fs::remove_dir_all(&dir);
     }
 
-    #[test]
-    fn note_possible_submit_feeds_only_enter_sequences() {
+    #[tokio::test]
+    async fn note_possible_submit_feeds_only_enter_sequences() {
         let dir = unique_temp_dir("assoc-submit");
         let (state, _rx) = state_with_locator(dir.clone());
         let locator = state.codex_locator.as_ref().unwrap().clone();
         maybe_arm(&state, "t1", "codex", Some("/tmp"), None);
-        note_possible_submit(&state, "t1", "hello");
+        note_possible_submit(&state, "t1", "hello").await;
         // Observable proof via the locator's own seam: "hello" must not have
         // consumed the window — a direct note_submit still returns true.
         assert!(locator.note_submit("t1", freshell_sessions::time::now_ms()));
@@ -1536,7 +1641,9 @@ Expected: COMPILE ERROR (module functions and `codex_locator` field missing).
 //! deviation: the locator's windows are ENTER-ANCHORED ONLY (no spawn
 //! window) — real codex materializes its rollout only at the first user
 //! prompt, so `maybe_arm` only takes the snapshot and `note_possible_submit`
-//! is what opens a correlation window.
+//! is what opens a correlation window (async: the FIRST submit re-snapshots
+//! `known_files` on the blocking pool and MUST complete before the Enter is
+//! written to the PTY — see the terminal.rs seam).
 
 use crate::WsState;
 
@@ -1560,12 +1667,26 @@ pub(crate) fn maybe_arm(
     }
 }
 
-pub(crate) fn note_possible_submit(state: &WsState, terminal_id: &str, data: &str) {
+/// Async, unlike the opencode sibling: the FIRST `note_submit` re-snapshots
+/// `known_files` (a bounded sessions-tree walk), so it runs on the blocking
+/// pool, and the CALLER MUST AWAIT this BEFORE writing the Enter to the PTY
+/// — codex materializes the rollout in response to that very Enter, and a
+/// re-snapshot racing after the write could capture (permanently exclude)
+/// the pane's own file. Non-submit data returns immediately; later submits
+/// are a cheap mutex hop.
+pub(crate) async fn note_possible_submit(state: &WsState, terminal_id: &str, data: &str) {
     if !is_submit_input(data) {
         return;
     }
-    if let Some(locator) = &state.codex_locator {
-        locator.note_submit(terminal_id, now_ms());
+    let Some(locator) = state.codex_locator.clone() else {
+        return;
+    };
+    let terminal_id = terminal_id.to_string();
+    let at_ms = now_ms();
+    if let Err(err) =
+        tokio::task::spawn_blocking(move || locator.note_submit(&terminal_id, at_ms)).await
+    {
+        tracing::warn!(error = %err, "codex_note_submit_panicked");
     }
 }
 
@@ -1641,9 +1762,11 @@ Wiring edits:
      `terminal.rs`'s generic resume derivation can drive `codex resume <id>`
      on restart").
    - The compiler will enumerate every literal `WsState` constructor that now
-     misses the field (association tests, other in-crate tests, main.rs).
-     Add `codex_locator: None,` everywhere except the sites Tasks 4-5 say
-     otherwise.
+     misses the field (association tests, other in-crate tests, the
+     `tests/common/mod.rs` spawn helpers, main.rs).
+     Add `codex_locator: None,` everywhere except the sites Tasks 4-6 say
+     otherwise (Task 6 adds ONE locator-wired spawn helper to
+     `tests/common/mod.rs`; that file's existing helpers stay `None`).
 2. `crates/freshell-server/src/main.rs`:
    - Next to the opencode locator construction (`:340-345` area):
      ```rust
@@ -1707,10 +1830,26 @@ Wiring edits:
      — the compile-truth is the surrounding function; the requirement is that
      `maybe_arm` executes on the blocking pool and completes before the
      create handler returns.)
-   - Submit seam — after the opencode `note_possible_submit` (`:542-546`):
+   - Submit seam — ORDERING IS LOAD-BEARING, do NOT copy the opencode seam
+     placement. In the `TerminalInput` match arm of `handle_client_text`
+     (`terminal.rs:526-548`), the PTY write
+     (`state.registry.input(&input.terminal_id, input.data.as_bytes())`,
+     `:527-529`) is currently the FIRST statement, and the amplifier/opencode
+     `note_possible_submit` calls come after it. The codex call must go
+     BEFORE the `registry.input(...)` line and be awaited:
      ```rust
-     crate::codex_association::note_possible_submit(state, &input.terminal_id, &input.data);
+     // Lane B2: MUST complete before the Enter reaches the PTY — the codex
+     // locator's FIRST-submit re-snapshot has to finish before codex can
+     // materialize the rollout this very Enter triggers (else the pane's
+     // own file could land in the snapshot and be permanently excluded).
+     // Sound here: this socket task processes frames sequentially, and the
+     // enclosing handler is already async. Non-submit data returns
+     // immediately; only the first Enter of an armed codex pane scans
+     // (7-9 ms warm — A6).
+     crate::codex_association::note_possible_submit(state, &input.terminal_id, &input.data).await;
      ```
+     Leave the amplifier/opencode seams where they are (they are in-memory
+     and order-insensitive).
    - Exit disarm — in the `ExitHook` closure (`:1354`, `:1377-1379` pattern):
      clone `let codex_locator = state.codex_locator.clone();` next to the
      opencode clone, and inside the closure after the opencode disarm add
@@ -1769,16 +1908,21 @@ REAL `PaneLedger::new(Some(dir))`. The codex adaptations, per test:
         // opencode sibling test does; maybe_arm(&state, "t1", "codex",
         // Some(&cwd), None).
         //
-        // Then write the rollout the locator must find:
+        // Then OPEN THE WINDOW FIRST:
+        // note_possible_submit(&state, "t1", "\r").await — windows are
+        // Enter-anchored (no spawn window), so resolution requires a submit,
+        // and the FIRST submit re-snapshots known_files, so the rollout MUST
+        // be seeded AFTER this call (a pre-seeded file would be captured by
+        // the re-snapshot and never bind — that exclusion is the Task 1/2
+        // hardening, not a bug).
+        //
+        // THEN write the rollout the locator must find:
         //   write a file <sessions_root>/2026/07/26/rollout-2026-07-26T08-00-00-<TID>.jsonl
         //   whose first line is {"timestamp":"...","type":"session_meta",
         //   "payload":{"id":"<TID>","cwd":"<the pane's cwd>"}}
-        // (reuse the write_rollout shape from codex_locator.rs tests inline).
-        //
-        // Then OPEN THE WINDOW: note_possible_submit(&state, "t1", "\r") —
-        // windows are Enter-anchored (no spawn window), so resolution
-        // requires a submit. The 40×100 ms drain poll comfortably covers the
-        // 2 s Enter-anchored deadline.
+        // (reuse the write_rollout shape from codex_locator.rs tests inline;
+        // the file lands well inside the 2 s window, and the 40×100 ms drain
+        // poll comfortably covers the Enter-anchored deadline).
         //
         // Poll drain_and_associate until resolution, then assert:
         //   state.identity.session_ref_for("t1") == Some(codex/<TID>)  (provider + id)
@@ -1800,8 +1944,9 @@ REAL `PaneLedger::new(Some(dir))`. The codex adaptations, per test:
         // "codex" in the ledger lookups. Record the pending marker via
         // state.pane_ledger.record_pending("t1", "codex", Some(cwd), now)
         // before resolution, exactly as the sibling does. As in the first
-        // test, add note_possible_submit(&state, "t1", "\r") after seeding
-        // the rollout — Enter-anchored windows need the submit.
+        // test, call note_possible_submit(&state, "t1", "\r").await BEFORE
+        // seeding the rollout — Enter-anchored windows need the submit, and
+        // the first-submit re-snapshot would exclude a pre-seeded file.
     }
 
     /// One-writer defense survives the channel swap: a session already bound
@@ -1812,9 +1957,11 @@ REAL `PaneLedger::new(Some(dir))`. The codex adaptations, per test:
         // with ("codex", <TID>) via state.identity.upsert(...), then retire it
         // via state.identity.retire("victim") (the exit-path call —
         // terminal.rs:1370 area shows the exact form).
-        // Register a real PTY "t1" (codex mode), arm it, seed the rollout for
-        // <TID>, note_possible_submit(&state, "t1", "\r") to open the
-        // Enter-anchored window, poll drain_and_associate past the window.
+        // Register a real PTY "t1" (codex mode), arm it, then
+        // note_possible_submit(&state, "t1", "\r").await to open the
+        // Enter-anchored window, THEN seed the rollout for <TID> (after the
+        // submit — the first-submit re-snapshot would exclude a pre-seeded
+        // file), and poll drain_and_associate past the window.
         // Assert: t1 gained NO identity (state.identity.session_ref_for("t1")
         // is None) and its registry entry's resume_session_id is None.
     }
@@ -1857,21 +2004,63 @@ git commit -m "test(ws): codex drain_and_associate binds identity+ledger+broadca
 
 **Files:**
 - Create: `crates/freshell-ws/tests/codex_locator_activity.rs`
+- Modify: `crates/freshell-ws/tests/common/mod.rs` (ONE new spawn helper — see Step 1; without it this test CANNOT pass)
 - Test: same file
 
 **Interfaces:**
-- Consumes: the full server harness helpers in
-  `crates/freshell-ws/tests/codex_candidate_activity.rs` (`spawn_server`,
-  `write_fake_codex()` + `codex_capture_spec()`, frame-await helpers — copy
-  them; that file is deleted next task, so this new file must be
-  self-contained) and the locator pipeline from Tasks 1-5.
+- Consumes: the per-test helpers in
+  `crates/freshell-ws/tests/codex_candidate_activity.rs` (`write_fake_codex`
+  `:24`, `codex_capture_spec` `:44`, `send_create` `:64`, `wait_for_frame`
+  `:110` — all local to that file; copy them, that file is deleted next
+  task, so the new file must be self-contained), the shared harness in
+  `tests/common/mod.rs`, and the locator pipeline from Tasks 1-5.
+- HARNESS GAP (load-bearing): every existing `spawn_server_*` helper in
+  `tests/common/mod.rs` builds its `WsState` literal with
+  `amplifier_locator: None, opencode_locator: None` (`:135/:215/:291/:356`)
+  — after Task 4's compile sweep they all get `codex_locator: None` too —
+  and NO test harness spawns any locator sweep (sweeps live only in
+  `main.rs:626/:636`). A test spawned through the unmodified harness has no
+  locator and no sweep, so identity can never resolve and every await below
+  would time out. Step 1 therefore adds a locator-wired helper.
 - Produces: the closing pin for the identity-less status gap — fresh codex
   panes' `codex.activity.updated` / `terminal.turn.complete` carry
   `sessionId` with NO client candidate frame.
 
-- [ ] **Step 1: Write the failing test**
+- [ ] **Step 1: Write the failing test (and the harness helper it needs)**
+
+First, in `crates/freshell-ws/tests/common/mod.rs`, add ONE new spawn helper
+following that file's established copy-a-variant convention: copy
+`spawn_server_with_specs_and_activity` (`:243-307`) into a sibling
+
+```rust
+pub async fn spawn_server_with_specs_activity_and_codex_locator(
+    specs: /* same as the donor */,
+    codex_sessions_root: &std::path::Path,
+) -> /* same return type as the donor */
+```
+
+with exactly two deltas from the copied body (everything else identical):
+1. In the `WsState` literal, set
+   `codex_locator: Some(std::sync::Arc::new(freshell_sessions::codex_locator::CodexLocator::new(codex_sessions_root.to_path_buf()))),`
+   instead of `None`.
+2. Immediately BEFORE the `freshell_ws::router(state)` line, spawn the sweep
+   on a clone (`WsState` is `Clone` with shared-`Arc` fields, so the sweep
+   and the router see the same locator/registry/identity):
+   ```rust
+   // Mirrors main.rs's sweep wiring; 150 ms is re-declared here because
+   // main.rs's AMPLIFIER_LOCATOR_SWEEP_INTERVAL is private to the server
+   // binary.
+   freshell_ws::codex_association::spawn_codex_locator_sweep(
+       state.clone(),
+       std::time::Duration::from_millis(150),
+   );
+   ```
+The other spawn helpers in `common/mod.rs` keep `codex_locator: None`
+(Task 4's compile sweep). The test passes
+`<CODEX_HOME>/sessions` as `codex_sessions_root` — the same root
+`codex_sessions_root()` resolves in the real server.
 
-Create `crates/freshell-ws/tests/codex_locator_activity.rs`:
+Then create `crates/freshell-ws/tests/codex_locator_activity.rs`:
 
 ```rust
 //! Lane B2: a FRESH codex terminal (no resume id, NO client candidate frame)
@@ -1890,20 +2079,35 @@ from `codex_candidate_activity.rs::adopted_candidate_identity_reaches_codex_acti
 1. Keep: `CODEX_HOME` tempdir env, server spawn, fake codex
    binary/`codex_capture_spec()`, creating a FRESH codex terminal over the
    socket, the `codex.activity.updated` await helper.
-2. DELETE the candidate-frame send. Instead, AFTER the terminal is created
-   (locator armed at create), write the rollout file the locator must find:
-   `<CODEX_HOME>/sessions/2026/07/24/rollout-2026-07-24T12-00-00-<THREAD>.jsonl`
-   with first line
-   `{"timestamp":"2026-07-24T12:00:00.000Z","type":"session_meta","payload":{"id":"<THREAD>","cwd":"<terminal cwd>"}}`
-   — the terminal's cwd is whatever the harness passed to terminal.create;
-   use that same value. THEN send a single `terminal.input` of `"\r"` over
-   the socket: windows are Enter-anchored (validated A1 — real codex
-   materializes the rollout only at the first user prompt; there is no spawn
-   window), so the submit is what opens the 2 s evaluation window.
-3. Await `codex.activity.updated` carrying `sessionId == <THREAD>` (the sweep
-   runs every 150 ms in the real server; give the await the same generous
-   timeout the donor test used).
-4. Then append two task-event lines to the SAME rollout file (copy the
+2. SPAWN through the new helper: set the `CODEX_HOME` tempdir env exactly as
+   the donor does, then call
+   `spawn_server_with_specs_activity_and_codex_locator(vec![codex_capture_spec()], &codex_home.join("sessions"))`
+   instead of `spawn_server_with_specs_and_activity(...)`.
+3. DELETE the candidate-frame send. Instead, AFTER the terminal is created
+   (locator armed at create), run this exact sequence — the order is
+   load-bearing because the FIRST submit re-snapshots `known_files` (Task 1
+   hardening), so the rollout must NOT exist yet at the first Enter:
+   a. Send a single `terminal.input` of `"\r"` over the socket: windows are
+      Enter-anchored (validated A1 — real codex materializes the rollout
+      only at the first user prompt; there is no spawn window), and this
+      first Enter takes the re-snapshot and opens the 2 s window.
+   b. Sleep ~3 s (`tokio::time::sleep`) so that first window resolves with
+      zero candidates (deadline 2 s + 150 ms sweep, with margin).
+   c. Write the rollout file the locator must find:
+      `<CODEX_HOME>/sessions/2026/07/24/rollout-2026-07-24T12-00-00-<THREAD>.jsonl`
+      with first line
+      `{"timestamp":"2026-07-24T12:00:00.000Z","type":"session_meta","payload":{"id":"<THREAD>","cwd":"<terminal cwd>"}}`
+      — the terminal's cwd is whatever the harness passed to
+      terminal.create; use that same value.
+   d. Send a second `terminal.input` of `"\r"`: a later Enter re-opens a
+      resolved window WITHOUT re-snapshotting (pinned by Task 2's
+      `later_enter_reopen_keeps_the_first_submit_snapshot`), so the file
+      written in (c) is deterministically the sole new candidate.
+4. Await `codex.activity.updated` carrying `sessionId == <THREAD>` (the
+   harness helper spawns the same 150 ms sweep main.rs uses; give the await
+   the same generous timeout the donor test used — it must cover the ~2 s
+   Enter-anchored deadline after (d)).
+5. Then append two task-event lines to the SAME rollout file (copy the
    `event_msg` line shapes from `activity.rs`'s `codex_event_line` helper,
    `:2381-2385` — `task_started` then `task_complete`, timestamps now-ish),
    and await a `terminal.turn.complete` frame asserting
@@ -1911,12 +2115,17 @@ from `codex_candidate_activity.rs::adopted_candidate_identity_reaches_codex_acti
    locator's `attach_codex_rollout` handed the file to the status watcher and
    completions are stamped.
 
-Note on determinism: resolution REQUIRES the Enter — there is no spawn
-window. Write the rollout file first, then send the `"\r"`; the
-Enter-anchored deadline (2 s later, swept every 150 ms) evaluates and binds.
-If flake appears because of ordering, send another `"\r"` — a later Enter
-re-opens the window (pinned by Task 2's
-`zero_candidate_window_keeps_watching_and_later_enter_reopens`).
+Note on determinism: resolution REQUIRES an Enter — there is no spawn
+window — and the rollout must be written strictly BETWEEN the first Enter's
+re-snapshot and a later Enter's re-opened window; the two-Enter sequence in
+step 3 guarantees that ordering without racing the server (the test cannot
+observe when the server finishes processing an input frame, so "write the
+file right after sending the first `\r`" would race the re-snapshot and
+could permanently exclude the file). If flake appears, lengthen the (b)
+sleep or send another `"\r"` — every later Enter re-opens the window against
+the same frozen snapshot (pinned by Task 2's
+`zero_candidate_window_keeps_watching_and_later_enter_reopens` and
+`later_enter_reopen_keeps_the_first_submit_snapshot`).
 
 - [ ] **Step 2: Run to verify it fails for the right reason**
 
@@ -1925,7 +2134,10 @@ Expected: with Tasks 1-5 landed this may already PASS — apply the inversion
 check (assert `session_id` is `None`, watch it fail, restore). If it fails
 for a REAL reason (e.g. `turn.complete` lacks sessionId because
 `attach_codex_rollout` wasn't reached), that is the red this task exists to
-fix — fix in the Task 3/4 modules, minimally.
+fix — fix in the Task 3/4 modules, minimally. If instead the awaits time out
+with identity never resolving at all, first suspect THIS task's harness
+wiring (the new `common/mod.rs` helper: locator field set, sweep spawned,
+root == `<CODEX_HOME>/sessions`) before touching Task 3/4 code.
 
 - [ ] **Step 3: Run to GREEN**
 
@@ -1937,8 +2149,8 @@ Expected: PASS.
 ```bash
 cargo fmt --all
 cargo clippy -p freshell-ws --all-targets -- -D warnings
-git add crates/freshell-ws/tests/codex_locator_activity.rs
-git commit -m "test(ws): fresh codex pane turn.complete carries sessionId via server-side locator"
+git add crates/freshell-ws/tests/codex_locator_activity.rs crates/freshell-ws/tests/common/mod.rs
+git commit -m "test(ws): fresh codex pane turn.complete carries sessionId via server-side locator (adds locator-wired spawn helper to the shared harness)"
 ```
 
 ---
@@ -2084,10 +2296,16 @@ codex_candidate_inert.rs and codex_locator_activity.rs)."
 - Consumes: env `CODEX_HOME` (set per-server by the RustServer harness),
   `FAKE_CODEX_TERMINAL_ARGV_LOG`, `FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH`.
 - Produces (Tasks 9-10 rely on these EXACT behaviors):
-  - fresh mode: prints `codex> `, and on FIRST stdin data writes
+  - fresh mode: prints `codex> `, and on the FIRST stdin chunk containing an
+    Enter (CR or LF) writes
     `<CODEX_HOME|~/.codex>/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl`
     (first line `session_meta` with `payload.id` + `payload.cwd`) then prints
-    `codex: session <uuid> started`;
+    `codex: session <uuid> started`. Enter-gating (NOT first-data) is
+    load-bearing: it mirrors validated Premise 7 (real codex materializes
+    the rollout only at the first user prompt), and the server re-snapshots
+    `known_files` before forwarding the first Enter to the PTY — a fixture
+    that wrote on mere typing would land its rollout PRE-snapshot and be
+    permanently excluded;
   - gate: when `FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH` is set, the write
     waits (50 ms poll) until that file exists — a never-created gate makes
     "identity never resolves" deterministic;
@@ -2104,9 +2322,14 @@ codex_candidate_inert.rs and codex_locator_activity.rs)."
 // identity artifact is a rollout JSONL under CODEX_HOME/sessions whose FIRST
 // line is the session_meta ownership record (payload.id — never the
 // filename — is the identity; payload.cwd is the locator's disambiguator).
-// - fresh: prints `codex> `; on FIRST stdin data writes the rollout (gated
-//   by FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH when set) and prints
-//   `codex: session <uuid> started`.
+// - fresh: prints `codex> `; on the FIRST stdin chunk containing an Enter
+//   (CR/LF) writes the rollout (gated by
+//   FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH when set) and prints
+//   `codex: session <uuid> started`. Enter-gating mirrors real codex
+//   (Premise 7: the rollout materializes only at the first user prompt) and
+//   keeps the fixture on the safe side of the server's first-submit
+//   known_files re-snapshot, which completes before the Enter reaches this
+//   process.
 // - resume (`resume` ANYWHERE in argv — resumeArgs are appended LAST after
 //   `-c` overrides): prints `codex: resumed session <id>`, writes nothing.
 // - argv mirrored to FAKE_CODEX_TERMINAL_ARGV_LOG as JSONL.
@@ -2156,8 +2379,12 @@ if (resumeIndex !== -1) {
 } else {
   process.stdout.write('codex> \r\n')
   let wrote = false
-  process.stdin.on('data', () => {
+  process.stdin.on('data', (chunk) => {
     if (wrote) return
+    const s = String(chunk)
+    // Enter-anchored, like real codex (Premise 7): typing alone must not
+    // create the rollout — only the first Enter does.
+    if (!s.includes('\r') && !s.includes('\n')) return
     wrote = true
     const threadId = crypto.randomUUID()
     const finish = () => {
@@ -2477,8 +2704,10 @@ results incl. wall disposition, and the scope-fence note that REST-lane
   takes only the snapshot) → Tasks 1-2, 4.
 - Misbind hardenings from the A4 adversarial validation (required cwd,
   pending-first-line bind-blocking grace, cross-tick contested-cwd refusal,
-  bound-elsewhere adoption refusal) → Tasks 1-3, pinned by Task 2's guard
-  tests and Task 5 test 3; the freshagent same-cwd residual is documented in
+  bound-elsewhere adoption refusal, first-submit known_files re-snapshot with
+  Task 4's before-PTY-write seam ordering) → Tasks 1-4, pinned by Task 1/2's
+  guard tests and Task 5 test 3; the post-first-Enter same-cwd residual
+  (freshagent sidecar) is documented in
   Validated Premise 10 and named in Task 11's report, not silently absorbed.
 - Reuse-don't-duplicate the wave-2 watcher → Premise Correction 2: discovery
   cannot ride the per-file status watcher (verified structural fact); the

From ee9374d6f052ab2a092447cda5b12828ecd8062c Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:28:37 -0700
Subject: [PATCH 14/87] feat(ws): sessionRef-level attach in verdict derivation
 + duplicate-PTY invariant alarm
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Council rule 6 (reconcile side): a pane claiming a sessionRef that a LIVE
terminal already carries now gets attach{terminalId} regardless of
createRequestId, closing the D8 second-writer respawn shape. The lookup
consults BOTH identity stores, mirroring resolve_authoritative_ref's
dual-source read: the ws-owned identity registry (live entry, re-verified
against registry liveness) then the registry-row join
(mode + resume_session_id + Running) for REST-created resumes whose
identity never reached the identity registry.

Council rule 9: TerminalRegistry::alarm_if_duplicate_session_ref ERROR-logs
(target "invariant", duplicate_pty_for_session_ref) when >=2 live PTYs
carry one sessionRef, and returns whether the invariant is violated.
TerminalRegistry::live_terminal_for_session_ref exposes the row-join
(newest generation first). Tasks 5/6 consume both.

No existing test asserted respawn where the new branch fires — no D8-pinning
tests needed updating; the full freshell-terminal and freshell-ws suites
pass unchanged.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-terminal/src/registry.rs   | 147 +++++++++++++++++++++
 crates/freshell-ws/src/reconcile.rs        |  72 ++++++++++
 crates/freshell-ws/tests/pane_reconcile.rs |  39 ++++++
 3 files changed, 258 insertions(+)

diff --git a/crates/freshell-terminal/src/registry.rs b/crates/freshell-terminal/src/registry.rs
index b3e7a5152..9ec59884c 100644
--- a/crates/freshell-terminal/src/registry.rs
+++ b/crates/freshell-terminal/src/registry.rs
@@ -1631,6 +1631,72 @@ impl TerminalRegistry {
         }
     }
 
+    /// Live terminal ids currently carrying this sessionRef via the
+    /// registry-row join: `mode == locator.provider &&
+    /// resume_session_id == Some(locator.session_id) && status Running`,
+    /// newest generation first (`created_at` desc, `terminal_id` desc
+    /// tie-break, mirroring [`Self::terminals_by_create_request_id`]).
+    ///
+    /// LOOKUP DESIGN (validator-corrected): registry rows have NO dedicated
+    /// `session_ref` field ([`TerminalShared::inventory`] hardcodes
+    /// `session_ref: None`), so row identity IS this join. Rows are one of
+    /// the TWO identity stores — the other is `freshell-ws`'s identity
+    /// registry, which this crate cannot see (dep direction) — so ws-side
+    /// callers consult both.
+    fn live_terminal_ids_for_session_ref(&self, locator: &SessionLocator) -> Vec<String> {
+        let shareds: Vec<Arc<Mutex<TerminalShared>>> = {
+            let inner = self.inner.lock().expect("registry lock");
+            inner
+                .terminals
+                .values()
+                .map(|h| Arc::clone(&h.shared))
+                .collect()
+        };
+        let mut rows: Vec<(i64, String)> = shareds
+            .iter()
+            .filter_map(|shared| {
+                let s = shared.lock().expect("terminal lock");
+                if s.status == TerminalRunStatus::Running
+                    && s.mode == locator.provider
+                    && s.resume_session_id.as_deref() == Some(locator.session_id.as_str())
+                {
+                    Some((s.created_at, s.terminal_id.clone()))
+                } else {
+                    None
+                }
+            })
+            .collect();
+        rows.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| b.1.cmp(&a.1)));
+        rows.into_iter().map(|(_, id)| id).collect()
+    }
+
+    /// Council rule 6: the live terminal (newest first) currently carrying
+    /// this sessionRef, if any — the reconcile derivation and the create-path
+    /// lease (Tasks 5/6) attach every other client's claim for the same ref
+    /// to this winner, regardless of `createRequestId`.
+    pub fn live_terminal_for_session_ref(&self, locator: &SessionLocator) -> Option<String> {
+        self.live_terminal_ids_for_session_ref(locator)
+            .into_iter()
+            .next()
+    }
+
+    /// Council rule 9, D8 backstop: >=2 live PTYs carrying one sessionRef is
+    /// the two-writers corruption shape. Alarm loudly (ERROR-level invariant
+    /// log); never kill silently. Returns whether the invariant is violated.
+    pub fn alarm_if_duplicate_session_ref(&self, locator: &SessionLocator) -> bool {
+        let live = self.live_terminal_ids_for_session_ref(locator);
+        if live.len() >= 2 {
+            tracing::error!(target: "invariant",
+                provider = %locator.provider,
+                session_id = %locator.session_id,
+                live = live.len(),
+                terminal_ids = ?live,
+                "duplicate_pty_for_session_ref: >=2 live PTYs share one sessionRef");
+            return true;
+        }
+        false
+    }
+
     /// The current `terminals.changed.revision` (run-monotonic, `§7.5`).
     pub fn revision(&self) -> i64 {
         self.inner.lock().expect("registry lock").revision
@@ -3469,6 +3535,87 @@ mod tests {
         );
     }
 
+    /// Council rule 6 support: the registry-row join (mode +
+    /// resume_session_id + Running) finds the live terminal carrying a
+    /// sessionRef — exited generations and other providers/sessions never
+    /// match.
+    #[test]
+    fn live_terminal_for_session_ref_joins_rows_on_mode_and_resume_id() {
+        let reg = TerminalRegistry::new();
+        reg.register_headless(HeadlessTerminal {
+            terminal_id: "T-ref".to_string(),
+            stream_id: "S-ref".to_string(),
+            mode: "codex".to_string(),
+            resume_session_id: Some("sess-r".to_string()),
+            create_request_id: Some("cr-a".to_string()),
+            created_at: Some(1_000),
+        });
+        let locator = SessionLocator {
+            provider: "codex".to_string(),
+            session_id: "sess-r".to_string(),
+        };
+        assert_eq!(
+            reg.live_terminal_for_session_ref(&locator),
+            Some("T-ref".to_string())
+        );
+        // Wrong provider / wrong session never match.
+        assert!(reg
+            .live_terminal_for_session_ref(&SessionLocator {
+                provider: "claude".to_string(),
+                session_id: "sess-r".to_string(),
+            })
+            .is_none());
+        assert!(reg
+            .live_terminal_for_session_ref(&SessionLocator {
+                provider: "codex".to_string(),
+                session_id: "other".to_string(),
+            })
+            .is_none());
+        // An exited terminal is not a live carrier.
+        reg.finish_pty_exit("T-ref", 0);
+        assert!(reg.live_terminal_for_session_ref(&locator).is_none());
+    }
+
+    /// Council rule 9 (D8 backstop): >=2 live PTYs stamped with ONE
+    /// sessionRef is the two-writers corruption shape — the alarm returns
+    /// true and ERROR-logs `duplicate_pty_for_session_ref`; one live carrier
+    /// returns false and stays silent.
+    #[test]
+    fn alarm_if_duplicate_session_ref_fires_only_on_two_live_carriers() {
+        let (events, _guard) = tracing_capture::capture();
+        let reg = TerminalRegistry::new();
+        let stamped = |id: &str, created_at: i64| HeadlessTerminal {
+            terminal_id: id.to_string(),
+            stream_id: format!("S-{id}"),
+            mode: "claude".to_string(),
+            resume_session_id: Some("sess-dup".to_string()),
+            create_request_id: None,
+            created_at: Some(created_at),
+        };
+        let locator = SessionLocator {
+            provider: "claude".to_string(),
+            session_id: "sess-dup".to_string(),
+        };
+
+        reg.register_headless(stamped("dupA", 1_000));
+        assert!(
+            !reg.alarm_if_duplicate_session_ref(&locator),
+            "one live carrier must not trip the alarm"
+        );
+
+        reg.register_headless(stamped("dupB", 2_000));
+        assert!(reg.alarm_if_duplicate_session_ref(&locator));
+        let captured = events.lock().unwrap();
+        let alarm = captured
+            .iter()
+            .find(|e| e.message.contains("duplicate_pty_for_session_ref"))
+            .expect(">=2 live PTYs on one sessionRef must emit the invariant alarm");
+        assert_eq!(
+            alarm.fields.get("session_id").map(String::as_str),
+            Some("sess-dup")
+        );
+    }
+
     /// §5.1 atomic-stamp insert-edge interleave (§9.1 test 5): the key is part
     /// of the row inserted under the registry lock, so an observer's
     /// `newest_live_by_create_request_id` sees either no row or the
diff --git a/crates/freshell-ws/src/reconcile.rs b/crates/freshell-ws/src/reconcile.rs
index 460731f81..c12052d21 100644
--- a/crates/freshell-ws/src/reconcile.rs
+++ b/crates/freshell-ws/src/reconcile.rs
@@ -158,6 +158,28 @@ fn attach(
     }
 }
 
+/// Council rule 6: the live terminal (if any) currently carrying this CLAIMED
+/// sessionRef — consulted across BOTH identity stores, mirroring
+/// [`resolve_authoritative_ref`]'s dual-source read: the ws-owned identity
+/// registry (live entries, re-verified against registry liveness so a stale
+/// un-retired entry never produces a phantom attach), then the registry-row
+/// join (REST-created resumes whose identity never reached the identity
+/// registry across the crate boundary).
+fn live_terminal_for_claimed_ref(
+    deps: &ReconcileDeps<'_>,
+    claim: &SessionLocator,
+) -> Option<String> {
+    if let Some(entry) = deps
+        .identity
+        .find_by_session(&claim.provider, &claim.session_id)
+    {
+        if deps.registry.is_live(&entry.terminal_id) {
+            return Some(entry.terminal_id);
+        }
+    }
+    deps.registry.live_terminal_for_session_ref(claim)
+}
+
 fn verdict_for_pane(deps: &ReconcileDeps<'_>, pane: &ReconcilePane) -> PaneVerdict {
     // §5.3 row 10 protocol hygiene: malformed entries get an explicit reason.
     if pane.pane_key.is_empty() {
@@ -177,6 +199,27 @@ fn verdict_for_pane(deps: &ReconcileDeps<'_>, pane: &ReconcilePane) -> PaneVerdi
         return invalid(pane, "missing_create_request_id");
     };
 
+    // Council rule 6 (sessionRef-level single-flight, reconcile side): a
+    // live terminal ALREADY carrying the claimed sessionRef wins over
+    // createRequestId keying — every other client's claim for the same ref
+    // (regardless of createRequestId) attaches to the winner, never a
+    // respawn that would open a second JSONL writer (D8).
+    if let Some(claim) = pane.session_ref.as_ref() {
+        if let Some(tid) = live_terminal_for_claimed_ref(deps, claim) {
+            let server_ref = deps
+                .identity
+                .session_ref_for(&tid)
+                .or_else(|| Some(claim.clone()));
+            let corrected = corrected_flag(pane.session_ref.as_ref(), server_ref.as_ref());
+            return PaneVerdict {
+                terminal_id: Some(tid),
+                session_ref: server_ref,
+                corrected,
+                ..base(pane, ReconcileVerdict::Attach)
+            };
+        }
+    }
+
     // Rows 1/2/2b: any LIVE terminal wins.
     let t1 = deps.registry.newest_live_by_create_request_id(&key);
     let t2 = pane
@@ -690,6 +733,35 @@ mod tests {
         );
     }
 
+    /// Council rule 6, registry-row half: a REST-created LIVE terminal whose
+    /// identity lives ONLY on the registry row (resume_session_id, no
+    /// identity-registry entry) still answers a different client's claim for
+    /// the same sessionRef with attach{its terminalId} — never a second
+    /// writer (D8).
+    #[test]
+    fn cross_client_claim_attaches_to_live_rest_created_terminal() {
+        let f = Fixture::new();
+        f.registry.register_headless(HeadlessTerminal {
+            terminal_id: "T-rest-live".to_string(),
+            stream_id: "S-rest-live".to_string(),
+            mode: "codex".to_string(),
+            resume_session_id: Some("s-shared".to_string()),
+            create_request_id: Some("cr-WINNER".to_string()),
+            created_at: Some(1_000),
+        });
+        // Session Present on disk — the D8 shape would otherwise be respawn.
+        f.probe.set("codex", "s-shared", SessionExistence::Present);
+
+        let mut p = pane("cr-OTHER");
+        p.mode = Some("codex".to_string());
+        p.session_ref = Some(sref("codex", "s-shared"));
+        let v = f.one(p);
+        assert_eq!(v.verdict, ReconcileVerdict::Attach);
+        assert_eq!(v.terminal_id.as_deref(), Some("T-rest-live"));
+        assert_eq!(v.session_ref, Some(sref("codex", "s-shared")));
+        assert_eq!(v.corrected, None, "the claim matched server truth");
+    }
+
     /// §9.1 test 8 trust boundary, respawn shape: the claim contradicts the
     /// retired server identity → server ref + corrected: true.
     #[test]
diff --git a/crates/freshell-ws/tests/pane_reconcile.rs b/crates/freshell-ws/tests/pane_reconcile.rs
index d63bb2ad9..8e6b0d1ac 100644
--- a/crates/freshell-ws/tests/pane_reconcile.rs
+++ b/crates/freshell-ws/tests/pane_reconcile.rs
@@ -508,6 +508,45 @@ async fn contradicting_claim_is_answered_with_server_ref_and_corrected() {
     assert_eq!(verdict["corrected"], true);
 }
 
+/// Council rule 6 (sessionRef-level single-flight, reconcile side): a live
+/// terminal spawned under createRequestId A and identity-stamped with
+/// sessionRef {claude, sess-x} answers a reconcile claim from
+/// createRequestId B (a different client) with attach{terminalId of A's
+/// terminal} — never a second writer for the same session file (D8).
+#[tokio::test]
+async fn different_create_request_id_same_session_ref_gets_attach_to_winner() {
+    let server = spawn_server().await;
+    // Seed: headless terminal live in the registry, identity-stamped with
+    // sessionRef {claude, sess-x} (the existing seeding pattern).
+    headless(&server, "T-winner", Some("cr-WINNER"), "claude", 1_000);
+    server
+        .identity
+        .upsert("T-winner", Some("claude"), Some("sess-x"), None, 1);
+
+    let (mut ws, _ready) = connect(&server.url, true).await;
+    ws.send(reconcile_request(
+        "rec-xclient",
+        serde_json::json!([{
+            "paneKey": "pk-x",
+            "kind": "terminal",
+            "mode": "claude",
+            "createRequestId": "cr-OTHER",
+            "sessionRef": { "provider": "claude", "sessionId": "sess-x" }
+        }]),
+    ))
+    .await
+    .expect("send request");
+
+    let result = next_frame_of_type(&mut ws, "pane.reconcile.result").await;
+    let v = &result["verdicts"][0];
+    assert_eq!(v["verdict"], "attach");
+    assert_eq!(v["terminalId"], "T-winner");
+    assert_eq!(
+        v["sessionRef"],
+        serde_json::json!({ "provider": "claude", "sessionId": "sess-x" })
+    );
+}
+
 // --- 9.1.10 single-flight create-dedupe --------------------------------------------
 
 /// Change #1 (the council's two-tab double-respawn blocker): on a

From 264549b67dcb6557f76963c17cdd8e81038fa810 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:31:43 -0700
Subject: [PATCH 15/87] docs: fix fresheyes iteration-2 blockers in
 recover-my-panes plan

- Task 4: correct buildQueryString call shape to the real tuple-entries
  signature (api.ts:273) in both the Interfaces block and the api.ts
  implementation snippet; getRecoveryInventory now typechecks and runs.
- Task 8: replace the copied codex-syntax hasResumePair (bare 'resume')
  with an in-spec hasClaudeResumePair matching the fake claude CLI's
  --resume flag, so Scenario 1's accept-resume poll can pass and
  Scenario 3's D7 negative assertion is non-vacuous.
- D2/D4 + Tasks 1/2/3/4/5: close the same-fresh-browser multi-window
  self-pollution hole with a bootAgoMs concurrent-client cutoff (A16):
  boot-state exports bootCapturedAtMs, the pending flag persists
  {contentId, bootAt}, the inventory request carries bootAgoMs, and
  select_foreign_recent_generation_ids drops clients born after the
  boot cutoff (new unit test) so junk fresh windows can never win
  primary-device selection over the genuinely lost device.
---
 docs/plans/2026-07-26-recover-my-panes.md | 135 +++++++++++++++-------
 1 file changed, 95 insertions(+), 40 deletions(-)

diff --git a/docs/plans/2026-07-26-recover-my-panes.md b/docs/plans/2026-07-26-recover-my-panes.md
index c686c66e9..c7038c9fa 100644
--- a/docs/plans/2026-07-26-recover-my-panes.md
+++ b/docs/plans/2026-07-26-recover-my-panes.md
@@ -28,9 +28,9 @@ Within Option A, per the directive "reuse what serves the UI flow, DELETE what d
 
 Consequences: *empty-never* and *empty-cleared* browsers (both have no layout key) get the offer — correct, both are genuinely new-browser situations. *Same-browser reload with intact localStorage* (key present) never sees the offer — even if the user deliberately closed all tabs (key present, zero tabs). Principle 4 ("never ask when we can act") is not violated: an empty client layout gives the server no client claim to adjudicate; silently materializing another device's layout onto a possibly-brand-new user's browser would be "silently wrong," so offering is the correct reading (the campaign plan's §4.4 itself says "offer"). `serverInstanceId` is NOT part of the trigger — snapshots and the ledger persist across restarts, and `restoreLayout` strips live-attach fields anyway.
 
-**D2 — Self-pollution filter.** A fresh browser context mints a fresh per-window `clientInstanceId` (sessionStorage) and starts pushing snapshots (auto shell tab) within seconds. The inventory request carries `?clientInstanceId=<current>`; the server excludes that client's generations when building each device union, so the requester's own junk pushes never appear as "recoverable." (A fresh browser also mints a fresh `deviceId`, so its pushes usually land in a different device dir — the filter covers the selective-clear case where the deviceId survived.)
+**D2 — Self-pollution filter.** A fresh browser context mints a fresh per-window `clientInstanceId` (sessionStorage) and starts pushing snapshots (auto shell tab) within seconds. The inventory request carries `?clientInstanceId=<current>`; the server excludes that client's generations when building each device union, so the requester's own junk pushes never appear as "recoverable." (A fresh browser also mints a fresh `deviceId`, so its pushes usually land in a different device dir — the filter covers the selective-clear case where the deviceId survived.) The per-window exclusion alone is NOT enough: opening the fresh browser with TWO windows (routine — session-restore of pinned tabs) makes each window's junk pushes *foreign* to the other window's request, and since they carry the newest `capturedAt` by construction they would win primary-device selection and demote the genuinely lost device to `otherDevices` (which accept does not restore). Therefore the request ALSO carries `bootAgoMs` — the elapsed milliseconds since the D1 boot-state capture (a DURATION, so client/server clock skew is irrelevant; for a D3 pending re-offer, elapsed since the ORIGINAL capture time persisted with the pending flag). The server computes `boot_cutoff = now_ms() - bootAgoMs` and drops every client ALL of whose retained generations have `capturedAt >= boot_cutoff` (the A16 concurrent-client rule in Task 1): a client that first pushed after this browser session booted is by definition not lost data — it is a concurrently-opened fresh window (or other concurrently-born client), never the lost device, whose clients' pushes ALL predate the fresh boot (so generation-retention depth cannot misclassify a real client). `capturedAt` is server-stamped at generation write time (`tabs_persist.rs:812-821`), so the comparison is server-clock-only.
 
-**D3 — Dismissal + pending persistence.** Decline writes the inventory `contentId` to `localStorage["freshell.recovery.dismissed.v1"]` (array, capped at 20). While the offer is shown but undecided, `localStorage["freshell.recovery.pending.v1"] = contentId` so a reload mid-decision (which by then has a persisted auto-tab layout) re-offers instead of silently losing the recovery chance; accept/decline clears it. "Decline is remembered" means: remembered until the recoverable SUBSTANCE changes. The `contentId` is a sha256 over timestamp-free substance (Task 1), so a dismissal survives server heartbeat re-pushes (which stamp a new `capturedAt` every ≤5 min whenever a second client is connected), server restarts, and Rust upgrades; only a real change to the recoverable panes/sessions re-offers.
+**D3 — Dismissal + pending persistence.** Decline writes the inventory `contentId` to `localStorage["freshell.recovery.dismissed.v1"]` (array, capped at 20). While the offer is shown but undecided, `localStorage["freshell.recovery.pending.v1"] = JSON.stringify({contentId, bootAt})` (where `bootAt` is the boot-state capture `Date.now()`) so a reload mid-decision (which by then has a persisted auto-tab layout) re-offers instead of silently losing the recovery chance — and the re-offer derives `bootAgoMs` from the ORIGINAL `bootAt`, keeping D2's concurrent-client filter anchored to the pre-junk moment; accept/decline clears it. "Decline is remembered" means: remembered until the recoverable SUBSTANCE changes. The `contentId` is a sha256 over timestamp-free substance (Task 1), so a dismissal survives server heartbeat re-pushes (which stamp a new `capturedAt` every ≤5 min whenever a second client is connected), server restarts, and Rust upgrades; only a real change to the recoverable panes/sessions re-offers.
 
 **D4 — Authority chain (§4.2): ledger identity beats snapshot claim.** For each snapshot pane with a `sessionRef`, the server joins the ledger and reports a verdict; the client uses `effectiveSessionRef`:
 - ledger row chain (following `supersededBy`, max 10 hops) ends at a `bound` row → resume the **ledger's** `{provider, sessionId}` (snapshot claim overridden).
@@ -40,7 +40,7 @@ Consequences: *empty-never* and *empty-cleared* browsers (both have no layout ke
 
 Claude resume requires canonical-UUID session ids (`is_canonical_claude_session_id`, `terminal.rs:1652-1660`): a non-canonical claude ref fails LOUD per-pane with `RestoreUnavailable` (`terminal.rs:1104-1117`) — acceptable, not silent.
 
-Bound ledger rows whose `(provider, sessionId)` matches no **effective** pane ref in ANY device union (not just the primary) and that are not owned by a currently-Running terminal (see D7) are returned as `ledgerOnly` and recreated in an extra "Recovered sessions" tab, so ledger-known sessions are never dropped just because layout was lost. Residual: primary-device selection is argmax `capturedAt` and can pick a device the user didn't lose; mitigation — the offer shows `deviceLabel` + `otherDevices`, and decline is cheap.
+Bound ledger rows whose `(provider, sessionId)` matches no **effective** pane ref in ANY device union (not just the primary) and that are not owned by a currently-Running terminal (see D7) are returned as `ledgerOnly` and recreated in an extra "Recovered sessions" tab, so ledger-known sessions are never dropped just because layout was lost. Residual: primary-device selection is argmax `capturedAt` and can pick a device the user didn't lose. Same-fresh-browser multi-window junk can NOT win primary — every concurrent window's client is born after the boot cutoff and is dropped by D2's `bootAgoMs` concurrent-client filter — so the residual is only a genuinely pre-existing OTHER device (e.g. a second machine still connected) out-winning the lost one; mitigation — the offer shows `deviceLabel` + `otherDevices`, and decline is cheap.
 
 **D5 — Recreation path.** Accept dispatches, per inventory tab: `addTab({id: nanoid(), title: tabName})` then `restoreLayout({tabId, layout, paneTitles})` — the exact path `reopenClosedTab` already exercises. `restoreLayout` re-mints `createRequestId`/`status` and strips `terminalId`, so after dispatch we read the post-normalization layout back from the store and arm terminal restore via `addTerminalRestoreRequestId(...)` for every terminal leaf carrying a `sessionRef` (the `App.tsx:1069` / `terminal-restore.ts` pattern) so the create goes out as a restore. Panes the inventory marks `live: true` carry no `sessionRef` after Task 4's strip, so they are recreated fresh and never armed (see D7). Terminal panes get the D4 treatment; non-terminal kinds (`browser`, `editor`, `fresh-agent`, `extension`, `picker`) are recreated by passing the snapshot pane payload through as content (`{kind, ...payload}`) with a minimal per-kind adapter (Task 4/A10: `editor` gains the required `content: ''` default per D6; `fresh-agent` drops `restoreError` so normalize keeps the sessionRef) — the same normalize/strip path handles them, exactly as it does for `reopenClosedTab`. The auto-created empty shell tab from `App.tsx:1423` is left in place (deliberate: removing it would touch tab-lifecycle code other lanes own; it is one empty shell tab).
 
@@ -109,7 +109,7 @@ Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.co
 
 **Interfaces:**
 - Consumes: `freshell_ws::pane_ledger::BindingRow` (fields serialize camelCase: `provider`, `sessionId`, `mode`, `cwd`, `state: bound|retired`, `retiredReason?: superseded|closed|gc_expired`, `supersededBy?: {provider, sessionId}`, `updatedAt`). Snapshot union doc shape (from `tabs_persist.rs`): `{deviceId, deviceLabel, capturedAt, records: [{tabKey, tabId, tabName, revision, updatedAt, paneCount, panes: [{paneId, kind, payload: {mode?, shell?, initialCwd?, sessionRef?: {provider, sessionId}, createRequestId?, ...}}]}]}`.
-- Produces: `pub struct DeviceUnion { pub device_id: String, pub union_doc: serde_json::Value }`, `pub fn select_foreign_recent_generation_ids(generations: &[serde_json::Value], exclude_client: &str) -> Vec<String>` (the A15 staleness filter, consumed by Task 2), and `pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow>, live_session_keys: HashSet<(String, String)>) -> serde_json::Value` — the third input is the set of `(provider, sessionId)` pairs owned by a currently-Running terminal (Task 2 feeds it from the terminal registry, read-only) — returning:
+- Produces: `pub struct DeviceUnion { pub device_id: String, pub union_doc: serde_json::Value }`, `pub fn select_foreign_recent_generation_ids(generations: &[serde_json::Value], exclude_client: &str, boot_cutoff_ms: u64) -> Vec<String>` (the A15 staleness + A16 concurrent-client filter, consumed by Task 2), and `pub fn build_inventory(device_unions: Vec<DeviceUnion>, bindings: Vec<BindingRow>, live_session_keys: HashSet<(String, String)>) -> serde_json::Value` — the third input is the set of `(provider, sessionId)` pairs owned by a currently-Running terminal (Task 2 feeds it from the terminal registry, read-only) — returning:
 
 ```json
 {
@@ -139,7 +139,7 @@ Rules encoded:
 - `ledgerOnly` = `state == bound` rows whose `(provider, sessionId)` matches no effective pane ref in ANY device union (not just the primary — a two-device steady state must not report the other device's sessions as orphaned) AND that is not in the live set (D7).
 - `contentId` = sha256 truncated to 16 hex chars (reuse the repo's digest convention — `digest_value`/`snapshot_content_id`, `tabs_persist.rs:70-87`) over the TIMESTAMP-FREE canonical substance: the sorted list of `(deviceId, tabKey, paneId, kind, effective provider:sessionId or "-")` for every pane in every included device union, plus sorted `provider:sessionId` for the `ledgerOnly` rows. `capturedAt`/`updatedAt` are EXCLUDED by design: the server heartbeat re-pushes stamp a new `capturedAt` every ≤5 min with any second connected client, and that churn must not defeat dismissal (D3).
 - `recoverable` = primary device exists OR `ledgerOnly` non-empty. Empty input ⇒ `{"recoverable": false, "contentId": "...", "device": null, "otherDevices": [], "ledgerOnly": []}`.
-- `select_foreign_recent_generation_ids` (A15 staleness rule, applied by Task 2 when composing each device's union): drop the requester's own generations, then drop every client whose newest generation `capturedAt` is more than 15 minutes older than that device's max `capturedAt` **computed over the remaining foreign clients** (the requester's just-pushed junk must never stale-out real recovery data). Rationale: every connected window force-pushes a heartbeat at least every 5 min (`tabRegistrySync.ts:21, 475-477`), so any client silent for >15 min is closed or rotated; this suppresses resurrection of closed tabs via the purely-additive union (closed tabs leave no durable trace — only open records are persisted). Post-filtering generations here leaves the `tabs_persist` write path untouched.
+- `select_foreign_recent_generation_ids` (A15 staleness + A16 concurrent-client rules, applied by Task 2 when composing each device's union): drop the requester's own generations; drop every client ALL of whose retained generations have `capturedAt >= boot_cutoff_ms` (A16, D2 — a client born after this browser session booted is a concurrently-opened fresh window, never lost data; a real lost client's generations all predate the fresh boot); then drop every client whose newest generation `capturedAt` is more than 15 minutes older than that device's max `capturedAt` **computed over the remaining clients** (junk must never stale-out real recovery data). Rationale: every connected window force-pushes a heartbeat at least every 5 min (`tabRegistrySync.ts:21, 475-477`), so any client silent for >15 min is closed or rotated; this suppresses resurrection of closed tabs via the purely-additive union (closed tabs leave no durable trace — only open records are persisted). Post-filtering generations here leaves the `tabs_persist` write path untouched.
 
 - [ ] **Step 1: Write the failing tests**
 
@@ -297,11 +297,29 @@ fn stale_clients_generations_are_dropped() {
         json!({"generationId": "gC", "clientInstanceId": "stale", "capturedAt": t_max - 16 * 60 * 1000}),
         json!({"generationId": "gD", "clientInstanceId": "me",    "capturedAt": t_max}),
     ];
-    let ids = select_foreign_recent_generation_ids(&gens, "me");
+    // boot cutoff AFTER every push: the A16 concurrent-client rule drops nothing here.
+    let ids = select_foreign_recent_generation_ids(&gens, "me", t_max + 1);
     assert!(ids.contains(&"gA".to_string()) && ids.contains(&"gB".to_string()));
     assert!(!ids.contains(&"gC".to_string()), "stale rotated client must not resurrect closed tabs");
     assert!(!ids.contains(&"gD".to_string()), "requester's own generations are excluded");
 }
+
+#[test]
+fn concurrent_fresh_windows_generations_are_dropped() {
+    // A16/D2: a client whose ENTIRE retained history postdates the requester's boot is a
+    // concurrently-opened fresh window (junk auto shell tab) - it must never demote the
+    // genuinely lost device by winning primary-device selection.
+    let boot: u64 = 100_000_000;
+    let gens = vec![
+        json!({"generationId": "gJ1", "clientInstanceId": "sibling-window", "capturedAt": boot + 2_000}),
+        json!({"generationId": "gJ2", "clientInstanceId": "sibling-window", "capturedAt": boot + 300_000}),
+        json!({"generationId": "gR",  "clientInstanceId": "lost",           "capturedAt": boot - 30_000}),
+    ];
+    let ids = select_foreign_recent_generation_ids(&gens, "me", boot);
+    assert!(ids.contains(&"gR".to_string()), "pre-boot client is real lost data - kept");
+    assert!(!ids.contains(&"gJ1".to_string()) && !ids.contains(&"gJ2".to_string()),
+        "post-boot-only client is a concurrent fresh window - dropped");
+}
 ```
 
 Write small local helpers `binding_row(provider, session_id, state_parts)`, `binding_row_at(provider, session_id, state_parts, updated_at)` (same, with a settable `updatedAt` — the timestamp-churn test needs it), `bound()`, `retired_closed()`, `retired_gc_expired()`, `retired_superseded_by(p, s)` that construct real `BindingRow` values (copy field names/enums from `crates/freshell-ws/src/pane_ledger.rs:93`; fill required timestamps with constants like `1000`).
@@ -334,24 +352,33 @@ pub struct DeviceUnion { pub device_id: String, pub union_doc: Value }
 
 const STALE_CLIENT_MS: u64 = 15 * 60 * 1000; // heartbeat cadence is 5 min (tabRegistrySync.ts:21, 475-477)
 
-/// A15 staleness rule: drop the requester's own generations, then drop clients whose
-/// newest generation is >15 min older than the device max over the REMAINING foreign
-/// clients (the requester's just-pushed junk must never stale-out real recovery data).
-pub fn select_foreign_recent_generation_ids(generations: &[Value], exclude_client: &str) -> Vec<String> {
+/// A15 staleness + A16 concurrent-client rules (D2): drop the requester's own generations;
+/// drop clients ALL of whose retained generations postdate boot_cutoff_ms (a client born
+/// after this browser session booted is a concurrently-opened fresh window, never lost
+/// data - a lost client's pushes all predate the fresh boot, so retention depth cannot
+/// misclassify it); then drop clients whose newest generation is >15 min older than the
+/// device max over the REMAINING clients (junk must never stale-out real recovery data).
+pub fn select_foreign_recent_generation_ids(generations: &[Value], exclude_client: &str, boot_cutoff_ms: u64) -> Vec<String> {
     let foreign: Vec<&Value> = generations.iter()
         .filter(|g| g["clientInstanceId"].as_str() != Some(exclude_client)).collect();
+    let mut oldest_by_client: HashMap<&str, u64> = HashMap::new();
     let mut newest_by_client: HashMap<&str, u64> = HashMap::new();
     for g in &foreign {
         let c = g["clientInstanceId"].as_str().unwrap_or("");
         let t = g["capturedAt"].as_u64().unwrap_or(0);
+        let o = oldest_by_client.entry(c).or_insert(u64::MAX);
+        if t < *o { *o = t; }
         let e = newest_by_client.entry(c).or_insert(0);
         if t > *e { *e = t; }
     }
-    let device_max = newest_by_client.values().copied().max().unwrap_or(0);
+    let pre_boot = |c: &str| oldest_by_client.get(c).copied().unwrap_or(u64::MAX) < boot_cutoff_ms;
+    let device_max = newest_by_client.iter()
+        .filter(|(c, _)| pre_boot(c))
+        .map(|(_, t)| *t).max().unwrap_or(0);
     foreign.iter()
         .filter(|g| {
             let c = g["clientInstanceId"].as_str().unwrap_or("");
-            newest_by_client.get(c).copied().unwrap_or(0) + STALE_CLIENT_MS >= device_max
+            pre_boot(c) && newest_by_client.get(c).copied().unwrap_or(0) + STALE_CLIENT_MS >= device_max
         })
         .filter_map(|g| g["generationId"].as_str().map(String::from))
         .collect()
@@ -511,9 +538,9 @@ git commit -m "feat(server): pure recovery-inventory builder joining snapshots w
 
 **Interfaces:**
 - Consumes: `freshell_ws::tabs_persist::{list_snapshot_devices, read_device_overview, read_generations_union_by_ids}` (sync `io::Result`, must run in `spawn_blocking`); `freshell_ws::pane_ledger::PaneLedger::list_bindings()` (sync, memory-only, callable directly); the shared terminal-registry handle (read-only — the same instance the WS server state receives; copy the exact type + binding name from `main.rs`) for the liveness join; `select_foreign_recent_generation_ids` and `build_inventory` from Task 1; the per-handler auth helper used by `tabs_snapshots.rs` handlers (`is_authed(&headers, &state.auth_token)` — copy the exact import from that file).
-- Produces: `pub struct RecoveryInventoryState { pub auth_token: String, pub snapshots_dir: Option<std::path::PathBuf>, pub ledger: std::sync::Arc<freshell_ws::pane_ledger::PaneLedger>, pub registry: /* shared terminal-registry handle, same type main.rs wires into the WS state */ }` (`#[derive(Clone)]`) and `pub fn router(state: RecoveryInventoryState) -> axum::Router`. Route: `GET /api/recovery/inventory?clientInstanceId=<id>`.
+- Produces: `pub struct RecoveryInventoryState { pub auth_token: String, pub snapshots_dir: Option<std::path::PathBuf>, pub ledger: std::sync::Arc<freshell_ws::pane_ledger::PaneLedger>, pub registry: /* shared terminal-registry handle, same type main.rs wires into the WS state */ }` (`#[derive(Clone)]`) and `pub fn router(state: RecoveryInventoryState) -> axum::Router`. Route: `GET /api/recovery/inventory?clientInstanceId=<id>&bootAgoMs=<elapsed-ms>` (`bootAgoMs` optional; missing/unparsable ⇒ `0`, i.e. `boot_cutoff = now` and the A16 concurrent-client filter drops nothing that predates the request).
 
-Handler behavior: 401 without valid token (same check as every other handler); with `snapshots_dir: None` or missing dir → inventory built from ledger only; snapshot reads: `spawn_blocking` over `(dir, exclude_client)` doing — `list_snapshot_devices(&dir)` → for each device `read_device_overview(&dir, &device)` → select generation ids via `select_foreign_recent_generation_ids(&generations, &exclude_client)` (Task 1 — drops the requester's own generations AND stale clients per the A15 recency rule) → `read_generations_union_by_ids(&dir, &device, &ids)` → collect `DeviceUnion`. Devices with zero surviving generations are skipped. IO errors and `JoinError` → 500 + `tracing::error!` (fail-loud, three-arm match, same shape as the dryRun path at `tabs_snapshots.rs:330`). Then build the live set from the registry (read-only): `live_session_keys(&state.registry)` collects `(provider = mode, sessionId)` for every currently-Running terminal row — the same row fields the ladder's A13 guard reads at `terminal.rs:1690-1745`; if the registry lacks a public row-listing accessor, add a read-only one to `freshell-terminal` (no behavior change). Finally `build_inventory(unions, state.ledger.list_bindings(), live)` → `Json(...)`.
+Handler behavior: 401 without valid token (same check as every other handler); with `snapshots_dir: None` or missing dir → inventory built from ledger only; parse `bootAgoMs` from the query (u64; missing/unparsable ⇒ 0) and compute `let boot_cutoff = now_ms().saturating_sub(boot_ago_ms);` (same `now_ms` helper convention as `tabs_persist.rs`); snapshot reads: `spawn_blocking` over `(dir, exclude_client, boot_cutoff)` doing — `list_snapshot_devices(&dir)` → for each device `read_device_overview(&dir, &device)` → select generation ids via `select_foreign_recent_generation_ids(&generations, &exclude_client, boot_cutoff)` (Task 1 — drops the requester's own generations, concurrent post-boot clients per the A16 rule, AND stale clients per the A15 recency rule) → `read_generations_union_by_ids(&dir, &device, &ids)` → collect `DeviceUnion`. Devices with zero surviving generations are skipped. IO errors and `JoinError` → 500 + `tracing::error!` (fail-loud, three-arm match, same shape as the dryRun path at `tabs_snapshots.rs:330`). Then build the live set from the registry (read-only): `live_session_keys(&state.registry)` collects `(provider = mode, sessionId)` for every currently-Running terminal row — the same row fields the ladder's A13 guard reads at `terminal.rs:1690-1745`; if the registry lacks a public row-listing accessor, add a read-only one to `freshell-terminal` (no behavior change). Finally `build_inventory(unions, state.ledger.list_bindings(), live)` → `Json(...)`.
 
 - [ ] **Step 1: Write the failing route tests**
 
@@ -674,14 +701,15 @@ fn live_session_keys(registry: &/* registry handle type */) -> std::collections:
     /* iterate rows; keep Running rows with a session identity; collect (mode, session_id) */
 }
 
-fn read_foreign_unions(dir: &std::path::Path, exclude_client: &str) -> std::io::Result<Vec<DeviceUnion>> {
+fn read_foreign_unions(dir: &std::path::Path, exclude_client: &str, boot_cutoff: u64) -> std::io::Result<Vec<DeviceUnion>> {
     use freshell_ws::tabs_persist::{list_snapshot_devices, read_device_overview, read_generations_union_by_ids};
     let mut out = vec![];
     if !dir.is_dir() { return Ok(out); }
     for device in list_snapshot_devices(dir)? {
         let Some((_, generations)) = read_device_overview(dir, &device)? else { continue };
-        // Task 1 helper: drops the requester's own generations AND stale clients (A15)
-        let foreign: Vec<String> = select_foreign_recent_generation_ids(&generations, exclude_client);
+        // Task 1 helper: drops the requester's own generations, concurrent post-boot
+        // clients (A16), AND stale clients (A15)
+        let foreign: Vec<String> = select_foreign_recent_generation_ids(&generations, exclude_client, boot_cutoff);
         if foreign.is_empty() { continue; }
         match read_generations_union_by_ids(dir, &device, &foreign) {
             Ok(union) => out.push(DeviceUnion { device_id: device, union_doc: union_value(union) }),
@@ -779,8 +807,8 @@ git commit -m "feat(ws): refuse sessionRef restore while a Running terminal owns
 **Interfaces:**
 - Consumes: `window.localStorage` (jsdom provides it in tests; clear it yourself — `console.error` throws in `afterEach`).
 - Produces:
-  - `boot-state.ts`: `export function computeHadPersistedLayout(storage: Pick<Storage, 'getItem'>): boolean` and `export const hadPersistedLayoutAtBoot: boolean` (evaluated at module import).
-  - `dismissal.ts`: `export function isDismissed(contentId: string): boolean`, `export function recordDismissal(contentId: string): void` (cap 20, newest kept), `export function getPendingOffer(): string | null`, `export function setPendingOffer(contentId: string): void`, `export function clearPendingOffer(): void`.
+  - `boot-state.ts`: `export function computeHadPersistedLayout(storage: Pick<Storage, 'getItem'>): boolean`, `export const hadPersistedLayoutAtBoot: boolean`, and `export const bootCapturedAtMs: number` (both constants evaluated at module import; `bootCapturedAtMs = Date.now()` — the anchor for D2's `bootAgoMs`).
+  - `dismissal.ts`: `export function isDismissed(contentId: string): boolean`, `export function recordDismissal(contentId: string): void` (cap 20, newest kept), `export interface PendingOffer { contentId: string; bootAt: number }`, `export function getPendingOffer(): PendingOffer | null`, `export function setPendingOffer(contentId: string, bootAt: number): void`, `export function clearPendingOffer(): void`.
 
 - [ ] **Step 1: Write the failing tests**
 
@@ -888,13 +916,18 @@ describe('recovery dismissal persistence', () => {
     expect(isDismissed('abc')).toBe(true)
   })
 
-  it('pending offer round-trips and clears', () => {
+  it('pending offer round-trips (with its bootAt anchor) and clears', () => {
     expect(getPendingOffer()).toBeNull()
-    setPendingOffer('abc')
-    expect(getPendingOffer()).toBe('abc')
+    setPendingOffer('abc', 12345)
+    expect(getPendingOffer()).toEqual({ contentId: 'abc', bootAt: 12345 })
     clearPendingOffer()
     expect(getPendingOffer()).toBeNull()
   })
+
+  it('tolerates corrupt pending JSON', () => {
+    localStorage.setItem('freshell.recovery.pending.v1', '{not json')
+    expect(getPendingOffer()).toBeNull()
+  })
 })
 ```
 
@@ -929,6 +962,11 @@ export function computeHadPersistedLayout(storage: Pick<Storage, 'getItem'>): bo
 // land long after module eval (see docs/plans/2026-07-26-recover-my-panes.md D1).
 export const hadPersistedLayoutAtBoot: boolean =
   typeof window !== 'undefined' && computeHadPersistedLayout(window.localStorage)
+
+// Paired with the capture above: the moment this boot's "had layout" signal was taken.
+// Anchor for the inventory request's bootAgoMs (D2's concurrent-client filter) - sent as
+// an elapsed DURATION so client/server clock skew cannot corrupt the server-side cutoff.
+export const bootCapturedAtMs: number = Date.now()
 ```
 
 In `src/main.tsx`, add a comment on the existing `import '@/store/storage-migration'` line (no code change):
@@ -966,12 +1004,24 @@ export function recordDismissal(contentId: string): void {
   localStorage.setItem(DISMISSED_KEY, JSON.stringify(next))
 }
 
-export function getPendingOffer(): string | null {
-  return localStorage.getItem(PENDING_KEY)
+export interface PendingOffer { contentId: string; bootAt: number }
+
+export function getPendingOffer(): PendingOffer | null {
+  try {
+    const raw = localStorage.getItem(PENDING_KEY)
+    if (!raw) return null
+    const parsed: unknown = JSON.parse(raw)
+    const p = parsed as { contentId?: unknown; bootAt?: unknown }
+    return typeof p?.contentId === 'string' && typeof p?.bootAt === 'number'
+      ? { contentId: p.contentId, bootAt: p.bootAt }
+      : null
+  } catch {
+    return null
+  }
 }
 
-export function setPendingOffer(contentId: string): void {
-  localStorage.setItem(PENDING_KEY, contentId)
+export function setPendingOffer(contentId: string, bootAt: number): void {
+  localStorage.setItem(PENDING_KEY, JSON.stringify({ contentId, bootAt }))
 }
 
 export function clearPendingOffer(): void {
@@ -1002,10 +1052,10 @@ git commit -m "feat(client): recovery trigger eligibility (boot-captured) and di
 - Create: `test/unit/client/lib/recovery/build-recovery-plan.test.ts`
 
 **Interfaces:**
-- Consumes: `PaneNode` / `TerminalPaneContent` from `@/store/paneTypes` (`PaneNode = leaf{id, content} | split{id, direction, children:[PaneNode,PaneNode], sizes:[number,number]}`, `paneTypes.ts:274-276`; terminal content fields incl. `initialCwd`, `sessionRef: {provider, sessionId}`, non-optional `createRequestId`/`status`); `nanoid`; `api.get` + `buildQueryString` (`api.ts:276-285`).
+- Consumes: `PaneNode` / `TerminalPaneContent` from `@/store/paneTypes` (`PaneNode = leaf{id, content} | split{id, direction, children:[PaneNode,PaneNode], sizes:[number,number]}`, `paneTypes.ts:274-276`; terminal content fields incl. `initialCwd`, `sessionRef: {provider, sessionId}`, non-optional `createRequestId`/`status`); `nanoid`; `api.get` + `buildQueryString(entries: Array<[string, string | number | undefined]>)` (`api.ts:273-285` — it takes an ARRAY OF `[key, value]` TUPLES, not an object; passing an object fails typecheck and would throw at runtime iterating a non-iterable).
 - Produces:
   - `types.ts`: `RecoveryInventory`, `RecoveryPane` (`{paneId, kind, mode: string|null, shell: string|null, cwd: string|null, payload: Record<string, unknown>, sessionRef: {provider, sessionId}|null, ledgerState: 'bound'|'closed'|'gc_expired'|'unknown', live: boolean}`), `RecoveryTab`, `LedgerOnlyEntry` — mirroring Task 1's response shape.
-  - `api.ts`: `export async function getRecoveryInventory(clientInstanceId: string): Promise<RecoveryInventory>` → `api.get<RecoveryInventory>('/api/recovery/inventory' + buildQueryString({ clientInstanceId }))`.
+  - `api.ts`: `export async function getRecoveryInventory(clientInstanceId: string, bootAgoMs: number): Promise<RecoveryInventory>` → `api.get<RecoveryInventory>('/api/recovery/inventory' + buildQueryString([['clientInstanceId', clientInstanceId], ['bootAgoMs', Math.max(0, Math.round(bootAgoMs))]]))` (tuple-entries call shape — see Consumes; `bootAgoMs` feeds D2's server-side concurrent-client cutoff).
   - `build-recovery-plan.ts`:
 
 ```ts
@@ -1199,8 +1249,10 @@ export function buildRecoveryPlan(inv: RecoveryInventory): RecoveryTabPlan[] {
 In `src/lib/api.ts`, next to `getBootstrap`:
 
 ```ts
-export async function getRecoveryInventory(clientInstanceId: string): Promise<RecoveryInventory> {
-  return api.get<RecoveryInventory>(`/api/recovery/inventory${buildQueryString({ clientInstanceId })}`)
+export async function getRecoveryInventory(clientInstanceId: string, bootAgoMs: number): Promise<RecoveryInventory> {
+  return api.get<RecoveryInventory>(
+    `/api/recovery/inventory${buildQueryString([['clientInstanceId', clientInstanceId], ['bootAgoMs', Math.max(0, Math.round(bootAgoMs))]])}`,
+  )
 }
 ```
 
@@ -1228,11 +1280,11 @@ git commit -m "feat(client): recovery inventory types, API helper, and recovery-
 - Create: `test/unit/client/components/RecoveryOfferPanel.test.tsx`
 
 **Interfaces:**
-- Consumes: `hadPersistedLayoutAtBoot`, dismissal module (Task 3), `getRecoveryInventory` (Task 4), `buildRecoveryPlan`/`countRecoverablePanes` (Task 4), `addTab` (`tabsSlice.ts:274-290` — payload accepts `id`; `activeTabId` set unconditionally), `restoreLayout` (`panesSlice.ts:910-926` — no-ops if the tab already has a layout), `addTerminalRestoreRequestId` (`src/lib/terminal-restore.ts`), `getClientInstanceId`.
+- Consumes: `hadPersistedLayoutAtBoot` + `bootCapturedAtMs`, dismissal module (Task 3), `getRecoveryInventory` (Task 4), `buildRecoveryPlan`/`countRecoverablePanes` (Task 4), `addTab` (`tabsSlice.ts:274-290` — payload accepts `id`; `activeTabId` set unconditionally), `restoreLayout` (`panesSlice.ts:910-926` — no-ops if the tab already has a layout), `addTerminalRestoreRequestId` (`src/lib/terminal-restore.ts`), `getClientInstanceId`.
 - Produces: `export function RecoveryOfferPanel(): JSX.Element | null` — fully self-gating (no props), rendered unconditionally from App. Also `export function armRecoveredTerminalRestores(state: RootState, tabIds: string[]): void` — walks each tab's post-normalization layout in `state.panes`, and for every terminal leaf whose content has a `sessionRef`, calls `addTerminalRestoreRequestId(content.createRequestId)`.
 
 Behavior:
-1. On mount: if `(hadPersistedLayoutAtBoot && !getPendingOffer())` → render null forever. Otherwise fetch `getRecoveryInventory(getClientInstanceId())` once; on error or `recoverable: false` or `isDismissed(contentId)` → render null; else `setPendingOffer(contentId)` and show the panel.
+1. On mount: `const pending = getPendingOffer()`; if `(hadPersistedLayoutAtBoot && !pending)` → render null forever. Otherwise `const bootAt = pending?.bootAt ?? bootCapturedAtMs` and fetch `getRecoveryInventory(getClientInstanceId(), Date.now() - bootAt)` once (D2: `bootAgoMs` anchors the server's concurrent-client cutoff to the ORIGINAL pre-junk boot, also across pending re-offers); on error or `recoverable: false` or `isDismissed(contentId)` → render null; else `setPendingOffer(contentId, bootAt)` and show the panel.
 2. Panel (modal-style, reuse the portal/overlay/focus pattern of `src/components/ui/confirm-modal.tsx`): heading `Restore N panes from server memory?` (N = `countRecoverablePanes`), the device label (`inventory.device.deviceLabel`, when a device is present), a list of recoverable items — for device panes: `{tabName}: {mode ?? kind}` plus cwd when present; for ledgerOnly: `{mode} session — {cwd ?? 'unknown directory'}`; buttons `Restore` and `Not now`. When any device pane has `live: true`, also render a note with `data-testid="recovery-live-note"` (copy flexible, e.g. `Some sessions are still running on the server — they were left untouched; their panes reopen without resuming.`) per D7.
 3. Accept: `clearPendingOffer()`; for each `RecoveryTabPlan`: `dispatch(addTab({ id: plan.tabId, title: plan.title }))`, `dispatch(restoreLayout({ tabId: plan.tabId, layout: plan.layout, paneTitles: plan.paneTitles }))`; then `armRecoveredTerminalRestores(store.getState(), planTabIds)`; hide panel. (Live panes carry no `sessionRef` after Task 4's strip, so the walk never arms them — no component-level special-casing needed.)
 4. Decline: `recordDismissal(contentId)`; `clearPendingOffer()`; hide panel. No further renders this or future visits for this contentId.
@@ -1255,6 +1307,7 @@ vi.mock('@/lib/api', async (importOriginal) => ({
 vi.mock('@/lib/recovery/boot-state', () => ({
   computeHadPersistedLayout: () => false,
   hadPersistedLayoutAtBoot: false, // simulate empty boot; per-test override via vi.mocked where needed
+  bootCapturedAtMs: 0,
 }))
 vi.mock('@/store/tabRegistrySync', async (importOriginal) => ({
   ...(await importOriginal<object>()),
@@ -1343,13 +1396,15 @@ export function RecoveryOfferPanel() {
   const [resolved, setResolved] = useState(false)
 
   useEffect(() => {
-    if (hadPersistedLayoutAtBoot && !getPendingOffer()) { setResolved(true); return }
+    const pending = getPendingOffer()
+    if (hadPersistedLayoutAtBoot && !pending) { setResolved(true); return }
+    const bootAt = pending?.bootAt ?? bootCapturedAtMs
     let cancelled = false
-    getRecoveryInventory(getClientInstanceId())
+    getRecoveryInventory(getClientInstanceId(), Date.now() - bootAt)
       .then((inv) => {
         if (cancelled) return
         if (!inv.recoverable || isDismissed(inv.contentId)) { setResolved(true); return }
-        setPendingOffer(inv.contentId)
+        setPendingOffer(inv.contentId, bootAt)
         setInventory(inv)
       })
       .catch(() => { if (!cancelled) setResolved(true) })
@@ -1466,7 +1521,7 @@ git add -A && git commit -m "test: stabilize recover-my-panes unit/integration c
 - Modify: the two registration lists that `pane-ledger-restart-rust.spec.ts` appears in — `RUST_ONLY_SPECS` and the `rust-chromium` project `testMatch` (grep for `pane-ledger-restart-rust` to find both; add this spec the same way)
 
 **Interfaces:**
-- Consumes: `RustServer` (`test/e2e-browser/helpers/rust-server.ts` — `homeDir` defaults to a fresh mkdtemp; `findFreePort()`; `restart()`), the fake-CLI installation + claude-pane creation pattern from `test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts:1-80` (`installFakeCli()` + fixtures `fake-claude-cli.mjs`), the `FAKE_CLAUDE_ARGV_LOG` JSONL and the `--session-id` extraction pattern (`pane-ledger-restart-rust.spec.ts:162-168`), the adjacent-pair `hasResumePair(argv, sessionId)` helper pattern from `snapshot-restore-rust.spec.ts:66-70` (COPY it into this spec now — Task 9 deletes that file), the fake CLI's resume marker `claude: resumed session <id>` (`fake-claude-cli.mjs:26-30`), fresh-context storage-wipe pattern from `tabs-client-retire.spec.ts:6-38` (`browser.newContext()` = empty localStorage), `?token=<t>&e2e=1` URL scheme, `data-testid="recovery-offer-panel"` / `recovery-accept` / `recovery-decline` / `recovery-live-note` from Task 5.
+- Consumes: `RustServer` (`test/e2e-browser/helpers/rust-server.ts` — `homeDir` defaults to a fresh mkdtemp; `findFreePort()`; `restart()`), the fake-CLI installation + claude-pane creation pattern from `test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts:1-80` (`installFakeCli()` + fixtures `fake-claude-cli.mjs`), the `FAKE_CLAUDE_ARGV_LOG` JSONL and the `--session-id` extraction pattern (`pane-ledger-restart-rust.spec.ts:162-168`), a claude-adapted adjacent-pair helper DEFINED IN THIS SPEC: `const hasClaudeResumePair = (argv: string[], sessionId: string) => { const i = argv.indexOf('--resume'); return i !== -1 && argv[i + 1] === sessionId }` — do NOT copy `hasResumePair` from `snapshot-restore-rust.spec.ts:66-70` verbatim: that helper matches codex's bare `resume` subcommand token (its only caller, `:273`, drives the codex CLI) and would NEVER match the fake claude CLI's `--resume <id>` flag (`fake-claude-cli.mjs:26-30`), which would make Scenario 1's accept-resume poll unpassable and Scenario 3's D7 negative assertion vacuous, the fake CLI's resume marker `claude: resumed session <id>` (`fake-claude-cli.mjs:26-30`), fresh-context storage-wipe pattern from `tabs-client-retire.spec.ts:6-38` (`browser.newContext()` = empty localStorage), `?token=<t>&e2e=1` URL scheme, `data-testid="recovery-offer-panel"` / `recovery-accept` / `recovery-decline` / `recovery-live-note` from Task 5.
 - Produces: the campaign's first browser-loss recovery e2e.
 
 Scenarios (all inside one spec file sharing one owned `RustServer` on an ephemeral port — NEVER 3001/3002; ESM imports use `.js` extensions):
@@ -1480,7 +1535,7 @@ Scenarios (all inside one spec file sharing one owned `RustServer` on an ephemer
 6. Context B: fresh `browser.newContext()` (empty storage = new machine) → `goto` the same URL.
 7. `await expect(pageB.getByTestId('recovery-offer-panel')).toBeVisible({ timeout: 15000 })` and assert the heading matches `/restore \d+ pane/i`.
 8. `await pageB.getByTestId('recovery-accept').click()` → panel disappears → assert a recreated terminal pane renders, then build the resume proof directly (`pane-ledger-restart-rust.spec.ts` has NO resume assertion to reuse — it only polls ledger files and checks `--session-id` preallocation):
-   - PRIMARY: poll the `FAKE_CLAUDE_ARGV_LOG` JSONL until an entry's argv contains the adjacent pair `--resume <sessionId>` for the sessionId recorded in step 2 (the `hasResumePair` pattern copied from `snapshot-restore-rust.spec.ts:66-70`).
+   - PRIMARY: poll the `FAKE_CLAUDE_ARGV_LOG` JSONL until an entry's argv contains the adjacent pair `--resume <sessionId>` for the sessionId recorded in step 2 (the `hasClaudeResumePair` helper from Interfaces — it searches for the `--resume` FLAG the fake claude CLI receives, not codex's bare `resume` token).
    - SECONDARY: the recreated pane's xterm text shows `claude: resumed session <id>` (`fake-claude-cli.mjs:26-30` emits it at CLI startup; scrollback replay delivers it to the late-attaching context).
    Also assert the browser pane from step 2 was recreated in context B (a browser-kind pane rendering `example.com` — assert via its testid/iframe src the way existing browser-pane specs do).
 9. Same-browser reload guard: `await pageB.reload()` → wait for app ready → `await expect(pageB.getByTestId('recovery-offer-panel')).toHaveCount(0)` (localStorage now has a layout — no offer).
@@ -1495,7 +1550,7 @@ Dismissal-across-reload persistence is proven at unit level (Task 3/5); e2e scen
 1. Fresh context D against the SAME still-running server (do NOT restart): create a new fake-claude pane (scenario 1's pattern), record its `sessionId` from the argv log (`--session-id` extraction) and the argv log's current entry count, and wait for a snapshot generation that includes it.
 2. `await contextD.close()` WITHOUT restarting the server — the claude PTY stays Running (registry-owned, not connection-owned).
 3. Fresh context E → the offer appears (the new session changed the recoverable substance, so scenario 2's dismissal does not suppress it) → assert the live-session note `recovery-live-note` is visible.
-4. `recovery-accept` click → panel disappears → a terminal pane is recreated → assert NO new `--resume <thatSessionId>` adjacent pair was appended to `FAKE_CLAUDE_ARGV_LOG` beyond the entry count recorded in step 1 (the live pane was recreated WITHOUT resume; the running session was left untouched — D7).
+4. `recovery-accept` click → panel disappears → a terminal pane is recreated → assert NO new `--resume <thatSessionId>` adjacent pair was appended to `FAKE_CLAUDE_ARGV_LOG` beyond the entry count recorded in step 1 — check with `hasClaudeResumePair` over the entries past that count (this negative assertion cannot pass vacuously: Scenario 1's PRIMARY poll already proves the same matcher matches a real `--resume` pair) (the live pane was recreated WITHOUT resume; the running session was left untouched — D7).
 
 - [ ] **Step 1: Write the failing spec**
 
@@ -1628,10 +1683,10 @@ The final report must ALSO state:
 
 ## Self-Review Record
 
-**1. Spec coverage:** (1) recover-my-panes flow — offer/trigger D1-D3 + Tasks 3/5/6 (boot-capture rationale corrected per A8, with the import-order invariants pinned and tested in Task 3); accept recreation honoring §4.2 D4-D5 + Tasks 1/4/5, including the A10 per-kind adapter (editor `content: ''` default, fresh-agent `restoreError` strip) with unit tests for editor/extension/picker; decline remembered Task 3/5, with the A5/A6 fix — `contentId` is sha256 over timestamp-free substance, so dismissal survives heartbeats, restarts, and Rust upgrades (tested: capturedAt/updatedAt bumps don't change it). (2) Liveness (A2/D7) — Task 1's third `live_session_keys` input + per-pane `live` flag, Task 2's read-only registry join, Task 2b's server-side guard on the direct sessionRef rung (failing integration test first), Task 4's sessionRef strip for live panes, Task 5's live note, Task 8 Scenario 3's no-restart proof (no new `--resume` pair). (3) Inventory correctness — `ledgerOnly` matched against effective refs across ALL device unions and excluding live rows (A4, tested), the A15 staleness rule dropping >15-min-silent clients (pure helper test + route test), self-pollution filter, auth'd. (4) kata h9vt — disposition section + Task 9 (Option A kept; Option B rejected with reason: ledger has no layout; the GET read API + `parse_selector` explicitly REUSED per A11; deploy-tab-diff remediation + spec reworked per A12; freshell-ws screenshot broker handled via the explicit A13 audit table since the compiler is silent for pub library items). TDD red-first for trigger conditions, inventory API, authority chain, liveness guard, dismissal — Tasks 1-5 + 2b all test-first; Task 8's e2e includes an explicit red-verification step. E2E — Task 8: three scenarios (restart accept-resume with argv-pair proof + browser-pane mixed-kind recreation, decline, no-restart live loss) with own RustServer/ephemeral ports/fresh contexts/same-browser-reload guard. Scope fence, a11y lint, PR policy — Global Constraints + Task 10 (which also carries the AD-1 §4.4 ratification statement and the B4 flag).
+**1. Spec coverage:** (1) recover-my-panes flow — offer/trigger D1-D3 + Tasks 3/5/6 (boot-capture rationale corrected per A8, with the import-order invariants pinned and tested in Task 3); accept recreation honoring §4.2 D4-D5 + Tasks 1/4/5, including the A10 per-kind adapter (editor `content: ''` default, fresh-agent `restoreError` strip) with unit tests for editor/extension/picker; decline remembered Task 3/5, with the A5/A6 fix — `contentId` is sha256 over timestamp-free substance, so dismissal survives heartbeats, restarts, and Rust upgrades (tested: capturedAt/updatedAt bumps don't change it). (2) Liveness (A2/D7) — Task 1's third `live_session_keys` input + per-pane `live` flag, Task 2's read-only registry join, Task 2b's server-side guard on the direct sessionRef rung (failing integration test first), Task 4's sessionRef strip for live panes, Task 5's live note, Task 8 Scenario 3's no-restart proof (no new `--resume` pair). (3) Inventory correctness — `ledgerOnly` matched against effective refs across ALL device unions and excluding live rows (A4, tested), the A15 staleness rule dropping >15-min-silent clients (pure helper test + route test), the self-pollution filter including the A16 concurrent-client rule (same-fresh-browser multi-window junk can never win primary-device selection; pure helper test), auth'd. (4) kata h9vt — disposition section + Task 9 (Option A kept; Option B rejected with reason: ledger has no layout; the GET read API + `parse_selector` explicitly REUSED per A11; deploy-tab-diff remediation + spec reworked per A12; freshell-ws screenshot broker handled via the explicit A13 audit table since the compiler is silent for pub library items). TDD red-first for trigger conditions, inventory API, authority chain, liveness guard, dismissal — Tasks 1-5 + 2b all test-first; Task 8's e2e includes an explicit red-verification step. E2E — Task 8: three scenarios (restart accept-resume with argv-pair proof + browser-pane mixed-kind recreation, decline, no-restart live loss) with own RustServer/ephemeral ports/fresh contexts/same-browser-reload guard. Scope fence, a11y lint, PR policy — Global Constraints + Task 10 (which also carries the AD-1 §4.4 ratification statement and the B4 flag).
 
 **1b. No silent deferrals:** no stubs or fake providers stand in for required behavior — the e2e uses the repo's established fake-CLI fixture (the same production-path proof used by the existing ledger restart e2e; it exercises the real create/resume path), and the Task 8 resume proof is built from the argv log + fixture marker (the previously-cited assertion did not exist — A14). Non-terminal pane recreation reuses the production `reopenClosedTab` restore path with a minimal per-kind adapter (D5/A10) — recreated, not deferred. Split geometry (D6) and editor buffer content (D6/A5) are not in the store — data facts, not deferrals. Two DOCUMENTED decisions with recorded rationale, not silent deferrals: (a) the freshopencode fresh-start limitation (Known-limitation note: fenced B4 crate owns the `opencode_ws.rs` bug; sessionRef passthrough kept forward-compatible; flagged to B4 in Task 10 Step 3); (b) live sessions are surfaced but NOT resumed (D7: attach-to-live rejected as unverified and colliding with Lane B1 ownership; server guard as defense-in-depth). No UNRESOLVED COVERAGE GAPS.
 
 **2. Placeholder scan:** the `row_*` accessors, `digest16`, and `select_foreign_recent_generation_ids` (Task 1), `union_value`, `live_session_keys`, and the registry-handle type (Task 2), and the guard's row-matching (Task 2b) are named adapters against real definitions the implementer opens — each is bound to a concrete file/line source (`pane_ledger.rs:93`, `tabs_persist.rs:70-87`, `terminal.rs:1690-1745`, main.rs wiring), with tests as the arbiter. Task 9's freshell-ws deletions are an explicit per-method audit table, not a "compiler will say" hope. No TBD/TODO/"handle edge cases" items remain.
 
-**3. Type consistency:** `DeviceUnion`/`select_foreign_recent_generation_ids`/`build_inventory` (Task 1, 3-arg signature) consumed verbatim in Task 2; the `live` field appears in Task 1's output schema, Task 4's `RecoveryPane` type and test fixtures, Task 5's `INVENTORY` fixture and live-note behavior, and Task 8 Scenario 3's assertions; `RecoveryInventory`/`RecoveryPane`/`RecoveryTabPlan` (Task 4) consumed in Task 5; `getClientInstanceId` exported in Task 5 and consumed there; testids `recovery-offer-panel`/`recovery-accept`/`recovery-decline`/`recovery-live-note` defined in Task 5, consumed in Task 8; `ledgerState` values (`bound|closed|gc_expired|unknown`) match between Task 1 output, Task 4 types, and tests; Task 2b's refusal frame mirrors the existing `RestoreUnavailable` shape consumed by the harness Task 2b's test copies.
+**3. Type consistency:** `DeviceUnion`/`select_foreign_recent_generation_ids`/`build_inventory` (Task 1, 3-arg signature) consumed verbatim in Task 2; the `live` field appears in Task 1's output schema, Task 4's `RecoveryPane` type and test fixtures, Task 5's `INVENTORY` fixture and live-note behavior, and Task 8 Scenario 3's assertions; `RecoveryInventory`/`RecoveryPane`/`RecoveryTabPlan` (Task 4) consumed in Task 5; `getClientInstanceId` exported in Task 5 and consumed there; testids `recovery-offer-panel`/`recovery-accept`/`recovery-decline`/`recovery-live-note` defined in Task 5, consumed in Task 8; `ledgerState` values (`bound|closed|gc_expired|unknown`) match between Task 1 output, Task 4 types, and tests; Task 2b's refusal frame mirrors the existing `RestoreUnavailable` shape consumed by the harness Task 2b's test copies; the D2 `bootAgoMs` chain is type-consistent end-to-end — `bootCapturedAtMs` (Task 3 boot-state) → `PendingOffer.bootAt` (Task 3 dismissal) → `getRecoveryInventory(clientInstanceId, bootAgoMs)` using the tuple-entries `buildQueryString` call shape that matches the REAL `api.ts:273` signature (Task 4) → `bootAgoMs` query param → `boot_cutoff` → `select_foreign_recent_generation_ids(_, _, boot_cutoff)` (Tasks 1/2, route param optional-default-0 so Task 2's existing route tests hold); Task 8's argv matcher `hasClaudeResumePair` targets the fake claude CLI's `--resume` flag, not codex's bare `resume` token, so the accept-resume poll can pass and the D7 negative assertion is non-vacuous.

From dda221d629895fc5f1c8b9aaf2a6929a242fa9b5 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:37:54 -0700
Subject: [PATCH 16/87] fix(ws): legacy resumeSessionId claims join the
 sessionRef-attach branch via the uniform promotion rule
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review finding on Task 4 (ee9374d6): the council-rule-6 attach branch in
verdict_for_pane fired only on a structured sessionRef claim, so a
legacy-claiming client (mode + resumeSessionId only) whose session was
carried by a live terminal under a DIFFERENT createRequestId fell through
to keyed resolution -> disk-Present -> respawn -- the D8 second-writer
shape rule 6 exists to close.

Fix: extract §5.2's ONE uniform promotion rule into promoted_legacy_claim
(reused by resolve_authoritative_ref step 4 -- no duplication) and compute
the branch's effective claim as sessionRef.or(promoted claim). Structured-
claim behavior and ordering unchanged; unsupported_kind arm untouched.

Test (RED first: derived Respawn, the literal D8 verdict):
reconcile::tests::legacy_resume_claim_attaches_to_live_terminal_across_create_request_ids

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-ws/src/reconcile.rs | 57 ++++++++++++++++++++++++++---
 1 file changed, 52 insertions(+), 5 deletions(-)

diff --git a/crates/freshell-ws/src/reconcile.rs b/crates/freshell-ws/src/reconcile.rs
index c12052d21..49a23a9b2 100644
--- a/crates/freshell-ws/src/reconcile.rs
+++ b/crates/freshell-ws/src/reconcile.rs
@@ -126,7 +126,13 @@ fn resolve_authoritative_ref(
     if let Some(sref) = pane.session_ref.clone() {
         return Some(sref);
     }
-    // 4. ONE uniform promotion rule: {provider: mode, sessionId: resumeSessionId}.
+    // 4. ONE uniform promotion rule.
+    promoted_legacy_claim(pane)
+}
+
+/// §5.2's ONE uniform promotion rule: a legacy `mode` + `resumeSessionId`
+/// pair IS a sessionRef claim — `{provider: mode, sessionId: resumeSessionId}`.
+fn promoted_legacy_claim(pane: &ReconcilePane) -> Option<SessionLocator> {
     let mode = pane
         .mode
         .as_deref()
@@ -203,14 +209,21 @@ fn verdict_for_pane(deps: &ReconcileDeps<'_>, pane: &ReconcilePane) -> PaneVerdi
     // live terminal ALREADY carrying the claimed sessionRef wins over
     // createRequestId keying — every other client's claim for the same ref
     // (regardless of createRequestId) attaches to the winner, never a
-    // respawn that would open a second JSONL writer (D8).
-    if let Some(claim) = pane.session_ref.as_ref() {
-        if let Some(tid) = live_terminal_for_claimed_ref(deps, claim) {
+    // respawn that would open a second JSONL writer (D8). The effective
+    // claim is the structured `sessionRef`, or the legacy `mode` +
+    // `resumeSessionId` pair promoted by §5.2's ONE uniform rule — a
+    // legacy-claiming client must not bypass this branch.
+    if let Some(claim) = pane
+        .session_ref
+        .clone()
+        .or_else(|| promoted_legacy_claim(pane))
+    {
+        if let Some(tid) = live_terminal_for_claimed_ref(deps, &claim) {
             let server_ref = deps
                 .identity
                 .session_ref_for(&tid)
                 .or_else(|| Some(claim.clone()));
-            let corrected = corrected_flag(pane.session_ref.as_ref(), server_ref.as_ref());
+            let corrected = corrected_flag(Some(&claim), server_ref.as_ref());
             return PaneVerdict {
                 terminal_id: Some(tid),
                 session_ref: server_ref,
@@ -762,6 +775,40 @@ mod tests {
         assert_eq!(v.corrected, None, "the claim matched server truth");
     }
 
+    /// Council rule 6, legacy-claim half: §5.2's ONE uniform promotion rule
+    /// applies BEFORE the sessionRef-attach lookup — a pane claiming only the
+    /// legacy `mode` + `resumeSessionId` pair (NO structured sessionRef)
+    /// whose session is carried by a live terminal under a DIFFERENT
+    /// createRequestId attaches to that terminal, never the D8 respawn that
+    /// would open a second JSONL writer.
+    #[test]
+    fn legacy_resume_claim_attaches_to_live_terminal_across_create_request_ids() {
+        let f = Fixture::new();
+        f.registry.register_headless(HeadlessTerminal {
+            terminal_id: "T-legacy-live".to_string(),
+            stream_id: "S-legacy-live".to_string(),
+            mode: "codex".to_string(),
+            resume_session_id: Some("s-legacy".to_string()),
+            create_request_id: Some("cr-WINNER".to_string()),
+            created_at: Some(1_000),
+        });
+        // Session Present on disk — the fall-through path would derive the
+        // D8 respawn.
+        f.probe.set("codex", "s-legacy", SessionExistence::Present);
+
+        let mut p = pane("cr-OTHER");
+        p.mode = Some("codex".to_string());
+        p.resume_session_id = Some("s-legacy".to_string()); // legacy claim only
+        let v = f.one(p);
+        assert_eq!(v.verdict, ReconcileVerdict::Attach);
+        assert_eq!(v.terminal_id.as_deref(), Some("T-legacy-live"));
+        assert_eq!(v.session_ref, Some(sref("codex", "s-legacy")));
+        assert_eq!(
+            v.corrected, None,
+            "a matching promoted claim is not a correction"
+        );
+    }
+
     /// §9.1 test 8 trust boundary, respawn shape: the claim contradicts the
     /// retired server identity → server ref + corrected: true.
     #[test]

From ee74b2e5eb1b2e9bad12d14771fc2584e1ba5b7a Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:38:53 -0700
Subject: [PATCH 17/87] docs(plan): register new test modules in Step 1 so TDD
 RED gates actually fail

Fresh-eyes iteration 2 blocking fix: Tasks 1 and 4 created their new .rs
files in Step 1 but deferred the 'pub mod' registration to Step 3, so the
Step 2 'Expected: COMPILE ERROR' gates would instead exit green with 0
tests (cargo never compiles an unregistered file). Move the module
registration (pub mod codex_locator / pub mod codex_association) into
Step 1 of each task, drop the duplicate registration from each Step 3,
and spell out both expected RED error families for Task 4 Step 2
(missing controller functions + missing WsState codex_locator field).
---
 .../plans/2026-07-26-codex-rollout-locator.md | 26 ++++++++++++++-----
 1 file changed, 20 insertions(+), 6 deletions(-)

diff --git a/docs/plans/2026-07-26-codex-rollout-locator.md b/docs/plans/2026-07-26-codex-rollout-locator.md
index c718f8893..10f9e4544 100644
--- a/docs/plans/2026-07-26-codex-rollout-locator.md
+++ b/docs/plans/2026-07-26-codex-rollout-locator.md
@@ -343,7 +343,12 @@ corpus; see "Validated Premises" above):
 Create `crates/freshell-sessions/src/codex_locator.rs` with ONLY the test
 module and a `#![allow(dead_code)]`-free skeleton that does not yet exist —
 i.e. write the tests first; the file will not compile until Step 3 adds the
-implementation above the tests. Test module:
+implementation above the tests. In this SAME step, register the module so
+cargo actually compiles it: add `pub mod codex_locator;` to
+`crates/freshell-sessions/src/lib.rs` (alphabetically among the existing
+`pub mod` lines). An unregistered `.rs` file is invisible to cargo — without
+this line, Step 2's test filter would exit green with 0 tests instead of the
+COMPILE ERROR the RED gate asserts. Test module:
 
 ```rust
 #[cfg(test)]
@@ -1021,8 +1026,9 @@ fn is_uuid_shaped(s: &str) -> bool {
 }
 ```
 
-Also add to `crates/freshell-sessions/src/lib.rs`: `pub mod codex_locator;`
-and in `crates/freshell-sessions/src/opencode_locator.rs` change
+(`pub mod codex_locator;` was already added to
+`crates/freshell-sessions/src/lib.rs` in Step 1.)
+Also in `crates/freshell-sessions/src/opencode_locator.rs` change
 `fn normalize_cwd(input: &str) -> String` to
 `pub(crate) fn normalize_cwd(input: &str) -> String`.
 
@@ -1572,7 +1578,12 @@ pub codex_locator: Option<Arc<freshell_sessions::codex_locator::CodexLocator>>,
 
 - [ ] **Step 1: Write the failing controller unit tests**
 
-Create `codex_association.rs` containing (initially) only the test module.
+Create `codex_association.rs` containing (initially) only the test module,
+and in this SAME step register it so cargo actually compiles it: add
+`pub mod codex_association;` to `crates/freshell-ws/src/lib.rs` (next to
+`opencode_association` at `:36`-ish, alphabetical). An unregistered `.rs`
+file is invisible to cargo — without this line, Step 2's test filter would
+exit green with 0 tests instead of the COMPILE ERROR the RED gate asserts.
 Mirror `opencode_association.rs`'s test harness EXACTLY: copy its
 `state_with_locator(...)` helper (`opencode_association.rs:227+` builds a full
 literal `WsState` with `pane_ledger: PaneLedger::disabled()`), adapting the
@@ -1624,7 +1635,10 @@ exact form — the harness copy is authoritative over this sketch.)
 - [ ] **Step 2: Run to verify RED**
 
 Run: `cargo test -p freshell-ws codex_association`
-Expected: COMPILE ERROR (module functions and `codex_locator` field missing).
+Expected: COMPILE ERROR — the module's functions (`is_submit_input`,
+`maybe_arm`, `note_possible_submit`, …) do not exist yet, and the test
+harness's `codex_locator:` field is not yet declared on `WsState`. Both
+error families are the RED for this task.
 
 - [ ] **Step 3: Implement the controller + wiring**
 
@@ -1753,7 +1767,7 @@ disagree, the transplant wins.
 Wiring edits:
 
 1. `crates/freshell-ws/src/lib.rs`:
-   - `pub mod codex_association;` (next to `opencode_association` at `:36`-ish, alphabetical)
+   - (`pub mod codex_association;` was already added in Step 1.)
    - Add the `codex_locator` field to `WsState` next to `opencode_locator`
      (~`:242`), doc comment mirroring opencode's shape but Enter-anchored
      ("correlates a fresh codex PTY's first Enter with the new rollout JSONL

From 691f20461af77c5853461e81724236306fd8d269 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:41:19 -0700
Subject: [PATCH 18/87] docs(plan): fix fresheyes iteration-2 blocking issues
 in B4 plan

- Task 2 Step 3: authoritative identity_sink.rs code block now includes the
  supersedes field on FreshAgentBindingUpsert, matching the Interfaces block,
  Task 2's own test, and all downstream constructions (Tasks 3/4/7/9/10)
- Task 11: paneReconcileFreshAgentV1 ready echo now names the required
  freshell-protocol ReadyCapabilities change (server_messages.rs:757-760,
  typed ready frame via build_handshake_with_capabilities - no raw-JSON path),
  adds it to the File Structure table, Task 11 Files list, and the Step 5
  git add so the scripted commit compiles
- Replace non-allowlisted model gpt-5.3-codex with allowlisted
  gpt-5.3-codex-spark throughout (normalize_freshcodex_model clamps unknown
  models to gpt-5.5, making Task 4's Rust assertion and Task 14 e2e test 1's
  resume assertion unpassable as written)
---
 .../2026-07-26-freshagent-verdicts-resume.md  | 32 +++++++++++--------
 1 file changed, 19 insertions(+), 13 deletions(-)

diff --git a/docs/plans/2026-07-26-freshagent-verdicts-resume.md b/docs/plans/2026-07-26-freshagent-verdicts-resume.md
index af4976906..f7d6115ff 100644
--- a/docs/plans/2026-07-26-freshagent-verdicts-resume.md
+++ b/docs/plans/2026-07-26-freshagent-verdicts-resume.md
@@ -44,6 +44,7 @@
 | `crates/freshell-server/src/main.rs` | Modify | construct + inject the sink into the three provider states + `FreshAgentState` (REST surface) |
 | `crates/freshell-ws/src/reconcile_freshagent.rs` | Create | snapshot types, async snapshot builder (supersession-chain resolution, respawn cap w/ reset-on-live), pure verdict mapping, dedupe |
 | `crates/freshell-ws/src/reconcile.rs` | Modify (minimal) | one `ReconcileDeps` field + one match arm + invert one unit test |
+| `crates/freshell-protocol/src/server_messages.rs` | Modify (minimal) | `ReadyCapabilities` gains an optional `pane_reconcile_fresh_agent_v1` field (the `paneReconcileFreshAgentV1` ready echo — the ready frame is typed; there is no raw-JSON path) |
 | `crates/freshell-ws/src/lib.rs` | Modify | `mod reconcile_freshagent;`, `paneReconcileFreshAgentV1` capability parse/echo, `WsState.fresh_agent_respawn_counts` |
 | `crates/freshell-ws/src/terminal.rs` | Modify | thread capability bool; build fresh-agent snapshot in `handle_pane_reconcile` |
 | `crates/freshell-ws/tests/pane_reconcile_freshagent.rs` | Create | direct-WS integration tests for the fresh-agent arm |
@@ -84,7 +85,7 @@ fn fresh_agent_binding_roundtrips_settings_and_pane_kind() {
             mode: "freshcodex",
             cwd: Some("/home/u/proj"),
             create_request_id: Some("req-1"),
-            model: Some("gpt-5.3-codex"),
+            model: Some("gpt-5.3-codex-spark"),
             sandbox: Some("workspace-write"),
             permission_mode: Some("on-request"),
             effort: Some("high"),
@@ -94,7 +95,7 @@ fn fresh_agent_binding_roundtrips_settings_and_pane_kind() {
         .unwrap();
     let row = ledger.load_binding("codex", "thread-1").expect("row");
     assert_eq!(row.pane_kind.as_deref(), Some("fresh-agent"));
-    assert_eq!(row.model.as_deref(), Some("gpt-5.3-codex"));
+    assert_eq!(row.model.as_deref(), Some("gpt-5.3-codex-spark"));
     assert_eq!(row.sandbox.as_deref(), Some("workspace-write"));
     assert_eq!(row.permission_mode.as_deref(), Some("on-request"));
     assert_eq!(row.effort.as_deref(), Some("high"));
@@ -411,6 +412,9 @@ pub struct FreshAgentBindingUpsert {
     pub mode: String,
     pub create_request_id: Option<String>,
     pub resolves_pending: Option<String>,
+    /// G3 supersession (V8/A14): OLD session id this binding replaces
+    /// (codex crash-respawn passes the old thread id; everyone else None).
+    pub supersedes: Option<String>,
     pub settings: FreshAgentSettings,
 }
 
@@ -573,7 +577,7 @@ mod tests {
             resolves_pending: None,
             supersedes: None,
             settings: FreshAgentSettings {
-                model: Some("gpt-5.3-codex".into()),
+                model: Some("gpt-5.3-codex-spark".into()),
                 sandbox: Some("workspace-write".into()),
                 permission_mode: Some("on-request".into()),
                 effort: None,
@@ -584,7 +588,7 @@ mod tests {
         .expect("awaited write succeeds");
         // Awaited write => durable and readable IMMEDIATELY, no polling.
         let s = sink.load_settings("codex", "t1").expect("binding visible after await");
-        assert_eq!(s.model.as_deref(), Some("gpt-5.3-codex"));
+        assert_eq!(s.model.as_deref(), Some("gpt-5.3-codex-spark"));
         assert_eq!(s.sandbox.as_deref(), Some("workspace-write"));
         assert!(sink.was_recorded("codex", "t1"));
         assert!(!sink.was_recorded("codex", "nope"));
@@ -775,7 +779,7 @@ async fn create_records_fresh_agent_binding_with_settings() {
     // settings — reuse create_real_fake_session, passing model/sandbox if it
     // accepts them, otherwise inline the same freshAgent.create the existing
     // create tests send, with:
-    //   model: "gpt-5.3-codex", sandbox: "workspace-write",
+    //   model: "gpt-5.3-codex-spark", sandbox: "workspace-write",
     //   permissionMode: "on-request", effort: "high", cwd: <tmp dir>
     let thread_id = create_real_fake_session(&state /* …with settings… */).await;
 
@@ -783,7 +787,7 @@ async fn create_records_fresh_agent_binding_with_settings() {
     let b = bindings.iter().find(|b| b.session_id == thread_id).expect("binding row written at thread/start");
     assert_eq!(b.provider, "codex");
     assert_eq!(b.mode, "freshcodex");
-    assert_eq!(b.settings.model.as_deref(), Some("gpt-5.3-codex"));
+    assert_eq!(b.settings.model.as_deref(), Some("gpt-5.3-codex-spark"));
     assert_eq!(b.settings.sandbox.as_deref(), Some("workspace-write"));
     assert_eq!(b.settings.permission_mode.as_deref(), Some("on-request"));
     assert_eq!(b.settings.effort.as_deref(), Some("high"));
@@ -913,7 +917,7 @@ async fn resume_after_restart_reapplies_settings_from_ledger() {
     let (state, _bus) = state_with_bus();
     let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
     fake.seed("codex", "thread-9", crate::identity_sink::FreshAgentSettings {
-        model: Some("gpt-5.3-codex".into()),
+        model: Some("gpt-5.3-codex-spark".into()),
         sandbox: Some("workspace-write".into()),
         permission_mode: Some("on-request".into()),
         effort: Some("high".into()),
@@ -929,7 +933,7 @@ async fn resume_after_restart_reapplies_settings_from_ledger() {
     // (1) The registered session carries the recovered settings:
     let sessions = state.sessions.lock().await;
     let s = sessions.get("thread-9").expect("session registered");
-    assert_eq!(s.model, "gpt-5.3-codex");
+    assert_eq!(s.model, "gpt-5.3-codex-spark");
     assert_eq!(s.sandbox.as_deref(), Some("workspace-write"));
     assert_eq!(s.permission_mode.as_deref(), Some("on-request"));
     assert_eq!(s.effort.as_deref(), Some("high"));
@@ -939,7 +943,7 @@ async fn resume_after_restart_reapplies_settings_from_ledger() {
     let log = std::fs::read_to_string(op_log.path()).unwrap();
     let resume_line = log.lines().find(|l| l.contains("\"thread/resume\"")).expect("thread/resume logged");
     let entry: serde_json::Value = serde_json::from_str(resume_line).unwrap();
-    assert_eq!(entry["params"]["model"], "gpt-5.3-codex");
+    assert_eq!(entry["params"]["model"], "gpt-5.3-codex-spark");
     assert_eq!(entry["params"]["sandbox"], "workspace-write");
 }
 
@@ -1581,6 +1585,7 @@ git commit -m "fix(claude): resume-in-place reapplies model/permissionMode/effor
 **Files:**
 - Modify: `crates/freshell-ws/src/lib.rs` (parse at the hello handler — sibling pattern `terminalOutputBatchV1` at `lib.rs:592-597`; `paneReconcileV1` at `:574-578`; ready echo where `paneReconcileV1` is echoed)
 - Modify: `crates/freshell-ws/src/terminal.rs` (`terminal::run` signature + `handle_pane_reconcile` param)
+- Modify: `crates/freshell-protocol/src/server_messages.rs` (`ReadyCapabilities` struct at `:757-760` — the ready echo requires a new typed field; see Step 3)
 - Test: `crates/freshell-ws/tests/pane_reconcile_freshagent.rs` (new file — first two tests)
 
 **Interfaces:**
@@ -1637,7 +1642,7 @@ let pane_reconcile_fresh_agent_v1 = value
     .unwrap_or(false);
 ```
 
-Echo `paneReconcileFreshAgentV1: true` in `ready.capabilities` when negotiated (same conditional style as `paneReconcileV1` — omitted entirely when false). Thread the bool through `terminal::run` into `handle_pane_reconcile` (parameter only in this task; used in Task 13).
+Echo `paneReconcileFreshAgentV1: true` in `ready.capabilities` when negotiated (same conditional style as `paneReconcileV1` — omitted entirely when false). NOTE the echo side is TYPED, not raw JSON: the ready frame is built via `build_handshake_with_capabilities` (`crates/freshell-ws/src/lib.rs:370-381`) from the `ReadyCapabilities` struct (`crates/freshell-protocol/src/server_messages.rs:757-760`, currently containing only `pane_reconcile_v1`). Add a sibling field `pane_reconcile_fresh_agent_v1` to `ReadyCapabilities`, mirroring `pane_reconcile_v1`'s type and serde attributes exactly (same rename-to-`paneReconcileFreshAgentV1` / omit-when-absent behavior), and populate it at the `build_handshake_with_capabilities` call site only when negotiated. Thread the bool through `terminal::run` into `handle_pane_reconcile` (parameter only in this task; used in Task 13).
 
 - [ ] **Step 4: Run tests to verify they pass**
 
@@ -1649,8 +1654,9 @@ Expected: PASS.
 ```bash
 cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
 git add crates/freshell-ws/src/lib.rs crates/freshell-ws/src/terminal.rs \
+        crates/freshell-protocol/src/server_messages.rs \
         crates/freshell-ws/tests/pane_reconcile_freshagent.rs
-git commit -m "feat(ws): paneReconcileFreshAgentV1 capability - parsed, threaded, echoed; frozen client unaffected"
+git commit -m "feat(ws): paneReconcileFreshAgentV1 capability - parsed, threaded, echoed via typed ReadyCapabilities; frozen client unaffected"
 ```
 
 ---
@@ -2294,14 +2300,14 @@ if (
 
 1. **`codex: create-shaped resume after restart carries the recorded model`** — exercises the CREATE-resume path (R1 + ledger-fill), the exact wire shape the frozen client sends after `page.reload()` (V2/A4). No browser page.
    - Boot with `CODEX_CMD` fake + static behavior including `appendThreadOperationLogPath: <tmp>/codex-ops.jsonl` (resume succeeds by default).
-   - PATCH `settings.freshAgent.enabled=true`; open a raw WS; `freshAgent.create` with `{ provider: 'codex', sessionType: 'freshcodex', model: 'gpt-5.3-codex', sandbox: 'workspace-write', cwd: <tmp> }`; await `freshAgent.created` (capture the durable thread id); one `freshAgent.send`; await the turn.
+   - PATCH `settings.freshAgent.enabled=true`; open a raw WS; `freshAgent.create` with `{ provider: 'codex', sessionType: 'freshcodex', model: 'gpt-5.3-codex-spark', sandbox: 'workspace-write', cwd: <tmp> }`; await `freshAgent.created` (capture the durable thread id); one `freshAgent.send`; await the turn.
    - `await server.restartAbrupt()`; open a NEW raw WS; send `freshAgent.create` with `{ provider: 'codex', sessionType: 'freshcodex', resumeSessionId: <thread id> }` and NO model/sandbox — proving the values come from the LEDGER (R1 fills gaps, Task 5(d)), not from the message; await the created/attach-equivalent reply.
    - Assertion block:
    ```ts
    const ops = fs.readFileSync(opLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
    const resume = ops.find((o) => o.method === 'thread/resume')
    expect(resume, 'restart must resume the durable thread').toBeTruthy()
-   expect(resume.params.model, 'resume must carry the recorded model, not null').toBe('gpt-5.3-codex')
+   expect(resume.params.model, 'resume must carry the recorded model, not null').toBe('gpt-5.3-codex-spark')
    expect(resume.params.sandbox, 'resume must carry the recorded sandbox').toBe('workspace-write')
    ```
 

From 99e734eec046a7b36c650c696d252bd2fd9f8061 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:47:35 -0700
Subject: [PATCH 19/87] docs: fix fresheyes iteration-3 blockers in
 recover-my-panes plan

Two blocking defects from independent plan review:

1. Task 2 Step 3 reference snippet omitted the load-bearing D2/A16
   bootAgoMs plumbing: InventoryQuery now carries boot_ago_ms:
   Option<u64>, the handler computes boot_cutoff =
   now_ms().saturating_sub(bootAgoMs), and read_foreign_unions is
   called with its real 3-arg signature. Added a dedicated route test
   (route_bootagoms_drops_concurrent_post_boot_clients, real
   wall-clock fixtures) that forces the wiring to exist: a post-boot
   concurrent client is dropped with bootAgoMs=30000 and kept without
   the param. Prose tightened: missing => 0; non-numeric => 400 from
   the Query extractor. Self-Review Record sections 1 and 3 updated to
   match.

2. Task 8 Scenario 3 step 1 attempted UI pane creation underneath the
   plan's own modal recovery offer (fresh context D against a server
   with recoverable state). Step 1 now waits for
   recovery-offer-panel and declines it before any pane interaction,
   noting the dismissal is scoped to context D's localStorage and does
   not affect context E.
---
 docs/plans/2026-07-26-recover-my-panes.md | 52 ++++++++++++++++++++---
 1 file changed, 45 insertions(+), 7 deletions(-)

diff --git a/docs/plans/2026-07-26-recover-my-panes.md b/docs/plans/2026-07-26-recover-my-panes.md
index c7038c9fa..bb8026d84 100644
--- a/docs/plans/2026-07-26-recover-my-panes.md
+++ b/docs/plans/2026-07-26-recover-my-panes.md
@@ -538,9 +538,9 @@ git commit -m "feat(server): pure recovery-inventory builder joining snapshots w
 
 **Interfaces:**
 - Consumes: `freshell_ws::tabs_persist::{list_snapshot_devices, read_device_overview, read_generations_union_by_ids}` (sync `io::Result`, must run in `spawn_blocking`); `freshell_ws::pane_ledger::PaneLedger::list_bindings()` (sync, memory-only, callable directly); the shared terminal-registry handle (read-only — the same instance the WS server state receives; copy the exact type + binding name from `main.rs`) for the liveness join; `select_foreign_recent_generation_ids` and `build_inventory` from Task 1; the per-handler auth helper used by `tabs_snapshots.rs` handlers (`is_authed(&headers, &state.auth_token)` — copy the exact import from that file).
-- Produces: `pub struct RecoveryInventoryState { pub auth_token: String, pub snapshots_dir: Option<std::path::PathBuf>, pub ledger: std::sync::Arc<freshell_ws::pane_ledger::PaneLedger>, pub registry: /* shared terminal-registry handle, same type main.rs wires into the WS state */ }` (`#[derive(Clone)]`) and `pub fn router(state: RecoveryInventoryState) -> axum::Router`. Route: `GET /api/recovery/inventory?clientInstanceId=<id>&bootAgoMs=<elapsed-ms>` (`bootAgoMs` optional; missing/unparsable ⇒ `0`, i.e. `boot_cutoff = now` and the A16 concurrent-client filter drops nothing that predates the request).
+- Produces: `pub struct RecoveryInventoryState { pub auth_token: String, pub snapshots_dir: Option<std::path::PathBuf>, pub ledger: std::sync::Arc<freshell_ws::pane_ledger::PaneLedger>, pub registry: /* shared terminal-registry handle, same type main.rs wires into the WS state */ }` (`#[derive(Clone)]`) and `pub fn router(state: RecoveryInventoryState) -> axum::Router`. Route: `GET /api/recovery/inventory?clientInstanceId=<id>&bootAgoMs=<elapsed-ms>` (`bootAgoMs` optional; missing ⇒ `0`, i.e. `boot_cutoff = now` and the A16 concurrent-client filter drops nothing that predates the request; a non-numeric value is rejected by the `Query` extractor with 400 — the client always sends `Math.max(0, Math.round(...))`).
 
-Handler behavior: 401 without valid token (same check as every other handler); with `snapshots_dir: None` or missing dir → inventory built from ledger only; parse `bootAgoMs` from the query (u64; missing/unparsable ⇒ 0) and compute `let boot_cutoff = now_ms().saturating_sub(boot_ago_ms);` (same `now_ms` helper convention as `tabs_persist.rs`); snapshot reads: `spawn_blocking` over `(dir, exclude_client, boot_cutoff)` doing — `list_snapshot_devices(&dir)` → for each device `read_device_overview(&dir, &device)` → select generation ids via `select_foreign_recent_generation_ids(&generations, &exclude_client, boot_cutoff)` (Task 1 — drops the requester's own generations, concurrent post-boot clients per the A16 rule, AND stale clients per the A15 recency rule) → `read_generations_union_by_ids(&dir, &device, &ids)` → collect `DeviceUnion`. Devices with zero surviving generations are skipped. IO errors and `JoinError` → 500 + `tracing::error!` (fail-loud, three-arm match, same shape as the dryRun path at `tabs_snapshots.rs:330`). Then build the live set from the registry (read-only): `live_session_keys(&state.registry)` collects `(provider = mode, sessionId)` for every currently-Running terminal row — the same row fields the ladder's A13 guard reads at `terminal.rs:1690-1745`; if the registry lacks a public row-listing accessor, add a read-only one to `freshell-terminal` (no behavior change). Finally `build_inventory(unions, state.ledger.list_bindings(), live)` → `Json(...)`.
+Handler behavior: 401 without valid token (same check as every other handler); with `snapshots_dir: None` or missing dir → inventory built from ledger only; parse `bootAgoMs` from the query (`Option<u64>` on `InventoryQuery`; missing ⇒ 0) and compute `let boot_cutoff = now_ms().saturating_sub(boot_ago_ms);` (same `now_ms` helper convention as `tabs_persist.rs`); snapshot reads: `spawn_blocking` over `(dir, exclude_client, boot_cutoff)` doing — `list_snapshot_devices(&dir)` → for each device `read_device_overview(&dir, &device)` → select generation ids via `select_foreign_recent_generation_ids(&generations, &exclude_client, boot_cutoff)` (Task 1 — drops the requester's own generations, concurrent post-boot clients per the A16 rule, AND stale clients per the A15 recency rule) → `read_generations_union_by_ids(&dir, &device, &ids)` → collect `DeviceUnion`. Devices with zero surviving generations are skipped. IO errors and `JoinError` → 500 + `tracing::error!` (fail-loud, three-arm match, same shape as the dryRun path at `tabs_snapshots.rs:330`). Then build the live set from the registry (read-only): `live_session_keys(&state.registry)` collects `(provider = mode, sessionId)` for every currently-Running terminal row — the same row fields the ladder's A13 guard reads at `terminal.rs:1690-1745`; if the registry lacks a public row-listing accessor, add a read-only one to `freshell-terminal` (no behavior change). Finally `build_inventory(unions, state.ledger.list_bindings(), live)` → `Json(...)`.
 
 - [ ] **Step 1: Write the failing route tests**
 
@@ -642,6 +642,40 @@ async fn route_drops_stale_rotated_clients() {
     assert!(tabs.iter().all(|t| t["tabKey"] != "zombie"), "stale client's tab must be dropped");
     assert!(tabs.iter().any(|t| t["tabKey"] == "k1"));
 }
+
+#[tokio::test]
+async fn route_bootagoms_drops_concurrent_post_boot_clients() {
+    // A16/D2 at the ROUTE level: this test forces the bootAgoMs -> boot_cutoff ->
+    // read_foreign_unions(_, _, boot_cutoff) wiring to actually exist. It uses REAL
+    // wall-clock capturedAt values because boot_cutoff is computed from now_ms().
+    let tmp = tempfile::tempdir().unwrap();
+    let now = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH).unwrap().as_millis() as u64;
+    // The genuinely lost client: its only push predates the requester's boot by 60s.
+    write_snapshot(tmp.path(), "dev1", "lost", now - 60_000, 1, json!([
+        {"tabKey":"k1","tabId":"t1","tabName":"work","status":"open","revision":1,"updatedAt":now - 60_000,
+         "paneCount":1,"panes":[{"paneId":"p1","kind":"terminal","payload":{"mode":"shell"}}]}
+    ]));
+    // A concurrently-born fresh window: ALL of its generations postdate the boot.
+    write_snapshot(tmp.path(), "dev1", "concurrent", now, 1, json!([
+        {"tabKey":"junk","tabId":"tj","tabName":"junk","status":"open","revision":1,"updatedAt":now,
+         "paneCount":1,"panes":[{"paneId":"pj","kind":"terminal","payload":{"mode":"shell"}}]}
+    ]));
+    let router = router(test_state(Some(tmp.path().to_path_buf()), None));
+    // Requester booted 30s ago => boot_cutoff = now - 30s: "concurrent" (born now) is
+    // post-boot junk and must be dropped; "lost" (60s ago) predates boot and survives.
+    let (_, body) = get(router.clone(),
+        "/api/recovery/inventory?clientInstanceId=me&bootAgoMs=30000", Some("tok")).await;
+    let tabs = body["device"]["tabs"].as_array().unwrap();
+    assert!(tabs.iter().all(|t| t["tabKey"] != "junk"), "post-boot concurrent client must be dropped (A16)");
+    assert!(tabs.iter().any(|t| t["tabKey"] == "k1"), "pre-boot lost client must survive");
+    // Without bootAgoMs (default 0 => boot_cutoff = now at handler time) BOTH clients
+    // predate the cutoff and BOTH tabs appear - pins the optional-default-0 contract.
+    let (_, body) = get(router, "/api/recovery/inventory?clientInstanceId=me", Some("tok")).await;
+    let tabs = body["device"]["tabs"].as_array().unwrap();
+    assert!(tabs.iter().any(|t| t["tabKey"] == "junk"), "default cutoff must drop nothing pre-request");
+    assert!(tabs.iter().any(|t| t["tabKey"] == "k1"));
+}
 ```
 
 (If the on-disk binding filename/JSON differs, copy the exact shape from `pane_ledger_tests.rs` fixtures — the test contract stands: a pre-seeded bound row surfaces in `ledgerOnly`.)
@@ -668,7 +702,7 @@ pub struct RecoveryInventoryState {
 
 #[derive(serde::Deserialize)]
 #[serde(rename_all = "camelCase")]
-struct InventoryQuery { client_instance_id: Option<String> }
+struct InventoryQuery { client_instance_id: Option<String>, boot_ago_ms: Option<u64> }
 
 pub fn router(state: RecoveryInventoryState) -> Router {
     Router::new().route("/api/recovery/inventory", get(inventory_handler)).with_state(state)
@@ -677,10 +711,14 @@ pub fn router(state: RecoveryInventoryState) -> Router {
 async fn inventory_handler(State(state): State<RecoveryInventoryState>, headers: HeaderMap, Query(q): Query<InventoryQuery>) -> Response {
     if !is_authed(&headers, &state.auth_token) { return unauthorized(); } // same helper as tabs_snapshots.rs
     let exclude = q.client_instance_id.unwrap_or_default();
+    // D2/A16: anchor the concurrent-client filter to the requester's boot. Missing param
+    // => 0 => boot_cutoff = now, so nothing that predates the request is dropped.
+    // now_ms(): same epoch-millis helper convention tabs_persist.rs uses - import or replicate.
+    let boot_cutoff = now_ms().saturating_sub(q.boot_ago_ms.unwrap_or(0));
     let unions = match state.snapshots_dir.clone() {
         None => vec![],
         Some(dir) => {
-            let job = tokio::task::spawn_blocking(move || read_foreign_unions(&dir, &exclude));
+            let job = tokio::task::spawn_blocking(move || read_foreign_unions(&dir, &exclude, boot_cutoff));
             match job.await {
                 Ok(Ok(u)) => u,
                 Ok(Err(e)) => { tracing::error!(error = %e, "recovery inventory snapshot read failed"); return internal_error(); }
@@ -1547,7 +1585,7 @@ Scenarios (all inside one spec file sharing one owned `RustServer` on an ephemer
 Dismissal-across-reload persistence is proven at unit level (Task 3/5); e2e scenario 2 proves the user-visible decline behavior.
 
 **Scenario 3 — no-restart browser loss (live session ⇒ recreate WITHOUT resume, D7):**
-1. Fresh context D against the SAME still-running server (do NOT restart): create a new fake-claude pane (scenario 1's pattern), record its `sessionId` from the argv log (`--session-id` extraction) and the argv log's current entry count, and wait for a snapshot generation that includes it.
+1. Fresh context D against the SAME still-running server (do NOT restart). Context D's localStorage is empty and the server still holds recoverable state from scenarios 1-2, so the recovery offer MODAL (Task 5: `role="dialog"`, overlay) appears first and would intercept all pointer events — clear it BEFORE any pane interaction: `await expect(pageD.getByTestId('recovery-offer-panel')).toBeVisible(...)` → `recovery-decline` click → panel gone (this dismissal lives only in D's localStorage; context E in step 3 is a different fresh context and is unaffected). THEN create a new fake-claude pane (scenario 1's pattern), record its `sessionId` from the argv log (`--session-id` extraction) and the argv log's current entry count, and wait for a snapshot generation that includes it.
 2. `await contextD.close()` WITHOUT restarting the server — the claude PTY stays Running (registry-owned, not connection-owned).
 3. Fresh context E → the offer appears (the new session changed the recoverable substance, so scenario 2's dismissal does not suppress it) → assert the live-session note `recovery-live-note` is visible.
 4. `recovery-accept` click → panel disappears → a terminal pane is recreated → assert NO new `--resume <thatSessionId>` adjacent pair was appended to `FAKE_CLAUDE_ARGV_LOG` beyond the entry count recorded in step 1 — check with `hasClaudeResumePair` over the entries past that count (this negative assertion cannot pass vacuously: Scenario 1's PRIMARY poll already proves the same matcher matches a real `--resume` pair) (the live pane was recreated WITHOUT resume; the running session was left untouched — D7).
@@ -1683,10 +1721,10 @@ The final report must ALSO state:
 
 ## Self-Review Record
 
-**1. Spec coverage:** (1) recover-my-panes flow — offer/trigger D1-D3 + Tasks 3/5/6 (boot-capture rationale corrected per A8, with the import-order invariants pinned and tested in Task 3); accept recreation honoring §4.2 D4-D5 + Tasks 1/4/5, including the A10 per-kind adapter (editor `content: ''` default, fresh-agent `restoreError` strip) with unit tests for editor/extension/picker; decline remembered Task 3/5, with the A5/A6 fix — `contentId` is sha256 over timestamp-free substance, so dismissal survives heartbeats, restarts, and Rust upgrades (tested: capturedAt/updatedAt bumps don't change it). (2) Liveness (A2/D7) — Task 1's third `live_session_keys` input + per-pane `live` flag, Task 2's read-only registry join, Task 2b's server-side guard on the direct sessionRef rung (failing integration test first), Task 4's sessionRef strip for live panes, Task 5's live note, Task 8 Scenario 3's no-restart proof (no new `--resume` pair). (3) Inventory correctness — `ledgerOnly` matched against effective refs across ALL device unions and excluding live rows (A4, tested), the A15 staleness rule dropping >15-min-silent clients (pure helper test + route test), the self-pollution filter including the A16 concurrent-client rule (same-fresh-browser multi-window junk can never win primary-device selection; pure helper test), auth'd. (4) kata h9vt — disposition section + Task 9 (Option A kept; Option B rejected with reason: ledger has no layout; the GET read API + `parse_selector` explicitly REUSED per A11; deploy-tab-diff remediation + spec reworked per A12; freshell-ws screenshot broker handled via the explicit A13 audit table since the compiler is silent for pub library items). TDD red-first for trigger conditions, inventory API, authority chain, liveness guard, dismissal — Tasks 1-5 + 2b all test-first; Task 8's e2e includes an explicit red-verification step. E2E — Task 8: three scenarios (restart accept-resume with argv-pair proof + browser-pane mixed-kind recreation, decline, no-restart live loss) with own RustServer/ephemeral ports/fresh contexts/same-browser-reload guard. Scope fence, a11y lint, PR policy — Global Constraints + Task 10 (which also carries the AD-1 §4.4 ratification statement and the B4 flag).
+**1. Spec coverage:** (1) recover-my-panes flow — offer/trigger D1-D3 + Tasks 3/5/6 (boot-capture rationale corrected per A8, with the import-order invariants pinned and tested in Task 3); accept recreation honoring §4.2 D4-D5 + Tasks 1/4/5, including the A10 per-kind adapter (editor `content: ''` default, fresh-agent `restoreError` strip) with unit tests for editor/extension/picker; decline remembered Task 3/5, with the A5/A6 fix — `contentId` is sha256 over timestamp-free substance, so dismissal survives heartbeats, restarts, and Rust upgrades (tested: capturedAt/updatedAt bumps don't change it). (2) Liveness (A2/D7) — Task 1's third `live_session_keys` input + per-pane `live` flag, Task 2's read-only registry join, Task 2b's server-side guard on the direct sessionRef rung (failing integration test first), Task 4's sessionRef strip for live panes, Task 5's live note, Task 8 Scenario 3's no-restart proof (no new `--resume` pair). (3) Inventory correctness — `ledgerOnly` matched against effective refs across ALL device unions and excluding live rows (A4, tested), the A15 staleness rule dropping >15-min-silent clients (pure helper test + route test), the self-pollution filter including the A16 concurrent-client rule (same-fresh-browser multi-window junk can never win primary-device selection; pure helper test + a dedicated route test that forces the `bootAgoMs` → `boot_cutoff` wiring), auth'd. (4) kata h9vt — disposition section + Task 9 (Option A kept; Option B rejected with reason: ledger has no layout; the GET read API + `parse_selector` explicitly REUSED per A11; deploy-tab-diff remediation + spec reworked per A12; freshell-ws screenshot broker handled via the explicit A13 audit table since the compiler is silent for pub library items). TDD red-first for trigger conditions, inventory API, authority chain, liveness guard, dismissal — Tasks 1-5 + 2b all test-first; Task 8's e2e includes an explicit red-verification step. E2E — Task 8: three scenarios (restart accept-resume with argv-pair proof + browser-pane mixed-kind recreation, decline, no-restart live loss) with own RustServer/ephemeral ports/fresh contexts/same-browser-reload guard. Scope fence, a11y lint, PR policy — Global Constraints + Task 10 (which also carries the AD-1 §4.4 ratification statement and the B4 flag).
 
 **1b. No silent deferrals:** no stubs or fake providers stand in for required behavior — the e2e uses the repo's established fake-CLI fixture (the same production-path proof used by the existing ledger restart e2e; it exercises the real create/resume path), and the Task 8 resume proof is built from the argv log + fixture marker (the previously-cited assertion did not exist — A14). Non-terminal pane recreation reuses the production `reopenClosedTab` restore path with a minimal per-kind adapter (D5/A10) — recreated, not deferred. Split geometry (D6) and editor buffer content (D6/A5) are not in the store — data facts, not deferrals. Two DOCUMENTED decisions with recorded rationale, not silent deferrals: (a) the freshopencode fresh-start limitation (Known-limitation note: fenced B4 crate owns the `opencode_ws.rs` bug; sessionRef passthrough kept forward-compatible; flagged to B4 in Task 10 Step 3); (b) live sessions are surfaced but NOT resumed (D7: attach-to-live rejected as unverified and colliding with Lane B1 ownership; server guard as defense-in-depth). No UNRESOLVED COVERAGE GAPS.
 
 **2. Placeholder scan:** the `row_*` accessors, `digest16`, and `select_foreign_recent_generation_ids` (Task 1), `union_value`, `live_session_keys`, and the registry-handle type (Task 2), and the guard's row-matching (Task 2b) are named adapters against real definitions the implementer opens — each is bound to a concrete file/line source (`pane_ledger.rs:93`, `tabs_persist.rs:70-87`, `terminal.rs:1690-1745`, main.rs wiring), with tests as the arbiter. Task 9's freshell-ws deletions are an explicit per-method audit table, not a "compiler will say" hope. No TBD/TODO/"handle edge cases" items remain.
 
-**3. Type consistency:** `DeviceUnion`/`select_foreign_recent_generation_ids`/`build_inventory` (Task 1, 3-arg signature) consumed verbatim in Task 2; the `live` field appears in Task 1's output schema, Task 4's `RecoveryPane` type and test fixtures, Task 5's `INVENTORY` fixture and live-note behavior, and Task 8 Scenario 3's assertions; `RecoveryInventory`/`RecoveryPane`/`RecoveryTabPlan` (Task 4) consumed in Task 5; `getClientInstanceId` exported in Task 5 and consumed there; testids `recovery-offer-panel`/`recovery-accept`/`recovery-decline`/`recovery-live-note` defined in Task 5, consumed in Task 8; `ledgerState` values (`bound|closed|gc_expired|unknown`) match between Task 1 output, Task 4 types, and tests; Task 2b's refusal frame mirrors the existing `RestoreUnavailable` shape consumed by the harness Task 2b's test copies; the D2 `bootAgoMs` chain is type-consistent end-to-end — `bootCapturedAtMs` (Task 3 boot-state) → `PendingOffer.bootAt` (Task 3 dismissal) → `getRecoveryInventory(clientInstanceId, bootAgoMs)` using the tuple-entries `buildQueryString` call shape that matches the REAL `api.ts:273` signature (Task 4) → `bootAgoMs` query param → `boot_cutoff` → `select_foreign_recent_generation_ids(_, _, boot_cutoff)` (Tasks 1/2, route param optional-default-0 so Task 2's existing route tests hold); Task 8's argv matcher `hasClaudeResumePair` targets the fake claude CLI's `--resume` flag, not codex's bare `resume` token, so the accept-resume poll can pass and the D7 negative assertion is non-vacuous.
+**3. Type consistency:** `DeviceUnion`/`select_foreign_recent_generation_ids`/`build_inventory` (Task 1, 3-arg signature) consumed verbatim in Task 2; the `live` field appears in Task 1's output schema, Task 4's `RecoveryPane` type and test fixtures, Task 5's `INVENTORY` fixture and live-note behavior, and Task 8 Scenario 3's assertions; `RecoveryInventory`/`RecoveryPane`/`RecoveryTabPlan` (Task 4) consumed in Task 5; `getClientInstanceId` exported in Task 5 and consumed there; testids `recovery-offer-panel`/`recovery-accept`/`recovery-decline`/`recovery-live-note` defined in Task 5, consumed in Task 8; `ledgerState` values (`bound|closed|gc_expired|unknown`) match between Task 1 output, Task 4 types, and tests; Task 2b's refusal frame mirrors the existing `RestoreUnavailable` shape consumed by the harness Task 2b's test copies; the D2 `bootAgoMs` chain is type-consistent end-to-end — `bootCapturedAtMs` (Task 3 boot-state) → `PendingOffer.bootAt` (Task 3 dismissal) → `getRecoveryInventory(clientInstanceId, bootAgoMs)` using the tuple-entries `buildQueryString` call shape that matches the REAL `api.ts:273` signature (Task 4) → `bootAgoMs` query param (`InventoryQuery.boot_ago_ms: Option<u64>` in Task 2's Step 3 snippet) → `boot_cutoff = now_ms().saturating_sub(...)` in the handler → 3-arg `read_foreign_unions(_, _, boot_cutoff)` → `select_foreign_recent_generation_ids(_, _, boot_cutoff)` (Tasks 1/2; optional-default-0 so Task 2's other route tests hold, and the wiring is FORCED by the dedicated `route_bootagoms_drops_concurrent_post_boot_clients` route test — real wall-clock fixtures, asserts a post-boot client is dropped with `bootAgoMs=30000` and kept without the param); Task 8's argv matcher `hasClaudeResumePair` targets the fake claude CLI's `--resume` flag, not codex's bare `resume` token, so the accept-resume poll can pass and the D7 negative assertion is non-vacuous.

From bf45f7c1ad12f2fe25dddc81d24684b0406cfc7b Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:48:08 -0700
Subject: [PATCH 20/87] feat(terminal): sessionRef liveness-bound lease with
 TTL kill-before-release semantics
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Council rule 7 (D8 two-writers): one in-flight create per sessionRef,
enforced in TerminalRegistry via a lease map keyed "provider\0sessionId"
(mirrors keyed_create_inflight) plus a session_ref_bindings map recording
the winner's terminalId at spawn-complete.

- claim_session_ref: BoundElsewhere (live row-join or non-dead binding) >
  Held (unexpired) > ExpiredNeedsKill{pid} (TTL + recorded child; lease
  stays held — kill-before-release) > revoke + hold closed (TTL, pid-less).
- complete_session_ref_claim: bind + release + duplicate alarm; false if
  revoked while spawning.
- fail_session_ref_claim / release_session_ref_leases_for_conn /
  force_release_after_confirmed_kill: release on spawn fail and conn
  death; pid-carrying conn-death entries returned still-held for
  confirmed kill first.
- SESSION_REF_LEASE_TTL_MS = 20s explicit wall-clock backstop (not
  derived from the spawn-gate permit budget).

Unit level only; Task 6 wires the create path to this exact API.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-terminal/src/registry.rs | 382 +++++++++++++++++++++++
 1 file changed, 382 insertions(+)

diff --git a/crates/freshell-terminal/src/registry.rs b/crates/freshell-terminal/src/registry.rs
index 9ec59884c..f4a96bde8 100644
--- a/crates/freshell-terminal/src/registry.rs
+++ b/crates/freshell-terminal/src/registry.rs
@@ -405,6 +405,68 @@ pub type ActivityObserver = Arc<dyn Fn(ActivityEvent) + Send + Sync>;
 const DEFAULT_RESPAWN_LIVENESS_WINDOW_MS: i64 = 30_000;
 const DEFAULT_RESPAWN_GENERATION_CAP: i64 = 3;
 
+/// Explicit wall-clock backstop for a hung holder. NOT derived from any
+/// "spawn budget" — the 10s constant at create_limit.rs:49 (spawn_timeout_ms,
+/// env FRESHELL_SPAWN_GATE_TIMEOUT_MS) bounds the spawn-GATE PERMIT wait,
+/// not spawn duration; spawns run unbounded in spawn_blocking. Task 6 makes
+/// this env-tunable and adds spawn-duration instrumentation to tune it on
+/// evidence.
+pub const SESSION_REF_LEASE_TTL_MS: u64 = 20_000;
+pub const SESSION_RESERVED_RETRY_AFTER_MS: u64 = 1_000;
+
+/// Outcome of [`TerminalRegistry::claim_session_ref`] (council rule 7, D8:
+/// one in-flight create per sessionRef, liveness-bound).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum SessionRefClaim {
+    Acquired,
+    Held {
+        retry_after_ms: u64,
+    },
+    /// TTL expired on a holder with a recorded child: caller must kill the
+    /// holder's spawn via the REGISTRY handle (group-kill discipline,
+    /// pty.rs:352-386 — never a raw single-pid SIGKILL), CONFIRM death, then
+    /// call force_release_after_confirmed_kill and re-claim. The pid is for
+    /// ESRCH-confirmation, not for raw kill().
+    ExpiredNeedsKill {
+        pid: u32,
+    },
+    BoundElsewhere {
+        terminal_id: String,
+    },
+}
+
+/// One in-flight sessionRef create reservation (value side of
+/// `TerminalRegistry::session_ref_leases`, keyed `"provider\u{0}sessionId"`).
+/// Released on spawn complete (bind), spawn fail (error), or holder
+/// connection death; [`SESSION_REF_LEASE_TTL_MS`] is the wall-clock backstop
+/// for a hung holder — expiry is KILL-BEFORE-RELEASE (a pid-carrying lease
+/// stays held until the caller confirms the kill; a pid-less one is revoked
+/// and held closed, never released except via holder conn death or spawn
+/// failure, both of which prove no orphan child exists).
+#[derive(Debug, Clone)]
+struct SessionRefLease {
+    /// Stored alongside the string key so conn-death cleanup can hand
+    /// callers real [`SessionLocator`]s without parsing NUL-joined keys.
+    locator: SessionLocator,
+    holder_create_request_id: String,
+    holder_conn: u64,
+    acquired_at_ms: u64,
+    /// The spawned child's pid once the holder records it
+    /// ([`TerminalRegistry::set_session_ref_lease_pid`]) — presence decides
+    /// TTL expiry's shape (`ExpiredNeedsKill` vs revoke-and-hold-closed).
+    pid: Option<u32>,
+    /// Set when TTL expired on a pid-less holder: there is nothing to kill,
+    /// so the lease is held closed and the holder's late
+    /// [`TerminalRegistry::complete_session_ref_claim`] is rejected.
+    revoked: bool,
+}
+
+/// A sessionRef lease's map key: `"provider\u{0}sessionId"` (NUL joint —
+/// neither side can contain it, so the key is collision-free).
+fn session_ref_key(locator: &SessionLocator) -> String {
+    format!("{}\u{0}{}", locator.provider, locator.session_id)
+}
+
 #[derive(Clone)]
 pub struct TerminalRegistry {
     inner: Arc<Mutex<RegistryInner>>,
@@ -450,6 +512,19 @@ pub struct TerminalRegistry {
     /// one key could BOTH pass the `newest_live_by_create_request_id` check
     /// and both spawn — the exact duplicate-writer shape the dedupe closes.
     keyed_create_inflight: Arc<Mutex<std::collections::HashSet<String>>>,
+    /// Council rule 7 (D8): one in-flight create per sessionRef. Keyed
+    /// `"provider\u{0}sessionId"` ([`session_ref_key`]); see
+    /// [`SessionRefLease`] for the release/TTL/kill-before-release rules.
+    /// Mirrors the `keyed_create_inflight` shape (claim before spawn,
+    /// release after bind/fail/conn-death).
+    session_ref_leases: Arc<Mutex<HashMap<String, SessionRefLease>>>,
+    /// locator key ([`session_ref_key`]) → the terminalId a completed claim
+    /// bound the sessionRef to. Consulted by
+    /// [`Self::claim_session_ref`] alongside
+    /// [`Self::live_terminal_for_session_ref`]; a binding whose terminal is
+    /// KNOWN dead (registered but not Running) is pruned instead of
+    /// answering `BoundElsewhere`, so a dead winner never strands losers.
+    session_ref_bindings: Arc<Mutex<HashMap<String, String>>>,
 }
 
 impl Default for TerminalRegistry {
@@ -500,6 +575,8 @@ impl TerminalRegistry {
             )),
             respawn_generation_cap: Arc::new(AtomicI64::new(DEFAULT_RESPAWN_GENERATION_CAP)),
             keyed_create_inflight: Arc::new(Mutex::new(std::collections::HashSet::new())),
+            session_ref_leases: Arc::new(Mutex::new(HashMap::new())),
+            session_ref_bindings: Arc::new(Mutex::new(HashMap::new())),
         }
     }
 
@@ -1612,6 +1689,219 @@ impl TerminalRegistry {
             .remove(key);
     }
 
+    /// Council rule 7 (D8): claim the one in-flight create slot for a
+    /// sessionRef. Checks, in order:
+    ///
+    /// 1. A live terminal already carrying the ref
+    ///    ([`Self::live_terminal_for_session_ref`]) or a recorded binding
+    ///    whose terminal is not KNOWN dead → `BoundElsewhere` (attach to the
+    ///    winner). A binding whose terminal is known dead (registered but
+    ///    not Running) is pruned instead — a dead winner must not strand
+    ///    losers.
+    /// 2. A held, unexpired lease → `Held` (retry after
+    ///    [`SESSION_RESERVED_RETRY_AFTER_MS`]).
+    /// 3. A held lease past `acquired_at_ms + `[`SESSION_REF_LEASE_TTL_MS`]:
+    ///    with a recorded pid → `ExpiredNeedsKill` (KILL-BEFORE-RELEASE: the
+    ///    lease stays held until [`Self::force_release_after_confirmed_kill`]);
+    ///    without one (holder hung pre-spawn, nothing to kill) → revoke the
+    ///    lease, ERROR-log, and answer `Held` — hold closed, never release
+    ///    what you can't kill.
+    /// 4. Otherwise the slot is free → record the lease, `Acquired`.
+    ///
+    /// `now_ms` is caller-supplied wall-clock so tests never sleep.
+    pub fn claim_session_ref(
+        &self,
+        locator: &SessionLocator,
+        holder_create_request_id: &str,
+        holder_conn: u64,
+        now_ms: u64,
+    ) -> SessionRefClaim {
+        let key = session_ref_key(locator);
+
+        // 1a. Row-join liveness: a live terminal already carries this ref.
+        if let Some(terminal_id) = self.live_terminal_for_session_ref(locator) {
+            return SessionRefClaim::BoundElsewhere { terminal_id };
+        }
+
+        // 1b. Recorded binding — honored unless its terminal is KNOWN dead
+        // (a registered row that is no longer Running). Lock order: the
+        // bindings mutex is held across the liveness probes, which take only
+        // the registry `inner` + terminal locks; no path acquires bindings
+        // while holding those, so the order is acyclic.
+        {
+            let mut bindings = self
+                .session_ref_bindings
+                .lock()
+                .expect("session-ref bindings lock");
+            if let Some(terminal_id) = bindings.get(&key).cloned() {
+                let known_dead = self.is_running(&terminal_id) && !self.is_live(&terminal_id);
+                if known_dead {
+                    bindings.remove(&key);
+                } else {
+                    return SessionRefClaim::BoundElsewhere { terminal_id };
+                }
+            }
+        }
+
+        let mut leases = self
+            .session_ref_leases
+            .lock()
+            .expect("session-ref lease lock");
+        match leases.get_mut(&key) {
+            None => {
+                leases.insert(
+                    key,
+                    SessionRefLease {
+                        locator: locator.clone(),
+                        holder_create_request_id: holder_create_request_id.to_string(),
+                        holder_conn,
+                        acquired_at_ms: now_ms,
+                        pid: None,
+                        revoked: false,
+                    },
+                );
+                SessionRefClaim::Acquired
+            }
+            Some(lease) => {
+                let expired = now_ms > lease.acquired_at_ms + SESSION_REF_LEASE_TTL_MS;
+                if !expired {
+                    return SessionRefClaim::Held {
+                        retry_after_ms: SESSION_RESERVED_RETRY_AFTER_MS,
+                    };
+                }
+                match lease.pid {
+                    Some(pid) => SessionRefClaim::ExpiredNeedsKill { pid },
+                    None => {
+                        if !lease.revoked {
+                            lease.revoked = true;
+                            tracing::error!(target: "invariant",
+                                provider = %locator.provider,
+                                session_id = %locator.session_id,
+                                holder_create_request_id = %lease.holder_create_request_id,
+                                acquired_at_ms = lease.acquired_at_ms,
+                                now_ms,
+                                "session_ref_lease_revoked: TTL expired on a pid-less holder; held closed");
+                        }
+                        SessionRefClaim::Held {
+                            retry_after_ms: SESSION_RESERVED_RETRY_AFTER_MS,
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    /// Record the holder's spawned child pid on its lease, arming the TTL
+    /// expiry's `ExpiredNeedsKill` path. No-op if the lease is gone or held
+    /// by a different `createRequestId`.
+    pub fn set_session_ref_lease_pid(
+        &self,
+        locator: &SessionLocator,
+        holder_create_request_id: &str,
+        pid: u32,
+    ) {
+        let key = session_ref_key(locator);
+        let mut leases = self
+            .session_ref_leases
+            .lock()
+            .expect("session-ref lease lock");
+        if let Some(lease) = leases.get_mut(&key) {
+            if lease.holder_create_request_id == holder_create_request_id {
+                lease.pid = Some(pid);
+            }
+        }
+    }
+
+    /// Spawn succeeded: record binding, release lease, run the duplicate alarm.
+    /// Returns false if the lease was revoked while spawning (caller must kill
+    /// its own child and fail the create loudly). A revoked lease is NOT
+    /// released here — kill-before-release: the caller confirms its child's
+    /// death, then calls [`Self::force_release_after_confirmed_kill`].
+    pub fn complete_session_ref_claim(
+        &self,
+        locator: &SessionLocator,
+        holder_create_request_id: &str,
+        terminal_id: &str,
+    ) -> bool {
+        let key = session_ref_key(locator);
+        let bound = {
+            let mut leases = self
+                .session_ref_leases
+                .lock()
+                .expect("session-ref lease lock");
+            match leases.get(&key) {
+                Some(lease)
+                    if lease.holder_create_request_id == holder_create_request_id
+                        && !lease.revoked =>
+                {
+                    leases.remove(&key);
+                    true
+                }
+                _ => false,
+            }
+        };
+        if !bound {
+            return false;
+        }
+        self.session_ref_bindings
+            .lock()
+            .expect("session-ref bindings lock")
+            .insert(key, terminal_id.to_string());
+        self.alarm_if_duplicate_session_ref(locator);
+        true
+    }
+
+    /// Spawn failed: release the holder's lease (no child exists — the spawn
+    /// itself errored — so release is safe even for a revoked lease). No-op
+    /// if the lease is gone or held by a different `createRequestId`.
+    pub fn fail_session_ref_claim(&self, locator: &SessionLocator, holder_create_request_id: &str) {
+        let key = session_ref_key(locator);
+        let mut leases = self
+            .session_ref_leases
+            .lock()
+            .expect("session-ref lease lock");
+        if leases
+            .get(&key)
+            .is_some_and(|l| l.holder_create_request_id == holder_create_request_id)
+        {
+            leases.remove(&key);
+        }
+    }
+
+    /// Connection death: release this conn's leases. Returns (locator_key, pid)
+    /// pairs whose in-flight children the caller must kill (kill-before-release
+    /// applies: entries WITH a pid are returned still-held; caller kills,
+    /// confirms, then calls force_release_after_confirmed_kill).
+    pub fn release_session_ref_leases_for_conn(
+        &self,
+        conn: u64,
+    ) -> Vec<(SessionLocator, Option<u32>)> {
+        let mut leases = self
+            .session_ref_leases
+            .lock()
+            .expect("session-ref lease lock");
+        let mut out = Vec::new();
+        leases.retain(|_, lease| {
+            if lease.holder_conn != conn {
+                return true;
+            }
+            out.push((lease.locator.clone(), lease.pid));
+            // pid-less: nothing spawned, release now. pid-carrying: keep held
+            // until the caller confirms the kill (kill-before-release).
+            lease.pid.is_some()
+        });
+        out
+    }
+
+    /// The caller killed the holder's child via the registry PTY handle and
+    /// CONFIRMED death (ESRCH): release the lease so the next claim wins.
+    pub fn force_release_after_confirmed_kill(&self, locator: &SessionLocator) {
+        self.session_ref_leases
+            .lock()
+            .expect("session-ref lease lock")
+            .remove(&session_ref_key(locator));
+    }
+
     /// §5.4 backstop detector (always-on, capability-independent): if a key
     /// now has two or more LIVE terminals, make it loud — two live PTYs on one
     /// `createRequestId` means two JSONL writers on one session file.
@@ -3616,6 +3906,98 @@ mod tests {
         );
     }
 
+    // ------------------------------------------------------------------
+    // Council rule 7 (D8): sessionRef liveness-bound lease — claim /
+    // complete / fail / conn-death release / TTL kill-before-release.
+    // ------------------------------------------------------------------
+
+    fn test_registry() -> TerminalRegistry {
+        TerminalRegistry::new()
+    }
+
+    fn locator(provider: &str, session_id: &str) -> SessionLocator {
+        SessionLocator {
+            provider: provider.to_string(),
+            session_id: session_id.to_string(),
+        }
+    }
+
+    #[test]
+    fn second_claim_while_held_is_reserved() {
+        let reg = test_registry();
+        let s = locator("claude", "s1");
+        assert!(matches!(
+            reg.claim_session_ref(&s, "cr-A", 1, 1000),
+            SessionRefClaim::Acquired
+        ));
+        assert!(matches!(
+            reg.claim_session_ref(&s, "cr-B", 2, 1500),
+            SessionRefClaim::Held { .. }
+        ));
+    }
+
+    #[test]
+    fn completed_claim_yields_bound_elsewhere() {
+        let reg = test_registry();
+        let s = locator("claude", "s1");
+        reg.claim_session_ref(&s, "cr-A", 1, 1000);
+        assert!(reg.complete_session_ref_claim(&s, "cr-A", "term-1"));
+        match reg.claim_session_ref(&s, "cr-B", 2, 2000) {
+            SessionRefClaim::BoundElsewhere { terminal_id } => assert_eq!(terminal_id, "term-1"),
+            other => panic!("expected BoundElsewhere, got {other:?}"),
+        }
+    }
+
+    /// winner-dies-mid-claim (council red test): holder conn death releases the
+    /// pid-less lease; the loser's next claim wins.
+    #[test]
+    fn winner_dies_mid_claim_releases_lease() {
+        let reg = test_registry();
+        let s = locator("claude", "s1");
+        reg.claim_session_ref(&s, "cr-A", 1, 1000);
+        let to_kill = reg.release_session_ref_leases_for_conn(1);
+        assert!(to_kill.iter().all(|(_, pid)| pid.is_none()));
+        assert!(matches!(
+            reg.claim_session_ref(&s, "cr-B", 2, 1500),
+            SessionRefClaim::Acquired
+        ));
+    }
+
+    /// winner-hangs-mid-claim (council red test): TTL expiry with a recorded
+    /// child pid demands kill-before-release; confirmed kill releases; a pid-less
+    /// hung holder is revoked and HELD CLOSED, never released.
+    #[test]
+    fn winner_hangs_mid_claim_ttl_is_kill_before_release() {
+        let reg = test_registry();
+        let s = locator("claude", "s1");
+        reg.claim_session_ref(&s, "cr-A", 1, 1000);
+        reg.set_session_ref_lease_pid(&s, "cr-A", 4242);
+        let late = 1000 + SESSION_REF_LEASE_TTL_MS + 1;
+        match reg.claim_session_ref(&s, "cr-B", 2, late) {
+            SessionRefClaim::ExpiredNeedsKill { pid } => assert_eq!(pid, 4242),
+            other => panic!("expected ExpiredNeedsKill, got {other:?}"),
+        }
+        reg.force_release_after_confirmed_kill(&s);
+        assert!(matches!(
+            reg.claim_session_ref(&s, "cr-B", 2, late + 1),
+            SessionRefClaim::Acquired
+        ));
+    }
+
+    #[test]
+    fn hung_holder_without_pid_is_revoked_and_held_closed() {
+        let reg = test_registry();
+        let s = locator("claude", "s1");
+        reg.claim_session_ref(&s, "cr-A", 1, 1000);
+        let late = 1000 + SESSION_REF_LEASE_TTL_MS + 1;
+        assert!(matches!(
+            reg.claim_session_ref(&s, "cr-B", 2, late),
+            SessionRefClaim::Held { .. }
+        ));
+        // The revoked holder's late completion is rejected.
+        assert!(!reg.complete_session_ref_claim(&s, "cr-A", "term-late"));
+    }
+
     /// §5.1 atomic-stamp insert-edge interleave (§9.1 test 5): the key is part
     /// of the row inserted under the registry lock, so an observer's
     /// `newest_live_by_create_request_id` sees either no row or the

From 45b0bc3afbc43d23feed43708987b29db8437add Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:54:19 -0700
Subject: [PATCH 21/87] docs(plan): make Task 5 hijack-guard test non-vacuous
 per fresh-eyes iteration 3

The located_session_bound_elsewhere_is_rejected pin had only negative
assertions, which pass identically whether the adoption-tail guard fired
or the locator silently never resolved (wrong cwd, bad seed timing) - and
the prescribed identity-inversion check cannot tell those worlds apart.

- Test delta now keeps a locator handle, seeds the rollout with
  payload.cwd = the pane's own cwd (mirroring test 1), and asserts the
  positive resolution signal locator.armed_count() == 0 BEFORE the
  negative identity/resume assertions.
- Step 2's inversion instruction for this test now targets the positive
  signal (invert to armed_count() == 1) and warns that identity-only
  inversions cannot prove non-vacuity.
---
 .../plans/2026-07-26-codex-rollout-locator.md | 27 ++++++++++++++-----
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/docs/plans/2026-07-26-codex-rollout-locator.md b/docs/plans/2026-07-26-codex-rollout-locator.md
index 10f9e4544..449e4421e 100644
--- a/docs/plans/2026-07-26-codex-rollout-locator.md
+++ b/docs/plans/2026-07-26-codex-rollout-locator.md
@@ -1971,13 +1971,24 @@ REAL `PaneLedger::new(Some(dir))`. The codex adaptations, per test:
         // with ("codex", <TID>) via state.identity.upsert(...), then retire it
         // via state.identity.retire("victim") (the exit-path call —
         // terminal.rs:1370 area shows the exact form).
-        // Register a real PTY "t1" (codex mode), arm it, then
-        // note_possible_submit(&state, "t1", "\r").await to open the
+        // Register a real PTY "t1" (codex mode), arm it, and keep a locator
+        // handle (let locator = state.codex_locator.as_ref().unwrap().clone()).
+        // Then note_possible_submit(&state, "t1", "\r").await to open the
         // Enter-anchored window, THEN seed the rollout for <TID> (after the
         // submit — the first-submit re-snapshot would exclude a pre-seeded
-        // file), and poll drain_and_associate past the window.
-        // Assert: t1 gained NO identity (state.identity.session_ref_for("t1")
-        // is None) and its registry entry's resume_session_id is None.
+        // file) with payload.cwd set to THE PANE'S OWN cwd, exactly as in the
+        // first test — the rollout must be a fully resolvable candidate, or
+        // this test proves nothing. Poll drain_and_associate past the window.
+        //
+        // Assert BOTH halves. The positive resolution signal comes FIRST so
+        // the negative assertions cannot pass vacuously — a locator that
+        // never resolved (wrong cwd, bad seed timing) also leaves identity
+        // None, and identity-only assertions cannot tell those worlds apart:
+        //   locator.armed_count() == 0
+        //     // tick emitted Located and disarmed: resolution HAPPENED, so
+        //     // whatever follows is the adoption-tail guard's doing
+        //   state.identity.session_ref_for("t1") is None   // guard refused
+        //   registry entry for t1: resume_session_id is None
     }
 ```
 
@@ -1996,7 +2007,11 @@ can fail: temporarily invert one core assertion per test (e.g. assert the
 identity is `None`), watch it fail, restore it. Record "verified-red by
 inversion" in the commit message. The third test (bound-elsewhere) exercises
 Task 3's new guard end-to-end for the first time — if it passes first try,
-apply the same inversion check.
+invert its POSITIVE signal (assert `locator.armed_count() == 1`), watch it
+fail, restore. Inverting only the identity-is-None assertions is NOT a valid
+check for this test: those fail identically whether the guard fired or the
+locator never resolved, so they cannot prove the test is non-vacuous — the
+armed_count inversion is the one that proves resolution actually occurred.
 
 - [ ] **Step 3: Fix any real gaps minimally; re-run to GREEN**
 

From 16c00cb0e4417d495fc4d95240010b6f5aac4d66 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:59:05 -0700
Subject: [PATCH 22/87] fix(terminal): prune sessionRef bindings on row
 removal; make complete_session_ref_claim atomic
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Task 5 review fix round 1 (both findings Important):

1. Killed winner stranded the sessionRef: kill_internal removes the
   terminal row entirely, so claim_session_ref's "known dead" probe
   (registered-but-not-Running) could never fire for a killed winner --
   the unknown-id binding was honored as BoundElsewhere{dead-id} forever.
   Now kill_internal (the only terminals.remove site; natural exit
   retains the row) prunes any session_ref_bindings entry pointing at
   the removed terminal. The brief-mandated
   completed_claim_yields_bound_elsewhere test (never-registered id)
   still passes unchanged.

2. complete_session_ref_claim released the lease and inserted the
   binding under separate locks, opening a window where a racing
   claim_session_ref saw no row, no binding, no lease -> Acquired ->
   second spawn. The binding is now inserted while the leases lock is
   still held. Lock order leases -> bindings is acyclic:
   claim_session_ref's bindings block ends before it takes leases, and
   no path acquires leases while holding bindings.

New test: killed_winner_binding_is_pruned_so_next_claim_acquires
(claim -> complete -> real kill path -> next claim Acquired), verified
RED before the fix.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-terminal/src/registry.rs | 72 ++++++++++++++++++++----
 1 file changed, 62 insertions(+), 10 deletions(-)

diff --git a/crates/freshell-terminal/src/registry.rs b/crates/freshell-terminal/src/registry.rs
index f4a96bde8..92be44d66 100644
--- a/crates/freshell-terminal/src/registry.rs
+++ b/crates/freshell-terminal/src/registry.rs
@@ -1220,6 +1220,18 @@ impl TerminalRegistry {
         let Some(mut handle) = handle else {
             return false;
         };
+        // sessionRef lease fix (finding 1): the kill path REMOVES the row
+        // entirely, so `claim_session_ref`'s "known dead" probe (which needs
+        // a registered-but-not-Running row) can never fire for a killed
+        // winner — an UNKNOWN id would be honored as `BoundElsewhere{dead-id}`
+        // forever. Prune any sessionRef binding pointing at this terminal at
+        // row-removal time instead. This is the ONLY row-removal site
+        // (natural exit RETAINS the row via `finish_pty_exit`). The `inner`
+        // lock is already released here, so no ordering hazard.
+        self.session_ref_bindings
+            .lock()
+            .expect("session-ref bindings lock")
+            .retain(|_, bound_id| bound_id != terminal_id);
         let was_running = {
             let mut s = handle.shared.lock().expect("terminal lock");
             let was_running = s.status == TerminalRunStatus::Running;
@@ -1824,7 +1836,7 @@ impl TerminalRegistry {
         terminal_id: &str,
     ) -> bool {
         let key = session_ref_key(locator);
-        let bound = {
+        {
             let mut leases = self
                 .session_ref_leases
                 .lock()
@@ -1835,18 +1847,24 @@ impl TerminalRegistry {
                         && !lease.revoked =>
                 {
                     leases.remove(&key);
-                    true
+                    // ATOMICITY (fix round 1, finding 2): the binding MUST be
+                    // inserted while the leases lock is still held. Releasing
+                    // the lease first and binding under a separate lock opens
+                    // a window where a racing `claim_session_ref` sees no live
+                    // row, no binding, and no lease -> `Acquired` -> a second
+                    // spawn: the exact duplicate-writer race this primitive
+                    // exists to close. Lock order leases -> bindings is
+                    // acyclic: `claim_session_ref`'s bindings block ends
+                    // before it takes the leases lock, and no other path
+                    // acquires the leases lock while holding bindings.
+                    self.session_ref_bindings
+                        .lock()
+                        .expect("session-ref bindings lock")
+                        .insert(key, terminal_id.to_string());
                 }
-                _ => false,
+                _ => return false,
             }
-        };
-        if !bound {
-            return false;
         }
-        self.session_ref_bindings
-            .lock()
-            .expect("session-ref bindings lock")
-            .insert(key, terminal_id.to_string());
         self.alarm_if_duplicate_session_ref(locator);
         true
     }
@@ -3998,6 +4016,40 @@ mod tests {
         assert!(!reg.complete_session_ref_claim(&s, "cr-A", "term-late"));
     }
 
+    /// Fix round 1, finding 1: a KILLED winner must not strand the
+    /// sessionRef. The kill path REMOVES the terminal row entirely
+    /// ([`TerminalRegistry::kill_internal`]), so the binding's terminal id
+    /// becomes UNKNOWN to the registry — the claim-time "known dead" probe
+    /// can never fire. The binding must instead be pruned at row-removal
+    /// time so the next claim wins, rather than answering
+    /// `BoundElsewhere{dead-id}` forever.
+    #[test]
+    fn killed_winner_binding_is_pruned_so_next_claim_acquires() {
+        let reg = test_registry();
+        let s = locator("claude", "s1");
+        assert!(matches!(
+            reg.claim_session_ref(&s, "cr-A", 1, 1000),
+            SessionRefClaim::Acquired
+        ));
+        // The winner's spawn registers a real row carrying the ref, then binds.
+        reg.register_headless(HeadlessTerminal {
+            terminal_id: "T-win".to_string(),
+            stream_id: "S-win".to_string(),
+            mode: "claude".to_string(),
+            resume_session_id: Some("s1".to_string()),
+            create_request_id: Some("cr-A".to_string()),
+            created_at: Some(1_000),
+        });
+        assert!(reg.complete_session_ref_claim(&s, "cr-A", "T-win"));
+        // User kills the winner: the real kill path removes the row entirely.
+        assert!(reg.kill("T-win"));
+        // The dead winner must not strand losers.
+        assert!(matches!(
+            reg.claim_session_ref(&s, "cr-B", 2, 2000),
+            SessionRefClaim::Acquired
+        ));
+    }
+
     /// §5.1 atomic-stamp insert-edge interleave (§9.1 test 5): the key is part
     /// of the row inserted under the registry lock, so an observer's
     /// `newest_live_by_create_request_id` sees either no row or the

From d96d71fff442f72818d0ba02f3755a6479640eb4 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:59:14 -0700
Subject: [PATCH 23/87] docs(plan): fix fresheyes iteration-3 blocking issue in
 B4 plan

Task 7's REST send-keys materialization change to freshell-freshagent/src/lib.rs
was declared but never verified nor committed within the task. Now: Step 1
writes the failing rest_send_keys_materialization_records_binding test in
lib.rs as part of the RED phase; Steps 2/4 run a second cargo test filter
exercising it (FAIL then PASS); Step 3 item 4 references the named test;
Step 5 stages both opencode_ws.rs and lib.rs and the commit message names
the REST send-keys site.
---
 .../plans/2026-07-26-freshagent-verdicts-resume.md | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/docs/plans/2026-07-26-freshagent-verdicts-resume.md b/docs/plans/2026-07-26-freshagent-verdicts-resume.md
index f7d6115ff..20ddf8d7d 100644
--- a/docs/plans/2026-07-26-freshagent-verdicts-resume.md
+++ b/docs/plans/2026-07-26-freshagent-verdicts-resume.md
@@ -1196,10 +1196,13 @@ async fn send_with_changed_settings_refreshes_the_binding() {
 
 (Driver plumbing comes from the existing tests in this file — e.g. the materialization/send tests around the harnesses at `:1080-1111` and `:1795-1819`; the assertions stand as written.)
 
+Also write the failing REST-path test NOW (it is part of this task's RED phase, not an afterthought): in `crates/freshell-freshagent/src/lib.rs`'s existing test module, add `#[tokio::test] async fn rest_send_keys_materialization_records_binding()` — modeled on the existing REST send-keys materialization (AGENT-08 continuity) test (locate the donor at implementation time) — install a `FakeIdentitySink` on `FreshAgentState`, drive the REST send-keys cold-start materialization for a REST-created pane carrying model/effort, and assert the sink received a binding whose `session_id` is the durable id, `resolves_pending` is the pane's placeholder id, and whose settings carry the REST create's model/effort.
+
 - [ ] **Step 2: Run tests to verify they fail**
 
 Run: `cargo test -p freshell-freshagent opencode_ws -- materialization_resolves_pending send_with_changed_settings`
-Expected: FAIL — no pendings, no bindings recorded.
+Then: `cargo test -p freshell-freshagent rest_send_keys_materialization_records_binding`
+Expected: FAIL for all three — no pendings, no bindings recorded (WS or REST).
 
 - [ ] **Step 3: Implement**
 
@@ -1244,19 +1247,20 @@ if let Some(sink) = self.identity_sink() {
 ```
 (Adapt local variable names at the site; opencode has no sandbox/permission concepts — always `None`.)
 3. `handle_send` commit (`:397-398`): after `session.model = model.clone(); session.effort = effort.clone();`, if the session id is durable (`starts_with("ses_")`), record a refresh binding (same awaited construction as above with `resolves_pending: None`, `create_request_id: None`, `supersedes: None`).
-4. REST materialization (`crates/freshell-freshagent/src/lib.rs`, the send-keys handler's cold-start block that persists `entry.durable_id` and broadcasts `FreshAgentSessionMaterialized`, near `lib.rs:1477-1516`): record the same binding through `FreshAgentState`'s sink (field added in Task 2, injected in Task 3) — `session_id: durable_id`, `mode: "freshopencode"`, `create_request_id: None`, `resolves_pending: Some(pane.placeholder_id.clone())`, settings from the pane record (`pane.model` / `pane.effort` / `pane.cwd`), awaited BEFORE the materialized broadcast (the handler is async). On `Err`, warn + broadcast the same `LEDGER_WRITE_FAILED` error-frame shape via `state.broadcast`. Without this site, REST-created sessions (Task 14 e2e test 2's seeding surface) never get a resume record (V10 A13-N1). Add an inline test in `lib.rs`'s existing test module, modeled on the existing send-keys materialization (AGENT-08 continuity) test — locate the donor at implementation time — asserting the `FakeIdentitySink` received a binding carrying the REST create's model/effort.
+4. REST materialization (`crates/freshell-freshagent/src/lib.rs`, the send-keys handler's cold-start block that persists `entry.durable_id` and broadcasts `FreshAgentSessionMaterialized`, near `lib.rs:1477-1516`): record the same binding through `FreshAgentState`'s sink (field added in Task 2, injected in Task 3) — `session_id: durable_id`, `mode: "freshopencode"`, `create_request_id: None`, `resolves_pending: Some(pane.placeholder_id.clone())`, settings from the pane record (`pane.model` / `pane.effort` / `pane.cwd`), awaited BEFORE the materialized broadcast (the handler is async). On `Err`, warn + broadcast the same `LEDGER_WRITE_FAILED` error-frame shape via `state.broadcast`. Without this site, REST-created sessions (Task 14 e2e test 2's seeding surface) never get a resume record (V10 A13-N1). This is the site Step 1's `rest_send_keys_materialization_records_binding` test (already written, currently RED) exercises — implementing this item turns it GREEN.
 
 - [ ] **Step 4: Run tests to verify they pass**
 
 Run: `cargo test -p freshell-freshagent opencode_ws`
-Expected: PASS.
+Then: `cargo test -p freshell-freshagent rest_send_keys_materialization_records_binding`
+Expected: PASS (both — the second run proves the REST site in `lib.rs`, not just the WS sites).
 
 - [ ] **Step 5: Commit**
 
 ```bash
 cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
-git add crates/freshell-freshagent/src/opencode_ws.rs
-git commit -m "feat(opencode): pending marker at create, binding row at ses_* materialization, refresh on settings change (P1.13)"
+git add crates/freshell-freshagent/src/opencode_ws.rs crates/freshell-freshagent/src/lib.rs
+git commit -m "feat(opencode): pending marker at create, binding row at ses_* materialization (WS + REST send-keys), refresh on settings change (P1.13)"
 ```
 
 ---

From b8cb904bde7fa896f7b64fa5500a3c29f353d44e Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:02:28 -0700
Subject: [PATCH 24/87] feat(server): pure recovery-inventory builder joining
 snapshots with pane-ledger (B3/P1.9)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Task 1 of the recover-my-panes lane: the PURE server-side inventory
builder (no HTTP yet - Task 2 adds the route).

- DeviceUnion + build_inventory(device_unions, bindings,
  live_session_keys) -> the /api/recovery inventory JSON: primary
  device = newest union with records, otherDevices summaries,
  D4 effective sessionRefs via the ledger superseded chain
  (bound|closed|gc_expired|unknown), D7 live flags, cross-device
  ledgerOnly (A4), and a timestamp-free 16-hex contentId (D3) so
  heartbeat capturedAt churn never defeats dismissal.
- select_foreign_recent_generation_ids: A15 staleness (15-min
  cutoff vs the remaining clients' max) + A16 concurrent-fresh-window
  boot-cutoff filter, consumed by Task 2 when composing unions.
- 11 sibling-module tests written red-first against a null stub.
- sha2 added to freshell-server (tabs_persist digest convention).

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 Cargo.lock                                    |   1 +
 crates/freshell-server/Cargo.toml             |   4 +
 crates/freshell-server/src/main.rs            |   1 +
 .../freshell-server/src/recovery_inventory.rs | 329 ++++++++++++++++++
 .../src/recovery_inventory_tests.rs           | 325 +++++++++++++++++
 5 files changed, 660 insertions(+)
 create mode 100644 crates/freshell-server/src/recovery_inventory.rs
 create mode 100644 crates/freshell-server/src/recovery_inventory_tests.rs

diff --git a/Cargo.lock b/Cargo.lock
index 20eb279dc..613f6ff49 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1362,6 +1362,7 @@ dependencies = [
  "serde",
  "serde_json",
  "sha1",
+ "sha2",
  "tempfile",
  "tokio",
  "tokio-tungstenite 0.24.0",
diff --git a/crates/freshell-server/Cargo.toml b/crates/freshell-server/Cargo.toml
index 9f3458602..679d428c8 100644
--- a/crates/freshell-server/Cargo.toml
+++ b/crates/freshell-server/Cargo.toml
@@ -66,6 +66,10 @@ dotenvy = "0.15.7"
 # `createHash('sha1')` (`fresh-agent-extras-router.ts:76`) -- not a security
 # use of SHA-1, just a deterministic per-cwd bucket name.
 sha1 = "0.10"
+# B3/P1.9 `recovery_inventory.rs`: the 16-hex-char `contentId` digest over the
+# timestamp-free inventory substance (same sha2 the tabs-persist digest
+# convention uses, `crates/freshell-ws/src/tabs_persist.rs:82-87`).
+sha2 = "0.10"
 # DIAG-01/DIAG-03: structured JSONL logging. `tracing` is the event/span API;
 # `tracing-subscriber`'s `registry` (default feature) gives the `Layer` +
 # `LookupSpan` machinery `logging.rs`'s custom formatter builds on, and
diff --git a/crates/freshell-server/src/main.rs b/crates/freshell-server/src/main.rs
index 3457cffc7..fd877414f 100644
--- a/crates/freshell-server/src/main.rs
+++ b/crates/freshell-server/src/main.rs
@@ -27,6 +27,7 @@ mod logging;
 mod network;
 mod proxy;
 mod rate_limit;
+mod recovery_inventory;
 mod screenshots;
 mod serve_client;
 mod session_directory;
diff --git a/crates/freshell-server/src/recovery_inventory.rs b/crates/freshell-server/src/recovery_inventory.rs
new file mode 100644
index 000000000..9b7e93ffe
--- /dev/null
+++ b/crates/freshell-server/src/recovery_inventory.rs
@@ -0,0 +1,329 @@
+//! B3/P1.9 Task 1 — the PURE recovery-inventory builder: joins tabs-snapshot
+//! device unions with pane-ledger binding rows into the `/api/recovery`
+//! inventory shape. No I/O here — Task 2 (the HTTP route) feeds it from the
+//! snapshot store, the ledger, and the terminal registry, and consumes
+//! `select_foreign_recent_generation_ids` when composing each device's union.
+#![allow(dead_code)] // consumed by Task 2 (the /api/recovery route wiring)
+
+use freshell_ws::pane_ledger::{BindingRow, RetiredReason, RowState};
+use serde_json::{json, Value};
+use std::collections::{HashMap, HashSet};
+
+pub struct DeviceUnion {
+    pub device_id: String,
+    pub union_doc: Value,
+}
+
+const STALE_CLIENT_MS: u64 = 15 * 60 * 1000; // heartbeat cadence is 5 min (tabRegistrySync.ts:21, 475-477)
+
+/// A15 staleness + A16 concurrent-client rules (D2): drop the requester's own
+/// generations; drop clients ALL of whose retained generations postdate
+/// `boot_cutoff_ms` (a client born after this browser session booted is a
+/// concurrently-opened fresh window, never lost data — a lost client's pushes
+/// all predate the fresh boot, so retention depth cannot misclassify it); then
+/// drop clients whose newest generation is >15 min older than the device max
+/// over the REMAINING clients (junk must never stale-out real recovery data).
+pub fn select_foreign_recent_generation_ids(
+    generations: &[Value],
+    exclude_client: &str,
+    boot_cutoff_ms: u64,
+) -> Vec<String> {
+    let foreign: Vec<&Value> = generations
+        .iter()
+        .filter(|g| g["clientInstanceId"].as_str() != Some(exclude_client))
+        .collect();
+    let mut oldest_by_client: HashMap<&str, u64> = HashMap::new();
+    let mut newest_by_client: HashMap<&str, u64> = HashMap::new();
+    for g in &foreign {
+        let c = g["clientInstanceId"].as_str().unwrap_or("");
+        let t = g["capturedAt"].as_u64().unwrap_or(0);
+        let o = oldest_by_client.entry(c).or_insert(u64::MAX);
+        if t < *o {
+            *o = t;
+        }
+        let e = newest_by_client.entry(c).or_insert(0);
+        if t > *e {
+            *e = t;
+        }
+    }
+    let pre_boot = |c: &str| oldest_by_client.get(c).copied().unwrap_or(u64::MAX) < boot_cutoff_ms;
+    let device_max = newest_by_client
+        .iter()
+        .filter(|(c, _)| pre_boot(c))
+        .map(|(_, t)| *t)
+        .max()
+        .unwrap_or(0);
+    foreign
+        .iter()
+        .filter(|g| {
+            let c = g["clientInstanceId"].as_str().unwrap_or("");
+            pre_boot(c)
+                && newest_by_client.get(c).copied().unwrap_or(0) + STALE_CLIENT_MS >= device_max
+        })
+        .filter_map(|g| g["generationId"].as_str().map(String::from))
+        .collect()
+}
+
+fn ref_key(provider: &str, session_id: &str) -> String {
+    format!("{provider}\u{1}{session_id}")
+}
+
+enum Verdict {
+    Bound(String, String),
+    Closed,
+    GcExpired,
+    Unknown,
+}
+
+/// Resolve a snapshot's sessionRef claim to its EFFECTIVE identity per D4 by
+/// walking the ledger's superseded chain (bounded — a cycle degrades to
+/// `GcExpired`, never loops).
+fn resolve(provider: &str, session_id: &str, by_key: &HashMap<String, &BindingRow>) -> Verdict {
+    let (mut p, mut s) = (provider.to_string(), session_id.to_string());
+    for _ in 0..10 {
+        match by_key.get(&ref_key(&p, &s)) {
+            None => {
+                return if (p.as_str(), s.as_str()) == (provider, session_id) {
+                    Verdict::Unknown
+                } else {
+                    Verdict::GcExpired
+                }
+            }
+            Some(row) if row_is_bound(row) => {
+                return Verdict::Bound(row_provider(row), row_session_id(row))
+            }
+            Some(row) => match row_successor(row) {
+                Some((np, ns)) => {
+                    p = np;
+                    s = ns;
+                }
+                None => {
+                    return if row_reason_is_closed(row) {
+                        Verdict::Closed
+                    } else {
+                        Verdict::GcExpired
+                    }
+                }
+            },
+        }
+    }
+    Verdict::GcExpired
+}
+
+pub fn build_inventory(
+    device_unions: Vec<DeviceUnion>,
+    bindings: Vec<BindingRow>,
+    live_session_keys: HashSet<(String, String)>,
+) -> Value {
+    let by_key: HashMap<String, &BindingRow> = bindings
+        .iter()
+        .map(|r| (ref_key(&row_provider(r), &row_session_id(r)), r))
+        .collect();
+    let is_live = |p: &str, s: &str| live_session_keys.contains(&(p.to_string(), s.to_string()));
+
+    // sort newest-first; primary device = greatest capturedAt with >=1 record
+    let mut unions = device_unions;
+    unions.sort_by_key(|d| std::cmp::Reverse(d.union_doc["capturedAt"].as_u64().unwrap_or(0)));
+
+    // Pass 1 - resolve EVERY pane in EVERY union (not just the primary): effective refs
+    // feed the cross-device ledgerOnly rule (A4) and the contentId substance (A5/A6);
+    // the primary union's tabs feed `device`.
+    let mut referenced: HashSet<String> = HashSet::new();
+    let mut substance: Vec<String> = Vec::new();
+    let mut tabs_per_union: Vec<Vec<Value>> = Vec::new();
+    for d in &unions {
+        let doc = &d.union_doc;
+        let device_id = doc["deviceId"].as_str().unwrap_or("").to_string();
+        let tabs: Vec<Value> = doc["records"]
+            .as_array()
+            .cloned()
+            .unwrap_or_default()
+            .iter()
+            .map(|rec| {
+                let panes: Vec<Value> = rec["panes"]
+                    .as_array()
+                    .cloned()
+                    .unwrap_or_default()
+                    .iter()
+                    .map(|pane| {
+                        let payload = &pane["payload"];
+                        let snap_ref = payload.get("sessionRef").filter(|v| !v.is_null()).cloned();
+                        let (ledger_state, eff_ref) = match &snap_ref {
+                            None => ("unknown", None),
+                            Some(r) => {
+                                let (p, s) = (
+                                    r["provider"].as_str().unwrap_or(""),
+                                    r["sessionId"].as_str().unwrap_or(""),
+                                );
+                                match resolve(p, s, &by_key) {
+                                    Verdict::Bound(bp, bs) => {
+                                        ("bound", Some(json!({"provider": bp, "sessionId": bs})))
+                                    }
+                                    Verdict::Closed => ("closed", None),
+                                    Verdict::GcExpired => ("gc_expired", Some(r.clone())),
+                                    Verdict::Unknown => ("unknown", Some(r.clone())),
+                                }
+                            }
+                        };
+                        let eff_str = eff_ref
+                            .as_ref()
+                            .map(|r| {
+                                format!(
+                                    "{}:{}",
+                                    r["provider"].as_str().unwrap_or(""),
+                                    r["sessionId"].as_str().unwrap_or("")
+                                )
+                            })
+                            .unwrap_or_else(|| "-".into());
+                        let live = eff_ref
+                            .as_ref()
+                            .map(|r| {
+                                is_live(
+                                    r["provider"].as_str().unwrap_or(""),
+                                    r["sessionId"].as_str().unwrap_or(""),
+                                )
+                            })
+                            .unwrap_or(false);
+                        if let Some(er) = &eff_ref {
+                            referenced.insert(ref_key(
+                                er["provider"].as_str().unwrap_or(""),
+                                er["sessionId"].as_str().unwrap_or(""),
+                            ));
+                        }
+                        // TIMESTAMP-FREE substance line: capturedAt/updatedAt deliberately absent (D3)
+                        substance.push(format!(
+                            "{}\u{1}{}\u{1}{}\u{1}{}\u{1}{}",
+                            device_id,
+                            rec["tabKey"].as_str().unwrap_or(""),
+                            pane["paneId"].as_str().unwrap_or(""),
+                            pane["kind"].as_str().unwrap_or(""),
+                            eff_str
+                        ));
+                        json!({
+                            "paneId": pane["paneId"], "kind": pane["kind"],
+                            "mode": payload.get("mode").cloned().unwrap_or(Value::Null),
+                            "shell": payload.get("shell").cloned().unwrap_or(Value::Null),
+                            "cwd": payload.get("initialCwd").cloned().unwrap_or(Value::Null),
+                            "payload": payload.clone(),
+                            "sessionRef": eff_ref.unwrap_or(Value::Null),
+                            "ledgerState": ledger_state,
+                            "live": live,
+                        })
+                    })
+                    .collect();
+                json!({"tabKey": rec["tabKey"], "tabName": rec["tabName"], "panes": panes})
+            })
+            .collect();
+        tabs_per_union.push(tabs);
+    }
+
+    let primary_idx = unions.iter().position(|d| {
+        d.union_doc["records"]
+            .as_array()
+            .map(|r| !r.is_empty())
+            .unwrap_or(false)
+    });
+
+    let device = primary_idx.map(|i| {
+        let doc = &unions[i].union_doc;
+        json!({"deviceId": doc["deviceId"], "deviceLabel": doc["deviceLabel"],
+               "capturedAt": doc["capturedAt"], "tabs": tabs_per_union[i].clone()})
+    });
+
+    let other_devices: Vec<Value> = unions
+        .iter()
+        .enumerate()
+        .filter(|(i, _)| Some(*i) != primary_idx)
+        .filter(|(_, d)| {
+            d.union_doc["records"]
+                .as_array()
+                .map(|r| !r.is_empty())
+                .unwrap_or(false)
+        })
+        .map(|(_, d)| {
+            let pane_count: u64 = d.union_doc["records"]
+                .as_array()
+                .unwrap()
+                .iter()
+                .map(|r| r["panes"].as_array().map(|p| p.len() as u64).unwrap_or(0))
+                .sum();
+            json!({"deviceId": d.union_doc["deviceId"], "deviceLabel": d.union_doc["deviceLabel"],
+                   "capturedAt": d.union_doc["capturedAt"], "paneCount": pane_count})
+        })
+        .collect();
+
+    let ledger_only: Vec<Value> = bindings
+        .iter()
+        .filter(|r| row_is_bound(r))
+        // vs effective refs across ALL unions (A4), not just the primary device
+        .filter(|r| !referenced.contains(&ref_key(&row_provider(r), &row_session_id(r))))
+        // live rows are excluded: sessions still running are never offered for resume (D7)
+        .filter(|r| !is_live(&row_provider(r), &row_session_id(r)))
+        .map(|r| {
+            json!({"provider": row_provider(r), "sessionId": row_session_id(r),
+                   "mode": row_mode(r), "cwd": row_cwd(r)})
+        })
+        .collect();
+
+    // contentId: sha256 over the sorted TIMESTAMP-FREE substance (A5/A6, D3)
+    substance.extend(ledger_only.iter().map(|e| {
+        format!(
+            "{}:{}",
+            e["provider"].as_str().unwrap_or(""),
+            e["sessionId"].as_str().unwrap_or("")
+        )
+    }));
+    substance.sort();
+    let content_id = digest16(&substance);
+
+    let recoverable = device.is_some() || !ledger_only.is_empty();
+    json!({"recoverable": recoverable, "contentId": content_id,
+           "device": device.unwrap_or(Value::Null),
+           "otherDevices": other_devices, "ledgerOnly": ledger_only})
+}
+
+// Thin accessors over the real `BindingRow` fields/enums
+// (`crates/freshell-ws/src/pane_ledger.rs:93`) — single field accesses, no logic.
+
+fn row_provider(r: &BindingRow) -> String {
+    r.provider.clone()
+}
+
+fn row_session_id(r: &BindingRow) -> String {
+    r.session_id.clone()
+}
+
+fn row_is_bound(r: &BindingRow) -> bool {
+    r.state == RowState::Bound
+}
+
+fn row_reason_is_closed(r: &BindingRow) -> bool {
+    r.retired_reason == Some(RetiredReason::Closed)
+}
+
+fn row_successor(r: &BindingRow) -> Option<(String, String)> {
+    r.superseded_by
+        .as_ref()
+        .map(|l| (l.provider.clone(), l.session_id.clone()))
+}
+
+fn row_mode(r: &BindingRow) -> String {
+    r.mode.clone()
+}
+
+fn row_cwd(r: &BindingRow) -> Option<String> {
+    r.cwd.clone()
+}
+
+/// The `contentId` digest: sha256 over the parts joined with `\u{1}`,
+/// hex-encoded, truncated to 16 chars (the tabs-persist digest convention,
+/// `crates/freshell-ws/src/tabs_persist.rs:82-87`, at half width).
+fn digest16(parts: &[String]) -> String {
+    use sha2::{Digest, Sha256};
+    let digest = Sha256::digest(parts.join("\u{1}").as_bytes());
+    digest[..8].iter().map(|b| format!("{b:02x}")).collect()
+}
+
+#[cfg(test)]
+#[path = "recovery_inventory_tests.rs"]
+mod tests;
diff --git a/crates/freshell-server/src/recovery_inventory_tests.rs b/crates/freshell-server/src/recovery_inventory_tests.rs
new file mode 100644
index 000000000..53e396639
--- /dev/null
+++ b/crates/freshell-server/src/recovery_inventory_tests.rs
@@ -0,0 +1,325 @@
+//! Tests for the pure recovery-inventory builder (B3/P1.9 Task 1).
+
+use super::*;
+use freshell_protocol::SessionLocator;
+use freshell_ws::pane_ledger::{BindingRow, RetiredReason, RowState, LEDGER_VERSION};
+use serde_json::json;
+use std::collections::HashSet;
+
+fn no_live() -> HashSet<(String, String)> {
+    HashSet::new()
+}
+
+fn live(pairs: &[(&str, &str)]) -> HashSet<(String, String)> {
+    pairs
+        .iter()
+        .map(|(p, s)| (p.to_string(), s.to_string()))
+        .collect()
+}
+
+fn union_doc(device: &str, captured_at: u64, panes: serde_json::Value) -> serde_json::Value {
+    json!({
+        "deviceId": device, "deviceLabel": format!("label-{device}"), "capturedAt": captured_at,
+        "records": [{ "tabKey": "k1", "tabId": "t1", "tabName": "work", "revision": 1,
+                      "updatedAt": captured_at, "paneCount": 1, "panes": panes }]
+    })
+}
+
+/// (state, retired_reason, superseded_by) parts for constructing a `BindingRow`.
+type StateParts = (RowState, Option<RetiredReason>, Option<SessionLocator>);
+
+fn bound() -> StateParts {
+    (RowState::Bound, None, None)
+}
+
+fn retired_closed() -> StateParts {
+    (RowState::Retired, Some(RetiredReason::Closed), None)
+}
+
+fn retired_gc_expired() -> StateParts {
+    (RowState::Retired, Some(RetiredReason::GcExpired), None)
+}
+
+fn retired_superseded_by(provider: &str, session_id: &str) -> StateParts {
+    (
+        RowState::Retired,
+        Some(RetiredReason::Superseded),
+        Some(SessionLocator {
+            provider: provider.to_string(),
+            session_id: session_id.to_string(),
+        }),
+    )
+}
+
+fn binding_row_at(
+    provider: &str,
+    session_id: &str,
+    state_parts: StateParts,
+    updated_at: i64,
+) -> BindingRow {
+    let (state, retired_reason, superseded_by) = state_parts;
+    BindingRow {
+        ledger_version: LEDGER_VERSION,
+        provider: provider.to_string(),
+        session_id: session_id.to_string(),
+        mode: provider.to_string(),
+        cwd: Some("/x".to_string()),
+        live_terminal_id: None,
+        create_request_id: None,
+        created_at: 1000,
+        updated_at,
+        last_observed_at: updated_at,
+        state,
+        retired_reason,
+        superseded_by,
+    }
+}
+
+fn binding_row(provider: &str, session_id: &str, state_parts: StateParts) -> BindingRow {
+    binding_row_at(provider, session_id, state_parts, 1000)
+}
+
+#[test]
+fn empty_inputs_not_recoverable() {
+    let out = build_inventory(vec![], vec![], no_live());
+    assert_eq!(out["recoverable"], false);
+    assert!(out["device"].is_null());
+    assert_eq!(out["ledgerOnly"].as_array().unwrap().len(), 0);
+}
+
+#[test]
+fn newest_device_wins_others_summarized() {
+    let old = DeviceUnion {
+        device_id: "dev0".into(),
+        union_doc: union_doc(
+            "dev0",
+            500,
+            json!([{ "paneId": "p0", "kind": "terminal", "payload": {"mode": "shell"} }]),
+        ),
+    };
+    let new = DeviceUnion {
+        device_id: "dev1".into(),
+        union_doc: union_doc(
+            "dev1",
+            1000,
+            json!([{ "paneId": "p1", "kind": "terminal", "payload": {"mode": "shell", "initialCwd": "/w"} }]),
+        ),
+    };
+    let out = build_inventory(vec![old, new], vec![], no_live());
+    assert_eq!(out["recoverable"], true);
+    assert_eq!(out["device"]["deviceId"], "dev1");
+    assert_eq!(out["device"]["tabs"][0]["panes"][0]["cwd"], "/w");
+    assert_eq!(out["device"]["tabs"][0]["panes"][0]["live"], false);
+    assert_eq!(out["otherDevices"][0]["deviceId"], "dev0");
+    assert_eq!(out["otherDevices"][0]["paneCount"], 1);
+}
+
+#[test]
+fn ledger_bound_row_overrides_snapshot_claim_via_superseded_chain() {
+    // snapshot says S1; ledger: S1 retired(superseded -> S2), S2 bound
+    let d = DeviceUnion {
+        device_id: "dev1".into(),
+        union_doc: union_doc(
+            "dev1",
+            1000,
+            json!([{ "paneId": "p1", "kind": "terminal",
+                     "payload": { "mode": "claude", "sessionRef": { "provider": "claude", "sessionId": "S1" } } }]),
+        ),
+    };
+    let bindings = vec![
+        binding_row("claude", "S1", retired_superseded_by("claude", "S2")),
+        binding_row("claude", "S2", bound()),
+    ];
+    let out = build_inventory(vec![d], bindings, no_live());
+    let pane = &out["device"]["tabs"][0]["panes"][0];
+    assert_eq!(pane["ledgerState"], "bound");
+    assert_eq!(pane["sessionRef"]["sessionId"], "S2"); // ledger identity beat the snapshot claim
+    assert_eq!(out["ledgerOnly"].as_array().unwrap().len(), 0); // S2 is referenced, not ledger-only
+}
+
+#[test]
+fn closed_row_strips_resume_gc_expired_keeps_snapshot_ref_unknown_passes_through() {
+    let d = DeviceUnion {
+        device_id: "dev1".into(),
+        union_doc: union_doc(
+            "dev1",
+            1000,
+            json!([
+                { "paneId": "p1", "kind": "terminal", "payload": { "mode": "claude", "sessionRef": { "provider": "claude", "sessionId": "CLOSED" } } },
+                { "paneId": "p2", "kind": "terminal", "payload": { "mode": "codex",  "sessionRef": { "provider": "codex",  "sessionId": "EXPIRED" } } },
+                { "paneId": "p3", "kind": "fresh-agent", "payload": { "sessionRef": { "provider": "freshclaude", "sessionId": "NOROW" } } }
+            ]),
+        ),
+    };
+    let bindings = vec![
+        binding_row("claude", "CLOSED", retired_closed()),
+        binding_row("codex", "EXPIRED", retired_gc_expired()),
+    ];
+    let out = build_inventory(vec![d], bindings, no_live());
+    let panes = out["device"]["tabs"][0]["panes"].as_array().unwrap();
+    assert_eq!(panes[0]["ledgerState"], "closed");
+    assert!(panes[0]["sessionRef"].is_null());
+    assert_eq!(panes[1]["ledgerState"], "gc_expired");
+    assert_eq!(panes[1]["sessionRef"]["sessionId"], "EXPIRED");
+    assert_eq!(panes[2]["ledgerState"], "unknown");
+    assert_eq!(panes[2]["sessionRef"]["sessionId"], "NOROW");
+}
+
+#[test]
+fn unreferenced_bound_rows_become_ledger_only() {
+    let out = build_inventory(vec![], vec![binding_row("codex", "C9", bound())], no_live());
+    assert_eq!(out["recoverable"], true);
+    assert_eq!(out["ledgerOnly"][0]["sessionId"], "C9");
+}
+
+#[test]
+fn bound_row_referenced_by_non_primary_device_is_not_ledger_only() {
+    // A4: a two-device steady state must not report the OTHER device's sessions as orphaned.
+    let newer = DeviceUnion {
+        device_id: "dev1".into(),
+        union_doc: union_doc(
+            "dev1",
+            1000,
+            json!([{ "paneId": "p1", "kind": "terminal", "payload": {"mode": "shell"} }]),
+        ),
+    };
+    let older = DeviceUnion {
+        device_id: "dev0".into(),
+        union_doc: union_doc(
+            "dev0",
+            500,
+            json!([{ "paneId": "p0", "kind": "terminal",
+                     "payload": { "mode": "codex", "sessionRef": { "provider": "codex", "sessionId": "C9" } } }]),
+        ),
+    };
+    let out = build_inventory(
+        vec![newer, older],
+        vec![binding_row("codex", "C9", bound())],
+        no_live(),
+    );
+    assert_eq!(out["device"]["deviceId"], "dev1"); // dev0 is NON-primary
+    assert_eq!(
+        out["ledgerOnly"].as_array().unwrap().len(),
+        0,
+        "C9 is referenced by dev0's union - not orphaned"
+    );
+}
+
+#[test]
+fn live_effective_ref_marks_pane_live_and_live_rows_never_ledger_only() {
+    // D7: pane resolves (via ledger chain) to S2, which a Running terminal owns;
+    // a second live bound row C9 is referenced by no pane.
+    let d = DeviceUnion {
+        device_id: "dev1".into(),
+        union_doc: union_doc(
+            "dev1",
+            1000,
+            json!([{ "paneId": "p1", "kind": "terminal",
+                     "payload": { "mode": "claude", "sessionRef": { "provider": "claude", "sessionId": "S1" } } }]),
+        ),
+    };
+    let bindings = vec![
+        binding_row("claude", "S1", retired_superseded_by("claude", "S2")),
+        binding_row("claude", "S2", bound()),
+        binding_row("codex", "C9", bound()),
+    ];
+    let out = build_inventory(
+        vec![d],
+        bindings,
+        live(&[("claude", "S2"), ("codex", "C9")]),
+    );
+    let pane = &out["device"]["tabs"][0]["panes"][0];
+    assert_eq!(pane["live"], true);
+    assert_eq!(pane["sessionRef"]["sessionId"], "S2"); // ref still reported; the CLIENT strips it (Task 4, D7)
+    assert_eq!(
+        out["ledgerOnly"].as_array().unwrap().len(),
+        0,
+        "live bound rows are excluded from ledgerOnly"
+    );
+}
+
+#[test]
+fn content_id_is_stable_and_input_sensitive() {
+    let a = build_inventory(vec![], vec![binding_row("codex", "C9", bound())], no_live());
+    let b = build_inventory(vec![], vec![binding_row("codex", "C9", bound())], no_live());
+    let c = build_inventory(vec![], vec![binding_row("codex", "C8", bound())], no_live());
+    assert_eq!(a["contentId"], b["contentId"]);
+    assert_ne!(a["contentId"], c["contentId"]);
+}
+
+#[test]
+fn content_id_ignores_timestamp_churn() {
+    // A5/A6: heartbeat re-pushes bump capturedAt/updatedAt every <=5 min - dismissal must survive.
+    let doc = |captured_at| {
+        union_doc(
+            "dev1",
+            captured_at,
+            json!([{ "paneId": "p1", "kind": "terminal", "payload": {"mode": "shell"} }]),
+        )
+    };
+    let a = build_inventory(
+        vec![DeviceUnion {
+            device_id: "dev1".into(),
+            union_doc: doc(1000),
+        }],
+        vec![binding_row_at("codex", "C9", bound(), 1000)],
+        no_live(),
+    );
+    let b = build_inventory(
+        vec![DeviceUnion {
+            device_id: "dev1".into(),
+            union_doc: doc(2000),
+        }],
+        vec![binding_row_at("codex", "C9", bound(), 2000)],
+        no_live(),
+    );
+    assert_eq!(
+        a["contentId"], b["contentId"],
+        "bumping only capturedAt/updatedAt must not change contentId"
+    );
+}
+
+#[test]
+fn stale_clients_generations_are_dropped() {
+    // A15: any client silent >15 min (heartbeat is 5 min) is closed or rotated - drop it.
+    let t_max: u64 = 100_000_000;
+    let gens = vec![
+        json!({"generationId": "gA", "clientInstanceId": "fresh", "capturedAt": t_max}),
+        json!({"generationId": "gB", "clientInstanceId": "fresh", "capturedAt": t_max - 60_000}),
+        json!({"generationId": "gC", "clientInstanceId": "stale", "capturedAt": t_max - 16 * 60 * 1000}),
+        json!({"generationId": "gD", "clientInstanceId": "me",    "capturedAt": t_max}),
+    ];
+    // boot cutoff AFTER every push: the A16 concurrent-client rule drops nothing here.
+    let ids = select_foreign_recent_generation_ids(&gens, "me", t_max + 1);
+    assert!(ids.contains(&"gA".to_string()) && ids.contains(&"gB".to_string()));
+    assert!(
+        !ids.contains(&"gC".to_string()),
+        "stale rotated client must not resurrect closed tabs"
+    );
+    assert!(
+        !ids.contains(&"gD".to_string()),
+        "requester's own generations are excluded"
+    );
+}
+
+#[test]
+fn concurrent_fresh_windows_generations_are_dropped() {
+    // A16/D2: a client whose ENTIRE retained history postdates the requester's boot is a
+    // concurrently-opened fresh window (junk auto shell tab) - it must never demote the
+    // genuinely lost device by winning primary-device selection.
+    let boot: u64 = 100_000_000;
+    let gens = vec![
+        json!({"generationId": "gJ1", "clientInstanceId": "sibling-window", "capturedAt": boot + 2_000}),
+        json!({"generationId": "gJ2", "clientInstanceId": "sibling-window", "capturedAt": boot + 300_000}),
+        json!({"generationId": "gR",  "clientInstanceId": "lost",           "capturedAt": boot - 30_000}),
+    ];
+    let ids = select_foreign_recent_generation_ids(&gens, "me", boot);
+    assert!(
+        ids.contains(&"gR".to_string()),
+        "pre-boot client is real lost data - kept"
+    );
+    assert!(
+        !ids.contains(&"gJ1".to_string()) && !ids.contains(&"gJ2".to_string()),
+        "post-boot-only client is a concurrent fresh window - dropped"
+    );
+}

From c01b0b226eae04c324df54ac1b77f4f754dc0d95 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:03:11 -0700
Subject: [PATCH 25/87] feat(sessions): CodexLocator skeleton - arm gates,
 fs-snapshot substrate, Enter-anchored resolve with pending-first-line grace

---
 crates/freshell-sessions/src/codex_locator.rs | 659 ++++++++++++++++++
 crates/freshell-sessions/src/lib.rs           |   1 +
 .../freshell-sessions/src/opencode_locator.rs |   2 +-
 3 files changed, 661 insertions(+), 1 deletion(-)
 create mode 100644 crates/freshell-sessions/src/codex_locator.rs

diff --git a/crates/freshell-sessions/src/codex_locator.rs b/crates/freshell-sessions/src/codex_locator.rs
new file mode 100644
index 000000000..ad84d7b04
--- /dev/null
+++ b/crates/freshell-sessions/src/codex_locator.rs
@@ -0,0 +1,659 @@
+//! Server-side codex terminal-pane session locator (Lane B2, campaign §2.3.2).
+//!
+//! Third sibling of `amplifier_locator` / `opencode_locator` (a
+//! provider-parameterized locator was explicitly rejected — the substrates
+//! share zero code). Substrate: codex persists ONE JSONL rollout file per
+//! session under a process-global sessions root
+//! (`<CODEX_HOME|~/.codex>/sessions/YYYY/MM/DD/rollout-<ts>-<threadId>.jsonl`,
+//! flat `<id>.jsonl` in tests). A new session is a NEW FILE — so the locator
+//! does a snapshot-diff of the file set, not a row-diff.
+//!
+//! Codex-behavior facts below are validated against codex source @
+//! rust-v0.145.0 and a 3,858-rollout corpus; a codex upgrade re-opens them.
+//!
+//! Deliberate deviations from the opencode locator, with rationale:
+//! - Windows are ENTER-ANCHORED ONLY — no spawn window. Real codex defers
+//!   rollout file creation until the first user prompt is recorded
+//!   (`RolloutRecorder` defers to `persist()`, materialized via
+//!   `ensure_rollout_materialized()`), so before the pane's first Enter every
+//!   new same-cwd rollout is by construction FOREIGN. `arm()` takes the
+//!   known-files snapshot immediately but schedules NO deadline until
+//!   `note_submit`.
+//! - NO `pre_epsilon_ms` and NO created-at time bound: filesystems have no
+//!   reliable cross-platform creation time (mtime moves on every append).
+//!   The `known_files` snapshot is the primary safety — a file
+//!   already present in the snapshot can never bind to this terminal. The FILENAME
+//!   timestamp and the dated `YYYY/MM/DD` dir are never used as filters
+//!   either: both are precomputed at codex session construction and can
+//!   predate on-disk creation by the entire user idle gap (the dir can even
+//!   be "yesterday" across midnight). The full-tree snapshot-diff sidesteps
+//!   both.
+//! - FIRST-SUBMIT re-snapshot (A4 hardening): the first `note_submit`
+//!   replaces `known_files` with a fresh scan — strictly safe because the
+//!   pane's own rollout cannot exist before its first Enter, so everything
+//!   that appeared between arm and the first Enter is foreign by
+//!   construction. SOUNDNESS PRECONDITION: the caller completes the first
+//!   `note_submit` BEFORE the Enter byte is written to the PTY (codex
+//!   materializes the rollout in response to that very Enter) — the
+//!   `codex_association` submit seam encodes this ordering. Later window
+//!   re-opens NEVER re-snapshot: a >2 s Enter→creation latency is recovered
+//!   by a later Enter only if the pane's own late file stays a candidate.
+//! - Attribution disambiguator: the rollout's own first-line
+//!   `session_meta.payload.cwd` is REQUIRED and must match the armed
+//!   terminal's cwd (`SessionMeta.cwd` is non-optional at 0.145.0;
+//!   3,858/3,858 real rollouts carry it — accepting a no-cwd line would be
+//!   pure foreign attack surface). `payload.cwd` is the codex process's
+//!   physical `getcwd` path recorded verbatim; equality holds because
+//!   `normalize_cwd` opportunistically canonicalizes the pane side — that
+//!   canonicalize is load-bearing for symlinked spawn dirs.
+//! - Pending first-line grace: codex CREATES the file, then awaits git-info
+//!   collection (subprocesses, 5 s timeout each, worst ~10 s) BEFORE writing
+//!   the `session_meta` line. A NEW file whose first line is empty/incomplete
+//!   is a PENDING candidate: re-probed each sweep up to
+//!   `PENDING_FIRST_LINE_GRACE_MS`, and while ANY pending candidate exists
+//!   this terminal binds NOTHING (bind-blocking — a readable foreign file
+//!   must not win while the pane's own file sits in its git-info gap).
+//!   Enter→creation latency beyond the 2 s window is mitigated by this grace
+//!   plus window re-open on a later Enter.
+//! - Contested-cwd refusal is CROSS-TICK: while ≥2 armed terminals share a
+//!   normalized cwd, no candidate with that cwd binds for any of them.
+//! - Ownership is proven ONLY by `payload.id` on line 1 — NEVER the filename
+//!   (prefilter-grade at best), NEVER `payload.session_id` (fork/resume
+//!   LINEAGE: matches a FOREIGN session in 54/144 sampled real rollouts) —
+//!   same predicate as `freshell-ws`'s `first_line_owns`.
+//! - Resumed codex sessions append to their EXISTING rollout file (no new
+//!   file) — consistent with the arm gate refusing resume panes. Compressed
+//!   artifacts (`.jsonl.zst`, present in 0.145.0 source) fail the `.jsonl`
+//!   suffix filter; fresh sessions always write plain `.jsonl`.
+//!
+//! Zero cost when idle: scans happen only at arm, at the FIRST `note_submit`
+//! (the re-snapshot), and at due Enter-anchored
+//! evaluations (a pending candidate keeps its evaluation due, so re-probes
+//! ride the same gate), proven by `fs_scan_count`. Callers run `arm()`,
+//! `note_submit()`, and `tick()` inside `tokio::task::spawn_blocking` (cold
+//! dentry cache is the one unmeasured tail — A6).
+
+use std::collections::{HashMap, HashSet};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Mutex;
+
+use crate::opencode_locator::normalize_cwd;
+
+/// Correlation window after a submit (Enter-anchored deadline). There is NO
+/// spawn-anchored window: real codex (0.145.0) creates the rollout file only
+/// when the first user prompt is recorded, so before the pane's first Enter
+/// every new same-cwd rollout is by construction foreign.
+pub const CODEX_WINDOW_MS: i64 = 2_000;
+
+/// Bounded re-probe grace for a NEW file whose first line is not yet
+/// readable: codex creates the file, then awaits git-info collection
+/// (subprocesses, 5 s timeout each, worst ~10 s) before writing the
+/// `session_meta` line. Matches codex's worst case and the magnitude of the
+/// existing `IDENTITY_RESOLUTION_GRACE_MS`.
+pub const PENDING_FIRST_LINE_GRACE_MS: i64 = 10_000;
+
+/// Bounded first-line read cap — real rollouts reach 152 MB; observed real
+/// first lines are ≤ 22.4 KB. Mirrors `codex_reconcile.rs`.
+const MAX_FIRST_LINE_BYTES: u64 = 1024 * 1024;
+
+/// Bounded walk depth — `sessions/YYYY/MM/DD/` is depth 3; 5 mirrors
+/// `locate_codex_rollout`.
+const MAX_WALK_DEPTH: u8 = 5;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Located {
+    pub terminal_id: String,
+    pub thread_id: String,
+    pub rollout_path: PathBuf,
+    pub cwd: String,
+}
+
+#[derive(Debug, Clone)]
+struct Armed {
+    cwd_normalized: String,
+    known_files: HashSet<PathBuf>,
+    enter_ms: Option<i64>,
+    resolved: bool,
+    /// NEW files whose first line was empty/incomplete when probed, keyed to
+    /// first-seen ms. While any un-expired entry exists, this terminal binds
+    /// NOTHING (bind-blocking); entries older than
+    /// `PENDING_FIRST_LINE_GRACE_MS` are merged into `known_files`
+    /// (permanently excluded — fail toward refusal).
+    pending_first_line: HashMap<PathBuf, i64>,
+}
+
+#[derive(Default)]
+struct Inner {
+    armed: HashMap<String, Armed>,
+}
+
+pub struct CodexLocator {
+    sessions_root: PathBuf,
+    window_ms: i64,
+    inner: Mutex<Inner>,
+    fs_scan_count: AtomicU64,
+}
+
+impl CodexLocator {
+    pub fn new(sessions_root: PathBuf) -> Self {
+        Self::with_config(sessions_root, CODEX_WINDOW_MS)
+    }
+
+    pub fn with_config(sessions_root: PathBuf, window_ms: i64) -> Self {
+        Self {
+            sessions_root,
+            window_ms,
+            inner: Mutex::new(Inner::default()),
+            fs_scan_count: AtomicU64::new(0),
+        }
+    }
+
+    pub fn armed_count(&self) -> usize {
+        self.inner.lock().unwrap().armed.len()
+    }
+
+    pub fn fs_scan_count(&self) -> u64 {
+        self.fs_scan_count.load(Ordering::SeqCst)
+    }
+
+    /// Admission rules (mirrors `OpencodeLocator::arm`): codex mode, running,
+    /// NO resume id (the only already-bound gate — never a restore flag, so
+    /// restore-created identity-less panes re-arm for free), non-empty cwd,
+    /// not already armed. On success takes the arm-time known-files snapshot.
+    /// Arming schedules NO deadline — windows open only on `note_submit`
+    /// (Enter-anchored; see module doc).
+    pub fn arm(
+        &self,
+        terminal_id: &str,
+        mode: &str,
+        status_running: bool,
+        resume_session_id: Option<&str>,
+        cwd: Option<&str>,
+    ) -> bool {
+        if mode != "codex" || !status_running || resume_session_id.is_some() {
+            return false;
+        }
+        let Some(cwd) = cwd.filter(|c| !c.is_empty()) else {
+            return false;
+        };
+        let mut inner = self.inner.lock().unwrap();
+        if inner.armed.contains_key(terminal_id) {
+            return false;
+        }
+        let known_files = self.scan_rollout_files();
+        inner.armed.insert(
+            terminal_id.to_string(),
+            Armed {
+                cwd_normalized: normalize_cwd(cwd),
+                known_files,
+                enter_ms: None,
+                resolved: false,
+                pending_first_line: HashMap::new(),
+            },
+        );
+        true
+    }
+
+    pub fn disarm(&self, terminal_id: &str) {
+        self.inner.lock().unwrap().armed.remove(terminal_id);
+    }
+
+    /// The FIRST submit is what opens a window at all (windows are
+    /// Enter-anchored — arm schedules no deadline), and it RE-SNAPSHOTS
+    /// `known_files` (see module doc: strictly safe because the pane's own
+    /// rollout cannot exist before its first Enter; the caller must complete
+    /// this call BEFORE the Enter byte reaches the PTY, and must run it on
+    /// the blocking pool — the re-snapshot walks the sessions tree).
+    /// Re-open semantics mirror
+    /// opencode: a mid-turn Enter never re-opens a still-pending evaluation;
+    /// a resolved (zero-candidate / ambiguous / contested) terminal gets a
+    /// fresh Enter-anchored deadline. Re-opens NEVER re-snapshot.
+    pub fn note_submit(&self, terminal_id: &str, at_ms: i64) -> bool {
+        let mut inner = self.inner.lock().unwrap();
+        let Some(armed) = inner.armed.get_mut(terminal_id) else {
+            return false;
+        };
+        if !armed.resolved && armed.enter_ms.is_some() {
+            return false;
+        }
+        if armed.enter_ms.is_none() {
+            // FIRST submit: everything that appeared between arm and this
+            // Enter is foreign by construction (A1/A4) — replace the
+            // snapshot. Holding the lock across the scan is deliberate and
+            // bounded (warm walks are 7-9 ms — A6; callers are on the
+            // blocking pool); it also keeps the re-snapshot atomic with the
+            // window open.
+            armed.known_files = self.scan_rollout_files();
+        }
+        armed.enter_ms = Some(at_ms);
+        armed.resolved = false;
+        true
+    }
+
+    /// A terminal is due only when an Enter-anchored deadline exists and has
+    /// passed. No submit -> no window -> never evaluated (see module doc).
+    fn due(&self, armed: &Armed, now_ms: i64) -> bool {
+        matches!(armed.enter_ms, Some(enter_ms) if !armed.resolved && now_ms >= enter_ms + self.window_ms)
+    }
+
+    /// Evaluation at (or after) an Enter-anchored deadline. Outcomes:
+    /// - any NEW file with an empty/incomplete first line (codex's
+    ///   create→session_meta git-info gap) → PENDING: bind NOTHING for this
+    ///   terminal, stay unresolved, re-probe each sweep up to
+    ///   `PENDING_FIRST_LINE_GRACE_MS` (grace-expired files are permanently
+    ///   excluded);
+    /// - 0 candidates → keep watching (stays armed, `resolved = true`);
+    /// - 2+ candidates for one terminal → WARN + refuse (never guess);
+    /// - exactly one candidate but ≥2 ARMED terminals share this cwd → WARN +
+    ///   refuse (contested cwd — cross-tick, so staggered deadlines can't
+    ///   grab a sibling's rollout uncontested);
+    /// - one candidate claimed by ≥2 terminals in the same tick → WARN +
+    ///   refuse ALL claimants (defense-in-depth behind the cwd census);
+    /// - exactly one clean match → emit `Located` and disarm. `tick()` drains.
+    pub fn tick(&self, now_ms: i64) -> Vec<Located> {
+        {
+            let inner = self.inner.lock().unwrap();
+            if inner.armed.is_empty() {
+                return Vec::new();
+            }
+            if !inner.armed.values().any(|a| self.due(a, now_ms)) {
+                return Vec::new();
+            }
+        }
+        let current = self.scan_rollout_files();
+        let mut inner = self.inner.lock().unwrap();
+
+        // Cross-tick contested-cwd census over ALL armed terminals (not just
+        // the due ones): two armed same-cwd panes are indistinguishable on
+        // this substrate, whatever their deadlines.
+        let mut cwd_counts: HashMap<String, usize> = HashMap::new();
+        for a in inner.armed.values() {
+            *cwd_counts.entry(a.cwd_normalized.clone()).or_insert(0) += 1;
+        }
+
+        // Pass 1: per-terminal candidate evaluation.
+        let mut claims: Vec<(String, Located)> = Vec::new();
+        for (terminal_id, armed) in inner.armed.iter_mut() {
+            if !matches!(armed.enter_ms, Some(e) if !armed.resolved && now_ms >= e + self.window_ms)
+            {
+                continue;
+            }
+            let new_paths: Vec<PathBuf> = current.difference(&armed.known_files).cloned().collect();
+            let mut matches: Vec<(PathBuf, RolloutMeta)> = Vec::new();
+            let mut pending_blocking = false;
+            for path in new_paths {
+                match probe_rollout(&path) {
+                    Probe::Candidate(meta) => {
+                        armed.pending_first_line.remove(&path);
+                        if normalize_cwd(&meta.cwd) == armed.cwd_normalized {
+                            matches.push((path, meta));
+                        }
+                    }
+                    Probe::NotYet => {
+                        let first_seen = *armed
+                            .pending_first_line
+                            .entry(path.clone())
+                            .or_insert(now_ms);
+                        if now_ms - first_seen >= PENDING_FIRST_LINE_GRACE_MS {
+                            // Grace exhausted: permanently excluded (fail
+                            // toward refusal — A4 hardening 1).
+                            armed.pending_first_line.remove(&path);
+                            armed.known_files.insert(path);
+                        } else {
+                            pending_blocking = true;
+                        }
+                    }
+                    Probe::Never => {}
+                }
+            }
+            if pending_blocking {
+                // A new file is still inside codex's create→session_meta gap
+                // (git-info collection, worst ~10 s). It may be THIS pane's
+                // rollout — binding any other candidate now could hand the
+                // window to a foreign file while the true owner is unreadable.
+                // Bind nothing, stay unresolved, re-probe next sweep.
+                tracing::debug!(
+                    terminal_id = %terminal_id,
+                    "codex_locator_pending: new rollout first line not yet readable; deferring evaluation"
+                );
+                continue;
+            }
+            armed.resolved = true;
+            match matches.len() {
+                0 => {} // keep watching
+                1 => {
+                    if cwd_counts.get(&armed.cwd_normalized).copied().unwrap_or(0) >= 2 {
+                        tracing::warn!(
+                            terminal_id = %terminal_id,
+                            "codex_locator_contested_cwd: >=2 armed terminals share this cwd; refusing to bind"
+                        );
+                    } else {
+                        let (path, meta) = matches.remove(0);
+                        claims.push((
+                            terminal_id.clone(),
+                            Located {
+                                terminal_id: terminal_id.clone(),
+                                thread_id: meta.thread_id,
+                                rollout_path: path,
+                                cwd: armed.cwd_normalized.clone(),
+                            },
+                        ));
+                    }
+                }
+                n => {
+                    tracing::warn!(
+                        terminal_id = %terminal_id,
+                        candidates = n,
+                        "codex_locator_ambiguous: multiple new rollouts in one window; refusing to bind"
+                    );
+                }
+            }
+        }
+
+        // Pass 2: same-tick cross-terminal conflict — the same rollout (or
+        // thread id) claimed by two armed terminals in one tick is
+        // unattributable. (Defense-in-depth: the contested-cwd census above
+        // already refuses same-cwd claimants across ticks.)
+        let mut located = Vec::new();
+        for (terminal_id, candidate) in &claims {
+            let contested = claims.iter().any(|(other_tid, other)| {
+                other_tid != terminal_id
+                    && (other.rollout_path == candidate.rollout_path
+                        || other.thread_id == candidate.thread_id)
+            });
+            if contested {
+                tracing::warn!(
+                    terminal_id = %terminal_id,
+                    thread_id = %candidate.thread_id,
+                    "codex_locator_contested: rollout claimed by multiple armed terminals; refusing to bind"
+                );
+                continue;
+            }
+            located.push(candidate.clone());
+        }
+        for l in &located {
+            inner.armed.remove(&l.terminal_id);
+        }
+        located
+    }
+
+    fn scan_rollout_files(&self) -> HashSet<PathBuf> {
+        self.fs_scan_count.fetch_add(1, Ordering::SeqCst);
+        fn walk(dir: &Path, depth: u8, out: &mut HashSet<PathBuf>) {
+            if depth > MAX_WALK_DEPTH {
+                return;
+            }
+            let Ok(entries) = std::fs::read_dir(dir) else {
+                return; // missing/corrupt root tolerated, never a panic
+            };
+            for entry in entries.flatten() {
+                let path = entry.path();
+                if path.is_dir() {
+                    walk(&path, depth + 1, out);
+                } else if path
+                    .file_name()
+                    .and_then(|n| n.to_str())
+                    .map(|n| n.ends_with(".jsonl"))
+                    .unwrap_or(false)
+                {
+                    out.insert(path);
+                }
+            }
+        }
+        let mut out = HashSet::new();
+        walk(&self.sessions_root, 0, &mut out);
+        out
+    }
+}
+
+struct RolloutMeta {
+    thread_id: String,
+    /// REQUIRED — `SessionMeta.cwd` is non-optional at codex 0.145.0
+    /// (3,858/3,858 real rollouts carry it); a no-cwd first line is a
+    /// foreign shape, never a candidate (A4 hardening).
+    cwd: String,
+}
+
+/// Tri-state probe result. The distinction between `NotYet` and `Never` is
+/// load-bearing: codex writes the whole session_meta line + '\n' in one
+/// write-then-flush, so a COMPLETE (newline-terminated) line that fails the
+/// candidate shape will never become one, while an empty file or a line
+/// without its trailing newline is codex's create→meta gap (or a raced
+/// write) — "not yet", not "never" (A3, validated).
+enum Probe {
+    /// Parseable `session_meta` with a bare-UUID `payload.id` AND a
+    /// `payload.cwd` — a real candidate shape.
+    Candidate(RolloutMeta),
+    /// Empty file, transient open/read failure, or first line still missing
+    /// its trailing newline — re-probe within the pending grace.
+    NotYet,
+    /// Complete first line that is not a codex session_meta candidate
+    /// (non-JSON, wrong type, non-UUID id, missing cwd, oversized) — never
+    /// a candidate; the locator stays silent on foreign files.
+    Never,
+}
+
+/// Identity probe: bounded first-line read (see `Probe` for the tri-state
+/// semantics).
+fn probe_rollout(path: &Path) -> Probe {
+    use std::io::{BufRead, Read};
+    let Ok(file) = std::fs::File::open(path) else {
+        return Probe::NotYet;
+    };
+    let mut reader = std::io::BufReader::new(file).take(MAX_FIRST_LINE_BYTES);
+    let mut first_line = Vec::new();
+    if reader.read_until(b'\n', &mut first_line).is_err() {
+        return Probe::NotYet;
+    }
+    if first_line.len() as u64 >= MAX_FIRST_LINE_BYTES && !first_line.ends_with(b"\n") {
+        return Probe::Never; // oversized: will never fit the cap
+    }
+    if first_line.is_empty() || !first_line.ends_with(b"\n") {
+        return Probe::NotYet; // create→meta gap, or a raced partial write
+    }
+    let Ok(record) = serde_json::from_slice::<serde_json::Value>(&first_line) else {
+        return Probe::Never;
+    };
+    if record.get("type").and_then(|v| v.as_str()) != Some("session_meta") {
+        return Probe::Never;
+    }
+    let Some(thread_id) = record.pointer("/payload/id").and_then(|v| v.as_str()) else {
+        return Probe::Never;
+    };
+    if !is_uuid_shaped(thread_id) {
+        return Probe::Never;
+    }
+    let Some(cwd) = record.pointer("/payload/cwd").and_then(|v| v.as_str()) else {
+        return Probe::Never; // cwd REQUIRED (A4 hardening)
+    };
+    Probe::Candidate(RolloutMeta {
+        thread_id: thread_id.to_string(),
+        cwd: cwd.to_string(),
+    })
+}
+
+/// Bare hyphenated 36-char UUID shape gate (deliberate small duplicate of
+/// `freshell-ws`'s predicate — this crate sits below it in the dep graph).
+fn is_uuid_shaped(s: &str) -> bool {
+    let bytes = s.as_bytes();
+    if bytes.len() != 36 {
+        return false;
+    }
+    for (i, b) in bytes.iter().enumerate() {
+        let is_hyphen_pos = matches!(i, 8 | 13 | 18 | 23);
+        if is_hyphen_pos {
+            if *b != b'-' {
+                return false;
+            }
+        } else if !b.is_ascii_hexdigit() {
+            return false;
+        }
+    }
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::{Path, PathBuf};
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    static TEST_DIR_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+    /// Same convention as opencode_locator.rs tests: no tempfile crate.
+    fn unique_temp_dir(label: &str) -> PathBuf {
+        let n = TEST_DIR_COUNTER.fetch_add(1, Ordering::SeqCst);
+        let dir = std::env::temp_dir().join(format!(
+            "freshell-codex-locator-test-{label}-{}-{n}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&dir).expect("create test dir");
+        dir
+    }
+
+    /// Write a rollout file whose FIRST line is the session_meta identity
+    /// record, exactly the shape the real codex CLI writes
+    /// (payload.id = identity; payload.cwd = the session's working dir).
+    fn write_rollout(root: &Path, rel_dir: &str, thread_id: &str, cwd: Option<&str>) -> PathBuf {
+        let dir = root.join(rel_dir);
+        std::fs::create_dir_all(&dir).expect("create rollout dir");
+        let file = dir.join(format!("rollout-2026-07-26T08-00-00-{thread_id}.jsonl"));
+        let payload = match cwd {
+            Some(c) => format!(r#"{{"id":"{thread_id}","cwd":"{c}"}}"#),
+            None => format!(r#"{{"id":"{thread_id}"}}"#),
+        };
+        let line = format!(
+            r#"{{"timestamp":"2026-07-26T08:00:00.000Z","type":"session_meta","payload":{payload}}}"#
+        );
+        std::fs::write(&file, format!("{line}\n")).expect("write rollout");
+        file
+    }
+
+    const TID: &str = "11111111-2222-3333-4444-555555555555";
+
+    #[test]
+    fn fresh_rollout_after_first_enter_resolves_via_enter_window() {
+        let root = unique_temp_dir("enter-happy");
+        let cwd = root.join("project");
+        std::fs::create_dir_all(&cwd).unwrap();
+        let cwd_s = cwd.to_string_lossy().to_string();
+        let locator = CodexLocator::new(root.clone());
+
+        assert!(locator.arm("t1", "codex", true, None, Some(&cwd_s)));
+        // No submit yet -> no deadline exists; nothing to evaluate.
+        assert!(locator.tick(10_000).is_empty());
+        // Enter at 20_000; the rollout appears AFTER the submit (real codex
+        // materializes the file only when the first user prompt is recorded).
+        assert!(locator.note_submit("t1", 20_000));
+        let path = write_rollout(&root, "2026/07/26", TID, Some(&cwd_s));
+
+        // Before the Enter-anchored deadline: nothing yet.
+        assert!(locator.tick(20_000 + CODEX_WINDOW_MS - 1).is_empty());
+        let located = locator.tick(20_000 + CODEX_WINDOW_MS);
+        assert_eq!(
+            located,
+            vec![Located {
+                terminal_id: "t1".into(),
+                thread_id: TID.into(),
+                rollout_path: path,
+                cwd: crate::opencode_locator::normalize_cwd(&cwd_s),
+            }]
+        );
+        // Success fully resolves and disarms; tick() drains.
+        assert_eq!(locator.armed_count(), 0);
+        assert!(locator.tick(20_000 + CODEX_WINDOW_MS + 1).is_empty());
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn rollout_after_arm_without_submit_is_never_bound_and_never_scanned() {
+        // A1 (validated): real codex creates the rollout ONLY at the first
+        // user prompt, so before Enter every new same-cwd rollout is by
+        // construction FOREIGN. With no submit there is NO window: the file
+        // must never bind and no deadline scans may run.
+        let root = unique_temp_dir("no-submit");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert_eq!(locator.fs_scan_count(), 1); // the arm snapshot
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert!(locator.tick(100 * CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        assert_eq!(locator.fs_scan_count(), 1); // still only the arm snapshot
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn rollout_created_between_arm_and_first_enter_never_binds() {
+        // A4 hardening (first-submit re-snapshot): Premise 7 guarantees the
+        // pane's own rollout cannot exist before its first Enter, so EVERY
+        // file that appears between arm and the first submit is foreign by
+        // construction (freshagent sidecar, `codex exec`, codex outside
+        // freshell in the same cwd). The FIRST note_submit re-snapshots
+        // known_files, so a bare Enter (empty composer, trust dialog) can
+        // never hand the window to that foreign file as a sole candidate.
+        let root = unique_temp_dir("resnapshot");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        // Foreign rollout lands AFTER arm but BEFORE the first Enter.
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.note_submit("t1", 1_000)); // first submit re-snapshots
+        assert_eq!(locator.fs_scan_count(), 2); // arm + first-submit scans
+        assert!(locator.tick(1_000 + CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1); // zero candidates → keep watching
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn arm_admission_gates() {
+        let root = unique_temp_dir("gates");
+        let locator = CodexLocator::new(root.clone());
+        // wrong mode
+        assert!(!locator.arm("t1", "opencode", true, None, Some("/tmp")));
+        // not running
+        assert!(!locator.arm("t1", "codex", false, None, Some("/tmp")));
+        // resume id present — the ONLY already-bound gate (no restore flag)
+        assert!(!locator.arm("t1", "codex", true, Some(TID), Some("/tmp")));
+        // missing / empty cwd
+        assert!(!locator.arm("t1", "codex", true, None, None));
+        assert!(!locator.arm("t1", "codex", true, None, Some("")));
+        // happy arm, then idempotent re-arm returns false
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(!locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn disarmed_terminal_never_resolves() {
+        let root = unique_temp_dir("disarm");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        locator.disarm("t1");
+        assert!(locator.tick(CODEX_WINDOW_MS + 1).is_empty());
+        assert_eq!(locator.armed_count(), 0);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn tick_while_unarmed_performs_zero_fs_scans() {
+        let root = unique_temp_dir("idle");
+        let locator = CodexLocator::new(root.clone());
+        // Construction must not scan eagerly either.
+        assert_eq!(locator.fs_scan_count(), 0);
+        assert!(locator.tick(10_000).is_empty());
+        assert_eq!(locator.fs_scan_count(), 0);
+        // Arming scans once (the known-files snapshot)…
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert_eq!(locator.fs_scan_count(), 1);
+        // …and a tick BEFORE any Enter-anchored deadline is due (here: no
+        // submit at all, so no deadline exists) still scans nothing.
+        let before = locator.fs_scan_count();
+        assert!(locator.tick(1).is_empty());
+        assert_eq!(locator.fs_scan_count(), before);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+}
diff --git a/crates/freshell-sessions/src/lib.rs b/crates/freshell-sessions/src/lib.rs
index ac5636ecb..ced48df3a 100644
--- a/crates/freshell-sessions/src/lib.rs
+++ b/crates/freshell-sessions/src/lib.rs
@@ -16,6 +16,7 @@
 
 pub mod amplifier;
 pub mod amplifier_locator;
+pub mod codex_locator;
 pub mod directory_index;
 pub mod indexer;
 pub mod meta;
diff --git a/crates/freshell-sessions/src/opencode_locator.rs b/crates/freshell-sessions/src/opencode_locator.rs
index c31aef0f9..ec30bd32b 100644
--- a/crates/freshell-sessions/src/opencode_locator.rs
+++ b/crates/freshell-sessions/src/opencode_locator.rs
@@ -366,7 +366,7 @@ impl OpencodeLocator {
 /// Lexical cwd normalization (mirrors `amplifier_locator::normalize_cwd`):
 /// trailing-slash / separator only — no realpath; `std::fs::canonicalize` is
 /// used opportunistically where the path exists.
-fn normalize_cwd(input: &str) -> String {
+pub(crate) fn normalize_cwd(input: &str) -> String {
     if let Ok(real) = std::fs::canonicalize(input) {
         return real.to_string_lossy().into_owned();
     }

From 5745022d791fd916bb7ccfe9909eee000d84d3cc Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:10:44 -0700
Subject: [PATCH 26/87] feat(ledger): resume-invocation record fields +
 fresh-agent binding upsert (P1.13)

---
 crates/freshell-ws/src/pane_ledger.rs       | 112 +++++++++++
 crates/freshell-ws/src/pane_ledger_tests.rs | 194 ++++++++++++++++++++
 2 files changed, 306 insertions(+)

diff --git a/crates/freshell-ws/src/pane_ledger.rs b/crates/freshell-ws/src/pane_ledger.rs
index ca940f1c4..dc0e2be1b 100644
--- a/crates/freshell-ws/src/pane_ledger.rs
+++ b/crates/freshell-ws/src/pane_ledger.rs
@@ -112,6 +112,20 @@ pub struct BindingRow {
     pub retired_reason: Option<RetiredReason>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub superseded_by: Option<SessionLocator>,
+    /// "fresh-agent" for fresh-agent rows (P1.13); absent on terminal rows.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pane_kind: Option<String>,
+    /// Resume-invocation record (campaign plan §4.2): exactly what the
+    /// provider-native resume command needs. Updated when the user changes
+    /// them. All optional under LEDGER_VERSION 1 — no version bump.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sandbox: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub permission_mode: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub effort: Option<String>,
 }
 
 /// Evidence that identity establishment was in flight (G1: never a binding).
@@ -137,6 +151,27 @@ pub struct BindingWrite<'a> {
     pub now_ms: i64,
 }
 
+/// One fresh-agent identity event's worth of binding-row input (P1.13).
+/// Settings are a FULL snapshot: callers always know the current values,
+/// so writes replace rather than merge.
+#[derive(Debug, Clone, Copy)]
+pub struct FreshAgentBindingWrite<'a> {
+    pub provider: &'a str,
+    pub session_id: &'a str,
+    pub mode: &'a str,
+    pub cwd: Option<&'a str>,
+    pub create_request_id: Option<&'a str>,
+    pub model: Option<&'a str>,
+    pub sandbox: Option<&'a str>,
+    pub permission_mode: Option<&'a str>,
+    pub effort: Option<&'a str>,
+    /// G3 supersession (V8/A14): the OLD session id this binding replaces
+    /// (codex crash-respawn). When `Some`, the old `(provider, supersedes)`
+    /// row is retired and linked AFTER the new row persists.
+    pub supersedes: Option<&'a str>,
+    pub now_ms: i64,
+}
+
 /// A chain-terminus lookup result. `corrected == true` means the caller's
 /// claimed ref was superseded and this row is the live successor.
 #[derive(Debug, Clone)]
@@ -366,6 +401,11 @@ impl PaneLedger {
             state: RowState::Bound,
             retired_reason: None,
             superseded_by: None,
+            pane_kind: None,
+            model: None,
+            sandbox: None,
+            permission_mode: None,
+            effort: None,
         };
         self.write_binding(root, index, &row)?; // new bound row FIRST (pinned)
 
@@ -389,6 +429,78 @@ impl PaneLedger {
         Ok(())
     }
 
+    /// Record (or refresh) a `bound` row for a fresh-agent identity event
+    /// (P1.13). Upsert keyed `(provider, session_id)`: settings are a FULL
+    /// snapshot (replace, not merge); `created_at` is preserved on rewrite.
+    /// When `w.supersedes` names a different old session id, the old row is
+    /// retired and linked AFTER the new bound row persists (G3 order pinned,
+    /// V8/A14) — a missing old row is a silent no-op.
+    pub fn record_fresh_agent_binding(
+        &self,
+        w: &FreshAgentBindingWrite<'_>,
+    ) -> std::io::Result<()> {
+        let Some(root) = &self.root else {
+            return Ok(());
+        };
+        let mut index = self.guard();
+
+        let key = (w.provider.to_string(), w.session_id.to_string());
+        let existing = index.bindings.get(&key);
+        let created_at = existing.map(|r| r.created_at).unwrap_or(w.now_ms);
+        // Advisory field: keep the existing row's value when the new write
+        // has none (latest-observed semantics, D4).
+        let create_request_id = w
+            .create_request_id
+            .map(str::to_string)
+            .or_else(|| existing.and_then(|r| r.create_request_id.clone()));
+        let row = BindingRow {
+            ledger_version: LEDGER_VERSION,
+            provider: w.provider.to_string(),
+            session_id: w.session_id.to_string(),
+            mode: w.mode.to_string(),
+            cwd: w.cwd.map(str::to_string),
+            live_terminal_id: None, // fresh-agent panes have no terminal
+            create_request_id,
+            created_at,
+            updated_at: w.now_ms,
+            last_observed_at: w.now_ms,
+            state: RowState::Bound,
+            retired_reason: None,
+            superseded_by: None,
+            pane_kind: Some("fresh-agent".into()),
+            model: w.model.map(str::to_string),
+            sandbox: w.sandbox.map(str::to_string),
+            permission_mode: w.permission_mode.map(str::to_string),
+            effort: w.effort.map(str::to_string),
+        };
+        self.write_binding(root, &mut index, &row)?; // new bound row FIRST (pinned)
+
+        if let Some(old_id) = w.supersedes {
+            if old_id != w.session_id {
+                let old_key = (w.provider.to_string(), old_id.to_string());
+                if let Some(mut old) = index.bindings.get(&old_key).cloned() {
+                    old.state = RowState::Retired;
+                    old.retired_reason = Some(RetiredReason::Superseded);
+                    old.superseded_by = Some(SessionLocator {
+                        provider: w.provider.to_string(),
+                        session_id: w.session_id.to_string(),
+                    });
+                    old.updated_at = w.now_ms;
+                    tracing::info!(
+                        target: "freshell_ws::pane_ledger",
+                        old_session_id = %old_id,
+                        new_session_id = %w.session_id,
+                        "pane_ledger_superseded: fresh-agent binding moved; \
+                         old row retired, never defended"
+                    );
+                    self.write_binding(root, &mut index, &old)?; // THEN retire the old
+                }
+                // Missing old row: silent no-op.
+            }
+        }
+        Ok(())
+    }
+
     /// One row: durable file FIRST, then the write-through index — in the
     /// same locked section, so readers never see index-ahead-of-disk.
     fn write_binding(
diff --git a/crates/freshell-ws/src/pane_ledger_tests.rs b/crates/freshell-ws/src/pane_ledger_tests.rs
index 1b48311b5..b4cbfb4f9 100644
--- a/crates/freshell-ws/src/pane_ledger_tests.rs
+++ b/crates/freshell-ws/src/pane_ledger_tests.rs
@@ -545,6 +545,11 @@ fn crash_mid_supersession_two_bound_rows_repaired_by_updated_at_tiebreak() {
             state: RowState::Bound,
             retired_reason: None,
             superseded_by: None,
+            pane_kind: None,
+            model: None,
+            sandbox: None,
+            permission_mode: None,
+            effort: None,
         };
         write_row_atomic(
             &root
@@ -637,6 +642,195 @@ fn gc_expired_tombstone_rebinds_on_a_live_identity_event() {
     std::fs::remove_dir_all(&root).ok();
 }
 
+#[test]
+fn fresh_agent_binding_roundtrips_settings_and_pane_kind() {
+    let root = temp_root("fresh-agent-roundtrip");
+    let ledger = PaneLedger::new(Some(root.clone()));
+    ledger
+        .record_fresh_agent_binding(&FreshAgentBindingWrite {
+            provider: "codex",
+            session_id: "thread-1",
+            mode: "freshcodex",
+            cwd: Some("/home/u/proj"),
+            create_request_id: Some("req-1"),
+            model: Some("gpt-5.3-codex-spark"),
+            sandbox: Some("workspace-write"),
+            permission_mode: Some("on-request"),
+            effort: Some("high"),
+            supersedes: None,
+            now_ms: 1_000,
+        })
+        .unwrap();
+    let row = ledger.load_binding("codex", "thread-1").expect("row");
+    assert_eq!(row.pane_kind.as_deref(), Some("fresh-agent"));
+    assert_eq!(row.model.as_deref(), Some("gpt-5.3-codex-spark"));
+    assert_eq!(row.sandbox.as_deref(), Some("workspace-write"));
+    assert_eq!(row.permission_mode.as_deref(), Some("on-request"));
+    assert_eq!(row.effort.as_deref(), Some("high"));
+    assert_eq!(row.cwd.as_deref(), Some("/home/u/proj"));
+    assert_eq!(row.created_at, 1_000);
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn fresh_agent_binding_upsert_preserves_created_at_and_refreshes_settings() {
+    let root = temp_root("fresh-agent-upsert");
+    let ledger = PaneLedger::new(Some(root.clone()));
+    let base = FreshAgentBindingWrite {
+        provider: "opencode",
+        session_id: "ses_abc",
+        mode: "freshopencode",
+        cwd: Some("/w"),
+        create_request_id: None,
+        model: Some("m1"),
+        sandbox: None,
+        permission_mode: None,
+        effort: Some("low"),
+        supersedes: None,
+        now_ms: 1_000,
+    };
+    ledger.record_fresh_agent_binding(&base).unwrap();
+    ledger
+        .record_fresh_agent_binding(&FreshAgentBindingWrite {
+            model: Some("m2"),
+            effort: None,
+            now_ms: 2_000,
+            ..base
+        })
+        .unwrap();
+    let row = ledger.load_binding("opencode", "ses_abc").expect("row");
+    assert_eq!(row.created_at, 1_000, "upsert must preserve created_at");
+    assert_eq!(row.updated_at, 2_000);
+    assert_eq!(row.model.as_deref(), Some("m2"));
+    assert_eq!(
+        row.effort, None,
+        "settings are a full snapshot, not a merge"
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn supersedes_retires_the_old_row_and_links_the_chain() {
+    // G3 supersession (V8/A14): codex crash-respawn must retire the OLD
+    // thread row and link it to the new one — never leave two Bound rows.
+    let root = temp_root("fresh-agent-supersedes");
+    let ledger = PaneLedger::new(Some(root.clone()));
+    let base = FreshAgentBindingWrite {
+        provider: "codex",
+        session_id: "old-thread",
+        mode: "freshcodex",
+        cwd: Some("/w"),
+        create_request_id: None,
+        model: Some("m"),
+        sandbox: None,
+        permission_mode: None,
+        effort: None,
+        supersedes: None,
+        now_ms: 1_000,
+    };
+    ledger.record_fresh_agent_binding(&base).unwrap();
+    ledger
+        .record_fresh_agent_binding(&FreshAgentBindingWrite {
+            session_id: "new-thread",
+            supersedes: Some("old-thread"),
+            now_ms: 2_000,
+            ..base
+        })
+        .unwrap();
+    let old = ledger
+        .load_binding("codex", "old-thread")
+        .expect("old row kept");
+    assert_eq!(
+        old.state,
+        RowState::Retired,
+        "old row retired, never left Bound"
+    );
+    assert_eq!(
+        old.superseded_by.as_ref().map(|l| l.session_id.as_str()),
+        Some("new-thread"),
+        "supersededBy links old → new"
+    );
+    let res = ledger
+        .lookup_by_session("codex", "old-thread")
+        .expect("chain resolves");
+    assert!(
+        res.corrected,
+        "claiming the old id is a corrected resolution"
+    );
+    assert_eq!(
+        res.row.session_id, "new-thread",
+        "resolution lands at the terminus"
+    );
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn fresh_agent_upsert_preserves_advisory_create_request_id_when_absent() {
+    // create_request_id is advisory, latest-observed (D4): a rewrite that
+    // carries None must not erase the previously observed value.
+    let root = temp_root("fresh-agent-req-id");
+    let ledger = PaneLedger::new(Some(root.clone()));
+    let base = FreshAgentBindingWrite {
+        provider: "codex",
+        session_id: "thread-1",
+        mode: "freshcodex",
+        cwd: None,
+        create_request_id: Some("req-1"),
+        model: None,
+        sandbox: None,
+        permission_mode: None,
+        effort: None,
+        supersedes: None,
+        now_ms: 1_000,
+    };
+    ledger.record_fresh_agent_binding(&base).unwrap();
+    ledger
+        .record_fresh_agent_binding(&FreshAgentBindingWrite {
+            create_request_id: None,
+            now_ms: 2_000,
+            ..base
+        })
+        .unwrap();
+    let row = ledger.load_binding("codex", "thread-1").expect("row");
+    assert_eq!(row.create_request_id.as_deref(), Some("req-1"));
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn supersedes_of_a_missing_old_row_is_a_silent_noop() {
+    let root = temp_root("fresh-agent-supersedes-missing");
+    let ledger = PaneLedger::new(Some(root.clone()));
+    ledger
+        .record_fresh_agent_binding(&FreshAgentBindingWrite {
+            provider: "codex",
+            session_id: "new-thread",
+            mode: "freshcodex",
+            cwd: None,
+            create_request_id: None,
+            model: None,
+            sandbox: None,
+            permission_mode: None,
+            effort: None,
+            supersedes: Some("never-existed"),
+            now_ms: 1_000,
+        })
+        .expect("missing old row is a silent no-op, not an error");
+    assert!(ledger.load_binding("codex", "never-existed").is_none());
+    let row = ledger.load_binding("codex", "new-thread").expect("row");
+    assert_eq!(row.state, RowState::Bound);
+    std::fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn old_terminal_rows_without_settings_fields_still_deserialize() {
+    // A wave-A row serialized before this change has none of the new fields.
+    let json = r#"{"ledgerVersion":1,"provider":"claude","sessionId":"s1","mode":"claude",
+        "createdAt":1,"updatedAt":1,"lastObservedAt":1,"state":"bound"}"#;
+    let row: BindingRow = serde_json::from_str(json).expect("old row must parse");
+    assert_eq!(row.pane_kind, None);
+    assert_eq!(row.model, None);
+}
+
 #[test]
 fn rebind_to_the_same_identity_is_not_a_supersession() {
     let root = temp_root("samebind");

From bcbf8aeeab37b780d2cbbc991be3d7cb1ff62b02 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:12:58 -0700
Subject: [PATCH 27/87] test(sessions): pin CodexLocator window semantics and
 correlation guards

---
 crates/freshell-sessions/src/codex_locator.rs | 309 ++++++++++++++++++
 1 file changed, 309 insertions(+)

diff --git a/crates/freshell-sessions/src/codex_locator.rs b/crates/freshell-sessions/src/codex_locator.rs
index ad84d7b04..ad7ba222f 100644
--- a/crates/freshell-sessions/src/codex_locator.rs
+++ b/crates/freshell-sessions/src/codex_locator.rs
@@ -656,4 +656,313 @@ mod tests {
         assert_eq!(locator.fs_scan_count(), before);
         let _ = std::fs::remove_dir_all(&root);
     }
+
+    const TID2: &str = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+
+    #[test]
+    fn rollout_present_at_arm_is_never_a_candidate() {
+        let root = unique_temp_dir("snapshot");
+        // File exists BEFORE arm — the known-files snapshot must exclude it
+        // forever, regardless of any timing.
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 1_000));
+        assert!(locator.tick(1_000 + CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1); // zero candidates → keep watching
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn foreign_cwd_rollout_is_never_a_candidate() {
+        let root = unique_temp_dir("cwd");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/home/me/project-a")));
+        assert!(locator.note_submit("t1", 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/home/me/project-b"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn rollout_without_cwd_field_never_binds() {
+        // cwd is REQUIRED (A4 hardening): `SessionMeta.cwd` is non-optional
+        // at codex 0.145.0 and 3,858/3,858 + 500/500 real rollouts carry it.
+        // A no-cwd first line is a foreign shape — accepting it would be
+        // pure attack surface (a location-blind universal candidate).
+        let root = unique_temp_dir("no-cwd");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        write_rollout(&root, "2026/07/26", TID, None);
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn two_new_rollouts_in_one_window_refuse_to_bind() {
+        let root = unique_temp_dir("ambiguous");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // Refusal marks the evaluation resolved but stays armed…
+        assert_eq!(locator.armed_count(), 1);
+        // …and a later Enter re-opens a fresh window (both files are now
+        // still absent from known_files, so still ambiguous — proves the
+        // refusal is repeatable, never a guess).
+        assert!(locator.note_submit("t1", CODEX_WINDOW_MS + 100));
+        assert!(locator
+            .tick(CODEX_WINDOW_MS + 100 + CODEX_WINDOW_MS)
+            .is_empty());
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn same_rollout_claimed_by_two_armed_terminals_refuses_both() {
+        let root = unique_temp_dir("contested");
+        let locator = CodexLocator::new(root.clone());
+        // Two panes, SAME cwd, armed concurrently, submitting in the same
+        // tick; ONE new rollout. The contested-cwd census refuses both
+        // (Pass 2's same-tick claim check remains as defense-in-depth).
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.arm("t2", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        assert!(locator.note_submit("t2", 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 2);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn staggered_same_cwd_armed_terminals_never_bind_uncontested() {
+        // Cross-tick contested guard (A4 hardening): ambiguity refusal must
+        // not be same-tick-only. While ≥2 ARMED terminals share a normalized
+        // cwd, NO candidate with that cwd binds for any of them — staggered
+        // deadlines must not let pane A grab pane B's rollout uncontested.
+        let root = unique_temp_dir("staggered");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.arm("t2", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        assert!(locator.note_submit("t2", 5_000));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        // t1's deadline fires alone: contested cwd → refuse.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // t2's deadline: still contested → refuse.
+        assert!(locator.tick(5_000 + CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 2);
+        // One pane exits (disarm); the survivor re-opens with a fresh Enter
+        // and may now bind — re-evaluation is legitimate once uncontested.
+        locator.disarm("t2");
+        assert!(locator.note_submit("t1", 10_000));
+        let located = locator.tick(10_000 + CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].terminal_id, "t1");
+        assert_eq!(located[0].thread_id, TID);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn zero_candidate_window_keeps_watching_and_later_enter_reopens() {
+        let root = unique_temp_dir("reopen");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        // Window closes with zero candidates → keep watching (stays armed).
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        // A later Enter re-opens; the rollout appears; resolves via the new
+        // Enter-anchored window.
+        let enter_at = 10 * CODEX_WINDOW_MS;
+        assert!(locator.note_submit("t1", enter_at));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let located = locator.tick(enter_at + CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn later_enter_reopen_keeps_the_first_submit_snapshot() {
+        // Slow materialization (>2 s Enter→creation) is recovered by a later
+        // Enter ONLY if re-opens never re-snapshot: the pane's own late
+        // rollout appears between the first window's close and the second
+        // Enter, and must STAY a candidate. Only the FIRST submit
+        // re-snapshots (pinned via fs_scan_count).
+        let root = unique_temp_dir("reopen-snapshot");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0)); // first submit: re-snapshot
+                                               // First window closes empty.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // The pane's own rollout lands LATE — after the window, before the
+        // next Enter.
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let scans_before = locator.fs_scan_count();
+        assert!(locator.note_submit("t1", 10_000)); // re-open: NO re-snapshot
+        assert_eq!(locator.fs_scan_count(), scans_before);
+        let located = locator.tick(10_000 + CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn mid_turn_enter_never_reopens_a_pending_evaluation() {
+        let root = unique_temp_dir("midturn");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 100));
+        // Second Enter while the first evaluation is still pending: no-op.
+        assert!(!locator.note_submit("t1", 200));
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn non_session_meta_or_malformed_first_line_is_never_a_candidate() {
+        // COMPLETE (newline-terminated) garbage lines are `Probe::Never` —
+        // not pending: codex writes the whole meta line + '\n' in one
+        // write-then-flush, so a complete non-candidate line never becomes
+        // one. (Empty/torn lines are the pending case — see the tests below.)
+        let root = unique_temp_dir("badmeta");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        std::fs::write(
+            dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl")),
+            format!(r#"{{"type":"event_msg","payload":{{"id":"{TID}"}}}}"#),
+        )
+        .unwrap();
+        std::fs::write(
+            dir.join(format!("rollout-2026-07-26T08-00-01-{TID2}.jsonl")),
+            "not json at all\n",
+        )
+        .unwrap();
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn empty_first_line_file_is_pending_and_binds_once_meta_lands() {
+        // A3 (validated): codex CREATES the rollout file, then awaits
+        // git-info collection (subprocesses, 5 s timeout each, worst ~10 s)
+        // BEFORE writing the session_meta first line. A deadline scan can
+        // observe the empty file — it must be a re-probed PENDING candidate,
+        // never dropped by a one-shot read.
+        let root = unique_temp_dir("pending");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        let file = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
+        std::fs::write(&file, "").unwrap(); // created, meta not yet written
+                                            // Deadline scan: pending candidate → bind NOTHING, stay unresolved.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        // Meta line lands (well within grace); the next sweep binds it.
+        // (write_rollout reuses the same filename — same ts, same TID.)
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let located = locator.tick(CODEX_WINDOW_MS + 300);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID);
+        assert_eq!(locator.armed_count(), 0);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn readable_candidate_never_binds_while_another_new_file_is_pending() {
+        // A4 (validated, CRITICAL): the pane's OWN rollout can sit
+        // unreadable in the git-info gap while a FOREIGN same-cwd rollout is
+        // already readable. Pending candidates are BIND-BLOCKING — the
+        // readable file must not win the window.
+        let root = unique_temp_dir("pending-block");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        // Pane's own file: created, first line not yet written.
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        let own = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
+        std::fs::write(&own, "").unwrap();
+        // Foreign file: fully readable, same cwd.
+        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
+        // Deadline: NOTHING binds while the pending file exists.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        // Own meta line lands → TWO candidates → ambiguity refusal (fail
+        // toward refusal, never a guess).
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS + 300).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn pending_file_that_never_parses_expires_after_grace() {
+        // Grace is bounded (A4 hardening 1): once PENDING_FIRST_LINE_GRACE_MS
+        // elapses without a readable first line, the file is permanently
+        // excluded and stops blocking; a surviving sole candidate may then
+        // bind.
+        let root = unique_temp_dir("pending-expiry");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        let own = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
+        std::fs::write(&own, "").unwrap(); // never gains a first line
+        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
+        // First due scan sees the pending file (grace clock starts here).
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // Still blocked just before grace expiry…
+        assert!(locator
+            .tick(CODEX_WINDOW_MS + PENDING_FIRST_LINE_GRACE_MS - 1)
+            .is_empty());
+        // …then the never-parsed file expires and the sole survivor binds.
+        let located = locator.tick(CODEX_WINDOW_MS + PENDING_FIRST_LINE_GRACE_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID2);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn missing_sessions_root_is_tolerated_and_resolves_once_it_appears() {
+        let base = unique_temp_dir("missing-root");
+        let root = base.join("does-not-exist-yet");
+        let locator = CodexLocator::new(root.clone());
+        // arm() scans the missing root — tolerated, never a panic.
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty()); // no panic, keep watching
+        assert_eq!(locator.armed_count(), 1);
+        assert!(locator.note_submit("t1", 2 * CODEX_WINDOW_MS));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let located = locator.tick(3 * CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        let _ = std::fs::remove_dir_all(&base);
+    }
+
+    #[test]
+    fn flat_test_shape_rollout_resolves() {
+        // locate_codex_rollout supports flat `<id>.jsonl`; the locator's walk
+        // must too (integration fixtures seed this shape).
+        let root = unique_temp_dir("flat");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        write_rollout(&root, ".", TID, Some("/tmp"));
+        let located = locator.tick(CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
 }

From 00307ff1faff159b9a9bc27776b15f4e72a20d20 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:13:51 -0700
Subject: [PATCH 28/87] feat(server): GET /api/recovery/inventory -
 device-scoped recoverable-state read API (B3/P1.9)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wires the Task 1 pure inventory builder into an authenticated axum route:
- RecoveryInventoryState + router() in recovery_inventory.rs; merged in
  main.rs beside the tabs_snapshots surface, sharing the SAME
  tabs-snapshots dir, pane ledger, and terminal registry.
- Snapshot reads run in spawn_blocking over the read-only tabs_persist
  selectors; per-device generations filtered through
  select_foreign_recent_generation_ids (own-client, A15 stale, A16
  post-boot concurrent). IO/Join errors -> 500 + tracing::error (fail-loud).
- D7 liveness join reads the shared TerminalRegistry directory():
  (mode, resume_session_id) for Running rows.
- bootAgoMs optional query param (missing => 0 => boot_cutoff = now).
- Removed Task 1's module-wide #![allow(dead_code)]; DeviceUnion.device_id
  is now read by build_inventory instead of re-derived from the union doc.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-server/src/main.rs            |  14 +
 .../freshell-server/src/recovery_inventory.rs | 148 ++++++++-
 .../src/recovery_inventory_tests.rs           | 286 ++++++++++++++++++
 3 files changed, 446 insertions(+), 2 deletions(-)

diff --git a/crates/freshell-server/src/main.rs b/crates/freshell-server/src/main.rs
index fd877414f..0ae00e06a 100644
--- a/crates/freshell-server/src/main.rs
+++ b/crates/freshell-server/src/main.rs
@@ -794,6 +794,20 @@ async fn main() -> ExitCode {
             restore_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
             restore_ack_timeout: std::time::Duration::from_secs(5),
         }))
+        // B3/P1.9 Task 2: the recovery-inventory read surface. Joins the SAME
+        // tabs-snapshots store as `tabs_snapshots` above (read-only), the
+        // pane-identity ledger (`:427`), and the shared terminal registry
+        // (`:249`, the D7 liveness join).
+        .merge(recovery_inventory::router(
+            recovery_inventory::RecoveryInventoryState {
+                auth_token: auth_token.as_ref().clone(),
+                snapshots_dir: home
+                    .as_ref()
+                    .map(|h| h.join(".freshell").join("tabs-snapshots")),
+                ledger: std::sync::Arc::clone(&pane_ledger),
+                registry: registry.clone(),
+            },
+        ))
         .merge(network::router(network_state))
         .merge(session_directory::router(session_directory_state))
         .merge(sessions::router(sessions::SessionsState {
diff --git a/crates/freshell-server/src/recovery_inventory.rs b/crates/freshell-server/src/recovery_inventory.rs
index 9b7e93ffe..e7fd72d38 100644
--- a/crates/freshell-server/src/recovery_inventory.rs
+++ b/crates/freshell-server/src/recovery_inventory.rs
@@ -3,7 +3,6 @@
 //! inventory shape. No I/O here — Task 2 (the HTTP route) feeds it from the
 //! snapshot store, the ledger, and the terminal registry, and consumes
 //! `select_foreign_recent_generation_ids` when composing each device's union.
-#![allow(dead_code)] // consumed by Task 2 (the /api/recovery route wiring)
 
 use freshell_ws::pane_ledger::{BindingRow, RetiredReason, RowState};
 use serde_json::{json, Value};
@@ -133,7 +132,7 @@ pub fn build_inventory(
     let mut tabs_per_union: Vec<Vec<Value>> = Vec::new();
     for d in &unions {
         let doc = &d.union_doc;
-        let device_id = doc["deviceId"].as_str().unwrap_or("").to_string();
+        let device_id = d.device_id.clone();
         let tabs: Vec<Value> = doc["records"]
             .as_array()
             .cloned()
@@ -324,6 +323,151 @@ fn digest16(parts: &[String]) -> String {
     digest[..8].iter().map(|b| format!("{b:02x}")).collect()
 }
 
+// ── Task 2: the `GET /api/recovery/inventory` route ───────────────────────────
+
+use axum::extract::{Query, State};
+use axum::http::{HeaderMap, StatusCode};
+use axum::response::{IntoResponse, Response};
+use axum::routing::get;
+use axum::{Json, Router};
+
+use crate::boot::{is_authed, unauthorized};
+
+/// State for the recovery-inventory read surface. `registry` is the SAME
+/// shared `TerminalRegistry` the WS server state receives (`main.rs:249`) —
+/// read-only here (the D7 liveness join).
+#[derive(Clone)]
+pub struct RecoveryInventoryState {
+    pub auth_token: String,
+    pub snapshots_dir: Option<std::path::PathBuf>,
+    pub ledger: std::sync::Arc<freshell_ws::pane_ledger::PaneLedger>,
+    pub registry: freshell_terminal::TerminalRegistry,
+}
+
+#[derive(serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct InventoryQuery {
+    client_instance_id: Option<String>,
+    boot_ago_ms: Option<u64>,
+}
+
+pub fn router(state: RecoveryInventoryState) -> Router {
+    Router::new()
+        .route("/api/recovery/inventory", get(inventory_handler))
+        .with_state(state)
+}
+
+/// Epoch millis — the same convention the tabs-persist/tabs stores use
+/// (`tabs.rs:549`), as `u64` because the A15/A16 cutoffs are unsigned.
+fn now_ms() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_millis() as u64)
+        .unwrap_or(0)
+}
+
+/// Snapshot store present but unreadable, or the blocking read task failed:
+/// fail LOUD (500) — never a silent empty inventory (the
+/// `tabs_snapshots.rs:61` precedent).
+fn internal_error() -> Response {
+    (
+        StatusCode::INTERNAL_SERVER_ERROR,
+        Json(json!({ "error": "recovery inventory unavailable" })),
+    )
+        .into_response()
+}
+
+async fn inventory_handler(
+    State(state): State<RecoveryInventoryState>,
+    headers: HeaderMap,
+    Query(q): Query<InventoryQuery>,
+) -> Response {
+    if !is_authed(&headers, &state.auth_token) {
+        return unauthorized();
+    }
+    let exclude = q.client_instance_id.unwrap_or_default();
+    // D2/A16: anchor the concurrent-client filter to the requester's boot.
+    // Missing param => 0 => boot_cutoff = now, so nothing that predates the
+    // request is dropped.
+    let boot_cutoff = now_ms().saturating_sub(q.boot_ago_ms.unwrap_or(0));
+    let unions = match state.snapshots_dir.clone() {
+        None => vec![],
+        Some(dir) => {
+            let job = tokio::task::spawn_blocking(move || {
+                read_foreign_unions(&dir, &exclude, boot_cutoff)
+            });
+            match job.await {
+                Ok(Ok(u)) => u,
+                Ok(Err(e)) => {
+                    tracing::error!(target: "freshell_server::recovery_inventory",
+                        error = %e, "recovery inventory snapshot read failed");
+                    return internal_error();
+                }
+                Err(e) => {
+                    tracing::error!(target: "freshell_server::recovery_inventory",
+                        error = %e, "recovery inventory join failed");
+                    return internal_error();
+                }
+            }
+        }
+    };
+    let live = live_session_keys(&state.registry);
+    Json(build_inventory(unions, state.ledger.list_bindings(), live)).into_response()
+}
+
+/// Read-only liveness join (D7): `(provider = mode, sessionId)` for every
+/// currently-Running terminal row — the same row fields the ladder's A13 guard
+/// reads (`terminal.rs:1690-1745`: mode + resume session id, status ==
+/// `TerminalRunStatus::Running`).
+fn live_session_keys(registry: &freshell_terminal::TerminalRegistry) -> HashSet<(String, String)> {
+    registry
+        .directory()
+        .into_iter()
+        .filter(|row| row.status == freshell_protocol::TerminalRunStatus::Running)
+        .filter_map(|row| {
+            row.resume_session_id
+                .filter(|s| !s.is_empty())
+                .map(|sid| (row.mode, sid))
+        })
+        .collect()
+}
+
+fn read_foreign_unions(
+    dir: &std::path::Path,
+    exclude_client: &str,
+    boot_cutoff: u64,
+) -> std::io::Result<Vec<DeviceUnion>> {
+    use freshell_ws::tabs_persist::{
+        list_snapshot_devices, read_device_overview, read_generations_union_by_ids, ComponentsUnion,
+    };
+    let mut out = vec![];
+    if !dir.is_dir() {
+        return Ok(out);
+    }
+    for device in list_snapshot_devices(dir)? {
+        let Some((_, generations)) = read_device_overview(dir, &device)? else {
+            continue;
+        };
+        // Task 1 helper: drops the requester's own generations, concurrent
+        // post-boot clients (A16), AND stale clients (A15).
+        let foreign =
+            select_foreign_recent_generation_ids(&generations, exclude_client, boot_cutoff);
+        if foreign.is_empty() {
+            continue;
+        }
+        match read_generations_union_by_ids(dir, &device, &foreign)? {
+            ComponentsUnion::Found(union_doc) => out.push(DeviceUnion {
+                device_id: device,
+                union_doc,
+            }),
+            // A component pruned between the overview scan and the union read:
+            // zero surviving generations for this device — skip it.
+            ComponentsUnion::Missing(_) => continue,
+        }
+    }
+    Ok(out)
+}
+
 #[cfg(test)]
 #[path = "recovery_inventory_tests.rs"]
 mod tests;
diff --git a/crates/freshell-server/src/recovery_inventory_tests.rs b/crates/freshell-server/src/recovery_inventory_tests.rs
index 53e396639..b8a557fda 100644
--- a/crates/freshell-server/src/recovery_inventory_tests.rs
+++ b/crates/freshell-server/src/recovery_inventory_tests.rs
@@ -302,6 +302,292 @@ fn stale_clients_generations_are_dropped() {
     );
 }
 
+// ── Task 2: `GET /api/recovery/inventory` route tests ─────────────────────────
+
+use axum::body::Body;
+use axum::http::{Request, StatusCode};
+use tower::ServiceExt;
+
+/// Snapshot fixture written directly with the store's REAL layout —
+/// `<dir>/<device>/<client>-<capturedAt:020>-r<rev:012>.json` (alphanumeric
+/// device/client ids need no escaping).
+fn write_snapshot(
+    dir: &std::path::Path,
+    device: &str,
+    client: &str,
+    captured_at: u64,
+    rev: u64,
+    records: serde_json::Value,
+) {
+    let doc = json!({
+        "deviceId": device, "deviceLabel": format!("label-{device}"), "clientInstanceId": client,
+        "serverInstanceId": "srv-test", "snapshotRevision": rev, "capturedAt": captured_at,
+        "records": records
+    });
+    let d = dir.join(device);
+    std::fs::create_dir_all(&d).unwrap();
+    std::fs::write(
+        d.join(format!("{client}-{captured_at:020}-r{rev:012}.json")),
+        serde_json::to_vec(&doc).unwrap(),
+    )
+    .unwrap();
+}
+
+// Fresh EMPTY terminal registry — constructed exactly the way main.rs:249 does;
+// no running terminals => every pane comes back `live: false`.
+fn test_registry() -> freshell_terminal::TerminalRegistry {
+    freshell_terminal::TerminalRegistry::new()
+}
+
+fn test_state(
+    dir: Option<std::path::PathBuf>,
+    ledger_root: Option<std::path::PathBuf>,
+) -> RecoveryInventoryState {
+    RecoveryInventoryState {
+        auth_token: "tok".into(),
+        snapshots_dir: dir,
+        ledger: std::sync::Arc::new(freshell_ws::pane_ledger::PaneLedger::new_locked(
+            ledger_root,
+        )),
+        registry: test_registry(),
+    }
+}
+
+async fn get(
+    router: axum::Router,
+    uri: &str,
+    auth: Option<&str>,
+) -> (StatusCode, serde_json::Value) {
+    let mut req = Request::builder().method("GET").uri(uri);
+    if let Some(token) = auth {
+        req = req.header("x-auth-token", token);
+    }
+    let resp = router
+        .oneshot(req.body(Body::empty()).unwrap())
+        .await
+        .unwrap();
+    let status = resp.status();
+    let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
+        .await
+        .unwrap();
+    (
+        status,
+        serde_json::from_slice(&bytes).unwrap_or(serde_json::Value::Null),
+    )
+}
+
+#[tokio::test]
+async fn route_requires_auth_and_serves_inventory() {
+    let tmp = tempfile::tempdir().unwrap();
+    write_snapshot(
+        tmp.path(),
+        "dev1",
+        "clientA",
+        1000,
+        1,
+        json!([
+            {"tabKey":"k1","tabId":"t1","tabName":"work","status":"open","revision":1,"updatedAt":1000,
+             "paneCount":1,"panes":[{"paneId":"p1","kind":"terminal","payload":{"mode":"shell","initialCwd":"/w"}}]}
+        ]),
+    );
+    let router = router(test_state(Some(tmp.path().to_path_buf()), None));
+    // house convention: 401 case asserted alongside the happy path
+    let (code, _) = get(
+        router.clone(),
+        "/api/recovery/inventory?clientInstanceId=me",
+        None,
+    )
+    .await;
+    assert_eq!(code, axum::http::StatusCode::UNAUTHORIZED);
+    let (code, body) = get(
+        router,
+        "/api/recovery/inventory?clientInstanceId=me",
+        Some("tok"),
+    )
+    .await;
+    assert_eq!(code, axum::http::StatusCode::OK);
+    assert_eq!(body["recoverable"], true);
+    assert_eq!(body["device"]["deviceId"], "dev1");
+    assert_eq!(body["device"]["tabs"][0]["panes"][0]["cwd"], "/w");
+}
+
+#[tokio::test]
+async fn route_excludes_requesting_clients_own_generations() {
+    let tmp = tempfile::tempdir().unwrap();
+    write_snapshot(
+        tmp.path(),
+        "dev1",
+        "oldclient",
+        1000,
+        1,
+        json!([
+            {"tabKey":"k1","tabId":"t1","tabName":"work","status":"open","revision":1,"updatedAt":1000,
+             "paneCount":1,"panes":[{"paneId":"p1","kind":"terminal","payload":{"mode":"shell"}}]}
+        ]),
+    );
+    write_snapshot(
+        tmp.path(),
+        "dev1",
+        "me",
+        2000,
+        1,
+        json!([
+            {"tabKey":"junk","tabId":"tj","tabName":"junk","status":"open","revision":1,"updatedAt":2000,
+             "paneCount":1,"panes":[{"paneId":"pj","kind":"terminal","payload":{"mode":"shell"}}]}
+        ]),
+    );
+    let router = router(test_state(Some(tmp.path().to_path_buf()), None));
+    let (_, body) = get(
+        router,
+        "/api/recovery/inventory?clientInstanceId=me",
+        Some("tok"),
+    )
+    .await;
+    let tabs = body["device"]["tabs"].as_array().unwrap();
+    assert!(
+        tabs.iter().all(|t| t["tabKey"] != "junk"),
+        "requester's own push must be filtered out"
+    );
+    assert!(tabs.iter().any(|t| t["tabKey"] == "k1"));
+}
+
+#[tokio::test]
+async fn route_serves_ledger_only_recovery_without_snapshots() {
+    // Seed a binding file the ledger boot-scan will load (BindingRow camelCase JSON).
+    let home = tempfile::tempdir().unwrap();
+    let broot = home.path().join("pane-ledger");
+    std::fs::create_dir_all(broot.join("bindings").join("claude")).unwrap();
+    std::fs::write(
+        broot.join("bindings").join("claude").join("S1.json"),
+        serde_json::to_vec(&json!({
+            "ledgerVersion": 1, "provider": "claude", "sessionId": "S1", "mode": "claude",
+            "cwd": "/w", "createdAt": 1, "updatedAt": 1, "lastObservedAt": 1, "state": "bound"
+        }))
+        .unwrap(),
+    )
+    .unwrap();
+    let router = router(test_state(None, Some(broot)));
+    let (_, body) = get(
+        router,
+        "/api/recovery/inventory?clientInstanceId=me",
+        Some("tok"),
+    )
+    .await;
+    assert_eq!(body["recoverable"], true);
+    assert_eq!(body["ledgerOnly"][0]["sessionId"], "S1");
+}
+
+#[tokio::test]
+async fn route_drops_stale_rotated_clients() {
+    // A15: a client silent >15 min (heartbeat is 5 min) is closed or rotated - its
+    // resurrected tab must not enter the inventory union.
+    let tmp = tempfile::tempdir().unwrap();
+    let t_max: u64 = 100_000_000;
+    write_snapshot(
+        tmp.path(),
+        "dev1",
+        "fresh",
+        t_max,
+        1,
+        json!([
+            {"tabKey":"k1","tabId":"t1","tabName":"work","status":"open","revision":1,"updatedAt":t_max,
+             "paneCount":1,"panes":[{"paneId":"p1","kind":"terminal","payload":{"mode":"shell"}}]}
+        ]),
+    );
+    write_snapshot(
+        tmp.path(),
+        "dev1",
+        "stale",
+        t_max - 16 * 60 * 1000,
+        1,
+        json!([
+            {"tabKey":"zombie","tabId":"tz","tabName":"zombie","status":"open","revision":1,"updatedAt":t_max - 16 * 60 * 1000,
+             "paneCount":1,"panes":[{"paneId":"pz","kind":"terminal","payload":{"mode":"shell"}}]}
+        ]),
+    );
+    let router = router(test_state(Some(tmp.path().to_path_buf()), None));
+    let (_, body) = get(
+        router,
+        "/api/recovery/inventory?clientInstanceId=me",
+        Some("tok"),
+    )
+    .await;
+    let tabs = body["device"]["tabs"].as_array().unwrap();
+    assert!(
+        tabs.iter().all(|t| t["tabKey"] != "zombie"),
+        "stale client's tab must be dropped"
+    );
+    assert!(tabs.iter().any(|t| t["tabKey"] == "k1"));
+}
+
+#[tokio::test]
+async fn route_bootagoms_drops_concurrent_post_boot_clients() {
+    // A16/D2 at the ROUTE level: this test forces the bootAgoMs -> boot_cutoff ->
+    // read_foreign_unions(_, _, boot_cutoff) wiring to actually exist. It uses REAL
+    // wall-clock capturedAt values because boot_cutoff is computed from now_ms().
+    let tmp = tempfile::tempdir().unwrap();
+    let now = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap()
+        .as_millis() as u64;
+    // The genuinely lost client: its only push predates the requester's boot by 60s.
+    write_snapshot(
+        tmp.path(),
+        "dev1",
+        "lost",
+        now - 60_000,
+        1,
+        json!([
+            {"tabKey":"k1","tabId":"t1","tabName":"work","status":"open","revision":1,"updatedAt":now - 60_000,
+             "paneCount":1,"panes":[{"paneId":"p1","kind":"terminal","payload":{"mode":"shell"}}]}
+        ]),
+    );
+    // A concurrently-born fresh window: ALL of its generations postdate the boot.
+    write_snapshot(
+        tmp.path(),
+        "dev1",
+        "concurrent",
+        now,
+        1,
+        json!([
+            {"tabKey":"junk","tabId":"tj","tabName":"junk","status":"open","revision":1,"updatedAt":now,
+             "paneCount":1,"panes":[{"paneId":"pj","kind":"terminal","payload":{"mode":"shell"}}]}
+        ]),
+    );
+    let router = router(test_state(Some(tmp.path().to_path_buf()), None));
+    // Requester booted 30s ago => boot_cutoff = now - 30s: "concurrent" (born now) is
+    // post-boot junk and must be dropped; "lost" (60s ago) predates boot and survives.
+    let (_, body) = get(
+        router.clone(),
+        "/api/recovery/inventory?clientInstanceId=me&bootAgoMs=30000",
+        Some("tok"),
+    )
+    .await;
+    let tabs = body["device"]["tabs"].as_array().unwrap();
+    assert!(
+        tabs.iter().all(|t| t["tabKey"] != "junk"),
+        "post-boot concurrent client must be dropped (A16)"
+    );
+    assert!(
+        tabs.iter().any(|t| t["tabKey"] == "k1"),
+        "pre-boot lost client must survive"
+    );
+    // Without bootAgoMs (default 0 => boot_cutoff = now at handler time) BOTH clients
+    // predate the cutoff and BOTH tabs appear - pins the optional-default-0 contract.
+    let (_, body) = get(
+        router,
+        "/api/recovery/inventory?clientInstanceId=me",
+        Some("tok"),
+    )
+    .await;
+    let tabs = body["device"]["tabs"].as_array().unwrap();
+    assert!(
+        tabs.iter().any(|t| t["tabKey"] == "junk"),
+        "default cutoff must drop nothing pre-request"
+    );
+    assert!(tabs.iter().any(|t| t["tabKey"] == "k1"));
+}
+
 #[test]
 fn concurrent_fresh_windows_generations_are_dropped() {
     // A16/D2: a client whose ENTIRE retained history postdates the requester's boot is a

From 7d19861b18799cb18e6c76032566d1acc4e027da Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:17:22 -0700
Subject: [PATCH 29/87] test(sessions): restore newline-terminated event_msg
 line so the Probe::Never branch is actually pinned

---
 crates/freshell-sessions/src/codex_locator.rs | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/crates/freshell-sessions/src/codex_locator.rs b/crates/freshell-sessions/src/codex_locator.rs
index ad7ba222f..a31f20de1 100644
--- a/crates/freshell-sessions/src/codex_locator.rs
+++ b/crates/freshell-sessions/src/codex_locator.rs
@@ -838,7 +838,11 @@ mod tests {
         std::fs::create_dir_all(&dir).unwrap();
         std::fs::write(
             dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl")),
-            format!(r#"{{"type":"event_msg","payload":{{"id":"{TID}"}}}}"#),
+            format!(
+                "{}
+",
+                r#"{{"type":"event_msg","payload":{{"id":"{TID}"}}}}"#
+            ),
         )
         .unwrap();
         std::fs::write(

From 14ecfed77a26535a80df680edd159f437817c04f Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:23:43 -0700
Subject: [PATCH 30/87] test(sessions): write valid wrong-type JSON in
 Never-branch pin (restore brief's verbatim format! line)

---
 crates/freshell-sessions/src/codex_locator.rs |   5 +-
 .../src/codex_locator.rs.bak                  | 972 ++++++++++++++++++
 2 files changed, 974 insertions(+), 3 deletions(-)
 create mode 100644 crates/freshell-sessions/src/codex_locator.rs.bak

diff --git a/crates/freshell-sessions/src/codex_locator.rs b/crates/freshell-sessions/src/codex_locator.rs
index a31f20de1..f51283eb1 100644
--- a/crates/freshell-sessions/src/codex_locator.rs
+++ b/crates/freshell-sessions/src/codex_locator.rs
@@ -839,9 +839,8 @@ mod tests {
         std::fs::write(
             dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl")),
             format!(
-                "{}
-",
-                r#"{{"type":"event_msg","payload":{{"id":"{TID}"}}}}"#
+                "{{\"type\":\"event_msg\",\"payload\":{{\"id\":\"{TID}\"}}}}
+"
             ),
         )
         .unwrap();
diff --git a/crates/freshell-sessions/src/codex_locator.rs.bak b/crates/freshell-sessions/src/codex_locator.rs.bak
new file mode 100644
index 000000000..a31f20de1
--- /dev/null
+++ b/crates/freshell-sessions/src/codex_locator.rs.bak
@@ -0,0 +1,972 @@
+//! Server-side codex terminal-pane session locator (Lane B2, campaign §2.3.2).
+//!
+//! Third sibling of `amplifier_locator` / `opencode_locator` (a
+//! provider-parameterized locator was explicitly rejected — the substrates
+//! share zero code). Substrate: codex persists ONE JSONL rollout file per
+//! session under a process-global sessions root
+//! (`<CODEX_HOME|~/.codex>/sessions/YYYY/MM/DD/rollout-<ts>-<threadId>.jsonl`,
+//! flat `<id>.jsonl` in tests). A new session is a NEW FILE — so the locator
+//! does a snapshot-diff of the file set, not a row-diff.
+//!
+//! Codex-behavior facts below are validated against codex source @
+//! rust-v0.145.0 and a 3,858-rollout corpus; a codex upgrade re-opens them.
+//!
+//! Deliberate deviations from the opencode locator, with rationale:
+//! - Windows are ENTER-ANCHORED ONLY — no spawn window. Real codex defers
+//!   rollout file creation until the first user prompt is recorded
+//!   (`RolloutRecorder` defers to `persist()`, materialized via
+//!   `ensure_rollout_materialized()`), so before the pane's first Enter every
+//!   new same-cwd rollout is by construction FOREIGN. `arm()` takes the
+//!   known-files snapshot immediately but schedules NO deadline until
+//!   `note_submit`.
+//! - NO `pre_epsilon_ms` and NO created-at time bound: filesystems have no
+//!   reliable cross-platform creation time (mtime moves on every append).
+//!   The `known_files` snapshot is the primary safety — a file
+//!   already present in the snapshot can never bind to this terminal. The FILENAME
+//!   timestamp and the dated `YYYY/MM/DD` dir are never used as filters
+//!   either: both are precomputed at codex session construction and can
+//!   predate on-disk creation by the entire user idle gap (the dir can even
+//!   be "yesterday" across midnight). The full-tree snapshot-diff sidesteps
+//!   both.
+//! - FIRST-SUBMIT re-snapshot (A4 hardening): the first `note_submit`
+//!   replaces `known_files` with a fresh scan — strictly safe because the
+//!   pane's own rollout cannot exist before its first Enter, so everything
+//!   that appeared between arm and the first Enter is foreign by
+//!   construction. SOUNDNESS PRECONDITION: the caller completes the first
+//!   `note_submit` BEFORE the Enter byte is written to the PTY (codex
+//!   materializes the rollout in response to that very Enter) — the
+//!   `codex_association` submit seam encodes this ordering. Later window
+//!   re-opens NEVER re-snapshot: a >2 s Enter→creation latency is recovered
+//!   by a later Enter only if the pane's own late file stays a candidate.
+//! - Attribution disambiguator: the rollout's own first-line
+//!   `session_meta.payload.cwd` is REQUIRED and must match the armed
+//!   terminal's cwd (`SessionMeta.cwd` is non-optional at 0.145.0;
+//!   3,858/3,858 real rollouts carry it — accepting a no-cwd line would be
+//!   pure foreign attack surface). `payload.cwd` is the codex process's
+//!   physical `getcwd` path recorded verbatim; equality holds because
+//!   `normalize_cwd` opportunistically canonicalizes the pane side — that
+//!   canonicalize is load-bearing for symlinked spawn dirs.
+//! - Pending first-line grace: codex CREATES the file, then awaits git-info
+//!   collection (subprocesses, 5 s timeout each, worst ~10 s) BEFORE writing
+//!   the `session_meta` line. A NEW file whose first line is empty/incomplete
+//!   is a PENDING candidate: re-probed each sweep up to
+//!   `PENDING_FIRST_LINE_GRACE_MS`, and while ANY pending candidate exists
+//!   this terminal binds NOTHING (bind-blocking — a readable foreign file
+//!   must not win while the pane's own file sits in its git-info gap).
+//!   Enter→creation latency beyond the 2 s window is mitigated by this grace
+//!   plus window re-open on a later Enter.
+//! - Contested-cwd refusal is CROSS-TICK: while ≥2 armed terminals share a
+//!   normalized cwd, no candidate with that cwd binds for any of them.
+//! - Ownership is proven ONLY by `payload.id` on line 1 — NEVER the filename
+//!   (prefilter-grade at best), NEVER `payload.session_id` (fork/resume
+//!   LINEAGE: matches a FOREIGN session in 54/144 sampled real rollouts) —
+//!   same predicate as `freshell-ws`'s `first_line_owns`.
+//! - Resumed codex sessions append to their EXISTING rollout file (no new
+//!   file) — consistent with the arm gate refusing resume panes. Compressed
+//!   artifacts (`.jsonl.zst`, present in 0.145.0 source) fail the `.jsonl`
+//!   suffix filter; fresh sessions always write plain `.jsonl`.
+//!
+//! Zero cost when idle: scans happen only at arm, at the FIRST `note_submit`
+//! (the re-snapshot), and at due Enter-anchored
+//! evaluations (a pending candidate keeps its evaluation due, so re-probes
+//! ride the same gate), proven by `fs_scan_count`. Callers run `arm()`,
+//! `note_submit()`, and `tick()` inside `tokio::task::spawn_blocking` (cold
+//! dentry cache is the one unmeasured tail — A6).
+
+use std::collections::{HashMap, HashSet};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Mutex;
+
+use crate::opencode_locator::normalize_cwd;
+
+/// Correlation window after a submit (Enter-anchored deadline). There is NO
+/// spawn-anchored window: real codex (0.145.0) creates the rollout file only
+/// when the first user prompt is recorded, so before the pane's first Enter
+/// every new same-cwd rollout is by construction foreign.
+pub const CODEX_WINDOW_MS: i64 = 2_000;
+
+/// Bounded re-probe grace for a NEW file whose first line is not yet
+/// readable: codex creates the file, then awaits git-info collection
+/// (subprocesses, 5 s timeout each, worst ~10 s) before writing the
+/// `session_meta` line. Matches codex's worst case and the magnitude of the
+/// existing `IDENTITY_RESOLUTION_GRACE_MS`.
+pub const PENDING_FIRST_LINE_GRACE_MS: i64 = 10_000;
+
+/// Bounded first-line read cap — real rollouts reach 152 MB; observed real
+/// first lines are ≤ 22.4 KB. Mirrors `codex_reconcile.rs`.
+const MAX_FIRST_LINE_BYTES: u64 = 1024 * 1024;
+
+/// Bounded walk depth — `sessions/YYYY/MM/DD/` is depth 3; 5 mirrors
+/// `locate_codex_rollout`.
+const MAX_WALK_DEPTH: u8 = 5;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Located {
+    pub terminal_id: String,
+    pub thread_id: String,
+    pub rollout_path: PathBuf,
+    pub cwd: String,
+}
+
+#[derive(Debug, Clone)]
+struct Armed {
+    cwd_normalized: String,
+    known_files: HashSet<PathBuf>,
+    enter_ms: Option<i64>,
+    resolved: bool,
+    /// NEW files whose first line was empty/incomplete when probed, keyed to
+    /// first-seen ms. While any un-expired entry exists, this terminal binds
+    /// NOTHING (bind-blocking); entries older than
+    /// `PENDING_FIRST_LINE_GRACE_MS` are merged into `known_files`
+    /// (permanently excluded — fail toward refusal).
+    pending_first_line: HashMap<PathBuf, i64>,
+}
+
+#[derive(Default)]
+struct Inner {
+    armed: HashMap<String, Armed>,
+}
+
+pub struct CodexLocator {
+    sessions_root: PathBuf,
+    window_ms: i64,
+    inner: Mutex<Inner>,
+    fs_scan_count: AtomicU64,
+}
+
+impl CodexLocator {
+    pub fn new(sessions_root: PathBuf) -> Self {
+        Self::with_config(sessions_root, CODEX_WINDOW_MS)
+    }
+
+    pub fn with_config(sessions_root: PathBuf, window_ms: i64) -> Self {
+        Self {
+            sessions_root,
+            window_ms,
+            inner: Mutex::new(Inner::default()),
+            fs_scan_count: AtomicU64::new(0),
+        }
+    }
+
+    pub fn armed_count(&self) -> usize {
+        self.inner.lock().unwrap().armed.len()
+    }
+
+    pub fn fs_scan_count(&self) -> u64 {
+        self.fs_scan_count.load(Ordering::SeqCst)
+    }
+
+    /// Admission rules (mirrors `OpencodeLocator::arm`): codex mode, running,
+    /// NO resume id (the only already-bound gate — never a restore flag, so
+    /// restore-created identity-less panes re-arm for free), non-empty cwd,
+    /// not already armed. On success takes the arm-time known-files snapshot.
+    /// Arming schedules NO deadline — windows open only on `note_submit`
+    /// (Enter-anchored; see module doc).
+    pub fn arm(
+        &self,
+        terminal_id: &str,
+        mode: &str,
+        status_running: bool,
+        resume_session_id: Option<&str>,
+        cwd: Option<&str>,
+    ) -> bool {
+        if mode != "codex" || !status_running || resume_session_id.is_some() {
+            return false;
+        }
+        let Some(cwd) = cwd.filter(|c| !c.is_empty()) else {
+            return false;
+        };
+        let mut inner = self.inner.lock().unwrap();
+        if inner.armed.contains_key(terminal_id) {
+            return false;
+        }
+        let known_files = self.scan_rollout_files();
+        inner.armed.insert(
+            terminal_id.to_string(),
+            Armed {
+                cwd_normalized: normalize_cwd(cwd),
+                known_files,
+                enter_ms: None,
+                resolved: false,
+                pending_first_line: HashMap::new(),
+            },
+        );
+        true
+    }
+
+    pub fn disarm(&self, terminal_id: &str) {
+        self.inner.lock().unwrap().armed.remove(terminal_id);
+    }
+
+    /// The FIRST submit is what opens a window at all (windows are
+    /// Enter-anchored — arm schedules no deadline), and it RE-SNAPSHOTS
+    /// `known_files` (see module doc: strictly safe because the pane's own
+    /// rollout cannot exist before its first Enter; the caller must complete
+    /// this call BEFORE the Enter byte reaches the PTY, and must run it on
+    /// the blocking pool — the re-snapshot walks the sessions tree).
+    /// Re-open semantics mirror
+    /// opencode: a mid-turn Enter never re-opens a still-pending evaluation;
+    /// a resolved (zero-candidate / ambiguous / contested) terminal gets a
+    /// fresh Enter-anchored deadline. Re-opens NEVER re-snapshot.
+    pub fn note_submit(&self, terminal_id: &str, at_ms: i64) -> bool {
+        let mut inner = self.inner.lock().unwrap();
+        let Some(armed) = inner.armed.get_mut(terminal_id) else {
+            return false;
+        };
+        if !armed.resolved && armed.enter_ms.is_some() {
+            return false;
+        }
+        if armed.enter_ms.is_none() {
+            // FIRST submit: everything that appeared between arm and this
+            // Enter is foreign by construction (A1/A4) — replace the
+            // snapshot. Holding the lock across the scan is deliberate and
+            // bounded (warm walks are 7-9 ms — A6; callers are on the
+            // blocking pool); it also keeps the re-snapshot atomic with the
+            // window open.
+            armed.known_files = self.scan_rollout_files();
+        }
+        armed.enter_ms = Some(at_ms);
+        armed.resolved = false;
+        true
+    }
+
+    /// A terminal is due only when an Enter-anchored deadline exists and has
+    /// passed. No submit -> no window -> never evaluated (see module doc).
+    fn due(&self, armed: &Armed, now_ms: i64) -> bool {
+        matches!(armed.enter_ms, Some(enter_ms) if !armed.resolved && now_ms >= enter_ms + self.window_ms)
+    }
+
+    /// Evaluation at (or after) an Enter-anchored deadline. Outcomes:
+    /// - any NEW file with an empty/incomplete first line (codex's
+    ///   create→session_meta git-info gap) → PENDING: bind NOTHING for this
+    ///   terminal, stay unresolved, re-probe each sweep up to
+    ///   `PENDING_FIRST_LINE_GRACE_MS` (grace-expired files are permanently
+    ///   excluded);
+    /// - 0 candidates → keep watching (stays armed, `resolved = true`);
+    /// - 2+ candidates for one terminal → WARN + refuse (never guess);
+    /// - exactly one candidate but ≥2 ARMED terminals share this cwd → WARN +
+    ///   refuse (contested cwd — cross-tick, so staggered deadlines can't
+    ///   grab a sibling's rollout uncontested);
+    /// - one candidate claimed by ≥2 terminals in the same tick → WARN +
+    ///   refuse ALL claimants (defense-in-depth behind the cwd census);
+    /// - exactly one clean match → emit `Located` and disarm. `tick()` drains.
+    pub fn tick(&self, now_ms: i64) -> Vec<Located> {
+        {
+            let inner = self.inner.lock().unwrap();
+            if inner.armed.is_empty() {
+                return Vec::new();
+            }
+            if !inner.armed.values().any(|a| self.due(a, now_ms)) {
+                return Vec::new();
+            }
+        }
+        let current = self.scan_rollout_files();
+        let mut inner = self.inner.lock().unwrap();
+
+        // Cross-tick contested-cwd census over ALL armed terminals (not just
+        // the due ones): two armed same-cwd panes are indistinguishable on
+        // this substrate, whatever their deadlines.
+        let mut cwd_counts: HashMap<String, usize> = HashMap::new();
+        for a in inner.armed.values() {
+            *cwd_counts.entry(a.cwd_normalized.clone()).or_insert(0) += 1;
+        }
+
+        // Pass 1: per-terminal candidate evaluation.
+        let mut claims: Vec<(String, Located)> = Vec::new();
+        for (terminal_id, armed) in inner.armed.iter_mut() {
+            if !matches!(armed.enter_ms, Some(e) if !armed.resolved && now_ms >= e + self.window_ms)
+            {
+                continue;
+            }
+            let new_paths: Vec<PathBuf> = current.difference(&armed.known_files).cloned().collect();
+            let mut matches: Vec<(PathBuf, RolloutMeta)> = Vec::new();
+            let mut pending_blocking = false;
+            for path in new_paths {
+                match probe_rollout(&path) {
+                    Probe::Candidate(meta) => {
+                        armed.pending_first_line.remove(&path);
+                        if normalize_cwd(&meta.cwd) == armed.cwd_normalized {
+                            matches.push((path, meta));
+                        }
+                    }
+                    Probe::NotYet => {
+                        let first_seen = *armed
+                            .pending_first_line
+                            .entry(path.clone())
+                            .or_insert(now_ms);
+                        if now_ms - first_seen >= PENDING_FIRST_LINE_GRACE_MS {
+                            // Grace exhausted: permanently excluded (fail
+                            // toward refusal — A4 hardening 1).
+                            armed.pending_first_line.remove(&path);
+                            armed.known_files.insert(path);
+                        } else {
+                            pending_blocking = true;
+                        }
+                    }
+                    Probe::Never => {}
+                }
+            }
+            if pending_blocking {
+                // A new file is still inside codex's create→session_meta gap
+                // (git-info collection, worst ~10 s). It may be THIS pane's
+                // rollout — binding any other candidate now could hand the
+                // window to a foreign file while the true owner is unreadable.
+                // Bind nothing, stay unresolved, re-probe next sweep.
+                tracing::debug!(
+                    terminal_id = %terminal_id,
+                    "codex_locator_pending: new rollout first line not yet readable; deferring evaluation"
+                );
+                continue;
+            }
+            armed.resolved = true;
+            match matches.len() {
+                0 => {} // keep watching
+                1 => {
+                    if cwd_counts.get(&armed.cwd_normalized).copied().unwrap_or(0) >= 2 {
+                        tracing::warn!(
+                            terminal_id = %terminal_id,
+                            "codex_locator_contested_cwd: >=2 armed terminals share this cwd; refusing to bind"
+                        );
+                    } else {
+                        let (path, meta) = matches.remove(0);
+                        claims.push((
+                            terminal_id.clone(),
+                            Located {
+                                terminal_id: terminal_id.clone(),
+                                thread_id: meta.thread_id,
+                                rollout_path: path,
+                                cwd: armed.cwd_normalized.clone(),
+                            },
+                        ));
+                    }
+                }
+                n => {
+                    tracing::warn!(
+                        terminal_id = %terminal_id,
+                        candidates = n,
+                        "codex_locator_ambiguous: multiple new rollouts in one window; refusing to bind"
+                    );
+                }
+            }
+        }
+
+        // Pass 2: same-tick cross-terminal conflict — the same rollout (or
+        // thread id) claimed by two armed terminals in one tick is
+        // unattributable. (Defense-in-depth: the contested-cwd census above
+        // already refuses same-cwd claimants across ticks.)
+        let mut located = Vec::new();
+        for (terminal_id, candidate) in &claims {
+            let contested = claims.iter().any(|(other_tid, other)| {
+                other_tid != terminal_id
+                    && (other.rollout_path == candidate.rollout_path
+                        || other.thread_id == candidate.thread_id)
+            });
+            if contested {
+                tracing::warn!(
+                    terminal_id = %terminal_id,
+                    thread_id = %candidate.thread_id,
+                    "codex_locator_contested: rollout claimed by multiple armed terminals; refusing to bind"
+                );
+                continue;
+            }
+            located.push(candidate.clone());
+        }
+        for l in &located {
+            inner.armed.remove(&l.terminal_id);
+        }
+        located
+    }
+
+    fn scan_rollout_files(&self) -> HashSet<PathBuf> {
+        self.fs_scan_count.fetch_add(1, Ordering::SeqCst);
+        fn walk(dir: &Path, depth: u8, out: &mut HashSet<PathBuf>) {
+            if depth > MAX_WALK_DEPTH {
+                return;
+            }
+            let Ok(entries) = std::fs::read_dir(dir) else {
+                return; // missing/corrupt root tolerated, never a panic
+            };
+            for entry in entries.flatten() {
+                let path = entry.path();
+                if path.is_dir() {
+                    walk(&path, depth + 1, out);
+                } else if path
+                    .file_name()
+                    .and_then(|n| n.to_str())
+                    .map(|n| n.ends_with(".jsonl"))
+                    .unwrap_or(false)
+                {
+                    out.insert(path);
+                }
+            }
+        }
+        let mut out = HashSet::new();
+        walk(&self.sessions_root, 0, &mut out);
+        out
+    }
+}
+
+struct RolloutMeta {
+    thread_id: String,
+    /// REQUIRED — `SessionMeta.cwd` is non-optional at codex 0.145.0
+    /// (3,858/3,858 real rollouts carry it); a no-cwd first line is a
+    /// foreign shape, never a candidate (A4 hardening).
+    cwd: String,
+}
+
+/// Tri-state probe result. The distinction between `NotYet` and `Never` is
+/// load-bearing: codex writes the whole session_meta line + '\n' in one
+/// write-then-flush, so a COMPLETE (newline-terminated) line that fails the
+/// candidate shape will never become one, while an empty file or a line
+/// without its trailing newline is codex's create→meta gap (or a raced
+/// write) — "not yet", not "never" (A3, validated).
+enum Probe {
+    /// Parseable `session_meta` with a bare-UUID `payload.id` AND a
+    /// `payload.cwd` — a real candidate shape.
+    Candidate(RolloutMeta),
+    /// Empty file, transient open/read failure, or first line still missing
+    /// its trailing newline — re-probe within the pending grace.
+    NotYet,
+    /// Complete first line that is not a codex session_meta candidate
+    /// (non-JSON, wrong type, non-UUID id, missing cwd, oversized) — never
+    /// a candidate; the locator stays silent on foreign files.
+    Never,
+}
+
+/// Identity probe: bounded first-line read (see `Probe` for the tri-state
+/// semantics).
+fn probe_rollout(path: &Path) -> Probe {
+    use std::io::{BufRead, Read};
+    let Ok(file) = std::fs::File::open(path) else {
+        return Probe::NotYet;
+    };
+    let mut reader = std::io::BufReader::new(file).take(MAX_FIRST_LINE_BYTES);
+    let mut first_line = Vec::new();
+    if reader.read_until(b'\n', &mut first_line).is_err() {
+        return Probe::NotYet;
+    }
+    if first_line.len() as u64 >= MAX_FIRST_LINE_BYTES && !first_line.ends_with(b"\n") {
+        return Probe::Never; // oversized: will never fit the cap
+    }
+    if first_line.is_empty() || !first_line.ends_with(b"\n") {
+        return Probe::NotYet; // create→meta gap, or a raced partial write
+    }
+    let Ok(record) = serde_json::from_slice::<serde_json::Value>(&first_line) else {
+        return Probe::Never;
+    };
+    if record.get("type").and_then(|v| v.as_str()) != Some("session_meta") {
+        return Probe::Never;
+    }
+    let Some(thread_id) = record.pointer("/payload/id").and_then(|v| v.as_str()) else {
+        return Probe::Never;
+    };
+    if !is_uuid_shaped(thread_id) {
+        return Probe::Never;
+    }
+    let Some(cwd) = record.pointer("/payload/cwd").and_then(|v| v.as_str()) else {
+        return Probe::Never; // cwd REQUIRED (A4 hardening)
+    };
+    Probe::Candidate(RolloutMeta {
+        thread_id: thread_id.to_string(),
+        cwd: cwd.to_string(),
+    })
+}
+
+/// Bare hyphenated 36-char UUID shape gate (deliberate small duplicate of
+/// `freshell-ws`'s predicate — this crate sits below it in the dep graph).
+fn is_uuid_shaped(s: &str) -> bool {
+    let bytes = s.as_bytes();
+    if bytes.len() != 36 {
+        return false;
+    }
+    for (i, b) in bytes.iter().enumerate() {
+        let is_hyphen_pos = matches!(i, 8 | 13 | 18 | 23);
+        if is_hyphen_pos {
+            if *b != b'-' {
+                return false;
+            }
+        } else if !b.is_ascii_hexdigit() {
+            return false;
+        }
+    }
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::{Path, PathBuf};
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    static TEST_DIR_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+    /// Same convention as opencode_locator.rs tests: no tempfile crate.
+    fn unique_temp_dir(label: &str) -> PathBuf {
+        let n = TEST_DIR_COUNTER.fetch_add(1, Ordering::SeqCst);
+        let dir = std::env::temp_dir().join(format!(
+            "freshell-codex-locator-test-{label}-{}-{n}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&dir).expect("create test dir");
+        dir
+    }
+
+    /// Write a rollout file whose FIRST line is the session_meta identity
+    /// record, exactly the shape the real codex CLI writes
+    /// (payload.id = identity; payload.cwd = the session's working dir).
+    fn write_rollout(root: &Path, rel_dir: &str, thread_id: &str, cwd: Option<&str>) -> PathBuf {
+        let dir = root.join(rel_dir);
+        std::fs::create_dir_all(&dir).expect("create rollout dir");
+        let file = dir.join(format!("rollout-2026-07-26T08-00-00-{thread_id}.jsonl"));
+        let payload = match cwd {
+            Some(c) => format!(r#"{{"id":"{thread_id}","cwd":"{c}"}}"#),
+            None => format!(r#"{{"id":"{thread_id}"}}"#),
+        };
+        let line = format!(
+            r#"{{"timestamp":"2026-07-26T08:00:00.000Z","type":"session_meta","payload":{payload}}}"#
+        );
+        std::fs::write(&file, format!("{line}\n")).expect("write rollout");
+        file
+    }
+
+    const TID: &str = "11111111-2222-3333-4444-555555555555";
+
+    #[test]
+    fn fresh_rollout_after_first_enter_resolves_via_enter_window() {
+        let root = unique_temp_dir("enter-happy");
+        let cwd = root.join("project");
+        std::fs::create_dir_all(&cwd).unwrap();
+        let cwd_s = cwd.to_string_lossy().to_string();
+        let locator = CodexLocator::new(root.clone());
+
+        assert!(locator.arm("t1", "codex", true, None, Some(&cwd_s)));
+        // No submit yet -> no deadline exists; nothing to evaluate.
+        assert!(locator.tick(10_000).is_empty());
+        // Enter at 20_000; the rollout appears AFTER the submit (real codex
+        // materializes the file only when the first user prompt is recorded).
+        assert!(locator.note_submit("t1", 20_000));
+        let path = write_rollout(&root, "2026/07/26", TID, Some(&cwd_s));
+
+        // Before the Enter-anchored deadline: nothing yet.
+        assert!(locator.tick(20_000 + CODEX_WINDOW_MS - 1).is_empty());
+        let located = locator.tick(20_000 + CODEX_WINDOW_MS);
+        assert_eq!(
+            located,
+            vec![Located {
+                terminal_id: "t1".into(),
+                thread_id: TID.into(),
+                rollout_path: path,
+                cwd: crate::opencode_locator::normalize_cwd(&cwd_s),
+            }]
+        );
+        // Success fully resolves and disarms; tick() drains.
+        assert_eq!(locator.armed_count(), 0);
+        assert!(locator.tick(20_000 + CODEX_WINDOW_MS + 1).is_empty());
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn rollout_after_arm_without_submit_is_never_bound_and_never_scanned() {
+        // A1 (validated): real codex creates the rollout ONLY at the first
+        // user prompt, so before Enter every new same-cwd rollout is by
+        // construction FOREIGN. With no submit there is NO window: the file
+        // must never bind and no deadline scans may run.
+        let root = unique_temp_dir("no-submit");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert_eq!(locator.fs_scan_count(), 1); // the arm snapshot
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert!(locator.tick(100 * CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        assert_eq!(locator.fs_scan_count(), 1); // still only the arm snapshot
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn rollout_created_between_arm_and_first_enter_never_binds() {
+        // A4 hardening (first-submit re-snapshot): Premise 7 guarantees the
+        // pane's own rollout cannot exist before its first Enter, so EVERY
+        // file that appears between arm and the first submit is foreign by
+        // construction (freshagent sidecar, `codex exec`, codex outside
+        // freshell in the same cwd). The FIRST note_submit re-snapshots
+        // known_files, so a bare Enter (empty composer, trust dialog) can
+        // never hand the window to that foreign file as a sole candidate.
+        let root = unique_temp_dir("resnapshot");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        // Foreign rollout lands AFTER arm but BEFORE the first Enter.
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.note_submit("t1", 1_000)); // first submit re-snapshots
+        assert_eq!(locator.fs_scan_count(), 2); // arm + first-submit scans
+        assert!(locator.tick(1_000 + CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1); // zero candidates → keep watching
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn arm_admission_gates() {
+        let root = unique_temp_dir("gates");
+        let locator = CodexLocator::new(root.clone());
+        // wrong mode
+        assert!(!locator.arm("t1", "opencode", true, None, Some("/tmp")));
+        // not running
+        assert!(!locator.arm("t1", "codex", false, None, Some("/tmp")));
+        // resume id present — the ONLY already-bound gate (no restore flag)
+        assert!(!locator.arm("t1", "codex", true, Some(TID), Some("/tmp")));
+        // missing / empty cwd
+        assert!(!locator.arm("t1", "codex", true, None, None));
+        assert!(!locator.arm("t1", "codex", true, None, Some("")));
+        // happy arm, then idempotent re-arm returns false
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(!locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn disarmed_terminal_never_resolves() {
+        let root = unique_temp_dir("disarm");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        locator.disarm("t1");
+        assert!(locator.tick(CODEX_WINDOW_MS + 1).is_empty());
+        assert_eq!(locator.armed_count(), 0);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn tick_while_unarmed_performs_zero_fs_scans() {
+        let root = unique_temp_dir("idle");
+        let locator = CodexLocator::new(root.clone());
+        // Construction must not scan eagerly either.
+        assert_eq!(locator.fs_scan_count(), 0);
+        assert!(locator.tick(10_000).is_empty());
+        assert_eq!(locator.fs_scan_count(), 0);
+        // Arming scans once (the known-files snapshot)…
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert_eq!(locator.fs_scan_count(), 1);
+        // …and a tick BEFORE any Enter-anchored deadline is due (here: no
+        // submit at all, so no deadline exists) still scans nothing.
+        let before = locator.fs_scan_count();
+        assert!(locator.tick(1).is_empty());
+        assert_eq!(locator.fs_scan_count(), before);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    const TID2: &str = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+
+    #[test]
+    fn rollout_present_at_arm_is_never_a_candidate() {
+        let root = unique_temp_dir("snapshot");
+        // File exists BEFORE arm — the known-files snapshot must exclude it
+        // forever, regardless of any timing.
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 1_000));
+        assert!(locator.tick(1_000 + CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1); // zero candidates → keep watching
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn foreign_cwd_rollout_is_never_a_candidate() {
+        let root = unique_temp_dir("cwd");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/home/me/project-a")));
+        assert!(locator.note_submit("t1", 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/home/me/project-b"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn rollout_without_cwd_field_never_binds() {
+        // cwd is REQUIRED (A4 hardening): `SessionMeta.cwd` is non-optional
+        // at codex 0.145.0 and 3,858/3,858 + 500/500 real rollouts carry it.
+        // A no-cwd first line is a foreign shape — accepting it would be
+        // pure attack surface (a location-blind universal candidate).
+        let root = unique_temp_dir("no-cwd");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        write_rollout(&root, "2026/07/26", TID, None);
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn two_new_rollouts_in_one_window_refuse_to_bind() {
+        let root = unique_temp_dir("ambiguous");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // Refusal marks the evaluation resolved but stays armed…
+        assert_eq!(locator.armed_count(), 1);
+        // …and a later Enter re-opens a fresh window (both files are now
+        // still absent from known_files, so still ambiguous — proves the
+        // refusal is repeatable, never a guess).
+        assert!(locator.note_submit("t1", CODEX_WINDOW_MS + 100));
+        assert!(locator
+            .tick(CODEX_WINDOW_MS + 100 + CODEX_WINDOW_MS)
+            .is_empty());
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn same_rollout_claimed_by_two_armed_terminals_refuses_both() {
+        let root = unique_temp_dir("contested");
+        let locator = CodexLocator::new(root.clone());
+        // Two panes, SAME cwd, armed concurrently, submitting in the same
+        // tick; ONE new rollout. The contested-cwd census refuses both
+        // (Pass 2's same-tick claim check remains as defense-in-depth).
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.arm("t2", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        assert!(locator.note_submit("t2", 0));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 2);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn staggered_same_cwd_armed_terminals_never_bind_uncontested() {
+        // Cross-tick contested guard (A4 hardening): ambiguity refusal must
+        // not be same-tick-only. While ≥2 ARMED terminals share a normalized
+        // cwd, NO candidate with that cwd binds for any of them — staggered
+        // deadlines must not let pane A grab pane B's rollout uncontested.
+        let root = unique_temp_dir("staggered");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.arm("t2", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        assert!(locator.note_submit("t2", 5_000));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        // t1's deadline fires alone: contested cwd → refuse.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // t2's deadline: still contested → refuse.
+        assert!(locator.tick(5_000 + CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 2);
+        // One pane exits (disarm); the survivor re-opens with a fresh Enter
+        // and may now bind — re-evaluation is legitimate once uncontested.
+        locator.disarm("t2");
+        assert!(locator.note_submit("t1", 10_000));
+        let located = locator.tick(10_000 + CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].terminal_id, "t1");
+        assert_eq!(located[0].thread_id, TID);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn zero_candidate_window_keeps_watching_and_later_enter_reopens() {
+        let root = unique_temp_dir("reopen");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        // Window closes with zero candidates → keep watching (stays armed).
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        // A later Enter re-opens; the rollout appears; resolves via the new
+        // Enter-anchored window.
+        let enter_at = 10 * CODEX_WINDOW_MS;
+        assert!(locator.note_submit("t1", enter_at));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let located = locator.tick(enter_at + CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn later_enter_reopen_keeps_the_first_submit_snapshot() {
+        // Slow materialization (>2 s Enter→creation) is recovered by a later
+        // Enter ONLY if re-opens never re-snapshot: the pane's own late
+        // rollout appears between the first window's close and the second
+        // Enter, and must STAY a candidate. Only the FIRST submit
+        // re-snapshots (pinned via fs_scan_count).
+        let root = unique_temp_dir("reopen-snapshot");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0)); // first submit: re-snapshot
+                                               // First window closes empty.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // The pane's own rollout lands LATE — after the window, before the
+        // next Enter.
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let scans_before = locator.fs_scan_count();
+        assert!(locator.note_submit("t1", 10_000)); // re-open: NO re-snapshot
+        assert_eq!(locator.fs_scan_count(), scans_before);
+        let located = locator.tick(10_000 + CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn mid_turn_enter_never_reopens_a_pending_evaluation() {
+        let root = unique_temp_dir("midturn");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 100));
+        // Second Enter while the first evaluation is still pending: no-op.
+        assert!(!locator.note_submit("t1", 200));
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn non_session_meta_or_malformed_first_line_is_never_a_candidate() {
+        // COMPLETE (newline-terminated) garbage lines are `Probe::Never` —
+        // not pending: codex writes the whole meta line + '\n' in one
+        // write-then-flush, so a complete non-candidate line never becomes
+        // one. (Empty/torn lines are the pending case — see the tests below.)
+        let root = unique_temp_dir("badmeta");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        std::fs::write(
+            dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl")),
+            format!(
+                "{}
+",
+                r#"{{"type":"event_msg","payload":{{"id":"{TID}"}}}}"#
+            ),
+        )
+        .unwrap();
+        std::fs::write(
+            dir.join(format!("rollout-2026-07-26T08-00-01-{TID2}.jsonl")),
+            "not json at all\n",
+        )
+        .unwrap();
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn empty_first_line_file_is_pending_and_binds_once_meta_lands() {
+        // A3 (validated): codex CREATES the rollout file, then awaits
+        // git-info collection (subprocesses, 5 s timeout each, worst ~10 s)
+        // BEFORE writing the session_meta first line. A deadline scan can
+        // observe the empty file — it must be a re-probed PENDING candidate,
+        // never dropped by a one-shot read.
+        let root = unique_temp_dir("pending");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        let file = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
+        std::fs::write(&file, "").unwrap(); // created, meta not yet written
+                                            // Deadline scan: pending candidate → bind NOTHING, stay unresolved.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        // Meta line lands (well within grace); the next sweep binds it.
+        // (write_rollout reuses the same filename — same ts, same TID.)
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let located = locator.tick(CODEX_WINDOW_MS + 300);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID);
+        assert_eq!(locator.armed_count(), 0);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn readable_candidate_never_binds_while_another_new_file_is_pending() {
+        // A4 (validated, CRITICAL): the pane's OWN rollout can sit
+        // unreadable in the git-info gap while a FOREIGN same-cwd rollout is
+        // already readable. Pending candidates are BIND-BLOCKING — the
+        // readable file must not win the window.
+        let root = unique_temp_dir("pending-block");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        // Pane's own file: created, first line not yet written.
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        let own = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
+        std::fs::write(&own, "").unwrap();
+        // Foreign file: fully readable, same cwd.
+        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
+        // Deadline: NOTHING binds while the pending file exists.
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        // Own meta line lands → TWO candidates → ambiguity refusal (fail
+        // toward refusal, never a guess).
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        assert!(locator.tick(CODEX_WINDOW_MS + 300).is_empty());
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn pending_file_that_never_parses_expires_after_grace() {
+        // Grace is bounded (A4 hardening 1): once PENDING_FIRST_LINE_GRACE_MS
+        // elapses without a readable first line, the file is permanently
+        // excluded and stops blocking; a surviving sole candidate may then
+        // bind.
+        let root = unique_temp_dir("pending-expiry");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        let dir = root.join("2026/07/26");
+        std::fs::create_dir_all(&dir).unwrap();
+        let own = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
+        std::fs::write(&own, "").unwrap(); // never gains a first line
+        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
+        // First due scan sees the pending file (grace clock starts here).
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
+        // Still blocked just before grace expiry…
+        assert!(locator
+            .tick(CODEX_WINDOW_MS + PENDING_FIRST_LINE_GRACE_MS - 1)
+            .is_empty());
+        // …then the never-parsed file expires and the sole survivor binds.
+        let located = locator.tick(CODEX_WINDOW_MS + PENDING_FIRST_LINE_GRACE_MS);
+        assert_eq!(located.len(), 1);
+        assert_eq!(located[0].thread_id, TID2);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn missing_sessions_root_is_tolerated_and_resolves_once_it_appears() {
+        let base = unique_temp_dir("missing-root");
+        let root = base.join("does-not-exist-yet");
+        let locator = CodexLocator::new(root.clone());
+        // arm() scans the missing root — tolerated, never a panic.
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        assert!(locator.tick(CODEX_WINDOW_MS).is_empty()); // no panic, keep watching
+        assert_eq!(locator.armed_count(), 1);
+        assert!(locator.note_submit("t1", 2 * CODEX_WINDOW_MS));
+        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
+        let located = locator.tick(3 * CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        let _ = std::fs::remove_dir_all(&base);
+    }
+
+    #[test]
+    fn flat_test_shape_rollout_resolves() {
+        // locate_codex_rollout supports flat `<id>.jsonl`; the locator's walk
+        // must too (integration fixtures seed this shape).
+        let root = unique_temp_dir("flat");
+        let locator = CodexLocator::new(root.clone());
+        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
+        assert!(locator.note_submit("t1", 0));
+        write_rollout(&root, ".", TID, Some("/tmp"));
+        let located = locator.tick(CODEX_WINDOW_MS);
+        assert_eq!(located.len(), 1);
+        let _ = std::fs::remove_dir_all(&root);
+    }
+}

From 043a934006741fdd10a97ab9cb6483f9d9f578f7 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:24:16 -0700
Subject: [PATCH 31/87] feat(ws): refuse sessionRef restore while a Running
 terminal owns the session (B3/P1.9, D7 guard)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every existing live-guard lives inside the createRequestId-keyed ladder
(resolve_claude_restore_session_id), which the direct wire-sessionRef
rung in handle_create bypasses entirely. The D5 recovery path re-mints
the createRequestId and carries identity ONLY in sessionRef, so a
session that went live between the inventory fetch and the user's
accept would silently spawn a duplicate `claude --resume S` while the
original live PTY owns S (one-JSONL-writer doctrine: silently wrong).

The new guard mirrors the ladder's A13 row-matching (identity-registry
owner check + REST-shaped live registry-row scan) but is mode-generic
(claude/codex/opencode/amplifier -- codex/opencode had no live-guard on
ANY path), applies only when the resume id was derived from the wire
sessionRef, and refuses with a loud RESTORE_UNAVAILABLE error frame
naming the live session.

Red-first integration test: tests/live_session_ref_guard.rs.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-ws/src/terminal.rs            |  55 ++++++++
 .../tests/live_session_ref_guard.rs           | 129 ++++++++++++++++++
 2 files changed, 184 insertions(+)
 create mode 100644 crates/freshell-ws/tests/live_session_ref_guard.rs

diff --git a/crates/freshell-ws/src/terminal.rs b/crates/freshell-ws/src/terminal.rs
index eec05ee2b..73edf3916 100644
--- a/crates/freshell-ws/src/terminal.rs
+++ b/crates/freshell-ws/src/terminal.rs
@@ -1116,6 +1116,61 @@ async fn handle_create(
         }
     }
 
+    // D7 liveness guard on the DIRECT wire-sessionRef rung (recover-my-panes
+    // Task 2b, defense-in-depth). Every other live-guard lives inside the
+    // createRequestId-keyed ladder (`resolve_claude_restore_session_id`), which
+    // the direct rung above bypasses entirely -- and the D5 recovery path
+    // re-mints the createRequestId, so a session that goes live between the
+    // inventory fetch and the user's accept would otherwise silently spawn a
+    // SECOND `<cli> --resume S` while the original live PTY owns S (the
+    // one-JSONL-writer doctrine: "silently wrong"). Mirrors the ladder's A13
+    // row-matching -- the identity-registry owner check plus the REST-shaped
+    // live-registry-row scan -- but MODE-GENERIC: codex/opencode/amplifier had
+    // no live-guard on ANY path, so this closes their gap too. Applies only
+    // when the resume id was derived from the wire `sessionRef` (the
+    // resumeSessionId fallback and ladder-resolved ids keep their existing
+    // guards).
+    if let Some(live_sid) = create
+        .session_ref
+        .as_ref()
+        .filter(|r| r.provider == mode)
+        .map(|r| r.session_id.as_str())
+        .filter(|sid| !sid.is_empty() && resume_session_id.as_deref() == Some(*sid))
+    {
+        let identity_owner_live =
+            state
+                .identity
+                .find_by_session(&mode, live_sid)
+                .is_some_and(|owner| {
+                    state
+                        .registry
+                        .probe(&owner.terminal_id)
+                        .is_some_and(|r| r.status == freshell_protocol::TerminalRunStatus::Running)
+                });
+        let registry_row_live = identity_owner_live
+            || state.registry.directory().into_iter().any(|entry| {
+                entry.mode == mode
+                    && entry.resume_session_id.as_deref() == Some(live_sid)
+                    && entry.status == freshell_protocol::TerminalRunStatus::Running
+            });
+        if registry_row_live {
+            tracing::warn!(
+                target: "freshell_ws::terminal",
+                mode = %mode,
+                session_id = %live_sid,
+                request_id = %create.request_id,
+                "create_refused: a Running terminal already owns this session (D7 live-guard)"
+            );
+            return send_create_error(
+                ws_tx,
+                ErrorCode::RestoreUnavailable,
+                format!("Session {live_sid} is still running on the server."),
+                &create.request_id,
+            )
+            .await;
+        }
+    }
+
     // Provider settings `codingCli.providers[mode]` (`ws:2317-2319`), with the
     // codex strip (`ws:2464-2465` — model/sandbox/permissionMode route to the
     // app-server plan instead). Boot-snapshot settings (same documented caveat
diff --git a/crates/freshell-ws/tests/live_session_ref_guard.rs b/crates/freshell-ws/tests/live_session_ref_guard.rs
new file mode 100644
index 000000000..f8ac14e95
--- /dev/null
+++ b/crates/freshell-ws/tests/live_session_ref_guard.rs
@@ -0,0 +1,129 @@
+//! Task 2b (recover-my-panes, D7 defense-in-depth): a `terminal.create` with
+//! `restore:true` + a wire `sessionRef` whose `(provider, sessionId)` is
+//! already owned by a currently-RUNNING terminal must be REFUSED loudly
+//! (`RESTORE_UNAVAILABLE`) — never a second `claude --resume S` while the
+//! original live PTY owns S (one-JSONL-writer doctrine, terminal.rs:933).
+//!
+//! Why the direct rung needs its own guard: every existing live-guard lives
+//! inside the createRequestId-keyed ladder (terminal.rs:1690-1745), and the
+//! direct wire-sessionRef rung (terminal.rs:1074-1078) bypasses the ladder
+//! entirely. The D5 recovery path re-mints the createRequestId and carries
+//! identity ONLY in `sessionRef`, so a session that goes live between the
+//! inventory fetch and the user's accept would silently double-spawn without
+//! this guard (the fetch→accept race client-side stripping cannot close).
+
+mod common;
+
+use common::{connect_and_capture_inventory, next_frame_of_type, session_ref_of, spawn_server};
+use futures_util::{SinkExt, StreamExt};
+use serde_json::json;
+use tokio_tungstenite::tungstenite::Message as WsMessage;
+
+async fn send_create(ws: &mut common::TestWs, body: serde_json::Value) {
+    ws.send(WsMessage::Text(body.to_string()))
+        .await
+        .expect("send terminal.create");
+}
+
+/// Read frames until either an `error` or a `terminal.created` correlated to
+/// `request_id` arrives. Returns the frame. Panics if a `terminal.created`
+/// for the request shows up — that IS the duplicate spawn this guard forbids.
+async fn expect_refusal_for(ws: &mut common::TestWs, request_id: &str) -> serde_json::Value {
+    for _ in 0..20u8 {
+        let msg = tokio::time::timeout(std::time::Duration::from_secs(5), ws.next())
+            .await
+            .expect("frame within timeout")
+            .expect("stream not ended")
+            .expect("no ws error");
+        if let WsMessage::Text(text) = &msg {
+            let value: serde_json::Value = serde_json::from_str(text).expect("json frame");
+            match value["type"].as_str() {
+                Some("terminal.created") if value["requestId"] == json!(request_id) => {
+                    panic!("duplicate spawn: create must be refused, got {value}");
+                }
+                Some("error") if value["requestId"] == json!(request_id) => {
+                    return value;
+                }
+                _ => {}
+            }
+        }
+    }
+    panic!("no error frame for {request_id} within 20 messages");
+}
+
+/// The D5 recovery wire shape against a LIVE session: restore:true +
+/// sessionRef owned by a currently-Running terminal, under a fresh
+/// (re-minted) requestId that has no ladder lineage. Must be refused loud;
+/// the registry must still hold exactly ONE terminal owning S.
+#[tokio::test]
+async fn live_session_ref_create_is_refused_loudly() {
+    let (url, registry) = spawn_server().await; // sleeper claude: stays Running
+    let (mut ws, _inv) = connect_and_capture_inventory(&url).await;
+
+    // A fresh claude terminal reaches Running, owning preallocated session S.
+    send_create(
+        &mut ws,
+        json!({
+            "type": "terminal.create",
+            "requestId": "req-live-owner-1",
+            "mode": "claude",
+            "shell": "system",
+            "cwd": std::env::temp_dir().to_string_lossy(),
+        }),
+    )
+    .await;
+    let created = next_frame_of_type(&mut ws, "terminal.created").await;
+    let tid1 = created["terminalId"]
+        .as_str()
+        .expect("terminalId")
+        .to_string();
+    let session_id = session_ref_of(&created).expect("fresh claude carries sessionRef")
+        ["sessionId"]
+        .as_str()
+        .expect("sessionId")
+        .to_string();
+
+    // The exact D5 recreation shape: fresh requestId (no lineage), restore,
+    // wire sessionRef pointing at the LIVE session.
+    send_create(
+        &mut ws,
+        json!({
+            "type": "terminal.create",
+            "requestId": "req-live-recreate-9f2a",
+            "mode": "claude",
+            "shell": "system",
+            "cwd": std::env::temp_dir().to_string_lossy(),
+            "restore": true,
+            "sessionRef": { "provider": "claude", "sessionId": session_id },
+        }),
+    )
+    .await;
+
+    let err = expect_refusal_for(&mut ws, "req-live-recreate-9f2a").await;
+    assert_eq!(
+        err["code"],
+        json!("RESTORE_UNAVAILABLE"),
+        "exact wire code: {err}"
+    );
+    let message = err["message"].as_str().expect("error message");
+    assert!(
+        message.contains(&session_id),
+        "message must name the live session {session_id}: {err}"
+    );
+
+    // No duplicate spawn: the registry still holds exactly ONE terminal, the
+    // original owner of S.
+    let rows = registry.identity_probe_rows();
+    assert_eq!(
+        rows.len(),
+        1,
+        "only the original live terminal may exist: {rows:?}"
+    );
+    assert_eq!(rows[0].terminal_id, tid1);
+    assert_eq!(
+        rows[0].resume_session_id.as_deref(),
+        Some(session_id.as_str())
+    );
+
+    registry.kill(&tid1);
+}

From fdf1c45dec107a09adbdb89c1f1b6c52ba88f9ab Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:24:45 -0700
Subject: [PATCH 32/87] chore: remove stray editor backup file committed by
 mistake

---
 .../src/codex_locator.rs.bak                  | 972 ------------------
 1 file changed, 972 deletions(-)
 delete mode 100644 crates/freshell-sessions/src/codex_locator.rs.bak

diff --git a/crates/freshell-sessions/src/codex_locator.rs.bak b/crates/freshell-sessions/src/codex_locator.rs.bak
deleted file mode 100644
index a31f20de1..000000000
--- a/crates/freshell-sessions/src/codex_locator.rs.bak
+++ /dev/null
@@ -1,972 +0,0 @@
-//! Server-side codex terminal-pane session locator (Lane B2, campaign §2.3.2).
-//!
-//! Third sibling of `amplifier_locator` / `opencode_locator` (a
-//! provider-parameterized locator was explicitly rejected — the substrates
-//! share zero code). Substrate: codex persists ONE JSONL rollout file per
-//! session under a process-global sessions root
-//! (`<CODEX_HOME|~/.codex>/sessions/YYYY/MM/DD/rollout-<ts>-<threadId>.jsonl`,
-//! flat `<id>.jsonl` in tests). A new session is a NEW FILE — so the locator
-//! does a snapshot-diff of the file set, not a row-diff.
-//!
-//! Codex-behavior facts below are validated against codex source @
-//! rust-v0.145.0 and a 3,858-rollout corpus; a codex upgrade re-opens them.
-//!
-//! Deliberate deviations from the opencode locator, with rationale:
-//! - Windows are ENTER-ANCHORED ONLY — no spawn window. Real codex defers
-//!   rollout file creation until the first user prompt is recorded
-//!   (`RolloutRecorder` defers to `persist()`, materialized via
-//!   `ensure_rollout_materialized()`), so before the pane's first Enter every
-//!   new same-cwd rollout is by construction FOREIGN. `arm()` takes the
-//!   known-files snapshot immediately but schedules NO deadline until
-//!   `note_submit`.
-//! - NO `pre_epsilon_ms` and NO created-at time bound: filesystems have no
-//!   reliable cross-platform creation time (mtime moves on every append).
-//!   The `known_files` snapshot is the primary safety — a file
-//!   already present in the snapshot can never bind to this terminal. The FILENAME
-//!   timestamp and the dated `YYYY/MM/DD` dir are never used as filters
-//!   either: both are precomputed at codex session construction and can
-//!   predate on-disk creation by the entire user idle gap (the dir can even
-//!   be "yesterday" across midnight). The full-tree snapshot-diff sidesteps
-//!   both.
-//! - FIRST-SUBMIT re-snapshot (A4 hardening): the first `note_submit`
-//!   replaces `known_files` with a fresh scan — strictly safe because the
-//!   pane's own rollout cannot exist before its first Enter, so everything
-//!   that appeared between arm and the first Enter is foreign by
-//!   construction. SOUNDNESS PRECONDITION: the caller completes the first
-//!   `note_submit` BEFORE the Enter byte is written to the PTY (codex
-//!   materializes the rollout in response to that very Enter) — the
-//!   `codex_association` submit seam encodes this ordering. Later window
-//!   re-opens NEVER re-snapshot: a >2 s Enter→creation latency is recovered
-//!   by a later Enter only if the pane's own late file stays a candidate.
-//! - Attribution disambiguator: the rollout's own first-line
-//!   `session_meta.payload.cwd` is REQUIRED and must match the armed
-//!   terminal's cwd (`SessionMeta.cwd` is non-optional at 0.145.0;
-//!   3,858/3,858 real rollouts carry it — accepting a no-cwd line would be
-//!   pure foreign attack surface). `payload.cwd` is the codex process's
-//!   physical `getcwd` path recorded verbatim; equality holds because
-//!   `normalize_cwd` opportunistically canonicalizes the pane side — that
-//!   canonicalize is load-bearing for symlinked spawn dirs.
-//! - Pending first-line grace: codex CREATES the file, then awaits git-info
-//!   collection (subprocesses, 5 s timeout each, worst ~10 s) BEFORE writing
-//!   the `session_meta` line. A NEW file whose first line is empty/incomplete
-//!   is a PENDING candidate: re-probed each sweep up to
-//!   `PENDING_FIRST_LINE_GRACE_MS`, and while ANY pending candidate exists
-//!   this terminal binds NOTHING (bind-blocking — a readable foreign file
-//!   must not win while the pane's own file sits in its git-info gap).
-//!   Enter→creation latency beyond the 2 s window is mitigated by this grace
-//!   plus window re-open on a later Enter.
-//! - Contested-cwd refusal is CROSS-TICK: while ≥2 armed terminals share a
-//!   normalized cwd, no candidate with that cwd binds for any of them.
-//! - Ownership is proven ONLY by `payload.id` on line 1 — NEVER the filename
-//!   (prefilter-grade at best), NEVER `payload.session_id` (fork/resume
-//!   LINEAGE: matches a FOREIGN session in 54/144 sampled real rollouts) —
-//!   same predicate as `freshell-ws`'s `first_line_owns`.
-//! - Resumed codex sessions append to their EXISTING rollout file (no new
-//!   file) — consistent with the arm gate refusing resume panes. Compressed
-//!   artifacts (`.jsonl.zst`, present in 0.145.0 source) fail the `.jsonl`
-//!   suffix filter; fresh sessions always write plain `.jsonl`.
-//!
-//! Zero cost when idle: scans happen only at arm, at the FIRST `note_submit`
-//! (the re-snapshot), and at due Enter-anchored
-//! evaluations (a pending candidate keeps its evaluation due, so re-probes
-//! ride the same gate), proven by `fs_scan_count`. Callers run `arm()`,
-//! `note_submit()`, and `tick()` inside `tokio::task::spawn_blocking` (cold
-//! dentry cache is the one unmeasured tail — A6).
-
-use std::collections::{HashMap, HashSet};
-use std::path::{Path, PathBuf};
-use std::sync::atomic::{AtomicU64, Ordering};
-use std::sync::Mutex;
-
-use crate::opencode_locator::normalize_cwd;
-
-/// Correlation window after a submit (Enter-anchored deadline). There is NO
-/// spawn-anchored window: real codex (0.145.0) creates the rollout file only
-/// when the first user prompt is recorded, so before the pane's first Enter
-/// every new same-cwd rollout is by construction foreign.
-pub const CODEX_WINDOW_MS: i64 = 2_000;
-
-/// Bounded re-probe grace for a NEW file whose first line is not yet
-/// readable: codex creates the file, then awaits git-info collection
-/// (subprocesses, 5 s timeout each, worst ~10 s) before writing the
-/// `session_meta` line. Matches codex's worst case and the magnitude of the
-/// existing `IDENTITY_RESOLUTION_GRACE_MS`.
-pub const PENDING_FIRST_LINE_GRACE_MS: i64 = 10_000;
-
-/// Bounded first-line read cap — real rollouts reach 152 MB; observed real
-/// first lines are ≤ 22.4 KB. Mirrors `codex_reconcile.rs`.
-const MAX_FIRST_LINE_BYTES: u64 = 1024 * 1024;
-
-/// Bounded walk depth — `sessions/YYYY/MM/DD/` is depth 3; 5 mirrors
-/// `locate_codex_rollout`.
-const MAX_WALK_DEPTH: u8 = 5;
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct Located {
-    pub terminal_id: String,
-    pub thread_id: String,
-    pub rollout_path: PathBuf,
-    pub cwd: String,
-}
-
-#[derive(Debug, Clone)]
-struct Armed {
-    cwd_normalized: String,
-    known_files: HashSet<PathBuf>,
-    enter_ms: Option<i64>,
-    resolved: bool,
-    /// NEW files whose first line was empty/incomplete when probed, keyed to
-    /// first-seen ms. While any un-expired entry exists, this terminal binds
-    /// NOTHING (bind-blocking); entries older than
-    /// `PENDING_FIRST_LINE_GRACE_MS` are merged into `known_files`
-    /// (permanently excluded — fail toward refusal).
-    pending_first_line: HashMap<PathBuf, i64>,
-}
-
-#[derive(Default)]
-struct Inner {
-    armed: HashMap<String, Armed>,
-}
-
-pub struct CodexLocator {
-    sessions_root: PathBuf,
-    window_ms: i64,
-    inner: Mutex<Inner>,
-    fs_scan_count: AtomicU64,
-}
-
-impl CodexLocator {
-    pub fn new(sessions_root: PathBuf) -> Self {
-        Self::with_config(sessions_root, CODEX_WINDOW_MS)
-    }
-
-    pub fn with_config(sessions_root: PathBuf, window_ms: i64) -> Self {
-        Self {
-            sessions_root,
-            window_ms,
-            inner: Mutex::new(Inner::default()),
-            fs_scan_count: AtomicU64::new(0),
-        }
-    }
-
-    pub fn armed_count(&self) -> usize {
-        self.inner.lock().unwrap().armed.len()
-    }
-
-    pub fn fs_scan_count(&self) -> u64 {
-        self.fs_scan_count.load(Ordering::SeqCst)
-    }
-
-    /// Admission rules (mirrors `OpencodeLocator::arm`): codex mode, running,
-    /// NO resume id (the only already-bound gate — never a restore flag, so
-    /// restore-created identity-less panes re-arm for free), non-empty cwd,
-    /// not already armed. On success takes the arm-time known-files snapshot.
-    /// Arming schedules NO deadline — windows open only on `note_submit`
-    /// (Enter-anchored; see module doc).
-    pub fn arm(
-        &self,
-        terminal_id: &str,
-        mode: &str,
-        status_running: bool,
-        resume_session_id: Option<&str>,
-        cwd: Option<&str>,
-    ) -> bool {
-        if mode != "codex" || !status_running || resume_session_id.is_some() {
-            return false;
-        }
-        let Some(cwd) = cwd.filter(|c| !c.is_empty()) else {
-            return false;
-        };
-        let mut inner = self.inner.lock().unwrap();
-        if inner.armed.contains_key(terminal_id) {
-            return false;
-        }
-        let known_files = self.scan_rollout_files();
-        inner.armed.insert(
-            terminal_id.to_string(),
-            Armed {
-                cwd_normalized: normalize_cwd(cwd),
-                known_files,
-                enter_ms: None,
-                resolved: false,
-                pending_first_line: HashMap::new(),
-            },
-        );
-        true
-    }
-
-    pub fn disarm(&self, terminal_id: &str) {
-        self.inner.lock().unwrap().armed.remove(terminal_id);
-    }
-
-    /// The FIRST submit is what opens a window at all (windows are
-    /// Enter-anchored — arm schedules no deadline), and it RE-SNAPSHOTS
-    /// `known_files` (see module doc: strictly safe because the pane's own
-    /// rollout cannot exist before its first Enter; the caller must complete
-    /// this call BEFORE the Enter byte reaches the PTY, and must run it on
-    /// the blocking pool — the re-snapshot walks the sessions tree).
-    /// Re-open semantics mirror
-    /// opencode: a mid-turn Enter never re-opens a still-pending evaluation;
-    /// a resolved (zero-candidate / ambiguous / contested) terminal gets a
-    /// fresh Enter-anchored deadline. Re-opens NEVER re-snapshot.
-    pub fn note_submit(&self, terminal_id: &str, at_ms: i64) -> bool {
-        let mut inner = self.inner.lock().unwrap();
-        let Some(armed) = inner.armed.get_mut(terminal_id) else {
-            return false;
-        };
-        if !armed.resolved && armed.enter_ms.is_some() {
-            return false;
-        }
-        if armed.enter_ms.is_none() {
-            // FIRST submit: everything that appeared between arm and this
-            // Enter is foreign by construction (A1/A4) — replace the
-            // snapshot. Holding the lock across the scan is deliberate and
-            // bounded (warm walks are 7-9 ms — A6; callers are on the
-            // blocking pool); it also keeps the re-snapshot atomic with the
-            // window open.
-            armed.known_files = self.scan_rollout_files();
-        }
-        armed.enter_ms = Some(at_ms);
-        armed.resolved = false;
-        true
-    }
-
-    /// A terminal is due only when an Enter-anchored deadline exists and has
-    /// passed. No submit -> no window -> never evaluated (see module doc).
-    fn due(&self, armed: &Armed, now_ms: i64) -> bool {
-        matches!(armed.enter_ms, Some(enter_ms) if !armed.resolved && now_ms >= enter_ms + self.window_ms)
-    }
-
-    /// Evaluation at (or after) an Enter-anchored deadline. Outcomes:
-    /// - any NEW file with an empty/incomplete first line (codex's
-    ///   create→session_meta git-info gap) → PENDING: bind NOTHING for this
-    ///   terminal, stay unresolved, re-probe each sweep up to
-    ///   `PENDING_FIRST_LINE_GRACE_MS` (grace-expired files are permanently
-    ///   excluded);
-    /// - 0 candidates → keep watching (stays armed, `resolved = true`);
-    /// - 2+ candidates for one terminal → WARN + refuse (never guess);
-    /// - exactly one candidate but ≥2 ARMED terminals share this cwd → WARN +
-    ///   refuse (contested cwd — cross-tick, so staggered deadlines can't
-    ///   grab a sibling's rollout uncontested);
-    /// - one candidate claimed by ≥2 terminals in the same tick → WARN +
-    ///   refuse ALL claimants (defense-in-depth behind the cwd census);
-    /// - exactly one clean match → emit `Located` and disarm. `tick()` drains.
-    pub fn tick(&self, now_ms: i64) -> Vec<Located> {
-        {
-            let inner = self.inner.lock().unwrap();
-            if inner.armed.is_empty() {
-                return Vec::new();
-            }
-            if !inner.armed.values().any(|a| self.due(a, now_ms)) {
-                return Vec::new();
-            }
-        }
-        let current = self.scan_rollout_files();
-        let mut inner = self.inner.lock().unwrap();
-
-        // Cross-tick contested-cwd census over ALL armed terminals (not just
-        // the due ones): two armed same-cwd panes are indistinguishable on
-        // this substrate, whatever their deadlines.
-        let mut cwd_counts: HashMap<String, usize> = HashMap::new();
-        for a in inner.armed.values() {
-            *cwd_counts.entry(a.cwd_normalized.clone()).or_insert(0) += 1;
-        }
-
-        // Pass 1: per-terminal candidate evaluation.
-        let mut claims: Vec<(String, Located)> = Vec::new();
-        for (terminal_id, armed) in inner.armed.iter_mut() {
-            if !matches!(armed.enter_ms, Some(e) if !armed.resolved && now_ms >= e + self.window_ms)
-            {
-                continue;
-            }
-            let new_paths: Vec<PathBuf> = current.difference(&armed.known_files).cloned().collect();
-            let mut matches: Vec<(PathBuf, RolloutMeta)> = Vec::new();
-            let mut pending_blocking = false;
-            for path in new_paths {
-                match probe_rollout(&path) {
-                    Probe::Candidate(meta) => {
-                        armed.pending_first_line.remove(&path);
-                        if normalize_cwd(&meta.cwd) == armed.cwd_normalized {
-                            matches.push((path, meta));
-                        }
-                    }
-                    Probe::NotYet => {
-                        let first_seen = *armed
-                            .pending_first_line
-                            .entry(path.clone())
-                            .or_insert(now_ms);
-                        if now_ms - first_seen >= PENDING_FIRST_LINE_GRACE_MS {
-                            // Grace exhausted: permanently excluded (fail
-                            // toward refusal — A4 hardening 1).
-                            armed.pending_first_line.remove(&path);
-                            armed.known_files.insert(path);
-                        } else {
-                            pending_blocking = true;
-                        }
-                    }
-                    Probe::Never => {}
-                }
-            }
-            if pending_blocking {
-                // A new file is still inside codex's create→session_meta gap
-                // (git-info collection, worst ~10 s). It may be THIS pane's
-                // rollout — binding any other candidate now could hand the
-                // window to a foreign file while the true owner is unreadable.
-                // Bind nothing, stay unresolved, re-probe next sweep.
-                tracing::debug!(
-                    terminal_id = %terminal_id,
-                    "codex_locator_pending: new rollout first line not yet readable; deferring evaluation"
-                );
-                continue;
-            }
-            armed.resolved = true;
-            match matches.len() {
-                0 => {} // keep watching
-                1 => {
-                    if cwd_counts.get(&armed.cwd_normalized).copied().unwrap_or(0) >= 2 {
-                        tracing::warn!(
-                            terminal_id = %terminal_id,
-                            "codex_locator_contested_cwd: >=2 armed terminals share this cwd; refusing to bind"
-                        );
-                    } else {
-                        let (path, meta) = matches.remove(0);
-                        claims.push((
-                            terminal_id.clone(),
-                            Located {
-                                terminal_id: terminal_id.clone(),
-                                thread_id: meta.thread_id,
-                                rollout_path: path,
-                                cwd: armed.cwd_normalized.clone(),
-                            },
-                        ));
-                    }
-                }
-                n => {
-                    tracing::warn!(
-                        terminal_id = %terminal_id,
-                        candidates = n,
-                        "codex_locator_ambiguous: multiple new rollouts in one window; refusing to bind"
-                    );
-                }
-            }
-        }
-
-        // Pass 2: same-tick cross-terminal conflict — the same rollout (or
-        // thread id) claimed by two armed terminals in one tick is
-        // unattributable. (Defense-in-depth: the contested-cwd census above
-        // already refuses same-cwd claimants across ticks.)
-        let mut located = Vec::new();
-        for (terminal_id, candidate) in &claims {
-            let contested = claims.iter().any(|(other_tid, other)| {
-                other_tid != terminal_id
-                    && (other.rollout_path == candidate.rollout_path
-                        || other.thread_id == candidate.thread_id)
-            });
-            if contested {
-                tracing::warn!(
-                    terminal_id = %terminal_id,
-                    thread_id = %candidate.thread_id,
-                    "codex_locator_contested: rollout claimed by multiple armed terminals; refusing to bind"
-                );
-                continue;
-            }
-            located.push(candidate.clone());
-        }
-        for l in &located {
-            inner.armed.remove(&l.terminal_id);
-        }
-        located
-    }
-
-    fn scan_rollout_files(&self) -> HashSet<PathBuf> {
-        self.fs_scan_count.fetch_add(1, Ordering::SeqCst);
-        fn walk(dir: &Path, depth: u8, out: &mut HashSet<PathBuf>) {
-            if depth > MAX_WALK_DEPTH {
-                return;
-            }
-            let Ok(entries) = std::fs::read_dir(dir) else {
-                return; // missing/corrupt root tolerated, never a panic
-            };
-            for entry in entries.flatten() {
-                let path = entry.path();
-                if path.is_dir() {
-                    walk(&path, depth + 1, out);
-                } else if path
-                    .file_name()
-                    .and_then(|n| n.to_str())
-                    .map(|n| n.ends_with(".jsonl"))
-                    .unwrap_or(false)
-                {
-                    out.insert(path);
-                }
-            }
-        }
-        let mut out = HashSet::new();
-        walk(&self.sessions_root, 0, &mut out);
-        out
-    }
-}
-
-struct RolloutMeta {
-    thread_id: String,
-    /// REQUIRED — `SessionMeta.cwd` is non-optional at codex 0.145.0
-    /// (3,858/3,858 real rollouts carry it); a no-cwd first line is a
-    /// foreign shape, never a candidate (A4 hardening).
-    cwd: String,
-}
-
-/// Tri-state probe result. The distinction between `NotYet` and `Never` is
-/// load-bearing: codex writes the whole session_meta line + '\n' in one
-/// write-then-flush, so a COMPLETE (newline-terminated) line that fails the
-/// candidate shape will never become one, while an empty file or a line
-/// without its trailing newline is codex's create→meta gap (or a raced
-/// write) — "not yet", not "never" (A3, validated).
-enum Probe {
-    /// Parseable `session_meta` with a bare-UUID `payload.id` AND a
-    /// `payload.cwd` — a real candidate shape.
-    Candidate(RolloutMeta),
-    /// Empty file, transient open/read failure, or first line still missing
-    /// its trailing newline — re-probe within the pending grace.
-    NotYet,
-    /// Complete first line that is not a codex session_meta candidate
-    /// (non-JSON, wrong type, non-UUID id, missing cwd, oversized) — never
-    /// a candidate; the locator stays silent on foreign files.
-    Never,
-}
-
-/// Identity probe: bounded first-line read (see `Probe` for the tri-state
-/// semantics).
-fn probe_rollout(path: &Path) -> Probe {
-    use std::io::{BufRead, Read};
-    let Ok(file) = std::fs::File::open(path) else {
-        return Probe::NotYet;
-    };
-    let mut reader = std::io::BufReader::new(file).take(MAX_FIRST_LINE_BYTES);
-    let mut first_line = Vec::new();
-    if reader.read_until(b'\n', &mut first_line).is_err() {
-        return Probe::NotYet;
-    }
-    if first_line.len() as u64 >= MAX_FIRST_LINE_BYTES && !first_line.ends_with(b"\n") {
-        return Probe::Never; // oversized: will never fit the cap
-    }
-    if first_line.is_empty() || !first_line.ends_with(b"\n") {
-        return Probe::NotYet; // create→meta gap, or a raced partial write
-    }
-    let Ok(record) = serde_json::from_slice::<serde_json::Value>(&first_line) else {
-        return Probe::Never;
-    };
-    if record.get("type").and_then(|v| v.as_str()) != Some("session_meta") {
-        return Probe::Never;
-    }
-    let Some(thread_id) = record.pointer("/payload/id").and_then(|v| v.as_str()) else {
-        return Probe::Never;
-    };
-    if !is_uuid_shaped(thread_id) {
-        return Probe::Never;
-    }
-    let Some(cwd) = record.pointer("/payload/cwd").and_then(|v| v.as_str()) else {
-        return Probe::Never; // cwd REQUIRED (A4 hardening)
-    };
-    Probe::Candidate(RolloutMeta {
-        thread_id: thread_id.to_string(),
-        cwd: cwd.to_string(),
-    })
-}
-
-/// Bare hyphenated 36-char UUID shape gate (deliberate small duplicate of
-/// `freshell-ws`'s predicate — this crate sits below it in the dep graph).
-fn is_uuid_shaped(s: &str) -> bool {
-    let bytes = s.as_bytes();
-    if bytes.len() != 36 {
-        return false;
-    }
-    for (i, b) in bytes.iter().enumerate() {
-        let is_hyphen_pos = matches!(i, 8 | 13 | 18 | 23);
-        if is_hyphen_pos {
-            if *b != b'-' {
-                return false;
-            }
-        } else if !b.is_ascii_hexdigit() {
-            return false;
-        }
-    }
-    true
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use std::path::{Path, PathBuf};
-    use std::sync::atomic::{AtomicU64, Ordering};
-
-    static TEST_DIR_COUNTER: AtomicU64 = AtomicU64::new(0);
-
-    /// Same convention as opencode_locator.rs tests: no tempfile crate.
-    fn unique_temp_dir(label: &str) -> PathBuf {
-        let n = TEST_DIR_COUNTER.fetch_add(1, Ordering::SeqCst);
-        let dir = std::env::temp_dir().join(format!(
-            "freshell-codex-locator-test-{label}-{}-{n}",
-            std::process::id()
-        ));
-        std::fs::create_dir_all(&dir).expect("create test dir");
-        dir
-    }
-
-    /// Write a rollout file whose FIRST line is the session_meta identity
-    /// record, exactly the shape the real codex CLI writes
-    /// (payload.id = identity; payload.cwd = the session's working dir).
-    fn write_rollout(root: &Path, rel_dir: &str, thread_id: &str, cwd: Option<&str>) -> PathBuf {
-        let dir = root.join(rel_dir);
-        std::fs::create_dir_all(&dir).expect("create rollout dir");
-        let file = dir.join(format!("rollout-2026-07-26T08-00-00-{thread_id}.jsonl"));
-        let payload = match cwd {
-            Some(c) => format!(r#"{{"id":"{thread_id}","cwd":"{c}"}}"#),
-            None => format!(r#"{{"id":"{thread_id}"}}"#),
-        };
-        let line = format!(
-            r#"{{"timestamp":"2026-07-26T08:00:00.000Z","type":"session_meta","payload":{payload}}}"#
-        );
-        std::fs::write(&file, format!("{line}\n")).expect("write rollout");
-        file
-    }
-
-    const TID: &str = "11111111-2222-3333-4444-555555555555";
-
-    #[test]
-    fn fresh_rollout_after_first_enter_resolves_via_enter_window() {
-        let root = unique_temp_dir("enter-happy");
-        let cwd = root.join("project");
-        std::fs::create_dir_all(&cwd).unwrap();
-        let cwd_s = cwd.to_string_lossy().to_string();
-        let locator = CodexLocator::new(root.clone());
-
-        assert!(locator.arm("t1", "codex", true, None, Some(&cwd_s)));
-        // No submit yet -> no deadline exists; nothing to evaluate.
-        assert!(locator.tick(10_000).is_empty());
-        // Enter at 20_000; the rollout appears AFTER the submit (real codex
-        // materializes the file only when the first user prompt is recorded).
-        assert!(locator.note_submit("t1", 20_000));
-        let path = write_rollout(&root, "2026/07/26", TID, Some(&cwd_s));
-
-        // Before the Enter-anchored deadline: nothing yet.
-        assert!(locator.tick(20_000 + CODEX_WINDOW_MS - 1).is_empty());
-        let located = locator.tick(20_000 + CODEX_WINDOW_MS);
-        assert_eq!(
-            located,
-            vec![Located {
-                terminal_id: "t1".into(),
-                thread_id: TID.into(),
-                rollout_path: path,
-                cwd: crate::opencode_locator::normalize_cwd(&cwd_s),
-            }]
-        );
-        // Success fully resolves and disarms; tick() drains.
-        assert_eq!(locator.armed_count(), 0);
-        assert!(locator.tick(20_000 + CODEX_WINDOW_MS + 1).is_empty());
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn rollout_after_arm_without_submit_is_never_bound_and_never_scanned() {
-        // A1 (validated): real codex creates the rollout ONLY at the first
-        // user prompt, so before Enter every new same-cwd rollout is by
-        // construction FOREIGN. With no submit there is NO window: the file
-        // must never bind and no deadline scans may run.
-        let root = unique_temp_dir("no-submit");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert_eq!(locator.fs_scan_count(), 1); // the arm snapshot
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        assert!(locator.tick(100 * CODEX_WINDOW_MS).is_empty());
-        assert_eq!(locator.armed_count(), 1);
-        assert_eq!(locator.fs_scan_count(), 1); // still only the arm snapshot
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn rollout_created_between_arm_and_first_enter_never_binds() {
-        // A4 hardening (first-submit re-snapshot): Premise 7 guarantees the
-        // pane's own rollout cannot exist before its first Enter, so EVERY
-        // file that appears between arm and the first submit is foreign by
-        // construction (freshagent sidecar, `codex exec`, codex outside
-        // freshell in the same cwd). The FIRST note_submit re-snapshots
-        // known_files, so a bare Enter (empty composer, trust dialog) can
-        // never hand the window to that foreign file as a sole candidate.
-        let root = unique_temp_dir("resnapshot");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        // Foreign rollout lands AFTER arm but BEFORE the first Enter.
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        assert!(locator.note_submit("t1", 1_000)); // first submit re-snapshots
-        assert_eq!(locator.fs_scan_count(), 2); // arm + first-submit scans
-        assert!(locator.tick(1_000 + CODEX_WINDOW_MS).is_empty());
-        assert_eq!(locator.armed_count(), 1); // zero candidates → keep watching
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn arm_admission_gates() {
-        let root = unique_temp_dir("gates");
-        let locator = CodexLocator::new(root.clone());
-        // wrong mode
-        assert!(!locator.arm("t1", "opencode", true, None, Some("/tmp")));
-        // not running
-        assert!(!locator.arm("t1", "codex", false, None, Some("/tmp")));
-        // resume id present — the ONLY already-bound gate (no restore flag)
-        assert!(!locator.arm("t1", "codex", true, Some(TID), Some("/tmp")));
-        // missing / empty cwd
-        assert!(!locator.arm("t1", "codex", true, None, None));
-        assert!(!locator.arm("t1", "codex", true, None, Some("")));
-        // happy arm, then idempotent re-arm returns false
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(!locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert_eq!(locator.armed_count(), 1);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn disarmed_terminal_never_resolves() {
-        let root = unique_temp_dir("disarm");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        locator.disarm("t1");
-        assert!(locator.tick(CODEX_WINDOW_MS + 1).is_empty());
-        assert_eq!(locator.armed_count(), 0);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn tick_while_unarmed_performs_zero_fs_scans() {
-        let root = unique_temp_dir("idle");
-        let locator = CodexLocator::new(root.clone());
-        // Construction must not scan eagerly either.
-        assert_eq!(locator.fs_scan_count(), 0);
-        assert!(locator.tick(10_000).is_empty());
-        assert_eq!(locator.fs_scan_count(), 0);
-        // Arming scans once (the known-files snapshot)…
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert_eq!(locator.fs_scan_count(), 1);
-        // …and a tick BEFORE any Enter-anchored deadline is due (here: no
-        // submit at all, so no deadline exists) still scans nothing.
-        let before = locator.fs_scan_count();
-        assert!(locator.tick(1).is_empty());
-        assert_eq!(locator.fs_scan_count(), before);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    const TID2: &str = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
-
-    #[test]
-    fn rollout_present_at_arm_is_never_a_candidate() {
-        let root = unique_temp_dir("snapshot");
-        // File exists BEFORE arm — the known-files snapshot must exclude it
-        // forever, regardless of any timing.
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 1_000));
-        assert!(locator.tick(1_000 + CODEX_WINDOW_MS).is_empty());
-        assert_eq!(locator.armed_count(), 1); // zero candidates → keep watching
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn foreign_cwd_rollout_is_never_a_candidate() {
-        let root = unique_temp_dir("cwd");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/home/me/project-a")));
-        assert!(locator.note_submit("t1", 0));
-        write_rollout(&root, "2026/07/26", TID, Some("/home/me/project-b"));
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        assert_eq!(locator.armed_count(), 1);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn rollout_without_cwd_field_never_binds() {
-        // cwd is REQUIRED (A4 hardening): `SessionMeta.cwd` is non-optional
-        // at codex 0.145.0 and 3,858/3,858 + 500/500 real rollouts carry it.
-        // A no-cwd first line is a foreign shape — accepting it would be
-        // pure attack surface (a location-blind universal candidate).
-        let root = unique_temp_dir("no-cwd");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        write_rollout(&root, "2026/07/26", TID, None);
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        assert_eq!(locator.armed_count(), 1);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn two_new_rollouts_in_one_window_refuse_to_bind() {
-        let root = unique_temp_dir("ambiguous");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        // Refusal marks the evaluation resolved but stays armed…
-        assert_eq!(locator.armed_count(), 1);
-        // …and a later Enter re-opens a fresh window (both files are now
-        // still absent from known_files, so still ambiguous — proves the
-        // refusal is repeatable, never a guess).
-        assert!(locator.note_submit("t1", CODEX_WINDOW_MS + 100));
-        assert!(locator
-            .tick(CODEX_WINDOW_MS + 100 + CODEX_WINDOW_MS)
-            .is_empty());
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn same_rollout_claimed_by_two_armed_terminals_refuses_both() {
-        let root = unique_temp_dir("contested");
-        let locator = CodexLocator::new(root.clone());
-        // Two panes, SAME cwd, armed concurrently, submitting in the same
-        // tick; ONE new rollout. The contested-cwd census refuses both
-        // (Pass 2's same-tick claim check remains as defense-in-depth).
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.arm("t2", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        assert!(locator.note_submit("t2", 0));
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        assert_eq!(locator.armed_count(), 2);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn staggered_same_cwd_armed_terminals_never_bind_uncontested() {
-        // Cross-tick contested guard (A4 hardening): ambiguity refusal must
-        // not be same-tick-only. While ≥2 ARMED terminals share a normalized
-        // cwd, NO candidate with that cwd binds for any of them — staggered
-        // deadlines must not let pane A grab pane B's rollout uncontested.
-        let root = unique_temp_dir("staggered");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.arm("t2", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        assert!(locator.note_submit("t2", 5_000));
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        // t1's deadline fires alone: contested cwd → refuse.
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        // t2's deadline: still contested → refuse.
-        assert!(locator.tick(5_000 + CODEX_WINDOW_MS).is_empty());
-        assert_eq!(locator.armed_count(), 2);
-        // One pane exits (disarm); the survivor re-opens with a fresh Enter
-        // and may now bind — re-evaluation is legitimate once uncontested.
-        locator.disarm("t2");
-        assert!(locator.note_submit("t1", 10_000));
-        let located = locator.tick(10_000 + CODEX_WINDOW_MS);
-        assert_eq!(located.len(), 1);
-        assert_eq!(located[0].terminal_id, "t1");
-        assert_eq!(located[0].thread_id, TID);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn zero_candidate_window_keeps_watching_and_later_enter_reopens() {
-        let root = unique_temp_dir("reopen");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        // Window closes with zero candidates → keep watching (stays armed).
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        assert_eq!(locator.armed_count(), 1);
-        // A later Enter re-opens; the rollout appears; resolves via the new
-        // Enter-anchored window.
-        let enter_at = 10 * CODEX_WINDOW_MS;
-        assert!(locator.note_submit("t1", enter_at));
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        let located = locator.tick(enter_at + CODEX_WINDOW_MS);
-        assert_eq!(located.len(), 1);
-        assert_eq!(located[0].thread_id, TID);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn later_enter_reopen_keeps_the_first_submit_snapshot() {
-        // Slow materialization (>2 s Enter→creation) is recovered by a later
-        // Enter ONLY if re-opens never re-snapshot: the pane's own late
-        // rollout appears between the first window's close and the second
-        // Enter, and must STAY a candidate. Only the FIRST submit
-        // re-snapshots (pinned via fs_scan_count).
-        let root = unique_temp_dir("reopen-snapshot");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0)); // first submit: re-snapshot
-                                               // First window closes empty.
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        // The pane's own rollout lands LATE — after the window, before the
-        // next Enter.
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        let scans_before = locator.fs_scan_count();
-        assert!(locator.note_submit("t1", 10_000)); // re-open: NO re-snapshot
-        assert_eq!(locator.fs_scan_count(), scans_before);
-        let located = locator.tick(10_000 + CODEX_WINDOW_MS);
-        assert_eq!(located.len(), 1);
-        assert_eq!(located[0].thread_id, TID);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn mid_turn_enter_never_reopens_a_pending_evaluation() {
-        let root = unique_temp_dir("midturn");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 100));
-        // Second Enter while the first evaluation is still pending: no-op.
-        assert!(!locator.note_submit("t1", 200));
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn non_session_meta_or_malformed_first_line_is_never_a_candidate() {
-        // COMPLETE (newline-terminated) garbage lines are `Probe::Never` —
-        // not pending: codex writes the whole meta line + '\n' in one
-        // write-then-flush, so a complete non-candidate line never becomes
-        // one. (Empty/torn lines are the pending case — see the tests below.)
-        let root = unique_temp_dir("badmeta");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        let dir = root.join("2026/07/26");
-        std::fs::create_dir_all(&dir).unwrap();
-        std::fs::write(
-            dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl")),
-            format!(
-                "{}
-",
-                r#"{{"type":"event_msg","payload":{{"id":"{TID}"}}}}"#
-            ),
-        )
-        .unwrap();
-        std::fs::write(
-            dir.join(format!("rollout-2026-07-26T08-00-01-{TID2}.jsonl")),
-            "not json at all\n",
-        )
-        .unwrap();
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        assert_eq!(locator.armed_count(), 1);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn empty_first_line_file_is_pending_and_binds_once_meta_lands() {
-        // A3 (validated): codex CREATES the rollout file, then awaits
-        // git-info collection (subprocesses, 5 s timeout each, worst ~10 s)
-        // BEFORE writing the session_meta first line. A deadline scan can
-        // observe the empty file — it must be a re-probed PENDING candidate,
-        // never dropped by a one-shot read.
-        let root = unique_temp_dir("pending");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        let dir = root.join("2026/07/26");
-        std::fs::create_dir_all(&dir).unwrap();
-        let file = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
-        std::fs::write(&file, "").unwrap(); // created, meta not yet written
-                                            // Deadline scan: pending candidate → bind NOTHING, stay unresolved.
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        assert_eq!(locator.armed_count(), 1);
-        // Meta line lands (well within grace); the next sweep binds it.
-        // (write_rollout reuses the same filename — same ts, same TID.)
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        let located = locator.tick(CODEX_WINDOW_MS + 300);
-        assert_eq!(located.len(), 1);
-        assert_eq!(located[0].thread_id, TID);
-        assert_eq!(locator.armed_count(), 0);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn readable_candidate_never_binds_while_another_new_file_is_pending() {
-        // A4 (validated, CRITICAL): the pane's OWN rollout can sit
-        // unreadable in the git-info gap while a FOREIGN same-cwd rollout is
-        // already readable. Pending candidates are BIND-BLOCKING — the
-        // readable file must not win the window.
-        let root = unique_temp_dir("pending-block");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        // Pane's own file: created, first line not yet written.
-        let dir = root.join("2026/07/26");
-        std::fs::create_dir_all(&dir).unwrap();
-        let own = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
-        std::fs::write(&own, "").unwrap();
-        // Foreign file: fully readable, same cwd.
-        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
-        // Deadline: NOTHING binds while the pending file exists.
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        assert_eq!(locator.armed_count(), 1);
-        // Own meta line lands → TWO candidates → ambiguity refusal (fail
-        // toward refusal, never a guess).
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        assert!(locator.tick(CODEX_WINDOW_MS + 300).is_empty());
-        assert_eq!(locator.armed_count(), 1);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn pending_file_that_never_parses_expires_after_grace() {
-        // Grace is bounded (A4 hardening 1): once PENDING_FIRST_LINE_GRACE_MS
-        // elapses without a readable first line, the file is permanently
-        // excluded and stops blocking; a surviving sole candidate may then
-        // bind.
-        let root = unique_temp_dir("pending-expiry");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        let dir = root.join("2026/07/26");
-        std::fs::create_dir_all(&dir).unwrap();
-        let own = dir.join(format!("rollout-2026-07-26T08-00-00-{TID}.jsonl"));
-        std::fs::write(&own, "").unwrap(); // never gains a first line
-        write_rollout(&root, "2026/07/26", TID2, Some("/tmp"));
-        // First due scan sees the pending file (grace clock starts here).
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty());
-        // Still blocked just before grace expiry…
-        assert!(locator
-            .tick(CODEX_WINDOW_MS + PENDING_FIRST_LINE_GRACE_MS - 1)
-            .is_empty());
-        // …then the never-parsed file expires and the sole survivor binds.
-        let located = locator.tick(CODEX_WINDOW_MS + PENDING_FIRST_LINE_GRACE_MS);
-        assert_eq!(located.len(), 1);
-        assert_eq!(located[0].thread_id, TID2);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-
-    #[test]
-    fn missing_sessions_root_is_tolerated_and_resolves_once_it_appears() {
-        let base = unique_temp_dir("missing-root");
-        let root = base.join("does-not-exist-yet");
-        let locator = CodexLocator::new(root.clone());
-        // arm() scans the missing root — tolerated, never a panic.
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        assert!(locator.tick(CODEX_WINDOW_MS).is_empty()); // no panic, keep watching
-        assert_eq!(locator.armed_count(), 1);
-        assert!(locator.note_submit("t1", 2 * CODEX_WINDOW_MS));
-        write_rollout(&root, "2026/07/26", TID, Some("/tmp"));
-        let located = locator.tick(3 * CODEX_WINDOW_MS);
-        assert_eq!(located.len(), 1);
-        let _ = std::fs::remove_dir_all(&base);
-    }
-
-    #[test]
-    fn flat_test_shape_rollout_resolves() {
-        // locate_codex_rollout supports flat `<id>.jsonl`; the locator's walk
-        // must too (integration fixtures seed this shape).
-        let root = unique_temp_dir("flat");
-        let locator = CodexLocator::new(root.clone());
-        assert!(locator.arm("t1", "codex", true, None, Some("/tmp")));
-        assert!(locator.note_submit("t1", 0));
-        write_rollout(&root, ".", TID, Some("/tmp"));
-        let located = locator.tick(CODEX_WINDOW_MS);
-        assert_eq!(located.len(), 1);
-        let _ = std::fs::remove_dir_all(&root);
-    }
-}

From 65d6662b20fca26bce0eb1c79eba5642e106fae7 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:25:46 -0700
Subject: [PATCH 33/87] feat(freshagent): PaneIdentitySink trait -
 crate-boundary bridge for the pane ledger (P1.13)

---
 crates/freshell-freshagent/src/claude.rs      |  20 +-
 crates/freshell-freshagent/src/codex.rs       |  20 +-
 .../freshell-freshagent/src/identity_sink.rs  | 197 ++++++++++++++++++
 crates/freshell-freshagent/src/lib.rs         |  23 ++
 crates/freshell-freshagent/src/opencode_ws.rs |  22 +-
 5 files changed, 279 insertions(+), 3 deletions(-)
 create mode 100644 crates/freshell-freshagent/src/identity_sink.rs

diff --git a/crates/freshell-freshagent/src/claude.rs b/crates/freshell-freshagent/src/claude.rs
index b4700bfe2..030457e95 100644
--- a/crates/freshell-freshagent/src/claude.rs
+++ b/crates/freshell-freshagent/src/claude.rs
@@ -60,7 +60,7 @@ use freshell_protocol::{
     FreshAgentSend, FreshAgentSendAccepted, ServerMessage, SessionType,
 };
 
-use crate::{FreshAgentCreateDedup, FreshAgentCreateOutcome};
+use crate::{FreshAgentCreateDedup, FreshAgentCreateOutcome, SharedPaneIdentitySink};
 
 /// The runtime provider (`AGENT_SESSION_TYPES.claude.provider`).
 const PROVIDER: &str = "claude";
@@ -97,6 +97,12 @@ pub struct FreshClaudeState {
     /// `resuming` analog, simplified: contenders return immediately instead of
     /// waiting -- the winner's frames broadcast to every client anyway).
     resuming: Arc<TokioMutex<std::collections::HashSet<String>>>,
+    /// P1.13 identity-event sink (the pane-ledger bridge,
+    /// [`crate::identity_sink`]). Clone-shared + set-once: the state is cloned
+    /// into consumer tasks, so the `OnceLock` sits behind an `Arc`. Wired
+    /// post-construction by `freshell-server` (precedent:
+    /// `TerminalRegistry::set_activity_observer`).
+    identity_sink: Arc<std::sync::OnceLock<SharedPaneIdentitySink>>,
 }
 
 /// The cached result of a completed claude/kilroy `freshAgent.create`, keyed by
@@ -142,9 +148,21 @@ impl FreshClaudeState {
             cli_index: Arc::new(TokioMutex::new(HashMap::new())),
             create_dedup: Arc::new(FreshAgentCreateDedup::new()),
             resuming: Arc::new(TokioMutex::new(std::collections::HashSet::new())),
+            identity_sink: Arc::new(std::sync::OnceLock::new()),
         }
     }
 
+    /// Wire the P1.13 identity-event sink (set-once; later calls are no-ops).
+    pub fn set_identity_sink(&self, sink: SharedPaneIdentitySink) {
+        let _ = self.identity_sink.set(sink);
+    }
+
+    /// The wired identity sink, if any.
+    #[allow(dead_code)] // used by identity-event tasks (Tasks 4-10)
+    fn identity_sink(&self) -> Option<SharedPaneIdentitySink> {
+        self.identity_sink.get().cloned()
+    }
+
     /// Reap every owned claude sidecar: SIGTERM the Node process (so it cleanly kills its
     /// own `claude` CLI via the SDK abort), SIGKILL any straggler, abort the consumer, and
     /// run the `/proc` ownership sweep for the grandchild. Called on server shutdown.
diff --git a/crates/freshell-freshagent/src/codex.rs b/crates/freshell-freshagent/src/codex.rs
index 2e469fc4e..96f4ebb1a 100644
--- a/crates/freshell-freshagent/src/codex.rs
+++ b/crates/freshell-freshagent/src/codex.rs
@@ -68,7 +68,7 @@ use freshell_protocol::{
     FreshAgentSend, FreshAgentSessionMaterialized, ServerMessage, SessionLocator,
 };
 
-use crate::{FreshAgentCreateDedup, FreshAgentCreateOutcome};
+use crate::{FreshAgentCreateDedup, FreshAgentCreateOutcome, SharedPaneIdentitySink};
 
 /// The codex fresh-agent `sessionType` (`AGENT_SESSION_TYPES.codex`).
 const SESSION_TYPE: &str = "freshcodex";
@@ -146,6 +146,12 @@ pub struct FreshCodexState {
     /// entries only on an explicit `freshAgent.kill` ([`Self::handle_kill`]); an
     /// unrequested sidecar exit does NOT evict (mirrors legacy, see the type doc).
     create_dedup: Arc<FreshAgentCreateDedup<CodexCreateRecord>>,
+    /// P1.13 identity-event sink (the pane-ledger bridge,
+    /// [`crate::identity_sink`]). Clone-shared + set-once: the state is cloned
+    /// into consumer tasks, so the `OnceLock` sits behind an `Arc`. Wired
+    /// post-construction by `freshell-server` (precedent:
+    /// `TerminalRegistry::set_activity_observer`).
+    identity_sink: Arc<std::sync::OnceLock<SharedPaneIdentitySink>>,
 }
 
 /// The cached result of a completed codex `freshAgent.create`, keyed by `requestId` in
@@ -272,9 +278,21 @@ impl FreshCodexState {
             dead_threads: Arc::new(TokioMutex::new(HashMap::new())),
             dead_thread_ttl: DEAD_THREAD_CACHE_TTL,
             create_dedup: Arc::new(FreshAgentCreateDedup::new()),
+            identity_sink: Arc::new(std::sync::OnceLock::new()),
         }
     }
 
+    /// Wire the P1.13 identity-event sink (set-once; later calls are no-ops).
+    pub fn set_identity_sink(&self, sink: SharedPaneIdentitySink) {
+        let _ = self.identity_sink.set(sink);
+    }
+
+    /// The wired identity sink, if any.
+    #[allow(dead_code)] // used by identity-event tasks (Tasks 4-10)
+    fn identity_sink(&self) -> Option<SharedPaneIdentitySink> {
+        self.identity_sink.get().cloned()
+    }
+
     /// The `PATCH /api/settings` sub-router (the fresh-clients enable toggle).
     pub fn settings_router(&self) -> Router {
         Router::new()
diff --git a/crates/freshell-freshagent/src/identity_sink.rs b/crates/freshell-freshagent/src/identity_sink.rs
new file mode 100644
index 000000000..db8640673
--- /dev/null
+++ b/crates/freshell-freshagent/src/identity_sink.rs
@@ -0,0 +1,197 @@
+//! P1.13 crate-boundary bridge: fresh-agent identity events flow OUT of this
+//! crate through this trait; `freshell-server` implements it over the pane
+//! ledger (this crate must not depend on `freshell-ws`, where the ledger
+//! lives — the dependency edge runs the other way).
+
+use std::sync::Arc;
+
+/// Resume-invocation record (campaign plan §4.2): exactly what the
+/// provider-native resume command needs.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct FreshAgentSettings {
+    pub model: Option<String>,
+    pub sandbox: Option<String>,
+    pub permission_mode: Option<String>,
+    pub effort: Option<String>,
+    pub cwd: Option<String>,
+}
+
+/// One fresh-agent identity event. Settings are a FULL snapshot (replace,
+/// not merge). `resolves_pending` names a pending marker (placeholder id)
+/// this binding supersedes.
+#[derive(Debug, Clone, PartialEq)]
+pub struct FreshAgentBindingUpsert {
+    pub provider: String,
+    pub session_id: String,
+    pub mode: String,
+    pub create_request_id: Option<String>,
+    pub resolves_pending: Option<String>,
+    /// G3 supersession (V8/A14): OLD session id this binding replaces
+    /// (codex crash-respawn passes the old thread id; everyone else None).
+    pub supersedes: Option<String>,
+    pub settings: FreshAgentSettings,
+}
+
+/// Write-completion future (see Interfaces block for the style citation:
+/// BoxFuture aliases at freshell-opencode/src/serve.rs:44 /
+/// freshell-codex/src/app_server.rs:62; no async-trait dep in the workspace).
+pub type SinkWrite =
+    std::pin::Pin<Box<dyn std::future::Future<Output = std::io::Result<()>> + Send + 'static>>;
+
+/// AWAITED writes (wave-A durable-before-answer policy, V8/A11): callers
+/// `.await` the returned future before replying/broadcasting/proceeding.
+/// Implementations run fsync work on `spawn_blocking` and propagate failures
+/// as `Err` — call sites surface them user-visibly, then proceed (a write
+/// failure never blocks the identity event). Reads are memory-fast + sync.
+pub trait PaneIdentitySink: Send + Sync {
+    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>) -> SinkWrite;
+    fn record_binding(&self, upsert: FreshAgentBindingUpsert) -> SinkWrite;
+    fn load_settings(&self, provider: &str, session_id: &str) -> Option<FreshAgentSettings>;
+    /// True iff a fresh-agent binding row was EVER recorded for this key —
+    /// the SETTINGS_RESET alarm gate (V7/A10): alarm only when the ledger
+    /// proves prior recording; never for never-recorded sessions.
+    fn was_recorded(&self, provider: &str, session_id: &str) -> bool;
+}
+
+pub type SharedPaneIdentitySink = Arc<dyn PaneIdentitySink>;
+
+/// In-memory sink for tests, crate-wide. Mutations happen synchronously
+/// before the (already-completed) future is returned, so tests can assert
+/// immediately after `.await`.
+#[cfg(test)]
+#[derive(Default)]
+pub(crate) struct FakeIdentitySink {
+    pub pendings: std::sync::Mutex<Vec<(String, String, Option<String>)>>,
+    pub bindings: std::sync::Mutex<Vec<FreshAgentBindingUpsert>>,
+    pub settings: std::sync::Mutex<std::collections::HashMap<(String, String), FreshAgentSettings>>,
+    /// Keys ever recorded (or seeded) — backs `was_recorded`.
+    pub recorded: std::sync::Mutex<std::collections::HashSet<(String, String)>>,
+    /// When true, write futures resolve to Err — for failure-surfacing tests.
+    pub fail_writes: std::sync::atomic::AtomicBool,
+}
+
+#[cfg(test)]
+impl FakeIdentitySink {
+    #[allow(dead_code)] // used by identity-event tasks (Tasks 4-10 tests)
+    pub fn seed(&self, provider: &str, session_id: &str, s: FreshAgentSettings) {
+        self.recorded
+            .lock()
+            .unwrap()
+            .insert((provider.into(), session_id.into()));
+        self.settings
+            .lock()
+            .unwrap()
+            .insert((provider.into(), session_id.into()), s);
+    }
+    /// Mark a key as previously recorded WITHOUT a recoverable snapshot —
+    /// the SETTINGS_RESET-alarm-positive fixture (V7/A10 gating).
+    #[allow(dead_code)] // used by identity-event tasks (Tasks 4-10 tests)
+    pub fn seed_recorded_only(&self, provider: &str, session_id: &str) {
+        self.recorded
+            .lock()
+            .unwrap()
+            .insert((provider.into(), session_id.into()));
+    }
+    fn write_result(&self) -> SinkWrite {
+        if self.fail_writes.load(std::sync::atomic::Ordering::SeqCst) {
+            Box::pin(std::future::ready(Err(std::io::Error::other(
+                "fake write failure",
+            ))))
+        } else {
+            Box::pin(std::future::ready(Ok(())))
+        }
+    }
+}
+
+#[cfg(test)]
+impl PaneIdentitySink for FakeIdentitySink {
+    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>) -> SinkWrite {
+        if !self.fail_writes.load(std::sync::atomic::Ordering::SeqCst) {
+            self.pendings.lock().unwrap().push((
+                placeholder_id.into(),
+                mode.into(),
+                cwd.map(Into::into),
+            ));
+        }
+        self.write_result()
+    }
+    fn record_binding(&self, upsert: FreshAgentBindingUpsert) -> SinkWrite {
+        if !self.fail_writes.load(std::sync::atomic::Ordering::SeqCst) {
+            self.recorded
+                .lock()
+                .unwrap()
+                .insert((upsert.provider.clone(), upsert.session_id.clone()));
+            self.settings.lock().unwrap().insert(
+                (upsert.provider.clone(), upsert.session_id.clone()),
+                upsert.settings.clone(),
+            );
+            self.bindings.lock().unwrap().push(upsert);
+        }
+        self.write_result()
+    }
+    fn load_settings(&self, provider: &str, session_id: &str) -> Option<FreshAgentSettings> {
+        self.settings
+            .lock()
+            .unwrap()
+            .get(&(provider.into(), session_id.into()))
+            .cloned()
+    }
+    fn was_recorded(&self, provider: &str, session_id: &str) -> bool {
+        self.recorded
+            .lock()
+            .unwrap()
+            .contains(&(provider.into(), session_id.into()))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+
+    #[tokio::test]
+    async fn fake_sink_records_and_serves_settings() {
+        let fake = Arc::new(FakeIdentitySink::default());
+        fake.record_pending("freshopencode-r1", "freshopencode", Some("/w"))
+            .await
+            .expect("pending write ok");
+        fake.record_binding(FreshAgentBindingUpsert {
+            provider: "opencode".into(),
+            session_id: "ses_1".into(),
+            mode: "freshopencode".into(),
+            create_request_id: Some("r1".into()),
+            resolves_pending: Some("freshopencode-r1".into()),
+            supersedes: None,
+            settings: FreshAgentSettings {
+                model: Some("m".into()),
+                sandbox: None,
+                permission_mode: None,
+                effort: Some("low".into()),
+                cwd: Some("/w".into()),
+            },
+        })
+        .await
+        .expect("binding write ok");
+        let s = fake.load_settings("opencode", "ses_1").expect("settings");
+        assert_eq!(s.model.as_deref(), Some("m"));
+        assert_eq!(s.effort.as_deref(), Some("low"));
+        assert_eq!(fake.pendings.lock().unwrap().len(), 1);
+        assert_eq!(fake.bindings.lock().unwrap().len(), 1);
+        assert!(fake.load_settings("opencode", "nope").is_none());
+        assert!(fake.was_recorded("opencode", "ses_1"));
+        assert!(!fake.was_recorded("opencode", "nope"));
+    }
+
+    #[tokio::test]
+    async fn fake_sink_failure_knob_returns_err() {
+        let fake = Arc::new(FakeIdentitySink::default());
+        fake.fail_writes
+            .store(true, std::sync::atomic::Ordering::SeqCst);
+        assert!(
+            fake.record_pending("p", "freshopencode", None)
+                .await
+                .is_err(),
+            "failure must surface as Err, never be swallowed"
+        );
+    }
+}
diff --git a/crates/freshell-freshagent/src/lib.rs b/crates/freshell-freshagent/src/lib.rs
index a0c1a406a..9b56cf8d5 100644
--- a/crates/freshell-freshagent/src/lib.rs
+++ b/crates/freshell-freshagent/src/lib.rs
@@ -39,6 +39,7 @@
 pub mod claude;
 pub(crate) mod claude_snapshot;
 pub mod codex;
+pub mod identity_sink;
 pub mod opencode_ws;
 pub mod pane_ops;
 pub mod snapshot;
@@ -46,6 +47,10 @@ pub mod terminal_tabs;
 
 pub use claude::FreshClaudeState;
 pub use codex::FreshCodexState;
+pub use identity_sink::{
+    FreshAgentBindingUpsert, FreshAgentSettings, PaneIdentitySink, SharedPaneIdentitySink,
+    SinkWrite,
+};
 pub use opencode_ws::FreshOpencodeState;
 pub use snapshot::SnapshotState;
 
@@ -171,6 +176,11 @@ pub struct FreshAgentState {
     /// restore fix -- the SAME shared instance
     /// `freshell_ws::opencode_association::maybe_arm` arms.
     pub(crate) opencode_locator: Option<Arc<freshell_sessions::opencode_locator::OpencodeLocator>>,
+    /// P1.13 identity-event sink (the pane-ledger bridge, [`identity_sink`]).
+    /// Clone-shared + set-once: the state is cloned into consumer tasks, so
+    /// the `OnceLock` sits behind an `Arc`. Wired post-construction by
+    /// `freshell-server` (precedent: `TerminalRegistry::set_activity_observer`).
+    identity_sink: Arc<std::sync::OnceLock<SharedPaneIdentitySink>>,
 }
 
 /// A fresh-agent pane (the `paneContent` subset the opencode T2 path needs).
@@ -235,9 +245,22 @@ impl FreshAgentState {
             cli_commands: Arc::new(Vec::new()),
             amplifier_locator: None,
             opencode_locator: None,
+            identity_sink: Arc::new(std::sync::OnceLock::new()),
         }
     }
 
+    /// Wire the P1.13 identity-event sink (set-once; later calls are no-ops).
+    pub fn set_identity_sink(&self, sink: SharedPaneIdentitySink) {
+        let _ = self.identity_sink.set(sink);
+    }
+
+    /// The wired identity sink, if any. Used by identity-event tasks
+    /// (the REST send-keys materialization site, Task 7).
+    #[allow(dead_code)] // used by identity-event tasks (Tasks 4-10)
+    fn identity_sink(&self) -> Option<SharedPaneIdentitySink> {
+        self.identity_sink.get().cloned()
+    }
+
     /// Record what a `restoreKey`-tagged create produced (continuity trio,
     /// `tabs_snapshots.rs:632`). Called by `terminal_tabs`'s create paths
     /// immediately after the tab/pane maps are populated, so a restore retry
diff --git a/crates/freshell-freshagent/src/opencode_ws.rs b/crates/freshell-freshagent/src/opencode_ws.rs
index d3042eacb..b3acfb6fc 100644
--- a/crates/freshell-freshagent/src/opencode_ws.rs
+++ b/crates/freshell-freshagent/src/opencode_ws.rs
@@ -74,7 +74,9 @@ use freshell_protocol::{
     FreshAgentSessionMaterialized, ServerMessage, SessionLocator,
 };
 
-use crate::{FreshAgentCreateDedup, FreshAgentCreateOutcome, FreshAgentState};
+use crate::{
+    FreshAgentCreateDedup, FreshAgentCreateOutcome, FreshAgentState, SharedPaneIdentitySink,
+};
 
 /// The opencode fresh-agent `sessionType` (`AGENT_SESSION_TYPES.opencode`).
 const SESSION_TYPE: &str = "freshopencode";
@@ -102,6 +104,12 @@ pub struct FreshOpencodeState {
     /// [`OpencodeSession`] object. Cleared for a session's entries only on an explicit
     /// `freshAgent.kill` ([`Self::handle_kill`]).
     create_dedup: Arc<FreshAgentCreateDedup<OpencodeCreateRecord>>,
+    /// P1.13 identity-event sink (the pane-ledger bridge,
+    /// [`crate::identity_sink`]). Clone-shared + set-once: the state is cloned
+    /// into consumer tasks, so the `OnceLock` sits behind an `Arc`. Wired
+    /// post-construction by `freshell-server` (precedent:
+    /// `TerminalRegistry::set_activity_observer`).
+    identity_sink: Arc<std::sync::OnceLock<SharedPaneIdentitySink>>,
 }
 
 /// The cached result of a completed opencode `freshAgent.create`, keyed by `requestId` in
@@ -188,9 +196,21 @@ impl FreshOpencodeState {
             fresh_agent,
             sessions: Arc::new(TokioMutex::new(HashMap::new())),
             create_dedup: Arc::new(FreshAgentCreateDedup::new()),
+            identity_sink: Arc::new(std::sync::OnceLock::new()),
         }
     }
 
+    /// Wire the P1.13 identity-event sink (set-once; later calls are no-ops).
+    pub fn set_identity_sink(&self, sink: SharedPaneIdentitySink) {
+        let _ = self.identity_sink.set(sink);
+    }
+
+    /// The wired identity sink, if any.
+    #[allow(dead_code)] // used by identity-event tasks (Tasks 4-10)
+    fn identity_sink(&self) -> Option<SharedPaneIdentitySink> {
+        self.identity_sink.get().cloned()
+    }
+
     fn broadcast(&self, msg: &ServerMessage) {
         self.fresh_agent.broadcast(msg);
     }

From 88a339331196094efa099ca5ff28a4abb1506a69 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:25:59 -0700
Subject: [PATCH 34/87] feat(ws): per-sessionRef single-flight on the create
 path with SESSION_RESERVED + registry bind (closes D8 server-side)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Council rules 6/7/8 wired into terminal.create for paneReconcileV1-negotiated
connections (Task 6 of the reconcile-client-adoption plan):

- protocol: SESSION_RESERVED error code + additive retryAfterMs on ErrorMsg
  (skip_serializing_if — every other error frame stays byte-identical)
- create path: claim_session_ref before the rate limiter; BoundElsewhere
  attaches to the winner (adopt-style emission, spawn nothing); Held answers
  error{SESSION_RESERVED, requestId, retryAfterMs} without charging the rate
  limiter (create_protection adopt precedent); ExpiredNeedsKill kills the
  holder via the REGISTRY handle (group-kill discipline), confirms ESRCH
  <=500ms, then force-releases and re-claims — unconfirmed holds closed
- winner path: pid recorded on the lease immediately post-spawn;
  complete_session_ref_claim at winner bind records the registry
  sessionRef->terminalId binding (the pane-ledger write is pre-existing
  create-path behavior, not duplicated); revoked-lease completes kill the
  just-spawned child + fail loud; spawn-duration tracing::info at bind
- RAII SessionRefLeaseGuard releases the lease on every non-complete exit
  (pre-spawn errors, spawn failure, cancellation)
- conn-close cleanup: release_session_ref_leases_for_conn + kill-confirm
  discipline for pid-carrying entries
- registry: SESSION_REF_LEASE_TTL_MS env-tunable via
  FRESHELL_SESSION_REF_LEASE_TTL_MS (sanitizing parse, spawn-gate-timeout
  shape); pid_of/live_terminal_for_pid/pid_alive/bound_terminal_for_session_ref
  accessors for the kill-before-release paths and test probes
- legacy (non-negotiated) connections byte-for-byte unchanged, pinned by test

TDD: tests/session_ref_singleflight.rs written first — RED showed both
creates spawning two PTYs and no registry binding; GREEN all 3 pass; full
freshell-ws suite (incl. create_protection + pane_reconcile), terminal/
protocol/freshagent suites, fmt and clippy -D warnings all green.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-freshagent/src/claude.rs      |   1 +
 crates/freshell-freshagent/src/codex.rs       |   1 +
 crates/freshell-freshagent/src/opencode_ws.rs |   1 +
 crates/freshell-protocol/src/common.rs        |   5 +
 .../freshell-protocol/src/server_messages.rs  |   5 +
 crates/freshell-terminal/src/registry.rs      |  74 ++++-
 crates/freshell-ws/src/lib.rs                 |   1 +
 crates/freshell-ws/src/terminal.rs            | 287 +++++++++++++++++-
 .../tests/session_ref_singleflight.rs         | 226 ++++++++++++++
 9 files changed, 599 insertions(+), 2 deletions(-)
 create mode 100644 crates/freshell-ws/tests/session_ref_singleflight.rs

diff --git a/crates/freshell-freshagent/src/claude.rs b/crates/freshell-freshagent/src/claude.rs
index b4700bfe2..d2b34f17a 100644
--- a/crates/freshell-freshagent/src/claude.rs
+++ b/crates/freshell-freshagent/src/claude.rs
@@ -569,6 +569,7 @@ impl FreshClaudeState {
             actual_session_ref: None,
             expected_session_ref: None,
             request_id: request_id.clone(),
+            retry_after_ms: None,
             terminal_exit_code: None,
             terminal_id: None,
         }));
diff --git a/crates/freshell-freshagent/src/codex.rs b/crates/freshell-freshagent/src/codex.rs
index 2e469fc4e..4763d0d23 100644
--- a/crates/freshell-freshagent/src/codex.rs
+++ b/crates/freshell-freshagent/src/codex.rs
@@ -817,6 +817,7 @@ impl FreshCodexState {
             actual_session_ref: None,
             expected_session_ref: None,
             request_id: request_id.clone(),
+            retry_after_ms: None,
             terminal_exit_code: None,
             terminal_id: None,
         }));
diff --git a/crates/freshell-freshagent/src/opencode_ws.rs b/crates/freshell-freshagent/src/opencode_ws.rs
index d3042eacb..8e2dd2816 100644
--- a/crates/freshell-freshagent/src/opencode_ws.rs
+++ b/crates/freshell-freshagent/src/opencode_ws.rs
@@ -203,6 +203,7 @@ impl FreshOpencodeState {
             actual_session_ref: None,
             expected_session_ref: None,
             request_id: request_id.clone(),
+            retry_after_ms: None,
             terminal_exit_code: None,
             terminal_id: None,
         }));
diff --git a/crates/freshell-protocol/src/common.rs b/crates/freshell-protocol/src/common.rs
index 5bfeb584a..58a6bb199 100644
--- a/crates/freshell-protocol/src/common.rs
+++ b/crates/freshell-protocol/src/common.rs
@@ -94,6 +94,11 @@ pub enum ErrorCode {
     /// failed (poisoned lock, index handle error). The client keeps its state
     /// and may re-send.
     ReconcileUnavailable,
+    /// D8 per-sessionRef single-flight (council rules 6/7/8): another create
+    /// for the same sessionRef is in flight on a `paneReconcileV1`-negotiated
+    /// connection. The loser retries after the frame's `retryAfterMs` hint —
+    /// by then it either adopts the winner's terminal or wins the next claim.
+    SessionReserved,
 }
 
 /// The coding-agent providers (`claude | codex | opencode | amplifier`).
diff --git a/crates/freshell-protocol/src/server_messages.rs b/crates/freshell-protocol/src/server_messages.rs
index 240d8c032..eb744821a 100644
--- a/crates/freshell-protocol/src/server_messages.rs
+++ b/crates/freshell-protocol/src/server_messages.rs
@@ -512,6 +512,11 @@ pub struct ErrorMsg {
     pub expected_session_ref: Option<SessionLocator>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub request_id: Option<String>,
+    /// D8 (`SESSION_RESERVED` only): how long the loser should wait before
+    /// re-sending its create. Additive and omitted everywhere else, so every
+    /// other error frame stays byte-identical on the wire.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub retry_after_ms: Option<u64>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub terminal_exit_code: Option<i64>,
     #[serde(skip_serializing_if = "Option::is_none")]
diff --git a/crates/freshell-terminal/src/registry.rs b/crates/freshell-terminal/src/registry.rs
index 92be44d66..83dbc453b 100644
--- a/crates/freshell-terminal/src/registry.rs
+++ b/crates/freshell-terminal/src/registry.rs
@@ -414,6 +414,43 @@ const DEFAULT_RESPAWN_GENERATION_CAP: i64 = 3;
 pub const SESSION_REF_LEASE_TTL_MS: u64 = 20_000;
 pub const SESSION_RESERVED_RETRY_AFTER_MS: u64 = 1_000;
 
+/// The effective lease TTL: `FRESHELL_SESSION_REF_LEASE_TTL_MS` when set to a
+/// positive integer, else [`SESSION_REF_LEASE_TTL_MS`]. Same sanitizing-parse
+/// shape as the spawn-gate timeout's `FRESHELL_SPAWN_GATE_TIMEOUT_MS`
+/// (`freshell-ws/src/create_limit.rs`) — unset/unparseable/zero → default.
+/// Kept next to the const so the client's re-drive window derivation
+/// (Task 12: window > TTL + margin) stays visible in one place.
+pub fn session_ref_lease_ttl_ms() -> u64 {
+    std::env::var("FRESHELL_SESSION_REF_LEASE_TTL_MS")
+        .ok()
+        .and_then(|v| v.parse::<u64>().ok())
+        .filter(|&v| v > 0)
+        .unwrap_or(SESSION_REF_LEASE_TTL_MS)
+}
+
+/// Whether `pid` is still alive (`kill(pid, 0)`): the ESRCH death-confirm
+/// probe of the kill-before-release discipline (council rule 8). Only ESRCH
+/// confirms death — EPERM (or any other errno) reports ALIVE, so an
+/// uncertain probe can never release a lease it shouldn't. Non-unix: PTY
+/// pids are never recorded there ([`crate::pty::PtyTerminal::pid`] is
+/// `None`), so no pid-carrying lease can exist and this is unreachable.
+pub fn pid_alive(pid: u32) -> bool {
+    #[cfg(unix)]
+    {
+        // SAFETY: signal 0 performs existence/permission checking only; no
+        // signal is delivered.
+        if unsafe { libc::kill(pid as libc::pid_t, 0) } == 0 {
+            return true;
+        }
+        std::io::Error::last_os_error().raw_os_error() != Some(libc::ESRCH)
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = pid;
+        false
+    }
+}
+
 /// Outcome of [`TerminalRegistry::claim_session_ref`] (council rule 7, D8:
 /// one in-flight create per sessionRef, liveness-bound).
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -1775,7 +1812,7 @@ impl TerminalRegistry {
                 SessionRefClaim::Acquired
             }
             Some(lease) => {
-                let expired = now_ms > lease.acquired_at_ms + SESSION_REF_LEASE_TTL_MS;
+                let expired = now_ms > lease.acquired_at_ms + session_ref_lease_ttl_ms();
                 if !expired {
                     return SessionRefClaim::Held {
                         retry_after_ms: SESSION_RESERVED_RETRY_AFTER_MS,
@@ -1920,6 +1957,41 @@ impl TerminalRegistry {
             .remove(&session_ref_key(locator));
     }
 
+    /// The terminalId a completed claim bound this sessionRef to
+    /// ([`Self::complete_session_ref_claim`]), if any — the read side of the
+    /// registry binding map (Task 6 winner bind; also a test probe).
+    pub fn bound_terminal_for_session_ref(&self, locator: &SessionLocator) -> Option<String> {
+        self.session_ref_bindings
+            .lock()
+            .expect("session-ref bindings lock")
+            .get(&session_ref_key(locator))
+            .cloned()
+    }
+
+    /// The live child pid behind `terminal_id`'s PTY handle (unix only;
+    /// `None` for headless/exited terminals). Task 6: the winner records this
+    /// on its sessionRef lease ([`Self::set_session_ref_lease_pid`]).
+    pub fn pid_of(&self, terminal_id: &str) -> Option<u32> {
+        let inner = self.inner.lock().expect("registry lock");
+        inner
+            .terminals
+            .get(terminal_id)
+            .and_then(|h| h.pty.as_ref())
+            .and_then(|p| p.pid())
+    }
+
+    /// The terminal whose PTY handle carries `pid`. The kill-before-release
+    /// paths (lease TTL expiry, holder conn death) must kill through the
+    /// REGISTRY handle ([`Self::kill`] → group-kill discipline, `pty.rs`) —
+    /// NEVER a raw single-pid SIGKILL — so they resolve the recorded pid back
+    /// to its owning terminal first.
+    pub fn live_terminal_for_pid(&self, pid: u32) -> Option<String> {
+        let inner = self.inner.lock().expect("registry lock");
+        inner.terminals.iter().find_map(|(id, h)| {
+            (h.pty.as_ref().and_then(|p| p.pid()) == Some(pid)).then(|| id.clone())
+        })
+    }
+
     /// §5.4 backstop detector (always-on, capability-independent): if a key
     /// now has two or more LIVE terminals, make it loud — two live PTYs on one
     /// `createRequestId` means two JSONL writers on one session file.
diff --git a/crates/freshell-ws/src/lib.rs b/crates/freshell-ws/src/lib.rs
index 4323a3b89..c94611ea0 100644
--- a/crates/freshell-ws/src/lib.rs
+++ b/crates/freshell-ws/src/lib.rs
@@ -673,6 +673,7 @@ async fn send_error(
         actual_session_ref: None,
         expected_session_ref: None,
         request_id: None,
+        retry_after_ms: None,
         terminal_exit_code: None,
         terminal_id: None,
     });
diff --git a/crates/freshell-ws/src/terminal.rs b/crates/freshell-ws/src/terminal.rs
index 6e10e1b9c..485da7ca5 100644
--- a/crates/freshell-ws/src/terminal.rs
+++ b/crates/freshell-ws/src/terminal.rs
@@ -436,6 +436,24 @@ pub async fn run(
         state.screenshots.remove_capable_client(conn_id);
     }
     state.registry.remove_connection(conn_id);
+
+    // D8 conn-death lease release (council rule 8): pid-less in-flight leases
+    // are released inside the registry call; pid-carrying ones come back
+    // STILL-HELD — kill via the registry handle, confirm, then force-release
+    // (kill-before-release). Unconfirmed kills hold the lease closed.
+    for (locator, pid) in state.registry.release_session_ref_leases_for_conn(conn_id) {
+        let Some(pid) = pid else { continue };
+        if kill_session_ref_holder_and_confirm(&state.registry, pid).await {
+            state.registry.force_release_after_confirmed_kill(&locator);
+        } else {
+            tracing::error!(target: "invariant",
+                connection_id = conn_id,
+                provider = %locator.provider,
+                session_id = %locator.session_id,
+                pid,
+                "session_ref_lease_conn_death_kill_unconfirmed: holding lease closed");
+        }
+    }
 }
 
 /// Parse + dispatch one inbound client text frame. Returns `false` to close the
@@ -506,7 +524,15 @@ async fn handle_client_text(
         }
         ClientMessage::ClientDiagnostic(_) => true,
         ClientMessage::TerminalCreate(create) => {
-            handle_create(create, ws_tx, state, pane_reconcile_v1, create_limiter).await
+            handle_create(
+                create,
+                ws_tx,
+                state,
+                conn_id,
+                pane_reconcile_v1,
+                create_limiter,
+            )
+            .await
         }
         // P0.3: server-side codex identity capture from the client's persisted
         // candidate -- guarded (campaign plan §2.3.1); rejects are logged and
@@ -915,6 +941,115 @@ impl Drop for KeyedCreateGuard {
     }
 }
 
+/// The sessionRef a create claims at spawn time (council rule 7, D8), when
+/// resolvable from the create BODY alone: a non-shell mode whose session id
+/// comes from `sessionRef` (provider must match the mode — the same filter
+/// as the resume derivation in `handle_create`) or the legacy
+/// `resumeSessionId`. Later-resolved identities (fresh-claude preallocation,
+/// the P0.4 restore ladder) are freshly minted or single-source and carry no
+/// concurrent-duplicate shape, so they claim nothing.
+fn create_session_locator(create: &TerminalCreate) -> Option<SessionLocator> {
+    if create.mode == "shell" {
+        return None;
+    }
+    let session_id = create
+        .session_ref
+        .as_ref()
+        .filter(|r| r.provider == create.mode)
+        .map(|r| r.session_id.clone())
+        .or_else(|| create.resume_session_id.clone())
+        .filter(|s| !s.is_empty())?;
+    Some(SessionLocator {
+        provider: create.mode.clone(),
+        session_id,
+    })
+}
+
+/// RAII release of a D8 sessionRef lease claim
+/// ([`freshell_terminal::TerminalRegistry::claim_session_ref`] →
+/// `Acquired`): on EVERY non-complete exit of `handle_create` — pre-spawn
+/// error, spawn failure, or task cancellation — drop releases the lease via
+/// `fail_session_ref_claim` (a no-op once `complete_session_ref_claim`
+/// removed it). The winner path disarms and completes explicitly.
+struct SessionRefLeaseGuard {
+    registry: freshell_terminal::TerminalRegistry,
+    locator: SessionLocator,
+    holder_create_request_id: String,
+    claimed_at_ms: i64,
+    armed: bool,
+}
+
+impl SessionRefLeaseGuard {
+    /// Hand ownership of the release decision back to the caller (winner
+    /// bind or the revoked-lease kill path).
+    fn disarm(mut self) -> (SessionLocator, i64) {
+        self.armed = false;
+        (self.locator.clone(), self.claimed_at_ms)
+    }
+}
+
+impl Drop for SessionRefLeaseGuard {
+    fn drop(&mut self) {
+        if self.armed {
+            self.registry
+                .fail_session_ref_claim(&self.locator, &self.holder_create_request_id);
+        }
+    }
+}
+
+/// Poll `kill(pid, 0)` for ESRCH for up to 500ms (the PTY's dedicated waiter
+/// thread reaps promptly — `pty.rs` reader/waiter). `true` = death CONFIRMED.
+async fn confirm_pid_dead_within_500ms(pid: u32) -> bool {
+    for _ in 0..20u8 {
+        if !freshell_terminal::registry::pid_alive(pid) {
+            return true;
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(25)).await;
+    }
+    !freshell_terminal::registry::pid_alive(pid)
+}
+
+/// Kill-before-release (council rule 8): kill a lease holder's spawn via the
+/// REGISTRY PTY handle ([`freshell_terminal::TerminalRegistry::kill`] —
+/// group-kill discipline, `pty.rs`; NEVER a raw single-pid SIGKILL), then
+/// confirm death. `true` = confirmed dead — only then may the caller
+/// `force_release_after_confirmed_kill`. Unconfirmed (or a pid no registry
+/// terminal owns, where nothing can be group-killed) holds the lease closed.
+async fn kill_session_ref_holder_and_confirm(
+    registry: &freshell_terminal::TerminalRegistry,
+    pid: u32,
+) -> bool {
+    match registry.live_terminal_for_pid(pid) {
+        Some(terminal_id) => {
+            registry.kill(&terminal_id);
+        }
+        None => {
+            tracing::error!(target: "invariant",
+                pid,
+                "session_ref_lease_kill_unroutable: no registry terminal owns the holder pid; holding lease closed");
+            return false;
+        }
+    }
+    confirm_pid_dead_within_500ms(pid).await
+}
+
+/// The D8 loser reply: `error{SESSION_RESERVED, requestId, retryAfterMs}` —
+/// the only error frame that carries `retryAfterMs`.
+async fn send_session_reserved(ws_tx: &mut WsSink, request_id: &str, retry_after_ms: u64) -> bool {
+    let msg = ServerMessage::Error(ErrorMsg {
+        code: ErrorCode::SessionReserved,
+        message: "Another terminal.create for this sessionRef is in flight".to_string(),
+        timestamp: crate::now_iso(),
+        actual_session_ref: None,
+        expected_session_ref: None,
+        request_id: Some(request_id.to_string()),
+        retry_after_ms: Some(retry_after_ms),
+        terminal_exit_code: None,
+        terminal_id: None,
+    });
+    send(ws_tx, &msg).await
+}
+
 /// `terminal.create` — spawn + register the PTY in the shared registry (owned by no
 /// connection), then reply `terminal.created`. Create does NOT attach; the client
 /// sends `terminal.attach` next.
@@ -922,6 +1057,7 @@ async fn handle_create(
     create: TerminalCreate,
     ws_tx: &mut WsSink,
     state: &WsState,
+    conn_id: u64,
     pane_reconcile_v1: bool,
     create_limiter: &mut crate::create_limit::CreateRateLimiter,
 ) -> bool {
@@ -978,6 +1114,89 @@ async fn handle_create(
     // the outcome itself is discoverable through the registry.
     let _keyed_create_guard = keyed_create_guard;
 
+    // Council rule 7 (D8 two-writers closure): per-sessionRef single-flight,
+    // negotiated connections ONLY. The claim runs BEFORE the rate limiter —
+    // a loser's SESSION_RESERVED (like the §5.4 adopt above, the
+    // create_protection.rs precedent) is neither checked nor charged. Legacy
+    // connections never enter this branch: their create flow stays
+    // byte-for-byte unchanged (§11 fence).
+    let mut session_ref_lease: Option<SessionRefLeaseGuard> = None;
+    if pane_reconcile_v1 {
+        if let Some(locator) = create_session_locator(&create) {
+            use freshell_terminal::registry::SessionRefClaim;
+            // Bounded: at most one ExpiredNeedsKill kill→confirm→re-claim
+            // round per create; a second expiry answers reserved instead.
+            for round in 0..2u8 {
+                match state.registry.claim_session_ref(
+                    &locator,
+                    &create.request_id,
+                    conn_id,
+                    now_ms().max(0) as u64,
+                ) {
+                    SessionRefClaim::Acquired => {
+                        session_ref_lease = Some(SessionRefLeaseGuard {
+                            registry: state.registry.clone(),
+                            locator: locator.clone(),
+                            holder_create_request_id: create.request_id.clone(),
+                            claimed_at_ms: now_ms(),
+                            armed: true,
+                        });
+                        break;
+                    }
+                    SessionRefClaim::BoundElsewhere { terminal_id } => {
+                        // Attach to the winner: mirror the §5.4 adopt emission
+                        // above — name the EXISTING terminal, spawn nothing.
+                        tracing::info!(
+                            terminal_id = %terminal_id,
+                            create_request_id = %create.request_id,
+                            provider = %locator.provider,
+                            session_id = %locator.session_id,
+                            "terminal.create.session_ref_attached"
+                        );
+                        let created = ServerMessage::TerminalCreated(TerminalCreated {
+                            created_at: now_ms(),
+                            request_id: create.request_id,
+                            terminal_id: terminal_id.clone(),
+                            clear_codex_durability: None,
+                            cwd: state.registry.probe(&terminal_id).and_then(|row| row.cwd),
+                            restore_error: None,
+                            session_ref: state
+                                .identity
+                                .session_ref_for(&terminal_id)
+                                .or(Some(locator)),
+                        });
+                        return send(ws_tx, &created).await;
+                    }
+                    SessionRefClaim::Held { retry_after_ms } => {
+                        return send_session_reserved(ws_tx, &create.request_id, retry_after_ms)
+                            .await;
+                    }
+                    SessionRefClaim::ExpiredNeedsKill { pid } => {
+                        if round == 0
+                            && kill_session_ref_holder_and_confirm(&state.registry, pid).await
+                        {
+                            state.registry.force_release_after_confirmed_kill(&locator);
+                            continue; // the slot is now free — re-claim
+                        }
+                        // Unconfirmed kill (or a second expiry in one create):
+                        // hold closed, fail loud, answer reserved.
+                        tracing::error!(target: "invariant",
+                            provider = %locator.provider,
+                            session_id = %locator.session_id,
+                            pid,
+                            "session_ref_lease_expired_kill_unconfirmed: holding lease closed");
+                        return send_session_reserved(
+                            ws_tx,
+                            &create.request_id,
+                            freshell_terminal::registry::SESSION_RESERVED_RETRY_AFTER_MS,
+                        )
+                        .await;
+                    }
+                }
+            }
+        }
+    }
+
     // Per-connection create rate limit (legacy parity: ws-handler.ts:2376-2389).
     // restore:true bypasses — neither checked nor recorded (`if (!m.restore)`).
     if create.restore != Some(true) && !create_limiter.try_acquire(crate::create_limit::epoch_ms())
@@ -1474,6 +1693,19 @@ async fn handle_create(
         .await;
     }
 
+    // D8: arm the lease's TTL kill path — record the just-spawned child's pid
+    // on the winner's lease immediately (its presence decides ExpiredNeedsKill
+    // vs revoke-and-hold-closed on expiry).
+    if let Some(guard) = &session_ref_lease {
+        if let Some(pid) = state.registry.pid_of(&terminal_id) {
+            state.registry.set_session_ref_lease_pid(
+                &guard.locator,
+                &guard.holder_create_request_id,
+                pid,
+            );
+        }
+    }
+
     // DEV-0006 S4: adopt the managed codex launch for this terminal
     // (`codexPlan.sidecar.adopt({terminalId, generation: 0})`, `ws:2511`) — ownership
     // transfers from the planner to the terminal; the PTY exit hook above tears it
@@ -1618,6 +1850,56 @@ async fn handle_create(
         crate::pane_ledger::surface_write_failure(state, &terminal_id_for_meta, result);
     }
 
+    // D8 winner bind: record sessionRef→terminalId in the REGISTRY binding
+    // map (inside `complete_session_ref_claim` — atomic with the lease
+    // release, then the duplicate alarm). The pane-ledger binding write above
+    // is PRE-EXISTING create-path behavior, deliberately not duplicated here.
+    if let Some(guard) = session_ref_lease.take() {
+        let (locator, claimed_at_ms) = guard.disarm();
+        if state
+            .registry
+            .complete_session_ref_claim(&locator, &create.request_id, &terminal_id)
+        {
+            // Spawn-duration instrumentation: the evidence stream for tuning
+            // FRESHELL_SESSION_REF_LEASE_TTL_MS (registry.rs).
+            tracing::info!(
+                terminal_id = %terminal_id,
+                provider = %locator.provider,
+                session_id = %locator.session_id,
+                spawn_elapsed_ms = now_ms().saturating_sub(claimed_at_ms),
+                "session_ref.winner_bound"
+            );
+        } else {
+            // Revoked while spawning (TTL expired on the then-pid-less lease):
+            // kill OUR OWN just-spawned child via the registry handle
+            // (group-kill discipline), confirm, and fail the create loudly.
+            let pid = state.registry.pid_of(&terminal_id);
+            state.registry.kill(&terminal_id);
+            let confirmed = match pid {
+                Some(pid) => confirm_pid_dead_within_500ms(pid).await,
+                // No pid handle to probe: the registry kill removed the row;
+                // nothing is left to signal, so treat as confirmed.
+                None => true,
+            };
+            if confirmed {
+                state.registry.force_release_after_confirmed_kill(&locator);
+            } else {
+                tracing::error!(target: "invariant",
+                    terminal_id = %terminal_id,
+                    provider = %locator.provider,
+                    session_id = %locator.session_id,
+                    "session_ref_lease_revoked_child_kill_unconfirmed: holding lease closed");
+            }
+            return send_create_error(
+                ws_tx,
+                ErrorCode::InternalError,
+                "Terminal create lost its sessionRef lease during spawn; the spawned process was killed".to_string(),
+                &create.request_id,
+            )
+            .await;
+        }
+    }
+
     let created = ServerMessage::TerminalCreated(TerminalCreated {
         created_at: now_ms(),
         request_id: create.request_id,
@@ -2025,6 +2307,7 @@ async fn send_create_error(
         actual_session_ref: None,
         expected_session_ref: None,
         request_id: Some(request_id.to_string()),
+        retry_after_ms: None,
         terminal_exit_code: None,
         terminal_id: None,
     });
@@ -2239,6 +2522,7 @@ fn invalid_dims_error(cols: i64, rows: i64) -> ServerMessage {
         actual_session_ref: None,
         expected_session_ref: None,
         request_id: None,
+        retry_after_ms: None,
         terminal_exit_code: None,
         terminal_id: None,
     })
@@ -2309,6 +2593,7 @@ async fn handle_kill(kill: TerminalKill, ws_tx: &mut WsSink, state: &WsState) ->
         actual_session_ref: None,
         expected_session_ref: None,
         request_id: None,
+        retry_after_ms: None,
         terminal_id: Some(kill.terminal_id),
         terminal_exit_code: None,
     });
diff --git a/crates/freshell-ws/tests/session_ref_singleflight.rs b/crates/freshell-ws/tests/session_ref_singleflight.rs
new file mode 100644
index 000000000..d52ea6b4b
--- /dev/null
+++ b/crates/freshell-ws/tests/session_ref_singleflight.rs
@@ -0,0 +1,226 @@
+//! D8 per-sessionRef single-flight wire tests (council rules 6/7/8): on a
+//! `paneReconcileV1`-negotiated connection, a `terminal.create` carrying a
+//! resume `sessionRef` runs the lease discipline — exactly one PTY per
+//! sessionRef; losers get `error{code: SESSION_RESERVED, retryAfterMs}` or
+//! attach to the winner's terminal. Frozen (non-negotiated) connections are
+//! byte-for-byte unchanged.
+//!
+//! Harness: `mod common;` + `spawn_server_with_specs(vec![sleeper_cli_spec
+//! ("claude")])` — real resume-create→live-PTY round trips (the verified
+//! recipe from `claude_restore_unavailable.rs`). SessionIds are
+//! canonical-UUID-shaped throughout (the claude restore gate rejects
+//! non-UUID pre-spawn, and D8 tests must stay valid under it).
+
+mod common;
+
+use std::time::Duration;
+
+use futures_util::{SinkExt, StreamExt};
+use tokio_tungstenite::tungstenite::Message as WsMessage;
+
+use common::{sleeper_cli_spec, spawn_server_with_specs, TestWs, AUTH_TOKEN};
+
+/// Connect + hello (optionally negotiating `paneReconcileV1`), consuming the
+/// 4-frame handshake (same shape as `tests/pane_reconcile.rs::connect`).
+async fn connect(url: &str, pane_reconcile_v1: bool) -> TestWs {
+    let (mut ws, _resp) = tokio_tungstenite::connect_async(url)
+        .await
+        .expect("ws connect");
+    let mut hello = serde_json::json!({
+        "type": "hello",
+        "token": AUTH_TOKEN,
+        "protocolVersion": freshell_protocol::WS_PROTOCOL_VERSION,
+    });
+    if pane_reconcile_v1 {
+        hello["capabilities"] = serde_json::json!({ "paneReconcileV1": true });
+    }
+    ws.send(WsMessage::Text(hello.to_string()))
+        .await
+        .expect("send hello");
+    for _ in 0..4u8 {
+        tokio::time::timeout(Duration::from_secs(5), ws.next())
+            .await
+            .expect("handshake message within timeout")
+            .expect("stream not ended")
+            .expect("no ws error");
+    }
+    ws
+}
+
+/// The same `terminal.create` JSON the client sends for a sessionRef resume
+/// (field names per `shared/ws-protocol.ts` `TerminalCreateSchema` — it is
+/// `.strict()`, so it IS the wire truth).
+fn terminal_create_resume(request_id: &str, mode: &str, session_id: &str) -> serde_json::Value {
+    serde_json::json!({
+        "type": "terminal.create",
+        "requestId": request_id,
+        "mode": mode,
+        "shell": "system",
+        "sessionRef": { "provider": mode, "sessionId": session_id },
+    })
+}
+
+async fn send_json(ws: &mut TestWs, value: serde_json::Value) {
+    ws.send(WsMessage::Text(value.to_string()))
+        .await
+        .expect("send frame");
+}
+
+/// Read frames until a `terminal.created` or `error` for `request_id`
+/// arrives (broadcast frames like `terminals.changed` are skipped).
+async fn next_created_or_error(ws: &mut TestWs, request_id: &str) -> serde_json::Value {
+    for _ in 0..40u8 {
+        let msg = tokio::time::timeout(Duration::from_secs(10), ws.next())
+            .await
+            .unwrap_or_else(|_| panic!("timed out waiting for created/error for {request_id}"))
+            .expect("stream not ended")
+            .expect("no ws error");
+        if let WsMessage::Text(text) = &msg {
+            let value: serde_json::Value = serde_json::from_str(text).expect("json frame");
+            let ty = value["type"].as_str().unwrap_or_default();
+            if (ty == "terminal.created" || ty == "error")
+                && value["requestId"] == serde_json::json!(request_id)
+            {
+                return value;
+            }
+        }
+    }
+    panic!("no terminal.created/error for {request_id} within 40 messages");
+}
+
+/// Count live PTYs carrying `session_id` via the registry-row join
+/// (`identity_probe_rows`): `mode` + `resume_session_id` + Running.
+fn live_pty_count_for_session(
+    registry: &freshell_terminal::TerminalRegistry,
+    mode: &str,
+    session_id: &str,
+) -> usize {
+    registry
+        .identity_probe_rows()
+        .into_iter()
+        .filter(|row| {
+            row.mode == mode
+                && row.status == freshell_protocol::TerminalRunStatus::Running
+                && row.resume_session_id.as_deref() == Some(session_id)
+        })
+        .count()
+}
+
+/// The registry's sessionRef→terminalId binding map (recorded at winner bind).
+fn registry_binding_for(
+    registry: &freshell_terminal::TerminalRegistry,
+    mode: &str,
+    session_id: &str,
+) -> Option<String> {
+    registry.bound_terminal_for_session_ref(&freshell_protocol::SessionLocator {
+        provider: mode.to_string(),
+        session_id: session_id.to_string(),
+    })
+}
+
+/// two-clients-same-sessionRef (council red test): two negotiated
+/// connections, DIFFERENT createRequestIds, same sessionRef resume ->
+/// exactly one PTY; the loser is reserved then attaches to the winner.
+#[tokio::test]
+async fn two_clients_same_session_ref_yield_exactly_one_pty() {
+    const SESS_DUP: &str = "11111111-1111-4111-8111-111111111111";
+    let (url, registry) = spawn_server_with_specs(vec![sleeper_cli_spec("claude")]).await;
+    let mut a = connect(&url, true).await;
+    let mut b = connect(&url, true).await;
+    send_json(&mut a, terminal_create_resume("cr-A", "claude", SESS_DUP)).await;
+    send_json(&mut b, terminal_create_resume("cr-B", "claude", SESS_DUP)).await;
+
+    let fa = next_created_or_error(&mut a, "cr-A").await;
+    let fb = next_created_or_error(&mut b, "cr-B").await;
+    // Exactly one connection wins the spawn; identify winner and other.
+    let (created, other, loser_is_b) = if fa["type"] == serde_json::json!("terminal.created") {
+        (fa, fb, true)
+    } else {
+        (fb, fa, false)
+    };
+    assert_eq!(
+        created["type"],
+        serde_json::json!("terminal.created"),
+        "at least one create must win: {created}"
+    );
+    let tid = created["terminalId"]
+        .as_str()
+        .expect("terminalId")
+        .to_string();
+
+    if other["type"] == serde_json::json!("error") {
+        // Loser path: reserved now, adopts the winner on re-send.
+        assert_eq!(other["code"], serde_json::json!("SESSION_RESERVED"));
+        let retry_after = other["retryAfterMs"].as_u64().expect("retryAfterMs");
+        assert!(retry_after >= 1);
+        tokio::time::sleep(Duration::from_millis(retry_after)).await;
+        let (loser_ws, loser_req) = if loser_is_b {
+            (&mut b, "cr-B")
+        } else {
+            (&mut a, "cr-A")
+        };
+        send_json(
+            loser_ws,
+            terminal_create_resume(loser_req, "claude", SESS_DUP),
+        )
+        .await;
+        let readopt = next_created_or_error(loser_ws, loser_req).await;
+        assert_eq!(
+            readopt["type"],
+            serde_json::json!("terminal.created"),
+            "re-send after retryAfterMs must adopt the winner: {readopt}"
+        );
+        assert_eq!(readopt["terminalId"], serde_json::json!(tid.clone()));
+    } else {
+        // Loser adopted immediately (winner already bound).
+        assert_eq!(other["terminalId"], serde_json::json!(tid.clone()));
+    }
+
+    assert_eq!(
+        live_pty_count_for_session(&registry, "claude", SESS_DUP),
+        1,
+        "exactly one live PTY per sessionRef"
+    );
+    registry.kill_all();
+}
+
+/// Legacy connections (no capability) never see SESSION_RESERVED — the
+/// frozen-client create path is byte-for-byte unchanged.
+#[tokio::test]
+async fn legacy_connection_create_path_unchanged() {
+    const SESS_LEGACY: &str = "22222222-2222-4222-8222-222222222222";
+    let (url, registry) = spawn_server_with_specs(vec![sleeper_cli_spec("claude")]).await;
+    let mut legacy = connect(&url, false).await;
+    send_json(
+        &mut legacy,
+        terminal_create_resume("cr-L", "claude", SESS_LEGACY),
+    )
+    .await;
+    let created = next_created_or_error(&mut legacy, "cr-L").await;
+    assert_eq!(created["type"], serde_json::json!("terminal.created"));
+    assert!(created["terminalId"].is_string());
+    // The legacy path never touches the lease/binding machinery.
+    assert_eq!(registry_binding_for(&registry, "claude", SESS_LEGACY), None);
+    registry.kill_all();
+}
+
+/// Winner bind populates the REGISTRY binding map: after the winner's
+/// `terminal.created`, the binding map answers with that terminalId (the
+/// NEW behavior this task adds; the pane-ledger write is pre-existing
+/// create-path behavior and not asserted here).
+#[tokio::test]
+async fn winner_bind_populates_registry_binding() {
+    const SESS_LED: &str = "33333333-3333-4333-8333-333333333333";
+    let (url, registry) = spawn_server_with_specs(vec![sleeper_cli_spec("claude")]).await;
+    let mut a = connect(&url, true).await;
+    send_json(&mut a, terminal_create_resume("cr-A", "claude", SESS_LED)).await;
+    let created = next_created_or_error(&mut a, "cr-A").await;
+    assert_eq!(created["type"], serde_json::json!("terminal.created"));
+    let tid = created["terminalId"].as_str().expect("terminalId");
+    assert_eq!(
+        registry_binding_for(&registry, "claude", SESS_LED).as_deref(),
+        Some(tid),
+        "the registry binding map must answer for this sessionRef"
+    );
+    registry.kill_all();
+}

From 0f2c342bedba2f3573df674e308bfac47a1b8dd3 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:30:40 -0700
Subject: [PATCH 35/87] feat(client): recovery trigger eligibility
 (boot-captured) and dismissal persistence (B3/P1.9)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 src/lib/recovery/boot-state.ts                | 26 ++++++++++
 src/lib/recovery/dismissal.ts                 | 49 +++++++++++++++++++
 src/main.tsx                                  |  4 ++
 .../client/lib/recovery/boot-state.test.ts    | 37 ++++++++++++++
 .../client/lib/recovery/dismissal.test.ts     | 40 +++++++++++++++
 .../lib/recovery/main-import-order.test.ts    | 27 ++++++++++
 6 files changed, 183 insertions(+)
 create mode 100644 src/lib/recovery/boot-state.ts
 create mode 100644 src/lib/recovery/dismissal.ts
 create mode 100644 test/unit/client/lib/recovery/boot-state.test.ts
 create mode 100644 test/unit/client/lib/recovery/dismissal.test.ts
 create mode 100644 test/unit/client/lib/recovery/main-import-order.test.ts

diff --git a/src/lib/recovery/boot-state.ts b/src/lib/recovery/boot-state.ts
new file mode 100644
index 000000000..34b9278be
--- /dev/null
+++ b/src/lib/recovery/boot-state.ts
@@ -0,0 +1,26 @@
+const LAYOUT_KEY = 'freshell.layout.v3'
+const LAYOUT_BAK_KEY = 'freshell.layout.v3.bak'
+
+export function computeHadPersistedLayout(storage: Pick<Storage, 'getItem'>): boolean {
+  return storage.getItem(LAYOUT_KEY) !== null || storage.getItem(LAYOUT_BAK_KEY) !== null
+}
+
+// Captured at module import. Synchronous module-load writers of freshell.layout.v3 DO
+// exist (storage-migration.ts:332/431 — self-executing via main.tsx's side-effect import
+// at main.tsx:4 — and migrateV2ToV3, persistedState.ts:594, during tabsSlice module eval),
+// but each fires only when durable layout data ALREADY existed, so key-presence here
+// remains the correct "had layout" signal. storage-migration also re-materializes
+// freshell.layout.v3 from the `.backup-before-fresh-agent-centralization` key BEFORE this
+// module can load — which is why we check only v3 + .bak. Invariants (pinned by
+// main-import-order.test.ts): the storage-migration import stays ahead of the store/App
+// imports in main.tsx (the imports above it are side-effect-free library imports);
+// main.tsx never imports this module.
+// The asynchronous writers (auto shell tab App.tsx:1423-1427, 500ms persist debounce)
+// land long after module eval (see docs/plans/2026-07-26-recover-my-panes.md D1).
+export const hadPersistedLayoutAtBoot: boolean =
+  typeof window !== 'undefined' && computeHadPersistedLayout(window.localStorage)
+
+// Paired with the capture above: the moment this boot's "had layout" signal was taken.
+// Anchor for the inventory request's bootAgoMs (D2's concurrent-client filter) - sent as
+// an elapsed DURATION so client/server clock skew cannot corrupt the server-side cutoff.
+export const bootCapturedAtMs: number = Date.now()
diff --git a/src/lib/recovery/dismissal.ts b/src/lib/recovery/dismissal.ts
new file mode 100644
index 000000000..363485510
--- /dev/null
+++ b/src/lib/recovery/dismissal.ts
@@ -0,0 +1,49 @@
+const DISMISSED_KEY = 'freshell.recovery.dismissed.v1'
+const PENDING_KEY = 'freshell.recovery.pending.v1'
+const CAP = 20
+
+function readDismissed(): string[] {
+  try {
+    const raw = localStorage.getItem(DISMISSED_KEY)
+    const parsed = raw ? JSON.parse(raw) : []
+    return Array.isArray(parsed) ? parsed.filter((x) => typeof x === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+export function isDismissed(contentId: string): boolean {
+  return readDismissed().includes(contentId)
+}
+
+export function recordDismissal(contentId: string): void {
+  const next = [...readDismissed().filter((id) => id !== contentId), contentId].slice(-CAP)
+  localStorage.setItem(DISMISSED_KEY, JSON.stringify(next))
+}
+
+export interface PendingOffer {
+  contentId: string
+  bootAt: number
+}
+
+export function getPendingOffer(): PendingOffer | null {
+  try {
+    const raw = localStorage.getItem(PENDING_KEY)
+    if (!raw) return null
+    const parsed: unknown = JSON.parse(raw)
+    const p = parsed as { contentId?: unknown; bootAt?: unknown }
+    return typeof p?.contentId === 'string' && typeof p?.bootAt === 'number'
+      ? { contentId: p.contentId, bootAt: p.bootAt }
+      : null
+  } catch {
+    return null
+  }
+}
+
+export function setPendingOffer(contentId: string, bootAt: number): void {
+  localStorage.setItem(PENDING_KEY, JSON.stringify({ contentId, bootAt }))
+}
+
+export function clearPendingOffer(): void {
+  localStorage.removeItem(PENDING_KEY)
+}
diff --git a/src/main.tsx b/src/main.tsx
index 1f1a13d04..223c0cf49 100644
--- a/src/main.tsx
+++ b/src/main.tsx
@@ -1,6 +1,10 @@
 import React from 'react'
 import ReactDOM from 'react-dom/client'
 import { Provider } from 'react-redux'
+// MUST stay ahead of the store/App imports: recover-my-panes boot-state (D1) depends on
+// migrations having re-materialized freshell.layout.v3 BEFORE any capture runs (the
+// react/react-dom/react-redux imports above are side-effect-free) — see
+// docs/plans/2026-07-26-recover-my-panes.md and main-import-order.test.ts.
 import '@/store/storage-migration'
 import { store } from '@/store/store'
 import App from '@/App'
diff --git a/test/unit/client/lib/recovery/boot-state.test.ts b/test/unit/client/lib/recovery/boot-state.test.ts
new file mode 100644
index 000000000..7590af464
--- /dev/null
+++ b/test/unit/client/lib/recovery/boot-state.test.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { computeHadPersistedLayout } from '@/lib/recovery/boot-state'
+
+const store = (entries: Record<string, string>) => ({ getItem: (k: string) => entries[k] ?? null })
+
+describe('computeHadPersistedLayout', () => {
+  beforeEach(() => localStorage.clear())
+
+  it('empty-never: no layout keys at all -> false (offer-eligible)', () => {
+    expect(computeHadPersistedLayout(store({}))).toBe(false)
+  })
+
+  it('empty-cleared: only unrelated keys survive a clear -> false (offer-eligible)', () => {
+    expect(computeHadPersistedLayout(store({ 'freshell.device-id.v2': 'dev' }))).toBe(false)
+  })
+
+  it('populated: layout key present -> true (no offer)', () => {
+    expect(computeHadPersistedLayout(store({ 'freshell.layout.v3': '{"tabs":[{"id":"t1"}]}' }))).toBe(true)
+  })
+
+  it('deliberately emptied: layout key present with zero tabs -> true (no offer)', () => {
+    expect(computeHadPersistedLayout(store({ 'freshell.layout.v3': '{"tabs":[]}' }))).toBe(true)
+  })
+
+  it('backup key alone counts as persisted layout', () => {
+    expect(computeHadPersistedLayout(store({ 'freshell.layout.v3.bak': '{}' }))).toBe(true)
+  })
+})
+
+describe('hadPersistedLayoutAtBoot capture', () => {
+  it('is captured at module import time, before later writes', async () => {
+    localStorage.clear()
+    const { hadPersistedLayoutAtBoot } = await import('@/lib/recovery/boot-state?fresh=' + Date.now())
+    localStorage.setItem('freshell.layout.v3', '{"tabs":[{"id":"auto"}]}') // simulates auto-tab persist
+    expect(hadPersistedLayoutAtBoot).toBe(false)
+  })
+})
diff --git a/test/unit/client/lib/recovery/dismissal.test.ts b/test/unit/client/lib/recovery/dismissal.test.ts
new file mode 100644
index 000000000..100523acc
--- /dev/null
+++ b/test/unit/client/lib/recovery/dismissal.test.ts
@@ -0,0 +1,40 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { isDismissed, recordDismissal, getPendingOffer, setPendingOffer, clearPendingOffer } from '@/lib/recovery/dismissal'
+
+describe('recovery dismissal persistence', () => {
+  beforeEach(() => localStorage.clear())
+
+  it('unknown contentId is not dismissed', () => expect(isDismissed('abc')).toBe(false))
+
+  it('recordDismissal persists across module state (localStorage-backed)', () => {
+    recordDismissal('abc')
+    expect(isDismissed('abc')).toBe(true)
+    expect(isDismissed('xyz')).toBe(false)
+  })
+
+  it('caps at 20, evicting oldest', () => {
+    for (let i = 0; i < 21; i++) recordDismissal(`id-${i}`)
+    expect(isDismissed('id-0')).toBe(false)
+    expect(isDismissed('id-20')).toBe(true)
+  })
+
+  it('tolerates corrupt stored JSON', () => {
+    localStorage.setItem('freshell.recovery.dismissed.v1', '{not json')
+    expect(isDismissed('abc')).toBe(false)
+    recordDismissal('abc')
+    expect(isDismissed('abc')).toBe(true)
+  })
+
+  it('pending offer round-trips (with its bootAt anchor) and clears', () => {
+    expect(getPendingOffer()).toBeNull()
+    setPendingOffer('abc', 12345)
+    expect(getPendingOffer()).toEqual({ contentId: 'abc', bootAt: 12345 })
+    clearPendingOffer()
+    expect(getPendingOffer()).toBeNull()
+  })
+
+  it('tolerates corrupt pending JSON', () => {
+    localStorage.setItem('freshell.recovery.pending.v1', '{not json')
+    expect(getPendingOffer()).toBeNull()
+  })
+})
diff --git a/test/unit/client/lib/recovery/main-import-order.test.ts b/test/unit/client/lib/recovery/main-import-order.test.ts
new file mode 100644
index 000000000..c1e75131d
--- /dev/null
+++ b/test/unit/client/lib/recovery/main-import-order.test.ts
@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+
+describe('boot-state capture ordering invariants (D1/A8)', () => {
+  const src = readFileSync('src/main.tsx', 'utf8')
+
+  it('storage-migration is imported before the store and App in main.tsx', () => {
+    // It re-materializes freshell.layout.v3 from the
+    // `.backup-before-fresh-agent-centralization` key BEFORE any capture can run —
+    // which is why boot-state checks only v3 + .bak. The imports above it
+    // (react, react-dom/client, react-redux) are pure library imports with no
+    // localStorage side effects, so "before store/App" is the real invariant.
+    const migrationIdx = src.indexOf("import '@/store/storage-migration'")
+    const storeIdx = src.indexOf("from '@/store/store'")
+    const appIdx = src.indexOf("from '@/App'")
+    expect(migrationIdx).toBeGreaterThan(-1)
+    expect(storeIdx).toBeGreaterThan(-1)
+    expect(appIdx).toBeGreaterThan(-1)
+    expect(migrationIdx).toBeLessThan(storeIdx)
+    expect(migrationIdx).toBeLessThan(appIdx)
+  })
+
+  it('boot-state is never imported from main.tsx', () => {
+    // boot-state must load AFTER migrations (it reaches the DOM via App → RecoveryOfferPanel)
+    expect(src).not.toMatch(/lib\/recovery\/boot-state/)
+  })
+})

From 64af48871978b270ee08a86c1beb63e1f35eb0ce Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:33:54 -0700
Subject: [PATCH 36/87] feat(server): wire pane ledger into fresh-agent states
 via LedgerIdentitySink (P1.13)

---
 crates/freshell-server/src/identity_sink.rs | 157 ++++++++++++++++++++
 crates/freshell-server/src/main.rs          |  13 ++
 2 files changed, 170 insertions(+)
 create mode 100644 crates/freshell-server/src/identity_sink.rs

diff --git a/crates/freshell-server/src/identity_sink.rs b/crates/freshell-server/src/identity_sink.rs
new file mode 100644
index 000000000..5ce4d46a6
--- /dev/null
+++ b/crates/freshell-server/src/identity_sink.rs
@@ -0,0 +1,157 @@
+//! Server-side implementation of the fresh-agent identity bridge (P1.13):
+//! freshell-freshagent cannot see the ledger (crate cycle), so main.rs
+//! injects this adapter at wiring time.
+
+use freshell_freshagent::{
+    FreshAgentBindingUpsert, FreshAgentSettings, PaneIdentitySink, SinkWrite,
+};
+use freshell_ws::pane_ledger::{FreshAgentBindingWrite, PaneLedger};
+use std::sync::Arc;
+
+pub struct LedgerIdentitySink {
+    ledger: Arc<PaneLedger>,
+}
+
+impl LedgerIdentitySink {
+    pub fn new(ledger: Arc<PaneLedger>) -> Self {
+        Self { ledger }
+    }
+}
+
+fn now_ms() -> i64 {
+    // Match the timestamp convention main.rs already uses for ledger writes
+    // (see the boot-scan / record_binding call sites in main.rs).
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_millis() as i64)
+        .unwrap_or(0)
+}
+
+impl PaneIdentitySink for LedgerIdentitySink {
+    // Writes are AWAITED spawn_blocking (durable-before-answer, V8/A11) —
+    // exactly the shape terminal.rs:1589 already ships. Timestamps are taken
+    // at EVENT time (before the hop), so `updated_at` reflects event order
+    // (V8's out-of-order aggravator).
+    fn record_pending(&self, placeholder_id: &str, mode: &str, cwd: Option<&str>) -> SinkWrite {
+        let ledger = self.ledger.clone();
+        let (p, m, c) = (
+            placeholder_id.to_string(),
+            mode.to_string(),
+            cwd.map(str::to_string),
+        );
+        let now = now_ms();
+        Box::pin(async move {
+            tokio::task::spawn_blocking(move || ledger.record_pending(&p, &m, c.as_deref(), now))
+                .await
+                .map_err(std::io::Error::other)? // JoinError (incl. closure panic) surfaces as Err
+        })
+    }
+
+    fn record_binding(&self, upsert: FreshAgentBindingUpsert) -> SinkWrite {
+        let ledger = self.ledger.clone();
+        let now = now_ms();
+        Box::pin(async move {
+            tokio::task::spawn_blocking(move || {
+                let w = FreshAgentBindingWrite {
+                    provider: &upsert.provider,
+                    session_id: &upsert.session_id,
+                    mode: &upsert.mode,
+                    cwd: upsert.settings.cwd.as_deref(),
+                    create_request_id: upsert.create_request_id.as_deref(),
+                    model: upsert.settings.model.as_deref(),
+                    sandbox: upsert.settings.sandbox.as_deref(),
+                    permission_mode: upsert.settings.permission_mode.as_deref(),
+                    effort: upsert.settings.effort.as_deref(),
+                    supersedes: upsert.supersedes.as_deref(),
+                    now_ms: now,
+                };
+                ledger.record_fresh_agent_binding(&w)?; // binding-write failure propagates
+                if let Some(p) = upsert.resolves_pending.as_deref() {
+                    // Cosmetic on failure: an orphaned marker is TTL-swept at 30d
+                    // (V6/A15) — warn, do not fail the identity event over it.
+                    if let Err(e) = ledger.delete_pending(p) {
+                        tracing::warn!(error = %e, placeholder = %p, "pane_ledger.fresh_agent.pending_delete_failed");
+                    }
+                }
+                Ok(())
+            })
+            .await
+            .map_err(std::io::Error::other)?
+        })
+    }
+
+    fn load_settings(&self, provider: &str, session_id: &str) -> Option<FreshAgentSettings> {
+        // Reads are memory-only against the write-through index — safe inline.
+        let row = self.ledger.load_binding(provider, session_id)?;
+        // Terminal-lineage rows (wave-A codex_candidate etc.) are NOT resume
+        // records — only fresh-agent rows serve settings (V7/A10 gating).
+        if row.pane_kind.as_deref() != Some("fresh-agent") {
+            return None;
+        }
+        let s = FreshAgentSettings {
+            model: row.model,
+            sandbox: row.sandbox,
+            permission_mode: row.permission_mode,
+            effort: row.effort,
+            cwd: row.cwd,
+        };
+        // A fully blank snapshot is "nothing recoverable" (real creates always
+        // carry at least cwd): None here + was_recorded()==true is exactly the
+        // SETTINGS_RESET alarm condition (V7/A10).
+        if s == FreshAgentSettings::default() {
+            return None;
+        }
+        Some(s)
+    }
+
+    fn was_recorded(&self, provider: &str, session_id: &str) -> bool {
+        // State-agnostic (load_binding serves Retired/GcExpired rows too, V6/A9).
+        self.ledger
+            .load_binding(provider, session_id)
+            .map(|r| r.pane_kind.as_deref() == Some("fresh-agent"))
+            .unwrap_or(false)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use freshell_freshagent::{FreshAgentBindingUpsert, FreshAgentSettings, PaneIdentitySink};
+    use std::sync::Arc;
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn writes_through_to_ledger_and_reads_back() {
+        let tmp = tempfile::tempdir().unwrap();
+        let ledger = Arc::new(freshell_ws::pane_ledger::PaneLedger::new(Some(
+            tmp.path().to_path_buf(),
+        )));
+        let sink = LedgerIdentitySink::new(ledger.clone());
+        sink.record_binding(FreshAgentBindingUpsert {
+            provider: "codex".into(),
+            session_id: "t1".into(),
+            mode: "freshcodex".into(),
+            create_request_id: None,
+            resolves_pending: None,
+            supersedes: None,
+            settings: FreshAgentSettings {
+                model: Some("gpt-5.3-codex-spark".into()),
+                sandbox: Some("workspace-write".into()),
+                permission_mode: Some("on-request".into()),
+                effort: None,
+                cwd: Some("/w".into()),
+            },
+        })
+        .await
+        .expect("awaited write succeeds");
+        // Awaited write => durable and readable IMMEDIATELY, no polling.
+        let s = sink
+            .load_settings("codex", "t1")
+            .expect("binding visible after await");
+        assert_eq!(s.model.as_deref(), Some("gpt-5.3-codex-spark"));
+        assert_eq!(s.sandbox.as_deref(), Some("workspace-write"));
+        assert!(sink.was_recorded("codex", "t1"));
+        assert!(!sink.was_recorded("codex", "nope"));
+        let row = ledger.load_binding("codex", "t1").unwrap();
+        assert_eq!(row.pane_kind.as_deref(), Some("fresh-agent"));
+    }
+}
diff --git a/crates/freshell-server/src/main.rs b/crates/freshell-server/src/main.rs
index 3457cffc7..53949ccf3 100644
--- a/crates/freshell-server/src/main.rs
+++ b/crates/freshell-server/src/main.rs
@@ -22,6 +22,7 @@ mod diag;
 mod existence;
 mod extensions;
 mod files;
+mod identity_sink;
 mod instance_id;
 mod logging;
 mod network;
@@ -427,6 +428,18 @@ async fn main() -> ExitCode {
         home.as_ref()
             .map(|h| h.join(".freshell").join("pane-ledger")),
     ));
+    // P1.13: inject the ledger-backed identity sink into the fresh-agent
+    // states (constructed earlier, before the ledger exists — the
+    // post-construction setter exists precisely for this ordering). All
+    // clones of each state share the `Arc<OnceLock>` field, so this covers
+    // every route's clone.
+    let fresh_agent_identity_sink: freshell_freshagent::SharedPaneIdentitySink =
+        std::sync::Arc::new(identity_sink::LedgerIdentitySink::new(pane_ledger.clone()));
+    fresh_codex_state.set_identity_sink(fresh_agent_identity_sink.clone());
+    fresh_claude_state.set_identity_sink(fresh_agent_identity_sink.clone());
+    fresh_opencode_state.set_identity_sink(fresh_agent_identity_sink.clone());
+    // opencode REST surface (Task 7's materialization site; V10 A13-N1)
+    fresh_agent_state.set_identity_sink(fresh_agent_identity_sink.clone());
     let ws_state = WsState {
         activity: Some(activity_hub.clone()),
         identity: terminal_identity.clone(),

From c8d59245ae9e62ee7b71d5d20869f9e116de1846 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:34:16 -0700
Subject: [PATCH 37/87] refactor(ws): extract adopt_codex_identity shared
 adoption tail from the candidate channel

---
 crates/freshell-ws/src/codex_candidate.rs | 132 +++----------------
 crates/freshell-ws/src/codex_identity.rs  | 153 ++++++++++++++++++++++
 crates/freshell-ws/src/lib.rs             |   3 +-
 3 files changed, 170 insertions(+), 118 deletions(-)
 create mode 100644 crates/freshell-ws/src/codex_identity.rs

diff --git a/crates/freshell-ws/src/codex_candidate.rs b/crates/freshell-ws/src/codex_candidate.rs
index 902bdb009..3946598ec 100644
--- a/crates/freshell-ws/src/codex_candidate.rs
+++ b/crates/freshell-ws/src/codex_candidate.rs
@@ -17,14 +17,11 @@
 //!      parity `server/coding-cli/codex-app-server/durability-proof.ts:88-102`)
 
 use std::io::{BufRead, Read};
-use std::path::{Path, PathBuf};
+use std::path::Path;
 
-use freshell_protocol::{
-    ServerMessage, SessionLocator, TerminalCodexCandidatePersisted, TerminalMetaRecord,
-    TerminalMetaUpdated, TerminalSessionAssociated,
-};
+use freshell_protocol::TerminalCodexCandidatePersisted;
 
-use crate::terminal::now_ms;
+use crate::codex_identity::{adopt_codex_identity, codex_sessions_root, CodexAdoption};
 use crate::WsState;
 
 /// Codex thread ids are bare hyphenated UUIDs. Cheap shape check so an empty
@@ -91,28 +88,6 @@ pub(crate) fn verify_rollout_path(
     }
 }
 
-/// `CODEX_HOME` env (non-empty) else `<HOME>/.codex`, then `/sessions` --
-/// mirrors `freshell-server/src/session_directory.rs::codex_home` (which is
-/// crate-private there; HOME only, never FRESHELL_HOME) joined with the
-/// `sessions` dir the way `freshell_sessions::directory_index::CodexSource`
-/// does.
-///
-/// `pub` (re-exported from the crate root) for `freshell-server`'s boot-time
-/// codex rollout-locator wiring.
-pub fn codex_sessions_root() -> Option<PathBuf> {
-    let home = match std::env::var("CODEX_HOME") {
-        Ok(v) if !v.is_empty() => PathBuf::from(v),
-        _ => {
-            #[cfg(windows)]
-            let base = std::env::var("USERPROFILE").ok()?;
-            #[cfg(not(windows))]
-            let base = std::env::var("HOME").ok()?;
-            PathBuf::from(base).join(".codex")
-        }
-    };
-    Some(home.join("sessions"))
-}
-
 /// Handle one `terminal.codex.candidate.persisted` frame. No reply frame on
 /// any path; rejects are WARN logs, accepts bind BOTH identity homes and
 /// broadcast (mirrors `opencode_association.rs`'s resolve path).
@@ -201,98 +176,21 @@ pub(crate) async fn handle_codex_candidate_persisted(
         );
         return;
     }
-    // Bind both identity homes (they have different consumers -- see
-    // opencode_association.rs:135-148), then broadcast.
-    state.identity.upsert(
-        &msg.terminal_id,
-        Some("codex"),
-        Some(thread_id),
-        row.cwd.as_deref(),
-        now_ms(),
-    );
-    state.registry.set_meta(
-        &msg.terminal_id,
-        None,
-        None,
-        Some("codex".to_string()),
-        Some(thread_id.to_string()),
-    );
-    // P1.8 (trigger b): the verified adoption is an identity event -- durable
-    // binding row first, then the spawn-time pending marker is deleted.
-    // Awaited spawn_blocking inside the helper: the fsync completes before
-    // the associated broadcast, without pinning the dispatch worker (V1.md).
-    crate::pane_ledger::ledger_resolve_identity(
+    // The shared adoption tail (codex_identity.rs): binds both identity
+    // homes, awaits the durable ledger row, broadcasts the pinned
+    // associated/meta pair, and feeds the activity hub. It re-checks guard
+    // 3b (session bound elsewhere, retired-inclusive) internally; a reject
+    // there stays a silent WARN, matching this channel's no-reply contract.
+    adopt_codex_identity(
         state,
-        &msg.terminal_id,
-        "codex",
-        thread_id,
-        row.cwd.as_deref(),
-    )
-    .await;
-    broadcast_terminal_session_associated(state, &msg.terminal_id, thread_id, row.cwd.clone());
-    // G3: adopted identity also feeds the activity tracker, so this
-    // terminal's `codex.activity.updated` records and subsequent
-    // `terminal.turn.complete` frames carry the sessionId (a fresh codex
-    // terminal otherwise never gets one -- identity arrives only here).
-    // Placed AFTER the pinned associated/meta broadcast pair.
-    if let Some(hub) = &state.activity {
-        hub.bind_codex_session(&msg.terminal_id, thread_id);
-        // G9: the verified rollout also feeds the reconcile lane, so this
-        // fresh terminal gets real busy-state from disk, not just PTY
-        // heuristics. Both calls only enqueue hub events (Task 2/Task 6):
-        // no file I/O and no frame emission happens on this WS dispatch
-        // path -- the hub task does the work, keeping frames serialized.
-        hub.attach_codex_rollout(
-            &msg.terminal_id,
+        CodexAdoption {
+            terminal_id: &msg.terminal_id,
             thread_id,
-            std::path::Path::new(&msg.rollout_path),
-        );
-    }
-}
-
-/// Fan `terminal.session.associated` + a `terminal.meta.updated` upsert to
-/// every connection. Byte-for-byte the shape of
-/// `opencode_association.rs::broadcast_terminal_session_associated` with
-/// provider "codex". EMISSION ORDER IS PINNED: `associated` FIRST, then
-/// `meta.updated` (mirroring opencode_association.rs:163-198) -- the
-/// integration test awaits them in exactly this order, and
-/// `next_frame_of_type` drops out-of-order frames. Do not reorder.
-fn broadcast_terminal_session_associated(
-    state: &WsState,
-    terminal_id: &str,
-    session_id: &str,
-    cwd: Option<String>,
-) {
-    let associated = ServerMessage::TerminalSessionAssociated(TerminalSessionAssociated {
-        terminal_id: terminal_id.to_string(),
-        session_ref: SessionLocator {
-            provider: "codex".to_string(),
-            session_id: session_id.to_string(),
+            rollout_path: Some(Path::new(&msg.rollout_path)),
+            cwd: row.cwd.as_deref(),
         },
-    });
-    if let Ok(frame) = serde_json::to_string(&associated) {
-        let _ = state.broadcast_tx.send(frame);
-    }
-
-    let meta = ServerMessage::TerminalMetaUpdated(TerminalMetaUpdated {
-        remove: Vec::new(),
-        upsert: vec![TerminalMetaRecord {
-            terminal_id: terminal_id.to_string(),
-            updated_at: now_ms(),
-            branch: None,
-            checkout_root: None,
-            cwd,
-            display_subdir: None,
-            is_dirty: None,
-            provider: Some("codex".to_string()),
-            repo_root: None,
-            session_id: Some(session_id.to_string()),
-            token_usage: None,
-        }],
-    });
-    if let Ok(frame) = serde_json::to_string(&meta) {
-        let _ = state.broadcast_tx.send(frame);
-    }
+    )
+    .await;
 }
 
 #[cfg(test)]
diff --git a/crates/freshell-ws/src/codex_identity.rs b/crates/freshell-ws/src/codex_identity.rs
new file mode 100644
index 000000000..81e77463c
--- /dev/null
+++ b/crates/freshell-ws/src/codex_identity.rs
@@ -0,0 +1,153 @@
+//! Shared codex identity adoption tail: bind a verified codex thread id into
+//! every identity home (identity store, registry meta, durable pane ledger,
+//! broadcast frames, activity hub) in the load-bearing order. Extracted from
+//! `codex_candidate.rs` so both the candidate channel and the server-side
+//! rollout locator adopt identically.
+
+use std::path::{Path, PathBuf};
+
+use freshell_protocol::{
+    ServerMessage, SessionLocator, TerminalMetaRecord, TerminalMetaUpdated,
+    TerminalSessionAssociated,
+};
+
+use crate::terminal::now_ms;
+use crate::WsState;
+
+/// `CODEX_HOME` env (non-empty) else `<HOME>/.codex`, then `/sessions` --
+/// mirrors `freshell-server/src/session_directory.rs::codex_home` (which is
+/// crate-private there; HOME only, never FRESHELL_HOME) joined with the
+/// `sessions` dir the way `freshell_sessions::directory_index::CodexSource`
+/// does.
+///
+/// `pub` (re-exported from the crate root) for `freshell-server`'s boot-time
+/// codex rollout-locator wiring.
+pub fn codex_sessions_root() -> Option<PathBuf> {
+    let home = match std::env::var("CODEX_HOME") {
+        Ok(v) if !v.is_empty() => PathBuf::from(v),
+        _ => {
+            #[cfg(windows)]
+            let base = std::env::var("USERPROFILE").ok()?;
+            #[cfg(not(windows))]
+            let base = std::env::var("HOME").ok()?;
+            PathBuf::from(base).join(".codex")
+        }
+    };
+    Some(home.join("sessions"))
+}
+
+pub(crate) struct CodexAdoption<'a> {
+    pub terminal_id: &'a str,
+    pub thread_id: &'a str,
+    pub rollout_path: Option<&'a Path>,
+    pub cwd: Option<&'a str>,
+}
+
+/// Bind a codex identity into every home, in the load-bearing order.
+/// Returns false (and adopts nothing) when the session is already bound to a
+/// DIFFERENT terminal -- retired-INCLUSIVE (ledger A8), preserving the
+/// cross-pane hijack defense the candidate channel had.
+pub(crate) async fn adopt_codex_identity(state: &WsState, a: CodexAdoption<'_>) -> bool {
+    // Cross-pane hijack / replay defense, retired-INCLUSIVE (ledger A8): a
+    // victim's binding retires at exit, so a live-only lookup would allow
+    // replaying a DEAD pane's identity onto a fresh terminal. Copied from
+    // candidate guard 3b (codex_candidate.rs:167-186) -- keep the exact
+    // comparison semantics that code uses today; re-adopting the SAME
+    // terminal is an idempotent allow. This guard is also a REQUIRED A4
+    // misbind hardening for the locator path: the adoption tail must refuse
+    // a thread id already bound to another terminal (Validated Premise 9),
+    // so it must never be weakened when the candidate channel is deleted.
+    if let Some(existing) = state
+        .identity
+        .find_by_session_including_retired("codex", a.thread_id)
+    {
+        if existing != a.terminal_id {
+            tracing::warn!(
+                terminal_id = %a.terminal_id,
+                thread_id = %a.thread_id,
+                "codex_adopt_rejected: session_bound_elsewhere"
+            );
+            return false;
+        }
+    }
+    // Both identity homes -- different consumers (see opencode_association.rs:135-148).
+    state.identity.upsert(
+        a.terminal_id,
+        Some("codex"),
+        Some(a.thread_id),
+        a.cwd,
+        now_ms(),
+    );
+    state.registry.set_meta(
+        a.terminal_id,
+        None,
+        None,
+        Some("codex".to_string()),
+        Some(a.thread_id.to_string()),
+    );
+    // Durable ledger: binding row FIRST, pending marker delete SECOND --
+    // awaited before the broadcast (fsync-before-announce).
+    crate::pane_ledger::ledger_resolve_identity(state, a.terminal_id, "codex", a.thread_id, a.cwd)
+        .await;
+    broadcast_terminal_session_associated(
+        state,
+        a.terminal_id,
+        a.thread_id,
+        a.cwd.map(str::to_string),
+    );
+    // Activity hub (channel-deferred, safe off the dispatch path): G3 --
+    // codex.activity.updated / terminal.turn.complete carry the sessionId;
+    // G9 -- the rollout reconcile lane gets its file.
+    if let Some(hub) = &state.activity {
+        hub.bind_codex_session(a.terminal_id, a.thread_id);
+        if let Some(path) = a.rollout_path {
+            hub.attach_codex_rollout(a.terminal_id, a.thread_id, path);
+        }
+    }
+    true
+}
+
+/// Fan `terminal.session.associated` + a `terminal.meta.updated` upsert to
+/// every connection. Byte-for-byte the shape of
+/// `opencode_association.rs::broadcast_terminal_session_associated` with
+/// provider "codex". EMISSION ORDER IS PINNED: `associated` FIRST, then
+/// `meta.updated` (mirroring opencode_association.rs:163-198) -- the
+/// integration test awaits them in exactly this order, and
+/// `next_frame_of_type` drops out-of-order frames. Do not reorder.
+fn broadcast_terminal_session_associated(
+    state: &WsState,
+    terminal_id: &str,
+    session_id: &str,
+    cwd: Option<String>,
+) {
+    let associated = ServerMessage::TerminalSessionAssociated(TerminalSessionAssociated {
+        terminal_id: terminal_id.to_string(),
+        session_ref: SessionLocator {
+            provider: "codex".to_string(),
+            session_id: session_id.to_string(),
+        },
+    });
+    if let Ok(frame) = serde_json::to_string(&associated) {
+        let _ = state.broadcast_tx.send(frame);
+    }
+
+    let meta = ServerMessage::TerminalMetaUpdated(TerminalMetaUpdated {
+        remove: Vec::new(),
+        upsert: vec![TerminalMetaRecord {
+            terminal_id: terminal_id.to_string(),
+            updated_at: now_ms(),
+            branch: None,
+            checkout_root: None,
+            cwd,
+            display_subdir: None,
+            is_dirty: None,
+            provider: Some("codex".to_string()),
+            repo_root: None,
+            session_id: Some(session_id.to_string()),
+            token_usage: None,
+        }],
+    });
+    if let Ok(frame) = serde_json::to_string(&meta) {
+        let _ = state.broadcast_tx.send(frame);
+    }
+}
diff --git a/crates/freshell-ws/src/lib.rs b/crates/freshell-ws/src/lib.rs
index d1b9d9f8d..42eb2e654 100644
--- a/crates/freshell-ws/src/lib.rs
+++ b/crates/freshell-ws/src/lib.rs
@@ -24,6 +24,7 @@ pub mod activity;
 pub mod amplifier_association;
 pub mod backpressure;
 pub(crate) mod codex_candidate;
+pub(crate) mod codex_identity;
 pub(crate) mod codex_reconcile;
 pub mod create_limit;
 pub mod existence;
@@ -39,7 +40,7 @@ pub mod tabs;
 pub mod tabs_persist;
 pub mod terminal;
 
-pub use codex_candidate::codex_sessions_root;
+pub use codex_identity::codex_sessions_root;
 pub use codex_reconcile::locate_codex_rollout;
 
 use std::sync::Arc;

From 4b0209f9580ad98138de539230af6244688b5bb1 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:38:37 -0700
Subject: [PATCH 38/87] feat(client): recovery inventory types, API helper, and
 recovery-plan builder honoring the ledger authority chain (B3/P1.9)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 src/lib/api.ts                                |  7 ++
 src/lib/recovery/build-recovery-plan.ts       | 72 ++++++++++++++
 src/lib/recovery/types.ts                     | 61 ++++++++++++
 .../lib/recovery/build-recovery-plan.test.ts  | 96 +++++++++++++++++++
 4 files changed, 236 insertions(+)
 create mode 100644 src/lib/recovery/build-recovery-plan.ts
 create mode 100644 src/lib/recovery/types.ts
 create mode 100644 test/unit/client/lib/recovery/build-recovery-plan.test.ts

diff --git a/src/lib/api.ts b/src/lib/api.ts
index fc18e1e45..ae61deffe 100644
--- a/src/lib/api.ts
+++ b/src/lib/api.ts
@@ -9,6 +9,7 @@ import { getClientPerfConfig, isClientPerfLoggingEnabled, logClientPerf } from '
 import { getAuthToken } from '@/lib/auth'
 import { sanitizeSessionLocators } from '@/lib/session-utils'
 import type { SessionLocator } from '@/store/paneTypes'
+import type { RecoveryInventory } from '@/lib/recovery/types'
 import {
   type FreshAgentModelCapabilitiesResponse,
 } from '@shared/fresh-agent-model-capabilities'
@@ -284,6 +285,12 @@ export async function getBootstrap(options: ApiRequestOptions = {}): Promise<any
   return api.get('/api/bootstrap', options)
 }
 
+export async function getRecoveryInventory(clientInstanceId: string, bootAgoMs: number): Promise<RecoveryInventory> {
+  return api.get<RecoveryInventory>(
+    `/api/recovery/inventory${buildQueryString([['clientInstanceId', clientInstanceId], ['bootAgoMs', Math.max(0, Math.round(bootAgoMs))]])}`,
+  )
+}
+
 export async function getFreshAgentModelCapabilities(
   sessionType: string,
   options: ApiRequestOptions & { cwd?: string } = {},
diff --git a/src/lib/recovery/build-recovery-plan.ts b/src/lib/recovery/build-recovery-plan.ts
new file mode 100644
index 000000000..b988a7844
--- /dev/null
+++ b/src/lib/recovery/build-recovery-plan.ts
@@ -0,0 +1,72 @@
+import { nanoid } from 'nanoid'
+import type { PaneNode, PaneContent } from '@/store/paneTypes'
+import type { RecoveryInventory, RecoveryPane, LedgerOnlyEntry } from './types'
+
+function terminalContent(p: {
+  mode: string | null
+  shell: string | null
+  cwd: string | null
+  sessionRef: { provider: string; sessionId: string } | null
+  live: boolean
+}): PaneContent {
+  return {
+    kind: 'terminal',
+    createRequestId: nanoid(), // re-minted by restoreLayout normalization; required by the type
+    status: 'creating',
+    ...(p.mode ? { mode: p.mode } : {}),
+    ...(p.shell ? { shell: p.shell } : {}),
+    ...(p.cwd ? { initialCwd: p.cwd } : {}),
+    // D7: live sessions are left untouched - recreate the pane WITHOUT resume
+    ...(p.sessionRef && !p.live ? { sessionRef: p.sessionRef } : {}),
+  } as PaneContent
+}
+
+function paneContent(p: RecoveryPane): PaneContent {
+  if (p.kind === 'terminal') return terminalContent(p)
+  if (p.kind === 'editor') {
+    // EditorPaneContent.content is required (paneTypes.ts:116-130) but snapshots never
+    // capture buffer text - recreate with an empty buffer (data fact, D6)
+    return { content: '', ...p.payload, kind: 'editor' } as PaneContent
+  }
+  if (p.kind === 'fresh-agent') {
+    // normalize's existingRestoreError branch would drop sessionRef; strip restoreError
+    // and let normalize re-validate the ref itself (A10)
+    const { restoreError: _restoreError, ...payload } = p.payload
+    return { ...payload, kind: 'fresh-agent' } as PaneContent
+  }
+  return { ...p.payload, kind: p.kind } as PaneContent
+}
+
+function leaf(content: PaneContent): PaneNode {
+  return { type: 'leaf', id: nanoid(), content }
+}
+
+// D6: no split geometry in snapshots - right-leaning binary chain of even splits
+function chain(leaves: PaneNode[]): PaneNode {
+  if (leaves.length === 1) return leaves[0]
+  const [head, ...rest] = leaves
+  return { type: 'split', id: nanoid(), direction: 'horizontal', children: [head, chain(rest)], sizes: [50, 50] }
+}
+
+export interface RecoveryTabPlan { tabId: string; title: string; layout: PaneNode; paneTitles: Record<string, string> }
+
+export function countRecoverablePanes(inv: RecoveryInventory): number {
+  const device = inv.device?.tabs.reduce((n, t) => n + t.panes.length, 0) ?? 0
+  return device + inv.ledgerOnly.length
+}
+
+export function buildRecoveryPlan(inv: RecoveryInventory): RecoveryTabPlan[] {
+  const plans: RecoveryTabPlan[] = (inv.device?.tabs ?? [])
+    .filter((t) => t.panes.length > 0)
+    .map((t) => ({ tabId: nanoid(), title: t.tabName || 'Recovered', layout: chain(t.panes.map((p) => leaf(paneContent(p)))), paneTitles: {} }))
+  if (inv.ledgerOnly.length > 0) {
+    plans.push({
+      tabId: nanoid(),
+      title: 'Recovered sessions',
+      layout: chain(inv.ledgerOnly.map((e: LedgerOnlyEntry) =>
+        leaf(terminalContent({ mode: e.mode, shell: null, cwd: e.cwd, sessionRef: { provider: e.provider, sessionId: e.sessionId }, live: false })))),
+      paneTitles: {},
+    })
+  }
+  return plans
+}
diff --git a/src/lib/recovery/types.ts b/src/lib/recovery/types.ts
new file mode 100644
index 000000000..7361b741c
--- /dev/null
+++ b/src/lib/recovery/types.ts
@@ -0,0 +1,61 @@
+/**
+ * Client-side mirror of the `GET /api/recovery/inventory` response shape
+ * (Task 1's `build_inventory`, crates/freshell-server/src/recovery_inventory.rs).
+ */
+
+export interface RecoverySessionRef {
+  provider: string
+  sessionId: string
+}
+
+export type RecoveryLedgerState = 'bound' | 'closed' | 'gc_expired' | 'unknown'
+
+export interface RecoveryPane {
+  paneId: string
+  kind: string
+  mode: string | null
+  shell: string | null
+  cwd: string | null
+  payload: Record<string, unknown>
+  /** Effective (ledger-corrected) session ref — the D4 authority chain is applied server-side. */
+  sessionRef: RecoverySessionRef | null
+  ledgerState: RecoveryLedgerState
+  /** True when a Running terminal currently owns the effective session (D7). */
+  live: boolean
+}
+
+export interface RecoveryTab {
+  tabKey: string
+  tabName: string
+  panes: RecoveryPane[]
+}
+
+export interface RecoveryDevice {
+  deviceId: string
+  deviceLabel: string
+  capturedAt: number
+  tabs: RecoveryTab[]
+}
+
+export interface RecoveryOtherDevice {
+  deviceId: string
+  deviceLabel: string
+  capturedAt: number
+  paneCount: number
+}
+
+/** Ledger-bound session with no snapshot pane referencing it (live rows are excluded server-side, D7). */
+export interface LedgerOnlyEntry {
+  provider: string
+  sessionId: string
+  mode: string
+  cwd: string | null
+}
+
+export interface RecoveryInventory {
+  recoverable: boolean
+  contentId: string
+  device: RecoveryDevice | null
+  otherDevices: RecoveryOtherDevice[]
+  ledgerOnly: LedgerOnlyEntry[]
+}
diff --git a/test/unit/client/lib/recovery/build-recovery-plan.test.ts b/test/unit/client/lib/recovery/build-recovery-plan.test.ts
new file mode 100644
index 000000000..56db5fe61
--- /dev/null
+++ b/test/unit/client/lib/recovery/build-recovery-plan.test.ts
@@ -0,0 +1,96 @@
+import { describe, it, expect, vi } from 'vitest'
+import { buildRecoveryPlan, countRecoverablePanes } from '@/lib/recovery/build-recovery-plan'
+import type { RecoveryInventory } from '@/lib/recovery/types'
+
+vi.mock('nanoid', () => { let n = 0; return { nanoid: () => `nid-${++n}` } })
+
+const pane = (over: Partial<RecoveryInventory['device']['tabs'][0]['panes'][0]> = {}) => ({
+  paneId: 'p1', kind: 'terminal', mode: 'shell', shell: null, cwd: '/w',
+  payload: {}, sessionRef: null, ledgerState: 'unknown' as const, live: false, ...over,
+})
+const inv = (panes: unknown[], ledgerOnly: unknown[] = []): RecoveryInventory => ({
+  recoverable: true, contentId: 'cid',
+  device: { deviceId: 'd', deviceLabel: 'l', capturedAt: 1, tabs: [{ tabKey: 'k', tabName: 'work', panes }] },
+  otherDevices: [], ledgerOnly,
+} as RecoveryInventory)
+
+describe('buildRecoveryPlan', () => {
+  it('single terminal pane -> one tab, leaf layout, cwd + mode carried', () => {
+    const [tab] = buildRecoveryPlan(inv([pane()]))
+    expect(tab.title).toBe('work')
+    expect(tab.layout.type).toBe('leaf')
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content).toMatchObject({ kind: 'terminal', mode: 'shell', initialCwd: '/w' })
+    expect(content.sessionRef).toBeUndefined()
+  })
+
+  it('ledger-corrected sessionRef is used verbatim (authority chain applied server-side)', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ sessionRef: { provider: 'claude', sessionId: 'S2' }, ledgerState: 'bound', mode: 'claude' })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content.sessionRef).toEqual({ provider: 'claude', sessionId: 'S2' })
+  })
+
+  it('closed panes come back fresh: no sessionRef, same cwd/mode', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ ledgerState: 'closed', mode: 'claude' })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content.sessionRef).toBeUndefined()
+    expect(content).toMatchObject({ mode: 'claude', initialCwd: '/w' })
+  })
+
+  it('three panes -> right-leaning binary split chain', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ paneId: 'a' }), pane({ paneId: 'b' }), pane({ paneId: 'c' })]))
+    expect(tab.layout.type).toBe('split')
+    const root = tab.layout as { children: [{ type: string }, { type: string }] }
+    expect(root.children[0].type).toBe('leaf')
+    expect(root.children[1].type).toBe('split')
+  })
+
+  it('live panes are recreated WITHOUT resume: sessionRef stripped, cwd/mode kept (D7)', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ sessionRef: { provider: 'claude', sessionId: 'S2' }, ledgerState: 'bound', mode: 'claude', live: true })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content.sessionRef).toBeUndefined()
+    expect(content).toMatchObject({ kind: 'terminal', mode: 'claude', initialCwd: '/w' })
+  })
+
+  it('non-terminal kinds pass payload through', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ kind: 'browser', payload: { url: 'https://x.test' }, mode: null, cwd: null })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content).toMatchObject({ kind: 'browser', url: 'https://x.test' })
+  })
+
+  it('editor panes get the required content default (buffer text is never captured)', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ kind: 'editor', payload: { filePath: '/f.txt' }, mode: null, cwd: null })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content).toMatchObject({ kind: 'editor', filePath: '/f.txt', content: '' })
+  })
+
+  it('fresh-agent restoreError is stripped so normalize keeps the sessionRef', () => {
+    const [tab] = buildRecoveryPlan(inv([pane({ kind: 'fresh-agent',
+      payload: { sessionRef: { provider: 'freshclaude', sessionId: 'F1' }, restoreError: 'stale' }, mode: null, cwd: null })]))
+    const content = (tab.layout as { content: Record<string, unknown> }).content
+    expect(content.restoreError).toBeUndefined()
+    expect(content).toMatchObject({ kind: 'fresh-agent', sessionRef: { provider: 'freshclaude', sessionId: 'F1' } })
+  })
+
+  it('extension and picker payloads pass through', () => {
+    const [tab] = buildRecoveryPlan(inv([
+      pane({ paneId: 'x1', kind: 'extension', payload: { extensionId: 'ext.foo' }, mode: null, cwd: null }),
+      pane({ paneId: 'x2', kind: 'picker', payload: {}, mode: null, cwd: null }),
+    ]))
+    const root = tab.layout as { children: [{ content: Record<string, unknown> }, { content: Record<string, unknown> }] }
+    expect(root.children[0].content).toMatchObject({ kind: 'extension', extensionId: 'ext.foo' })
+    expect(root.children[1].content).toMatchObject({ kind: 'picker' })
+  })
+
+  it('ledgerOnly entries get a trailing Recovered sessions tab', () => {
+    const plans = buildRecoveryPlan(inv([pane()], [{ provider: 'codex', sessionId: 'C9', mode: 'codex', cwd: '/x' }]))
+    expect(plans).toHaveLength(2)
+    expect(plans[1].title).toBe('Recovered sessions')
+    const content = (plans[1].layout as { content: Record<string, unknown> }).content
+    expect(content).toMatchObject({ kind: 'terminal', mode: 'codex', initialCwd: '/x', sessionRef: { provider: 'codex', sessionId: 'C9' } })
+  })
+
+  it('countRecoverablePanes sums device panes and ledgerOnly', () => {
+    expect(countRecoverablePanes(inv([pane(), pane({ paneId: 'p2' })], [{ provider: 'codex', sessionId: 'C9', mode: 'codex', cwd: null }]))).toBe(3)
+  })
+})

From 26102523c0080e3484dbd0e6b17b871983ac8be0 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:40:04 -0700
Subject: [PATCH 39/87] feat(protocol): pane.reconcile client schemas, ready
 capabilities, reconcile pane fields
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the client-side wire surface for the reconciliation handshake:
- ReconcileSessionRefSchema / ReconcilePaneSchema / PaneReconcileRequestSchema
  (200-pane cap, added to ClientMessageSchema union)
- PaneVerdictSchema with the 6-verdict enum (attach|respawn|fresh|
  dead_session|invalid|error - no retry), PaneReconcileResultSchema,
  PaneReconcileResultMessage added to the ServerMessage union
- ReadyCapabilitiesSchema (paneReconcileV1) merged into ReadyMessage
- Error frame gains additive retryAfterMs?: number and SESSION_RESERVED code
- TerminalPaneContent gains reconcileNotice / pendingReconcile /
  reconcileEpoch (volatile fold counter); normalizePaneContent whitelists
  all three

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 shared/ws-protocol.ts                         | 81 +++++++++++++++++++
 src/store/paneTypes.ts                        |  6 ++
 src/store/panesSlice.ts                       |  5 ++
 .../unit/shared/ws-protocol.reconcile.test.ts | 37 +++++++++
 4 files changed, 129 insertions(+)
 create mode 100644 test/unit/shared/ws-protocol.reconcile.test.ts

diff --git a/shared/ws-protocol.ts b/shared/ws-protocol.ts
index 522017b7a..f7470f61c 100644
--- a/shared/ws-protocol.ts
+++ b/shared/ws-protocol.ts
@@ -32,6 +32,7 @@ export const ErrorCode = z.enum([
   'RATE_LIMITED',
   'UNAUTHORIZED',
   'PROTOCOL_MISMATCH',
+  'SESSION_RESERVED',
 ])
 
 export type ErrorCode = z.infer<typeof ErrorCode>
@@ -564,9 +565,84 @@ export const FreshAgentClientMessageSchema = z.discriminatedUnion('type', [
 
 export type FreshAgentClientMessage = z.infer<typeof FreshAgentClientMessageSchema>
 
+// ── pane.reconcile (reconciliation handshake) ──
+
+export const ReconcileSessionRefSchema = SessionLocatorSchema
+
+export const ReconcilePaneSchema = z.object({
+  /** Opaque to the server; echoed verbatim on the verdict. */
+  paneKey: z.string().min(1),
+  /** v1: 'terminal' only. */
+  kind: z.literal('terminal'),
+  /** TerminalMode string as persisted ('shell', 'claude', …). */
+  mode: z.string().min(1),
+  /** The pane's stable creation key — required by contract. */
+  createRequestId: z.string().min(1),
+  /** Last known live handle. */
+  terminalId: z.string().min(1).optional(),
+  /** Locality hint, informational only. */
+  serverInstanceId: z.string().min(1).optional(),
+  /** Optional identity claim. */
+  sessionRef: ReconcileSessionRefSchema.optional(),
+  /** Optional legacy single-key claim. */
+  resumeSessionId: z.string().optional(),
+  /** Informational only — never trusted. */
+  status: z.string().optional(),
+})
+
+export const PaneReconcileRequestSchema = z.object({
+  type: z.literal('pane.reconcile.request'),
+  /** Client-minted, echoed verbatim; correlation only. */
+  reconcileId: z.string().min(1),
+  /** Flat list — no tree, no tab structure. Cap: 200 entries. */
+  panes: z.array(ReconcilePaneSchema).max(200),
+})
+
+export type ReconcilePane = z.infer<typeof ReconcilePaneSchema>
+export type PaneReconcileRequest = z.infer<typeof PaneReconcileRequestSchema>
+
+export const PaneVerdictSchema = z.object({
+  /** Echoed verbatim, 1:1 with request order. */
+  paneKey: z.string().min(1),
+  verdict: z.enum(['attach', 'respawn', 'fresh', 'dead_session', 'invalid', 'error']),
+  /** attach only: the live terminal to attach to. */
+  terminalId: z.string().min(1).optional(),
+  /**
+   * attach: authoritative identity; respawn: THE identity to resume with;
+   * dead_session: the claimed-but-missing identity, for the error UI.
+   */
+  sessionRef: ReconcileSessionRefSchema.optional(),
+  /** Present iff the server overrode a differing client claim. */
+  corrected: z.literal(true).optional(),
+  /** fresh / dead_session / error / invalid: machine-readable code. */
+  reason: z.string().optional(),
+  /** A newer duplicate generation exists for the same createRequestId; flags the duplicate terminalId. */
+  duplicate: z.string().optional(),
+})
+
+export const PaneReconcileResultSchema = z.object({
+  type: z.literal('pane.reconcile.result'),
+  /** Echoed from the request. */
+  reconcileId: z.string().min(1),
+  /** This server process's boot. */
+  bootId: z.string().min(1),
+  serverInstanceId: z.string().min(1),
+  /** Cardinality invariant: verdicts.length === panes.length, matched 1:1 by paneKey. */
+  verdicts: z.array(PaneVerdictSchema),
+})
+
+export type PaneVerdict = z.infer<typeof PaneVerdictSchema>
+export type PaneReconcileResultMessage = z.infer<typeof PaneReconcileResultSchema>
+
+/** Server capability advertisement on `ready`: present iff the client's hello opted in via capabilities.paneReconcileV1. */
+export const ReadyCapabilitiesSchema = z.object({ paneReconcileV1: z.literal(true).optional() }).optional()
+
+export type ReadyCapabilities = z.infer<typeof ReadyCapabilitiesSchema>
+
 // ── Client message discriminated union ──
 
 export const ClientMessageSchema = z.discriminatedUnion('type', [
+  PaneReconcileRequestSchema,
   HelloSchema,
   PingSchema,
   ClientDiagnosticSchema,
@@ -610,6 +686,8 @@ export type ReadyMessage = {
   timestamp: string
   serverInstanceId?: string
   bootId?: string
+  /** Present iff the client's hello opted in via capabilities.paneReconcileV1. */
+  capabilities?: ReadyCapabilities
 }
 
 export type PongMessage = {
@@ -626,6 +704,8 @@ export type ErrorMessage = {
   terminalExitCode?: number
   expectedSessionRef?: SessionLocator
   actualSessionRef?: SessionLocator
+  /** SESSION_RESERVED only: how long the loser should wait before re-sending its create. Additive; omitted everywhere else. */
+  retryAfterMs?: number
   timestamp: string
 }
 
@@ -1004,6 +1084,7 @@ export type ServerMessage =
   | TerminalsChangedMessage
   | TerminalMetaUpdatedMessage
   | TerminalInventoryMessage
+  | PaneReconcileResultMessage
   | CodexActivityListResponseMessage
   | CodexActivityUpdatedMessage
   | OpencodeActivityListResponseMessage
diff --git a/src/store/paneTypes.ts b/src/store/paneTypes.ts
index eb41ab220..1acc90a72 100644
--- a/src/store/paneTypes.ts
+++ b/src/store/paneTypes.ts
@@ -94,6 +94,12 @@ export type TerminalPaneContent = {
   restoreError?: RestoreError
   /** Initial working directory */
   initialCwd?: string
+  /** One-shot user-visible reconcile notice (corrected identity, fresh-by-reason, duplicate ignored). Rendered then cleared by TerminalView. */
+  reconcileNotice?: string
+  /** Set by verdict folding; consumed by TerminalView when it sends terminal.create. 'respawn' = create-with-resume from sessionRef; 'fresh' = clean create. */
+  pendingReconcile?: 'respawn' | 'fresh'
+  /** VOLATILE fold counter. Incremented by applyReconcileAttach / resetPaneForReconcileCreate so a fold on an already-mounted pane (same createRequestId — never re-minted) re-fires TerminalView's create-or-attach effect (Task 12 adds it to the dep array). Stripped from persistence (Task 8). */
+  reconcileEpoch?: number
 }
 
 /**
diff --git a/src/store/panesSlice.ts b/src/store/panesSlice.ts
index a82cf3af1..031dfd77e 100644
--- a/src/store/panesSlice.ts
+++ b/src/store/panesSlice.ts
@@ -93,6 +93,11 @@ function normalizePaneContent(
       streamId: typeof input.streamId === 'string' && input.streamId.length > 0 ? input.streamId : undefined,
       ...(restoreError.success ? { restoreError: restoreError.data } : {}),
       initialCwd: typeof input.initialCwd === 'string' ? input.initialCwd : undefined,
+      reconcileNotice: typeof input.reconcileNotice === 'string' ? input.reconcileNotice : undefined,
+      pendingReconcile: input.pendingReconcile === 'respawn' || input.pendingReconcile === 'fresh'
+        ? input.pendingReconcile
+        : undefined,
+      reconcileEpoch: typeof input.reconcileEpoch === 'number' ? input.reconcileEpoch : undefined,
     }
   }
   if (input.kind === 'browser') {
diff --git a/test/unit/shared/ws-protocol.reconcile.test.ts b/test/unit/shared/ws-protocol.reconcile.test.ts
new file mode 100644
index 000000000..45908d1a0
--- /dev/null
+++ b/test/unit/shared/ws-protocol.reconcile.test.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import {
+  PaneReconcileRequestSchema,
+  PaneReconcileResultSchema,
+  ClientMessageSchema,
+} from '@shared/ws-protocol'
+
+describe('pane.reconcile schemas', () => {
+  const request = {
+    type: 'pane.reconcile.request',
+    reconcileId: 'rec-1',
+    panes: [{
+      paneKey: 'tab1:paneA', kind: 'terminal', mode: 'claude',
+      createRequestId: 'cr-1', terminalId: 'term-1',
+      sessionRef: { provider: 'claude', sessionId: 's-1' }, status: 'running',
+    }],
+  }
+  it('parses a valid request and accepts it in the client union', () => {
+    expect(PaneReconcileRequestSchema.parse(request)).toBeTruthy()
+    expect(ClientMessageSchema.safeParse(request).success).toBe(true)
+  })
+  it('rejects >200 panes', () => {
+    const big = { ...request, panes: Array.from({ length: 201 }, (_, i) => ({ ...request.panes[0], paneKey: `t:${i}` })) }
+    expect(PaneReconcileRequestSchema.safeParse(big).success).toBe(false)
+  })
+  it('parses a result with the 6-verdict enum and no retry', () => {
+    const result = {
+      type: 'pane.reconcile.result', reconcileId: 'rec-1', bootId: 'b1', serverInstanceId: 'srv1',
+      verdicts: [
+        { paneKey: 'tab1:paneA', verdict: 'attach', terminalId: 'term-1', corrected: true },
+        { paneKey: 'tab1:paneB', verdict: 'error', reason: 'index_warming' },
+      ],
+    }
+    expect(PaneReconcileResultSchema.parse(result)).toBeTruthy()
+    expect(PaneReconcileResultSchema.safeParse({ ...result, verdicts: [{ paneKey: 'x', verdict: 'retry' }] }).success).toBe(false)
+  })
+})

From 18a9469edbd48a7732382b5e47dbdb21775cb926 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:40:56 -0700
Subject: [PATCH 40/87] refactor(ws): delete duplicated guard 3b from candidate
 handler - adopt_codex_identity owns it

---
 crates/freshell-ws/src/codex_candidate.rs | 31 +++++------------------
 1 file changed, 7 insertions(+), 24 deletions(-)

diff --git a/crates/freshell-ws/src/codex_candidate.rs b/crates/freshell-ws/src/codex_candidate.rs
index 3946598ec..0ae13cb38 100644
--- a/crates/freshell-ws/src/codex_candidate.rs
+++ b/crates/freshell-ws/src/codex_candidate.rs
@@ -7,10 +7,13 @@
 //! `server/ws-handler.ts:2951-2963`):
 //!   1. the terminalId exists in the registry
 //!   2. that terminal is codex-mode
-//!   3. the terminal is not already bound to a DIFFERENT thread id (stale
-//!      replay) and the claimed thread id is not already bound to a DIFFERENT
-//!      terminal -- live OR retired (cross-pane hijack, including replaying a
-//!      DEAD pane's candidate onto a fresh pane)
+//!   3. binding uniqueness, in two halves: 3a -- the terminal is not already
+//!      bound to a DIFFERENT thread id (stale replay), enforced HERE; and
+//!      3b -- the claimed thread id is not already bound to a DIFFERENT
+//!      terminal, live OR retired (cross-pane hijack, including replaying a
+//!      DEAD pane's candidate onto a fresh pane), enforced INSIDE
+//!      `adopt_codex_identity` (codex_identity.rs), the shared adoption
+//!      tail, not by this handler
 //!   4. disk truth: the rolloutPath canonicalizes under the codex sessions
 //!      root and its FIRST JSONL record is a `session_meta` whose
 //!      `payload.id` is the claimed thread id (bounded 1MB read; legacy
@@ -139,26 +142,6 @@ pub(crate) async fn handle_codex_candidate_persisted(
         }
         return;
     }
-    // Guard 3b: the claimed session is not bound to a DIFFERENT terminal --
-    // live OR retired (cross-pane hijack). Retired-INCLUSIVE deliberately
-    // (ledger A8): a victim's binding is retired at exit, so a live-only
-    // lookup would let a DEAD pane's candidate be replayed onto a fresh
-    // terminal. Blocks no legitimate flow: every legit resume binds at
-    // create time and short-circuits at guard 3a above.
-    if let Some(other_tid) = state
-        .identity
-        .find_by_session_including_retired("codex", thread_id)
-    {
-        if other_tid != msg.terminal_id {
-            tracing::warn!(
-                terminal_id = %msg.terminal_id,
-                candidate_thread_id = %thread_id,
-                bound_terminal_id = %other_tid,
-                "codex_candidate_rejected: session_bound_elsewhere"
-            );
-            return;
-        }
-    }
     // Guard 4: disk truth.
     let Some(root) = codex_sessions_root() else {
         tracing::warn!(

From ec4324eb772f56993e36ccac5ac82a114a8ea4fa Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:44:42 -0700
Subject: [PATCH 41/87] feat(codex): write fresh-agent ledger binding rows at
 every identity event (P1.13)

---
 crates/freshell-freshagent/src/codex.rs | 306 ++++++++++++++++++++++--
 1 file changed, 291 insertions(+), 15 deletions(-)

diff --git a/crates/freshell-freshagent/src/codex.rs b/crates/freshell-freshagent/src/codex.rs
index 96f4ebb1a..d0bc254fe 100644
--- a/crates/freshell-freshagent/src/codex.rs
+++ b/crates/freshell-freshagent/src/codex.rs
@@ -288,11 +288,91 @@ impl FreshCodexState {
     }
 
     /// The wired identity sink, if any.
-    #[allow(dead_code)] // used by identity-event tasks (Tasks 4-10)
     fn identity_sink(&self) -> Option<SharedPaneIdentitySink> {
         self.identity_sink.get().cloned()
     }
 
+    /// P1.13: write one fresh-agent binding row (FULL settings snapshot) through the
+    /// identity sink. AWAITED at every identity site (the wave-A durable-before-answer
+    /// policy) BEFORE that site's reply/broadcast goes out; a failed write is surfaced
+    /// user-visibly ([`Self::emit_fresh_agent_error`], never warn-and-drop) and then the
+    /// identity event proceeds -- a write failure never blocks it.
+    #[allow(clippy::too_many_arguments)]
+    async fn record_codex_binding(
+        &self,
+        session_id: &str,
+        create_request_id: Option<&str>,
+        model: &str,
+        sandbox: Option<&str>,
+        permission_mode: Option<&str>,
+        effort: Option<&str>,
+        cwd: Option<&str>,
+        supersedes: Option<&str>,
+    ) {
+        let Some(sink) = self.identity_sink() else {
+            return;
+        };
+        let settings = crate::identity_sink::FreshAgentSettings {
+            model: if model.is_empty() {
+                None
+            } else {
+                Some(model.into())
+            },
+            sandbox: sandbox.map(Into::into),
+            permission_mode: permission_mode.map(Into::into),
+            effort: effort.map(Into::into),
+            cwd: cwd.map(Into::into),
+        };
+        // No-laundering guard (V7/A10): never persist an all-blank snapshot --
+        // it would mask a genuine record miss forever. Real creates always carry
+        // at least cwd; a supersession write always goes through (G3 linkage).
+        if settings == crate::identity_sink::FreshAgentSettings::default() && supersedes.is_none() {
+            return;
+        }
+        if let Err(e) = sink
+            .record_binding(crate::identity_sink::FreshAgentBindingUpsert {
+                provider: "codex".into(),
+                session_id: session_id.into(),
+                mode: "freshcodex".into(),
+                create_request_id: create_request_id.map(Into::into),
+                resolves_pending: None,
+                supersedes: supersedes.map(Into::into),
+                settings,
+            })
+            .await
+        {
+            tracing::warn!(error = %e, session = %session_id, "freshagent.codex.ledger_write_failed");
+            self.emit_fresh_agent_error(
+                session_id,
+                "LEDGER_WRITE_FAILED",
+                "Failed to persist this session's resume record - settings may not survive a server restart.",
+            );
+        }
+    }
+
+    /// Broadcast a `freshAgent.error` alarm/degradation frame (Tasks 5/6 consume this
+    /// too). Wire shape (V1/A2, verified against `fresh-agent-ws.ts:182-193`):
+    /// `{ "type": "freshAgent.event", "sessionId", "sessionType", "provider",
+    /// "event": { "type": "freshAgent.error", "code", "message" } }` -- built on the
+    /// SAME [`ServerMessage::FreshAgentEvent`] envelope [`lost_session_frame`] uses (the
+    /// existing `freshAgent.error` forwarding path), so it is byte-compatible with the
+    /// frozen client's banner path: top-level `sessionType`/`provider` are REQUIRED
+    /// (locator resolution) and `message` is user-facing (the banner shows the message,
+    /// never the code).
+    fn emit_fresh_agent_error(&self, session_id: &str, code: &str, message: &str) {
+        self.broadcast(&ServerMessage::FreshAgentEvent(FreshAgentEvent {
+            event: json!({
+                "type": "freshAgent.error",
+                "sessionId": session_id,
+                "code": code,
+                "message": message,
+            }),
+            provider: PROVIDER.to_string(),
+            session_id: session_id.to_string(),
+            session_type: SESSION_TYPE.to_string(),
+        }));
+    }
+
     /// The `PATCH /api/settings` sub-router (the fresh-clients enable toggle).
     pub fn settings_router(&self) -> Router {
         Router::new()
@@ -636,11 +716,11 @@ impl FreshCodexState {
             thread_id.clone(),
             CodexSession {
                 client,
-                model,
-                effort,
+                model: model.clone(),
+                effort: effort.clone(),
                 cwd: cwd.clone(),
-                sandbox,
-                permission_mode,
+                sandbox: sandbox.clone(),
+                permission_mode: permission_mode.clone(),
                 active_turn,
                 consumer,
                 kill_tx: Some(kill_tx),
@@ -649,6 +729,22 @@ impl FreshCodexState {
             },
         );
 
+        // P1.13 identity event (Task 4): the ledger binding row for this create,
+        // AWAITED before the `freshAgent.created` reply below goes out
+        // (durable-before-answer). Covers both the healthy create and the
+        // `handle_create_resume` (R1) path -- both funnel through this shared tail.
+        self.record_codex_binding(
+            &thread_id,
+            Some(&request_id),
+            &model,
+            sandbox.as_deref(),
+            permission_mode.as_deref(),
+            effort.as_deref(),
+            cwd.as_deref(),
+            None,
+        )
+        .await;
+
         // DIAG-01: fresh-agent session lifecycle -- provider/session_id/cwd,
         // never the turn text/prompt content.
         tracing::info!(
@@ -1264,11 +1360,11 @@ impl FreshCodexState {
                 session_id.to_string(),
                 CodexSession {
                     client,
-                    model,
-                    effort,
-                    cwd,
-                    sandbox,
-                    permission_mode,
+                    model: model.clone(),
+                    effort: effort.clone(),
+                    cwd: cwd.clone(),
+                    sandbox: sandbox.clone(),
+                    permission_mode: permission_mode.clone(),
                     active_turn,
                     consumer,
                     kill_tx: Some(kill_tx),
@@ -1278,6 +1374,22 @@ impl FreshCodexState {
             );
         }
 
+        // P1.13 identity event (Task 4, R2): refresh write under the SAME id --
+        // snapshots the LIVE in-session values (which originate from a real
+        // create/user change); the helper's no-laundering guard skips it if they
+        // are all blank. AWAITED before this fn returns (durable-before-answer).
+        self.record_codex_binding(
+            session_id,
+            None,
+            &model,
+            sandbox.as_deref(),
+            permission_mode.as_deref(),
+            effort.as_deref(),
+            cwd.as_deref(),
+            None,
+        )
+        .await;
+
         // FIX (CODEX-FIRST triage Finding 2): the app-server just proved this id alive again
         // -- clear any stale "recently gone" marking so it doesn't linger.
         self.clear_dead_thread(session_id).await;
@@ -1351,11 +1463,11 @@ impl FreshCodexState {
                 new_thread_id.clone(),
                 CodexSession {
                     client,
-                    model,
-                    effort,
-                    cwd,
-                    sandbox,
-                    permission_mode,
+                    model: model.clone(),
+                    effort: effort.clone(),
+                    cwd: cwd.clone(),
+                    sandbox: sandbox.clone(),
+                    permission_mode: permission_mode.clone(),
                     active_turn,
                     consumer,
                     kill_tx: Some(kill_tx),
@@ -1365,6 +1477,23 @@ impl FreshCodexState {
             );
         }
 
+        // P1.13 identity event (Task 4): NEW ledger row under the new thread id with
+        // `supersedes: Some(old_thread_id)` -- the G3 supersession linkage (V8/A14):
+        // the ledger retires the old row and links it to the new one. This is the
+        // ONLY site that ever knows both ids; the edge is unrecoverable if not
+        // written here. AWAITED before the materialized broadcast below goes out.
+        self.record_codex_binding(
+            &new_thread_id,
+            None,
+            &model,
+            sandbox.as_deref(),
+            permission_mode.as_deref(),
+            effort.as_deref(),
+            cwd.as_deref(),
+            Some(old_session_id),
+        )
+        .await;
+
         // DIAG-01: crash recovery had to mint a fresh thread -- the durable
         // identity MOVED (old_session_id -> new_thread_id); conversation
         // memory for the old thread is lost. `warn`, unlike the resume-first
@@ -1823,6 +1952,15 @@ impl FreshCodexState {
                 },
             );
         }
+
+        // P1.13 identity event (Task 4, R3): refresh write, `supersedes: None`. Until
+        // Task 5 lands this registers blanks (plus any caller-supplied cwd), so the
+        // helper's no-laundering guard makes the all-blank case a no-op -- never a
+        // defaults row for a never-recorded historical session (V7). AWAITED before
+        // this fn returns (durable-before-answer).
+        self.record_codex_binding(thread_id, None, "", None, None, None, cwd, None)
+            .await;
+
         Ok(ResumedCodexSession {
             client,
             active_turn,
@@ -5084,6 +5222,144 @@ pub(crate) mod tests {
         assert_eq!(exited_frame["sessionId"], session_id);
     }
 
+    /// Task 4 (P1.13): a healthy create writes a fresh-agent binding row (provider
+    /// `codex`, mode `freshcodex`, FULL settings snapshot) through the identity sink
+    /// at thread/start -- the ledger row a restarted server later resumes from.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn create_records_fresh_agent_binding_with_settings() {
+        let _guard = ENV_LOCK.lock().await;
+        configure_fake_codex_cmd("{}");
+        let (state, mut rx) = state_with_bus();
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        state.set_identity_sink(fake.clone());
+
+        // Drive a real create through the fake app server, requesting explicit
+        // settings -- `create_real_fake_session` doesn't accept settings, so this
+        // inlines the same `freshAgent.create` the existing create tests send.
+        let tmp_cwd = std::env::temp_dir().to_string_lossy().to_string();
+        state
+            .handle_create(FreshAgentCreate {
+                request_id: "req-bind-1".to_string(),
+                session_type: freshell_protocol::SessionType::Freshcodex,
+                provider: Some(freshell_protocol::AgentProvider::Codex),
+                cwd: Some(tmp_cwd),
+                legacy_restore_context: None,
+                resume_session_id: None,
+                session_ref: None,
+                model: Some("gpt-5.3-codex-spark".to_string()),
+                model_selection: None,
+                permission_mode: Some("on-request".to_string()),
+                sandbox: Some(freshell_protocol::Sandbox::WorkspaceWrite),
+                effort: Some("high".to_string()),
+                plugins: None,
+            })
+            .await;
+        let created: Value = tokio::time::timeout(std::time::Duration::from_secs(15), async {
+            loop {
+                let frame: Value = serde_json::from_str(&rx.recv().await.unwrap()).unwrap();
+                if frame["type"] == "freshAgent.created"
+                    || frame["type"] == "freshAgent.create.failed"
+                {
+                    return frame;
+                }
+            }
+        })
+        .await
+        .expect("the fake app-server responds within the budget");
+        assert_eq!(
+            created["type"], "freshAgent.created",
+            "fixture create failed: {created}"
+        );
+        let thread_id = created["sessionId"].as_str().unwrap().to_string();
+
+        let bindings = fake.bindings.lock().unwrap();
+        let b = bindings
+            .iter()
+            .find(|b| b.session_id == thread_id)
+            .expect("binding row written at thread/start");
+        assert_eq!(b.provider, "codex");
+        assert_eq!(b.mode, "freshcodex");
+        assert_eq!(b.settings.model.as_deref(), Some("gpt-5.3-codex-spark"));
+        assert_eq!(b.settings.sandbox.as_deref(), Some("workspace-write"));
+        assert_eq!(b.settings.permission_mode.as_deref(), Some("on-request"));
+        assert_eq!(b.settings.effort.as_deref(), Some("high"));
+    }
+
+    /// Task 4 (P1.13, awaited-writes policy): a failed ledger write is surfaced as a
+    /// live `freshAgent.error{code:'LEDGER_WRITE_FAILED'}` frame (never a silent
+    /// warn-and-drop) AND the create still succeeds -- a write failure never blocks
+    /// the identity event.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn ledger_write_failure_is_surfaced_as_a_live_frame() {
+        let _guard = ENV_LOCK.lock().await;
+        configure_fake_codex_cmd("{}");
+        let (state, mut rx) = state_with_bus();
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        fake.fail_writes
+            .store(true, std::sync::atomic::Ordering::SeqCst);
+        state.set_identity_sink(fake.clone());
+
+        state
+            .handle_create(FreshAgentCreate {
+                request_id: "req-ledger-fail".to_string(),
+                session_type: freshell_protocol::SessionType::Freshcodex,
+                provider: Some(freshell_protocol::AgentProvider::Codex),
+                cwd: None,
+                legacy_restore_context: None,
+                resume_session_id: None,
+                session_ref: None,
+                model: Some("gpt-5.3-codex-spark".to_string()),
+                model_selection: None,
+                permission_mode: None,
+                sandbox: None,
+                effort: None,
+                plugins: None,
+            })
+            .await;
+
+        // Drain the bus (bounded, as in the alarm tests): both the alarm frame and
+        // the created frame must arrive -- in either order.
+        let mut failure_frame: Option<Value> = None;
+        let mut created_frame: Option<Value> = None;
+        tokio::time::timeout(std::time::Duration::from_secs(15), async {
+            loop {
+                let frame: Value = serde_json::from_str(&rx.recv().await.unwrap()).unwrap();
+                if frame["type"] == "freshAgent.event"
+                    && frame["event"]["code"] == "LEDGER_WRITE_FAILED"
+                {
+                    failure_frame = Some(frame);
+                } else if frame["type"] == "freshAgent.created" {
+                    created_frame = Some(frame);
+                }
+                if failure_frame.is_some() && created_frame.is_some() {
+                    return;
+                }
+            }
+        })
+        .await
+        .expect("a LEDGER_WRITE_FAILED frame AND freshAgent.created arrive within the budget");
+
+        let failure = failure_frame.expect("a LEDGER_WRITE_FAILED frame was broadcast");
+        assert_eq!(failure["sessionType"], "freshcodex");
+        assert_eq!(failure["provider"], "codex");
+        assert_eq!(failure["event"]["type"], "freshAgent.error");
+        assert!(
+            failure["event"]["message"]
+                .as_str()
+                .is_some_and(|m| !m.is_empty()),
+            "the alarm carries a user-facing message: {failure}"
+        );
+
+        // The create still succeeded: the session exists under the created id.
+        let created = created_frame.expect("the create still succeeded");
+        let thread_id = created["sessionId"].as_str().unwrap().to_string();
+        let guard = state.sessions.lock().await;
+        assert!(
+            guard.contains_key(&thread_id),
+            "a write failure never blocks the identity event"
+        );
+    }
+
     /// FIX-2 (codex-first triage): crash recovery is resume-first now. The crashed
     /// sidecar respawns, `thread/resume`s the ORIGINAL thread id, and the turn completes
     /// under that SAME id -- no `freshAgent.session.materialized` broadcast (the durable

From f4322f85cada44577bfe5fd912ea372c2cc97a78 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:48:52 -0700
Subject: [PATCH 42/87] feat(client): self-gating recover-my-panes offer panel
 with accept/decline (B3/P1.9)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

RecoveryOfferPanel decides its own eligibility (D1: skip when the boot had a
persisted layout unless a pending offer survives; D2: bootAgoMs anchored to the
original pre-junk boot across re-offers), fetches the recovery inventory once,
and offers to recreate lost tabs. Accept replays buildRecoveryPlan via
addTab + restoreLayout and arms terminal restore for every sessionRef-bearing
terminal leaf (live panes never arm - Task 4 strips their refs, D7). Decline
records dismissal for the contentId and clears the pending flag.

Note: the brief's tabRegistrySync export change was superseded - the getter is
already exported as getCurrentTabRegistryClientInstanceId; no alias added.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 src/components/RecoveryOfferPanel.tsx         | 157 +++++++++++++++
 ...RecoveryOfferPanel.persisted-boot.test.tsx |  96 ++++++++++
 .../components/RecoveryOfferPanel.test.tsx    | 181 ++++++++++++++++++
 3 files changed, 434 insertions(+)
 create mode 100644 src/components/RecoveryOfferPanel.tsx
 create mode 100644 test/unit/client/components/RecoveryOfferPanel.persisted-boot.test.tsx
 create mode 100644 test/unit/client/components/RecoveryOfferPanel.test.tsx

diff --git a/src/components/RecoveryOfferPanel.tsx b/src/components/RecoveryOfferPanel.tsx
new file mode 100644
index 000000000..67a480dab
--- /dev/null
+++ b/src/components/RecoveryOfferPanel.tsx
@@ -0,0 +1,157 @@
+import { useEffect, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { useAppDispatch, useAppStore } from '@/store/hooks'
+import type { RootState } from '@/store/store'
+import { getRecoveryInventory } from '@/lib/api'
+import { hadPersistedLayoutAtBoot, bootCapturedAtMs } from '@/lib/recovery/boot-state'
+import {
+  getPendingOffer,
+  setPendingOffer,
+  clearPendingOffer,
+  isDismissed,
+  recordDismissal,
+} from '@/lib/recovery/dismissal'
+import { buildRecoveryPlan, countRecoverablePanes } from '@/lib/recovery/build-recovery-plan'
+import type { RecoveryInventory } from '@/lib/recovery/types'
+import { getCurrentTabRegistryClientInstanceId } from '@/store/tabRegistrySync'
+import { addTab } from '@/store/tabsSlice'
+import { restoreLayout } from '@/store/panesSlice'
+import { addTerminalRestoreRequestId } from '@/lib/terminal-restore'
+import type { PaneNode } from '@/store/paneTypes'
+import { OVERLAY_Z } from '@/components/ui/overlay'
+import { Button } from '@/components/ui/button'
+
+const HEADING_ID = 'recovery-offer-heading'
+
+function walkArmingRestores(node: PaneNode | undefined): void {
+  if (!node) return
+  if (node.type === 'leaf') {
+    const content = node.content
+    if (content.kind === 'terminal' && content.sessionRef && content.createRequestId) {
+      // Post-normalization id — restoreLayout's reducer re-minted it (App.tsx:1069 pattern).
+      addTerminalRestoreRequestId(content.createRequestId)
+    }
+    return
+  }
+  for (const child of node.children) walkArmingRestores(child)
+}
+
+/**
+ * Arms terminal restore for every terminal leaf carrying a sessionRef in the
+ * given tabs' post-normalization layouts. Live panes never arm: Task 4's plan
+ * builder strips their sessionRef (D7), so the walk skips them naturally.
+ */
+export function armRecoveredTerminalRestores(state: Pick<RootState, 'panes'>, tabIds: string[]): void {
+  for (const tabId of tabIds) {
+    walkArmingRestores(state.panes.layouts[tabId])
+  }
+}
+
+/**
+ * Self-gating recover-my-panes offer (D1/D3): rendered unconditionally from App,
+ * decides its own eligibility, fetches the recovery inventory once, and offers
+ * to recreate the lost tabs from server memory.
+ */
+export function RecoveryOfferPanel(): JSX.Element | null {
+  const dispatch = useAppDispatch()
+  const store = useAppStore()
+  const [inventory, setInventory] = useState<RecoveryInventory | null>(null)
+
+  useEffect(() => {
+    const pending = getPendingOffer()
+    // D1: a boot that found a persisted layout lost nothing — unless a pending
+    // offer from an earlier (empty) boot is still awaiting an answer.
+    if (hadPersistedLayoutAtBoot && !pending) return
+    // D2: anchor the server's concurrent-client cutoff to the ORIGINAL
+    // pre-junk boot, also across pending re-offers.
+    const bootAt = pending?.bootAt ?? bootCapturedAtMs
+    let cancelled = false
+    getRecoveryInventory(getCurrentTabRegistryClientInstanceId(), Date.now() - bootAt)
+      .then((inv) => {
+        if (cancelled) return
+        if (!inv.recoverable || isDismissed(inv.contentId)) return
+        setPendingOffer(inv.contentId, bootAt)
+        setInventory(inv)
+      })
+      .catch(() => {
+        // Recovery is best-effort: on fetch failure, stay quiet.
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  const accept = () => {
+    if (!inventory) return
+    clearPendingOffer()
+    const plans = buildRecoveryPlan(inventory)
+    for (const plan of plans) {
+      dispatch(addTab({ id: plan.tabId, title: plan.title }))
+      dispatch(restoreLayout({ tabId: plan.tabId, layout: plan.layout, paneTitles: plan.paneTitles }))
+    }
+    armRecoveredTerminalRestores(store.getState(), plans.map((p) => p.tabId))
+    setInventory(null)
+  }
+
+  const decline = () => {
+    if (inventory) recordDismissal(inventory.contentId)
+    clearPendingOffer()
+    setInventory(null)
+  }
+
+  if (!inventory) return null
+
+  const paneCount = countRecoverablePanes(inventory)
+  const device = inventory.device
+  const anyLive = device?.tabs.some((tab) => tab.panes.some((pane) => pane.live)) ?? false
+
+  return createPortal(
+    <div
+      className={`fixed inset-0 flex items-center justify-center bg-black/50 ${OVERLAY_Z.modal}`}
+      role="presentation"
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={HEADING_ID}
+        data-testid="recovery-offer-panel"
+        className="bg-background border border-border rounded-lg shadow-lg w-full max-w-md mx-4 p-5"
+      >
+        <h2 id={HEADING_ID} className="text-lg font-semibold">
+          Restore {paneCount} {paneCount === 1 ? 'pane' : 'panes'} from server memory?
+        </h2>
+        {device && <p className="mt-1 text-xs text-muted-foreground">{device.deviceLabel}</p>}
+        <ul className="mt-3 text-sm text-muted-foreground list-disc pl-5 space-y-1">
+          {(device?.tabs ?? []).flatMap((tab) =>
+            tab.panes.map((pane) => (
+              <li key={`${tab.tabKey}:${pane.paneId}`}>
+                {tab.tabName}: {pane.mode ?? pane.kind}
+                {pane.cwd ? ` — ${pane.cwd}` : ''}
+              </li>
+            ))
+          )}
+          {inventory.ledgerOnly.map((entry) => (
+            <li key={`${entry.provider}:${entry.sessionId}`}>
+              {entry.mode} session — {entry.cwd ?? 'unknown directory'}
+            </li>
+          ))}
+        </ul>
+        {anyLive && (
+          <p data-testid="recovery-live-note" className="mt-3 text-xs text-muted-foreground">
+            Some sessions are still running on the server — they were left untouched; their panes
+            reopen without resuming.
+          </p>
+        )}
+        <div className="mt-4 flex justify-end gap-2">
+          <Button variant="ghost" size="sm" data-testid="recovery-decline" onClick={decline}>
+            Not now
+          </Button>
+          <Button variant="default" size="sm" data-testid="recovery-accept" onClick={accept}>
+            Restore
+          </Button>
+        </div>
+      </div>
+    </div>,
+    document.body
+  )
+}
diff --git a/test/unit/client/components/RecoveryOfferPanel.persisted-boot.test.tsx b/test/unit/client/components/RecoveryOfferPanel.persisted-boot.test.tsx
new file mode 100644
index 000000000..2c977f866
--- /dev/null
+++ b/test/unit/client/components/RecoveryOfferPanel.persisted-boot.test.tsx
@@ -0,0 +1,96 @@
+// Boot-state variant: this file mocks hadPersistedLayoutAtBoot to TRUE (the boot
+// found a persisted layout, so nothing was lost). Split from the main test file
+// because the boot-state capture is a module constant — one mock per module graph.
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, screen, waitFor, cleanup } from '@testing-library/react'
+import { Provider } from 'react-redux'
+import { configureStore } from '@reduxjs/toolkit'
+
+vi.mock('@/lib/api', async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  getRecoveryInventory: vi.fn(),
+}))
+vi.mock('@/lib/recovery/boot-state', () => ({
+  computeHadPersistedLayout: () => true,
+  hadPersistedLayoutAtBoot: true, // this boot HAD a layout
+  bootCapturedAtMs: 1000,
+}))
+vi.mock('@/store/tabRegistrySync', async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  getCurrentTabRegistryClientInstanceId: () => 'client-me',
+}))
+
+import { getRecoveryInventory } from '@/lib/api'
+import { RecoveryOfferPanel } from '@/components/RecoveryOfferPanel'
+import { setPendingOffer } from '@/lib/recovery/dismissal'
+import type { RecoveryInventory } from '@/lib/recovery/types'
+import tabsReducer from '@/store/tabsSlice'
+import panesReducer from '@/store/panesSlice'
+
+function makeTestStore() {
+  return configureStore({ reducer: { tabs: tabsReducer, panes: panesReducer } })
+}
+
+const INVENTORY: RecoveryInventory = {
+  recoverable: true,
+  contentId: 'cid-1',
+  device: {
+    deviceId: 'd',
+    deviceLabel: 'l',
+    capturedAt: 1,
+    tabs: [
+      {
+        tabKey: 'k',
+        tabName: 'work',
+        panes: [
+          {
+            paneId: 'p1',
+            kind: 'terminal',
+            mode: 'claude',
+            shell: null,
+            cwd: '/w',
+            payload: {},
+            sessionRef: { provider: 'claude', sessionId: 'S2' },
+            ledgerState: 'bound',
+            live: false,
+          },
+        ],
+      },
+    ],
+  },
+  otherDevices: [],
+  ledgerOnly: [],
+}
+
+describe('RecoveryOfferPanel with a persisted layout at boot', () => {
+  beforeEach(() => {
+    localStorage.clear()
+    vi.mocked(getRecoveryInventory).mockReset()
+  })
+
+  afterEach(() => cleanup())
+
+  it('renders nothing and never fetches when there is no pending offer (D1)', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    // Give any (wrongly scheduled) fetch a chance to fire before asserting
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(vi.mocked(getRecoveryInventory)).not.toHaveBeenCalled()
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('re-offers a pending offer, anchoring bootAgoMs to the ORIGINAL boot (D2)', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    const pendingBootAt = 500
+    setPendingOffer('cid-1', pendingBootAt)
+    const t0 = Date.now()
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    expect(await screen.findByRole('dialog')).toBeInTheDocument()
+    expect(vi.mocked(getRecoveryInventory)).toHaveBeenCalledTimes(1)
+    const [clientInstanceId, bootAgoMs] = vi.mocked(getRecoveryInventory).mock.calls[0]
+    expect(clientInstanceId).toBe('client-me')
+    // Anchored to the pending offer's bootAt (500), NOT this module-load's
+    // bootCapturedAtMs (1000): expected ~ t0 - 500, with test-jitter slack.
+    expect(Math.abs(bootAgoMs - (t0 - pendingBootAt))).toBeLessThan(200)
+  })
+})
diff --git a/test/unit/client/components/RecoveryOfferPanel.test.tsx b/test/unit/client/components/RecoveryOfferPanel.test.tsx
new file mode 100644
index 000000000..dea37d8a1
--- /dev/null
+++ b/test/unit/client/components/RecoveryOfferPanel.test.tsx
@@ -0,0 +1,181 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, screen, waitFor, cleanup } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Provider } from 'react-redux'
+import { configureStore } from '@reduxjs/toolkit'
+
+vi.mock('@/lib/api', async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  getRecoveryInventory: vi.fn(),
+}))
+vi.mock('@/lib/recovery/boot-state', () => ({
+  computeHadPersistedLayout: () => false,
+  hadPersistedLayoutAtBoot: false, // simulate empty boot
+  bootCapturedAtMs: 0,
+}))
+vi.mock('@/store/tabRegistrySync', async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  getCurrentTabRegistryClientInstanceId: () => 'client-me',
+}))
+
+import { getRecoveryInventory } from '@/lib/api'
+import { RecoveryOfferPanel } from '@/components/RecoveryOfferPanel'
+import { getPendingOffer } from '@/lib/recovery/dismissal'
+import { consumeTerminalRestoreRequestId } from '@/lib/terminal-restore'
+import type { RecoveryInventory } from '@/lib/recovery/types'
+import type { PaneNode } from '@/store/paneTypes'
+import tabsReducer from '@/store/tabsSlice'
+import panesReducer from '@/store/panesSlice'
+
+function makeTestStore() {
+  return configureStore({ reducer: { tabs: tabsReducer, panes: panesReducer } })
+}
+
+type TestStore = ReturnType<typeof makeTestStore>
+
+const INVENTORY: RecoveryInventory = {
+  recoverable: true,
+  contentId: 'cid-1',
+  device: {
+    deviceId: 'd',
+    deviceLabel: 'l',
+    capturedAt: 1,
+    tabs: [
+      {
+        tabKey: 'k',
+        tabName: 'work',
+        panes: [
+          {
+            paneId: 'p1',
+            kind: 'terminal',
+            mode: 'claude',
+            shell: null,
+            cwd: '/w',
+            payload: {},
+            sessionRef: { provider: 'claude', sessionId: 'S2' },
+            ledgerState: 'bound',
+            live: false,
+          },
+        ],
+      },
+    ],
+  },
+  otherDevices: [],
+  ledgerOnly: [],
+}
+
+function collectTerminalLeaves(node: PaneNode | undefined): Extract<PaneNode, { type: 'leaf' }>[] {
+  if (!node) return []
+  if (node.type === 'leaf') return node.content.kind === 'terminal' ? [node] : []
+  return node.children.flatMap((child) => collectTerminalLeaves(child))
+}
+
+function findRecoveredTerminalLeaves(store: TestStore, title: string) {
+  const tab = store.getState().tabs.tabs.find((t) => t.title === title)
+  expect(tab, `expected a recovered tab titled "${title}"`).toBeTruthy()
+  return collectTerminalLeaves(store.getState().panes.layouts[tab!.id])
+}
+
+describe('RecoveryOfferPanel', () => {
+  beforeEach(() => {
+    localStorage.clear()
+    vi.mocked(getRecoveryInventory).mockReset()
+  })
+
+  afterEach(() => cleanup())
+
+  it('offers when eligible and inventory is recoverable, recording the pending offer', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    expect(await screen.findByRole('dialog')).toBeInTheDocument()
+    expect(screen.getByText(/restore 1 pane/i)).toBeInTheDocument()
+    expect(screen.getByText(/work/)).toBeInTheDocument()
+    // D2: the pending flag anchors re-offers to the original boot
+    expect(getPendingOffer()).toEqual({ contentId: 'cid-1', bootAt: 0 })
+    // no live panes in this inventory -> no live note
+    expect(screen.queryByTestId('recovery-live-note')).not.toBeInTheDocument()
+  })
+
+  it('accept creates the tabs, arms terminal restore, and hides the panel', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    const store = makeTestStore()
+    render(<Provider store={store}><RecoveryOfferPanel /></Provider>)
+    await userEvent.click(await screen.findByTestId('recovery-accept'))
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+
+    const leaves = findRecoveredTerminalLeaves(store, 'work')
+    expect(leaves).toHaveLength(1)
+    const content = leaves[0].content
+    expect(content.kind).toBe('terminal')
+    if (content.kind !== 'terminal') throw new Error('unreachable')
+    // Recreated pane carries the ledger-corrected ref
+    expect(content.sessionRef?.sessionId).toBe('S2')
+    // The post-normalization createRequestId was armed for restore
+    expect(consumeTerminalRestoreRequestId(content.createRequestId)).toBe(true)
+    // Pending flag is cleared on accept
+    expect(getPendingOffer()).toBeNull()
+  })
+
+  it('decline hides, records dismissal, and a remount stays quiet', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    const store = makeTestStore()
+    const first = render(<Provider store={store}><RecoveryOfferPanel /></Provider>)
+    await userEvent.click(await screen.findByTestId('recovery-decline'))
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+    expect(getPendingOffer()).toBeNull()
+    first.unmount()
+
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    await waitFor(() => expect(vi.mocked(getRecoveryInventory)).toHaveBeenCalledTimes(2))
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('renders nothing when inventory is not recoverable', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue({
+      ...INVENTORY,
+      recoverable: false,
+      device: null,
+    })
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    await waitFor(() => expect(vi.mocked(getRecoveryInventory)).toHaveBeenCalled())
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('renders nothing when the inventory fetch fails', async () => {
+    vi.mocked(getRecoveryInventory).mockRejectedValue(new Error('boom'))
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    await waitFor(() => expect(vi.mocked(getRecoveryInventory)).toHaveBeenCalled())
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('shows the live note for live panes and recreates them without sessionRef (D7)', async () => {
+    const liveInventory: RecoveryInventory = {
+      ...INVENTORY,
+      device: {
+        ...INVENTORY.device!,
+        tabs: [
+          {
+            tabKey: 'k',
+            tabName: 'work',
+            panes: [{ ...INVENTORY.device!.tabs[0].panes[0], live: true }],
+          },
+        ],
+      },
+    }
+    vi.mocked(getRecoveryInventory).mockResolvedValue(liveInventory)
+    const store = makeTestStore()
+    render(<Provider store={store}><RecoveryOfferPanel /></Provider>)
+    expect(await screen.findByTestId('recovery-live-note')).toBeVisible()
+
+    await userEvent.click(screen.getByTestId('recovery-accept'))
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+
+    const leaves = findRecoveredTerminalLeaves(store, 'work')
+    expect(leaves).toHaveLength(1)
+    const content = leaves[0].content
+    if (content.kind !== 'terminal') throw new Error('unreachable')
+    // Live sessions are left untouched: no resume ref, no restore arming
+    expect(content.sessionRef).toBeUndefined()
+    expect(consumeTerminalRestoreRequestId(content.createRequestId)).toBe(false)
+  })
+})

From 5cfcb93e79f5b787a49d45f62285e216fd359184 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:52:32 -0700
Subject: [PATCH 43/87] feat(ws): codex locator controller + arm/submit/disarm
 seams + 150ms sweep wiring

---
 crates/freshell-server/src/main.rs            |  14 +
 .../freshell-ws/src/amplifier_association.rs  |   1 +
 crates/freshell-ws/src/codex_association.rs   | 281 ++++++++++++++++++
 crates/freshell-ws/src/lib.rs                 |  13 +
 .../freshell-ws/src/opencode_association.rs   |   1 +
 crates/freshell-ws/src/terminal.rs            |  53 ++++
 .../tests/codex_managed_launch_e2e.rs         |   1 +
 .../tests/codex_session_ref_resume.rs         |   1 +
 crates/freshell-ws/tests/common/mod.rs        |   4 +
 .../tests/diag01_lifecycle_events.rs          |   1 +
 .../tests/freshagent_claude_attach.rs         |   1 +
 .../tests/freshagent_claude_kill_interrupt.rs |   1 +
 crates/freshell-ws/tests/hello_timeout.rs     |   1 +
 crates/freshell-ws/tests/keepalive.rs         |   1 +
 crates/freshell-ws/tests/max_payload.rs       |   1 +
 crates/freshell-ws/tests/origin_policy.rs     |   1 +
 crates/freshell-ws/tests/pane_reconcile.rs    |   1 +
 .../tests/safe08_restore_diagnostics.rs       |   1 +
 .../freshell-ws/tests/term09_output_queue.rs  |   1 +
 19 files changed, 379 insertions(+)
 create mode 100644 crates/freshell-ws/src/codex_association.rs

diff --git a/crates/freshell-server/src/main.rs b/crates/freshell-server/src/main.rs
index 3457cffc7..cedd93d71 100644
--- a/crates/freshell-server/src/main.rs
+++ b/crates/freshell-server/src/main.rs
@@ -340,6 +340,12 @@ async fn main() -> ExitCode {
             freshell_sessions::parse::default_opencode_data_home(),
         ),
     ));
+    // Lane B2 (campaign §2.3.2): server-side codex identity locator. Same
+    // sessions root the resume-time rollout locator below walks. `None`
+    // when HOME/CODEX_HOME are unresolvable — every codex_association
+    // entry point no-ops in that case.
+    let codex_locator = freshell_ws::codex_sessions_root()
+        .map(|root| std::sync::Arc::new(freshell_sessions::codex_locator::CodexLocator::new(root)));
     // Slice 3a (docs/plans/2026-07-18-agent-api-mcp-parity-spec.md): wire the
     // SAME locators + coding-CLI command specs `ws_state` (below) gets into
     // `fresh_agent_state` too, so `POST /api/tabs` terminal-mode creates (a)
@@ -432,6 +438,7 @@ async fn main() -> ExitCode {
         identity: terminal_identity.clone(),
         amplifier_locator: amplifier_locator.clone(),
         opencode_locator: opencode_locator.clone(),
+        codex_locator: codex_locator.clone(),
         // Reconciliation handshake disk-truth probe (design §5.1): backed by
         // the SAME shared session index the History surfaces read; the
         // no-index fallback (honest `Unknown` on known providers) when no
@@ -638,6 +645,13 @@ async fn main() -> ExitCode {
             AMPLIFIER_LOCATOR_SWEEP_INTERVAL,
         );
     }
+    // Lane B2: codex locator sweep — same cadence as the sibling sweeps.
+    if codex_locator.is_some() {
+        freshell_ws::codex_association::spawn_codex_locator_sweep(
+            ws_state.clone(),
+            AMPLIFIER_LOCATOR_SWEEP_INTERVAL,
+        );
+    }
     // DIAG-05: the diag router's `sessionsProjects` reads the SAME session
     // index (clone before the move below into `session_directory_state`).
     let diag_session_index = session_index.clone();
diff --git a/crates/freshell-ws/src/amplifier_association.rs b/crates/freshell-ws/src/amplifier_association.rs
index 35c08f49c..d56c39604 100644
--- a/crates/freshell-ws/src/amplifier_association.rs
+++ b/crates/freshell-ws/src/amplifier_association.rs
@@ -317,6 +317,7 @@ mod tests {
             amplifier_locator: Some(StdArc::new(AmplifierLocator::new(amplifier_home))),
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
             opencode_locator: None,
+            codex_locator: None,
             activity: None,
         };
         (state, rx)
diff --git a/crates/freshell-ws/src/codex_association.rs b/crates/freshell-ws/src/codex_association.rs
new file mode 100644
index 000000000..e74410730
--- /dev/null
+++ b/crates/freshell-ws/src/codex_association.rs
@@ -0,0 +1,281 @@
+//! Codex terminal-pane association controller (Lane B2): arm the
+//! CodexLocator at create, feed Enter submits, and on resolution adopt the
+//! identity through the shared `codex_identity::adopt_codex_identity` tail.
+//! Structure mirrors `opencode_association.rs` — deliberately (spec §5-shape
+//! duplication over a premature provider-generic controller). One deliberate
+//! deviation: the locator's windows are ENTER-ANCHORED ONLY (no spawn
+//! window) — real codex materializes its rollout only at the first user
+//! prompt, so `maybe_arm` only takes the snapshot and `note_possible_submit`
+//! is what opens a correlation window (async: the FIRST submit re-snapshots
+//! `known_files` on the blocking pool and MUST complete before the Enter is
+//! written to the PTY — see the terminal.rs seam).
+
+use freshell_protocol::TerminalRunStatus;
+
+use crate::terminal::now_ms;
+use crate::WsState;
+
+/// Deliberate one-line duplicate of `opencode_association::is_submit_input`
+/// (itself a duplicate of `amplifier_association`'s — spec §5: "a one-liner,
+/// duplication acceptable"): the input is ONLY a run of CR/LF bytes — an
+/// Enter keypress, possibly repeated.
+pub(crate) fn is_submit_input(data: &str) -> bool {
+    !data.is_empty() && data.chars().all(|c| c == '\r' || c == '\n')
+}
+
+/// Arm the locator for a freshly-created terminal, iff it's a fresh
+/// (non-resuming) `codex` pane with a resolved cwd. No-ops when the locator
+/// is unavailable (`WsState::codex_locator` is `None`) or the mode isn't
+/// `codex`. Arming only takes the known-files snapshot — windows are
+/// Enter-anchored and open in `note_possible_submit` (see module doc). The
+/// snapshot walks the sessions tree, so the caller runs this on the
+/// blocking pool (see the terminal.rs arm-at-create seam).
+pub(crate) fn maybe_arm(
+    state: &WsState,
+    terminal_id: &str,
+    mode: &str,
+    cwd: Option<&str>,
+    resume_session_id: Option<&str>,
+) {
+    if mode != "codex" {
+        return;
+    }
+    let Some(locator) = &state.codex_locator else {
+        return;
+    };
+    locator.arm(terminal_id, mode, true, resume_session_id, cwd);
+}
+
+/// Feed a `terminal.input` write to the locator iff it's submit-shaped
+/// (Enter). Async, unlike the opencode sibling: the FIRST `note_submit`
+/// re-snapshots `known_files` (a bounded sessions-tree walk), so it runs on
+/// the blocking pool, and the CALLER MUST AWAIT this BEFORE writing the
+/// Enter to the PTY — codex materializes the rollout in response to that
+/// very Enter, and a re-snapshot racing after the write could capture
+/// (permanently exclude) the pane's own file. Non-submit data returns
+/// immediately; later submits are a cheap mutex hop.
+pub(crate) async fn note_possible_submit(state: &WsState, terminal_id: &str, data: &str) {
+    if !is_submit_input(data) {
+        return;
+    }
+    let Some(locator) = &state.codex_locator else {
+        return;
+    };
+    let locator = std::sync::Arc::clone(locator);
+    let terminal_id = terminal_id.to_string();
+    let at_ms = now_ms();
+    if let Err(join_error) =
+        tokio::task::spawn_blocking(move || locator.note_submit(&terminal_id, at_ms)).await
+    {
+        tracing::warn!(
+            error = %join_error,
+            "codex_note_submit_panicked: blocking submit task panicked"
+        );
+    }
+}
+
+/// Drive one locator polling cycle and adopt every association it resolved
+/// this tick through the shared `codex_identity::adopt_codex_identity` tail.
+/// The tick does bounded filesystem walks + first-line reads — never on an
+/// async worker (same `spawn_blocking` discipline as the opencode sweep).
+pub(crate) async fn drain_and_associate(state: &WsState) {
+    let Some(locator) = &state.codex_locator else {
+        return;
+    };
+    let locator = std::sync::Arc::clone(locator);
+    let now = now_ms();
+    let located = match tokio::task::spawn_blocking(move || locator.tick(now)).await {
+        Ok(located) => located,
+        Err(join_error) => {
+            tracing::warn!(
+                error = %join_error,
+                "codex_locator_tick_panicked: sweep tick task panicked, skipping this cycle"
+            );
+            return;
+        }
+    };
+    for hit in located {
+        // Defense-in-depth rejects against registry truth (mirrors
+        // opencode_association.rs's drain checks): a terminal could
+        // legitimately be killed between `Located` and this draining tick.
+        let Some(entry) = state
+            .registry
+            .directory()
+            .into_iter()
+            .find(|e| e.terminal_id == hit.terminal_id)
+        else {
+            tracing::warn!(
+                terminal_id = %hit.terminal_id,
+                thread_id = %hit.thread_id,
+                "codex_association_rejected: terminal_missing"
+            );
+            continue;
+        };
+        if entry.mode != "codex" || entry.status != TerminalRunStatus::Running {
+            tracing::warn!(
+                terminal_id = %hit.terminal_id,
+                mode = %entry.mode,
+                "codex_association_rejected: terminal_not_codex_or_not_running"
+            );
+            continue;
+        }
+        if entry.resume_session_id.is_some() {
+            tracing::warn!(
+                terminal_id = %hit.terminal_id,
+                "codex_association_rejected: terminal_already_bound"
+            );
+            continue;
+        }
+        // The shared adoption tail (codex_identity.rs): binds both identity
+        // homes, awaits the durable ledger row, broadcasts the pinned
+        // associated/meta pair, and feeds the activity hub (including the
+        // rollout attach for the reconcile lane).
+        crate::codex_identity::adopt_codex_identity(
+            state,
+            crate::codex_identity::CodexAdoption {
+                terminal_id: &hit.terminal_id,
+                thread_id: &hit.thread_id,
+                rollout_path: Some(hit.rollout_path.as_path()),
+                cwd: entry.cwd.as_deref(),
+            },
+        )
+        .await;
+    }
+}
+
+/// The sweep-timer wiring (mirrors `spawn_opencode_locator_sweep`):
+/// periodically drive the locator's polling cycle and process any resolved
+/// associations, off the per-connection select loops.
+pub fn spawn_codex_locator_sweep(state: WsState, interval: std::time::Duration) {
+    tokio::spawn(async move {
+        let mut ticker = tokio::time::interval(interval);
+        loop {
+            ticker.tick().await;
+            drain_and_associate(&state).await;
+        }
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::terminal::now_ms;
+    use crate::WsState;
+    use freshell_sessions::codex_locator::CodexLocator;
+    use std::sync::Arc as StdArc;
+
+    fn state_with_locator(
+        data_home: std::path::PathBuf,
+    ) -> (WsState, tokio::sync::broadcast::Receiver<String>) {
+        let auth_token = StdArc::new("s3cr3t-token-abcdef".to_string());
+        let broadcast_tx = StdArc::new(tokio::sync::broadcast::channel::<String>(16).0);
+        let rx = broadcast_tx.subscribe();
+        let state = WsState {
+            pane_ledger: std::sync::Arc::new(crate::pane_ledger::PaneLedger::disabled()),
+            identity: crate::identity::TerminalIdentityRegistry::new(),
+            auth_token: StdArc::clone(&auth_token),
+            server_instance_id: StdArc::new("srv-1111".to_string()),
+            boot_id: StdArc::new("boot-2222".to_string()),
+            settings: StdArc::new(
+                serde_json::from_value(serde_json::json!({
+                    "ai": {},
+                    "codingCli": { "enabledProviders": [], "mcpServer": true, "providers": {} },
+                    "editor": { "externalEditor": "auto" },
+                    "extensions": { "disabled": [] },
+                    "freshAgent": { "defaultPlugins": [], "enabled": false, "providers": {} },
+                    "logging": { "debug": false },
+                    "network": { "configured": true, "host": "127.0.0.1" },
+                    "panes": { "defaultNewPane": "ask" },
+                    "safety": { "autoKillIdleMinutes": 15 },
+                    "sidebar": {
+                        "autoGenerateTitles": true,
+                        "excludeFirstChatMustStart": false,
+                        "excludeFirstChatSubstrings": []
+                    },
+                    "terminal": { "scrollback": 10000 }
+                }))
+                .unwrap(),
+            ),
+            broadcast_tx: StdArc::clone(&broadcast_tx),
+            fresh_codex: freshell_freshagent::FreshCodexState::new(
+                StdArc::clone(&auth_token),
+                StdArc::clone(&broadcast_tx),
+                serde_json::json!({ "freshAgent": { "enabled": false } }),
+            ),
+            fresh_claude: freshell_freshagent::FreshClaudeState::new(StdArc::clone(&broadcast_tx)),
+            fresh_opencode: freshell_freshagent::FreshOpencodeState::new(
+                freshell_freshagent::FreshAgentState::new(auth_token, StdArc::clone(&broadcast_tx)),
+            ),
+            registry: freshell_terminal::TerminalRegistry::new(),
+            shutdown: StdArc::new(tokio::sync::Notify::new()),
+            tabs: crate::tabs::TabsRegistry::new(),
+            screenshots: crate::screenshot::ScreenshotBroker::new(broadcast_tx),
+            terminals_revision: StdArc::new(std::sync::atomic::AtomicI64::new(0)),
+            sessions_revision: StdArc::new(std::sync::atomic::AtomicI64::new(0)),
+            cli_commands: StdArc::new(Vec::new()),
+            ping_interval_ms: 30_000,
+            hello_timeout_ms: 5_000,
+            allowed_origins: StdArc::new(crate::origin::default_allowed_origins()),
+            ws_max_payload_bytes: 16 * 1024 * 1024,
+            term09: crate::backpressure::Term09Config::default(),
+            create_protect: crate::create_limit::CreateProtectConfig::default(),
+            spawn_gate: std::sync::Arc::new(crate::spawn_gate::SpawnGate::new(4, 64)),
+            config_fallback: None,
+            amplifier_locator: None,
+            opencode_locator: None,
+            codex_locator: Some(StdArc::new(CodexLocator::new(data_home))),
+            activity: None,
+            session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+        };
+        (state, rx)
+    }
+
+    fn unique_temp_dir(label: &str) -> std::path::PathBuf {
+        use std::sync::atomic::{AtomicU64, Ordering};
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let n = COUNTER.fetch_add(1, Ordering::SeqCst);
+        let dir = std::env::temp_dir().join(format!(
+            "freshell-codex-association-test-{label}-{}-{n}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    #[test]
+    fn is_submit_input_matches_enter_only_sequences() {
+        for yes in ["\r", "\n", "\r\n", "\r\r\n\n"] {
+            assert!(is_submit_input(yes), "{yes:?} should be a submit");
+        }
+        for no in ["", "hello", "hello\r\n", "\u{1b}[A"] {
+            assert!(!is_submit_input(no), "{no:?} should not be a submit");
+        }
+    }
+
+    #[test]
+    fn maybe_arm_arms_a_fresh_codex_terminal_and_ignores_others() {
+        let dir = unique_temp_dir("assoc-arm");
+        let (state, _rx) = state_with_locator(dir.clone());
+        let locator = state.codex_locator.as_ref().unwrap().clone();
+        maybe_arm(&state, "t1", "opencode", Some("/tmp"), None); // wrong mode
+        assert_eq!(locator.armed_count(), 0);
+        maybe_arm(&state, "t1", "codex", Some("/tmp"), Some("resume-id")); // resuming
+        assert_eq!(locator.armed_count(), 0);
+        maybe_arm(&state, "t1", "codex", Some("/tmp"), None); // fresh
+        assert_eq!(locator.armed_count(), 1);
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[tokio::test]
+    async fn note_possible_submit_feeds_only_enter_sequences() {
+        let dir = unique_temp_dir("assoc-submit");
+        let (state, _rx) = state_with_locator(dir.clone());
+        let locator = state.codex_locator.as_ref().unwrap().clone();
+        maybe_arm(&state, "t1", "codex", Some("/tmp"), None);
+        note_possible_submit(&state, "t1", "hello").await;
+        // Observable proof via the locator's own seam: "hello" must not have
+        // consumed the window — a direct note_submit still returns true.
+        assert!(locator.note_submit("t1", now_ms()));
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+}
diff --git a/crates/freshell-ws/src/lib.rs b/crates/freshell-ws/src/lib.rs
index 42eb2e654..b0cf5576c 100644
--- a/crates/freshell-ws/src/lib.rs
+++ b/crates/freshell-ws/src/lib.rs
@@ -23,6 +23,7 @@
 pub mod activity;
 pub mod amplifier_association;
 pub mod backpressure;
+pub mod codex_association;
 pub(crate) mod codex_candidate;
 pub(crate) mod codex_identity;
 pub(crate) mod codex_reconcile;
@@ -241,6 +242,17 @@ pub struct WsState {
     /// point no-ops in that case. Sibling to `amplifier_locator` (spec §8: a
     /// provider-parameterized locator was explicitly rejected).
     pub opencode_locator: Option<Arc<freshell_sessions::opencode_locator::OpencodeLocator>>,
+    /// The codex terminal-pane rollout locator (Lane B2): correlates a fresh
+    /// codex PTY's first Enter with the new rollout JSONL codex writes under
+    /// the sessions root — real codex materializes the file only at the first
+    /// user prompt, so the locator's windows are Enter-anchored (no spawn
+    /// window) — so the terminal can be bound to a session identity and
+    /// `terminal.rs`'s generic resume derivation can drive `codex resume <id>`
+    /// on restart. `None` when HOME/CODEX_HOME are unresolvable — every
+    /// [`crate::codex_association`] entry point no-ops in that case. Sibling
+    /// to `opencode_locator` (a provider-parameterized locator was explicitly
+    /// rejected there; same call here).
+    pub codex_locator: Option<Arc<freshell_sessions::codex_locator::CodexLocator>>,
     /// TERM-15/TERM-16: the terminal-mode CLI activity hub (claude/codex/
     /// amplifier trackers + the truly-idle gate + the amplifier events
     /// lanes). `None` in unit tests that never exercise activity; always
@@ -740,6 +752,7 @@ mod tests {
             config_fallback: None,
             amplifier_locator: None,
             opencode_locator: None,
+            codex_locator: None,
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
         }
diff --git a/crates/freshell-ws/src/opencode_association.rs b/crates/freshell-ws/src/opencode_association.rs
index df20d50a6..38d4fad37 100644
--- a/crates/freshell-ws/src/opencode_association.rs
+++ b/crates/freshell-ws/src/opencode_association.rs
@@ -289,6 +289,7 @@ mod tests {
             config_fallback: None,
             amplifier_locator: None,
             opencode_locator: Some(StdArc::new(OpencodeLocator::new(data_home))),
+            codex_locator: None,
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
         };
diff --git a/crates/freshell-ws/src/terminal.rs b/crates/freshell-ws/src/terminal.rs
index eec05ee2b..b6bbcd6d8 100644
--- a/crates/freshell-ws/src/terminal.rs
+++ b/crates/freshell-ws/src/terminal.rs
@@ -524,6 +524,16 @@ async fn handle_client_text(
             }
         }
         ClientMessage::TerminalInput(input) => {
+            // Lane B2: MUST complete before the Enter reaches the PTY — the
+            // codex locator's FIRST-submit re-snapshot has to finish before
+            // codex can materialize the rollout this very Enter triggers
+            // (else the pane's own file could land in the snapshot and be
+            // permanently excluded). Sound here: this socket task processes
+            // frames sequentially, and the enclosing handler is already
+            // async. Non-submit data returns immediately; only the first
+            // Enter of an armed codex pane scans (7-9 ms warm — A6).
+            crate::codex_association::note_possible_submit(state, &input.terminal_id, &input.data)
+                .await;
             state
                 .registry
                 .input(&input.terminal_id, input.data.as_bytes());
@@ -1352,6 +1362,10 @@ async fn handle_create(
         // (never-submitted, or already-associated) opencode terminal's armed
         // entry is never left dangling.
         let opencode_locator = state.opencode_locator.clone();
+        // Lane B2: sibling disarm for the codex rollout locator, so an
+        // exited (never-submitted, or already-associated) codex terminal's
+        // armed entry is never left dangling.
+        let codex_locator = state.codex_locator.clone();
         Some(Box::new(move |exit_code: i64| {
             cleanup_mcp_config(&RealMcpRuntime, &tid, &cleanup_mode, cleanup_cwd.as_deref());
             registry.finish_pty_exit(&tid, exit_code);
@@ -1377,6 +1391,9 @@ async fn handle_create(
             if let Some(locator) = &opencode_locator {
                 locator.disarm(&tid);
             }
+            if let Some(locator) = &codex_locator {
+                locator.disarm(&tid);
+            }
         }))
     };
 
@@ -1526,6 +1543,40 @@ async fn handle_create(
         resume_session_id.as_deref(),
     );
 
+    // Lane B2: arm the codex rollout locator for a FRESH (non-resuming)
+    // codex pane. Restore-created panes WITHOUT identity arm too — arm()
+    // gates on resume_session_id, never a restore flag (the wave-A re-arm
+    // contract).
+    //
+    // ORDERING NOTE (A5, validated): this arm runs AFTER the PTY spawn
+    // (registry.create + adopt() have already awaited above). That is safe
+    // ONLY because windows are Enter-anchored: real codex materializes its
+    // rollout at the first user prompt, never in the spawn→arm gap, so the
+    // snapshot cannot miss the pane's own file. Do not reinterpret this as
+    // "snapshot precedes spawn" — it does not need to.
+    //
+    // The arm() snapshot walks the sessions tree; run it on the blocking
+    // pool, not the WS dispatch path (A6: warm walks are 7-9 ms today and
+    // ~100 ms at 100k files, but cold dentry cache after a reboot is the
+    // one unmeasured tail).
+    {
+        let state = state.clone();
+        let terminal_id = terminal_id.clone();
+        let mode = mode.clone();
+        let cwd = resolved_cwd.clone();
+        let resume = resume_session_id.clone();
+        let _ = tokio::task::spawn_blocking(move || {
+            crate::codex_association::maybe_arm(
+                &state,
+                &terminal_id,
+                &mode,
+                cwd.as_deref(),
+                resume.as_deref(),
+            );
+        })
+        .await;
+    }
+
     // Snapshot the id before it's moved into `created` below -- needed for the
     // `terminal.meta.updated` create-time slice after the create frame is sent.
     let terminal_id_for_meta = terminal_id.clone();
@@ -3193,6 +3244,7 @@ mod terminals_changed_tests {
             config_fallback: None,
             amplifier_locator: None,
             opencode_locator: None,
+            codex_locator: None,
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
         };
@@ -3400,6 +3452,7 @@ mod terminal_meta_created_tests {
             config_fallback: None,
             amplifier_locator: None,
             opencode_locator: None,
+            codex_locator: None,
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
         };
diff --git a/crates/freshell-ws/tests/codex_managed_launch_e2e.rs b/crates/freshell-ws/tests/codex_managed_launch_e2e.rs
index 3c87985f9..50b711900 100644
--- a/crates/freshell-ws/tests/codex_managed_launch_e2e.rs
+++ b/crates/freshell-ws/tests/codex_managed_launch_e2e.rs
@@ -153,6 +153,7 @@ async fn spawn_server() -> (String, freshell_terminal::TerminalRegistry) {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/codex_session_ref_resume.rs b/crates/freshell-ws/tests/codex_session_ref_resume.rs
index 57bc9d155..310764708 100644
--- a/crates/freshell-ws/tests/codex_session_ref_resume.rs
+++ b/crates/freshell-ws/tests/codex_session_ref_resume.rs
@@ -146,6 +146,7 @@ async fn spawn_server() -> (String, freshell_terminal::TerminalRegistry) {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/common/mod.rs b/crates/freshell-ws/tests/common/mod.rs
index 778e734e1..774967980 100644
--- a/crates/freshell-ws/tests/common/mod.rs
+++ b/crates/freshell-ws/tests/common/mod.rs
@@ -134,6 +134,7 @@ pub async fn spawn_server_with_specs(
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
@@ -214,6 +215,7 @@ pub async fn spawn_server_with_ledger(
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
@@ -290,6 +292,7 @@ pub async fn spawn_server_with_specs_and_activity(
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: Some(activity_hub.clone()),
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
@@ -355,6 +358,7 @@ pub async fn spawn_server_with_create_protect(
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/diag01_lifecycle_events.rs b/crates/freshell-ws/tests/diag01_lifecycle_events.rs
index 912db6baf..85a45e3f2 100644
--- a/crates/freshell-ws/tests/diag01_lifecycle_events.rs
+++ b/crates/freshell-ws/tests/diag01_lifecycle_events.rs
@@ -170,6 +170,7 @@ async fn spawn_server(ping_interval_ms: u64) -> String {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/freshagent_claude_attach.rs b/crates/freshell-ws/tests/freshagent_claude_attach.rs
index 6014b3f3b..49929bd02 100644
--- a/crates/freshell-ws/tests/freshagent_claude_attach.rs
+++ b/crates/freshell-ws/tests/freshagent_claude_attach.rs
@@ -174,6 +174,7 @@ async fn spawn_server() -> String {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs b/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs
index df44c89ef..337f23883 100644
--- a/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs
+++ b/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs
@@ -205,6 +205,7 @@ async fn spawn_server() -> String {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/hello_timeout.rs b/crates/freshell-ws/tests/hello_timeout.rs
index c3d08eec0..f7c82a936 100644
--- a/crates/freshell-ws/tests/hello_timeout.rs
+++ b/crates/freshell-ws/tests/hello_timeout.rs
@@ -90,6 +90,7 @@ async fn spawn_server(hello_timeout_ms: u64) -> String {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/keepalive.rs b/crates/freshell-ws/tests/keepalive.rs
index 37132e772..5ace58ff9 100644
--- a/crates/freshell-ws/tests/keepalive.rs
+++ b/crates/freshell-ws/tests/keepalive.rs
@@ -91,6 +91,7 @@ async fn spawn_server(
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/max_payload.rs b/crates/freshell-ws/tests/max_payload.rs
index aa9a0b06c..45a388c43 100644
--- a/crates/freshell-ws/tests/max_payload.rs
+++ b/crates/freshell-ws/tests/max_payload.rs
@@ -91,6 +91,7 @@ async fn spawn_server(ws_max_payload_bytes: usize) -> String {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/origin_policy.rs b/crates/freshell-ws/tests/origin_policy.rs
index b8f197f4f..84a7391e3 100644
--- a/crates/freshell-ws/tests/origin_policy.rs
+++ b/crates/freshell-ws/tests/origin_policy.rs
@@ -81,6 +81,7 @@ async fn spawn_server(allowed_origins: Vec<String>) -> (String, String) {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/pane_reconcile.rs b/crates/freshell-ws/tests/pane_reconcile.rs
index c1db5b723..2e8c77a8f 100644
--- a/crates/freshell-ws/tests/pane_reconcile.rs
+++ b/crates/freshell-ws/tests/pane_reconcile.rs
@@ -105,6 +105,7 @@ async fn spawn_server() -> Server {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/safe08_restore_diagnostics.rs b/crates/freshell-ws/tests/safe08_restore_diagnostics.rs
index c0a949981..d3ef9170c 100644
--- a/crates/freshell-ws/tests/safe08_restore_diagnostics.rs
+++ b/crates/freshell-ws/tests/safe08_restore_diagnostics.rs
@@ -177,6 +177,7 @@ async fn spawn_server() -> String {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };
diff --git a/crates/freshell-ws/tests/term09_output_queue.rs b/crates/freshell-ws/tests/term09_output_queue.rs
index 9edcedb52..667478d9f 100644
--- a/crates/freshell-ws/tests/term09_output_queue.rs
+++ b/crates/freshell-ws/tests/term09_output_queue.rs
@@ -84,6 +84,7 @@ async fn spawn_server(term09: Term09Config) -> String {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
     };

From 07ecbb35abcdab00ef89e69adbcddf738a672ac7 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:56:45 -0700
Subject: [PATCH 44/87] feat(store): reconcile verdict fold reducers -
 attach/reset without createRequestId re-mint, batched dead-session state
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the panesSlice reducers Task 9's verdict folding will dispatch:
- applyReconcileAttach: folds attach/duplicate verdicts into pane content
  (terminalId, status running, corrected/duplicate notices)
- resetPaneForReconcileCreate: clears live handles for respawn/fresh
  creates while PRESERVING createRequestId (D4 - the load-bearing
  difference from clearTerminalContentForRecreate); respawn guards
  sessionRef.provider === pane mode and degrades loudly to fresh
- setPaneReconcileNotice/clearPaneReconcileNotice
- setDeadSessionAdjudication/resolveDeadSessionEntry/
  clearDeadSessionAdjudication (batched list, council rule 12)
- setReconcileWarming/clearReconcileWarming

Both fold reducers bump the volatile reconcileEpoch (A1 fix) so
same-createRequestId folds are observable to TerminalView (Task 12).
createRequestId is never re-minted by any reconcile path (council rule 2).

A19 persistence: pendingReconcile/reconcileNotice/reconcileEpoch are
stripped per-pane in stripTransientSessionFields; deadSessionAdjudication
and reconcileWarming are stripped slice-level in flush; updatePaneContent
clears pendingReconcile when terminal.created folds a new terminalId in.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 src/store/paneTypes.ts                        |  33 +++
 src/store/panesSlice.ts                       | 199 ++++++++++++++
 src/store/persistMiddleware.ts                |   6 +
 .../client/store/panesSlice.reconcile.test.ts | 252 ++++++++++++++++++
 4 files changed, 490 insertions(+)
 create mode 100644 test/unit/client/store/panesSlice.reconcile.test.ts

diff --git a/src/store/paneTypes.ts b/src/store/paneTypes.ts
index 1acc90a72..ac9e6d04b 100644
--- a/src/store/paneTypes.ts
+++ b/src/store/paneTypes.ts
@@ -272,6 +272,29 @@ export type RestoreFallbackAttempt = {
   reason: 'dead_live_handle_without_session_ref'
 }
 
+/**
+ * One pane awaiting user adjudication after the server reported its
+ * session dead in a pane.reconcile verdict. Council rule 12: dead_session
+ * is a UI state, not a deletion — the pane stays until the user decides.
+ */
+export type DeadSessionEntry = {
+  tabId: string
+  paneId: string
+  title: string
+  mode: string
+  sessionRef?: { provider: string; sessionId: string }
+  reason?: string
+}
+
+/**
+ * Slice-level banner state while reconcile-driven creates are warming.
+ * Ephemeral — must never be persisted.
+ */
+export type ReconcileWarmingState = {
+  count: number
+  paneRefs: { tabId: string; paneId: string }[]
+}
+
 /**
  * Recursive tree structure for pane layouts.
  * A leaf is a single pane with content.
@@ -318,6 +341,16 @@ export interface PanesState {
    * Must never be persisted.
    */
   restoreFallbackAttemptsByPane: Record<string, Record<string, RestoreFallbackAttempt>>
+  /**
+   * Batched dead-session adjudication list from pane.reconcile verdicts.
+   * Ephemeral UI state — must never be persisted.
+   */
+  deadSessionAdjudication?: DeadSessionEntry[]
+  /**
+   * Reconcile warming banner state while reconcile-driven creates run.
+   * Ephemeral UI state — must never be persisted.
+   */
+  reconcileWarming?: ReconcileWarmingState | null
 }
 
 /**
diff --git a/src/store/panesSlice.ts b/src/store/panesSlice.ts
index 031dfd77e..22d60e6bc 100644
--- a/src/store/panesSlice.ts
+++ b/src/store/panesSlice.ts
@@ -4,6 +4,7 @@ import {
   normalizeFreshAgentEffortOverride,
   normalizeFreshAgentModelSelection,
   normalizeFreshAgentPendingLocalEcho,
+  type DeadSessionEntry,
   type FreshAgentPaneContent,
   type LivePaneContentInput,
   type PanesState,
@@ -11,6 +12,7 @@ import {
   type PaneContentInput,
   type PaneNode,
   type PaneRefreshRequest,
+  type ReconcileWarmingState,
   type SessionLocator,
   type TerminalPaneContent,
 } from './paneTypes'
@@ -296,6 +298,8 @@ function loadInitialPanesState(): PanesState {
     zoomedPane: {},
     refreshRequestsByPane: {},
     restoreFallbackAttemptsByPane: {},
+    deadSessionAdjudication: [],
+    reconcileWarming: null,
   }
 
   try {
@@ -313,6 +317,8 @@ function loadInitialPanesState(): PanesState {
       zoomedPane: {},
       refreshRequestsByPane: {},
       restoreFallbackAttemptsByPane: {},
+      deadSessionAdjudication: [],
+      reconcileWarming: null,
     }
     state = cleanOrphanedLayouts(state)
     return state
@@ -572,6 +578,30 @@ function clearTerminalContentForRecreate(
   }
 }
 
+// Reconcile notice copy — exact strings reused by later tasks/tests.
+export const RECONCILE_NOTICE_CORRECTED = 'Session identity corrected by server — this pane now points at its live session.'
+export const RECONCILE_NOTICE_DUPLICATE = 'A duplicate terminal for this session was detected and ignored.'
+export function reconcileFreshNotice(reason: string): string {
+  return `Started fresh (${reason}).`
+}
+
+/**
+ * Locate a terminal pane's content by (tabId, paneId) for reconcile folds.
+ * Same pane walk as clearTerminalContentForRecreate's callers (via findLeaf),
+ * but the folds below never mint a createRequestId — council rule 2.
+ */
+function findReconcileTerminalContent(
+  state: PanesState,
+  tabId: string,
+  paneId: string,
+): TerminalPaneContent | undefined {
+  const root = state.layouts[tabId]
+  if (!root) return undefined
+  const leaf = findLeaf(root, paneId)
+  if (!leaf || leaf.content.kind !== 'terminal') return undefined
+  return leaf.content
+}
+
 function freshAgentPaneMatchesMaterializedSession(
   content: FreshAgentPaneContent,
   materialized: FreshAgentSessionMaterializedPayload,
@@ -1345,6 +1375,17 @@ export const panesSlice = createSlice({
           if (node.id === paneId) {
             previousContentForTitle = node.content
             const nextContent = normalizePaneContent(content, node.content)
+            // A19: when terminal.created folds a terminalId into this pane,
+            // the reconcile intent is consumed — stale respawn/fresh intent
+            // must never survive past a completed create.
+            if (
+              nextContent.kind === 'terminal'
+              && nextContent.pendingReconcile
+              && nextContent.terminalId
+              && (node.content.kind !== 'terminal' || node.content.terminalId !== nextContent.terminalId)
+            ) {
+              nextContent.pendingReconcile = undefined
+            }
             normalizedContentForTitle = nextContent
             return { ...node, content: nextContent }
           }
@@ -1626,6 +1667,8 @@ export const panesSlice = createSlice({
       state.zoomedPane = {}
       state.refreshRequestsByPane = {}
       state.restoreFallbackAttemptsByPane = {}
+      state.deadSessionAdjudication = []
+      state.reconcileWarming = null
     },
 
     updatePaneTitle: (
@@ -1799,6 +1842,153 @@ export const panesSlice = createSlice({
       }
     },
 
+    /**
+     * Fold a pane.reconcile attach/duplicate verdict into pane content.
+     * Council rule 2: never mints a createRequestId — the existing one is preserved.
+     */
+    applyReconcileAttach: (
+      state,
+      action: PayloadAction<{
+        tabId: string
+        paneId: string
+        terminalId: string
+        serverInstanceId?: string
+        sessionRef?: SessionLocator
+        corrected?: boolean
+        duplicate?: boolean
+      }>
+    ) => {
+      const { tabId, paneId, terminalId, serverInstanceId, corrected, duplicate } = action.payload
+      if (!terminalId) return
+      const content = findReconcileTerminalContent(state, tabId, paneId)
+      if (!content) return
+
+      content.terminalId = terminalId
+      content.serverInstanceId = serverInstanceId
+      content.streamId = undefined
+      content.status = 'running'
+      content.restoreError = undefined
+      const sessionRef = sanitizeSessionRef(action.payload.sessionRef)
+      if (sessionRef) {
+        content.sessionRef = sessionRef
+        content.resumeSessionId = undefined
+      }
+      content.pendingReconcile = undefined
+      // A1 fix: same-createRequestId folds are only observable via the epoch bump.
+      content.reconcileEpoch = (content.reconcileEpoch ?? 0) + 1
+      if (corrected) {
+        content.reconcileNotice = RECONCILE_NOTICE_CORRECTED
+      } else if (duplicate) {
+        content.reconcileNotice = RECONCILE_NOTICE_DUPLICATE
+      }
+      clearRestoreFallbackAttemptForPane(state, tabId, paneId)
+    },
+
+    /**
+     * Fold a pane.reconcile respawn/fresh verdict: clear live handles so
+     * TerminalView re-creates, PRESERVING createRequestId (D4 — the
+     * load-bearing difference from clearTerminalContentForRecreate).
+     */
+    resetPaneForReconcileCreate: (
+      state,
+      action: PayloadAction<{
+        tabId: string
+        paneId: string
+        intent: 'respawn' | 'fresh'
+        sessionRef?: SessionLocator
+        reason?: string
+        corrected?: boolean
+      }>
+    ) => {
+      const { tabId, paneId, corrected } = action.payload
+      const content = findReconcileTerminalContent(state, tabId, paneId)
+      if (!content) return
+      let intent = action.payload.intent
+      let reason = action.payload.reason
+      const sessionRef = sanitizeSessionRef(action.payload.sessionRef)
+
+      content.terminalId = undefined
+      content.serverInstanceId = undefined
+      content.streamId = undefined
+      content.status = 'creating'
+      content.restoreError = undefined
+
+      if (intent === 'respawn') {
+        if (sessionRef && sessionRef.provider === content.mode) {
+          content.sessionRef = sessionRef
+          content.resumeSessionId = undefined
+        } else {
+          // Invariant: respawn requires sessionRef.provider === pane mode.
+          // The server create path filters on it; a mismatch spawns
+          // identity-less. Degrade loudly to fresh-with-notice.
+          log.error('resetPaneForReconcileCreate: respawn sessionRef/provider mismatch — degrading to fresh', {
+            tabId,
+            paneId,
+            paneMode: content.mode,
+            sessionRefProvider: sessionRef?.provider,
+          })
+          intent = 'fresh'
+          reason = reason ?? (sessionRef ? 'respawn_provider_mismatch' : 'respawn_session_ref_missing')
+        }
+      }
+      if (intent === 'fresh') {
+        content.sessionRef = undefined
+        content.resumeSessionId = undefined
+        content.codexDurability = undefined
+      }
+      content.pendingReconcile = intent
+      // A1 fix: same-createRequestId folds are only observable via the epoch bump.
+      content.reconcileEpoch = (content.reconcileEpoch ?? 0) + 1
+      if (corrected) {
+        content.reconcileNotice = RECONCILE_NOTICE_CORRECTED
+      } else if (intent === 'fresh' && reason) {
+        content.reconcileNotice = reconcileFreshNotice(reason)
+      }
+      clearRestoreFallbackAttemptForPane(state, tabId, paneId)
+    },
+
+    setPaneReconcileNotice: (
+      state,
+      action: PayloadAction<{ tabId: string; paneId: string; notice: string }>
+    ) => {
+      const content = findReconcileTerminalContent(state, action.payload.tabId, action.payload.paneId)
+      if (!content) return
+      content.reconcileNotice = action.payload.notice
+    },
+
+    clearPaneReconcileNotice: (
+      state,
+      action: PayloadAction<{ tabId: string; paneId: string }>
+    ) => {
+      const content = findReconcileTerminalContent(state, action.payload.tabId, action.payload.paneId)
+      if (!content) return
+      content.reconcileNotice = undefined
+    },
+
+    /** Council rule 12: dead_session is a UI state, not a deletion — panes wait for the user. */
+    setDeadSessionAdjudication: (state, action: PayloadAction<DeadSessionEntry[]>) => {
+      state.deadSessionAdjudication = action.payload
+    },
+
+    resolveDeadSessionEntry: (state, action: PayloadAction<{ tabId: string; paneId: string }>) => {
+      const { tabId, paneId } = action.payload
+      state.deadSessionAdjudication = (state.deadSessionAdjudication ?? []).filter(
+        (entry) => !(entry.tabId === tabId && entry.paneId === paneId),
+      )
+    },
+
+    clearDeadSessionAdjudication: (state) => {
+      state.deadSessionAdjudication = []
+    },
+
+    setReconcileWarming: (state, action: PayloadAction<ReconcileWarmingState>) => {
+      state.reconcileWarming = action.payload
+    },
+
+    clearReconcileWarming: (state) => {
+      state.reconcileWarming = null
+    },
+
     repairCodexIdentityMismatch: (
       state,
       action: PayloadAction<{
@@ -1874,6 +2064,15 @@ export const {
   toggleZoom,
   clearDeadTerminals,
   clearTerminalLiveHandles,
+  applyReconcileAttach,
+  resetPaneForReconcileCreate,
+  setPaneReconcileNotice,
+  clearPaneReconcileNotice,
+  setDeadSessionAdjudication,
+  resolveDeadSessionEntry,
+  clearDeadSessionAdjudication,
+  setReconcileWarming,
+  clearReconcileWarming,
   repairCodexIdentityMismatch,
 } = panesSlice.actions
 
diff --git a/src/store/persistMiddleware.ts b/src/store/persistMiddleware.ts
index 6739f5242..5b9e6f314 100644
--- a/src/store/persistMiddleware.ts
+++ b/src/store/persistMiddleware.ts
@@ -251,6 +251,10 @@ function stripTransientSessionFields(content: any): any {
     resumeSessionId: _resumeSessionId,
     sessionRef: _legacySessionRef,
     sessionId: _sessionId,
+    // A19: reconcile fold state is volatile — never persisted.
+    pendingReconcile: _pendingReconcile,
+    reconcileNotice: _reconcileNotice,
+    reconcileEpoch: _reconcileEpoch,
     ...rest
   } = content
 
@@ -593,6 +597,8 @@ export const persistMiddleware: Middleware<{}, PersistState> = (store) => {
             zoomedPane: _zp,
             refreshRequestsByPane: _rrbp,
             restoreFallbackAttemptsByPane: _rfabp,
+            deadSessionAdjudication: _dsa,
+            reconcileWarming: _rw,
             ...persistablePanes
           } = state.panes
           persistablePanesSection = {
diff --git a/test/unit/client/store/panesSlice.reconcile.test.ts b/test/unit/client/store/panesSlice.reconcile.test.ts
new file mode 100644
index 000000000..27c663054
--- /dev/null
+++ b/test/unit/client/store/panesSlice.reconcile.test.ts
@@ -0,0 +1,252 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { configureStore } from '@reduxjs/toolkit'
+
+// Mock localStorage BEFORE importing slices (persistMiddleware reads it at import time)
+const localStorageMock = (() => {
+  let store: Record<string, string> = {}
+  return {
+    getItem: (key: string) => store[key] || null,
+    setItem: (key: string, value: string) => { store[key] = value },
+    removeItem: (key: string) => { delete store[key] },
+    clear: () => { store = {} },
+  }
+})()
+Object.defineProperty(globalThis, 'localStorage', { value: localStorageMock, writable: true })
+
+import tabsReducer, { addTab } from '../../../../src/store/tabsSlice'
+import panesReducer, {
+  initLayout,
+  updatePaneContent,
+  applyReconcileAttach,
+  resetPaneForReconcileCreate,
+  setPaneReconcileNotice,
+  clearPaneReconcileNotice,
+  setDeadSessionAdjudication,
+  resolveDeadSessionEntry,
+  clearDeadSessionAdjudication,
+  setReconcileWarming,
+  clearReconcileWarming,
+} from '../../../../src/store/panesSlice'
+import type { PanesState } from '../../../../src/store/panesSlice'
+import {
+  persistMiddleware,
+  resetPersistFlushListenersForTests,
+  resetPersistedPanesCacheForTests,
+  resetPersistedLayoutCacheForTests,
+} from '../../../../src/store/persistMiddleware'
+import type { PaneNode, TerminalPaneContent } from '../../../../src/store/paneTypes'
+
+function emptyState(): PanesState {
+  return {
+    layouts: {},
+    activePane: {},
+    paneTitles: {},
+    paneTitleSetByUser: {},
+    renameRequestTabId: null,
+    renameRequestPaneId: null,
+    zoomedPane: {},
+    refreshRequestsByPane: {},
+    restoreFallbackAttemptsByPane: {},
+  }
+}
+
+function stateWithTerminalPane(overrides: Partial<TerminalPaneContent> = {}): PanesState {
+  return panesReducer(emptyState(), initLayout({
+    tabId: 'tab1',
+    paneId: 'p1',
+    content: {
+      kind: 'terminal',
+      mode: 'claude',
+      shell: 'system',
+      createRequestId: 'cr-keep',
+      ...overrides,
+    },
+  }))
+}
+
+function findTerminalLeaf(node: PaneNode, paneId: string): TerminalPaneContent | undefined {
+  if (node.type === 'leaf') {
+    if (node.id === paneId && node.content.kind === 'terminal') return node.content
+    return undefined
+  }
+  return findTerminalLeaf(node.children[0], paneId) ?? findTerminalLeaf(node.children[1], paneId)
+}
+
+function terminalContent(state: PanesState, tabId: string, paneId: string): TerminalPaneContent {
+  const root = state.layouts[tabId]
+  if (!root) throw new Error(`no layout for tab ${tabId}`)
+  const content = findTerminalLeaf(root, paneId)
+  if (!content) throw new Error(`no terminal pane ${paneId} in tab ${tabId}`)
+  return content
+}
+
+describe('reconcile reducers', () => {
+  it('applyReconcileAttach sets terminalId/status without touching createRequestId', () => {
+    const state = stateWithTerminalPane({ createRequestId: 'cr-keep', terminalId: undefined, status: 'creating' })
+    const next = panesReducer(state, applyReconcileAttach({ tabId: 'tab1', paneId: 'p1', terminalId: 'term-9', serverInstanceId: 'srv-2', sessionRef: { provider: 'claude', sessionId: 's1' } }))
+    const c = terminalContent(next, 'tab1', 'p1')
+    expect(c.terminalId).toBe('term-9')
+    expect(c.status).toBe('running')
+    expect(c.createRequestId).toBe('cr-keep')   // council rule: never re-minted
+    expect(c.restoreError).toBeUndefined()
+    expect(c.reconcileEpoch).toBe(1)            // A1 fix: fold bumps the volatile epoch
+  })
+
+  it('every fold bumps reconcileEpoch monotonically (createRequestId untouched)', () => {
+    let s = stateWithTerminalPane({ createRequestId: 'cr-keep' })
+    s = panesReducer(s, applyReconcileAttach({ tabId: 'tab1', paneId: 'p1', terminalId: 't1' }))
+    s = panesReducer(s, resetPaneForReconcileCreate({ tabId: 'tab1', paneId: 'p1', intent: 'fresh' }))
+    const c = terminalContent(s, 'tab1', 'p1')
+    expect(c.reconcileEpoch).toBe(2)
+    expect(c.createRequestId).toBe('cr-keep')
+  })
+
+  it('applyReconcileAttach with corrected sets a visible notice', () => {
+    const next = panesReducer(stateWithTerminalPane({}), applyReconcileAttach({ tabId: 'tab1', paneId: 'p1', terminalId: 't', corrected: true }))
+    expect(terminalContent(next, 'tab1', 'p1').reconcileNotice).toMatch(/corrected/i)
+    expect(terminalContent(next, 'tab1', 'p1').reconcileNotice)
+      .toBe('Session identity corrected by server — this pane now points at its live session.')
+  })
+
+  it('applyReconcileAttach with duplicate sets the duplicate notice verbatim', () => {
+    const next = panesReducer(stateWithTerminalPane({}), applyReconcileAttach({ tabId: 'tab1', paneId: 'p1', terminalId: 't', duplicate: true }))
+    expect(terminalContent(next, 'tab1', 'p1').reconcileNotice)
+      .toBe('A duplicate terminal for this session was detected and ignored.')
+  })
+
+  it('resetPaneForReconcileCreate(respawn) clears handles, keeps createRequestId, sets server-named sessionRef', () => {
+    const state = stateWithTerminalPane({ createRequestId: 'cr-keep', terminalId: 'dead', streamId: 'st', sessionRef: { provider: 'claude', sessionId: 'client-guess' } })
+    const next = panesReducer(state, resetPaneForReconcileCreate({ tabId: 'tab1', paneId: 'p1', intent: 'respawn', sessionRef: { provider: 'claude', sessionId: 'server-truth' } }))
+    const c = terminalContent(next, 'tab1', 'p1')
+    expect(c.terminalId).toBeUndefined(); expect(c.streamId).toBeUndefined()
+    expect(c.status).toBe('creating')
+    expect(c.createRequestId).toBe('cr-keep')
+    expect(c.sessionRef).toEqual({ provider: 'claude', sessionId: 'server-truth' })
+    expect(c.pendingReconcile).toBe('respawn')
+  })
+
+  it('resetPaneForReconcileCreate(fresh) clears session identity and notes the reason', () => {
+    const state = stateWithTerminalPane({ createRequestId: 'cr-keep', sessionRef: { provider: 'claude', sessionId: 'gone' }, resumeSessionId: 'gone' })
+    const next = panesReducer(state, resetPaneForReconcileCreate({ tabId: 'tab1', paneId: 'p1', intent: 'fresh', reason: 'identity_never_observed' }))
+    const c = terminalContent(next, 'tab1', 'p1')
+    expect(c.sessionRef).toBeUndefined(); expect(c.resumeSessionId).toBeUndefined()
+    expect(c.pendingReconcile).toBe('fresh')
+    expect(c.reconcileNotice).toMatch(/identity_never_observed/)
+    expect(c.reconcileNotice).toBe('Started fresh (identity_never_observed).')
+  })
+
+  it('resetPaneForReconcileCreate(respawn) with provider mismatch degrades loudly to fresh', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    try {
+      const state = stateWithTerminalPane({ mode: 'shell', sessionRef: { provider: 'claude', sessionId: 'x' } })
+      const next = panesReducer(state, resetPaneForReconcileCreate({ tabId: 'tab1', paneId: 'p1', intent: 'respawn', sessionRef: { provider: 'claude', sessionId: 'srv' } }))
+      const c = terminalContent(next, 'tab1', 'p1')
+      expect(c.pendingReconcile).toBe('fresh')
+      expect(c.sessionRef).toBeUndefined()
+      expect(c.reconcileNotice).toMatch(/^Started fresh \(/)
+      expect(c.createRequestId).toBe('cr-keep')
+      expect(errorSpy).toHaveBeenCalled()
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('setPaneReconcileNotice / clearPaneReconcileNotice manage the notice', () => {
+    let s = stateWithTerminalPane({})
+    s = panesReducer(s, setPaneReconcileNotice({ tabId: 'tab1', paneId: 'p1', notice: 'hello' }))
+    expect(terminalContent(s, 'tab1', 'p1').reconcileNotice).toBe('hello')
+    s = panesReducer(s, clearPaneReconcileNotice({ tabId: 'tab1', paneId: 'p1' }))
+    expect(terminalContent(s, 'tab1', 'p1').reconcileNotice).toBeUndefined()
+  })
+
+  it('dead-session adjudication is one batched list', () => {
+    let s = panesReducer(undefined, setDeadSessionAdjudication([
+      { tabId: 't1', paneId: 'p1', title: 'a', mode: 'claude' },
+      { tabId: 't1', paneId: 'p2', title: 'b', mode: 'codex' },
+    ]))
+    expect(s.deadSessionAdjudication).toHaveLength(2)
+    s = panesReducer(s, resolveDeadSessionEntry({ tabId: 't1', paneId: 'p1' }))
+    expect(s.deadSessionAdjudication).toHaveLength(1)
+    expect(s.deadSessionAdjudication?.[0]?.paneId).toBe('p2')
+    s = panesReducer(s, clearDeadSessionAdjudication())
+    expect(s.deadSessionAdjudication).toHaveLength(0)
+  })
+
+  it('reconcile warming is set and cleared as one slice-level field', () => {
+    let s = panesReducer(undefined, setReconcileWarming({ count: 2, paneRefs: [{ tabId: 't1', paneId: 'p1' }, { tabId: 't1', paneId: 'p2' }] }))
+    expect(s.reconcileWarming).toEqual({ count: 2, paneRefs: [{ tabId: 't1', paneId: 'p1' }, { tabId: 't1', paneId: 'p2' }] })
+    s = panesReducer(s, clearReconcileWarming())
+    expect(s.reconcileWarming).toBeNull()
+  })
+
+  it('clears pendingReconcile when terminal.created folds into pane content', () => {
+    let s = stateWithTerminalPane({ createRequestId: 'cr-keep' })
+    s = panesReducer(s, resetPaneForReconcileCreate({ tabId: 'tab1', paneId: 'p1', intent: 'respawn', sessionRef: { provider: 'claude', sessionId: 'srv' } }))
+    const before = terminalContent(s, 'tab1', 'p1')
+    expect(before.pendingReconcile).toBe('respawn')
+    // Mirror TerminalView's terminal.created fold: spread current content + created updates
+    s = panesReducer(s, updatePaneContent({
+      tabId: 'tab1',
+      paneId: 'p1',
+      content: { ...before, terminalId: 'term-new', status: 'running' },
+    }))
+    const after = terminalContent(s, 'tab1', 'p1')
+    expect(after.terminalId).toBe('term-new')
+    expect(after.pendingReconcile).toBeUndefined()
+    expect(after.createRequestId).toBe('cr-keep')
+  })
+})
+
+describe('reconcile persistence stripping', () => {
+  beforeEach(() => {
+    localStorageMock.clear()
+    vi.clearAllMocks()
+    vi.useFakeTimers()
+    resetPersistFlushListenersForTests()
+    resetPersistedPanesCacheForTests()
+    resetPersistedLayoutCacheForTests()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('strips per-pane volatile reconcile fields and slice-level adjudication/warming from persistence', () => {
+    const store = configureStore({
+      reducer: { tabs: tabsReducer, panes: panesReducer },
+      middleware: (getDefault) => getDefault().concat(persistMiddleware as any),
+    })
+
+    store.dispatch(addTab({ mode: 'shell' }))
+    const tabId = store.getState().tabs.tabs[0].id
+    store.dispatch(initLayout({ tabId, paneId: 'p1', content: { kind: 'terminal', mode: 'claude', createRequestId: 'cr-keep' } }))
+    // Sets all three per-pane volatile fields: pendingReconcile, reconcileNotice, reconcileEpoch
+    store.dispatch(resetPaneForReconcileCreate({ tabId, paneId: 'p1', intent: 'fresh', reason: 'identity_never_observed' }))
+    store.dispatch(setDeadSessionAdjudication([{ tabId, paneId: 'p1', title: 'a', mode: 'claude' }]))
+    store.dispatch(setReconcileWarming({ count: 1, paneRefs: [{ tabId, paneId: 'p1' }] }))
+
+    // Live state has all volatile fields
+    const live = store.getState().panes
+    const liveContent = terminalContent(live, tabId, 'p1')
+    expect(liveContent.pendingReconcile).toBe('fresh')
+    expect(liveContent.reconcileNotice).toBe('Started fresh (identity_never_observed).')
+    expect(liveContent.reconcileEpoch).toBe(1)
+    expect(live.deadSessionAdjudication).toHaveLength(1)
+    expect(live.reconcileWarming).not.toBeNull()
+
+    vi.runAllTimers()
+
+    const raw = localStorage.getItem('freshell.layout.v3')
+    expect(raw).not.toBeNull()
+    const parsed = JSON.parse(raw!)
+    const leaf = parsed.panes.layouts[tabId]
+    expect(leaf.type).toBe('leaf')
+    expect(leaf.content.kind).toBe('terminal')
+    expect(leaf.content.createRequestId).toBe('cr-keep')
+    expect('pendingReconcile' in leaf.content).toBe(false)
+    expect('reconcileNotice' in leaf.content).toBe(false)
+    expect('reconcileEpoch' in leaf.content).toBe(false)
+    expect('deadSessionAdjudication' in parsed.panes).toBe(false)
+    expect('reconcileWarming' in parsed.panes).toBe(false)
+  })
+})

From a1f78176e54fa2f683c5b37433b3d373f4365b27 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 05:57:58 -0700
Subject: [PATCH 45/87] fix(client): port confirm-modal focus pattern to
 RecoveryOfferPanel; clear stale pending offers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review fixes for Task 5 (f4322f85):
- Port the confirm-modal focus pattern: initial focus on Restore, Tab
  focus trap, focus restore on close, body scroll-lock, Escape and
  overlay-click handling. Escape/overlay-click close WITHOUT deciding
  (brief is silent): decline permanently records dismissal, so an
  undecided close keeps the D3 pending flag set and the offer
  re-appears next boot — matching confirm-modal's cancel semantics.
- Clear the pending offer when the fetched inventory is dead
  (!recoverable or already dismissed) so a stale flag can't cause
  pointless fetches every boot; fetch ERRORS keep the flag (retry).
- Drop unused waitFor import in the persisted-boot test file.

Tests: 5 new + 2 extended (focus, Tab trap, Escape, overlay-click,
stale-pending clearing, error-path pending retention). 13/13 pass.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 src/components/RecoveryOfferPanel.tsx         | 108 +++++++++++++++++-
 ...RecoveryOfferPanel.persisted-boot.test.tsx |   2 +-
 .../components/RecoveryOfferPanel.test.tsx    |  73 +++++++++++-
 3 files changed, 176 insertions(+), 7 deletions(-)

diff --git a/src/components/RecoveryOfferPanel.tsx b/src/components/RecoveryOfferPanel.tsx
index 67a480dab..0d08d67f6 100644
--- a/src/components/RecoveryOfferPanel.tsx
+++ b/src/components/RecoveryOfferPanel.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
 import { useAppDispatch, useAppStore } from '@/store/hooks'
 import type { RootState } from '@/store/store'
@@ -23,6 +23,20 @@ import { Button } from '@/components/ui/button'
 
 const HEADING_ID = 'recovery-offer-heading'
 
+// Focus pattern shared with src/components/ui/confirm-modal.tsx
+function getFocusable(container: HTMLElement): HTMLElement[] {
+  const selectors = [
+    'button',
+    '[href]',
+    'input',
+    'select',
+    'textarea',
+    '[tabindex]:not([tabindex="-1"])',
+  ]
+  return Array.from(container.querySelectorAll<HTMLElement>(selectors.join(',')))
+    .filter((el) => !el.hasAttribute('disabled') && !el.getAttribute('aria-hidden'))
+}
+
 function walkArmingRestores(node: PaneNode | undefined): void {
   if (!node) return
   if (node.type === 'leaf') {
@@ -56,6 +70,11 @@ export function RecoveryOfferPanel(): JSX.Element | null {
   const dispatch = useAppDispatch()
   const store = useAppStore()
   const [inventory, setInventory] = useState<RecoveryInventory | null>(null)
+  const dialogRef = useRef<HTMLDivElement>(null)
+  const acceptRef = useRef<HTMLButtonElement>(null)
+  const previousFocusRef = useRef<HTMLElement | null>(null)
+  const previousOverflowRef = useRef<string | null>(null)
+  const open = inventory !== null
 
   useEffect(() => {
     const pending = getPendingOffer()
@@ -69,7 +88,13 @@ export function RecoveryOfferPanel(): JSX.Element | null {
     getRecoveryInventory(getCurrentTabRegistryClientInstanceId(), Date.now() - bootAt)
       .then((inv) => {
         if (cancelled) return
-        if (!inv.recoverable || isDismissed(inv.contentId)) return
+        if (!inv.recoverable || isDismissed(inv.contentId)) {
+          // A dead offer (nothing recoverable / already dismissed) must not
+          // leave a stale pending record causing pointless fetches every boot.
+          // Fetch ERRORS deliberately keep the flag set (retry next boot).
+          clearPendingOffer()
+          return
+        }
         setPendingOffer(inv.contentId, bootAt)
         setInventory(inv)
       })
@@ -81,6 +106,44 @@ export function RecoveryOfferPanel(): JSX.Element | null {
     }
   }, [])
 
+  // Focus management + body scroll-lock while the dialog is open
+  // (confirm-modal.tsx pattern).
+  useEffect(() => {
+    if (!open) return
+    previousFocusRef.current = document.activeElement as HTMLElement | null
+    previousOverflowRef.current = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+
+    const focusTimer = window.setTimeout(() => {
+      acceptRef.current?.focus()
+    }, 0)
+
+    return () => {
+      window.clearTimeout(focusTimer)
+      document.body.style.overflow = previousOverflowRef.current || ''
+      previousFocusRef.current?.focus()
+    }
+  }, [open])
+
+  // Escape closes WITHOUT deciding: unlike decline (which permanently records
+  // dismissal), an undecided close keeps the pending flag set so the offer
+  // re-appears next boot (D3) — matching confirm-modal's "cancel" semantics.
+  useEffect(() => {
+    if (!open) return
+    const handleKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        setInventory(null)
+      }
+    }
+    document.addEventListener('keydown', handleKey)
+    return () => document.removeEventListener('keydown', handleKey)
+  }, [open])
+
+  const closeWithoutDecision = () => {
+    setInventory(null)
+  }
+
   const accept = () => {
     if (!inventory) return
     clearPendingOffer()
@@ -108,14 +171,47 @@ export function RecoveryOfferPanel(): JSX.Element | null {
   return createPortal(
     <div
       className={`fixed inset-0 flex items-center justify-center bg-black/50 ${OVERLAY_Z.modal}`}
+      onClick={closeWithoutDecision}
+      onKeyDown={(e) => {
+        if (e.key === 'Escape') {
+          e.preventDefault()
+          closeWithoutDecision()
+        }
+      }}
       role="presentation"
+      tabIndex={-1}
     >
+      {/* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions */}
       <div
+        ref={dialogRef}
         role="dialog"
         aria-modal="true"
         aria-labelledby={HEADING_ID}
         data-testid="recovery-offer-panel"
         className="bg-background border border-border rounded-lg shadow-lg w-full max-w-md mx-4 p-5"
+        onClick={(e) => e.stopPropagation()}
+        onKeyDown={(e) => {
+          if (e.key !== 'Tab') return
+          const dialog = dialogRef.current
+          if (!dialog) return
+          const focusables = getFocusable(dialog)
+          if (focusables.length === 0) {
+            e.preventDefault()
+            return
+          }
+          const first = focusables[0]
+          const last = focusables[focusables.length - 1]
+          const active = document.activeElement as HTMLElement | null
+          if (e.shiftKey) {
+            if (active === first || !dialog.contains(active)) {
+              e.preventDefault()
+              last.focus()
+            }
+          } else if (active === last) {
+            e.preventDefault()
+            first.focus()
+          }
+        }}
       >
         <h2 id={HEADING_ID} className="text-lg font-semibold">
           Restore {paneCount} {paneCount === 1 ? 'pane' : 'panes'} from server memory?
@@ -146,7 +242,13 @@ export function RecoveryOfferPanel(): JSX.Element | null {
           <Button variant="ghost" size="sm" data-testid="recovery-decline" onClick={decline}>
             Not now
           </Button>
-          <Button variant="default" size="sm" data-testid="recovery-accept" onClick={accept}>
+          <Button
+            ref={acceptRef}
+            variant="default"
+            size="sm"
+            data-testid="recovery-accept"
+            onClick={accept}
+          >
             Restore
           </Button>
         </div>
diff --git a/test/unit/client/components/RecoveryOfferPanel.persisted-boot.test.tsx b/test/unit/client/components/RecoveryOfferPanel.persisted-boot.test.tsx
index 2c977f866..78d8bd3a9 100644
--- a/test/unit/client/components/RecoveryOfferPanel.persisted-boot.test.tsx
+++ b/test/unit/client/components/RecoveryOfferPanel.persisted-boot.test.tsx
@@ -2,7 +2,7 @@
 // found a persisted layout, so nothing was lost). Split from the main test file
 // because the boot-state capture is a module constant — one mock per module graph.
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { render, screen, waitFor, cleanup } from '@testing-library/react'
+import { render, screen, cleanup } from '@testing-library/react'
 import { Provider } from 'react-redux'
 import { configureStore } from '@reduxjs/toolkit'
 
diff --git a/test/unit/client/components/RecoveryOfferPanel.test.tsx b/test/unit/client/components/RecoveryOfferPanel.test.tsx
index dea37d8a1..c4e894acb 100644
--- a/test/unit/client/components/RecoveryOfferPanel.test.tsx
+++ b/test/unit/client/components/RecoveryOfferPanel.test.tsx
@@ -20,7 +20,7 @@ vi.mock('@/store/tabRegistrySync', async (importOriginal) => ({
 
 import { getRecoveryInventory } from '@/lib/api'
 import { RecoveryOfferPanel } from '@/components/RecoveryOfferPanel'
-import { getPendingOffer } from '@/lib/recovery/dismissal'
+import { getPendingOffer, setPendingOffer, isDismissed, recordDismissal } from '@/lib/recovery/dismissal'
 import { consumeTerminalRestoreRequestId } from '@/lib/terminal-restore'
 import type { RecoveryInventory } from '@/lib/recovery/types'
 import type { PaneNode } from '@/store/paneTypes'
@@ -130,7 +130,8 @@ describe('RecoveryOfferPanel', () => {
     expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
   })
 
-  it('renders nothing when inventory is not recoverable', async () => {
+  it('renders nothing when inventory is not recoverable and clears a stale pending offer', async () => {
+    setPendingOffer('cid-1', 0)
     vi.mocked(getRecoveryInventory).mockResolvedValue({
       ...INVENTORY,
       recoverable: false,
@@ -139,13 +140,79 @@ describe('RecoveryOfferPanel', () => {
     render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
     await waitFor(() => expect(vi.mocked(getRecoveryInventory)).toHaveBeenCalled())
     expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+    // A dead offer must not leave a pending record causing pointless fetches every boot
+    await waitFor(() => expect(getPendingOffer()).toBeNull())
   })
 
-  it('renders nothing when the inventory fetch fails', async () => {
+  it('clears a stale pending offer when the fetched inventory is already dismissed', async () => {
+    recordDismissal('cid-1')
+    setPendingOffer('cid-1', 0)
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    await waitFor(() => expect(vi.mocked(getRecoveryInventory)).toHaveBeenCalled())
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+    await waitFor(() => expect(getPendingOffer()).toBeNull())
+  })
+
+  it('renders nothing when the inventory fetch fails, keeping any pending offer for retry', async () => {
+    setPendingOffer('cid-1', 0)
     vi.mocked(getRecoveryInventory).mockRejectedValue(new Error('boom'))
     render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
     await waitFor(() => expect(vi.mocked(getRecoveryInventory)).toHaveBeenCalled())
     expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+    // Fetch errors are transient: the pending flag stays so the next boot retries
+    expect(getPendingOffer()).toEqual({ contentId: 'cid-1', bootAt: 0 })
+  })
+
+  it('moves initial focus to the Restore button and locks body scroll while open', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    const dialog = await screen.findByRole('dialog')
+    await waitFor(() => expect(screen.getByTestId('recovery-accept')).toHaveFocus())
+    expect(dialog.contains(document.activeElement)).toBe(true)
+    expect(document.body.style.overflow).toBe('hidden')
+  })
+
+  it('traps Tab focus inside the dialog', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    await screen.findByRole('dialog')
+    await waitFor(() => expect(screen.getByTestId('recovery-accept')).toHaveFocus())
+    // accept is the last focusable; Tab wraps to the first (decline)
+    await userEvent.tab()
+    expect(screen.getByTestId('recovery-decline')).toHaveFocus()
+    // decline is the first focusable; Shift+Tab wraps back to the last (accept)
+    await userEvent.tab({ shift: true })
+    expect(screen.getByTestId('recovery-accept')).toHaveFocus()
+  })
+
+  it('Escape closes without deciding: no dismissal recorded, pending offer kept, re-offers on remount', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    const first = render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    await screen.findByRole('dialog')
+    await userEvent.keyboard('{Escape}')
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+    // Undecided close (D3): pending survives so the offer re-appears next boot
+    expect(getPendingOffer()).toEqual({ contentId: 'cid-1', bootAt: 0 })
+    expect(isDismissed('cid-1')).toBe(false)
+    first.unmount()
+
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    expect(await screen.findByRole('dialog')).toBeInTheDocument()
+  })
+
+  it('overlay click closes without deciding; clicks inside the dialog do not close', async () => {
+    vi.mocked(getRecoveryInventory).mockResolvedValue(INVENTORY)
+    render(<Provider store={makeTestStore()}><RecoveryOfferPanel /></Provider>)
+    const dialog = await screen.findByRole('dialog')
+    // Clicking inside the dialog body must NOT close it
+    await userEvent.click(screen.getByText(/restore 1 pane/i))
+    expect(screen.getByRole('dialog')).toBeInTheDocument()
+    // Clicking the overlay closes without recording a decision
+    await userEvent.click(dialog.parentElement as HTMLElement)
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+    expect(getPendingOffer()).toEqual({ contentId: 'cid-1', bootAt: 0 })
+    expect(isDismissed('cid-1')).toBe(false)
   })
 
   it('shows the live note for live panes and recreates them without sessionRef (D7)', async () => {

From 2eec577164d2fd3411aeba7992f917171b2ae2e4 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:01:11 -0700
Subject: [PATCH 46/87] =?UTF-8?q?fix(codex):=20resume=20paths=20reapply=20?=
 =?UTF-8?q?model/sandbox/permission/effort=20from=20the=20ledger=20record?=
 =?UTF-8?q?=20(P1.13=20=C2=A72.6c)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 crates/freshell-freshagent/src/codex.rs | 255 +++++++++++++++++++++---
 1 file changed, 231 insertions(+), 24 deletions(-)

diff --git a/crates/freshell-freshagent/src/codex.rs b/crates/freshell-freshagent/src/codex.rs
index d0bc254fe..29b559f32 100644
--- a/crates/freshell-freshagent/src/codex.rs
+++ b/crates/freshell-freshagent/src/codex.rs
@@ -451,11 +451,23 @@ impl FreshCodexState {
             FreshAgentCreateOutcome::Proceed(guard) => guard,
         };
 
-        let cwd = msg.cwd.clone();
-        let model = normalize_freshcodex_model(msg.model.as_deref());
-        let effort = normalize_freshcodex_effort(Some(&model), msg.effort.as_deref());
-        let sandbox = msg.sandbox.map(sandbox_wire_value);
-        let permission_mode = msg.permission_mode.clone();
+        // P1.13 (Task 5, R1): for a resume-create the client's explicit params win and
+        // the ledger record fills the gaps -- merged BEFORE normalization, so a missing
+        // model recovers the recorded one instead of being rewritten to the default.
+        let rec = match msg.resume_session_id.as_deref() {
+            Some(resume_id) => self
+                .identity_sink()
+                .and_then(|s| s.load_settings("codex", resume_id))
+                .unwrap_or_default(),
+            None => crate::identity_sink::FreshAgentSettings::default(),
+        };
+        let cwd = msg.cwd.clone().or(rec.cwd);
+        let raw_model = msg.model.clone().or(rec.model);
+        let model = normalize_freshcodex_model(raw_model.as_deref());
+        let raw_effort = msg.effort.clone().or(rec.effort);
+        let effort = normalize_freshcodex_effort(Some(&model), raw_effort.as_deref());
+        let sandbox = msg.sandbox.map(sandbox_wire_value).or(rec.sandbox);
+        let permission_mode = msg.permission_mode.clone().or(rec.permission_mode);
 
         // Validate the effort maps to the codex wire vocabulary (adapter create calls
         // toCodexReasoningEffort purely to reject unsupported efforts before spawning).
@@ -1179,7 +1191,7 @@ impl FreshCodexState {
         &self,
         session_id: &str,
     ) -> Result<EnsureAliveOutcome, EnsureAliveError> {
-        let (cwd, model, effort, sandbox, permission_mode) = {
+        let (cwd, session_model, session_effort, session_sandbox, session_permission_mode) = {
             let guard = self.sessions.lock().await;
             let session = guard.get(session_id).ok_or(EnsureAliveError::NotFound)?;
             if !session.exited.load(Ordering::SeqCst) {
@@ -1194,6 +1206,29 @@ impl FreshCodexState {
             )
         };
 
+        // P1.13 (Task 5, R2): a blank stored model means this registration came from a
+        // settings-less resume (a record miss at R3 time) -- fall back to the ledger
+        // record so crash recovery doesn't silently respawn onto defaults.
+        let (model, sandbox, permission_mode, effort) = if session_model.is_empty() {
+            let rec = self
+                .identity_sink()
+                .and_then(|s| s.load_settings("codex", session_id))
+                .unwrap_or_default();
+            (
+                rec.model.unwrap_or_default(),
+                rec.sandbox,
+                rec.permission_mode,
+                rec.effort,
+            )
+        } else {
+            (
+                session_model,
+                session_sandbox,
+                session_permission_mode,
+                session_effort,
+            )
+        };
+
         // Single-flight: acquire (and possibly create) this session id's per-thread lock,
         // shared with `ensure_session_resumable`'s map so a concurrent historical-thread
         // resume and a crash recovery for the SAME id can't race either.
@@ -1862,14 +1897,41 @@ impl FreshCodexState {
             .await
             .map_err(ResumeSessionError::Transient)?;
 
+        // P1.13 (Task 5, R3): recover this thread's recorded settings snapshot BEFORE
+        // issuing `thread/resume`, gated per V7/A10.
+        let sink = self.identity_sink();
+        let recovered = sink
+            .as_ref()
+            .and_then(|s| s.load_settings("codex", thread_id));
+        // A record miss with NO prior recording (pre-ship / historical / sidebar-opened
+        // -- the populations this resume path exists to serve, see `snapshot_runtime_for`)
+        // is ROUTINE: resume silently with defaults exactly as before. NO alarm, NO
+        // defaults write (V7).
+        if recovered.is_none()
+            && sink
+                .as_ref()
+                .is_some_and(|s| s.was_recorded("codex", thread_id))
+        {
+            // The ledger PROVES prior fresh-agent recording, yet nothing is
+            // recoverable -- the genuine "never-happens" anomaly. Alarm.
+            tracing::warn!(session = %thread_id, "freshagent.codex.settings_record_unrecoverable");
+            self.emit_fresh_agent_error(
+                thread_id,
+                "SETTINGS_RESET",
+                "Session settings could not be recovered after restart - the agent is \
+                 running with default model and permissions. Reconfirm your settings.",
+            );
+        }
+        let rec = recovered.clone().unwrap_or_default();
+
         let resume_result = client
             .resume_thread(
                 thread_id,
                 StartThreadParams {
                     cwd: cwd.map(str::to_string),
-                    model: None,
-                    sandbox: None,
-                    approval_policy: None,
+                    model: rec.model.clone(),
+                    sandbox: rec.sandbox.clone(),
+                    approval_policy: rec.permission_mode.clone(),
                 },
             )
             .await;
@@ -1935,15 +1997,14 @@ impl FreshCodexState {
                 thread_id.to_string(),
                 CodexSession {
                     client: client.clone(),
-                    // Unknown until a `freshAgent.send` supplies one (matches the
-                    // reference's `settingsByThread` being unpopulated for a thread this
-                    // process has never created/sent to); `handle_send` overwrites these
-                    // via its own `rememberThreadSettings`-equivalent path when it runs.
-                    model: String::new(),
-                    effort: None,
-                    cwd: cwd.map(str::to_string),
-                    sandbox: None,
-                    permission_mode: None,
+                    // P1.13 (Task 5, R3): the ledger record's settings snapshot -- blank
+                    // only when no record was recoverable (never-recorded historical
+                    // sessions resume on defaults, exactly as before this fix).
+                    model: rec.model.clone().unwrap_or_default(),
+                    effort: rec.effort.clone(),
+                    cwd: cwd.map(str::to_string).or_else(|| rec.cwd.clone()),
+                    sandbox: rec.sandbox.clone(),
+                    permission_mode: rec.permission_mode.clone(),
                     active_turn: active_turn.clone(),
                     consumer,
                     kill_tx: Some(kill_tx),
@@ -1953,13 +2014,24 @@ impl FreshCodexState {
             );
         }
 
-        // P1.13 identity event (Task 4, R3): refresh write, `supersedes: None`. Until
-        // Task 5 lands this registers blanks (plus any caller-supplied cwd), so the
-        // helper's no-laundering guard makes the all-blank case a no-op -- never a
-        // defaults row for a never-recorded historical session (V7). AWAITED before
-        // this fn returns (durable-before-answer).
-        self.record_codex_binding(thread_id, None, "", None, None, None, cwd, None)
+        // P1.13 identity event (Task 5, R3): refresh write re-persisting the RECOVERED
+        // live values, `supersedes: None` -- GATED on an actual recovery. On a miss it
+        // must NOT run: writing would launder blank defaults into the ledger and
+        // permanently mask the miss (V7 §2's laundering finding). AWAITED before this
+        // fn returns (durable-before-answer).
+        if recovered.is_some() {
+            self.record_codex_binding(
+                thread_id,
+                None,
+                rec.model.as_deref().unwrap_or(""),
+                rec.sandbox.as_deref(),
+                rec.permission_mode.as_deref(),
+                rec.effort.as_deref(),
+                cwd.or(rec.cwd.as_deref()),
+                None,
+            )
             .await;
+        }
 
         Ok(ResumedCodexSession {
             client,
@@ -4135,6 +4207,141 @@ pub(crate) mod tests {
         }
     }
 
+    /// Task 5 (R3): a restart/reload resume of a thread the ledger holds a full settings
+    /// record for must reapply model/sandbox/permission/effort -- on the registered
+    /// session AND on the `thread/resume` RPC itself (the wire is the contract).
+    #[tokio::test(flavor = "multi_thread")]
+    async fn resume_after_restart_reapplies_settings_from_ledger() {
+        let _guard = ENV_LOCK.lock().await;
+        let op_log = tempfile::NamedTempFile::new().unwrap();
+        configure_fake_codex_cmd(
+            &json!({ "appendThreadOperationLogPath": op_log.path().to_str().unwrap() }).to_string(),
+        );
+        let (state, _bus) = state_with_bus();
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        fake.seed(
+            "codex",
+            "thread-9",
+            crate::identity_sink::FreshAgentSettings {
+                model: Some("gpt-5.3-codex-spark".into()),
+                sandbox: Some("workspace-write".into()),
+                permission_mode: Some("on-request".into()),
+                effort: Some("high".into()),
+                cwd: Some("/w".into()),
+            },
+        );
+        state.set_identity_sink(fake.clone());
+
+        // Simulate the restart path exactly as the existing R3 tests above do
+        // (`handle_attach_unknown_session_*`): attach to "thread-9", which is NOT in
+        // the in-memory map.
+        state.handle_attach(attach_msg("thread-9")).await;
+
+        // (1) The registered session carries the recovered settings:
+        let sessions = state.sessions.lock().await;
+        let s = sessions.get("thread-9").expect("session registered");
+        assert_eq!(s.model, "gpt-5.3-codex-spark");
+        assert_eq!(s.sandbox.as_deref(), Some("workspace-write"));
+        assert_eq!(s.permission_mode.as_deref(), Some("on-request"));
+        assert_eq!(s.effort.as_deref(), Some("high"));
+        drop(sessions);
+
+        // The fake app-server's log write lands from a SEPARATE OS process (see the
+        // single-flight test above) -- poll briefly for it before the one real read.
+        tokio::time::timeout(std::time::Duration::from_secs(5), async {
+            while !std::fs::read_to_string(op_log.path())
+                .unwrap_or_default()
+                .contains("\"thread/resume\"")
+            {
+                tokio::time::sleep(std::time::Duration::from_millis(20)).await;
+            }
+        })
+        .await
+        .expect("thread/resume reaches the fake app-server's op log");
+
+        // (2) The thread/resume RPC itself carried them (the wire is the contract):
+        let log = std::fs::read_to_string(op_log.path()).unwrap();
+        let resume_line = log
+            .lines()
+            .find(|l| l.contains("\"thread/resume\""))
+            .expect("thread/resume logged");
+        let entry: serde_json::Value = serde_json::from_str(resume_line).unwrap();
+        assert_eq!(entry["params"]["model"], "gpt-5.3-codex-spark");
+        assert_eq!(entry["params"]["sandbox"], "workspace-write");
+    }
+
+    /// V7/A10: record misses are ROUTINE (pre-ship sessions, sidebar-opened historical
+    /// threads -- R3 exists FOR them, see `snapshot_runtime_for`'s doc). They must
+    /// resume silently with defaults exactly as today, and must NOT launder a defaults
+    /// row into the ledger. Permanent regression guard for V7's no-spam rule.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn resume_of_a_never_recorded_session_is_silent_and_writes_no_defaults_row() {
+        let _guard = ENV_LOCK.lock().await;
+        configure_fake_codex_cmd("{}");
+        let (state, mut bus_rx) = state_with_bus();
+        // Deliberately empty: no record, no snapshot.
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        state.set_identity_sink(fake.clone());
+
+        // Same R3 entry point as above for an untracked "thread-x".
+        state.handle_attach(attach_msg("thread-x")).await;
+
+        // Bounded drain: NO SETTINGS_RESET frame may appear.
+        while let Ok(frame) =
+            tokio::time::timeout(std::time::Duration::from_secs(1), bus_rx.recv()).await
+        {
+            let Ok(text) = frame else { break };
+            assert!(
+                !text.contains("SETTINGS_RESET"),
+                "never-recorded resume must stay silent"
+            );
+        }
+        // No defaults laundering (V7 §2): no binding row was written for thread-x.
+        assert!(
+            !fake
+                .bindings
+                .lock()
+                .unwrap()
+                .iter()
+                .any(|b| b.session_id == "thread-x"),
+            "a load_settings miss must not write a defaults row"
+        );
+    }
+
+    /// The genuine anomaly: the ledger PROVES prior fresh-agent recording, yet no
+    /// snapshot is recoverable -- the only case that alarms (V7/A10).
+    #[tokio::test(flavor = "multi_thread")]
+    async fn resume_with_a_prior_record_but_unrecoverable_settings_alarms_settings_reset() {
+        let _guard = ENV_LOCK.lock().await;
+        configure_fake_codex_cmd("{}");
+        let (state, mut bus_rx) = state_with_bus();
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        fake.seed_recorded_only("codex", "thread-y"); // was_recorded=true, load_settings=None
+        state.set_identity_sink(fake);
+
+        // Same R3 entry point, attaching untracked "thread-y".
+        state.handle_attach(attach_msg("thread-y")).await;
+
+        let mut found = false;
+        while let Ok(frame) =
+            tokio::time::timeout(std::time::Duration::from_secs(2), bus_rx.recv()).await
+        {
+            let Ok(text) = frame else { break };
+            if text.contains("SETTINGS_RESET") {
+                // A2 qualification (V1): the frame must carry top-level
+                // sessionType/provider and a user-facing message.
+                assert!(text.contains("freshcodex") && text.contains("codex"));
+                assert!(text.contains("Reconfirm your settings"));
+                found = true;
+                break;
+            }
+        }
+        assert!(
+            found,
+            "recorded-but-unrecoverable resume must broadcast SETTINGS_RESET"
+        );
+    }
+
     /// REVIEW FIX (Minor, item 3): `fail_create`'s `freshAgent.create.failed` frame must
     /// carry `retryable: true`, matching legacy's hardcoded `retryable: true` on every
     /// create-failed path this port's `fail_create` corresponds to (`ws-handler.ts:3334`

From 642a6c735b7459297b3b3ebf81c747fe9f6f57e9 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:03:26 -0700
Subject: [PATCH 47/87] test(ws): codex drain_and_associate binds
 identity+ledger+broadcasts; re-arm and hijack pins

All three transplanted pins passed first try (Tasks 1-4 left no gap);
verified-red by inversion per the brief:
- binds_identity_ledger_and_broadcasts: inverted the identity assertion
  (session_ref_for == None) -> failed at the inverted line; restored.
- restore_created_pane_..._ledger: inverted the binding-row assertion
  (live_terminal_id == None) -> failed 'left: Some("t1") right: None'; restored.
- located_session_bound_elsewhere_is_rejected: inverted the POSITIVE
  resolution signal (armed_count == 1) -> failed 'left: 0 right: 1',
  proving resolution actually occurred and the adoption-tail guard (not a
  non-resolving locator) is what leaves identity None; restored.
---
 crates/freshell-ws/src/codex_association.rs | 342 ++++++++++++++++++++
 1 file changed, 342 insertions(+)

diff --git a/crates/freshell-ws/src/codex_association.rs b/crates/freshell-ws/src/codex_association.rs
index e74410730..f61c28e5b 100644
--- a/crates/freshell-ws/src/codex_association.rs
+++ b/crates/freshell-ws/src/codex_association.rs
@@ -230,6 +230,21 @@ mod tests {
         (state, rx)
     }
 
+    /// Sibling of `state_with_locator` with a REAL (enabled) pane ledger
+    /// rooted at `ledger_dir` — copied from `opencode_association.rs`'s
+    /// harness rather than churning every existing caller of the
+    /// disabled-ledger fixture.
+    fn state_with_locator_and_ledger(
+        data_home: std::path::PathBuf,
+        ledger_dir: &std::path::Path,
+    ) -> (WsState, tokio::sync::broadcast::Receiver<String>) {
+        let (mut state, rx) = state_with_locator(data_home);
+        state.pane_ledger = std::sync::Arc::new(crate::pane_ledger::PaneLedger::new(Some(
+            ledger_dir.to_path_buf(),
+        )));
+        (state, rx)
+    }
+
     fn unique_temp_dir(label: &str) -> std::path::PathBuf {
         use std::sync::atomic::{AtomicU64, Ordering};
         static COUNTER: AtomicU64 = AtomicU64::new(0);
@@ -242,6 +257,30 @@ mod tests {
         dir
     }
 
+    /// Write a rollout file whose FIRST line is the session_meta identity
+    /// record, exactly the shape the real codex CLI writes (payload.id =
+    /// identity; payload.cwd = the session's working dir). Reused inline
+    /// from `codex_locator.rs`'s test helper.
+    fn write_rollout(
+        root: &std::path::Path,
+        rel_dir: &str,
+        thread_id: &str,
+        cwd: Option<&str>,
+    ) -> std::path::PathBuf {
+        let dir = root.join(rel_dir);
+        std::fs::create_dir_all(&dir).expect("create rollout dir");
+        let file = dir.join(format!("rollout-2026-07-26T08-00-00-{thread_id}.jsonl"));
+        let payload = match cwd {
+            Some(c) => format!(r#"{{"id":"{thread_id}","cwd":"{c}"}}"#),
+            None => format!(r#"{{"id":"{thread_id}"}}"#),
+        };
+        let line = format!(
+            r#"{{"timestamp":"2026-07-26T08:00:00.000Z","type":"session_meta","payload":{payload}}}"#
+        );
+        std::fs::write(&file, format!("{line}\n")).expect("write rollout");
+        file
+    }
+
     #[test]
     fn is_submit_input_matches_enter_only_sequences() {
         for yes in ["\r", "\n", "\r\n", "\r\r\n\n"] {
@@ -278,4 +317,307 @@ mod tests {
         assert!(locator.note_submit("t1", now_ms()));
         let _ = std::fs::remove_dir_all(&dir);
     }
+
+    /// Fresh codex pane: rollout appears after arm → sweep binds identity,
+    /// writes the durable binding row, and broadcasts both frames in the
+    /// pinned order.
+    #[tokio::test]
+    async fn drain_and_associate_binds_identity_ledger_and_broadcasts() {
+        const TID: &str = "11111111-2222-3333-4444-555555555555";
+        let home = unique_temp_dir("drain-associate");
+        let ledger_dir = unique_temp_dir("drain-associate-ledger");
+        let (state, mut rx) = state_with_locator_and_ledger(home.clone(), &ledger_dir);
+
+        // A running codex terminal the association controller can validate
+        // against (mode/status/resume_session_id all read from
+        // `state.registry`, mirroring the controller's own reject checks).
+        let spec = freshell_platform::build_spawn_spec(
+            freshell_platform::ShellType::System,
+            freshell_platform::detect::HostOs::Linux,
+            false,
+            Some("/tmp"),
+            &freshell_platform::RealEnv,
+            &freshell_platform::RealFileProbe,
+            &std::collections::BTreeMap::new(),
+            None,
+            None,
+        );
+        state
+            .registry
+            .create(
+                &spec,
+                &std::collections::BTreeMap::new(),
+                "t1".to_string(),
+                "stream-1".to_string(),
+                "codex",
+                None,
+                None,
+                None,
+                None,
+            )
+            .expect("spawn a real shell for the test PTY");
+        state
+            .registry
+            .set_meta("t1", None, None, Some("codex".to_string()), None);
+
+        maybe_arm(&state, "t1", "codex", Some("/tmp"), None);
+
+        // OPEN THE WINDOW FIRST: windows are Enter-anchored (no spawn
+        // window), so resolution requires a submit, and the FIRST submit
+        // re-snapshots known_files — the rollout MUST be seeded AFTER this
+        // call (a pre-seeded file would be captured by the re-snapshot and
+        // never bind; that exclusion is the Task 1/2 hardening, not a bug).
+        note_possible_submit(&state, "t1", "\r").await;
+
+        // THEN write the rollout the locator must find (lands well inside
+        // the 2 s Enter-anchored window).
+        write_rollout(&home, "2026/07/26", TID, Some("/tmp"));
+
+        // Drain repeatedly until the locator's correlation window has
+        // definitely closed relative to wall-clock `now_ms()`.
+        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+        for _ in 0..40 {
+            drain_and_associate(&state).await;
+            if state
+                .identity
+                .get("t1")
+                .and_then(|i| i.session_id)
+                .is_some()
+            {
+                break;
+            }
+            tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+        }
+
+        assert_eq!(
+            state.identity.session_ref_for("t1"),
+            Some(freshell_protocol::SessionLocator {
+                provider: "codex".to_string(),
+                session_id: TID.to_string(),
+            })
+        );
+
+        let dir_entry = state
+            .registry
+            .directory()
+            .into_iter()
+            .find(|e| e.terminal_id == "t1")
+            .unwrap();
+        assert_eq!(dir_entry.resume_session_id.as_deref(), Some(TID));
+
+        let hit = state
+            .pane_ledger
+            .lookup_by_session("codex", TID)
+            .expect("binding row written at resolution");
+        assert_eq!(hit.row.live_terminal_id.as_deref(), Some("t1"));
+        assert!(state.pane_ledger.pending_for_terminal("t1").is_none());
+
+        // Broadcasts, in the pinned order: `terminal.session.associated`
+        // FIRST, then `terminal.meta.updated` (frame type assertions exactly
+        // as the opencode sibling does them, plus the order pin).
+        let mut frames = Vec::new();
+        while let Ok(frame) = rx.try_recv() {
+            frames.push(frame);
+        }
+        let associated_at = frames
+            .iter()
+            .position(|f| f.contains("terminal.session.associated") && f.contains(TID))
+            .expect("expected a terminal.session.associated broadcast");
+        let meta_at = frames
+            .iter()
+            .position(|f| f.contains("terminal.meta.updated") && f.contains(TID))
+            .expect("expected a terminal.meta.updated broadcast");
+        assert!(
+            associated_at < meta_at,
+            "pinned order: associated THEN meta.updated"
+        );
+
+        state.registry.kill("t1");
+        let _ = std::fs::remove_dir_all(&home);
+        let _ = std::fs::remove_dir_all(&ledger_dir);
+    }
+
+    /// Wave-A re-arm contract (the codex mirror of P1.10): a restore-created
+    /// pane WITHOUT identity (resume None) arms like a fresh pane, records a
+    /// pending marker, and resolves into the ledger — binding row first,
+    /// marker gone after.
+    #[tokio::test]
+    async fn restore_created_pane_without_identity_arms_and_resolves_into_the_ledger() {
+        const TID: &str = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+        let home = unique_temp_dir("p110-restore-rearm");
+        let ledger_dir = unique_temp_dir("p110-ledger");
+        let (state, _rx) = state_with_locator_and_ledger(home.clone(), &ledger_dir);
+
+        // A real PTY registry row, exactly as the sibling resolve-path test
+        // spawns it (the controller's reject checks read mode/status/resume
+        // from `state.registry`).
+        let spec = freshell_platform::build_spawn_spec(
+            freshell_platform::ShellType::System,
+            freshell_platform::detect::HostOs::Linux,
+            false,
+            Some("/tmp"),
+            &freshell_platform::RealEnv,
+            &freshell_platform::RealFileProbe,
+            &std::collections::BTreeMap::new(),
+            None,
+            None,
+        );
+        state
+            .registry
+            .create(
+                &spec,
+                &std::collections::BTreeMap::new(),
+                "t1".to_string(),
+                "stream-1".to_string(),
+                "codex",
+                None,
+                None,
+                None,
+                None,
+            )
+            .expect("spawn a real shell for the test PTY");
+        state
+            .registry
+            .set_meta("t1", None, None, Some("codex".to_string()), None);
+
+        // The restore-shaped arm: identity absent, so resume is None — the
+        // exact argument shape terminal.rs's handle_create produces for a
+        // restore:true create that carried no sessionRef.
+        maybe_arm(&state, "t1", "codex", Some("/tmp"), None);
+        assert_eq!(state.codex_locator.as_ref().unwrap().armed_count(), 1);
+
+        // The spawn-time pending marker (written by handle_create in
+        // production — written directly here because this test drives the
+        // module, not the WS handler).
+        state
+            .pane_ledger
+            .record_pending("t1", "codex", Some("/tmp"), now_ms())
+            .unwrap();
+
+        // Enter-anchored window needs the submit; the first-submit
+        // re-snapshot would exclude a pre-seeded file, so the rollout is
+        // written only AFTER this await completes.
+        note_possible_submit(&state, "t1", "\r").await;
+
+        write_rollout(&home, "2026/07/26", TID, Some("/tmp"));
+
+        // Drain repeatedly until the locator's correlation window has
+        // definitely closed relative to wall-clock `now_ms()`.
+        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+        for _ in 0..40 {
+            drain_and_associate(&state).await;
+            if state
+                .identity
+                .get("t1")
+                .and_then(|i| i.session_id)
+                .is_some()
+            {
+                break;
+            }
+            tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+        }
+
+        // Resolution wrote the binding and deleted the marker (pinned order).
+        let hit = state
+            .pane_ledger
+            .lookup_by_session("codex", TID)
+            .expect("binding row written at resolution");
+        assert_eq!(hit.row.live_terminal_id.as_deref(), Some("t1"));
+        assert!(state.pane_ledger.pending_for_terminal("t1").is_none());
+        assert!(state.pane_ledger.list_pending_raw().is_empty());
+
+        state.registry.kill("t1");
+        let _ = std::fs::remove_dir_all(&home);
+        let _ = std::fs::remove_dir_all(&ledger_dir);
+    }
+
+    /// One-writer defense survives the channel swap: a session already bound
+    /// to ANOTHER terminal (including a retired binding) is never re-adopted.
+    #[tokio::test]
+    async fn located_session_bound_elsewhere_is_rejected() {
+        const TID: &str = "99999999-8888-7777-6666-555555555555";
+        let home = unique_temp_dir("bound-elsewhere");
+        let (state, _rx) = state_with_locator(home.clone());
+
+        // The victim's binding, RETIRED — exactly the state the exit path
+        // leaves behind (terminal.rs's exit hook calls
+        // `identity.retire(&tid)`). Retired-INCLUSIVE is the point: a dead
+        // pane's identity must still repel adoption by a fresh terminal.
+        state
+            .identity
+            .upsert("victim", Some("codex"), Some(TID), Some("/tmp"), now_ms());
+        assert!(state.identity.retire("victim"));
+
+        // A real PTY "t1" (codex mode), armed, with a locator handle kept
+        // for the positive resolution signal below.
+        let spec = freshell_platform::build_spawn_spec(
+            freshell_platform::ShellType::System,
+            freshell_platform::detect::HostOs::Linux,
+            false,
+            Some("/tmp"),
+            &freshell_platform::RealEnv,
+            &freshell_platform::RealFileProbe,
+            &std::collections::BTreeMap::new(),
+            None,
+            None,
+        );
+        state
+            .registry
+            .create(
+                &spec,
+                &std::collections::BTreeMap::new(),
+                "t1".to_string(),
+                "stream-1".to_string(),
+                "codex",
+                None,
+                None,
+                None,
+                None,
+            )
+            .expect("spawn a real shell for the test PTY");
+        state
+            .registry
+            .set_meta("t1", None, None, Some("codex".to_string()), None);
+
+        maybe_arm(&state, "t1", "codex", Some("/tmp"), None);
+        let locator = state.codex_locator.as_ref().unwrap().clone();
+        assert_eq!(locator.armed_count(), 1);
+
+        // Open the Enter-anchored window, THEN seed the rollout (after the
+        // submit — the first-submit re-snapshot would exclude a pre-seeded
+        // file) with payload.cwd set to THE PANE'S OWN cwd: the rollout must
+        // be a fully resolvable candidate, or this test proves nothing.
+        note_possible_submit(&state, "t1", "\r").await;
+        write_rollout(&home, "2026/07/26", TID, Some("/tmp"));
+
+        // Poll drain_and_associate past the window.
+        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+        for _ in 0..40 {
+            drain_and_associate(&state).await;
+            if locator.armed_count() == 0 {
+                break;
+            }
+            tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+        }
+
+        // POSITIVE resolution signal FIRST, so the negative assertions
+        // cannot pass vacuously: tick emitted Located and disarmed —
+        // resolution HAPPENED, so whatever follows is the adoption-tail
+        // guard's doing (a locator that never resolved would also leave
+        // identity None, and identity-only assertions cannot tell those
+        // worlds apart).
+        assert_eq!(locator.armed_count(), 0);
+        // Guard refused: nothing adopted.
+        assert!(state.identity.session_ref_for("t1").is_none());
+        let dir_entry = state
+            .registry
+            .directory()
+            .into_iter()
+            .find(|e| e.terminal_id == "t1")
+            .unwrap();
+        assert!(dir_entry.resume_session_id.is_none());
+
+        state.registry.kill("t1");
+        let _ = std::fs::remove_dir_all(&home);
+    }
 }

From 3583a1fde51eeb63e27c054ef4f61dd217e1b660 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:09:18 -0700
Subject: [PATCH 48/87] =?UTF-8?q?feat(codex):=20user-visible=20THREAD=5FME?=
 =?UTF-8?q?MORY=5FLOST=20degradation=20frame=20on=20crash=20respawn=20(P1.?=
 =?UTF-8?q?13=20=C2=A72.6b)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-freshagent/src/codex.rs | 86 +++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/crates/freshell-freshagent/src/codex.rs b/crates/freshell-freshagent/src/codex.rs
index 29b559f32..eb625503d 100644
--- a/crates/freshell-freshagent/src/codex.rs
+++ b/crates/freshell-freshagent/src/codex.rs
@@ -1552,6 +1552,18 @@ impl FreshCodexState {
             },
         ));
 
+        // P1.13 §2.6b (Task 6): memory loss must be user-visible, not server-log-only.
+        // Emitted AFTER the materialized broadcast above -- the frozen client re-keys
+        // its session state on `materialized` (`fresh-agent-ws.ts:143-160`); emitting
+        // first would target a session id the client no longer tracks. The non-`RESTORE_`
+        // error branch also clears streaming and forces `running -> idle` -- safe here,
+        // the turn is already dead.
+        self.emit_fresh_agent_error(
+            &new_thread_id,
+            "THREAD_MEMORY_LOST",
+            "Codex crashed and this pane was restarted as a new thread. The agent no longer has memory of the earlier conversation in this pane.",
+        );
+
         Ok(EnsureAliveOutcome::Respawned {
             new_session_id: new_thread_id,
         })
@@ -5717,6 +5729,80 @@ pub(crate) mod tests {
         assert!(guard.contains_key(&new_thread_id));
     }
 
+    /// P1.13 §2.6b (Task 6): crash respawn discards conversation memory -- that loss must be
+    /// user-visible. After the mint-new-thread fallback, a `THREAD_MEMORY_LOST` degradation
+    /// frame is broadcast under the NEW thread id, AFTER the
+    /// `freshAgent.session.materialized` frame (the frozen client re-keys its session state
+    /// on materialized; an error frame emitted first would target an id the client no
+    /// longer tracks).
+    #[tokio::test(flavor = "multi_thread")]
+    async fn send_after_crash_mint_new_thread_broadcasts_thread_memory_lost_after_materialized() {
+        let _guard = ENV_LOCK.lock().await;
+        let (st, mut rx) = state_with_bus();
+
+        configure_fake_codex_cmd(
+            r#"{"threadStartThreadId":"thread-original","exitProcessAfterMethodsOnce":["thread/start"]}"#,
+        );
+        let thread_id = create_real_fake_session(&st, &mut rx).await;
+        wait_for_self_heal(&st, &mut rx, &thread_id).await;
+
+        // The respawned sidecar's `thread/resume` reports the thread as genuinely gone,
+        // forcing the mint-new-thread crash-respawn fallback.
+        configure_fake_codex_cmd(
+            &json!({
+                "threadStartThreadId": "thread-respawned",
+                "overrides": {
+                    "thread/resume": {
+                        "error": { "code": -32001, "message": "Thread not found" }
+                    }
+                }
+            })
+            .to_string(),
+        );
+
+        st.handle_send(FreshAgentSend {
+            request_id: Some("req-2".to_string()),
+            provider: freshell_protocol::AgentProvider::Codex,
+            session_id: thread_id.clone(),
+            session_type: freshell_protocol::SessionType::Freshcodex,
+            text: "hello again".to_string(),
+            images: None,
+            cwd: None,
+            settings: None,
+        })
+        .await;
+
+        let mut saw_materialized = false;
+        let mut new_thread_id = String::new();
+        let mut degradation_after_materialized = false;
+        while let Ok(frame) =
+            tokio::time::timeout(std::time::Duration::from_secs(2), rx.recv()).await
+        {
+            let Ok(text) = frame else { break };
+            if text.contains("freshAgent.session.materialized") {
+                saw_materialized = true;
+                let materialized: Value = serde_json::from_str(&text).unwrap();
+                new_thread_id = materialized["sessionId"].as_str().unwrap().to_string();
+            }
+            if text.contains("THREAD_MEMORY_LOST") {
+                assert!(
+                    saw_materialized,
+                    "degradation frame must follow materialized (client re-keys on it)"
+                );
+                assert!(
+                    text.contains(&new_thread_id),
+                    "frame must target the NEW thread id"
+                );
+                degradation_after_materialized = true;
+                break;
+            }
+        }
+        assert!(
+            degradation_after_materialized,
+            "crash respawn must broadcast a user-visible degradation frame"
+        );
+    }
+
     /// FIX-2: a resume failure that is NOT "thread not found" (a transient RPC error) must
     /// NOT silently mint a new thread -- it reports `CODEX_RESPAWN_FAILED` and leaves the
     /// session mapped under its OLD id, still marked exited, for a future retry (mirroring

From 8e7279fa91b5be30152715cc035baeb2dc19da07 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:13:00 -0700
Subject: [PATCH 49/87] test(ws): fresh codex pane turn.complete carries
 sessionId via server-side locator (adds locator-wired spawn helper to the
 shared harness)

---
 .../tests/codex_locator_activity.rs           | 249 ++++++++++++++++++
 crates/freshell-ws/tests/common/mod.rs        |  85 ++++++
 2 files changed, 334 insertions(+)
 create mode 100644 crates/freshell-ws/tests/codex_locator_activity.rs

diff --git a/crates/freshell-ws/tests/codex_locator_activity.rs b/crates/freshell-ws/tests/codex_locator_activity.rs
new file mode 100644
index 000000000..31dbc09e4
--- /dev/null
+++ b/crates/freshell-ws/tests/codex_locator_activity.rs
@@ -0,0 +1,249 @@
+//! Lane B2: a FRESH codex terminal (no resume id, NO client candidate frame)
+//! gains identity from the server-side rollout locator, and its activity
+//! frames carry the sessionId — closing the "terminals created before any
+//! candidate" status gap.
+//!
+//! Harness copied from the (retired) codex_candidate_activity.rs: real
+//! server, real socket, real PTY running a fake codex binary, CODEX_HOME
+//! pointed at a tempdir.
+
+#[cfg(unix)]
+mod common;
+
+#[cfg(unix)]
+use futures_util::{SinkExt, StreamExt};
+#[cfg(unix)]
+use serde_json::json;
+#[cfg(unix)]
+use std::time::Duration;
+#[cfg(unix)]
+use tokio_tungstenite::tungstenite::Message as WsMessage;
+
+/// Fake codex: records argv to $CODEX_ARGV_CAPTURE_PATH (atomic tmp+mv) then
+/// sleeps. Copied from tests/codex_candidate_persisted.rs.
+#[cfg(unix)]
+fn write_fake_codex() -> std::path::PathBuf {
+    let script_path = std::env::temp_dir().join(format!(
+        "freshell-codex-locator-activity-fake-{}.sh",
+        std::process::id()
+    ));
+    let script = "#!/bin/sh\n\
+        printf '%s\\n' \"$@\" > \"$CODEX_ARGV_CAPTURE_PATH.tmp\"\n\
+        mv \"$CODEX_ARGV_CAPTURE_PATH.tmp\" \"$CODEX_ARGV_CAPTURE_PATH\"\n\
+        exec sleep 300\n";
+    std::fs::write(&script_path, script).expect("write fake codex script");
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let mut perms = std::fs::metadata(&script_path).unwrap().permissions();
+        perms.set_mode(0o755);
+        std::fs::set_permissions(&script_path, perms).unwrap();
+    }
+    script_path
+}
+
+#[cfg(unix)]
+fn codex_capture_spec() -> freshell_platform::CliCommandSpec {
+    freshell_platform::CliCommandSpec {
+        name: "codex".to_string(),
+        label: "Codex CLI".to_string(),
+        env_var: None,
+        default_cmd: write_fake_codex().to_string_lossy().to_string(),
+        base_args: vec![],
+        base_env: std::collections::BTreeMap::new(),
+        // Real codex manifest shape: resume subcommand, no createSessionArgs.
+        resume_args: Some(vec!["resume".to_string(), "{{sessionId}}".to_string()]),
+        create_session_args: None,
+        model_args: None,
+        sandbox_args: None,
+        permission_mode_args: None,
+    }
+}
+
+/// Send a fresh `terminal.create` (no sessionRef, no resume id) and await its
+/// `terminal.created`, returning the terminalId.
+#[cfg(unix)]
+async fn send_create(ws: &mut common::TestWs, mode: &str) -> String {
+    ws.send(WsMessage::Text(
+        json!({
+            "type": "terminal.create",
+            "requestId": "req-codex-locator-activity-1",
+            "mode": mode,
+            "shell": "system",
+            "cwd": std::env::temp_dir().to_string_lossy(),
+        })
+        .to_string(),
+    ))
+    .await
+    .expect("send terminal.create");
+    let created = common::next_frame_of_type(ws, "terminal.created").await;
+    created["terminalId"]
+        .as_str()
+        .expect("terminal.created carries terminalId")
+        .to_string()
+}
+
+/// Scan WS text frames until `pred` matches or the 10s budget elapses.
+/// Non-matching frames are simply skipped (no drop-on-mismatch semantics).
+#[cfg(unix)]
+async fn wait_for_frame(
+    ws: &mut common::TestWs,
+    pred: impl Fn(&serde_json::Value) -> bool,
+) -> bool {
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(10);
+    while tokio::time::Instant::now() < deadline {
+        let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
+        match tokio::time::timeout(remaining.max(Duration::from_millis(1)), ws.next()).await {
+            Ok(Some(Ok(WsMessage::Text(text)))) => {
+                if let Ok(value) = serde_json::from_str::<serde_json::Value>(&text) {
+                    if pred(&value) {
+                        return true;
+                    }
+                }
+            }
+            Ok(Some(Ok(_))) => {}
+            _ => return false, // stream ended, ws error, or timed out
+        }
+    }
+    false
+}
+
+/// Wall-clock ms — matches the tracker's `now_ms` timestamp domain.
+#[cfg(unix)]
+fn now_ms() -> i64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .expect("clock after epoch")
+        .as_millis() as i64
+}
+
+/// A codex rollout `event_msg` line (shape copied from activity.rs's
+/// `codex_event_line` test helper).
+#[cfg(unix)]
+fn codex_event_line(payload_type: &str, at_ms: i64) -> String {
+    format!(r#"{{"timestamp":{at_ms},"type":"event_msg","payload":{{"type":"{payload_type}"}}}}"#)
+}
+
+#[cfg(unix)]
+#[tokio::test(flavor = "multi_thread")]
+async fn fresh_pane_locator_identity_reaches_activity_and_turn_complete() {
+    const THREAD: &str = "11111111-2222-3333-4444-555555555555";
+
+    // ---- env setup (single sequential test: this binary owns process env) ----
+    // CODEX_HOME tempdir; the sessions day tree exists but holds NO rollout
+    // yet — the locator's FIRST-submit re-snapshot must see zero files.
+    let codex_home = tempfile::tempdir().expect("codex home");
+    let sessions_day = codex_home
+        .path()
+        .join("sessions")
+        .join("2026")
+        .join("07")
+        .join("24");
+    std::fs::create_dir_all(&sessions_day).expect("sessions tree");
+    std::env::set_var("CODEX_HOME", codex_home.path());
+    std::env::remove_var("FRESHELL_CODEX_MANAGED_LAUNCH");
+    let capture = std::env::temp_dir().join(format!(
+        "codex-locator-activity-argv-{}.txt",
+        std::process::id()
+    ));
+    let _ = std::fs::remove_file(&capture);
+    std::env::set_var("CODEX_ARGV_CAPTURE_PATH", &capture);
+
+    let (url, registry) = common::spawn_server_with_specs_activity_and_codex_locator(
+        vec![codex_capture_spec()],
+        &codex_home.path().join("sessions"),
+    )
+    .await;
+    let (mut ws, _inventory) = common::connect_and_capture_inventory(&url).await;
+
+    // 1. Create a FRESH codex terminal (no sessionRef, no resume id, and —
+    //    unlike the retired candidate test — NO candidate frame ever sent).
+    //    The create arms the locator server-side.
+    let terminal_id = send_create(&mut ws, "codex").await;
+
+    // 2a. First Enter: windows are Enter-anchored (no spawn window). This
+    //     submit takes the FIRST-submit re-snapshot of known_files and opens
+    //     the 2 s window — the rollout must NOT exist yet (a pre-seeded file
+    //     would be captured by the re-snapshot and permanently excluded).
+    common::send_input(&mut ws, &terminal_id, "\r").await;
+
+    // 2b. Let that first window resolve with zero candidates (deadline 2 s +
+    //     150 ms sweep, with margin).
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // 2c. NOW write the rollout the locator must find. payload.cwd must
+    //     match the terminal's cwd (the value send_create passed).
+    let cwd = std::env::temp_dir().to_string_lossy().to_string();
+    let rollout = sessions_day.join(format!("rollout-2026-07-24T12-00-00-{THREAD}.jsonl"));
+    std::fs::write(
+        &rollout,
+        format!("{{\"timestamp\":\"2026-07-24T12:00:00.000Z\",\"type\":\"session_meta\",\"payload\":{{\"id\":\"{THREAD}\",\"cwd\":\"{cwd}\"}}}}\n"),
+    )
+    .unwrap();
+
+    // 2d. Second Enter: a later Enter re-opens a resolved window WITHOUT
+    //     re-snapshotting (Task 2's later_enter_reopen_keeps_the_first_submit_snapshot),
+    //     so the file written in 2c is deterministically the sole new candidate.
+    common::send_input(&mut ws, &terminal_id, "\r").await;
+
+    // 3. The locator sweep resolves and the adoption tail must emit
+    //    codex.activity.updated with the sessionId. Collect frames by
+    //    scanning (never drop-on-mismatch); the 10 s budget covers the ~2 s
+    //    Enter-anchored deadline + 150 ms sweep.
+    let bound = wait_for_frame(&mut ws, |v| {
+        v["type"] == "codex.activity.updated"
+            && v["upsert"]
+                .as_array()
+                .map(|u| {
+                    u.iter().any(|r| {
+                        r["terminalId"] == terminal_id.as_str() && r["sessionId"] == THREAD
+                    })
+                })
+                .unwrap_or(false)
+    })
+    .await;
+    assert!(
+        bound,
+        "expected codex.activity.updated carrying the locator-resolved sessionId"
+    );
+
+    // 4. The adoption tail also attached the rollout to the status watcher
+    //    (attach_codex_rollout). Append a task_started/task_complete pair to
+    //    the SAME rollout — inotify drives the reads — and the completion
+    //    frame must be stamped with the provider AND sessionId.
+    {
+        use std::io::Write;
+        let mut f = std::fs::OpenOptions::new()
+            .append(true)
+            .open(&rollout)
+            .expect("open rollout for append");
+        writeln!(f, "{}", codex_event_line("task_started", now_ms())).expect("append task_started");
+    }
+    // Let the busy edge land before completing the turn (mirrors the
+    // seed-then-append shape of activity.rs's rollout-lane unit tests).
+    tokio::time::sleep(Duration::from_millis(300)).await;
+    {
+        use std::io::Write;
+        let mut f = std::fs::OpenOptions::new()
+            .append(true)
+            .open(&rollout)
+            .expect("open rollout for append");
+        writeln!(f, "{}", codex_event_line("task_complete", now_ms()))
+            .expect("append task_complete");
+    }
+
+    let completed = wait_for_frame(&mut ws, |v| {
+        v["type"] == "terminal.turn.complete"
+            && v["terminalId"] == terminal_id.as_str()
+            && v["provider"] == "codex"
+            && v["sessionId"] == THREAD
+    })
+    .await;
+    assert!(
+        completed,
+        "expected terminal.turn.complete with provider=codex and sessionId stamped by the locator adoption"
+    );
+
+    registry.kill(&terminal_id);
+    std::env::remove_var("CODEX_HOME");
+    std::env::remove_var("CODEX_ARGV_CAPTURE_PATH");
+}
diff --git a/crates/freshell-ws/tests/common/mod.rs b/crates/freshell-ws/tests/common/mod.rs
index 774967980..1dc2f48f4 100644
--- a/crates/freshell-ws/tests/common/mod.rs
+++ b/crates/freshell-ws/tests/common/mod.rs
@@ -309,6 +309,91 @@ pub async fn spawn_server_with_specs_and_activity(
     (format!("ws://{addr}/ws", addr = addr), registry)
 }
 
+/// [`spawn_server_with_specs_and_activity`], with the codex rollout LOCATOR
+/// wired and its sweep spawned (Lane B2: fresh codex panes gain identity
+/// server-side with NO client candidate frame). Identical body except two
+/// deltas: `codex_locator` is `Some(CodexLocator)` rooted at
+/// `codex_sessions_root` (tests pass `<CODEX_HOME>/sessions` — the same root
+/// `codex_sessions_root()` resolves in the real server), and the locator
+/// sweep is spawned before the router.
+#[allow(dead_code)] // not every test binary uses the codex-locator variant
+pub async fn spawn_server_with_specs_activity_and_codex_locator(
+    cli_commands: Vec<freshell_platform::CliCommandSpec>,
+    codex_sessions_root: &std::path::Path,
+) -> (String, freshell_terminal::TerminalRegistry) {
+    let auth_token = Arc::new(AUTH_TOKEN.to_string());
+    let broadcast_tx = Arc::new(tokio::sync::broadcast::channel::<String>(64).0);
+    let settings =
+        Arc::new(serde_json::from_value(test_settings_value()).expect("valid settings fixture"));
+    let registry = freshell_terminal::TerminalRegistry::new();
+
+    let activity_hub =
+        freshell_ws::activity::ActivityHub::new(std::sync::Arc::clone(&broadcast_tx), None);
+    registry.set_activity_observer(activity_hub.registry_observer());
+
+    let state = WsState {
+        pane_ledger: std::sync::Arc::new(freshell_ws::pane_ledger::PaneLedger::disabled()),
+        identity: freshell_ws::identity::TerminalIdentityRegistry::new(),
+        auth_token: Arc::clone(&auth_token),
+        server_instance_id: Arc::new("srv-test".to_string()),
+        boot_id: Arc::new("boot-test".to_string()),
+        settings,
+        broadcast_tx: Arc::clone(&broadcast_tx),
+        fresh_codex: freshell_freshagent::FreshCodexState::new(
+            Arc::clone(&auth_token),
+            Arc::clone(&broadcast_tx),
+            serde_json::json!({ "freshAgent": { "enabled": false } }),
+        ),
+        fresh_claude: freshell_freshagent::FreshClaudeState::new(Arc::clone(&broadcast_tx)),
+        fresh_opencode: freshell_freshagent::FreshOpencodeState::new(
+            freshell_freshagent::FreshAgentState::new(
+                Arc::clone(&auth_token),
+                Arc::clone(&broadcast_tx),
+            ),
+        ),
+        registry: registry.clone(),
+        tabs: freshell_ws::tabs::TabsRegistry::new(),
+        screenshots: freshell_ws::screenshot::ScreenshotBroker::new(Arc::clone(&broadcast_tx)),
+        terminals_revision: Arc::new(std::sync::atomic::AtomicI64::new(0)),
+        sessions_revision: Arc::new(std::sync::atomic::AtomicI64::new(0)),
+        cli_commands: Arc::new(cli_commands),
+        shutdown: Arc::new(tokio::sync::Notify::new()),
+        ping_interval_ms: 30_000,
+        hello_timeout_ms: 5_000,
+        allowed_origins: Arc::new(freshell_ws::origin::default_allowed_origins()),
+        ws_max_payload_bytes: 16 * 1024 * 1024,
+        term09: freshell_ws::backpressure::Term09Config::default(),
+        create_protect: freshell_ws::create_limit::CreateProtectConfig::default(),
+        spawn_gate: std::sync::Arc::new(freshell_ws::spawn_gate::SpawnGate::new(4, 64)),
+        config_fallback: None,
+        amplifier_locator: None,
+        opencode_locator: None,
+        codex_locator: Some(std::sync::Arc::new(
+            freshell_sessions::codex_locator::CodexLocator::new(codex_sessions_root.to_path_buf()),
+        )),
+        activity: Some(activity_hub.clone()),
+        session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+    };
+
+    // Mirrors main.rs's sweep wiring; 150 ms is re-declared here because
+    // main.rs's AMPLIFIER_LOCATOR_SWEEP_INTERVAL is private to the server
+    // binary.
+    freshell_ws::codex_association::spawn_codex_locator_sweep(
+        state.clone(),
+        std::time::Duration::from_millis(150),
+    );
+    let router = freshell_ws::router(state);
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind ephemeral loopback port");
+    let addr = listener.local_addr().expect("local addr");
+    tokio::spawn(async move {
+        let _ = axum::serve(listener, router).await;
+    });
+
+    (format!("ws://{addr}/ws", addr = addr), registry)
+}
+
 /// [`spawn_server`] variant with injectable `terminal.create` protection
 /// knobs (rate limit + spawn gate). Identical `WsState` otherwise; returns
 /// only the ws URL (the create-protection tests never need the registry).

From 7ac12ec1ad89670207f138014ec111f3d60a5c6e Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:14:02 -0700
Subject: [PATCH 50/87] feat(client): pane-reconcile module - request builder,
 verdict folding, cardinality invariant
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds src/lib/pane-reconcile.ts: buildReconcileRequest /
buildReconcileRequestForPanes (terminal-pane walk, >200 cap with
console.error breadcrumb), paneKeyFor, and foldVerdicts with the
cardinality invariant checked FIRST (length + 1:1 ordered paneKey
match; on violation nothing is dispatched and the caller is flagged
to fall back to the legacy census).

Fold mapping: attach -> applyReconcileAttach (serverInstanceId from
the result), respawn/fresh -> resetPaneForReconcileCreate, dead_session
-> ONE batched setDeadSessionAdjudication + per-pane restoreError
breadcrumb, index_warming -> ONE setReconcileWarming, invalid /
provider_unavailable -> per-pane restoreError via a new small
setPaneRestoreError reducer (nothing dispatchable reached
content.restoreError non-destructively before).

Moves App.tsx's collectTerminalPaneTargets walk into the module and
re-exports it so the request builder and App share one walk.

Documents the pinned FOLD-OWNERSHIP RULE in the module doc comment:
correlation is the existing ws.onMessage broadcast subscription; each
requester folds only results whose reconcileId it minted.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 src/App.tsx                                 |  28 +-
 src/lib/pane-reconcile.ts                   | 315 ++++++++++++++++++
 src/store/panesSlice.ts                     |  15 +
 test/unit/client/lib/pane-reconcile.test.ts | 345 ++++++++++++++++++++
 4 files changed, 677 insertions(+), 26 deletions(-)
 create mode 100644 src/lib/pane-reconcile.ts
 create mode 100644 test/unit/client/lib/pane-reconcile.test.ts

diff --git a/src/App.tsx b/src/App.tsx
index 426206796..d7392cf88 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -17,6 +17,7 @@ import {
 } from '@/store/sessionsThunks'
 import { fetchTerminalDirectoryWindow } from '@/store/terminalDirectoryThunks'
 import { createTerminalInvalidationHandler } from '@/lib/terminal-invalidation-handler'
+import { collectTerminalPaneTargets } from '@/lib/pane-reconcile'
 import { getShareAction, ensureShareUrlToken, isRemoteAccessEnabledStatus } from '@/lib/share-utils'
 import { getWsClient } from '@/lib/ws-client'
 import { collectSessionLocatorsFromTabs, getSessionsForHello } from '@/lib/session-utils'
@@ -808,31 +809,6 @@ export default function App() {
         }
       }
 
-      const collectTerminalPaneTargets = (terminalIds: string[]) => {
-        const terminalIdSet = new Set(terminalIds)
-        const layouts = appStore.getState().panes.layouts
-        const targets: Array<{ tabId: string; paneId: string }> = []
-        for (const [tabId, layout] of Object.entries(layouts)) {
-          ;(function walk(node: any) {
-            if (!node) return
-            if (node.type === 'leaf') {
-              if (
-                node.content?.kind === 'terminal' &&
-                node.content.terminalId &&
-                terminalIdSet.has(node.content.terminalId)
-              ) {
-                targets.push({ tabId, paneId: node.id })
-              }
-              return
-            }
-            if (node.type === 'split' && Array.isArray(node.children)) {
-              for (const child of node.children) walk(child)
-            }
-          })(layout)
-        }
-        return targets
-      }
-
       const findPaneById = (layout: any, paneId: string): any | undefined => {
         if (!layout) return undefined
         if (layout.type === 'leaf') return layout.id === paneId ? layout : undefined
@@ -875,7 +851,7 @@ export default function App() {
         queueActiveSessionWindowRefresh: () => queueActiveSessionWindowRefresh() as any,
         fetchTerminalDirectoryWindow: (payload) => fetchTerminalDirectoryWindow(payload) as any,
         handleRecoverableTerminalIds: (terminalIds) => {
-          const targets = collectTerminalPaneTargets(terminalIds)
+          const targets = collectTerminalPaneTargets(appStore.getState().panes.layouts, terminalIds)
           if (targets.length === 0) return
           const removedSet = new Set(terminalIds)
           const currentLiveIds = appStore.getState().connection.liveTerminalIds
diff --git a/src/lib/pane-reconcile.ts b/src/lib/pane-reconcile.ts
new file mode 100644
index 000000000..ef78e0d53
--- /dev/null
+++ b/src/lib/pane-reconcile.ts
@@ -0,0 +1,315 @@
+/**
+ * pane.reconcile client adoption: request builder + verdict folding.
+ *
+ * FOLD-OWNERSHIP RULE (pinned; applies to every consumer):
+ * The correlation mechanism is the EXISTING `ws.onMessage` broadcast
+ * subscription (ws-client) — there is NO separate correlator module.
+ * Each requester (App boot reconcile, TerminalView exhaustion
+ * auto-resolve, warming-banner Retry) folds ONLY results whose
+ * `reconcileId` it minted, silently skipping foreign ones. This is what
+ * prevents double-folds when several requesters are live at once.
+ *
+ * This module provides pure builders and the fold function; consumers
+ * send the request over the socket themselves and enforce ownership.
+ */
+import { nanoid } from 'nanoid'
+import type {
+  PaneReconcileRequest,
+  PaneReconcileResultMessage,
+  ReconcilePane,
+} from '@shared/ws-protocol'
+import { buildRestoreError } from '@shared/session-contract'
+import type { AppDispatch, RootState } from '@/store/store'
+import type { DeadSessionEntry, PaneNode, TerminalPaneContent } from '@/store/paneTypes'
+import {
+  applyReconcileAttach,
+  resetPaneForReconcileCreate,
+  setDeadSessionAdjudication,
+  setPaneReconcileNotice,
+  setPaneRestoreError,
+  setReconcileWarming,
+} from '@/store/panesSlice'
+import { derivePaneTitle } from '@/lib/derivePaneTitle'
+
+/** Protocol cap on request size (mirrors PaneReconcileRequestSchema). */
+const MAX_RECONCILE_PANES = 200
+
+export function paneKeyFor(tabId: string, paneId: string): string {
+  return `${tabId}:${paneId}`
+}
+
+function forEachTerminalPane(
+  layouts: Record<string, PaneNode>,
+  visit: (tabId: string, paneId: string, content: TerminalPaneContent) => void,
+): void {
+  for (const [tabId, layout] of Object.entries(layouts)) {
+    ;(function walk(node: PaneNode | undefined) {
+      if (!node) return
+      if (node.type === 'leaf') {
+        if (node.content?.kind === 'terminal') {
+          visit(tabId, node.id, node.content)
+        }
+        return
+      }
+      if (node.type === 'split' && Array.isArray(node.children)) {
+        for (const child of node.children) walk(child)
+      }
+    })(layout)
+  }
+}
+
+/**
+ * Pane-tree walk shared with App's terminal-invalidation handling:
+ * find the {tabId, paneId} of every terminal pane whose terminalId is
+ * in the given set. (Moved here from App.tsx so the reconcile request
+ * builder and App share ONE walk.)
+ */
+export function collectTerminalPaneTargets(
+  layouts: Record<string, PaneNode>,
+  terminalIds: string[],
+): Array<{ tabId: string; paneId: string }> {
+  const terminalIdSet = new Set(terminalIds)
+  const targets: Array<{ tabId: string; paneId: string }> = []
+  forEachTerminalPane(layouts, (tabId, paneId, content) => {
+    if (content.terminalId && terminalIdSet.has(content.terminalId)) {
+      targets.push({ tabId, paneId })
+    }
+  })
+  return targets
+}
+
+function toReconcilePane(tabId: string, paneId: string, content: TerminalPaneContent): ReconcilePane | null {
+  // Panes without a createRequestId cannot be reconciled — skip.
+  if (!content.createRequestId) return null
+  return {
+    paneKey: paneKeyFor(tabId, paneId),
+    kind: 'terminal',
+    mode: content.mode,
+    createRequestId: content.createRequestId,
+    ...(content.terminalId ? { terminalId: content.terminalId } : {}),
+    ...(content.serverInstanceId ? { serverInstanceId: content.serverInstanceId } : {}),
+    ...(content.sessionRef ? { sessionRef: content.sessionRef } : {}),
+    ...(content.resumeSessionId ? { resumeSessionId: content.resumeSessionId } : {}),
+    ...(content.status ? { status: content.status } : {}),
+  }
+}
+
+function buildRequestFromPanes(panes: ReconcilePane[]): PaneReconcileRequest | null {
+  if (panes.length === 0) return null
+  let capped = panes
+  if (panes.length > MAX_RECONCILE_PANES) {
+    console.error(
+      `pane-reconcile: ${panes.length} terminal panes exceed the protocol cap of ${MAX_RECONCILE_PANES}; sending the first ${MAX_RECONCILE_PANES} only`,
+    )
+    capped = panes.slice(0, MAX_RECONCILE_PANES)
+  }
+  return {
+    type: 'pane.reconcile.request',
+    reconcileId: nanoid(),
+    panes: capped,
+  }
+}
+
+/** Build a reconcile request covering every terminal pane in the store, or null if there are none. */
+export function buildReconcileRequest(state: RootState): PaneReconcileRequest | null {
+  const panes: ReconcilePane[] = []
+  forEachTerminalPane(state.panes.layouts, (tabId, paneId, content) => {
+    const pane = toReconcilePane(tabId, paneId, content)
+    if (pane) panes.push(pane)
+  })
+  return buildRequestFromPanes(panes)
+}
+
+/** Build a reconcile request for specific panes only (e.g. a single exhausted pane), or null if none resolve. */
+export function buildReconcileRequestForPanes(
+  state: RootState,
+  targets: { tabId: string; paneId: string }[],
+): PaneReconcileRequest | null {
+  const wanted = new Set(targets.map((t) => paneKeyFor(t.tabId, t.paneId)))
+  const panes: ReconcilePane[] = []
+  forEachTerminalPane(state.panes.layouts, (tabId, paneId, content) => {
+    if (!wanted.has(paneKeyFor(tabId, paneId))) return
+    const pane = toReconcilePane(tabId, paneId, content)
+    if (pane) panes.push(pane)
+  })
+  return buildRequestFromPanes(panes)
+}
+
+export interface FoldOutcome {
+  attached: number
+  respawned: number
+  fresh: number
+  dead: number
+  warming: number
+  invalid: number
+  cardinalityViolation: boolean
+}
+
+/**
+ * Parse a pane ref back out of OUR OWN paneKey. Safe because the key was
+ * minted by paneKeyFor from nanoid tab/pane ids (which never contain ':'),
+ * and foldVerdicts only reaches here after verifying the server echoed the
+ * request's keys verbatim — we never string-split server input.
+ */
+function paneRefFromOwnKey(paneKey: string): { tabId: string; paneId: string } {
+  const sep = paneKey.indexOf(':')
+  return { tabId: paneKey.slice(0, sep), paneId: paneKey.slice(sep + 1) }
+}
+
+function deadSessionTitle(pane: ReconcilePane): string {
+  return derivePaneTitle({
+    kind: 'terminal',
+    mode: pane.mode as TerminalPaneContent['mode'],
+    createRequestId: pane.createRequestId,
+    status: 'running',
+  })
+}
+
+/**
+ * Fold a pane.reconcile.result into the store, one dispatch per pane
+ * verdict — EXCEPT dead_session adjudication and index_warming, which
+ * are each batched into a single dispatch.
+ *
+ * Cardinality invariant comes FIRST: verdicts must match the request's
+ * panes 1:1 in order. On violation NOTHING is dispatched — the caller
+ * sees `cardinalityViolation: true` and falls back to the legacy census.
+ */
+export function foldVerdicts(
+  dispatch: AppDispatch,
+  request: PaneReconcileRequest,
+  result: PaneReconcileResultMessage,
+): FoldOutcome {
+  const outcome: FoldOutcome = {
+    attached: 0,
+    respawned: 0,
+    fresh: 0,
+    dead: 0,
+    warming: 0,
+    invalid: 0,
+    cardinalityViolation: false,
+  }
+
+  if (result.verdicts.length !== request.panes.length) {
+    outcome.cardinalityViolation = true
+    return outcome
+  }
+  for (let i = 0; i < request.panes.length; i++) {
+    if (result.verdicts[i].paneKey !== request.panes[i].paneKey) {
+      outcome.cardinalityViolation = true
+      return outcome
+    }
+  }
+
+  const deadEntries: DeadSessionEntry[] = []
+  const warmingRefs: Array<{ tabId: string; paneId: string }> = []
+
+  for (let i = 0; i < request.panes.length; i++) {
+    const pane = request.panes[i]
+    const verdict = result.verdicts[i]
+    const { tabId, paneId } = paneRefFromOwnKey(pane.paneKey)
+
+    switch (verdict.verdict) {
+      case 'attach': {
+        // Contract: attach carries the live terminalId. A missing one is a
+        // malformed verdict — the reducer would no-op, so skip it entirely.
+        if (!verdict.terminalId) break
+        dispatch(applyReconcileAttach({
+          tabId,
+          paneId,
+          terminalId: verdict.terminalId,
+          serverInstanceId: result.serverInstanceId,
+          sessionRef: verdict.sessionRef,
+          corrected: verdict.corrected,
+          duplicate: verdict.duplicate ? true : undefined,
+        }))
+        outcome.attached++
+        break
+      }
+      case 'respawn': {
+        dispatch(resetPaneForReconcileCreate({
+          tabId,
+          paneId,
+          intent: 'respawn',
+          sessionRef: verdict.sessionRef,
+          corrected: verdict.corrected,
+        }))
+        outcome.respawned++
+        break
+      }
+      case 'fresh': {
+        dispatch(resetPaneForReconcileCreate({
+          tabId,
+          paneId,
+          intent: 'fresh',
+          reason: verdict.reason,
+        }))
+        outcome.fresh++
+        break
+      }
+      case 'dead_session': {
+        deadEntries.push({
+          tabId,
+          paneId,
+          title: deadSessionTitle(pane),
+          mode: pane.mode,
+          sessionRef: verdict.sessionRef,
+          reason: verdict.reason,
+        })
+        // Loud, non-destructive per-pane breadcrumb: the saved session
+        // artifact is gone. RestoreError reasons are a closed enum, so the
+        // verdict's machine reason travels on the DeadSessionEntry instead.
+        dispatch(setPaneRestoreError({
+          tabId,
+          paneId,
+          restoreError: buildRestoreError('durable_artifact_missing'),
+        }))
+        outcome.dead++
+        break
+      }
+      case 'invalid': {
+        dispatch(setPaneRestoreError({
+          tabId,
+          paneId,
+          restoreError: buildRestoreError('missing_canonical_identity'),
+        }))
+        if (verdict.reason) {
+          // RestoreError's reason enum can't carry the server's machine
+          // code — surface it via the one-shot reconcile notice.
+          dispatch(setPaneReconcileNotice({
+            tabId,
+            paneId,
+            notice: `Reconcile rejected this pane (${verdict.reason}).`,
+          }))
+        }
+        outcome.invalid++
+        break
+      }
+      case 'error': {
+        if (verdict.reason === 'index_warming') {
+          warmingRefs.push({ tabId, paneId })
+          outcome.warming++
+        } else {
+          // provider_unavailable and any other terminal error reason:
+          // per-pane restoreError via the provider-failure rendering path.
+          dispatch(setPaneRestoreError({
+            tabId,
+            paneId,
+            restoreError: buildRestoreError('provider_runtime_failed'),
+          }))
+        }
+        break
+      }
+    }
+  }
+
+  // Council rule 1: ONE batched adjudication list — never N dispatches.
+  if (deadEntries.length > 0) {
+    dispatch(setDeadSessionAdjudication(deadEntries))
+  }
+  // Council rule 5: warming verdicts aggregate into ONE dispatch.
+  if (warmingRefs.length > 0) {
+    dispatch(setReconcileWarming({ count: warmingRefs.length, paneRefs: warmingRefs }))
+  }
+
+  return outcome
+}
diff --git a/src/store/panesSlice.ts b/src/store/panesSlice.ts
index 22d60e6bc..de40040e0 100644
--- a/src/store/panesSlice.ts
+++ b/src/store/panesSlice.ts
@@ -1989,6 +1989,20 @@ export const panesSlice = createSlice({
       state.reconcileWarming = null
     },
 
+    /**
+     * Loud, non-destructive per-pane breadcrumb for reconcile
+     * dead_session/invalid/error verdicts. Sets only restoreError —
+     * never touches identity, handles, or createRequestId.
+     */
+    setPaneRestoreError: (
+      state,
+      action: PayloadAction<{ tabId: string; paneId: string; restoreError: RestoreError }>
+    ) => {
+      const content = findReconcileTerminalContent(state, action.payload.tabId, action.payload.paneId)
+      if (!content) return
+      content.restoreError = action.payload.restoreError
+    },
+
     repairCodexIdentityMismatch: (
       state,
       action: PayloadAction<{
@@ -2073,6 +2087,7 @@ export const {
   clearDeadSessionAdjudication,
   setReconcileWarming,
   clearReconcileWarming,
+  setPaneRestoreError,
   repairCodexIdentityMismatch,
 } = panesSlice.actions
 
diff --git a/test/unit/client/lib/pane-reconcile.test.ts b/test/unit/client/lib/pane-reconcile.test.ts
new file mode 100644
index 000000000..1f7ab63f7
--- /dev/null
+++ b/test/unit/client/lib/pane-reconcile.test.ts
@@ -0,0 +1,345 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+
+// Mock localStorage BEFORE importing slices (persistMiddleware reads it at import time)
+const localStorageMock = (() => {
+  let store: Record<string, string> = {}
+  return {
+    getItem: (key: string) => store[key] || null,
+    setItem: (key: string, value: string) => { store[key] = value },
+    removeItem: (key: string) => { delete store[key] },
+    clear: () => { store = {} },
+  }
+})()
+Object.defineProperty(globalThis, 'localStorage', { value: localStorageMock, writable: true })
+
+import panesReducer, {
+  initLayout,
+  applyReconcileAttach,
+  resetPaneForReconcileCreate,
+  setDeadSessionAdjudication,
+  setReconcileWarming,
+  setPaneRestoreError,
+} from '@/store/panesSlice'
+import type { PanesState } from '@/store/panesSlice'
+import type { TerminalPaneContent, PaneNode } from '@/store/paneTypes'
+import type { AppDispatch, RootState } from '@/store/store'
+import type { PaneVerdict, PaneReconcileRequest, PaneReconcileResultMessage } from '@shared/ws-protocol'
+import {
+  buildReconcileRequest,
+  buildReconcileRequestForPanes,
+  collectTerminalPaneTargets,
+  foldVerdicts,
+  paneKeyFor,
+} from '@/lib/pane-reconcile'
+import type { UnknownAction } from '@reduxjs/toolkit'
+
+function emptyPanesState(): PanesState {
+  return {
+    layouts: {},
+    activePane: {},
+    paneTitles: {},
+    paneTitleSetByUser: {},
+    renameRequestTabId: null,
+    renameRequestPaneId: null,
+    zoomedPane: {},
+    refreshRequestsByPane: {},
+    restoreFallbackAttemptsByPane: {},
+  }
+}
+
+function addTerminalPane(
+  state: PanesState,
+  tabId: string,
+  paneId: string,
+  overrides: Partial<TerminalPaneContent> = {},
+): PanesState {
+  return panesReducer(state, initLayout({
+    tabId,
+    paneId,
+    content: {
+      kind: 'terminal',
+      mode: 'claude',
+      shell: 'system',
+      createRequestId: `cr-${paneId}`,
+      ...overrides,
+    },
+  }))
+}
+
+function asRootState(panes: PanesState): RootState {
+  return { panes } as unknown as RootState
+}
+
+function storeStateWith2TerminalPanes(): RootState {
+  let panes = emptyPanesState()
+  panes = addTerminalPane(panes, 'tab1', 'p1', { terminalId: 't-1', status: 'running' })
+  panes = addTerminalPane(panes, 'tab2', 'p2')
+  return asRootState(panes)
+}
+
+function emptyState(): RootState {
+  return asRootState(emptyPanesState())
+}
+
+type VerdictSpec = [PaneVerdict['verdict'], Partial<PaneVerdict>]
+
+interface Dispatched {
+  actions: UnknownAction[]
+  types: string[]
+  verdicts: PaneVerdict[]
+  countOf: (type: string) => number
+  lastPayloadOf: (type: string) => unknown
+}
+
+function recordingDispatch(): { dispatch: AppDispatch; dispatched: Dispatched } {
+  const actions: UnknownAction[] = []
+  const dispatched: Dispatched = {
+    actions,
+    get types() { return actions.map((a) => a.type) },
+    verdicts: [],
+    countOf: (type) => actions.filter((a) => a.type === type).length,
+    lastPayloadOf: (type) => {
+      const matches = actions.filter((a) => a.type === type)
+      return (matches[matches.length - 1] as { payload?: unknown } | undefined)?.payload
+    },
+  }
+  const dispatch = ((action: UnknownAction) => { actions.push(action); return action }) as unknown as AppDispatch
+  return { dispatch, dispatched }
+}
+
+function foldHarness(specs: VerdictSpec[]) {
+  let panes = emptyPanesState()
+  specs.forEach((_, i) => {
+    panes = addTerminalPane(panes, `tab${i + 1}`, `p${i + 1}`)
+  })
+  const req = buildReconcileRequest(asRootState(panes))
+  if (!req) throw new Error('foldHarness: expected a request')
+  const { dispatch, dispatched } = recordingDispatch()
+  dispatched.verdicts = specs.map(([verdict, extra], i) => ({
+    paneKey: req.panes[i].paneKey,
+    verdict,
+    ...extra,
+  }))
+  return { req, dispatch, dispatched }
+}
+
+function foldHarnessAllDead(n: number) {
+  const specs: VerdictSpec[] = Array.from({ length: n }, (_, i) => (
+    ['dead_session', { sessionRef: { provider: 'claude', sessionId: `gone-${i}` }, reason: 'session_missing' }]
+  ))
+  return foldHarness(specs)
+}
+
+function resultFor(req: PaneReconcileRequest, verdicts: PaneVerdict[]): PaneReconcileResultMessage {
+  return {
+    type: 'pane.reconcile.result',
+    reconcileId: req.reconcileId,
+    bootId: 'boot-1',
+    serverInstanceId: 'srv-1',
+    verdicts,
+  }
+}
+
+function deadResultFor(req: PaneReconcileRequest): PaneReconcileResultMessage {
+  return resultFor(req, req.panes.map((p) => ({
+    paneKey: p.paneKey,
+    verdict: 'dead_session' as const,
+    sessionRef: { provider: 'claude', sessionId: 'gone' },
+    reason: 'session_missing',
+  })))
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('paneKeyFor', () => {
+  it('joins tabId and paneId with a colon', () => {
+    expect(paneKeyFor('tab1', 'p1')).toBe('tab1:p1')
+  })
+})
+
+describe('buildReconcileRequest', () => {
+  it('collects terminal panes with paneKey tab:pane and required createRequestId', () => {
+    const state = storeStateWith2TerminalPanes()
+    const req = buildReconcileRequest(state)!
+    expect(req.type).toBe('pane.reconcile.request')
+    expect(req.reconcileId).toBeTruthy()
+    expect(req.panes).toHaveLength(2)
+    expect(req.panes[0].paneKey).toBe(paneKeyFor('tab1', 'p1'))
+    expect(req.panes[0].createRequestId).toBeTruthy()
+    expect(req.panes[0].kind).toBe('terminal')
+    expect(req.panes[0].terminalId).toBe('t-1')
+    expect(req.panes[1].paneKey).toBe(paneKeyFor('tab2', 'p2'))
+  })
+
+  it('returns null with no terminal panes', () => {
+    expect(buildReconcileRequest(emptyState())).toBeNull()
+  })
+
+  it('caps at 200 panes with a console.error breadcrumb', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    let panes = emptyPanesState()
+    for (let i = 0; i < 201; i++) {
+      panes = addTerminalPane(panes, `tab${i}`, `p${i}`)
+    }
+    const req = buildReconcileRequest(asRootState(panes))!
+    expect(req.panes).toHaveLength(200)
+    expect(errorSpy).toHaveBeenCalled()
+  })
+})
+
+describe('buildReconcileRequestForPanes', () => {
+  it('builds only for the given targets', () => {
+    const state = storeStateWith2TerminalPanes()
+    const req = buildReconcileRequestForPanes(state, [{ tabId: 'tab2', paneId: 'p2' }])!
+    expect(req.panes).toHaveLength(1)
+    expect(req.panes[0].paneKey).toBe(paneKeyFor('tab2', 'p2'))
+  })
+
+  it('returns null when no target resolves to a terminal pane', () => {
+    const state = storeStateWith2TerminalPanes()
+    expect(buildReconcileRequestForPanes(state, [{ tabId: 'nope', paneId: 'nada' }])).toBeNull()
+  })
+})
+
+describe('collectTerminalPaneTargets', () => {
+  it('finds panes whose terminalId is in the given set', () => {
+    const state = storeStateWith2TerminalPanes()
+    const targets = collectTerminalPaneTargets(state.panes.layouts, ['t-1'])
+    expect(targets).toEqual([{ tabId: 'tab1', paneId: 'p1' }])
+  })
+
+  it('returns empty for unknown terminal ids', () => {
+    const state = storeStateWith2TerminalPanes()
+    expect(collectTerminalPaneTargets(state.panes.layouts, ['t-unknown'])).toEqual([])
+  })
+})
+
+describe('foldVerdicts', () => {
+  it('dispatches the right action per verdict', () => {
+    const { req, dispatch, dispatched } = foldHarness([
+      ['attach', { terminalId: 'T1' }],
+      ['respawn', { sessionRef: { provider: 'claude', sessionId: 's' } }],
+      ['fresh', { reason: 'identity_never_observed' }],
+      ['dead_session', { sessionRef: { provider: 'codex', sessionId: 'gone' } }],
+      ['error', { reason: 'index_warming' }],
+    ])
+    const outcome = foldVerdicts(dispatch, req, resultFor(req, dispatched.verdicts))
+    expect(outcome).toMatchObject({ attached: 1, respawned: 1, fresh: 1, dead: 1, warming: 1, cardinalityViolation: false })
+    expect(dispatched.types).toContain(applyReconcileAttach.type)
+    expect(dispatched.types).toContain(resetPaneForReconcileCreate.type)
+    expect(dispatched.types).toContain(setDeadSessionAdjudication.type)
+    expect(dispatched.types).toContain(setReconcileWarming.type)
+  })
+
+  it('attach fold carries the result serverInstanceId and the pane ref parsed from the request', () => {
+    const { req, dispatch, dispatched } = foldHarness([['attach', { terminalId: 'T1', corrected: true }]])
+    foldVerdicts(dispatch, req, resultFor(req, dispatched.verdicts))
+    expect(dispatched.lastPayloadOf(applyReconcileAttach.type)).toMatchObject({
+      tabId: 'tab1',
+      paneId: 'p1',
+      terminalId: 'T1',
+      serverInstanceId: 'srv-1',
+      corrected: true,
+    })
+  })
+
+  it('respawn folds create-with-resume using the server-named sessionRef', () => {
+    const { req, dispatch, dispatched } = foldHarness([
+      ['respawn', { sessionRef: { provider: 'claude', sessionId: 'server-truth' } }],
+    ])
+    foldVerdicts(dispatch, req, resultFor(req, dispatched.verdicts))
+    expect(dispatched.lastPayloadOf(resetPaneForReconcileCreate.type)).toMatchObject({
+      tabId: 'tab1',
+      paneId: 'p1',
+      intent: 'respawn',
+      sessionRef: { provider: 'claude', sessionId: 'server-truth' },
+    })
+  })
+
+  it('dead sessions are batched into ONE setDeadSessionAdjudication dispatch (never N)', () => {
+    const { req, dispatch, dispatched } = foldHarnessAllDead(3)
+    const outcome = foldVerdicts(dispatch, req, deadResultFor(req))
+    expect(outcome.dead).toBe(3)
+    expect(dispatched.countOf(setDeadSessionAdjudication.type)).toBe(1)
+    expect(dispatched.lastPayloadOf(setDeadSessionAdjudication.type)).toHaveLength(3)
+  })
+
+  it('dead sessions ALSO get a loud per-pane restoreError breadcrumb', () => {
+    const { req, dispatch, dispatched } = foldHarnessAllDead(1)
+    foldVerdicts(dispatch, req, deadResultFor(req))
+    expect(dispatched.countOf(setPaneRestoreError.type)).toBe(1)
+    expect(dispatched.lastPayloadOf(setPaneRestoreError.type)).toMatchObject({
+      tabId: 'tab1',
+      paneId: 'p1',
+      restoreError: { code: 'RESTORE_UNAVAILABLE' },
+    })
+  })
+
+  it('warming verdicts aggregate into ONE setReconcileWarming dispatch', () => {
+    const { req, dispatch, dispatched } = foldHarness([
+      ['error', { reason: 'index_warming' }],
+      ['error', { reason: 'index_warming' }],
+    ])
+    const outcome = foldVerdicts(dispatch, req, resultFor(req, dispatched.verdicts))
+    expect(outcome.warming).toBe(2)
+    expect(dispatched.countOf(setReconcileWarming.type)).toBe(1)
+    expect(dispatched.lastPayloadOf(setReconcileWarming.type)).toMatchObject({
+      count: 2,
+      paneRefs: [{ tabId: 'tab1', paneId: 'p1' }, { tabId: 'tab2', paneId: 'p2' }],
+    })
+  })
+
+  it('cardinality violation folds NOTHING and flags the caller', () => {
+    const { req, dispatch, dispatched } = foldHarness([['attach', { terminalId: 'T1' }]])
+    const short = { ...resultFor(req, []), verdicts: [] }
+    const outcome = foldVerdicts(dispatch, req, short)
+    expect(outcome.cardinalityViolation).toBe(true)
+    expect(dispatched.types).toHaveLength(0)
+  })
+
+  it('paneKey mismatch is a cardinality violation too', () => {
+    const { req, dispatch, dispatched } = foldHarness([['attach', { terminalId: 'T1' }]])
+    const mismatched = resultFor(req, [{ paneKey: 'other:pane', verdict: 'attach', terminalId: 'T1' }])
+    const outcome = foldVerdicts(dispatch, req, mismatched)
+    expect(outcome.cardinalityViolation).toBe(true)
+    expect(dispatched.types).toHaveLength(0)
+  })
+
+  it('error{provider_unavailable} becomes a per-pane restoreError, not warming', () => {
+    const { req, dispatch, dispatched } = foldHarness([['error', { reason: 'provider_unavailable' }]])
+    const outcome = foldVerdicts(dispatch, req, resultFor(req, dispatched.verdicts))
+    expect(outcome.warming).toBe(0)
+    // folded via the existing restoreError rendering path
+    expect(dispatched.countOf(setReconcileWarming.type)).toBe(0)
+    expect(dispatched.countOf(setPaneRestoreError.type)).toBe(1)
+  })
+
+  it('invalid becomes a per-pane restoreError and counts as invalid', () => {
+    const { req, dispatch, dispatched } = foldHarness([['invalid', { reason: 'unsupported_kind' }]])
+    const outcome = foldVerdicts(dispatch, req, resultFor(req, dispatched.verdicts))
+    expect(outcome.invalid).toBe(1)
+    expect(dispatched.countOf(setPaneRestoreError.type)).toBe(1)
+  })
+})
+
+describe('setPaneRestoreError reducer', () => {
+  it('sets restoreError on the terminal pane content without touching identity or handles', () => {
+    let panes = emptyPanesState()
+    panes = addTerminalPane(panes, 'tab1', 'p1', { terminalId: 't-1', status: 'running' })
+    const next = panesReducer(panes, setPaneRestoreError({
+      tabId: 'tab1',
+      paneId: 'p1',
+      restoreError: { code: 'RESTORE_UNAVAILABLE', reason: 'durable_artifact_missing' },
+    }))
+    const root = next.layouts['tab1']
+    const leaf = (function find(node: PaneNode): TerminalPaneContent | undefined {
+      if (node.type === 'leaf') return node.content.kind === 'terminal' ? node.content : undefined
+      return find(node.children[0]) ?? find(node.children[1])
+    })(root)
+    expect(leaf?.restoreError).toEqual({ code: 'RESTORE_UNAVAILABLE', reason: 'durable_artifact_missing' })
+    expect(leaf?.terminalId).toBe('t-1')
+    expect(leaf?.createRequestId).toBe('cr-p1')
+  })
+})

From 567f576f42e02a347fc20ffa4e3bdf3f461419f0 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:15:18 -0700
Subject: [PATCH 51/87] feat(client): mount recovery offer panel in App (Lane
 B3 region) (B3/P1.9)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deviations from the task brief (controller-approved):
- The brief's anchor line (~App.tsx:1347) is stale; the SetupWizard JSX now
  renders at ~1757-1769, so the LANE B3 mount uses the semantic anchor
  (adjacent to SetupWizard) at App.tsx:1771-1772. Fenced Lane B1 regions
  (811-898, 900-981, 1002-1090, 1283-1325) untouched.
- Mounting the panel app-wide exposed missing mock exports in the 11 App
  test suites' explicit vi.mock factories: getRecoveryInventory added to
  all 11 '@/lib/api' factories, and getCurrentTabRegistryClientInstanceId
  added to the 6 '@/store/tabRegistrySync' factories. Plain async/arrow
  implementations (not vi.fn().mockResolvedValue) because three suites
  call vi.resetAllMocks() in beforeEach, which wipes vi.fn implementations
  and made the panel's fetch return undefined. Mock factories only; no
  test assertions changed.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 src/App.tsx                                                   | 3 +++
 test/unit/client/components/App.lazy-views.test.tsx           | 2 ++
 test/unit/client/components/App.mobile-landscape.test.tsx     | 2 ++
 test/unit/client/components/App.mobile.test.tsx               | 2 ++
 test/unit/client/components/App.perf-audit-bootstrap.test.tsx | 1 +
 test/unit/client/components/App.restart-signals.test.tsx      | 1 +
 test/unit/client/components/App.sidebar-resize.test.tsx       | 2 ++
 test/unit/client/components/App.swipe-sidebar.test.tsx        | 2 ++
 test/unit/client/components/App.swipe-tabs.test.tsx           | 2 ++
 test/unit/client/components/App.test.tsx                      | 1 +
 test/unit/client/components/App.ws-bootstrap.test.tsx         | 1 +
 test/unit/client/components/App.ws-extensions.test.tsx        | 1 +
 12 files changed, 20 insertions(+)

diff --git a/src/App.tsx b/src/App.tsx
index 426206796..2e437058c 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -51,6 +51,7 @@ import TabsView from '@/components/TabsView'
 import PaneDivider from '@/components/panes/PaneDivider'
 import { AuthRequiredModal } from '@/components/AuthRequiredModal'
 import { SetupWizard } from '@/components/SetupWizard'
+import { RecoveryOfferPanel } from '@/components/RecoveryOfferPanel'
 import { ErrorBoundary } from '@/components/ui/error-boundary'
 import { fetchNetworkStatus } from '@/store/networkSlice'
 import { ContextMenuProvider } from '@/components/context-menu/ContextMenuProvider'
@@ -1767,6 +1768,8 @@ npm run serve`}</pre>
           }}
         />
       )}
+      {/* LANE B3 (recover-my-panes): self-gating recovery offer — see docs/plans/2026-07-26-recover-my-panes.md */}
+      <RecoveryOfferPanel />
       </div>
     </ContextMenuProvider>
   )
diff --git a/test/unit/client/components/App.lazy-views.test.tsx b/test/unit/client/components/App.lazy-views.test.tsx
index 166f644b3..0acb9522a 100644
--- a/test/unit/client/components/App.lazy-views.test.tsx
+++ b/test/unit/client/components/App.lazy-views.test.tsx
@@ -32,6 +32,7 @@ vi.mock('@/lib/ws-client', () => ({
 
 const mockApiGet = vi.fn().mockResolvedValue({})
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => mockApiGet(url),
     patch: vi.fn().mockResolvedValue({}),
@@ -77,6 +78,7 @@ vi.mock('@/hooks/useTheme', () => ({
 
 vi.mock('@/store/tabRegistrySync', () => ({
   startTabRegistrySync: () => () => {},
+  getCurrentTabRegistryClientInstanceId: () => 'test-client-instance',
 }))
 
 function createStore() {
diff --git a/test/unit/client/components/App.mobile-landscape.test.tsx b/test/unit/client/components/App.mobile-landscape.test.tsx
index b5045d9e4..942e70360 100644
--- a/test/unit/client/components/App.mobile-landscape.test.tsx
+++ b/test/unit/client/components/App.mobile-landscape.test.tsx
@@ -33,6 +33,7 @@ vi.mock('@/lib/ws-client', () => ({
 
 const mockApiGet = vi.fn().mockResolvedValue({})
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => mockApiGet(url),
     patch: vi.fn().mockResolvedValue({}),
@@ -73,6 +74,7 @@ vi.mock('@/hooks/useTheme', () => ({
 
 vi.mock('@/store/tabRegistrySync', () => ({
   startTabRegistrySync: () => () => {},
+  getCurrentTabRegistryClientInstanceId: () => 'test-client-instance',
 }))
 
 vi.mock('@use-gesture/react', () => ({
diff --git a/test/unit/client/components/App.mobile.test.tsx b/test/unit/client/components/App.mobile.test.tsx
index 5f9c64e07..bb82f1149 100644
--- a/test/unit/client/components/App.mobile.test.tsx
+++ b/test/unit/client/components/App.mobile.test.tsx
@@ -43,6 +43,7 @@ vi.mock('@/lib/ws-client', () => ({
 const mockApiGet = vi.fn().mockResolvedValue({})
 const mockApiPatch = vi.fn().mockResolvedValue({})
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => mockApiGet(url),
     patch: (...args: unknown[]) => mockApiPatch(...args),
@@ -106,6 +107,7 @@ vi.mock('@/hooks/useTheme', () => ({
 
 vi.mock('@/store/tabRegistrySync', () => ({
   startTabRegistrySync: () => () => {},
+  getCurrentTabRegistryClientInstanceId: () => 'test-client-instance',
 }))
 
 const defaultServerSettings = createDefaultServerSettings({
diff --git a/test/unit/client/components/App.perf-audit-bootstrap.test.tsx b/test/unit/client/components/App.perf-audit-bootstrap.test.tsx
index 32b6866b1..e5b699866 100644
--- a/test/unit/client/components/App.perf-audit-bootstrap.test.tsx
+++ b/test/unit/client/components/App.perf-audit-bootstrap.test.tsx
@@ -37,6 +37,7 @@ vi.mock('@/lib/ws-client', () => ({
 }))
 
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => apiGet(url),
     patch: vi.fn().mockResolvedValue({}),
diff --git a/test/unit/client/components/App.restart-signals.test.tsx b/test/unit/client/components/App.restart-signals.test.tsx
index 27b223223..88c03c23d 100644
--- a/test/unit/client/components/App.restart-signals.test.tsx
+++ b/test/unit/client/components/App.restart-signals.test.tsx
@@ -125,6 +125,7 @@ const fetchSidebarSessionsSnapshot = vi.hoisted(() => vi.fn())
 const getTerminalDirectoryPage = vi.hoisted(() => vi.fn())
 const searchTerminalView = vi.hoisted(() => vi.fn())
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => apiGet(url),
     patch: vi.fn().mockResolvedValue({}),
diff --git a/test/unit/client/components/App.sidebar-resize.test.tsx b/test/unit/client/components/App.sidebar-resize.test.tsx
index 3b6c6d995..ca67517b8 100644
--- a/test/unit/client/components/App.sidebar-resize.test.tsx
+++ b/test/unit/client/components/App.sidebar-resize.test.tsx
@@ -38,6 +38,7 @@ vi.mock('@/lib/ws-client', () => ({
 const mockApiGet = vi.fn().mockResolvedValue({})
 const mockApiPatch = vi.fn().mockResolvedValue({})
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => mockApiGet(url),
     patch: (url: string, data: any) => mockApiPatch(url, data),
@@ -112,6 +113,7 @@ vi.mock('@/hooks/useTheme', () => ({
 
 vi.mock('@/store/tabRegistrySync', () => ({
   startTabRegistrySync: () => () => {},
+  getCurrentTabRegistryClientInstanceId: () => 'test-client-instance',
 }))
 vi.mock('@/components/SetupWizard', () => ({
   SetupWizard: () => <div data-testid="mock-setup-wizard">Setup Wizard</div>,
diff --git a/test/unit/client/components/App.swipe-sidebar.test.tsx b/test/unit/client/components/App.swipe-sidebar.test.tsx
index ff6c6612b..2c63670e6 100644
--- a/test/unit/client/components/App.swipe-sidebar.test.tsx
+++ b/test/unit/client/components/App.swipe-sidebar.test.tsx
@@ -39,6 +39,7 @@ vi.mock('@/lib/ws-client', () => ({
 // Mock the api module
 const mockApiGet = vi.fn().mockResolvedValue({})
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => mockApiGet(url),
     patch: vi.fn().mockResolvedValue({}),
@@ -87,6 +88,7 @@ vi.mock('@/hooks/useTheme', () => ({
 
 vi.mock('@/store/tabRegistrySync', () => ({
   startTabRegistrySync: () => () => {},
+  getCurrentTabRegistryClientInstanceId: () => 'test-client-instance',
 }))
 
 function createTestStore(options?: { sidebarCollapsed?: boolean }) {
diff --git a/test/unit/client/components/App.swipe-tabs.test.tsx b/test/unit/client/components/App.swipe-tabs.test.tsx
index ffbb9bb00..b6e50a2c1 100644
--- a/test/unit/client/components/App.swipe-tabs.test.tsx
+++ b/test/unit/client/components/App.swipe-tabs.test.tsx
@@ -34,6 +34,7 @@ vi.mock('@/lib/ws-client', () => ({
 // Mock the api module
 const mockApiGet = vi.fn().mockResolvedValue({})
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => mockApiGet(url),
     patch: vi.fn().mockResolvedValue({}),
@@ -82,6 +83,7 @@ vi.mock('@/hooks/useTheme', () => ({
 
 vi.mock('@/store/tabRegistrySync', () => ({
   startTabRegistrySync: () => () => {},
+  getCurrentTabRegistryClientInstanceId: () => 'test-client-instance',
 }))
 
 function createTestStore(options?: {
diff --git a/test/unit/client/components/App.test.tsx b/test/unit/client/components/App.test.tsx
index 3b3f2fad2..a3772a7b6 100644
--- a/test/unit/client/components/App.test.tsx
+++ b/test/unit/client/components/App.test.tsx
@@ -74,6 +74,7 @@ vi.mock('@/store/crossTabSync', () => ({
 const mockApiGet = vi.fn().mockResolvedValue({})
 const fetchSidebarSessionsSnapshot = vi.fn()
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => mockApiGet(url),
     patch: vi.fn().mockResolvedValue({}),
diff --git a/test/unit/client/components/App.ws-bootstrap.test.tsx b/test/unit/client/components/App.ws-bootstrap.test.tsx
index 34d290de3..4ce62dba8 100644
--- a/test/unit/client/components/App.ws-bootstrap.test.tsx
+++ b/test/unit/client/components/App.ws-bootstrap.test.tsx
@@ -128,6 +128,7 @@ const fetchSidebarSessionsSnapshot = vi.hoisted(() => vi.fn())
 const getTerminalDirectoryPage = vi.hoisted(() => vi.fn())
 const searchTerminalView = vi.hoisted(() => vi.fn())
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => apiGet(url),
     patch: vi.fn().mockResolvedValue({}),
diff --git a/test/unit/client/components/App.ws-extensions.test.tsx b/test/unit/client/components/App.ws-extensions.test.tsx
index 71e269624..e3ac41a47 100644
--- a/test/unit/client/components/App.ws-extensions.test.tsx
+++ b/test/unit/client/components/App.ws-extensions.test.tsx
@@ -80,6 +80,7 @@ vi.mock('@/lib/ws-client', () => ({
 const apiGet = vi.hoisted(() => vi.fn())
 const fetchSidebarSessionsSnapshot = vi.hoisted(() => vi.fn())
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => apiGet(url),
     patch: vi.fn().mockResolvedValue({}),

From 37fe753af7fb8eb6c89949e0d9328dd8dde020e6 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:21:25 -0700
Subject: [PATCH 52/87] feat(opencode): pending marker at create, binding row
 at ses_* materialization (WS + REST send-keys), refresh on settings change
 (P1.13)

---
 crates/freshell-freshagent/src/lib.rs         | 132 +++++++++++-
 crates/freshell-freshagent/src/opencode_ws.rs | 191 +++++++++++++++++-
 2 files changed, 318 insertions(+), 5 deletions(-)

diff --git a/crates/freshell-freshagent/src/lib.rs b/crates/freshell-freshagent/src/lib.rs
index 9b56cf8d5..ad92cfbfa 100644
--- a/crates/freshell-freshagent/src/lib.rs
+++ b/crates/freshell-freshagent/src/lib.rs
@@ -77,7 +77,8 @@ use freshell_opencode::{
     ServeDeps, ServeError,
 };
 use freshell_protocol::{
-    FreshAgentSessionMaterialized, ServerMessage, SessionLocator, SessionsChanged, UiCommand,
+    FreshAgentEvent, FreshAgentSessionMaterialized, ServerMessage, SessionLocator, SessionsChanged,
+    UiCommand,
 };
 
 /// The opencode fresh-agent `sessionType` (`AGENT_SESSION_TYPES.opencode`, `router.ts:541`).
@@ -254,9 +255,8 @@ impl FreshAgentState {
         let _ = self.identity_sink.set(sink);
     }
 
-    /// The wired identity sink, if any. Used by identity-event tasks
-    /// (the REST send-keys materialization site, Task 7).
-    #[allow(dead_code)] // used by identity-event tasks (Tasks 4-10)
+    /// The wired identity sink, if any. Used by the REST send-keys
+    /// materialization site ([`send_keys`]'s cold-start block).
     fn identity_sink(&self) -> Option<SharedPaneIdentitySink> {
         self.identity_sink.get().cloned()
     }
@@ -1519,6 +1519,46 @@ async fn send_keys(
             entry.durable_id = Some(durable_id.clone());
         }
 
+        // P1.13: binding row at REST materialization (AWAITED BEFORE the materialized
+        // broadcast -- durable-before-answer), resolving the pane's placeholder id.
+        // Without this site, REST-created sessions (the e2e seeding surface) never get
+        // a resume record (V10 A13-N1). Opencode has no sandbox/permission concepts.
+        if let Some(sink) = state.identity_sink() {
+            if let Err(e) = sink
+                .record_binding(identity_sink::FreshAgentBindingUpsert {
+                    provider: PROVIDER.into(),
+                    session_id: durable_id.clone(),
+                    mode: SESSION_TYPE.into(),
+                    create_request_id: None,
+                    resolves_pending: Some(pane.placeholder_id.clone()),
+                    supersedes: None,
+                    settings: identity_sink::FreshAgentSettings {
+                        model: pane.model.clone(),
+                        sandbox: None,
+                        permission_mode: None,
+                        effort: pane.effort.clone(),
+                        cwd: pane.cwd.clone(),
+                    },
+                })
+                .await
+            {
+                tracing::warn!(error = %e, session = %durable_id, "freshagent.opencode.rest_binding_write_failed");
+                // Same LEDGER_WRITE_FAILED frame shape the WS sites emit (top-level
+                // sessionType/provider + user-facing message), via state.broadcast.
+                state.broadcast(&ServerMessage::FreshAgentEvent(FreshAgentEvent {
+                    event: json!({
+                        "type": "freshAgent.error",
+                        "sessionId": durable_id,
+                        "code": "LEDGER_WRITE_FAILED",
+                        "message": "Failed to persist this session's resume record - settings may not survive a server restart.",
+                    }),
+                    provider: PROVIDER.to_string(),
+                    session_id: durable_id.clone(),
+                    session_type: SESSION_TYPE.to_string(),
+                }));
+            }
+        }
+
         let session_ref = SessionLocator {
             provider: PROVIDER.to_string(),
             session_id: durable_id.clone(),
@@ -2388,6 +2428,90 @@ mod tests {
         assert!(matches!(err, OpencodeSnapshotError::NotFound));
     }
 
+    // -- P1.13 Task 7: REST send-keys materialization writes a binding row --
+
+    /// Like `opencode_ws::tests::FakeHttp`: `POST /session` mints `ses_1`; everything
+    /// else (health, prompt, status) answers a benign `{}`.
+    struct CreateCapableHttp;
+    impl ServeHttp for CreateCapableHttp {
+        fn request<'a>(
+            &'a self,
+            req: ServeHttpRequest,
+        ) -> std::pin::Pin<
+            Box<dyn std::future::Future<Output = Result<ServeHttpResponse, String>> + Send + 'a>,
+        > {
+            let is_create = matches!(req.method, freshell_opencode::serve::HttpMethod::Post)
+                && (req.url.ends_with("/session") || req.url.contains("/session?"));
+            let body = if is_create {
+                serde_json::to_vec(&json!({ "id": "ses_1", "directory": null })).unwrap()
+            } else {
+                b"{}".to_vec()
+            };
+            Box::pin(async move { Ok(ServeHttpResponse::new(200, body)) })
+        }
+    }
+
+    /// The REST half of the Task 7 identity-event coverage (V10 A13-N1): a REST-created
+    /// pane (POST /api/tabs seeds model/effort) whose first `send-keys` cold-start
+    /// materializes the durable `ses_*` id must record a binding through the pane
+    /// ledger sink -- without this site, REST-created sessions never get a resume record.
+    #[tokio::test]
+    async fn rest_send_keys_materialization_records_binding() {
+        let st = state();
+        let deps = ServeDeps {
+            spawner: Arc::new(NoopSpawner),
+            http: Arc::new(CreateCapableHttp),
+            ports: Arc::new(FakeAllocator),
+            events: Arc::new(NoopEventSource),
+        };
+        let manager = OpencodeServeManager::new(deps, ServeConfig::default());
+        manager
+            .ensure_started()
+            .await
+            .expect("healthy fake serve starts");
+        st.set_manager_for_test(manager).await;
+
+        let fake = Arc::new(identity_sink::FakeIdentitySink::default());
+        st.set_identity_sink(fake.clone());
+
+        // A REST-created pane carrying model/effort (what POST /api/tabs records).
+        st.panes.lock().expect("panes mutex").insert(
+            "pane-1".to_string(),
+            PaneEntry {
+                placeholder_id: "freshopencode-r1".to_string(),
+                cwd: Some("/w".to_string()),
+                model: Some("big-model".to_string()),
+                effort: Some("high".to_string()),
+                durable_id: None,
+            },
+        );
+
+        // Drive the REST send-keys cold-start materialization. `timeout: 0` bounds the
+        // inline `run_turn` idle-wait (the fake never reports activity); the
+        // materialization + binding write happen BEFORE the turn is driven.
+        let mut headers = HeaderMap::new();
+        headers.insert("x-auth-token", "tok".parse().unwrap());
+        let _resp = send_keys(
+            State(st.clone()),
+            Path("pane-1".to_string()),
+            headers,
+            Json(json!({ "text": "hello", "timeout": 0 })),
+        )
+        .await;
+
+        let bindings = fake.bindings.lock().unwrap();
+        let b = bindings
+            .iter()
+            .find(|b| b.session_id == "ses_1")
+            .expect("binding recorded at REST send-keys materialization");
+        assert_eq!(b.provider, "opencode");
+        assert_eq!(b.mode, "freshopencode");
+        assert_eq!(b.resolves_pending.as_deref(), Some("freshopencode-r1"));
+        assert_eq!(b.settings.model.as_deref(), Some("big-model"));
+        assert_eq!(b.settings.effort.as_deref(), Some("high"));
+        assert_eq!(b.settings.cwd.as_deref(), Some("/w"));
+    }
+
     // -- Batch D PR-6: rich transcript items for the opencode snapshot endpoint --
 
     #[test]
diff --git a/crates/freshell-freshagent/src/opencode_ws.rs b/crates/freshell-freshagent/src/opencode_ws.rs
index b3acfb6fc..4e060df46 100644
--- a/crates/freshell-freshagent/src/opencode_ws.rs
+++ b/crates/freshell-freshagent/src/opencode_ws.rs
@@ -206,11 +206,31 @@ impl FreshOpencodeState {
     }
 
     /// The wired identity sink, if any.
-    #[allow(dead_code)] // used by identity-event tasks (Tasks 4-10)
     fn identity_sink(&self) -> Option<SharedPaneIdentitySink> {
         self.identity_sink.get().cloned()
     }
 
+    /// Broadcast a `freshAgent.error` alarm/degradation frame (Task 8 consumes this
+    /// too). Same envelope contract as codex.rs's helper (verified against
+    /// `fresh-agent-ws.ts:182-193`): `{ "type": "freshAgent.event", "sessionId",
+    /// "sessionType", "provider", "event": { "type": "freshAgent.error", "code",
+    /// "message" } }` -- built on the SAME [`ServerMessage::FreshAgentEvent`] envelope
+    /// [`lost_session_frame`] uses, so it is byte-compatible with the frozen client's
+    /// banner path: top-level `sessionType`/`provider` are REQUIRED (locator
+    /// resolution) and `message` is user-facing (the banner shows the message, never
+    /// the code).
+    fn emit_fresh_agent_error(&self, session_id: &str, code: &str, message: &str) {
+        self.broadcast(&event_frame(
+            session_id,
+            json!({
+                "type": "freshAgent.error",
+                "sessionId": session_id,
+                "code": code,
+                "message": message,
+            }),
+        ));
+    }
+
     fn broadcast(&self, msg: &ServerMessage) {
         self.fresh_agent.broadcast(msg);
     }
@@ -282,6 +302,23 @@ impl FreshOpencodeState {
             )
             .await;
 
+        // P1.13: pending marker (AWAITED before the created broadcast --
+        // durable-before-answer). A failed write is surfaced user-visibly, never
+        // silently dropped, and never blocks the create.
+        if let Some(sink) = self.identity_sink() {
+            if let Err(e) = sink
+                .record_pending(&placeholder, SESSION_TYPE, msg.cwd.as_deref())
+                .await
+            {
+                tracing::warn!(error = %e, placeholder = %placeholder, "freshagent.opencode.pending_write_failed");
+                self.emit_fresh_agent_error(
+                    &placeholder,
+                    "LEDGER_WRITE_FAILED",
+                    "Failed to persist this pane's identity marker - identity may not survive a crash.",
+                );
+            }
+        }
+
         self.broadcast(&ServerMessage::FreshAgentCreated(FreshAgentCreated {
             provider: PROVIDER.to_string(),
             request_id,
@@ -388,6 +425,37 @@ impl FreshOpencodeState {
                 .await
                 .insert(durable_id.clone(), session_arc.clone());
 
+            // P1.13: binding row at materialization (AWAITED BEFORE the materialized
+            // broadcast -- durable-before-answer), resolving the create's pending
+            // marker. Opencode has no sandbox/permission concepts -- always `None`.
+            if let Some(sink) = self.identity_sink() {
+                if let Err(e) = sink
+                    .record_binding(crate::identity_sink::FreshAgentBindingUpsert {
+                        provider: PROVIDER.into(),
+                        session_id: durable_id.clone(),
+                        mode: SESSION_TYPE.into(),
+                        create_request_id: request_id.clone(),
+                        resolves_pending: Some(session.placeholder_id.clone()),
+                        supersedes: None,
+                        settings: crate::identity_sink::FreshAgentSettings {
+                            model: session.model.clone(),
+                            sandbox: None,
+                            permission_mode: None,
+                            effort: session.effort.clone(),
+                            cwd: session.cwd.clone(),
+                        },
+                    })
+                    .await
+                {
+                    tracing::warn!(error = %e, session = %durable_id, "freshagent.opencode.binding_write_failed");
+                    self.emit_fresh_agent_error(
+                        &durable_id,
+                        "LEDGER_WRITE_FAILED",
+                        "Failed to persist this session's resume record - settings may not survive a server restart.",
+                    );
+                }
+            }
+
             // `freshAgent.session.materialized` (ws-handler.ts:3477-3484): placeholder ->
             // durable, emitted EXACTLY ONCE (a later send never re-enters this branch).
             self.broadcast(&ServerMessage::FreshAgentSessionMaterialized(
@@ -416,6 +484,40 @@ impl FreshOpencodeState {
 
         session.model = model.clone();
         session.effort = effort.clone();
+
+        // P1.13: settings-change refresh -- once durable, every send's committed
+        // model/effort re-snapshot the binding row (AWAITED BEFORE send.accepted --
+        // durable-before-answer). No pending resolution or supersession here.
+        if acked_session_id.starts_with("ses_") {
+            if let Some(sink) = self.identity_sink() {
+                if let Err(e) = sink
+                    .record_binding(crate::identity_sink::FreshAgentBindingUpsert {
+                        provider: PROVIDER.into(),
+                        session_id: acked_session_id.clone(),
+                        mode: SESSION_TYPE.into(),
+                        create_request_id: None,
+                        resolves_pending: None,
+                        supersedes: None,
+                        settings: crate::identity_sink::FreshAgentSettings {
+                            model: session.model.clone(),
+                            sandbox: None,
+                            permission_mode: None,
+                            effort: session.effort.clone(),
+                            cwd: session.cwd.clone(),
+                        },
+                    })
+                    .await
+                {
+                    tracing::warn!(error = %e, session = %acked_session_id, "freshagent.opencode.binding_write_failed");
+                    self.emit_fresh_agent_error(
+                        &acked_session_id,
+                        "LEDGER_WRITE_FAILED",
+                        "Failed to persist this session's resume record - settings may not survive a server restart.",
+                    );
+                }
+            }
+        }
+
         let real_id = acked_session_id.clone();
         let route = session.cwd.clone();
         let text = msg.text.clone();
@@ -1807,6 +1909,93 @@ mod tests {
             .contains("SESSION_NOT_FOUND"));
     }
 
+    // ── P1.13: identity-sink writes (pending at create, binding at materialization,
+    // refresh on settings change) ──────────────────────────────────────────
+
+    #[tokio::test]
+    async fn materialization_resolves_pending_into_binding_with_settings() {
+        // Harness: same FakeHttp setup the existing materialization test uses.
+        let (state, _killed) = state().await;
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        state.set_identity_sink(fake.clone());
+
+        // Create with settings, then first send (materializes ses_*):
+        // freshAgent.create { requestId: "r1", sessionType: "freshopencode",
+        //                     cwd: "/w", model: "big-model", effort: "high" }
+        let mut create = create_msg("r1");
+        create.cwd = Some("/w".to_string());
+        create.model = Some("big-model".to_string());
+        create.effort = Some("high".to_string());
+        state.handle_create(create).await;
+        state
+            .handle_send(send_msg("freshopencode-r1", "hello"))
+            .await;
+
+        // Pending was recorded at create under the placeholder:
+        let pendings = fake.pendings.lock().unwrap();
+        assert!(pendings
+            .iter()
+            .any(|(id, mode, _)| id.starts_with("freshopencode-") && mode == "freshopencode"));
+        drop(pendings);
+
+        // Binding recorded at materialization, resolving the pending:
+        let bindings = fake.bindings.lock().unwrap();
+        let b = bindings
+            .iter()
+            .find(|b| b.session_id.starts_with("ses_"))
+            .expect("binding at materialization");
+        assert_eq!(b.provider, "opencode");
+        assert_eq!(b.settings.model.as_deref(), Some("big-model"));
+        assert_eq!(b.settings.effort.as_deref(), Some("high"));
+        assert!(
+            b.settings.cwd.is_some(),
+            "cwd captured (upgraded from created.directory)"
+        );
+        assert!(b
+            .resolves_pending
+            .as_deref()
+            .unwrap_or("")
+            .starts_with("freshopencode-"));
+    }
+
+    #[tokio::test]
+    async fn send_with_changed_settings_refreshes_the_binding() {
+        // Same harness; after materialization, send again with
+        // settings: { model: "small-model", effort: "low" } (FreshAgentSendSettings,
+        // consumed per-turn by handle_send's normalize block).
+        let (state, _killed) = state().await;
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        state.set_identity_sink(fake.clone());
+
+        let mut create = create_msg("r2");
+        create.cwd = Some("/w".to_string());
+        create.model = Some("big-model".to_string());
+        create.effort = Some("high".to_string());
+        state.handle_create(create).await;
+        let placeholder = "freshopencode-r2";
+        state.handle_send(send_msg(placeholder, "first")).await;
+
+        let mut second = send_msg(placeholder, "second");
+        second.settings = Some(freshell_protocol::FreshAgentSendSettings {
+            cwd: None,
+            effort: Some("low".to_string()),
+            model: Some("small-model".to_string()),
+            permission_mode: None,
+            sandbox: None,
+        });
+        state.handle_send(second).await;
+
+        // Assert the LAST recorded binding for the ses_* id carries the new values:
+        let bindings = fake.bindings.lock().unwrap();
+        let b = bindings
+            .iter()
+            .rev()
+            .find(|b| b.session_id.starts_with("ses_"))
+            .unwrap();
+        assert_eq!(b.settings.model.as_deref(), Some("small-model"));
+        assert_eq!(b.settings.effort.as_deref(), Some("low"));
+    }
+
     // ── PR-3: serve-stream bridge (status / turn.complete gating) ─────────
 
     /// Build a [`FreshOpencodeState`] on top of [`state_with_status_poll`], returning it

From 63b6b7974be6277976a4e717c9ef4466b502085c Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:24:10 -0700
Subject: [PATCH 53/87] feat(client): advertise paneReconcileV1, surface ready
 capabilities, gate blind create replay
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- HelloSchema capabilities gains paneReconcileV1: z.literal(true).optional()
  (A20 corollary: non-strict Zod strips unknown keys, so the schema key is
  required for the capability to survive parsing; legacy TS server ignores it)
- Client hello advertises paneReconcileV1: true
- ready.capabilities captured per-connection BEFORE the replay block;
  getServerCapabilities() returns {} until acked on the CURRENT socket and
  resets on disconnect so a downgraded server is honored
- Blind inFlightCreates replay on reconnect is skipped when paneReconcileV1
  was acked (verdicts, not resends, decide); preReadyCreateQueue flush is
  unchanged (new user-initiated creates)

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 shared/ws-protocol.ts                         |   3 +
 src/lib/ws-client.ts                          |  27 +++-
 .../client/lib/ws-client.reconcile.test.ts    | 151 ++++++++++++++++++
 test/unit/client/lib/ws-client.test.ts        |   1 +
 4 files changed, 179 insertions(+), 3 deletions(-)
 create mode 100644 test/unit/client/lib/ws-client.reconcile.test.ts

diff --git a/shared/ws-protocol.ts b/shared/ws-protocol.ts
index f7470f61c..e982c2961 100644
--- a/shared/ws-protocol.ts
+++ b/shared/ws-protocol.ts
@@ -272,6 +272,9 @@ export const HelloSchema = z.object({
   capabilities: z.object({
     uiScreenshotV1: z.boolean().optional(),
     terminalOutputBatchV1: z.boolean().optional(),
+    // REQUIRED here (not just in the sent object): Zod non-strict objects silently
+    // STRIP unknown keys, so without this the capability would silently no-op.
+    paneReconcileV1: z.literal(true).optional(),
   }).optional(),
   client: z.object({
     mobile: z.boolean().optional(),
diff --git a/src/lib/ws-client.ts b/src/lib/ws-client.ts
index 920481de5..0a4f5c237 100644
--- a/src/lib/ws-client.ts
+++ b/src/lib/ws-client.ts
@@ -7,7 +7,7 @@ import {
 import { getAuthToken } from '@/lib/auth'
 import { sanitizeSessionLocators } from '@/lib/session-utils'
 import { WS_PROTOCOL_VERSION } from '@shared/ws-version'
-import type { ServerMessage, SessionLocator } from '@shared/ws-protocol'
+import type { ReadyCapabilities, ServerMessage, SessionLocator } from '@shared/ws-protocol'
 import { createLogger } from '@/lib/client-logger'
 
 const log = createLogger('WsClient')
@@ -127,6 +127,9 @@ export class WsClient {
   private reconnectEpoch = 0
   private inFlightCreates = new Map<string, InFlightCreate>()
   private preReadyCreateQueue = new Map<string, unknown>()
+  // Per-connection: {} until a ready with capabilities arrives on the CURRENT
+  // socket; reset on disconnect so a downgraded server is honored.
+  private serverCapabilities: NonNullable<ReadyCapabilities> = {}
 
   constructor(private url: string) {}
 
@@ -150,6 +153,9 @@ export class WsClient {
       this._serverInstanceId = typeof msg.serverInstanceId === 'string' && msg.serverInstanceId.trim()
         ? msg.serverInstanceId
         : undefined
+      // Capture BEFORE the replay block below: the CURRENT socket's ack decides
+      // whether the blind in-flight create replay runs.
+      this.serverCapabilities = msg.capabilities ?? {}
       this.clearReadyTimeout()
       const isReconnect = this.wasConnectedOnce
       this.wasConnectedOnce = true
@@ -192,7 +198,10 @@ export class WsClient {
         this.sendNow(next)
       }
 
-      if (isReconnect) {
+      // When paneReconcileV1 was acked on THIS socket's ready, verdicts (not blind
+      // resends) decide the fate of in-flight creates. The preReadyCreateQueue
+      // flush above is unchanged: those are new user-initiated creates.
+      if (isReconnect && !this.serverCapabilities.paneReconcileV1) {
         for (const [requestId, entry] of this.inFlightCreates.entries()) {
           if (entry.lastResendEpoch === this.reconnectEpoch) continue
           if (createRequestIdsFlushed.has(requestId)) {
@@ -280,6 +289,14 @@ export class WsClient {
     return this._serverInstanceId
   }
 
+  /**
+   * Capabilities acked by the server on the CURRENT socket's ready.
+   * Returns {} until a ready with capabilities arrives; reset on disconnect.
+   */
+  getServerCapabilities(): NonNullable<ReadyCapabilities> {
+    return this.serverCapabilities
+  }
+
   connect(): Promise<void> {
     // StrictMode / double-mount safe: callers can call connect() multiple times and should
     // receive the same in-flight promise until the socket is "ready".
@@ -340,7 +357,7 @@ export class WsClient {
           type: 'hello',
           token,
           protocolVersion: WS_PROTOCOL_VERSION,
-          capabilities: { uiScreenshotV1: true, terminalOutputBatchV1: true },
+          capabilities: { uiScreenshotV1: true, terminalOutputBatchV1: true, paneReconcileV1: true },
           ...helloExtensions,
         })
       }
@@ -381,6 +398,9 @@ export class WsClient {
         const closedBeforeReady = !wasReady
         this._state = 'disconnected'
         this.ws = null
+        // Capabilities are per-connection: reset so a downgraded server (next
+        // ready without the ack) is honored.
+        this.serverCapabilities = {}
         this.disconnectHandlers.forEach((handler) => handler())
 
         // Close codes:
@@ -515,6 +535,7 @@ export class WsClient {
     this.pendingMessages = []
     this.inFlightCreates.clear()
     this.preReadyCreateQueue.clear()
+    this.serverCapabilities = {}
     this._serverInstanceId = undefined
     this.connectPromise = null
     this.reconnectAttempts = 0
diff --git a/test/unit/client/lib/ws-client.reconcile.test.ts b/test/unit/client/lib/ws-client.reconcile.test.ts
new file mode 100644
index 000000000..8567ea953
--- /dev/null
+++ b/test/unit/client/lib/ws-client.reconcile.test.ts
@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { WsClient, getWsClient, resetWsClientForTests } from '../../../../src/lib/ws-client'
+
+class MockWebSocket {
+  static OPEN = 1
+  static instances: MockWebSocket[] = []
+
+  readyState = MockWebSocket.OPEN
+  onopen: null | (() => void) = null
+  onmessage: null | ((ev: { data: string }) => void) = null
+  onclose: null | ((ev: { code: number; reason: string }) => void) = null
+  onerror: null | (() => void) = null
+  sent: string[] = []
+
+  constructor(_url: string) {
+    MockWebSocket.instances.push(this)
+  }
+
+  send(data: any) {
+    this.sent.push(String(data))
+  }
+
+  close() {
+    this.onclose?.({ code: 1000, reason: '' })
+  }
+
+  _open() {
+    this.onopen?.()
+  }
+
+  _message(obj: any) {
+    this.onmessage?.({ data: JSON.stringify(obj) })
+  }
+
+  _close(code: number, reason = '') {
+    this.onclose?.({ code, reason })
+  }
+}
+
+async function connectAndReady(c: WsClient, ready: Record<string, unknown> = {}): Promise<MockWebSocket> {
+  const p = c.connect()
+  const instance = MockWebSocket.instances[MockWebSocket.instances.length - 1]
+  instance._open()
+  instance._message({ type: 'ready', ...ready })
+  await p
+  return instance
+}
+
+function framesOf(instance: MockWebSocket): any[] {
+  return instance.sent.map((x) => JSON.parse(x))
+}
+
+describe('WsClient pane-reconcile capability', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    MockWebSocket.instances = []
+    // @ts-expect-error - test override
+    globalThis.WebSocket = MockWebSocket
+    localStorage.setItem('freshell.auth-token', 't')
+
+    // Some Vitest environments provide a minimal window without timer fns.
+    ;(window as any).setTimeout = globalThis.setTimeout
+    ;(window as any).clearTimeout = globalThis.clearTimeout
+  })
+
+  afterEach(() => {
+    resetWsClientForTests()
+    vi.clearAllTimers()
+    vi.useRealTimers()
+  })
+
+  it('hello advertises paneReconcileV1', async () => {
+    const c = new WsClient('ws://example/ws')
+    const p = c.connect()
+    expect(MockWebSocket.instances).toHaveLength(1)
+    MockWebSocket.instances[0]._open()
+
+    const hello = JSON.parse(MockWebSocket.instances[0].sent[0])
+    expect(hello.type).toBe('hello')
+    expect(hello.capabilities).toMatchObject({
+      uiScreenshotV1: true,
+      terminalOutputBatchV1: true,
+      paneReconcileV1: true,
+    })
+
+    MockWebSocket.instances[0]._message({ type: 'ready' })
+    await p
+  })
+
+  it('surfaces ready.capabilities and resets them on disconnect', async () => {
+    const client = getWsClient()
+    expect(client.getServerCapabilities()).toEqual({})
+
+    await connectAndReady(client, { capabilities: { paneReconcileV1: true } })
+    expect(client.getServerCapabilities().paneReconcileV1).toBe(true)
+
+    MockWebSocket.instances[0]._close(1006, 'drop')
+    expect(client.getServerCapabilities().paneReconcileV1).toBeUndefined()
+    expect(client.getServerCapabilities()).toEqual({})
+  })
+
+  it('suppresses the in-flight create replay when the capability is acked', async () => {
+    const c = new WsClient('ws://example/ws')
+    c.send({ type: 'terminal.create', requestId: 'cr-1', mode: 'shell' } as any)
+
+    await connectAndReady(c, { capabilities: { paneReconcileV1: true } })
+    MockWebSocket.instances[0]._close(1006, 'drop-after-create')
+
+    const reconnectInstance = await connectAndReady(c, { capabilities: { paneReconcileV1: true } })
+    const creates = framesOf(reconnectInstance).filter((f) => f.type === 'terminal.create')
+    expect(creates).toHaveLength(0)
+  })
+
+  it('keeps the legacy replay when the server does not ack (old server)', async () => {
+    const c = new WsClient('ws://example/ws')
+    c.send({ type: 'terminal.create', requestId: 'cr-1', mode: 'shell' } as any)
+
+    await connectAndReady(c, { /* no capabilities */ })
+    MockWebSocket.instances[0]._close(1006, 'drop-after-create')
+
+    const reconnectInstance = await connectAndReady(c, { /* no capabilities */ })
+    const creates = framesOf(reconnectInstance).filter((f) => f.type === 'terminal.create')
+    expect(creates).toHaveLength(1)
+  })
+
+  it('honors a downgraded server: capability acked on a previous socket does not suppress replay', async () => {
+    const c = new WsClient('ws://example/ws')
+    c.send({ type: 'terminal.create', requestId: 'cr-1', mode: 'shell' } as any)
+
+    // First connection acks the capability.
+    await connectAndReady(c, { capabilities: { paneReconcileV1: true } })
+    MockWebSocket.instances[0]._close(1006, 'drop-after-create')
+
+    // Downgraded server: reconnect ready has no capabilities. Legacy replay must fire.
+    const reconnectInstance = await connectAndReady(c, { /* no capabilities */ })
+    const creates = framesOf(reconnectInstance).filter((f) => f.type === 'terminal.create')
+    expect(creates).toHaveLength(1)
+  })
+
+  it('flushes the pre-ready create queue even when the capability is acked', async () => {
+    const c = new WsClient('ws://example/ws')
+    // Queued while offline: this is a NEW user-initiated create, not a replay.
+    c.send({ type: 'terminal.create', requestId: 'cr-new', mode: 'shell' } as any)
+
+    const instance = await connectAndReady(c, { capabilities: { paneReconcileV1: true } })
+    const creates = framesOf(instance).filter((f) => f.type === 'terminal.create')
+    expect(creates).toEqual([
+      expect.objectContaining({ type: 'terminal.create', requestId: 'cr-new' }),
+    ])
+  })
+})
diff --git a/test/unit/client/lib/ws-client.test.ts b/test/unit/client/lib/ws-client.test.ts
index b573b1b94..0ccb511a1 100644
--- a/test/unit/client/lib/ws-client.test.ts
+++ b/test/unit/client/lib/ws-client.test.ts
@@ -91,6 +91,7 @@ describe('WsClient.connect', () => {
     expect(hello.capabilities).toEqual({
       uiScreenshotV1: true,
       terminalOutputBatchV1: true,
+      paneReconcileV1: true,
     })
 
     MockWebSocket.instances[0]._message({ type: 'ready' })

From 4767b7ec8e86fd8afff4386ee7560b70e020de3a Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:28:16 -0700
Subject: [PATCH 54/87] feat(ws)!: retire terminal.codex.candidate.persisted
 writer - accept-and-ignore with debug log
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One writer per codex identity fact (campaign §2.3.2): the server-side
rollout locator is authoritative. The protocol variant stays for
wire-compat with the frozen client; the write path, its four guards,
and both candidate integration tests are deleted (superseded by
codex_candidate_inert.rs and codex_locator_activity.rs).
---
 crates/freshell-ws/src/codex_candidate.rs     | 360 -----------------
 crates/freshell-ws/src/codex_identity.rs      |  10 +-
 crates/freshell-ws/src/codex_reconcile.rs     |   6 +-
 crates/freshell-ws/src/invariants.rs          |  11 +
 crates/freshell-ws/src/lib.rs                 |   1 -
 crates/freshell-ws/src/terminal.rs            |  18 +-
 .../tests/codex_candidate_activity.rs         | 197 ---------
 .../tests/codex_candidate_inert.rs            | 221 ++++++++++
 .../tests/codex_candidate_persisted.rs        | 381 ------------------
 .../tests/codex_locator_activity.rs           |   2 +-
 10 files changed, 253 insertions(+), 954 deletions(-)
 delete mode 100644 crates/freshell-ws/src/codex_candidate.rs
 delete mode 100644 crates/freshell-ws/tests/codex_candidate_activity.rs
 create mode 100644 crates/freshell-ws/tests/codex_candidate_inert.rs
 delete mode 100644 crates/freshell-ws/tests/codex_candidate_persisted.rs

diff --git a/crates/freshell-ws/src/codex_candidate.rs b/crates/freshell-ws/src/codex_candidate.rs
deleted file mode 100644
index 0ae13cb38..000000000
--- a/crates/freshell-ws/src/codex_candidate.rs
+++ /dev/null
@@ -1,360 +0,0 @@
-//! P0.3 (campaign plan §2.3.1): server-side capture of a codex terminal's
-//! session identity from the client's `terminal.codex.candidate.persisted`
-//! frame -- guarded so identity never becomes client-writable.
-//!
-//! Four guards; a candidate failing ANY check is logged at WARN and ignored
-//! (never adopted, and nothing is sent back -- legacy parity with
-//! `server/ws-handler.ts:2951-2963`):
-//!   1. the terminalId exists in the registry
-//!   2. that terminal is codex-mode
-//!   3. binding uniqueness, in two halves: 3a -- the terminal is not already
-//!      bound to a DIFFERENT thread id (stale replay), enforced HERE; and
-//!      3b -- the claimed thread id is not already bound to a DIFFERENT
-//!      terminal, live OR retired (cross-pane hijack, including replaying a
-//!      DEAD pane's candidate onto a fresh pane), enforced INSIDE
-//!      `adopt_codex_identity` (codex_identity.rs), the shared adoption
-//!      tail, not by this handler
-//!   4. disk truth: the rolloutPath canonicalizes under the codex sessions
-//!      root and its FIRST JSONL record is a `session_meta` whose
-//!      `payload.id` is the claimed thread id (bounded 1MB read; legacy
-//!      parity `server/coding-cli/codex-app-server/durability-proof.ts:88-102`)
-
-use std::io::{BufRead, Read};
-use std::path::Path;
-
-use freshell_protocol::TerminalCodexCandidatePersisted;
-
-use crate::codex_identity::{adopt_codex_identity, codex_sessions_root, CodexAdoption};
-use crate::WsState;
-
-/// Codex thread ids are bare hyphenated UUIDs. Cheap shape check so an empty
-/// or junk id can never substring-match everything in the disk guard.
-pub(crate) fn is_uuid_shaped(s: &str) -> bool {
-    s.len() == 36
-        && s.chars().enumerate().all(|(i, c)| match i {
-            8 | 13 | 18 | 23 => c == '-',
-            _ => c.is_ascii_hexdigit(),
-        })
-}
-
-/// Upper bound on the first-line read below. Legacy parity:
-/// `MAX_FIRST_RECORD_BYTES` in `durability-proof.ts`. Real first lines
-/// observed <= 22.4KB (V5 sampling); 1MB is generous headroom while capping
-/// what a 152MB adversarial rollout can cost the sync dispatch loop.
-const MAX_FIRST_LINE_BYTES: u64 = 1024 * 1024;
-
-/// Guard 4 (disk truth). Client-supplied paths are NEVER trusted raw:
-/// `fs::canonicalize` both sides (stats the file and resolves `..` and
-/// symlinks, so traversal and symlink escapes fail containment), require the
-/// rollout to live under the sessions root, then prove OWNERSHIP with a
-/// bounded read of only the FIRST line, parsed as JSON: it must be a
-/// `session_meta` record whose `payload.id` equals the claimed thread id
-/// (legacy parity: `durability-proof.ts:88-102`).
-///
-/// `payload.id` EXACTLY -- NOT `payload.session_id`, which is fork/resume
-/// LINEAGE and matches a FOREIGN session in 54/144 real rollouts (V5); and
-/// never a substring match on filename or contents, which the same lineage
-/// data makes spoofable (40% of sampled rollouts contain foreign uuids).
-pub(crate) fn verify_rollout_path(
-    rollout_path: &str,
-    sessions_root: &Path,
-    thread_id: &str,
-) -> Result<(), &'static str> {
-    let root = std::fs::canonicalize(sessions_root).map_err(|_| "sessions_root_missing")?;
-    let rollout = std::fs::canonicalize(rollout_path).map_err(|_| "rollout_missing")?;
-    if !rollout.starts_with(&root) {
-        return Err("rollout_outside_sessions_root");
-    }
-    if !rollout.is_file() {
-        return Err("rollout_not_a_file");
-    }
-    // Bounded first-line read: never `read_to_string` a client-named file
-    // (real rollouts reach 152MB, p99=28MB -- an uncapped read in the sync
-    // dispatch loop is an adversarial hazard).
-    let file = std::fs::File::open(&rollout).map_err(|_| "rollout_unreadable")?;
-    let mut first_line: Vec<u8> = Vec::new();
-    let mut limited = std::io::BufReader::new(file).take(MAX_FIRST_LINE_BYTES);
-    limited
-        .read_until(b'\n', &mut first_line)
-        .map_err(|_| "rollout_unreadable")?;
-    if first_line.len() as u64 >= MAX_FIRST_LINE_BYTES && !first_line.ends_with(b"\n") {
-        return Err("rollout_first_line_too_large");
-    }
-    let record: serde_json::Value =
-        serde_json::from_slice(&first_line).map_err(|_| "rollout_first_record_not_json")?;
-    if record.get("type").and_then(|v| v.as_str()) != Some("session_meta") {
-        return Err("rollout_first_record_not_session_meta");
-    }
-    match record.pointer("/payload/id").and_then(|v| v.as_str()) {
-        Some(id) if id == thread_id => Ok(()),
-        _ => Err("thread_id_mismatch"),
-    }
-}
-
-/// Handle one `terminal.codex.candidate.persisted` frame. No reply frame on
-/// any path; rejects are WARN logs, accepts bind BOTH identity homes and
-/// broadcast (mirrors `opencode_association.rs`'s resolve path).
-pub(crate) async fn handle_codex_candidate_persisted(
-    state: &WsState,
-    msg: TerminalCodexCandidatePersisted,
-) {
-    let thread_id = msg.candidate_thread_id.as_str();
-    if !is_uuid_shaped(thread_id) {
-        tracing::warn!(
-            terminal_id = %msg.terminal_id,
-            candidate_thread_id = %thread_id,
-            "codex_candidate_rejected: invalid_thread_id"
-        );
-        return;
-    }
-    // Guard 1: the terminal exists.
-    let Some(row) = state.registry.probe(&msg.terminal_id) else {
-        tracing::warn!(
-            terminal_id = %msg.terminal_id,
-            candidate_thread_id = %thread_id,
-            "codex_candidate_rejected: terminal_missing"
-        );
-        return;
-    };
-    // Guard 2: the terminal is codex-mode.
-    if row.mode != "codex" {
-        tracing::warn!(
-            terminal_id = %msg.terminal_id,
-            mode = %row.mode,
-            "codex_candidate_rejected: terminal_not_codex"
-        );
-        return;
-    }
-    // Guard 3a: the terminal is not already bound to a DIFFERENT session
-    // (stale-replay defense; a re-announce of the SAME id is an idempotent
-    // no-op -- the client re-sends on every durability update). ORDER
-    // MATTERS: this same-terminal check must run BEFORE guard 3b's
-    // cross-terminal check, so a legit re-announce short-circuits here and
-    // never reaches the retired-inclusive lookup.
-    if let Some(existing) = row.resume_session_id.as_deref().filter(|s| !s.is_empty()) {
-        if existing != thread_id {
-            tracing::warn!(
-                terminal_id = %msg.terminal_id,
-                candidate_thread_id = %thread_id,
-                bound_session_id = %existing,
-                "codex_candidate_rejected: terminal_already_bound"
-            );
-        }
-        return;
-    }
-    // Guard 4: disk truth.
-    let Some(root) = codex_sessions_root() else {
-        tracing::warn!(
-            terminal_id = %msg.terminal_id,
-            "codex_candidate_rejected: no_codex_sessions_root"
-        );
-        return;
-    };
-    if let Err(reason) = verify_rollout_path(&msg.rollout_path, &root, thread_id) {
-        tracing::warn!(
-            terminal_id = %msg.terminal_id,
-            candidate_thread_id = %thread_id,
-            rollout_path = %msg.rollout_path,
-            "codex_candidate_rejected: {reason}"
-        );
-        return;
-    }
-    // The shared adoption tail (codex_identity.rs): binds both identity
-    // homes, awaits the durable ledger row, broadcasts the pinned
-    // associated/meta pair, and feeds the activity hub. It re-checks guard
-    // 3b (session bound elsewhere, retired-inclusive) internally; a reject
-    // there stays a silent WARN, matching this channel's no-reply contract.
-    adopt_codex_identity(
-        state,
-        CodexAdoption {
-            terminal_id: &msg.terminal_id,
-            thread_id,
-            rollout_path: Some(Path::new(&msg.rollout_path)),
-            cwd: row.cwd.as_deref(),
-        },
-    )
-    .await;
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    const TID: &str = "0192aaaa-bbbb-cccc-dddd-eeeeffff0001";
-    /// A DIFFERENT session's uuid -- plays the fork/resume-lineage foreign id.
-    const OTHER: &str = "0192aaaa-bbbb-cccc-dddd-eeeeffff0099";
-
-    /// The honest first line a real rollout starts with (durability-proof.ts
-    /// contract): a `session_meta` record whose `payload.id` is the file's
-    /// OWN session id.
-    fn session_meta_line(id: &str) -> String {
-        format!("{{\"timestamp\":\"2026-07-24T12:00:00.000Z\",\"type\":\"session_meta\",\"payload\":{{\"id\":\"{id}\"}}}}\n")
-    }
-
-    fn root_with_rollout(
-        file_name: &str,
-        contents: &str,
-    ) -> (tempfile::TempDir, std::path::PathBuf) {
-        let dir = tempfile::tempdir().expect("tempdir");
-        let sessions = dir
-            .path()
-            .join("sessions")
-            .join("2026")
-            .join("07")
-            .join("24");
-        std::fs::create_dir_all(&sessions).expect("mkdir sessions tree");
-        let rollout = sessions.join(file_name);
-        std::fs::write(&rollout, contents).expect("write rollout");
-        (dir, rollout)
-    }
-
-    #[test]
-    fn uuid_shape_accepts_canonical_and_rejects_junk() {
-        assert!(is_uuid_shaped(TID));
-        assert!(!is_uuid_shaped(""));
-        assert!(!is_uuid_shaped("not-a-uuid"));
-        assert!(!is_uuid_shaped("0192aaaa-bbbb-cccc-dddd-eeeeffff000")); // 35 chars
-        assert!(!is_uuid_shaped("0192aaaa+bbbb+cccc+dddd+eeeeffff0001")); // wrong separators
-    }
-
-    #[test]
-    fn accepts_rollout_whose_first_record_is_own_session_meta() {
-        // Later lines (even ones mentioning FOREIGN ids) are irrelevant: only
-        // the first record is consulted.
-        let contents = format!(
-            "{}{{\"type\":\"response_item\",\"session_id\":\"{OTHER}\"}}\n",
-            session_meta_line(TID)
-        );
-        let (dir, rollout) = root_with_rollout(
-            &format!("rollout-2026-07-24T12-00-00-{TID}.jsonl"),
-            &contents,
-        );
-        let root = dir.path().join("sessions");
-        assert_eq!(
-            verify_rollout_path(rollout.to_str().unwrap(), &root, TID),
-            Ok(())
-        );
-    }
-
-    #[test]
-    fn rejects_foreign_lineage_rollout() {
-        // The real-world fork-lineage spoof (V5: 54/144 real rollouts): the
-        // first line IS a session_meta and DOES carry the claimed id -- but
-        // only as `payload.session_id` (fork/resume lineage). `payload.id`,
-        // the file's OWN id, belongs to a different session. Must reject.
-        let contents = format!(
-            "{{\"type\":\"session_meta\",\"payload\":{{\"id\":\"{OTHER}\",\"session_id\":\"{TID}\"}}}}\n"
-        );
-        let (dir, rollout) = root_with_rollout(
-            &format!("rollout-2026-07-24T12-00-00-{OTHER}.jsonl"),
-            &contents,
-        );
-        let root = dir.path().join("sessions");
-        assert_eq!(
-            verify_rollout_path(rollout.to_str().unwrap(), &root, TID),
-            Err("thread_id_mismatch")
-        );
-    }
-
-    #[test]
-    fn rejects_non_session_meta_first_record() {
-        // Even a record carrying the claimed id is not proof unless it is the
-        // session_meta header record.
-        let contents = format!("{{\"type\":\"response_item\",\"payload\":{{\"id\":\"{TID}\"}}}}\n");
-        let (dir, rollout) = root_with_rollout(
-            &format!("rollout-2026-07-24T12-00-00-{TID}.jsonl"),
-            &contents,
-        );
-        let root = dir.path().join("sessions");
-        assert_eq!(
-            verify_rollout_path(rollout.to_str().unwrap(), &root, TID),
-            Err("rollout_first_record_not_session_meta")
-        );
-    }
-
-    #[test]
-    fn rejects_malformed_first_line() {
-        let (dir, rollout) = root_with_rollout(
-            &format!("rollout-2026-07-24T12-00-00-{TID}.jsonl"),
-            "not json\n",
-        );
-        let root = dir.path().join("sessions");
-        assert_eq!(
-            verify_rollout_path(rollout.to_str().unwrap(), &root, TID),
-            Err("rollout_first_record_not_json")
-        );
-    }
-
-    #[test]
-    fn rejects_oversized_first_line() {
-        // A >1MB first line is rejected by the cap BEFORE parsing -- even if
-        // the JSON would have been a valid own-session session_meta.
-        let contents = format!(
-            "{{\"type\":\"session_meta\",\"payload\":{{\"id\":\"{TID}\",\"pad\":\"{}\"}}}}\n",
-            "a".repeat(2 * 1024 * 1024)
-        );
-        let (dir, rollout) = root_with_rollout(
-            &format!("rollout-2026-07-24T12-00-00-{TID}.jsonl"),
-            &contents,
-        );
-        let root = dir.path().join("sessions");
-        assert_eq!(
-            verify_rollout_path(rollout.to_str().unwrap(), &root, TID),
-            Err("rollout_first_line_too_large")
-        );
-    }
-
-    #[test]
-    fn rejects_nonexistent_rollout() {
-        let dir = tempfile::tempdir().expect("tempdir");
-        let root = dir.path().join("sessions");
-        std::fs::create_dir_all(&root).unwrap();
-        let missing = root.join(format!("rollout-{TID}.jsonl"));
-        assert_eq!(
-            verify_rollout_path(missing.to_str().unwrap(), &root, TID),
-            Err("rollout_missing")
-        );
-    }
-
-    #[test]
-    fn rejects_rollout_outside_sessions_root() {
-        let (dir, _rollout) = root_with_rollout(&format!("rollout-{TID}.jsonl"), "{}");
-        let root = dir.path().join("sessions");
-        // A real file that exists but lives OUTSIDE the root.
-        let outside = dir.path().join(format!("rollout-{TID}.jsonl"));
-        std::fs::write(&outside, "{}").unwrap();
-        assert_eq!(
-            verify_rollout_path(outside.to_str().unwrap(), &root, TID),
-            Err("rollout_outside_sessions_root")
-        );
-    }
-
-    #[test]
-    fn rejects_dotdot_traversal_escape() {
-        let (dir, _rollout) = root_with_rollout(&format!("rollout-{TID}.jsonl"), "{}");
-        let root = dir.path().join("sessions");
-        let outside = dir.path().join(format!("escape-{TID}.jsonl"));
-        std::fs::write(&outside, "{}").unwrap();
-        // Path is SPELLED under the root but traverses out; canonicalize resolves it.
-        let sneaky = root.join("..").join(format!("escape-{TID}.jsonl"));
-        assert_eq!(
-            verify_rollout_path(sneaky.to_str().unwrap(), &root, TID),
-            Err("rollout_outside_sessions_root")
-        );
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn rejects_symlink_escape() {
-        let (dir, _rollout) = root_with_rollout(&format!("rollout-{TID}.jsonl"), "{}");
-        let root = dir.path().join("sessions");
-        let outside = dir.path().join(format!("target-{TID}.jsonl"));
-        std::fs::write(&outside, "{}").unwrap();
-        let link = root.join(format!("rollout-link-{TID}.jsonl"));
-        std::os::unix::fs::symlink(&outside, &link).expect("symlink");
-        assert_eq!(
-            verify_rollout_path(link.to_str().unwrap(), &root, TID),
-            Err("rollout_outside_sessions_root")
-        );
-    }
-}
diff --git a/crates/freshell-ws/src/codex_identity.rs b/crates/freshell-ws/src/codex_identity.rs
index 81e77463c..7bda3595b 100644
--- a/crates/freshell-ws/src/codex_identity.rs
+++ b/crates/freshell-ws/src/codex_identity.rs
@@ -1,8 +1,8 @@
 //! Shared codex identity adoption tail: bind a verified codex thread id into
 //! every identity home (identity store, registry meta, durable pane ledger,
 //! broadcast frames, activity hub) in the load-bearing order. Extracted from
-//! `codex_candidate.rs` so both the candidate channel and the server-side
-//! rollout locator adopt identically.
+//! the retired client candidate channel (`codex_candidate.rs`, campaign
+//! §2.3.2) and now owned solely by the server-side rollout locator.
 
 use std::path::{Path, PathBuf};
 
@@ -50,9 +50,9 @@ pub(crate) struct CodexAdoption<'a> {
 pub(crate) async fn adopt_codex_identity(state: &WsState, a: CodexAdoption<'_>) -> bool {
     // Cross-pane hijack / replay defense, retired-INCLUSIVE (ledger A8): a
     // victim's binding retires at exit, so a live-only lookup would allow
-    // replaying a DEAD pane's identity onto a fresh terminal. Copied from
-    // candidate guard 3b (codex_candidate.rs:167-186) -- keep the exact
-    // comparison semantics that code uses today; re-adopting the SAME
+    // replaying a DEAD pane's identity onto a fresh terminal. Inherited from
+    // the retired candidate channel's guard 3b -- keep the exact
+    // comparison semantics that code used; re-adopting the SAME
     // terminal is an idempotent allow. This guard is also a REQUIRED A4
     // misbind hardening for the locator path: the adoption tail must refuse
     // a thread id already bound to another terminal (Validated Premise 9),
diff --git a/crates/freshell-ws/src/codex_reconcile.rs b/crates/freshell-ws/src/codex_reconcile.rs
index ae8791648..72a87d631 100644
--- a/crates/freshell-ws/src/codex_reconcile.rs
+++ b/crates/freshell-ws/src/codex_reconcile.rs
@@ -13,7 +13,7 @@ use freshell_activity::codex::CodexTaskEvents;
 use freshell_sessions::time::parse_timestamp_ms;
 
 /// Initial attach reads at most this much of the rollout's tail. Rollouts
-/// reach 28MB+ (p99, see codex_candidate.rs:72-73); the latest task events
+/// reach 28MB+ (p99, V5 sampling); the latest task events
 /// live at the end, and trusting the tail is the legacy sanitizer's
 /// converged behavior for truncated snapshots.
 pub(crate) const INITIAL_TAIL_BYTES: u64 = 256 * 1024;
@@ -141,8 +141,8 @@ pub(crate) fn fold_task_events(lines: &[String]) -> CodexTaskEvents {
 /// the codex sessions root. Filename containment is only a cheap PREFILTER;
 /// ownership is proven by the first line being a `session_meta` whose
 /// `payload.id` equals the session id -- filename/substring matching alone is
-/// documented-unsafe (codex_candidate.rs:46-57: 40% of sampled rollouts
-/// contain foreign uuids). Bounded recursive walk (the tree is
+/// documented-unsafe (V5 sampling: 40% of sampled rollouts
+/// contain foreign uuids as fork/resume lineage). Bounded recursive walk (the tree is
 /// `sessions/YYYY/MM/DD/rollout-*.jsonl`, flat `<id>.jsonl` in tests).
 pub fn locate_codex_rollout(sessions_root: &Path, session_id: &str) -> Option<PathBuf> {
     fn walk(dir: &Path, session_id: &str, depth: u8, hit: &mut Option<PathBuf>) {
diff --git a/crates/freshell-ws/src/invariants.rs b/crates/freshell-ws/src/invariants.rs
index ad2e72271..b8f4f4d37 100644
--- a/crates/freshell-ws/src/invariants.rs
+++ b/crates/freshell-ws/src/invariants.rs
@@ -36,6 +36,17 @@ use crate::identity::TerminalIdentityRegistry;
 /// (2s) after a submit; five windows of slack keeps the alarm quiet through
 /// any normal association latency while still firing within seconds of a
 /// genuinely-lost identity.
+///
+/// This same grace also covers the codex locator
+/// ([`freshell_sessions::codex_locator::CODEX_WINDOW_MS`] = 2s,
+/// Enter-anchored, plus
+/// [`freshell_sessions::codex_locator::PENDING_FIRST_LINE_GRACE_MS`] = 10s
+/// that applies ONLY in the anomalous empty-first-line gap): fresh codex
+/// panes are expected to resolve via `codex_association` within this grace
+/// of their first Enter. A maximally slow codex git-info gap (rollout header
+/// held back until codex finishes probing repo state) can legitimately
+/// outlast the alarm grace -- in that case the alarm is advisory, not a
+/// lost identity.
 pub(crate) const IDENTITY_RESOLUTION_GRACE_MS: i64 =
     5 * freshell_sessions::amplifier_locator::AMPLIFIER_DIR_APPEAR_WINDOW_MS;
 
diff --git a/crates/freshell-ws/src/lib.rs b/crates/freshell-ws/src/lib.rs
index b0cf5576c..c9d930b8f 100644
--- a/crates/freshell-ws/src/lib.rs
+++ b/crates/freshell-ws/src/lib.rs
@@ -24,7 +24,6 @@ pub mod activity;
 pub mod amplifier_association;
 pub mod backpressure;
 pub mod codex_association;
-pub(crate) mod codex_candidate;
 pub(crate) mod codex_identity;
 pub(crate) mod codex_reconcile;
 pub mod create_limit;
diff --git a/crates/freshell-ws/src/terminal.rs b/crates/freshell-ws/src/terminal.rs
index b6bbcd6d8..575b92a36 100644
--- a/crates/freshell-ws/src/terminal.rs
+++ b/crates/freshell-ws/src/terminal.rs
@@ -508,11 +508,16 @@ async fn handle_client_text(
         ClientMessage::TerminalCreate(create) => {
             handle_create(create, ws_tx, state, pane_reconcile_v1, create_limiter).await
         }
-        // P0.3: server-side codex identity capture from the client's persisted
-        // candidate -- guarded (campaign plan §2.3.1); rejects are logged and
-        // ignored, never answered (legacy parity ws-handler.ts:2951-2963).
+        // RETIRED (campaign §2.3.2, Lane B2): codex identity has exactly one
+        // writer -- the server-side rollout locator (codex_association). The
+        // frozen client still sends this frame (TerminalView.tsx durability
+        // handler), so accept-and-ignore with a debug breadcrumb; never an
+        // error to the client, never an identity write.
         ClientMessage::TerminalCodexCandidatePersisted(candidate) => {
-            crate::codex_candidate::handle_codex_candidate_persisted(state, candidate).await;
+            tracing::debug!(
+                terminal_id = %candidate.terminal_id,
+                "codex_candidate_ignored: client candidate channel retired (server locator is authoritative)"
+            );
             true
         }
         ClientMessage::TerminalAttach(attach) => {
@@ -1697,8 +1702,9 @@ async fn handle_create(
 /// regex /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i):
 /// canonical UUID shape with a version digit 1-5 (position 14) and a variant
 /// digit [89ab] (position 19), case-insensitive. Same chars-based idiom as
-/// `codex_candidate::is_uuid_shaped`, extended with the version/variant
-/// constraints. Used ONLY by the P0.4 restore gate below -- non-restore
+/// the codex locator's uuid shape gate
+/// (`freshell_sessions::codex_locator::is_uuid_shaped`), extended with the
+/// version/variant constraints. Used ONLY by the P0.4 restore gate below -- non-restore
 /// resume derivation is deliberately untouched.
 fn is_canonical_claude_session_id(s: &str) -> bool {
     s.len() == 36
diff --git a/crates/freshell-ws/tests/codex_candidate_activity.rs b/crates/freshell-ws/tests/codex_candidate_activity.rs
deleted file mode 100644
index aa3ac6303..000000000
--- a/crates/freshell-ws/tests/codex_candidate_activity.rs
+++ /dev/null
@@ -1,197 +0,0 @@
-//! G3 integration: a FRESH codex terminal (no resume id) whose candidate is
-//! adopted must broadcast `codex.activity.updated` carrying the sessionId,
-//! and its subsequent turn completion must carry the same sessionId.
-//! Uses the activity-enabled harness (the default harness has `activity: None`).
-//!
-//! This binary asserts the identity upsert only; the completion payoff is
-//! covered at hub level (activity.rs unit tests) and e2e level.
-
-#[cfg(unix)]
-mod common;
-
-#[cfg(unix)]
-use futures_util::{SinkExt, StreamExt};
-#[cfg(unix)]
-use serde_json::json;
-#[cfg(unix)]
-use std::time::Duration;
-#[cfg(unix)]
-use tokio_tungstenite::tungstenite::Message as WsMessage;
-
-/// Fake codex: records argv to $CODEX_ARGV_CAPTURE_PATH (atomic tmp+mv) then
-/// sleeps. Copied from tests/codex_candidate_persisted.rs.
-#[cfg(unix)]
-fn write_fake_codex() -> std::path::PathBuf {
-    let script_path = std::env::temp_dir().join(format!(
-        "freshell-codex-candidate-activity-fake-{}.sh",
-        std::process::id()
-    ));
-    let script = "#!/bin/sh\n\
-        printf '%s\\n' \"$@\" > \"$CODEX_ARGV_CAPTURE_PATH.tmp\"\n\
-        mv \"$CODEX_ARGV_CAPTURE_PATH.tmp\" \"$CODEX_ARGV_CAPTURE_PATH\"\n\
-        exec sleep 300\n";
-    std::fs::write(&script_path, script).expect("write fake codex script");
-    {
-        use std::os::unix::fs::PermissionsExt;
-        let mut perms = std::fs::metadata(&script_path).unwrap().permissions();
-        perms.set_mode(0o755);
-        std::fs::set_permissions(&script_path, perms).unwrap();
-    }
-    script_path
-}
-
-#[cfg(unix)]
-fn codex_capture_spec() -> freshell_platform::CliCommandSpec {
-    freshell_platform::CliCommandSpec {
-        name: "codex".to_string(),
-        label: "Codex CLI".to_string(),
-        env_var: None,
-        default_cmd: write_fake_codex().to_string_lossy().to_string(),
-        base_args: vec![],
-        base_env: std::collections::BTreeMap::new(),
-        // Real codex manifest shape: resume subcommand, no createSessionArgs.
-        resume_args: Some(vec!["resume".to_string(), "{{sessionId}}".to_string()]),
-        create_session_args: None,
-        model_args: None,
-        sandbox_args: None,
-        permission_mode_args: None,
-    }
-}
-
-/// Send a fresh `terminal.create` (no sessionRef, no resume id) and await its
-/// `terminal.created`, returning the terminalId.
-#[cfg(unix)]
-async fn send_create(ws: &mut common::TestWs, mode: &str) -> String {
-    ws.send(WsMessage::Text(
-        json!({
-            "type": "terminal.create",
-            "requestId": "req-codex-activity-1",
-            "mode": mode,
-            "shell": "system",
-            "cwd": std::env::temp_dir().to_string_lossy(),
-        })
-        .to_string(),
-    ))
-    .await
-    .expect("send terminal.create");
-    let created = common::next_frame_of_type(ws, "terminal.created").await;
-    created["terminalId"]
-        .as_str()
-        .expect("terminal.created carries terminalId")
-        .to_string()
-}
-
-/// Plain candidate announce (client announcing the persisted rollout).
-/// Copied from tests/codex_candidate_persisted.rs.
-#[cfg(unix)]
-async fn send_candidate(
-    ws: &mut common::TestWs,
-    terminal_id: &str,
-    thread_id: &str,
-    rollout_path: &str,
-) {
-    ws.send(WsMessage::Text(
-        json!({
-            "type": "terminal.codex.candidate.persisted",
-            "terminalId": terminal_id,
-            "candidateThreadId": thread_id,
-            "rolloutPath": rollout_path,
-            "capturedAt": 1_753_300_000_000i64,
-        })
-        .to_string(),
-    ))
-    .await
-    .expect("send candidate");
-}
-
-/// Scan WS text frames until `pred` matches or the 10s budget elapses.
-/// Non-matching frames are simply skipped (no drop-on-mismatch semantics).
-#[cfg(unix)]
-async fn wait_for_frame(
-    ws: &mut common::TestWs,
-    pred: impl Fn(&serde_json::Value) -> bool,
-) -> bool {
-    let deadline = tokio::time::Instant::now() + Duration::from_secs(10);
-    while tokio::time::Instant::now() < deadline {
-        let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
-        match tokio::time::timeout(remaining.max(Duration::from_millis(1)), ws.next()).await {
-            Ok(Some(Ok(WsMessage::Text(text)))) => {
-                if let Ok(value) = serde_json::from_str::<serde_json::Value>(&text) {
-                    if pred(&value) {
-                        return true;
-                    }
-                }
-            }
-            Ok(Some(Ok(_))) => {}
-            _ => return false, // stream ended, ws error, or timed out
-        }
-    }
-    false
-}
-
-#[cfg(unix)]
-#[tokio::test(flavor = "multi_thread")]
-async fn adopted_candidate_identity_reaches_codex_activity() {
-    const THREAD: &str = "11111111-2222-3333-4444-555555555555";
-
-    // ---- env setup (single sequential test: this binary owns process env) ----
-    // CODEX_HOME tempdir + a real rollout whose first line is
-    // session_meta { payload: { id: THREAD } } (adoption guard 4 disk truth).
-    let codex_home = tempfile::tempdir().expect("codex home");
-    let sessions_day = codex_home
-        .path()
-        .join("sessions")
-        .join("2026")
-        .join("07")
-        .join("24");
-    std::fs::create_dir_all(&sessions_day).expect("sessions tree");
-    std::env::set_var("CODEX_HOME", codex_home.path());
-    std::env::remove_var("FRESHELL_CODEX_MANAGED_LAUNCH");
-    let capture = std::env::temp_dir().join(format!(
-        "codex-candidate-activity-argv-{}.txt",
-        std::process::id()
-    ));
-    let _ = std::fs::remove_file(&capture);
-    std::env::set_var("CODEX_ARGV_CAPTURE_PATH", &capture);
-
-    let rollout = sessions_day.join(format!("rollout-2026-07-24T12-00-00-{THREAD}.jsonl"));
-    std::fs::write(
-        &rollout,
-        format!("{{\"timestamp\":\"2026-07-24T12:00:00.000Z\",\"type\":\"session_meta\",\"payload\":{{\"id\":\"{THREAD}\"}}}}\n"),
-    )
-    .unwrap();
-    let rollout_path = rollout.to_string_lossy().to_string();
-
-    let (url, registry) =
-        common::spawn_server_with_specs_and_activity(vec![codex_capture_spec()]).await;
-    let (mut ws, _inventory) = common::connect_and_capture_inventory(&url).await;
-
-    // 1. Create a FRESH codex terminal (no sessionRef, no resume id).
-    let terminal_id = send_create(&mut ws, "codex").await;
-
-    // 2. Send the candidate frame (client announcing the persisted rollout).
-    send_candidate(&mut ws, &terminal_id, THREAD, &rollout_path).await;
-
-    // 3. The adopt path must now emit codex.activity.updated with sessionId.
-    //    Collect frames by scanning (never drop-on-mismatch).
-    let bound = wait_for_frame(&mut ws, |v| {
-        v["type"] == "codex.activity.updated"
-            && v["upsert"]
-                .as_array()
-                .map(|u| {
-                    u.iter().any(|r| {
-                        r["terminalId"] == terminal_id.as_str() && r["sessionId"] == THREAD
-                    })
-                })
-                .unwrap_or(false)
-    })
-    .await;
-    assert!(
-        bound,
-        "expected codex.activity.updated carrying the adopted sessionId"
-    );
-
-    registry.kill(&terminal_id);
-    std::env::remove_var("CODEX_HOME");
-    std::env::remove_var("CODEX_ARGV_CAPTURE_PATH");
-}
diff --git a/crates/freshell-ws/tests/codex_candidate_inert.rs b/crates/freshell-ws/tests/codex_candidate_inert.rs
new file mode 100644
index 000000000..a3141ce55
--- /dev/null
+++ b/crates/freshell-ws/tests/codex_candidate_inert.rs
@@ -0,0 +1,221 @@
+//! Lane B2 / campaign §2.3.2: terminal.codex.candidate.persisted is RETIRED
+//! as a writer. The frozen client still SENDS it (TerminalView.tsx:4009-4018),
+//! so the server must accept-and-ignore with a debug log — never an error to
+//! the client, and NEVER an identity write.
+
+mod common;
+
+use common::{connect_and_capture_inventory, next_frame_of_type, spawn_server_with_ledger};
+use futures_util::{SinkExt, StreamExt};
+use serde_json::json;
+use tokio_tungstenite::tungstenite::Message as WsMessage;
+
+const THREAD: &str = "0192cccc-dddd-4eee-8fff-000011112222";
+
+/// Fake codex: records argv to $CODEX_ARGV_CAPTURE_PATH (atomic tmp+mv) then
+/// sleeps. Copied from the retired tests/codex_candidate_persisted.rs (which
+/// copied it from tests/codex_session_ref_resume.rs:85-103).
+fn write_fake_codex() -> std::path::PathBuf {
+    let script_path = std::env::temp_dir().join(format!(
+        "freshell-codex-inert-fake-{}.sh",
+        std::process::id()
+    ));
+    let script = "#!/bin/sh\n\
+        printf '%s\\n' \"$@\" > \"$CODEX_ARGV_CAPTURE_PATH.tmp\"\n\
+        mv \"$CODEX_ARGV_CAPTURE_PATH.tmp\" \"$CODEX_ARGV_CAPTURE_PATH\"\n\
+        exec sleep 300\n";
+    std::fs::write(&script_path, script).expect("write fake codex script");
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let mut perms = std::fs::metadata(&script_path).unwrap().permissions();
+        perms.set_mode(0o755);
+        std::fs::set_permissions(&script_path, perms).unwrap();
+    }
+    script_path
+}
+
+fn codex_capture_spec() -> freshell_platform::CliCommandSpec {
+    freshell_platform::CliCommandSpec {
+        name: "codex".to_string(),
+        label: "Codex CLI".to_string(),
+        env_var: None,
+        default_cmd: write_fake_codex().to_string_lossy().to_string(),
+        base_args: vec![],
+        base_env: std::collections::BTreeMap::new(),
+        // Real codex manifest shape: resume subcommand, no createSessionArgs.
+        resume_args: Some(vec!["resume".to_string(), "{{sessionId}}".to_string()]),
+        create_session_args: None,
+        model_args: None,
+        sandbox_args: None,
+        permission_mode_args: None,
+    }
+}
+
+fn registry_resume_id(
+    registry: &freshell_terminal::TerminalRegistry,
+    terminal_id: &str,
+) -> Option<String> {
+    registry
+        .identity_probe_rows()
+        .into_iter()
+        .find(|row| row.terminal_id == terminal_id)
+        .unwrap_or_else(|| panic!("registry must list {terminal_id}"))
+        .resume_session_id
+}
+
+/// Send a candidate that must be IGNORED: the ping/pong round-trip proves the
+/// frame was consumed AND that nothing was sent back (silence proof --
+/// precedent: pane_reconcile.rs uses exactly this to prove nothing was sent).
+/// Copied from the retired tests/codex_candidate_persisted.rs:112-131.
+async fn send_candidate_expect_silence(
+    ws: &mut common::TestWs,
+    terminal_id: &str,
+    thread_id: &str,
+    rollout_path: &str,
+) {
+    ws.send(WsMessage::Text(
+        json!({
+            "type": "terminal.codex.candidate.persisted",
+            "terminalId": terminal_id,
+            "candidateThreadId": thread_id,
+            "rolloutPath": rollout_path,
+            "capturedAt": 1_753_300_000_000i64,
+        })
+        .to_string(),
+    ))
+    .await
+    .expect("send candidate");
+    ws.send(WsMessage::Text(json!({"type": "ping"}).to_string()))
+        .await
+        .expect("send ping");
+    let _pong = next_frame_of_type(ws, "pong").await;
+}
+
+/// Ping, then read frames until the pong arrives — panicking on any `error`
+/// frame in between (the connection must stay healthy; broadcasts like
+/// `terminals.changed` are fine and skipped).
+async fn expect_no_error_until_pong(ws: &mut common::TestWs) {
+    ws.send(WsMessage::Text(json!({"type": "ping"}).to_string()))
+        .await
+        .expect("send ping");
+    for _ in 0..20u8 {
+        let msg = tokio::time::timeout(std::time::Duration::from_secs(5), ws.next())
+            .await
+            .expect("frame within timeout")
+            .expect("stream not ended")
+            .expect("no ws error");
+        if let WsMessage::Text(text) = &msg {
+            let value: serde_json::Value = serde_json::from_str(text).expect("json frame");
+            assert_ne!(
+                value["type"],
+                json!("error"),
+                "connection must stay error-free: {value}"
+            );
+            if value["type"] == json!("pong") {
+                return;
+            }
+        }
+    }
+    panic!("no pong frame within 20 messages");
+}
+
+#[tokio::test(flavor = "multi_thread")]
+#[cfg(unix)]
+async fn candidate_frame_is_accepted_ignored_and_writes_nothing() {
+    // ---- env setup (single sequential test: this binary owns process env) ----
+    let codex_home = tempfile::tempdir().expect("codex home");
+    let sessions_day = codex_home
+        .path()
+        .join("sessions")
+        .join("2026")
+        .join("07")
+        .join("24");
+    std::fs::create_dir_all(&sessions_day).expect("sessions tree");
+    std::env::set_var("CODEX_HOME", codex_home.path());
+    std::env::remove_var("FRESHELL_CODEX_MANAGED_LAUNCH");
+    let capture = std::env::temp_dir().join(format!("codex-inert-argv-{}.txt", std::process::id()));
+    let _ = std::fs::remove_file(&capture);
+    std::env::set_var("CODEX_ARGV_CAPTURE_PATH", &capture);
+
+    // A VALID rollout for THREAD — one that would have passed all four old
+    // guards. Written BEFORE the terminal exists, so the locator's arm-time
+    // snapshot excludes it forever: any identity write observed below could
+    // only have come from the candidate channel.
+    let rollout = sessions_day.join(format!("rollout-2026-07-24T12-00-00-{THREAD}.jsonl"));
+    std::fs::write(
+        &rollout,
+        format!("{{\"timestamp\":\"2026-07-24T12:00:00.000Z\",\"type\":\"session_meta\",\"payload\":{{\"id\":\"{THREAD}\"}}}}\n"),
+    )
+    .unwrap();
+    let rollout = rollout.to_string_lossy().to_string();
+
+    // A REAL ledger dir so "writes nothing" covers the durable home too.
+    let ledger_dir =
+        std::env::temp_dir().join(format!("codex-inert-ledger-{}", std::process::id()));
+    std::fs::create_dir_all(&ledger_dir).unwrap();
+    let (url, registry, _server_ledger) =
+        spawn_server_with_ledger(vec![codex_capture_spec()], &ledger_dir).await;
+    let (mut ws, _inventory) = connect_and_capture_inventory(&url).await;
+
+    // A REAL fresh codex terminal with NO identity (no sessionRef, no resume).
+    ws.send(WsMessage::Text(
+        json!({
+            "type": "terminal.create",
+            "requestId": "req-codex-inert-1",
+            "mode": "codex",
+            "shell": "system",
+            "cwd": std::env::temp_dir().to_string_lossy(),
+        })
+        .to_string(),
+    ))
+    .await
+    .expect("send terminal.create");
+    let created = next_frame_of_type(&mut ws, "terminal.created").await;
+    let codex_tid = created["terminalId"]
+        .as_str()
+        .expect("terminalId")
+        .to_string();
+    assert_eq!(
+        registry_resume_id(&registry, &codex_tid),
+        None,
+        "fresh codex must start unbound"
+    );
+
+    // The frozen client's durability announce: a candidate that the OLD
+    // handler would have adopted. Retired channel: accept-and-ignore,
+    // nothing sent back, connection healthy.
+    send_candidate_expect_silence(&mut ws, &codex_tid, THREAD, &rollout).await;
+
+    // NO identity write in ANY home: registry meta stays unbound...
+    assert_eq!(
+        registry_resume_id(&registry, &codex_tid),
+        None,
+        "retired candidate channel must never write identity"
+    );
+    // ...and the durable ledger holds no binding row for the thread id
+    // (fresh reader instance: construction-time scan sees disk truth).
+    let ledger = freshell_ws::pane_ledger::PaneLedger::new(Some(ledger_dir.clone()));
+    assert!(
+        ledger.load_binding("codex", THREAD).is_none(),
+        "retired candidate channel must never write a ledger binding"
+    );
+
+    // The terminal still works: input flows and no protocol error comes back.
+    ws.send(WsMessage::Text(
+        json!({
+            "type": "terminal.input",
+            "terminalId": codex_tid,
+            "data": "\r",
+        })
+        .to_string(),
+    ))
+    .await
+    .expect("send terminal.input");
+    expect_no_error_until_pong(&mut ws).await;
+
+    registry.kill(&codex_tid);
+    std::env::remove_var("CODEX_HOME");
+    std::env::remove_var("CODEX_ARGV_CAPTURE_PATH");
+    std::fs::remove_dir_all(&ledger_dir).ok();
+}
diff --git a/crates/freshell-ws/tests/codex_candidate_persisted.rs b/crates/freshell-ws/tests/codex_candidate_persisted.rs
deleted file mode 100644
index 76d478e5f..000000000
--- a/crates/freshell-ws/tests/codex_candidate_persisted.rs
+++ /dev/null
@@ -1,381 +0,0 @@
-//! P0.3 integration: `terminal.codex.candidate.persisted` handling.
-//! Campaign plan §2.3.1: four guards; reject = WARN + ignore, nothing sent back.
-
-mod common;
-
-use common::{
-    connect_and_capture_inventory, next_frame_of_type, sleeper_cli_spec, spawn_server_with_ledger,
-};
-use futures_util::SinkExt;
-use serde_json::json;
-use tokio_tungstenite::tungstenite::Message as WsMessage;
-
-const THREAD_A: &str = "0192aaaa-bbbb-4ccc-8ddd-eeeeffff0001";
-const THREAD_B: &str = "0192aaaa-bbbb-4ccc-8ddd-eeeeffff0002";
-
-/// Fake codex: records argv to $CODEX_ARGV_CAPTURE_PATH (atomic tmp+mv) then
-/// sleeps. Copied from tests/codex_session_ref_resume.rs:85-103.
-fn write_fake_codex() -> std::path::PathBuf {
-    let script_path = std::env::temp_dir().join(format!(
-        "freshell-codex-candidate-fake-{}.sh",
-        std::process::id()
-    ));
-    let script = "#!/bin/sh\n\
-        printf '%s\\n' \"$@\" > \"$CODEX_ARGV_CAPTURE_PATH.tmp\"\n\
-        mv \"$CODEX_ARGV_CAPTURE_PATH.tmp\" \"$CODEX_ARGV_CAPTURE_PATH\"\n\
-        exec sleep 300\n";
-    std::fs::write(&script_path, script).expect("write fake codex script");
-    #[cfg(unix)]
-    {
-        use std::os::unix::fs::PermissionsExt;
-        let mut perms = std::fs::metadata(&script_path).unwrap().permissions();
-        perms.set_mode(0o755);
-        std::fs::set_permissions(&script_path, perms).unwrap();
-    }
-    script_path
-}
-
-fn codex_capture_spec() -> freshell_platform::CliCommandSpec {
-    freshell_platform::CliCommandSpec {
-        name: "codex".to_string(),
-        label: "Codex CLI".to_string(),
-        env_var: None,
-        default_cmd: write_fake_codex().to_string_lossy().to_string(),
-        base_args: vec![],
-        base_env: std::collections::BTreeMap::new(),
-        // Real codex manifest shape: resume subcommand, no createSessionArgs.
-        resume_args: Some(vec!["resume".to_string(), "{{sessionId}}".to_string()]),
-        create_session_args: None,
-        model_args: None,
-        sandbox_args: None,
-        permission_mode_args: None,
-    }
-}
-
-fn registry_resume_id(
-    registry: &freshell_terminal::TerminalRegistry,
-    terminal_id: &str,
-) -> Option<String> {
-    registry
-        .identity_probe_rows()
-        .into_iter()
-        .find(|row| row.terminal_id == terminal_id)
-        .unwrap_or_else(|| panic!("registry must list {terminal_id}"))
-        .resume_session_id
-}
-
-async fn send_create(
-    ws: &mut common::TestWs,
-    request_id: &str,
-    mode: &str,
-    extra: serde_json::Value,
-) {
-    let mut msg = json!({
-        "type": "terminal.create",
-        "requestId": request_id,
-        "mode": mode,
-        "shell": "system",
-        "cwd": std::env::temp_dir().to_string_lossy(),
-    });
-    if let (Some(obj), Some(extra_obj)) = (msg.as_object_mut(), extra.as_object()) {
-        for (k, v) in extra_obj {
-            obj.insert(k.clone(), v.clone());
-        }
-    }
-    ws.send(WsMessage::Text(msg.to_string()))
-        .await
-        .expect("send terminal.create");
-}
-
-/// Plain send, NO sync gate. Used by the HAPPY PATH only, which proves
-/// consumption by awaiting the broadcasts themselves.
-async fn send_candidate(
-    ws: &mut common::TestWs,
-    terminal_id: &str,
-    thread_id: &str,
-    rollout_path: &str,
-) {
-    ws.send(WsMessage::Text(
-        json!({
-            "type": "terminal.codex.candidate.persisted",
-            "terminalId": terminal_id,
-            "candidateThreadId": thread_id,
-            "rolloutPath": rollout_path,
-            "capturedAt": 1_753_300_000_000i64,
-        })
-        .to_string(),
-    ))
-    .await
-    .expect("send candidate");
-}
-
-/// Send a candidate that must be REJECTED: the ping/pong round-trip proves
-/// the frame was consumed AND that nothing was sent back (silence proof --
-/// precedent: pane_reconcile.rs:230-250 uses exactly this to prove nothing
-/// was sent). NEVER use this on the accept path: `next_frame_of_type`
-/// permanently DROPS mismatched frames (tests/common/mod.rs:327-342), and the
-/// connection loop is one unbiased `tokio::select!`, so broadcasts queued
-/// during candidate handling commonly hit the wire BEFORE the pong --
-/// awaiting the pong first would eat the association broadcasts.
-async fn send_candidate_expect_silence(
-    ws: &mut common::TestWs,
-    terminal_id: &str,
-    thread_id: &str,
-    rollout_path: &str,
-) {
-    send_candidate(ws, terminal_id, thread_id, rollout_path).await;
-    ws.send(WsMessage::Text(json!({"type": "ping"}).to_string()))
-        .await
-        .expect("send ping");
-    let _pong = next_frame_of_type(ws, "pong").await;
-}
-
-fn wait_for_captured_argv(path: &std::path::Path) -> Vec<String> {
-    for _ in 0..100 {
-        if let Ok(contents) = std::fs::read_to_string(path) {
-            return contents.lines().map(str::to_string).collect();
-        }
-        std::thread::sleep(std::time::Duration::from_millis(100));
-    }
-    panic!("fake codex never wrote argv capture at {}", path.display());
-}
-
-#[tokio::test(flavor = "multi_thread")]
-#[cfg(unix)]
-async fn codex_candidate_persisted_guards_and_happy_path() {
-    // ---- env setup (single sequential test: this binary owns process env) ----
-    let codex_home = tempfile::tempdir().expect("codex home");
-    let sessions_day = codex_home
-        .path()
-        .join("sessions")
-        .join("2026")
-        .join("07")
-        .join("24");
-    std::fs::create_dir_all(&sessions_day).expect("sessions tree");
-    std::env::set_var("CODEX_HOME", codex_home.path());
-    std::env::remove_var("FRESHELL_CODEX_MANAGED_LAUNCH");
-    let capture =
-        std::env::temp_dir().join(format!("codex-candidate-argv-{}.txt", std::process::id()));
-    let _ = std::fs::remove_file(&capture);
-    std::env::set_var("CODEX_ARGV_CAPTURE_PATH", &capture);
-
-    // P1.8: a REAL ledger dir -- adoption must durably record the identity.
-    // The third tuple element (the server's own Arc) is unused: durability is
-    // verified via a FRESH reader instance constructed AFTER the adoption.
-    let ledger_dir =
-        std::env::temp_dir().join(format!("codex-adopt-ledger-{}", std::process::id()));
-    std::fs::create_dir_all(&ledger_dir).unwrap();
-    let (url, registry, _server_ledger) = spawn_server_with_ledger(
-        vec![sleeper_cli_spec("claude"), codex_capture_spec()],
-        &ledger_dir,
-    )
-    .await;
-    let (mut ws, _inventory) = connect_and_capture_inventory(&url).await;
-
-    // A codex terminal with NO identity yet (fresh create, no resume).
-    send_create(&mut ws, "req-codex-cand-1", "codex", json!({})).await;
-    let created = next_frame_of_type(&mut ws, "terminal.created").await;
-    let codex_tid = created["terminalId"]
-        .as_str()
-        .expect("terminalId")
-        .to_string();
-    assert_eq!(
-        registry_resume_id(&registry, &codex_tid),
-        None,
-        "fresh codex must start unbound"
-    );
-
-    // A valid on-disk rollout for THREAD_A: first line is the session_meta
-    // header whose payload.id is the rollout's OWN id (guard 4's contract).
-    let rollout_a = sessions_day.join(format!("rollout-2026-07-24T12-00-00-{THREAD_A}.jsonl"));
-    std::fs::write(
-        &rollout_a,
-        format!("{{\"timestamp\":\"2026-07-24T12:00:00.000Z\",\"type\":\"session_meta\",\"payload\":{{\"id\":\"{THREAD_A}\"}}}}\n"),
-    )
-    .unwrap();
-    let rollout_a = rollout_a.to_string_lossy().to_string();
-
-    // ---- Guard 1: unknown terminal is ignored ----
-    send_candidate_expect_silence(&mut ws, "no-such-terminal", THREAD_A, &rollout_a).await;
-    assert_eq!(registry_resume_id(&registry, &codex_tid), None);
-
-    // ---- Guard 2: non-codex terminal is ignored ----
-    send_create(&mut ws, "req-claude-cand-1", "claude", json!({})).await;
-    let claude_created = next_frame_of_type(&mut ws, "terminal.created").await;
-    let claude_tid = claude_created["terminalId"]
-        .as_str()
-        .expect("terminalId")
-        .to_string();
-    send_candidate_expect_silence(&mut ws, &claude_tid, THREAD_A, &rollout_a).await;
-    assert_ne!(
-        registry_resume_id(&registry, &claude_tid).as_deref(),
-        Some(THREAD_A),
-        "claude terminal must never adopt a codex candidate"
-    );
-    assert_eq!(registry_resume_id(&registry, &codex_tid), None);
-
-    // ---- Guard 4: out-of-root rolloutPath is ignored (fails containment,
-    //      so its contents are never read) ----
-    let outside = std::env::temp_dir().join(format!("outside-rollout-{THREAD_A}.jsonl"));
-    std::fs::write(&outside, format!("{THREAD_A}\n")).unwrap();
-    send_candidate_expect_silence(&mut ws, &codex_tid, THREAD_A, &outside.to_string_lossy()).await;
-    assert_eq!(registry_resume_id(&registry, &codex_tid), None);
-
-    // ---- Guard 4: nonexistent rolloutPath is ignored ----
-    let missing = sessions_day.join("rollout-nope.jsonl");
-    send_candidate_expect_silence(&mut ws, &codex_tid, THREAD_A, &missing.to_string_lossy()).await;
-    assert_eq!(registry_resume_id(&registry, &codex_tid), None);
-
-    // ---- Guard 4: foreign-lineage rollout is ignored (in-root, real file,
-    //      session_meta first line -- but payload.id is ANOTHER session's;
-    //      the claimed id appears only as fork lineage payload.session_id) ----
-    let foreign = sessions_day.join(format!("rollout-2026-07-24T11-00-00-{THREAD_B}.jsonl"));
-    std::fs::write(
-        &foreign,
-        format!("{{\"type\":\"session_meta\",\"payload\":{{\"id\":\"{THREAD_B}\",\"session_id\":\"{THREAD_A}\"}}}}\n"),
-    )
-    .unwrap();
-    send_candidate_expect_silence(&mut ws, &codex_tid, THREAD_A, &foreign.to_string_lossy()).await;
-    assert_eq!(registry_resume_id(&registry, &codex_tid), None);
-
-    // ---- Happy path: binds both identity homes + broadcasts ----
-    // NO ping gate here (see send_candidate_expect_silence's doc): receipt of
-    // the two broadcasts IS the consumption proof. Their order is pinned by
-    // the handler: associated BEFORE meta.updated.
-    send_candidate(&mut ws, &codex_tid, THREAD_A, &rollout_a).await;
-    let associated = next_frame_of_type(&mut ws, "terminal.session.associated").await;
-    assert_eq!(associated["terminalId"], json!(codex_tid));
-    assert_eq!(
-        associated["sessionRef"],
-        json!({ "provider": "codex", "sessionId": THREAD_A })
-    );
-    let meta = next_frame_of_type(&mut ws, "terminal.meta.updated").await;
-    let upsert = &meta["upsert"][0];
-    assert_eq!(upsert["terminalId"], json!(codex_tid));
-    assert_eq!(upsert["provider"], json!("codex"));
-    assert_eq!(upsert["sessionId"], json!(THREAD_A));
-    assert_eq!(
-        registry_resume_id(&registry, &codex_tid).as_deref(),
-        Some(THREAD_A)
-    );
-
-    // P1.8: adoption is an identity event -- the ledger must now hold a
-    // binding row for THREAD_A, and the spawn-time pending marker must be
-    // gone (binding-first pinned order, spec §4.2).
-    let ledger = freshell_ws::pane_ledger::PaneLedger::new(Some(ledger_dir.clone()));
-    let row = ledger
-        .load_binding("codex", THREAD_A)
-        .expect("adoption wrote a binding row");
-    assert_eq!(row.state, freshell_ws::pane_ledger::RowState::Bound);
-    assert_eq!(row.live_terminal_id.as_deref(), Some(codex_tid.as_str()));
-    assert!(
-        ledger.pending_for_terminal(&codex_tid).is_none(),
-        "pending marker resolved away"
-    );
-    assert!(ledger
-        .list_pending_raw()
-        .iter()
-        .all(|m| m.terminal_id != codex_tid));
-
-    // ---- Guard 3b: cross-pane hijack -- THREAD_A is live-bound to codex_tid ----
-    send_create(&mut ws, "req-codex-cand-2", "codex", json!({})).await;
-    let created2 = next_frame_of_type(&mut ws, "terminal.created").await;
-    let codex_tid2 = created2["terminalId"]
-        .as_str()
-        .expect("terminalId")
-        .to_string();
-    send_candidate_expect_silence(&mut ws, &codex_tid2, THREAD_A, &rollout_a).await;
-    assert_eq!(
-        registry_resume_id(&registry, &codex_tid2),
-        None,
-        "a sessionRef bound to a different live terminal must never be adopted"
-    );
-
-    // ---- Guard 3a: stale replayed candidate once a newer binding exists ----
-    let rollout_b = sessions_day.join(format!("rollout-2026-07-24T13-00-00-{THREAD_B}.jsonl"));
-    std::fs::write(
-        &rollout_b,
-        format!("{{\"type\":\"session_meta\",\"payload\":{{\"id\":\"{THREAD_B}\"}}}}\n"),
-    )
-    .unwrap();
-    send_candidate_expect_silence(&mut ws, &codex_tid, THREAD_B, &rollout_b.to_string_lossy())
-        .await;
-    assert_eq!(
-        registry_resume_id(&registry, &codex_tid).as_deref(),
-        Some(THREAD_A),
-        "an already-bound terminal must keep its binding; replayed/stale candidates are ignored"
-    );
-
-    // ---- Guard 3b (retired-INCLUSIVE): dead-pane candidate replay ----
-    // Kill THREAD_A's owner over the WS protocol: `handle_kill` retires the
-    // identity entry SYNCHRONOUSLY in the dispatch loop
-    // (`state.identity.retire(terminal_id)` in terminal.rs's handle_kill), so
-    // the ping/pong gate deterministically orders retirement before the
-    // replay. (A direct `registry.kill()` would leave retirement to the
-    // async pty exit hook -- racy, and the red test must observe a RETIRED
-    // binding to distinguish retired-inclusive from live-only guard 3b.)
-    ws.send(WsMessage::Text(
-        json!({"type": "terminal.kill", "terminalId": codex_tid}).to_string(),
-    ))
-    .await
-    .expect("send terminal.kill");
-    ws.send(WsMessage::Text(json!({"type": "ping"}).to_string()))
-        .await
-        .expect("send ping");
-    let _pong = next_frame_of_type(&mut ws, "pong").await;
-
-    send_create(&mut ws, "req-codex-cand-3", "codex", json!({})).await;
-    let created3 = next_frame_of_type(&mut ws, "terminal.created").await;
-    let codex_tid3 = created3["terminalId"]
-        .as_str()
-        .expect("terminalId")
-        .to_string();
-    // Replay the SAME candidate (THREAD_A, its genuine rollout) onto the
-    // fresh pane: WARN + ignore, nothing sent back, tid3 stays unbound -- a
-    // retired binding still blocks a DIFFERENT terminal's claim (ledger A8).
-    send_candidate_expect_silence(&mut ws, &codex_tid3, THREAD_A, &rollout_a).await;
-    assert_eq!(
-        registry_resume_id(&registry, &codex_tid3),
-        None,
-        "a DEAD pane's session identity must never be claimable by a fresh terminal"
-    );
-
-    // ---- Subsequent restore create builds `codex ... resume <id>` ----
-    // (codex_tid was already killed in the dead-pane phase above.)
-    // Per-phase capture path (precedent: codex_session_ref_resume.rs's
-    // `capture_for(phase)`): the earlier fresh codex spawns (tid2/tid3) hold
-    // the ORIGINAL path in their env and may write it late -- a shared path
-    // would let a stale fresh-create argv shadow the restore argv.
-    let capture_restore = std::env::temp_dir().join(format!(
-        "codex-candidate-argv-restore-{}.txt",
-        std::process::id()
-    ));
-    let _ = std::fs::remove_file(&capture_restore);
-    std::env::set_var("CODEX_ARGV_CAPTURE_PATH", &capture_restore);
-    send_create(
-        &mut ws,
-        "req-codex-cand-restore",
-        "codex",
-        json!({ "restore": true, "sessionRef": { "provider": "codex", "sessionId": THREAD_A } }),
-    )
-    .await;
-    let restored = next_frame_of_type(&mut ws, "terminal.created").await;
-    let restored_tid = restored["terminalId"]
-        .as_str()
-        .expect("terminalId")
-        .to_string();
-    let argv = wait_for_captured_argv(&capture_restore);
-    let pos = argv.iter().position(|a| a == "resume");
-    assert!(
-        pos.is_some_and(|p| argv.get(p + 1).map(String::as_str) == Some(THREAD_A)),
-        "restore create must spawn `codex ... resume {THREAD_A}`: {argv:?}"
-    );
-
-    registry.kill(&restored_tid);
-    registry.kill(&codex_tid2);
-    registry.kill(&codex_tid3);
-    registry.kill(&claude_tid);
-    std::env::remove_var("CODEX_HOME");
-    std::env::remove_var("CODEX_ARGV_CAPTURE_PATH");
-    std::fs::remove_dir_all(&ledger_dir).ok();
-}
diff --git a/crates/freshell-ws/tests/codex_locator_activity.rs b/crates/freshell-ws/tests/codex_locator_activity.rs
index 31dbc09e4..9657bf3c0 100644
--- a/crates/freshell-ws/tests/codex_locator_activity.rs
+++ b/crates/freshell-ws/tests/codex_locator_activity.rs
@@ -20,7 +20,7 @@ use std::time::Duration;
 use tokio_tungstenite::tungstenite::Message as WsMessage;
 
 /// Fake codex: records argv to $CODEX_ARGV_CAPTURE_PATH (atomic tmp+mv) then
-/// sleeps. Copied from tests/codex_candidate_persisted.rs.
+/// sleeps. Copied from the (retired) tests/codex_candidate_persisted.rs.
 #[cfg(unix)]
 fn write_fake_codex() -> std::path::PathBuf {
     let script_path = std::env::temp_dir().join(format!(

From 78a57da7ef00f2a9b4ca23cf421aa2481a1913bd Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:32:28 -0700
Subject: [PATCH 55/87] test: stabilize recover-my-panes unit/integration
 coverage (B3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Task 7 checkpoint: full coordinated suite surfaced 7 App-rendering
suites (25 tests) failing with '[vitest] No "getRecoveryInventory"
export is defined on the @/lib/api mock' — the same Task 6 fallout
pattern (App now mounts RecoveryOfferPanel, which imports
getRecoveryInventory from @/lib/api and
getCurrentTabRegistryClientInstanceId from @/store/tabRegistrySync).
Task 6 patched the 11 App unit suites but missed these e2e suites and
the visible-first hydration harness.

Fix: extend the existing explicit vi.mock factories with the same
plain-async non-recoverable inventory stub used in Task 6 (not
vi.fn().mockResolvedValue, so vi.resetAllMocks() can't wipe it):
- test/e2e/{auth-required-bootstrap-flow,mobile-sidebar-fullwidth-flow,
  open-tab-session-sidebar-visibility,pane-header-runtime-meta-flow,
  sidebar-refresh-dom-stability,terminal-font-settings}.test.tsx
- test/e2e/mobile-sidebar-fullwidth-flow: also add
  getCurrentTabRegistryClientInstanceId to its tabRegistrySync factory
- test/helpers/visible-first/app-hydration-harness.tsx: add
  getRecoveryInventory + isTransientRequestFailure (App imports the
  latter directly; the harness doMock replaces the whole module)

Mock factories only; no test assertions or production code changed.
Full coordinated suite now green (exit 0), cargo fmt/clippy/test green.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 test/e2e/auth-required-bootstrap-flow.test.tsx        | 1 +
 test/e2e/mobile-sidebar-fullwidth-flow.test.tsx       | 2 ++
 test/e2e/open-tab-session-sidebar-visibility.test.tsx | 1 +
 test/e2e/pane-header-runtime-meta-flow.test.tsx       | 1 +
 test/e2e/sidebar-refresh-dom-stability.test.tsx       | 1 +
 test/e2e/terminal-font-settings.test.tsx              | 1 +
 test/helpers/visible-first/app-hydration-harness.tsx  | 2 ++
 7 files changed, 9 insertions(+)

diff --git a/test/e2e/auth-required-bootstrap-flow.test.tsx b/test/e2e/auth-required-bootstrap-flow.test.tsx
index bae6e7ca6..c2968ccac 100644
--- a/test/e2e/auth-required-bootstrap-flow.test.tsx
+++ b/test/e2e/auth-required-bootstrap-flow.test.tsx
@@ -49,6 +49,7 @@ vi.mock('@/lib/ws-client', () => ({
 }))
 
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => mockApiGet(url),
     patch: vi.fn().mockResolvedValue({}),
diff --git a/test/e2e/mobile-sidebar-fullwidth-flow.test.tsx b/test/e2e/mobile-sidebar-fullwidth-flow.test.tsx
index 20aa4dc33..394ed0c85 100644
--- a/test/e2e/mobile-sidebar-fullwidth-flow.test.tsx
+++ b/test/e2e/mobile-sidebar-fullwidth-flow.test.tsx
@@ -32,6 +32,7 @@ vi.mock('@/lib/ws-client', () => ({
 }))
 
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => mockApiGet(url),
     patch: vi.fn().mockResolvedValue({}),
@@ -72,6 +73,7 @@ vi.mock('@/hooks/useTheme', () => ({
 
 vi.mock('@/store/tabRegistrySync', () => ({
   startTabRegistrySync: () => () => {},
+  getCurrentTabRegistryClientInstanceId: () => 'test-client-instance',
 }))
 
 vi.mock('@/components/SetupWizard', () => ({
diff --git a/test/e2e/open-tab-session-sidebar-visibility.test.tsx b/test/e2e/open-tab-session-sidebar-visibility.test.tsx
index 12c4a452a..3e156c55c 100644
--- a/test/e2e/open-tab-session-sidebar-visibility.test.tsx
+++ b/test/e2e/open-tab-session-sidebar-visibility.test.tsx
@@ -110,6 +110,7 @@ vi.mock('@/lib/ws-client', () => ({
 }))
 
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => apiGet(url),
     patch: vi.fn().mockResolvedValue({}),
diff --git a/test/e2e/pane-header-runtime-meta-flow.test.tsx b/test/e2e/pane-header-runtime-meta-flow.test.tsx
index 14c56fae3..943925b4d 100644
--- a/test/e2e/pane-header-runtime-meta-flow.test.tsx
+++ b/test/e2e/pane-header-runtime-meta-flow.test.tsx
@@ -75,6 +75,7 @@ vi.mock('@/lib/ws-client', () => ({
 }))
 
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => apiGet(url),
     patch: vi.fn().mockResolvedValue({}),
diff --git a/test/e2e/sidebar-refresh-dom-stability.test.tsx b/test/e2e/sidebar-refresh-dom-stability.test.tsx
index 1f9d66ab7..a91d233bb 100644
--- a/test/e2e/sidebar-refresh-dom-stability.test.tsx
+++ b/test/e2e/sidebar-refresh-dom-stability.test.tsx
@@ -86,6 +86,7 @@ vi.mock('@/lib/ws-client', () => ({
 }))
 
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => apiGet(url),
     patch: vi.fn().mockResolvedValue({}),
diff --git a/test/e2e/terminal-font-settings.test.tsx b/test/e2e/terminal-font-settings.test.tsx
index 399b44e9c..abbb88523 100644
--- a/test/e2e/terminal-font-settings.test.tsx
+++ b/test/e2e/terminal-font-settings.test.tsx
@@ -54,6 +54,7 @@ vi.mock('@/lib/ws-client', () => ({
 }))
 
 vi.mock('@/lib/api', () => ({
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   api: {
     get: (url: string) => mockApiGet(url),
     patch: vi.fn().mockResolvedValue({}),
diff --git a/test/helpers/visible-first/app-hydration-harness.tsx b/test/helpers/visible-first/app-hydration-harness.tsx
index 0b9f80f51..232092cba 100644
--- a/test/helpers/visible-first/app-hydration-harness.tsx
+++ b/test/helpers/visible-first/app-hydration-harness.tsx
@@ -307,6 +307,8 @@ export async function createAppHydrationHarness(options: AppHydrationHarnessOpti
     getWsClient: () => wsState.ws,
   }))
   vi.doMock('@/lib/api', () => ({
+    getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
+    isTransientRequestFailure: () => false,
     api: {
       get: (path: string) => resolveResponse(path),
       post: (path: string) => resolveResponse(path),

From f31b9c0af3612b020506cdfd657c9a1f00a6bdf4 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:34:17 -0700
Subject: [PATCH 56/87] test(e2e): fake codex terminal fixture that writes a
 real gated rollout JSONL

---
 .../fixtures/fake-codex-terminal.mjs          | 89 +++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 test/e2e-browser/fixtures/fake-codex-terminal.mjs

diff --git a/test/e2e-browser/fixtures/fake-codex-terminal.mjs b/test/e2e-browser/fixtures/fake-codex-terminal.mjs
new file mode 100644
index 000000000..dba97a1a9
--- /dev/null
+++ b/test/e2e-browser/fixtures/fake-codex-terminal.mjs
@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Fake codex TERMINAL CLI for the rollout-locator e2e specs (Lane B2).
+// Mirrors fake-opencode-terminal.mjs's contract, on codex's substrate: the
+// identity artifact is a rollout JSONL under CODEX_HOME/sessions whose FIRST
+// line is the session_meta ownership record (payload.id — never the
+// filename — is the identity; payload.cwd is the locator's disambiguator).
+// - fresh: prints `codex> `; on the FIRST stdin chunk containing an Enter
+//   (CR/LF) writes the rollout (gated by
+//   FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH when set) and prints
+//   `codex: session <uuid> started`. Enter-gating mirrors real codex
+//   (Premise 7: the rollout materializes only at the first user prompt) and
+//   keeps the fixture on the safe side of the server's first-submit
+//   known_files re-snapshot, which completes before the Enter reaches this
+//   process.
+// - resume (`resume` ANYWHERE in argv — resumeArgs are appended LAST after
+//   `-c` overrides): prints `codex: resumed session <id>`, writes nothing.
+// - argv mirrored to FAKE_CODEX_TERMINAL_ARGV_LOG as JSONL.
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+const argv = process.argv.slice(2)
+
+function appendArgvLog() {
+  const logPath = process.env.FAKE_CODEX_TERMINAL_ARGV_LOG
+  if (!logPath) return
+  fs.mkdirSync(path.dirname(logPath), { recursive: true })
+  fs.appendFileSync(logPath, `${JSON.stringify({ pid: process.pid, t: Date.now(), argv })}\n`)
+}
+appendArgvLog()
+
+function codexSessionsDir() {
+  const home = process.env.CODEX_HOME && process.env.CODEX_HOME.length > 0
+    ? process.env.CODEX_HOME
+    : path.join(process.env.HOME ?? '', '.codex')
+  const now = new Date()
+  const yyyy = String(now.getUTCFullYear())
+  const mm = String(now.getUTCMonth() + 1).padStart(2, '0')
+  const dd = String(now.getUTCDate()).padStart(2, '0')
+  return path.join(home, 'sessions', yyyy, mm, dd)
+}
+
+function writeRollout(threadId) {
+  const now = new Date()
+  const ts = now.toISOString().slice(0, 19).replace(/:/g, '-')
+  const dir = codexSessionsDir()
+  fs.mkdirSync(dir, { recursive: true })
+  const file = path.join(dir, `rollout-${ts}-${threadId}.jsonl`)
+  const meta = {
+    timestamp: now.toISOString(),
+    type: 'session_meta',
+    payload: { id: threadId, cwd: process.cwd() },
+  }
+  fs.writeFileSync(file, `${JSON.stringify(meta)}\n`)
+}
+
+const resumeIndex = argv.indexOf('resume')
+if (resumeIndex !== -1) {
+  const sessionId = argv[resumeIndex + 1] ?? ''
+  process.stdout.write(`codex: resumed session ${sessionId}\r\n`)
+} else {
+  process.stdout.write('codex> \r\n')
+  let wrote = false
+  process.stdin.on('data', (chunk) => {
+    if (wrote) return
+    const s = String(chunk)
+    // Enter-anchored, like real codex (Premise 7): typing alone must not
+    // create the rollout — only the first Enter does.
+    if (!s.includes('\r') && !s.includes('\n')) return
+    wrote = true
+    const threadId = crypto.randomUUID()
+    const finish = () => {
+      writeRollout(threadId)
+      process.stdout.write(`codex: session ${threadId} started\r\n`)
+    }
+    const gate = process.env.FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH
+    if (gate) {
+      const poll = setInterval(() => {
+        if (fs.existsSync(gate)) {
+          clearInterval(poll)
+          finish()
+        }
+      }, 50)
+    } else {
+      finish()
+    }
+  })
+}
+process.stdin.resume()

From a5ce3c61b098e62eb99af5d4bd4f60ada2a6972d Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:36:14 -0700
Subject: [PATCH 57/87] =?UTF-8?q?fix(opencode):=20resume=20reapplies=20mod?=
 =?UTF-8?q?el/effort/cwd=20from=20the=20ledger=20record=20(P1.13=20=C2=A72?=
 =?UTF-8?q?.7b)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 crates/freshell-freshagent/src/opencode_ws.rs | 436 +++++++++++++++++-
 1 file changed, 429 insertions(+), 7 deletions(-)

diff --git a/crates/freshell-freshagent/src/opencode_ws.rs b/crates/freshell-freshagent/src/opencode_ws.rs
index 4e060df46..4e7ca4424 100644
--- a/crates/freshell-freshagent/src/opencode_ws.rs
+++ b/crates/freshell-freshagent/src/opencode_ws.rs
@@ -69,9 +69,10 @@ use freshell_opencode::{
     SdkProviderEvent, SessionSignal, SnapshotStatus,
 };
 use freshell_protocol::{
-    ErrorCode, ErrorMsg, FreshAgentAttach, FreshAgentCreate, FreshAgentCreated, FreshAgentEvent,
-    FreshAgentInterrupt, FreshAgentKill, FreshAgentKilled, FreshAgentSend, FreshAgentSendAccepted,
-    FreshAgentSessionMaterialized, ServerMessage, SessionLocator,
+    ErrorCode, ErrorMsg, FreshAgentAttach, FreshAgentCreate, FreshAgentCreateFailed,
+    FreshAgentCreated, FreshAgentEvent, FreshAgentInterrupt, FreshAgentKill, FreshAgentKilled,
+    FreshAgentSend, FreshAgentSendAccepted, FreshAgentSessionMaterialized, ServerMessage,
+    SessionLocator,
 };
 
 use crate::{
@@ -235,6 +236,20 @@ impl FreshOpencodeState {
         self.fresh_agent.broadcast(msg);
     }
 
+    /// Broadcast a `freshAgent.create.failed` frame (mirrors codex.rs's `fail_create`;
+    /// `ws-handler.ts:3388-3405`'s generic catch -- always `retryable: true`,
+    /// `ws-handler.ts:3403`).
+    fn fail_create(&self, request_id: &str, code: &str, message: &str) {
+        self.broadcast(&ServerMessage::FreshAgentCreateFailed(
+            FreshAgentCreateFailed {
+                code: code.to_string(),
+                message: message.to_string(),
+                request_id: request_id.to_string(),
+                retryable: Some(true),
+            },
+        ));
+    }
+
     fn send_error(&self, request_id: &Option<String>, code: &str, message: &str) {
         self.broadcast(&ServerMessage::Error(ErrorMsg {
             code: ErrorCode::InternalError,
@@ -280,6 +295,23 @@ impl FreshOpencodeState {
             FreshAgentCreateOutcome::Proceed(guard) => guard,
         };
 
+        // P1.13 (Task 8, V2/A4 -- THE P1.13 wall-pin mechanism): after a page reload
+        // the frozen client never sends `freshAgent.attach` -- its ONLY resume vehicle
+        // is `freshAgent.create{resumeSessionId: ses_*}` (persistMiddleware strips
+        // `sessionId`, gating both attach effects off). A create naming a durable
+        // `ses_*` id must REBIND that surviving session (mirroring codex/claude's
+        // resume-in-create), never mint a fresh `freshopencode-*` placeholder.
+        let resume_target = msg
+            .resume_session_id
+            .clone()
+            .or_else(|| msg.session_ref.as_ref().map(|r| r.session_id.clone()))
+            .filter(|id| id.starts_with("ses_"));
+        if let Some(durable_id) = resume_target {
+            self.handle_create_resume(request_id, durable_id, &msg)
+                .await;
+            return;
+        }
+
         let model = normalize_opencode_model(msg.model.as_deref());
         let effort = normalize_opencode_effort(model.as_deref(), msg.effort.as_deref());
         let placeholder = format!("freshopencode-{request_id}");
@@ -334,6 +366,91 @@ impl FreshOpencodeState {
 
     // ── freshAgent.send (WS) — materialize-or-send ─────────────────────────
 
+    /// The resume branch of `handle_create` (P1.13 Task 8, V2/A4): rebind the
+    /// surviving durable `ses_*` session instead of minting a `freshopencode-*`
+    /// placeholder. Routes through the SAME resume machinery `freshAgent.attach`
+    /// uses ([`Self::resume_durable_session`], which applies settings-from-ledger
+    /// and the V7/A10 `SETTINGS_RESET` gate), then answers `freshAgent.created`
+    /// with the durable id so the frozen client ends up re-keyed to the `ses_*`
+    /// identity. Mirrors codex's `handle_create_resume`: a resume target that is
+    /// genuinely gone (or an unreachable sidecar) fails the create loudly
+    /// (`freshAgent.create.failed`) -- never a silently-minted fresh session,
+    /// never a `lost_session_frame` (that shape is exclusive to `freshAgent.attach`).
+    async fn handle_create_resume(
+        &self,
+        request_id: String,
+        durable_id: String,
+        msg: &FreshAgentCreate,
+    ) {
+        // Already tracked locally (a live pane, or an earlier attach/create already
+        // rebound it)? Reuse it -- mirrors handle_attach's local-map-first lookup.
+        let existing = {
+            let guard = self.sessions.lock().await;
+            guard.get(&durable_id).cloned()
+        };
+        let session_arc = match existing {
+            Some(session_arc) => session_arc,
+            None => match self
+                .resume_durable_session(&durable_id, msg.cwd.as_deref())
+                .await
+            {
+                Ok(session_arc) => session_arc,
+                Err(ResumeOpencodeError::NotFound) => {
+                    self.fail_create(
+                        &request_id,
+                        "FRESH_AGENT_CREATE_FAILED",
+                        &format!("opencode session {durable_id} not found"),
+                    );
+                    return;
+                }
+                Err(ResumeOpencodeError::Manager(err)) => {
+                    self.fail_create(&request_id, "FRESH_AGENT_CREATE_FAILED", &err.to_string());
+                    return;
+                }
+            },
+        };
+
+        // Explicit client params on the create win over the ledger record (Task 5(d)
+        // precedence): merge msg over the resumed session's values BEFORE
+        // normalization, so an omitted param recovers the recorded value instead of
+        // being rewritten to the default.
+        {
+            let mut session = session_arc.lock().await;
+            let raw_model = msg.model.clone().or_else(|| session.model.clone());
+            let model = normalize_opencode_model(raw_model.as_deref());
+            let raw_effort = msg.effort.clone().or_else(|| session.effort.clone());
+            let effort = normalize_opencode_effort(model.as_deref(), raw_effort.as_deref());
+            session.model = model;
+            session.effort = effort;
+            if msg.cwd.is_some() {
+                session.cwd = msg.cwd.clone();
+            }
+        }
+
+        // requestId dedup cache: a duplicate create replays the DURABLE id (never a
+        // placeholder), keeping the reconnect-resend behavior intact.
+        self.create_dedup
+            .record_success(
+                &request_id,
+                OpencodeCreateRecord {
+                    placeholder_id: durable_id.clone(),
+                },
+            )
+            .await;
+
+        self.broadcast(&ServerMessage::FreshAgentCreated(FreshAgentCreated {
+            provider: PROVIDER.to_string(),
+            request_id,
+            runtime_provider: PROVIDER.to_string(),
+            session_id: durable_id.clone(),
+            session_type: SESSION_TYPE.to_string(),
+            session_ref: Some(SessionLocator {
+                provider: PROVIDER.to_string(),
+                session_id: durable_id,
+            }),
+        }));
+    }
+
     /// Handle a `freshAgent.send` for opencode: `materializeOrSend` (`adapter.ts:324-361`).
     /// Creates the durable `ses_*` session ONLY if this session has not materialized yet
     /// (the continuity fix), broadcasts `freshAgent.session.materialized` exactly once,
@@ -797,10 +914,49 @@ impl FreshOpencodeState {
             }
             Err(err) => return Err(ResumeOpencodeError::Manager(err)),
         };
-        let _ = info;
+        // P1.13 (Task 8): recover this session's recorded settings snapshot, gated
+        // per V7/A10 (same vocabulary + gating as codex.rs's Task 5 site).
+        let sink = self.identity_sink();
+        let recovered = sink
+            .as_ref()
+            .and_then(|s| s.load_settings(PROVIDER, session_id));
+        if recovered.is_none()
+            && sink
+                .as_ref()
+                .is_some_and(|s| s.was_recorded(PROVIDER, session_id))
+        {
+            // Recorded before, unrecoverable now -- the genuine anomaly. Never-recorded
+            // sessions (pre-ship / serve-known-but-ledger-unknown, the ROUTINE attach
+            // population per this handler's own doc above) resume silently with defaults.
+            tracing::warn!(session = %session_id, "freshagent.opencode.settings_record_unrecoverable");
+            self.emit_fresh_agent_error(
+                session_id,
+                "SETTINGS_RESET",
+                "Session settings could not be recovered after restart - the agent is running with default model and effort. Reconfirm your settings.",
+            );
+        }
+        let rec = recovered.clone().unwrap_or_default();
+
+        // Stop discarding the serve body (the old `let _ = info;`): its `directory`
+        // is the session's REAL working directory -- a better cwd than the attach
+        // message's, though the ledger record's still wins.
+        let serve_dir = info
+            .get("directory")
+            .and_then(Value::as_str)
+            .filter(|d| !d.is_empty())
+            .map(str::to_string);
+        let cwd = rec
+            .cwd
+            .clone()
+            .or(serve_dir)
+            .or_else(|| cwd.map(str::to_string));
 
-        let mut session =
-            OpencodeSession::new(session_id.to_string(), cwd.map(str::to_string), None, None);
+        let mut session = OpencodeSession::new(
+            session_id.to_string(),
+            cwd.clone(),
+            rec.model.clone(),
+            rec.effort.clone(),
+        );
         session.real_session_id = Some(session_id.to_string());
         session.serve_bridge = Some(self.spawn_serve_bridge(
             manager,
@@ -814,6 +970,39 @@ impl FreshOpencodeState {
             .await
             .insert(session_id.to_string(), session_arc.clone());
 
+        // P1.13 (Task 8): refresh the binding row after a successful resume -- AWAITED
+        // (durable-before-answer), and ONLY when a record was actually recovered: never
+        // launder a defaults row for a never-recorded session (V7).
+        if recovered.is_some() {
+            if let Some(sink) = sink {
+                if let Err(e) = sink
+                    .record_binding(crate::identity_sink::FreshAgentBindingUpsert {
+                        provider: PROVIDER.into(),
+                        session_id: session_id.to_string(),
+                        mode: SESSION_TYPE.into(),
+                        create_request_id: None,
+                        resolves_pending: None,
+                        supersedes: None,
+                        settings: crate::identity_sink::FreshAgentSettings {
+                            model: rec.model.clone(),
+                            sandbox: None,
+                            permission_mode: None,
+                            effort: rec.effort.clone(),
+                            cwd,
+                        },
+                    })
+                    .await
+                {
+                    tracing::warn!(error = %e, session = %session_id, "freshagent.opencode.binding_write_failed");
+                    self.emit_fresh_agent_error(
+                        session_id,
+                        "LEDGER_WRITE_FAILED",
+                        "Failed to persist this session's resume record - settings may not survive a server restart.",
+                    );
+                }
+            }
+        }
+
         Ok(session_arc)
     }
 
@@ -1188,8 +1377,11 @@ mod tests {
                 ]))
                 .unwrap()
             } else {
+                // Like the real serve, `GET /session/:id` carries the session's own
+                // `directory` -- Task 8's resume path consumes it instead of
+                // discarding the body (`let _ = info;`).
                 serde_json::to_vec(
-                    &json!({ "id": id, "title": "materialized session", "time": { "updated": 5 } }),
+                    &json!({ "id": id, "title": "materialized session", "time": { "updated": 5 }, "directory": "/serve/dir" }),
                 )
                 .unwrap()
             };
@@ -1996,6 +2188,236 @@ mod tests {
         assert_eq!(b.settings.effort.as_deref(), Some("low"));
     }
 
+    // ── P1.13 Task 8: settings-from-ledger resume (attach + create-with-resume) ──
+
+    /// The durable `ses_*` id [`RealisticServeHttp`] mints for its FIRST
+    /// `POST /session` -- the one durable serve session the Task 8 harness
+    /// pre-creates.
+    const DURABLE_ID: &str = "ses_1";
+
+    /// Task 8 harness: a [`RealisticServeHttp`]-backed state (same fakes as the
+    /// donor test `attach_unknown_session_resumes_a_durable_serve_session_not_in_the_local_map`)
+    /// with ONE durable serve session pre-created ([`DURABLE_ID`]) that the local WS
+    /// session map has never heard of, plus a bus receiver subscribed BEFORE any
+    /// handler runs. Each test wires its own identity-sink fixture.
+    async fn state_with_durable_serve_session(
+    ) -> (FreshOpencodeState, tokio::sync::broadcast::Receiver<String>) {
+        let (tx, rx) = tokio::sync::broadcast::channel::<String>(64);
+        let fresh_agent = FreshAgentState::new(Arc::new("tok".to_string()), Arc::new(tx));
+        let deps = ServeDeps {
+            spawner: Arc::new(TrackedSpawner {
+                killed: Arc::new(std::sync::atomic::AtomicBool::new(false)),
+            }),
+            http: Arc::new(RealisticServeHttp::new()),
+            ports: Arc::new(FakeAllocator),
+            events: Arc::new(NoopEventSource),
+        };
+        let manager = OpencodeServeManager::new(deps, ServeConfig::default());
+        manager
+            .ensure_started()
+            .await
+            .expect("healthy fake serve starts");
+        let created = manager
+            .create_session(None, None, None)
+            .await
+            .expect("create_session");
+        assert_eq!(
+            created.id, DURABLE_ID,
+            "sanity: RealisticServeHttp mints ses_1 for its first create"
+        );
+        fresh_agent.set_manager_for_test(manager).await;
+        let st = FreshOpencodeState::new(fresh_agent);
+        assert!(
+            !st.sessions.lock().await.contains_key(DURABLE_ID),
+            "not tracked locally yet"
+        );
+        (st, rx)
+    }
+
+    #[tokio::test]
+    async fn resume_durable_session_reapplies_settings_from_ledger() {
+        // Same RealisticServeHttp harness as the donor test.
+        let (state, _rx) = state_with_durable_serve_session().await;
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        fake.seed(
+            "opencode",
+            DURABLE_ID,
+            crate::identity_sink::FreshAgentSettings {
+                model: Some("big-model".into()),
+                sandbox: None,
+                permission_mode: None,
+                effort: Some("high".into()),
+                cwd: Some("/real/project".into()),
+            },
+        );
+        state.set_identity_sink(fake);
+
+        // Drive the same attach the donor test drives -- with a COMPETING cwd on
+        // the attach message, so the cwd assertion below proves precedence rather
+        // than absence.
+        let mut attach = attach_msg(DURABLE_ID);
+        attach.cwd = Some("/attach/cwd".to_string());
+        state.handle_attach(attach).await;
+
+        let sessions = state.sessions.lock().await;
+        let s = sessions.get(DURABLE_ID).expect("resumed").lock().await;
+        assert_eq!(s.model.as_deref(), Some("big-model"));
+        assert_eq!(s.effort.as_deref(), Some("high"));
+        assert_eq!(
+            s.cwd.as_deref(),
+            Some("/real/project"),
+            "cwd from the record, not the attach message"
+        );
+    }
+
+    #[tokio::test]
+    async fn resume_without_record_is_silent_and_uses_serve_directory() {
+        // Same harness; NO seed (never-recorded session -- the ROUTINE case, V7:
+        // handle_attach's own doc describes this attach population).
+        let (state, mut rx) = state_with_durable_serve_session().await;
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        state.set_identity_sink(fake.clone());
+
+        state.handle_attach(attach_msg(DURABLE_ID)).await;
+
+        // RealisticServeHttp's GET /session/:id directory is now used instead of
+        // being discarded.
+        {
+            let sessions = state.sessions.lock().await;
+            let s = sessions.get(DURABLE_ID).expect("resumed").lock().await;
+            assert_eq!(
+                s.cwd.as_deref(),
+                Some("/serve/dir"),
+                "the serve GET /session/:id body's directory must be used, not discarded"
+            );
+        }
+
+        // NO SETTINGS_RESET frame was broadcast (bounded bus drain -- Task 5 pattern).
+        while let Ok(frame) =
+            tokio::time::timeout(std::time::Duration::from_secs(1), rx.recv()).await
+        {
+            let Ok(text) = frame else { break };
+            assert!(
+                !text.contains("SETTINGS_RESET"),
+                "never-recorded resume must stay silent"
+            );
+        }
+
+        // NO refresh binding was written for the session (no defaults laundering).
+        assert!(
+            !fake
+                .bindings
+                .lock()
+                .unwrap()
+                .iter()
+                .any(|b| b.session_id == DURABLE_ID),
+            "a load_settings miss must not write a defaults row"
+        );
+    }
+
+    #[tokio::test]
+    async fn resume_with_prior_record_but_unrecoverable_settings_alarms() {
+        // fake.seed_recorded_only("opencode", DURABLE_ID) -- was_recorded=true,
+        // load_settings=None. The genuine anomaly: the only case that alarms (V7/A10).
+        let (state, mut rx) = state_with_durable_serve_session().await;
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        fake.seed_recorded_only("opencode", DURABLE_ID);
+        state.set_identity_sink(fake);
+
+        state.handle_attach(attach_msg(DURABLE_ID)).await;
+
+        let mut found = false;
+        while let Ok(frame) =
+            tokio::time::timeout(std::time::Duration::from_secs(2), rx.recv()).await
+        {
+            let Ok(text) = frame else { break };
+            if text.contains("SETTINGS_RESET") {
+                let frame: serde_json::Value = serde_json::from_str(&text).unwrap();
+                // Top-level sessionType/provider (locator resolution) + a
+                // user-facing message (the banner shows the message, not the code).
+                assert_eq!(frame["sessionType"], "freshopencode");
+                assert_eq!(frame["provider"], "opencode");
+                assert_eq!(frame["event"]["code"], "SETTINGS_RESET");
+                assert!(frame["event"]["message"]
+                    .as_str()
+                    .unwrap()
+                    .contains("Reconfirm your settings"));
+                found = true;
+                break;
+            }
+        }
+        assert!(
+            found,
+            "recorded-but-unrecoverable resume must broadcast SETTINGS_RESET"
+        );
+    }
+
+    #[tokio::test]
+    async fn create_with_resume_session_id_rebinds_the_durable_session() {
+        // V2/A4: the frozen client's ONLY post-reload resume vehicle is
+        // freshAgent.create{resumeSessionId: ses_*} -- donor shape: codex's
+        // handle_create_with_resume_session_id_resumes_the_same_thread.
+        let (state, mut rx) = state_with_durable_serve_session().await;
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        fake.seed(
+            "opencode",
+            DURABLE_ID,
+            crate::identity_sink::FreshAgentSettings {
+                model: Some("big-model".into()),
+                sandbox: None,
+                permission_mode: None,
+                effort: Some("high".into()),
+                cwd: Some("/real/project".into()),
+            },
+        );
+        state.set_identity_sink(fake);
+
+        let mut create = create_msg("req-resume-oc");
+        create.resume_session_id = Some(DURABLE_ID.to_string());
+        state.handle_create(create).await;
+
+        let sessions = state.sessions.lock().await;
+        assert!(
+            sessions.contains_key(DURABLE_ID),
+            "rebound to the surviving ses_*"
+        );
+        let s = sessions.get(DURABLE_ID).unwrap().lock().await;
+        assert_eq!(
+            s.model.as_deref(),
+            Some("big-model"),
+            "settings-from-ledger applied on the create path"
+        );
+        drop(s);
+        drop(sessions);
+
+        // And the FreshAgentCreated broadcast answered with the ses_* id (not a
+        // freshopencode-* placeholder) -- capture it via the bus receiver.
+        let mut created_frame: Option<serde_json::Value> = None;
+        while let Ok(frame) =
+            tokio::time::timeout(std::time::Duration::from_secs(1), rx.recv()).await
+        {
+            let Ok(text) = frame else { break };
+            let frame: serde_json::Value = serde_json::from_str(&text).unwrap();
+            if frame["type"] == "freshAgent.created" {
+                created_frame = Some(frame);
+                break;
+            }
+        }
+        let created = created_frame.expect("a freshAgent.created frame was broadcast");
+        assert_eq!(
+            created["sessionId"], DURABLE_ID,
+            "created must answer with the durable ses_* id, not a placeholder"
+        );
+        assert_eq!(created["sessionRef"]["sessionId"], DURABLE_ID);
+        assert!(
+            !created["sessionId"]
+                .as_str()
+                .unwrap()
+                .starts_with("freshopencode-"),
+            "never a freshopencode-* placeholder on a resume-create"
+        );
+    }
+
     // ── PR-3: serve-stream bridge (status / turn.complete gating) ─────────
 
     /// Build a [`FreshOpencodeState`] on top of [`state_with_status_poll`], returning it

From 8d396fd87dc1d0c2bd328507810bf2afe5d676e8 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:38:32 -0700
Subject: [PATCH 58/87] feat(client): reconcile on ready-with-capability;
 census becomes the capability-gated fallback (F3/F4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

On every ready whose capabilities.paneReconcileV1 === true, App activates
pane-reconcile mode (paneReconcileActiveRef + setPaneReconcileActive),
builds a pane.reconcile.request from the store and sends it, folding only
results whose reconcileId it minted (fold-ownership rule; foreign results
are skipped). The destructive half of the legacy terminal.inventory census
(clearDeadTerminals + the restore/fresh-recovery arming walk) now runs ONLY
when the capability is absent — setLiveTerminalIds and
setServerRestarted(false) stay unconditional (council rule 11: the census
remains as the capability-gated fallback, not deleted).

A result is not guaranteed (A2): a cardinality violation, a malformed
result, or a correlated error frame (requestId === reconcileId, e.g.
RECONCILE_TOO_LARGE / RECONCILE_UNAVAILABLE) is TERMINAL for that
reconcile — loud console.error, deactivate for this inventory cycle, and
run the legacy census once from the CACHED liveTerminalIds (inventory
always precedes any reconcile result on the real wire). No wall-clock
timeout — the request is re-sent on EVERY ready, so reconnect covers loss
windows.

terminal-restore.ts exports setPaneReconcileActive(v); while active,
consumeTerminalRestoreRequestId / consumeTerminalFreshRecoveryRequest
report not-armed via a first-line early return that preserves armed
entries, so deactivation restores the exact previous latch behavior.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 src/App.tsx                                   | 159 +++++--
 src/lib/terminal-restore.ts                   |  16 +
 .../App.reconcile-adoption.test.tsx           | 432 ++++++++++++++++++
 .../components/App.restart-signals.test.tsx   |   2 +
 .../components/App.ws-bootstrap.test.tsx      |   2 +
 test/unit/lib/terminal-restore.test.ts        |  39 ++
 6 files changed, 619 insertions(+), 31 deletions(-)
 create mode 100644 test/unit/client/components/App.reconcile-adoption.test.tsx

diff --git a/src/App.tsx b/src/App.tsx
index d7392cf88..a2ca6f986 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -17,7 +17,8 @@ import {
 } from '@/store/sessionsThunks'
 import { fetchTerminalDirectoryWindow } from '@/store/terminalDirectoryThunks'
 import { createTerminalInvalidationHandler } from '@/lib/terminal-invalidation-handler'
-import { collectTerminalPaneTargets } from '@/lib/pane-reconcile'
+import { buildReconcileRequest, collectTerminalPaneTargets, foldVerdicts } from '@/lib/pane-reconcile'
+import { PaneReconcileResultSchema, type PaneReconcileRequest } from '@shared/ws-protocol'
 import { getShareAction, ensureShareUrlToken, isRemoteAccessEnabledStatus } from '@/lib/share-utils'
 import { getWsClient } from '@/lib/ws-client'
 import { collectSessionLocatorsFromTabs, getSessionsForHello } from '@/lib/session-utils'
@@ -62,7 +63,7 @@ import { updateSettingsLocal } from '@/store/settingsSlice'
 
 import { setTerminalMetaSnapshot, upsertTerminalMeta, removeTerminalMeta } from '@/store/terminalMetaSlice'
 import { clearDeadTerminals, clearTerminalLiveHandles } from '@/store/panesSlice'
-import { addTerminalFreshRecoveryRequestId, addTerminalRestoreRequestId } from '@/lib/terminal-restore'
+import { addTerminalFreshRecoveryRequestId, addTerminalRestoreRequestId, setPaneReconcileActive } from '@/lib/terminal-restore'
 import { reconcileTerminalSessionAssociation } from '@/lib/terminal-session-association'
 import { setCodexActivitySnapshot, upsertCodexActivity, removeCodexActivity, resetCodexActivity } from '@/store/codexActivitySlice'
 import { setClaudeActivitySnapshot, upsertClaudeActivity, removeClaudeActivity, resetClaudeActivity } from '@/store/claudeActivitySlice'
@@ -152,6 +153,10 @@ const ReadyMessageSchema = z.object({
   timestamp: z.string(),
   serverInstanceId: z.string().min(1),
   bootId: z.string().min(1).optional(),
+  // Server capability ack (present iff our hello opted in). Deliberately a
+  // loose record: an unexpected capabilities shape must never fail the WHOLE
+  // ready frame and silently disable restart detection.
+  capabilities: z.record(z.string(), z.unknown()).optional(),
 })
 
 export default function App() {
@@ -245,6 +250,13 @@ export default function App() {
   const amplifierActivityOrderRef = useRef(0)
   const opencodeActivityOrderRef = useRef(0)
   const copiedResetTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  // pane.reconcile adoption: capability of the CURRENT connection (re-captured
+  // on every ready) and the reconcile request App itself minted. Fold-ownership
+  // rule: App folds ONLY results whose reconcileId it minted, skipping foreign
+  // ones (TerminalView exhaustion auto-resolve and the warming-banner Retry
+  // mint their own).
+  const paneReconcileActiveRef = useRef(false)
+  const pendingReconcileRef = useRef<PaneReconcileRequest | null>(null)
   const fullscreenTouchStartYRef = useRef<number | null>(null)
   const isLandscapeTerminalView = isMobile && isLandscape && view === 'terminal'
   const shareAccessUrl = networkStatus?.accessUrl
@@ -843,6 +855,62 @@ export default function App() {
         }
       }
 
+      // The destructive half of the legacy inventory census: wipe pane handles
+      // whose terminals are not in liveIds, then re-arm the explicit recovery
+      // latches for the regenerated createRequestIds. Shared by the
+      // capability-absent inventory path and the reconcile fallback path.
+      const runDestructiveTerminalCensus = (liveIds: string[]) => {
+        dispatch(clearDeadTerminals({ liveTerminalIds: liveIds }))
+        // Register regenerated createRequestIds with the correct explicit
+        // recovery path after stale terminal handles are cleared.
+        const layouts = appStore.getState().panes.layouts
+        const fallbackAttempts = appStore.getState().panes.restoreFallbackAttemptsByPane || {}
+        for (const [tabId, layout] of Object.entries(layouts)) {
+          ;(function walk(node: any) {
+            if (!node) return
+            if (node.type === 'leaf') {
+              if (node.content?.kind === 'terminal' && node.content.status === 'creating' && node.content.createRequestId) {
+                const fallbackAttempt = fallbackAttempts[tabId]?.[node.id]
+                if (
+                  fallbackAttempt?.requestId === node.content.createRequestId
+                  && !node.content.sessionRef
+                ) {
+                  addTerminalFreshRecoveryRequestId(
+                    node.content.createRequestId,
+                    'fresh_after_restore_unavailable',
+                  )
+                } else if (node.content.sessionRef) {
+                  addTerminalRestoreRequestId(node.content.createRequestId)
+                }
+              }
+              return
+            }
+            if (node.type === 'split' && Array.isArray(node.children)) {
+              for (const child of node.children) walk(child)
+            }
+          })(layout)
+        }
+      }
+
+      // Terminal failure of a reconcile App minted (cardinality violation or a
+      // correlated server error frame like RECONCILE_TOO_LARGE /
+      // RECONCILE_UNAVAILABLE): deactivate reconcile for THIS inventory cycle
+      // (re-set true on the next ready) and run the legacy census once from
+      // the CACHED liveTerminalIds — on the real wire terminal.inventory
+      // ALWAYS precedes any reconcile result, so the cache is populated.
+      // Deliberately NO wall-clock timeout on the pending reconcile: it would
+      // false-trip on legitimate deferrals; the request is re-sent on every
+      // ready, so reconnect covers loss windows.
+      const fallBackToLegacyCensus = () => {
+        pendingReconcileRef.current = null
+        paneReconcileActiveRef.current = false
+        setPaneReconcileActive(false)
+        const cachedLiveIds = appStore.getState().connection.liveTerminalIds
+        if (cachedLiveIds) {
+          runDestructiveTerminalCensus(cachedLiveIds)
+        }
+      }
+
       const terminalInvalidationHandler = createTerminalInvalidationHandler({
         dispatch: (action) => appStore.dispatch(action as any),
         upsertTerminalMeta,
@@ -943,6 +1011,22 @@ export default function App() {
             if (serverRestarted || instanceChanged || firstReadyBaseline) {
               dispatch(resetCompletionDedupeBaselines())
             }
+            // pane.reconcile adoption: capability re-captured per connection,
+            // and the request re-sent on EVERY ready — a result is not
+            // guaranteed (deferral, drop, error frame), so reconnect covers
+            // loss windows. While active, the destructive inventory census is
+            // gated off and the terminal-restore latches report not-armed.
+            const paneReconcile = ready.data.capabilities?.paneReconcileV1 === true
+            paneReconcileActiveRef.current = paneReconcile
+            setPaneReconcileActive(paneReconcile)
+            pendingReconcileRef.current = null
+            if (paneReconcile) {
+              const req = buildReconcileRequest(appStore.getState())
+              if (req) {
+                pendingReconcileRef.current = req
+                ws.send(req)
+              }
+            }
           }
           dispatch(resetWsSnapshotReceived())
           // If App registered late and missed a prior invalidation, a fresh HTTP baseline
@@ -955,6 +1039,41 @@ export default function App() {
           lastSessionsRevision = -1
           void recoverMissingStartupState()
         }
+        if (msg.type === 'pane.reconcile.result') {
+          const pending = pendingReconcileRef.current
+          // Fold-ownership rule: App folds ONLY results whose reconcileId it
+          // minted; foreign ones belong to another requester (TerminalView
+          // exhaustion auto-resolve, warming-banner Retry) — skip silently.
+          if (!pending || (msg as { reconcileId?: unknown }).reconcileId !== pending.reconcileId) {
+            return
+          }
+          pendingReconcileRef.current = null
+          const parsed = PaneReconcileResultSchema.safeParse(msg)
+          if (!parsed.success) {
+            console.error('[reconcile] malformed result — falling back to legacy census', parsed.error.issues)
+            fallBackToLegacyCensus()
+            return
+          }
+          const outcome = foldVerdicts(dispatch, pending, parsed.data)
+          if (outcome.cardinalityViolation) {
+            console.error('[reconcile] cardinality violation — falling back to legacy census')
+            fallBackToLegacyCensus()
+          }
+          return
+        }
+        if (msg.type === 'error') {
+          const pending = pendingReconcileRef.current
+          if (pending && (msg as { requestId?: unknown }).requestId === pending.reconcileId) {
+            // A RESULT IS NOT GUARANTEED: the server has live-socket
+            // error-instead-of-result paths (RECONCILE_TOO_LARGE,
+            // RECONCILE_UNAVAILABLE) carrying requestId = reconcileId. Such an
+            // error is TERMINAL for this reconcile — fall back to the legacy
+            // census from the cached inventory (which always precedes the
+            // result on the real wire).
+            console.error('[reconcile] server error — falling back to legacy census', (msg as { code?: unknown }).code)
+            fallBackToLegacyCensus()
+          }
+        }
         if (msg.type === 'sessions.changed') {
           const rev = typeof msg.revision === 'number' ? msg.revision : -1
           if (rev > lastSessionsRevision) {
@@ -1022,35 +1141,13 @@ export default function App() {
             .map((t: any) => t.terminalId as string)
           dispatch(setLiveTerminalIds(liveIds))
           dispatch(setServerRestarted(false))
-          dispatch(clearDeadTerminals({ liveTerminalIds: liveIds }))
-          // Register regenerated createRequestIds with the correct explicit
-          // recovery path after stale terminal handles are cleared.
-          const layouts = appStore.getState().panes.layouts
-          const fallbackAttempts = appStore.getState().panes.restoreFallbackAttemptsByPane || {}
-          for (const [tabId, layout] of Object.entries(layouts)) {
-            ;(function walk(node: any) {
-              if (!node) return
-              if (node.type === 'leaf') {
-                if (node.content?.kind === 'terminal' && node.content.status === 'creating' && node.content.createRequestId) {
-                  const fallbackAttempt = fallbackAttempts[tabId]?.[node.id]
-                  if (
-                    fallbackAttempt?.requestId === node.content.createRequestId
-                    && !node.content.sessionRef
-                  ) {
-                    addTerminalFreshRecoveryRequestId(
-                      node.content.createRequestId,
-                      'fresh_after_restore_unavailable',
-                    )
-                  } else if (node.content.sessionRef) {
-                    addTerminalRestoreRequestId(node.content.createRequestId)
-                  }
-                }
-                return
-              }
-              if (node.type === 'split' && Array.isArray(node.children)) {
-                for (const child of node.children) walk(child)
-              }
-            })(layout)
+          // Capability-gated census (council rule 11): while pane.reconcile is
+          // active on this connection the reconcile verdicts own pane adoption,
+          // so ONLY the destructive part is skipped — the cached liveTerminalIds
+          // and restart-flag reset above stay unconditional (and feed the
+          // fallback census if the reconcile later fails).
+          if (!paneReconcileActiveRef.current) {
+            runDestructiveTerminalCensus(liveIds)
           }
           dispatch(setTerminalMetaSnapshot({ terminals: terminalMeta, requestedAt: terminalMetaRequestedAt }))
           dispatch(patchSessionRunningStateFromTerminalMeta({
diff --git a/src/lib/terminal-restore.ts b/src/lib/terminal-restore.ts
index 4dc5d3a2d..e4631d053 100644
--- a/src/lib/terminal-restore.ts
+++ b/src/lib/terminal-restore.ts
@@ -25,6 +25,20 @@ function collectCreateRequestIds(node: PaneNode | null | undefined): void {
   }
 }
 
+// While the pane.reconcile protocol owns pane adoption (server acked the
+// paneReconcileV1 capability on the CURRENT connection), the legacy
+// restore/fresh-recovery latches must report not-armed: reconcile verdicts
+// carry the authoritative restore intent, and a latch firing alongside them
+// would double-restore. The bypass is a first-line early return — armed
+// entries are preserved untouched, so deactivating (census fallback, or a
+// reconnect to a server without the capability) restores the exact previous
+// behavior.
+let paneReconcileActive = false
+
+export function setPaneReconcileActive(v: boolean): void {
+  paneReconcileActive = v
+}
+
 const persisted = loadPersistedPanes()
 if (persisted?.layouts && typeof persisted.layouts === 'object') {
   for (const node of Object.values(persisted.layouts)) {
@@ -49,6 +63,7 @@ if (persisted?.layouts && typeof persisted.layouts === 'object') {
 // happens, this keeps returning true for as many interrupted restore rounds
 // as it takes to anchor.
 export function consumeTerminalRestoreRequestId(requestId: string): boolean {
+  if (paneReconcileActive) return false
   if (freshRecoveryRequestIds.has(requestId)) return false
   return restoredCreateRequestIds.has(requestId)
 }
@@ -70,6 +85,7 @@ export function addTerminalRestoreRequestId(requestId: string): void {
 export function consumeTerminalFreshRecoveryRequest(
   requestId: string,
 ): TerminalFreshRecoveryIntent | undefined {
+  if (paneReconcileActive) return undefined
   const intent = freshRecoveryRequestIds.get(requestId)
   if (!intent) return undefined
   freshRecoveryRequestIds.delete(requestId)
diff --git a/test/unit/client/components/App.reconcile-adoption.test.tsx b/test/unit/client/components/App.reconcile-adoption.test.tsx
new file mode 100644
index 000000000..c3dfa006b
--- /dev/null
+++ b/test/unit/client/components/App.reconcile-adoption.test.tsx
@@ -0,0 +1,432 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, cleanup, waitFor, act } from '@testing-library/react'
+import { Provider } from 'react-redux'
+import { configureStore } from '@reduxjs/toolkit'
+import App from '@/App'
+import settingsReducer, { defaultSettings } from '@/store/settingsSlice'
+import tabsReducer from '@/store/tabsSlice'
+import connectionReducer, { setLiveTerminalIds } from '@/store/connectionSlice'
+import sessionsReducer from '@/store/sessionsSlice'
+import panesReducer, { applyReconcileAttach, clearDeadTerminals } from '@/store/panesSlice'
+import tabRegistryReducer from '@/store/tabRegistrySlice'
+import terminalMetaReducer from '@/store/terminalMetaSlice'
+import extensionsReducer from '@/store/extensionsSlice'
+import turnCompletionReducer from '@/store/turnCompletionSlice'
+import { networkReducer } from '@/store/networkSlice'
+import codexActivityReducer from '@/store/codexActivitySlice'
+import opencodeActivityReducer from '@/store/opencodeActivitySlice'
+import {
+  createDefaultServerSettings,
+  composeResolvedSettings,
+  resolveLocalSettings,
+} from '@shared/settings'
+
+// Mock heavy child components to avoid xterm/canvas issues
+vi.mock('@/components/TabContent', () => ({
+  default: () => <div data-testid="mock-tab-content">Tab Content</div>,
+}))
+vi.mock('@/components/Sidebar', () => ({
+  default: () => <div data-testid="mock-sidebar">Sidebar</div>,
+  AppView: {} as any,
+}))
+vi.mock('@/components/HistoryView', () => ({
+  default: () => <div data-testid="mock-history-view">History View</div>,
+}))
+vi.mock('@/components/SettingsView', () => ({
+  default: () => <div data-testid="mock-settings-view">Settings View</div>,
+}))
+vi.mock('@/components/OverviewView', () => ({
+  default: () => <div data-testid="mock-overview-view">Overview View</div>,
+}))
+vi.mock('@/hooks/useTheme', () => ({
+  useThemeEffect: () => {},
+}))
+vi.mock('@/components/SetupWizard', () => ({
+  SetupWizard: () => <div data-testid="mock-setup-wizard">Setup Wizard</div>,
+}))
+
+const defaultServerSettings = createDefaultServerSettings({
+  loggingDebug: defaultSettings.logging.debug,
+})
+
+function stubAudio(): void {
+  vi.stubGlobal('Audio', vi.fn(() => ({
+    preload: '',
+    volume: 1,
+    pause: vi.fn(),
+    play: vi.fn().mockResolvedValue(undefined),
+    currentTime: 0,
+    src: '',
+  }) as unknown as HTMLAudioElement))
+}
+
+const wsMocks = vi.hoisted(() => ({
+  send: vi.fn(),
+  connect: vi.fn(),
+  onMessage: vi.fn(),
+  onReconnect: vi.fn().mockReturnValue(() => {}),
+  onDisconnect: vi.fn().mockReturnValue(() => {}),
+  setHelloExtensionProvider: vi.fn(),
+  isReady: false,
+  serverInstanceId: undefined as string | undefined,
+}))
+
+const terminalRestoreMocks = vi.hoisted(() => ({
+  addTerminalRestoreRequestId: vi.fn(),
+  addTerminalFreshRecoveryRequestId: vi.fn(),
+  setPaneReconcileActive: vi.fn(),
+}))
+
+vi.mock('@/lib/terminal-restore', () => ({
+  addTerminalRestoreRequestId: terminalRestoreMocks.addTerminalRestoreRequestId,
+  addTerminalFreshRecoveryRequestId: terminalRestoreMocks.addTerminalFreshRecoveryRequestId,
+  setPaneReconcileActive: terminalRestoreMocks.setPaneReconcileActive,
+}))
+
+let messageHandler: ((msg: any) => void) | null = null
+
+vi.mock('@/lib/ws-client', () => ({
+  getWsClient: () => ({
+    send: wsMocks.send,
+    connect: wsMocks.connect,
+    onMessage: wsMocks.onMessage,
+    onReconnect: wsMocks.onReconnect,
+    onDisconnect: wsMocks.onDisconnect,
+    setHelloExtensionProvider: wsMocks.setHelloExtensionProvider,
+    get isReady() {
+      return wsMocks.isReady
+    },
+    get serverInstanceId() {
+      return wsMocks.serverInstanceId
+    },
+  }),
+}))
+
+const apiGet = vi.hoisted(() => vi.fn())
+const fetchSidebarSessionsSnapshot = vi.hoisted(() => vi.fn())
+const getTerminalDirectoryPage = vi.hoisted(() => vi.fn())
+const searchTerminalView = vi.hoisted(() => vi.fn())
+vi.mock('@/lib/api', () => ({
+  api: {
+    get: (url: string) => apiGet(url),
+    patch: vi.fn().mockResolvedValue({}),
+    post: vi.fn().mockResolvedValue({}),
+  },
+  fetchSidebarSessionsSnapshot: (options?: unknown) => fetchSidebarSessionsSnapshot(options),
+  getTerminalDirectoryPage: (options?: unknown, init?: unknown) => getTerminalDirectoryPage(options, init),
+  searchTerminalView: (terminalId: string, query: string, options?: unknown) => searchTerminalView(terminalId, query, options),
+  isApiUnauthorizedError: (err: any) => !!err && typeof err === 'object' && err.status === 401,
+  isTransientRequestFailure: (err: any) =>
+    !!err && (err.name === 'NetworkError' || err.name === 'AbortError' || [502, 503, 504].includes(err.status)),
+}))
+
+const sentFrames: any[] = []
+const dispatchedTypes: string[] = []
+const dispatched = { types: dispatchedTypes }
+
+let seededPane: { createRequestId: string } | null = null
+
+function seedPersistedTerminalPane(opts: { createRequestId: string }): void {
+  seededPane = opts
+}
+
+function createSettingsState() {
+  const localSettings = resolveLocalSettings()
+  return {
+    serverSettings: defaultServerSettings,
+    localSettings,
+    settings: composeResolvedSettings(defaultServerSettings, localSettings),
+    loaded: true,
+    lastSavedAt: undefined,
+  }
+}
+
+function createStore() {
+  const layouts: Record<string, unknown> = seededPane
+    ? {
+        'tab-1': {
+          type: 'leaf',
+          id: 'pane-1',
+          content: {
+            kind: 'terminal',
+            mode: 'shell',
+            shell: 'system',
+            status: 'running',
+            createRequestId: seededPane.createRequestId,
+            terminalId: 'term-old',
+          },
+        },
+      }
+    : {}
+  return configureStore({
+    reducer: {
+      settings: settingsReducer,
+      tabs: tabsReducer,
+      connection: connectionReducer,
+      sessions: sessionsReducer,
+      panes: panesReducer,
+      network: networkReducer,
+      codexActivity: codexActivityReducer,
+      opencodeActivity: opencodeActivityReducer,
+      tabRegistry: tabRegistryReducer,
+      terminalMeta: terminalMetaReducer,
+      extensions: extensionsReducer,
+      turnCompletion: turnCompletionReducer,
+    },
+    middleware: (getDefault) =>
+      getDefault({
+        serializableCheck: { ignoredPaths: ['sessions.expandedProjects'] },
+      }).concat(() => (next) => (action: any) => {
+        if (typeof action?.type === 'string') dispatchedTypes.push(action.type)
+        return next(action)
+      }),
+    preloadedState: {
+      settings: createSettingsState(),
+      tabs: { tabs: [{ id: 'tab-1', mode: 'shell' }] as any, activeTabId: 'tab-1' },
+      connection: {
+        status: 'disconnected' as const,
+        lastError: undefined,
+        platform: null,
+        availableClis: {},
+      },
+      sessions: {
+        projects: [],
+        expandedProjects: new Set<string>(),
+        wsSnapshotReceived: false,
+        isLoading: false,
+        error: null,
+        windows: {},
+      },
+      panes: {
+        layouts,
+        activePane: seededPane ? { 'tab-1': 'pane-1' } : {},
+        paneTitles: {},
+        paneTitleSetByUser: {},
+        renameRequestTabId: null,
+        renameRequestPaneId: null,
+        zoomedPane: {},
+      },
+      network: { status: null, loading: false, configuring: false, error: null },
+      codexActivity: {
+        byTerminalId: {},
+        lastSnapshotSeq: 0,
+        liveMutationSeqByTerminalId: {},
+        removedMutationSeqByTerminalId: {},
+      },
+      opencodeActivity: {
+        byTerminalId: {},
+        lastSnapshotSeq: 0,
+        liveMutationSeqByTerminalId: {},
+        removedMutationSeqByTerminalId: {},
+      },
+      tabRegistry: {
+        deviceId: 'device-test',
+        deviceLabel: 'device-test',
+        deviceAliases: {},
+        localOpen: [],
+        remoteOpen: [],
+        closed: [],
+        localClosed: {},
+        searchRangeDays: 30,
+        loading: false,
+      },
+      terminalMeta: { byTerminalId: {} },
+      extensions: { entries: [] },
+      turnCompletion: {
+        seq: 0,
+        lastAtByTerminalId: {},
+        lastIdleAtByTerminalId: {},
+        pendingEvents: [],
+        attentionByTab: {},
+        attentionByPane: {},
+      },
+    } as any,
+  })
+}
+
+function readyFrame(options: { capabilities?: Record<string, unknown> } = {}) {
+  return {
+    type: 'ready',
+    timestamp: new Date().toISOString(),
+    serverInstanceId: 'srv-1',
+    bootId: 'boot-1',
+    ...(options.capabilities ? { capabilities: options.capabilities } : {}),
+  }
+}
+
+async function bootAppWithReady(options: { capabilities?: Record<string, unknown> } = {}) {
+  const store = createStore()
+  render(
+    <Provider store={store}>
+      <App />
+    </Provider>,
+  )
+  await waitFor(() => {
+    expect(messageHandler).toBeTypeOf('function')
+  })
+  act(() => {
+    messageHandler?.(readyFrame(options))
+  })
+  return { sentFrames, dispatched, store }
+}
+
+async function receiveInventory({ liveTerminalIds }: { liveTerminalIds: string[] }) {
+  act(() => {
+    messageHandler?.({
+      type: 'terminal.inventory',
+      terminals: liveTerminalIds.map((terminalId) => ({
+        terminalId,
+        title: 'Terminal',
+        mode: 'shell',
+        createdAt: 1_000,
+        lastActivityAt: 1_700,
+        status: 'running',
+      })),
+      terminalMeta: [],
+    })
+  })
+}
+
+async function receiveServerFrame(frame: Record<string, unknown>) {
+  act(() => {
+    messageHandler?.(frame)
+  })
+}
+
+async function simulateReconnectWithReady(options: { capabilities?: Record<string, unknown> } = {}) {
+  act(() => {
+    messageHandler?.(readyFrame(options))
+  })
+}
+
+function attachResultFor(req: any, terminalId: string) {
+  return {
+    type: 'pane.reconcile.result',
+    reconcileId: req.reconcileId,
+    bootId: 'boot-1',
+    serverInstanceId: 'srv-1',
+    verdicts: req.panes.map((pane: any) => ({
+      paneKey: pane.paneKey,
+      verdict: 'attach',
+      terminalId,
+    })),
+  }
+}
+
+describe('App pane.reconcile adoption', () => {
+  beforeEach(() => {
+    cleanup()
+    vi.resetAllMocks()
+    stubAudio()
+    sentFrames.length = 0
+    dispatchedTypes.length = 0
+    seededPane = null
+    messageHandler = null
+    wsMocks.isReady = false
+    wsMocks.serverInstanceId = undefined
+    wsMocks.onReconnect.mockReturnValue(() => {})
+    wsMocks.onDisconnect.mockReturnValue(() => {})
+    wsMocks.onMessage.mockImplementation((cb: (msg: any) => void) => {
+      messageHandler = cb
+      return () => { messageHandler = null }
+    })
+    wsMocks.send.mockImplementation((frame: unknown) => {
+      sentFrames.push(frame)
+    })
+
+    fetchSidebarSessionsSnapshot.mockResolvedValue([])
+    getTerminalDirectoryPage.mockResolvedValue({ items: [], revision: 1, nextCursor: null })
+    searchTerminalView.mockResolvedValue({ matches: [] })
+    apiGet.mockImplementation((url: string) => {
+      if (url === '/api/bootstrap') {
+        return Promise.resolve({
+          settings: defaultServerSettings,
+          platform: { platform: 'linux' },
+          shell: { authenticated: true, ready: true },
+        })
+      }
+      return Promise.resolve({})
+    })
+  })
+
+  afterEach(() => {
+    cleanup()
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  it('sends pane.reconcile.request after ready-with-capability and does NOT run the census', async () => {
+    seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+    const { sentFrames, dispatched } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+    await receiveInventory({ liveTerminalIds: [] })
+    expect(sentFrames.some((f) => f.type === 'pane.reconcile.request')).toBe(true)
+    expect(dispatched.types).not.toContain(clearDeadTerminals.type)
+    expect(dispatched.types).toContain(setLiveTerminalIds.type) // non-destructive part stays
+  })
+
+  it('runs the legacy census when the server does not ack the capability', async () => {
+    seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+    const { sentFrames, dispatched } = await bootAppWithReady({ /* no capabilities */ })
+    await receiveInventory({ liveTerminalIds: [] })
+    expect(sentFrames.some((f) => f.type === 'pane.reconcile.request')).toBe(false)
+    expect(dispatched.types).toContain(clearDeadTerminals.type)
+  })
+
+  it('folds a matching pane.reconcile.result', async () => {
+    seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+    const { sentFrames, dispatched } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+    const req = sentFrames.find((f) => f.type === 'pane.reconcile.request')!
+    await receiveServerFrame(attachResultFor(req, 'term-77'))
+    expect(dispatched.types).toContain(applyReconcileAttach.type)
+  })
+
+  it('skips a pane.reconcile.result with a foreign reconcileId (fold-ownership rule)', async () => {
+    seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+    const { sentFrames, dispatched } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+    const req = sentFrames.find((f) => f.type === 'pane.reconcile.request')!
+    const foreign = { ...attachResultFor(req, 'term-88'), reconcileId: 'foreign-reconcile-id' }
+    await receiveServerFrame(foreign)
+    expect(dispatched.types).not.toContain(applyReconcileAttach.type)
+    // ...and our own result still folds afterwards (the pending ref survived the foreign frame).
+    await receiveServerFrame(attachResultFor(req, 'term-77'))
+    expect(dispatched.types).toContain(applyReconcileAttach.type)
+  })
+
+  it('cardinality violation falls back to the census, loudly (real wire order: inventory BEFORE result)', async () => {
+    seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { sentFrames, dispatched } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+    const req = sentFrames.find((f) => f.type === 'pane.reconcile.request')!
+    // Real handshake order (lib.rs:368-427): terminal.inventory ALWAYS precedes
+    // any reconcile result — inject it FIRST; the fallback census must run from
+    // the CACHED liveTerminalIds.
+    await receiveInventory({ liveTerminalIds: [] })
+    await receiveServerFrame({
+      type: 'pane.reconcile.result',
+      reconcileId: req.reconcileId,
+      bootId: 'b',
+      serverInstanceId: 's',
+      verdicts: [],
+    })
+    expect(errSpy).toHaveBeenCalled()
+    expect(dispatched.types).toContain(clearDeadTerminals.type)
+  })
+
+  it('a correlated error frame is TERMINAL for the reconcile — census fallback from cached inventory', async () => {
+    seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { sentFrames, dispatched } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+    const req = sentFrames.find((f) => f.type === 'pane.reconcile.request')!
+    await receiveInventory({ liveTerminalIds: [] }) // inventory first — real wire order
+    await receiveServerFrame({ type: 'error', code: 'RECONCILE_UNAVAILABLE', requestId: req.reconcileId })
+    expect(errSpy).toHaveBeenCalled()
+    expect(dispatched.types).toContain(clearDeadTerminals.type) // census ran from cached liveTerminalIds
+  })
+
+  it('re-sends the reconcile request on EVERY ready (reconnect covers loss windows)', async () => {
+    seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+    const { sentFrames } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+    await simulateReconnectWithReady({ capabilities: { paneReconcileV1: true } })
+    expect(sentFrames.filter((f) => f.type === 'pane.reconcile.request')).toHaveLength(2)
+  })
+})
diff --git a/test/unit/client/components/App.restart-signals.test.tsx b/test/unit/client/components/App.restart-signals.test.tsx
index 27b223223..38bc7fe56 100644
--- a/test/unit/client/components/App.restart-signals.test.tsx
+++ b/test/unit/client/components/App.restart-signals.test.tsx
@@ -94,11 +94,13 @@ const wsMocks = vi.hoisted(() => ({
 const terminalRestoreMocks = vi.hoisted(() => ({
   addTerminalRestoreRequestId: vi.fn(),
   addTerminalFreshRecoveryRequestId: vi.fn(),
+  setPaneReconcileActive: vi.fn(),
 }))
 
 vi.mock('@/lib/terminal-restore', () => ({
   addTerminalRestoreRequestId: terminalRestoreMocks.addTerminalRestoreRequestId,
   addTerminalFreshRecoveryRequestId: terminalRestoreMocks.addTerminalFreshRecoveryRequestId,
+  setPaneReconcileActive: terminalRestoreMocks.setPaneReconcileActive,
 }))
 
 let messageHandler: ((msg: any) => void) | null = null
diff --git a/test/unit/client/components/App.ws-bootstrap.test.tsx b/test/unit/client/components/App.ws-bootstrap.test.tsx
index 34d290de3..f9b62071e 100644
--- a/test/unit/client/components/App.ws-bootstrap.test.tsx
+++ b/test/unit/client/components/App.ws-bootstrap.test.tsx
@@ -96,11 +96,13 @@ const wsMocks = vi.hoisted(() => ({
 const terminalRestoreMocks = vi.hoisted(() => ({
   addTerminalRestoreRequestId: vi.fn(),
   addTerminalFreshRecoveryRequestId: vi.fn(),
+  setPaneReconcileActive: vi.fn(),
 }))
 
 vi.mock('@/lib/terminal-restore', () => ({
   addTerminalRestoreRequestId: terminalRestoreMocks.addTerminalRestoreRequestId,
   addTerminalFreshRecoveryRequestId: terminalRestoreMocks.addTerminalFreshRecoveryRequestId,
+  setPaneReconcileActive: terminalRestoreMocks.setPaneReconcileActive,
 }))
 
 let messageHandler: ((msg: any) => void) | null = null
diff --git a/test/unit/lib/terminal-restore.test.ts b/test/unit/lib/terminal-restore.test.ts
index d71abe1fe..1a29c47b1 100644
--- a/test/unit/lib/terminal-restore.test.ts
+++ b/test/unit/lib/terminal-restore.test.ts
@@ -83,6 +83,45 @@ describe('terminal-restore', () => {
     expect(consumeTerminalFreshRecoveryRequest('fresh-id-1')).toBeUndefined()
   })
 
+  it('reports not-armed while pane reconcile is active', async () => {
+    const {
+      setPaneReconcileActive,
+      addTerminalRestoreRequestId,
+      consumeTerminalRestoreRequestId,
+      addTerminalFreshRecoveryRequestId,
+      consumeTerminalFreshRecoveryRequest,
+    } = await import('@/lib/terminal-restore')
+
+    setPaneReconcileActive(true)
+    addTerminalRestoreRequestId('cr-x')
+    expect(consumeTerminalRestoreRequestId('cr-x')).toBeFalsy()
+
+    addTerminalFreshRecoveryRequestId('cr-y', 'fresh_after_restore_unavailable')
+    expect(consumeTerminalFreshRecoveryRequest('cr-y')).toBeUndefined()
+  })
+
+  it('restores latch behavior after pane reconcile is deactivated', async () => {
+    const {
+      setPaneReconcileActive,
+      addTerminalRestoreRequestId,
+      consumeTerminalRestoreRequestId,
+      addTerminalFreshRecoveryRequestId,
+      consumeTerminalFreshRecoveryRequest,
+    } = await import('@/lib/terminal-restore')
+
+    setPaneReconcileActive(true)
+    addTerminalRestoreRequestId('cr-x')
+    addTerminalFreshRecoveryRequestId('cr-y', 'fresh_after_restore_unavailable')
+    expect(consumeTerminalRestoreRequestId('cr-x')).toBeFalsy()
+    expect(consumeTerminalFreshRecoveryRequest('cr-y')).toBeUndefined()
+
+    // Deactivate: the bypass is a first-line early return, so the armed
+    // latches were never consumed and behave exactly as before.
+    setPaneReconcileActive(false)
+    expect(consumeTerminalRestoreRequestId('cr-x')).toBe(true)
+    expect(consumeTerminalFreshRecoveryRequest('cr-y')).toBe('fresh_after_restore_unavailable')
+  })
+
   it('prefers explicit fresh recovery when a request id is mistakenly registered for both paths', async () => {
     const {
       addTerminalFreshRecoveryRequestId,

From d9e413fc6ffa9d4c5f68025cb3c353a951b3627f Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:46:26 -0700
Subject: [PATCH 59/87] feat(claude): record fresh-agent binding row with
 create settings at sdk.session.init (P1.13)

---
 crates/freshell-freshagent/src/claude.rs | 136 ++++++++++++++++++++++-
 1 file changed, 133 insertions(+), 3 deletions(-)

diff --git a/crates/freshell-freshagent/src/claude.rs b/crates/freshell-freshagent/src/claude.rs
index 030457e95..029692424 100644
--- a/crates/freshell-freshagent/src/claude.rs
+++ b/crates/freshell-freshagent/src/claude.rs
@@ -158,11 +158,36 @@ impl FreshClaudeState {
     }
 
     /// The wired identity sink, if any.
-    #[allow(dead_code)] // used by identity-event tasks (Tasks 4-10)
     fn identity_sink(&self) -> Option<SharedPaneIdentitySink> {
         self.identity_sink.get().cloned()
     }
 
+    /// Broadcast a `freshAgent.error` alarm/degradation frame (P1.13; Task 10
+    /// consumes this too). Same envelope contract as codex's helper (`codex.rs`):
+    /// top-level `sessionType`/`provider` are REQUIRED (locator resolution) and
+    /// `message` is user-facing (the banner shows the message, never the code) —
+    /// but unlike codex this one cannot hardcode the session type: provider
+    /// `claude` covers BOTH `freshclaude` and `kilroy`, so the flavour is a param.
+    fn emit_fresh_agent_error(
+        &self,
+        session_id: &str,
+        session_type: &str,
+        code: &str,
+        message: &str,
+    ) {
+        self.broadcast(&ServerMessage::FreshAgentEvent(FreshAgentEvent {
+            event: json!({
+                "type": "freshAgent.error",
+                "sessionId": session_id,
+                "code": code,
+                "message": message,
+            }),
+            provider: PROVIDER.to_string(),
+            session_id: session_id.to_string(),
+            session_type: session_type.to_string(),
+        }));
+    }
+
     /// Reap every owned claude sidecar: SIGTERM the Node process (so it cleanly kills its
     /// own `claude` CLI via the SDK abort), SIGKILL any straggler, abort the consumer, and
     /// run the `/proc` ownership sweep for the grandchild. Called on server shutdown.
@@ -231,6 +256,17 @@ impl FreshClaudeState {
             }
         };
 
+        // P1.13: FULL settings snapshot for the binding row the consumer writes at
+        // `sdk.session.init` (claude has no sandbox concept — always `None`). Built
+        // from the SAME values the create request below actually sends.
+        let settings = crate::identity_sink::FreshAgentSettings {
+            model: msg.model.clone(),
+            sandbox: None,
+            permission_mode: msg.permission_mode.clone(),
+            effort: msg.effort.clone(),
+            cwd: msg.cwd.clone(),
+        };
+
         // Send the create request (faithful to createClaudeSdkOptions inputs).
         let create_req = json!({
             "type": "create",
@@ -262,11 +298,13 @@ impl FreshClaudeState {
         };
 
         // Start the stdout consumer (the completion edge normalization lives here).
+        // `Some(settings)` => the consumer records a binding row at `sdk.session.init`.
         let consumer = self.spawn_consumer(
             reader,
             created.clone(),
             session_type.to_string(),
             created.clone(),
+            Some(settings),
         );
 
         self.sessions.lock().await.insert(
@@ -546,13 +584,16 @@ impl FreshClaudeState {
         // Register under the CLIENT's id: the consumer stamps the map key on every
         // envelope and the frozen client routes by envelope sessionId
         // (fresh-agent-ws.ts:180-183) -- a fresh key would strand the pane.
-        // 4-arg spawn_consumer: the sidecar's created id is the eviction identity
-        // guard for this consumer.
+        // The sidecar's created id is the eviction identity guard for this consumer.
+        // `settings: None` (P1.13): until Task 10 resolves the ledger record for the
+        // resume path, record NOTHING here — writing would launder a blank row under
+        // the new cliSessionId (V7/A10).
         let consumer = self.spawn_consumer(
             reader,
             msg.session_id.clone(),
             session_type.clone(),
             sidecar_session_id.clone(),
+            None,
         );
         self.sessions.lock().await.insert(
             msg.session_id.clone(),
@@ -601,16 +642,25 @@ impl FreshClaudeState {
     /// `sidecar_session_id` is the id THIS consumer's sidecar is keyed by; it guards the
     /// eviction so a stale consumer can never evict a newer session re-registered under
     /// the same map key (attach-resume, Task 6).
+    ///
+    /// `settings` (P1.13): `Some` = record a fresh-agent binding row at
+    /// `sdk.session.init` (create path / resume-with-record); `None` = do NOT record
+    /// (resume of a never-recorded session — writing would launder a blank row under
+    /// the new cliSessionId, V7/A10). The row's `mode` is the `session_type` param
+    /// (the `"freshclaude"` vs `"kilroy"` flavour; provider is always [`PROVIDER`]).
     fn spawn_consumer(
         &self,
         mut reader: tokio::io::Lines<BufReader<ChildStdout>>,
         session_id: String,
         session_type: String,
         sidecar_session_id: String,
+        settings: Option<crate::identity_sink::FreshAgentSettings>,
     ) -> tokio::task::JoinHandle<()> {
         let broadcast_tx = self.broadcast_tx.clone();
         let sessions = self.sessions.clone();
         let cli_index = self.cli_index.clone();
+        let identity_sink = self.identity_sink();
+        let state = self.clone();
         tokio::spawn(async move {
             while let Ok(Some(line)) = reader.next_line().await {
                 let trimmed = line.trim();
@@ -632,6 +682,36 @@ impl FreshClaudeState {
                         if let Some(session) = sessions.lock().await.get_mut(&session_id) {
                             session.cli_session_id = Some(cli_id.to_string());
                         }
+                        // P1.13: binding row keyed by the DURABLE cliSessionId, with
+                        // the FULL create-settings snapshot — AWAITED here (this arm
+                        // runs on the async consumer task) so the row is durable
+                        // BEFORE the init-driven broadcast below proceeds (V8/A11).
+                        // A failed write is surfaced user-visibly, never
+                        // warn-and-drop, then the identity event proceeds.
+                        if let (Some(sink), Some(settings)) =
+                            (identity_sink.clone(), settings.as_ref())
+                        {
+                            if let Err(e) = sink
+                                .record_binding(crate::identity_sink::FreshAgentBindingUpsert {
+                                    provider: PROVIDER.into(),
+                                    session_id: cli_id.to_string(),
+                                    mode: session_type.clone(),
+                                    create_request_id: None,
+                                    resolves_pending: None,
+                                    supersedes: None,
+                                    settings: settings.clone(),
+                                })
+                                .await
+                            {
+                                tracing::warn!(error = %e, session = %cli_id, "freshagent.claude.binding_write_failed");
+                                state.emit_fresh_agent_error(
+                                    cli_id,
+                                    &session_type,
+                                    "LEDGER_WRITE_FAILED",
+                                    "Failed to persist this session's resume record - settings may not survive a server restart.",
+                                );
+                            }
+                        }
                     }
                 }
                 if let Some(frame) = sdk_line_to_frame(&value, &session_id, &session_type) {
@@ -1860,6 +1940,56 @@ rl.on('line', (line) => {
         drop(env);
     }
 
+    /// P1.13 (Task 9): the `sdk.session.init` arm must record ONE fresh-agent binding
+    /// row through the identity sink — keyed by the DURABLE cliSessionId, carrying the
+    /// FULL create-settings snapshot and the sessionType flavour — AWAITED before the
+    /// init-driven broadcast proceeds (durable-before-answer, V8/A11).
+    #[tokio::test(flavor = "multi_thread")]
+    async fn session_init_records_binding_with_create_settings() {
+        let _guard = CLAUDE_ENV_LOCK.lock().await;
+        let env = FakeClaudeSidecarEnv::install();
+        let (state, mut rx) = state_with_bus();
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        state.set_identity_sink(fake.clone());
+
+        // Drive freshAgent.create with sessionType kilroy + explicit settings.
+        let mut msg = dedup_create_msg("req-binding-init");
+        msg.session_type = SessionType::Kilroy;
+        msg.model = Some("opus-x".to_string());
+        msg.permission_mode = Some("plan".to_string());
+        msg.effort = Some("high".to_string());
+        msg.cwd = Some(env.dir.to_string_lossy().to_string());
+        state.handle_create(msg).await;
+        await_claude_created(&mut rx, "req-binding-init").await;
+
+        // Wait for sdk.session.init to be consumed: the binding write is AWAITED
+        // before the init frame broadcasts, so seeing the freshAgent.session.init
+        // envelope proves the row already landed.
+        tokio::time::timeout(std::time::Duration::from_secs(15), async {
+            loop {
+                let frame: Value = serde_json::from_str(&rx.recv().await.unwrap()).unwrap();
+                if frame["event"]["type"] == "freshAgent.session.init" {
+                    break;
+                }
+            }
+        })
+        .await
+        .expect("freshAgent.session.init consumed within budget");
+
+        let bindings = fake.bindings.lock().unwrap();
+        let b = bindings.last().expect("binding at sdk.session.init");
+        assert_eq!(b.provider, "claude");
+        assert_eq!(b.mode, "kilroy", "sessionType flavour preserved in the row");
+        assert_eq!(
+            b.session_id, "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+            "keyed by cliSessionId"
+        );
+        assert_eq!(b.settings.model.as_deref(), Some("opus-x"));
+        assert_eq!(b.settings.permission_mode.as_deref(), Some("plan"));
+        assert_eq!(b.settings.effort.as_deref(), Some("high"));
+        assert!(b.settings.cwd.is_some());
+    }
+
     /// Ledger A9: consumer exit (== sidecar death) must evict the dead session AND its
     /// `cli_index` entries — kill/shutdown are NOT the only eviction paths. Without this,
     /// a dead-but-tracked session makes the tracked⇒no-op attach row strand panes forever.

From 4a779402b6f87d3a60ffcfaf016baddc8ff6ff2f Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:48:45 -0700
Subject: [PATCH 60/87] test(e2e): fresh codex pane gains server-side identity
 and resumes via 'codex resume <id>' across restart

---
 test/e2e-browser/playwright.config.ts         |   6 +
 .../specs/codex-terminal-restore-rust.spec.ts | 380 ++++++++++++++++++
 2 files changed, 386 insertions(+)
 create mode 100644 test/e2e-browser/specs/codex-terminal-restore-rust.spec.ts

diff --git a/test/e2e-browser/playwright.config.ts b/test/e2e-browser/playwright.config.ts
index c4151f30e..2c1c9c6ed 100644
--- a/test/e2e-browser/playwright.config.ts
+++ b/test/e2e-browser/playwright.config.ts
@@ -127,6 +127,9 @@ const RUST_ONLY_SPECS = [
   // ledger-join coherence, A2xA3 dual claude identity stores). Imports
   // RustServer directly for restartAbrupt().
   /wavea-interactions-rust\.spec\.ts$/,
+  // Lane B2 codex rollout locator: rust-only (legacy has no codex terminal
+  // locator); imports the RustServer-backed harness for same-port restart.
+  /codex-terminal-restore-rust\.spec\.ts$/,
 ]
 
 export default defineConfig({
@@ -284,6 +287,9 @@ export default defineConfig({
         // ledger-join coherence, A2xA3 dual claude identity stores). Imports
         // RustServer directly for restartAbrupt().
         /wavea-interactions-rust\.spec\.ts$/,
+        // Lane B2 codex rollout locator: rust-only (legacy has no codex terminal
+        // locator); imports the RustServer-backed harness for same-port restart.
+        /codex-terminal-restore-rust\.spec\.ts$/,
       ],
     },
     // CONTINUITY SMOKE (pre-deploy gate): REAL freshell-server binary + REAL
diff --git a/test/e2e-browser/specs/codex-terminal-restore-rust.spec.ts b/test/e2e-browser/specs/codex-terminal-restore-rust.spec.ts
new file mode 100644
index 000000000..101c4ba1e
--- /dev/null
+++ b/test/e2e-browser/specs/codex-terminal-restore-rust.spec.ts
@@ -0,0 +1,380 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { test, expect } from '../helpers/fixtures.js'
+import { createE2eServerHandle } from '../helpers/external-target.js'
+import { TestHarness } from '../helpers/test-harness.js'
+import { openPanePicker } from '../helpers/pane-picker.js'
+
+/**
+ * CODEX TERMINAL RESTORE (Lane B2) -- restore-across-server-restart
+ * acceptance scenario for codex TERMINAL panes on the Rust port: a fresh
+ * WS-created codex pane gains its identity SERVER-SIDE (the rollout
+ * locator), then resumes across a full server restart via
+ * `codex ... resume <id>`.
+ *
+ * KNOWN DIVERGENCE (rust-only, by design -- see `playwright.config.ts`'s
+ * `rust-chromium`-only `testMatch` entry for this file, and
+ * `opencode-terminal-restore-rust.spec.ts`'s identical divergence note):
+ * legacy has NO codex terminal rollout locator -- fresh codex terminal
+ * identity there depended on the client's `terminal.codex.durability.updated`
+ * candidate path, which the Rust server retired server-side. This is not a
+ * parity gap to gate per-assertion; it is a capability that exists only on
+ * the Rust port, designed by analogy to the amplifier/opencode locator
+ * precedents, and this spec is scoped to the Rust project only rather than
+ * pretending legacy participates.
+ *
+ * The fix under test (Tasks 1-7 of the codex rollout locator pipeline): the
+ * Rust server arms fresh WS-created codex panes at create; the pane's first
+ * Enter re-snapshots known_files and opens the submit window; the 150ms
+ * sweep resolves the NEW rollout JSONL under CODEX_HOME/sessions (first-line
+ * session_meta `payload.id` is the identity), adopts it (identity registry +
+ * terminal meta + pane ledger + broadcasts + activity bind), and broadcasts
+ * `terminal.session.associated` + `terminal.meta.updated` -- the SAME wire
+ * messages the frozen client's generic
+ * `reconcileTerminalSessionAssociation` + restore machinery already handle
+ * for every other provider. No client/shared changes were needed; this
+ * scenario is the proof.
+ *
+ * Row-timing note (mirrors the donor spec's fixture-shape note): the Task 8
+ * fixture models the ENTER-anchored shape (the rollout is written on the
+ * pane's first Enter, exactly like real codex -- the rollout materializes
+ * only at the first user prompt) so the scenario has a clean, symmetric
+ * negative control (a pane that never types never gets a rollout, never
+ * associates). Finer-grained rollout-vs-arm timing races are separately and
+ * deterministically proven by the locator's own Rust unit tests, which
+ * control timing to the millisecond -- something this e2e, driving a real
+ * browser + WS round trip, cannot do reliably.
+ */
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const FAKE_CODEX_TERMINAL_SOURCE = path.resolve(__dirname, '../fixtures/fake-codex-terminal.mjs')
+
+/**
+ * Install the fake codex CLI as an executable named `codex` in a throwaway
+ * bin dir, then point `CODEX_CMD` at it -- same copy-then-chmod pattern
+ * `opencode-terminal-restore-rust.spec.ts`'s `installFakeOpencodeTerminal`
+ * uses (helpers are per-spec-owned by convention, copied not imported).
+ */
+async function installFakeCodexTerminal(binDir: string): Promise<string> {
+  await fs.mkdir(binDir, { recursive: true })
+  const target = path.join(binDir, 'codex')
+  await fs.copyFile(FAKE_CODEX_TERMINAL_SOURCE, target)
+  await fs.chmod(target, 0o755)
+  return target
+}
+
+async function selectShellIfPickerShowing(page: import('@playwright/test').Page): Promise<void> {
+  await page.waitForTimeout(500)
+  const xtermVisible = await page.locator('.xterm').first().isVisible().catch(() => false)
+  if (xtermVisible) return
+  const shellNames = ['Shell', 'WSL', 'CMD', 'PowerShell', 'Bash']
+  for (const name of shellNames) {
+    try {
+      await page.getByRole('button', { name: new RegExp(`^${name}$`, 'i') }).click({ timeout: 5_000 })
+      await page.locator('.xterm').first().waitFor({ state: 'visible', timeout: 15_000 })
+      return
+    } catch {
+      continue
+    }
+  }
+}
+
+async function bootAndConnect(
+  page: import('@playwright/test').Page,
+  info: { baseUrl: string; token: string },
+): Promise<TestHarness> {
+  await page.goto(`${info.baseUrl}/?token=${info.token}&e2e=1`)
+  const harness = new TestHarness(page)
+  await harness.waitForHarness()
+  await harness.waitForConnection()
+  await selectShellIfPickerShowing(page)
+  return harness
+}
+
+/** Read the fake CLI's argv-log JSONL (empty array if not yet written). */
+async function readArgvLog(logPath: string): Promise<Array<{ argv: string[] }>> {
+  const raw = await fs.readFile(logPath, 'utf8').catch(() => '')
+  if (!raw) return []
+  return raw.trim().split('\n').filter(Boolean).map((line) => JSON.parse(line) as { argv: string[] })
+}
+
+/**
+ * Open a NEW pane via the picker and select the "Codex CLI" provider option
+ * (the manifest label in `extensions/codex-cli/freshell.json` is
+ * "Codex CLI" -- `/^Codex$/` matches nothing). Selecting a coding-CLI
+ * provider opens a follow-up "Starting directory for Codex CLI" combobox
+ * (`src/components/panes/DirectoryPicker.tsx`), pre-filled with the CURRENT
+ * directory and already focused. Pressing Enter submits the combobox's own
+ * pre-filled value directly, accepting the current directory as-is (mirrors
+ * `opencode-terminal-restore-rust.spec.ts`'s `openOpencodePane`).
+ */
+async function openCodexPane(page: import('@playwright/test').Page): Promise<void> {
+  const picker = await openPanePicker(page)
+  await picker.getByRole('button', { name: /^Codex CLI$/i }).click({ force: true })
+  await page.getByRole('combobox', { name: /Starting directory for Codex CLI/i }).press('Enter')
+}
+
+/** Flatten a pane layout tree into its leaf nodes. */
+function collectLeaves(node: any): any[] {
+  if (!node) return []
+  if (node.type === 'leaf') return [node]
+  if (node.type === 'split') return (node.children ?? []).flatMap(collectLeaves)
+  return []
+}
+
+/** Every codex-mode terminal leaf currently in a tab's layout. */
+function findCodexLeaves(layout: any): any[] {
+  return collectLeaves(layout).filter((leaf) => leaf?.content?.mode === 'codex')
+}
+
+/**
+ * Open a new codex pane (splitting the current terminal) and return the
+ * NEWLY-added codex leaf -- identified by diffing the leaf set before vs
+ * after, since a fresh codex pane's `content.terminalId` isn't known until
+ * the create round-trip completes.
+ */
+async function openCodexPaneAndGetLeaf(
+  page: import('@playwright/test').Page,
+  harness: TestHarness,
+  tabId: string,
+): Promise<any> {
+  const before = findCodexLeaves(await harness.getPaneLayout(tabId))
+  const beforeIds = new Set(before.map((leaf) => leaf.id))
+  await openCodexPane(page)
+  await expect(page.locator('.xterm').last()).toBeVisible({ timeout: 15_000 })
+  return expect.poll(async () => {
+    const layout = await harness.getPaneLayout(tabId)
+    const newLeaf = findCodexLeaves(layout).find((leaf) => !beforeIds.has(leaf.id))
+    return newLeaf?.content?.terminalId ? newLeaf : null
+  }, { timeout: 15_000 }).not.toBeNull().then(async () => {
+    const layout = await harness.getPaneLayout(tabId)
+    return findCodexLeaves(layout).find((leaf) => !beforeIds.has(leaf.id))
+  })
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+test.describe('Codex Terminal Restore (Rust only)', () => {
+  test.setTimeout(120_000)
+
+  test('a fresh codex terminal pane gains server-side identity and restores across a server restart via `codex resume <id>`, and a never-submitted pane restores fresh', async ({ page, e2eServerKind }) => {
+    // This spec is registered ONLY under the `rust-chromium` project
+    // (`playwright.config.ts`), but assert the precondition explicitly so a
+    // future accidental `MATRIX_SPECS` inclusion fails loudly instead of
+    // silently no-op'ing on legacy.
+    expect(e2eServerKind).toBe('rust')
+
+    const sharedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'freshell-codex-terminal-restore-'))
+    const argLogPath = path.join(sharedRoot, 'fake-codex-terminal-argv.jsonl')
+    try {
+      const fakeCodexPath = await installFakeCodexTerminal(path.join(sharedRoot, 'bin'))
+
+      const server = await createE2eServerHandle(process.env, {
+        kind: e2eServerKind,
+        construct: {
+          env: {
+            CODEX_CMD: fakeCodexPath,
+            FAKE_CODEX_TERMINAL_ARGV_LOG: argLogPath,
+          },
+          // PanePicker only renders a CLI option when THREE conditions all
+          // hold (`src/components/panes/PanePicker.tsx`'s `cliOptions`
+          // filter): `availableClis[name]`, `enabledProviders.includes(name)`,
+          // and NOT `disabledExtensions.includes(name)`. Seeded here the same
+          // way `opencode-terminal-restore-rust.spec.ts` seeds
+          // `enabledProviders` for `opencode`.
+          setupHome: async (homeDir) => {
+            const freshellDir = path.join(homeDir, '.freshell')
+            await fs.mkdir(freshellDir, { recursive: true })
+            await fs.writeFile(path.join(freshellDir, 'config.json'), JSON.stringify({
+              version: 1,
+              settings: {
+                codingCli: { enabledProviders: ['codex'] },
+              },
+            }, null, 2))
+          },
+        },
+      })
+      const info = await server.start()
+
+      try {
+        const harness = await bootAndConnect(page, info)
+        await expect(page.locator('.xterm').first()).toBeVisible({ timeout: 30_000 })
+
+        // `availableClis` is populated by the SERVER's `which`/`where.exe`
+        // probe (`crates/freshell-server/src/extensions.rs`'s
+        // `detect_available_clis_live`), whose spec list is derived from
+        // GENUINELY DISCOVERED CLI extension manifests --
+        // `extensions/codex-cli/freshell.json` is a real `category: "cli"`
+        // manifest (`command: "codex"`, `envVar: "CODEX_CMD"`), so the
+        // server's live boot-time detection already discovers and probes
+        // codex via the `CODEX_CMD` override this test sets.
+        const tabId = await harness.getActiveTabId()
+        expect(tabId).toBeTruthy()
+
+        // -------------------------------------------------------------
+        // Positive case: a fresh codex pane that DOES submit a prompt.
+        // -------------------------------------------------------------
+        const positiveLeaf = await openCodexPaneAndGetLeaf(page, harness, tabId!)
+        const terminalIdBefore: string = positiveLeaf.content.terminalId
+        const positivePaneId: string = positiveLeaf.id
+        expect(terminalIdBefore).toBeTruthy()
+
+        await expect.poll(async () => {
+          const buffer = await harness.getTerminalBuffer(terminalIdBefore)
+          return typeof buffer === 'string' && buffer.includes('codex> ')
+        }, { timeout: 15_000 }).toBe(true)
+
+        // The pane's first Enter/submit -- this is the locator's submit
+        // trigger: the server re-snapshots known_files and opens the 2s
+        // submit window; the fixture writes the rollout on this Enter. Only
+        // two `.xterm` containers exist at this point (the original shell
+        // pane + this freshly-created one), and this one was just added, so
+        // `.last()` unambiguously targets it.
+        await page.locator('.xterm').last().click()
+        await page.keyboard.type('hello codex')
+        await page.keyboard.press('Enter')
+
+        // The fixture's session-created marker proves the CLI itself wrote
+        // its rollout JSONL. Strip newlines before matching -- xterm wraps
+        // long lines at the terminal's column width.
+        await expect.poll(async () => {
+          const buffer = await harness.getTerminalBuffer(terminalIdBefore)
+          const unwrapped = typeof buffer === 'string' ? buffer.replace(/\n/g, '') : ''
+          return /codex: session \S+ started/.test(unwrapped)
+        }, { timeout: 15_000 }).toBe(true)
+
+        /** Re-read the (possibly reshuffled) leaf for a given pane id. */
+        async function findLeafById(tid: string, paneId: string): Promise<any> {
+          const layout = await harness.getPaneLayout(tid)
+          return collectLeaves(layout).find((leaf) => leaf.id === paneId)
+        }
+
+        // The SERVER-SIDE identity capture proof. NO client candidate can
+        // exist here: the Rust server never emits
+        // `terminal.codex.durability.updated`, so the frozen client's codex
+        // candidate sender never fires -- identity arriving at all IS the
+        // server-locator proof. The client path is already validated (A7):
+        // the frozen client applies `terminal.session.associated`
+        // provider-generically (`App.tsx:1004-1017` -> panesSlice
+        // `sessionRef`, `resumeSessionId` cleared), and its conflict guard
+        // only drops a push when the pane ALREADY holds a DIFFERENT
+        // sessionRef -- impossible for fresh panes (the locator arms only
+        // unbound panes).
+        const associatedSessionId: string = await expect.poll(async () => {
+          const leaf = await findLeafById(tabId!, positivePaneId)
+          return leaf?.content?.sessionRef?.sessionId ?? leaf?.content?.resumeSessionId ?? null
+        }, { timeout: 15_000 }).not.toBeNull().then(async () => {
+          const leaf = await findLeafById(tabId!, positivePaneId)
+          return leaf?.content?.sessionRef?.sessionId ?? leaf?.content?.resumeSessionId
+        })
+        expect(associatedSessionId).toMatch(UUID_RE)
+        const positiveLeafAfterAssociation = await findLeafById(tabId!, positivePaneId)
+        expect(positiveLeafAfterAssociation?.content?.sessionRef?.provider).toBe('codex')
+
+        // Persisted across a reload too (the client's persist middleware +
+        // localStorage round trip that the restore chain depends on).
+        await page.evaluate(() => {
+          (window as any).__FRESHELL_TEST_HARNESS__?.dispatch({ type: 'persist/flushNow' })
+        })
+
+        // -------------------------------------------------------------
+        // Negative control: a SECOND codex pane that never submits.
+        // Proves the locator never false-binds an un-submitted terminal --
+        // the fixture writes no rollout without an Enter -- opened alongside
+        // the positive-case pane so both restore in the SAME server restart
+        // below.
+        // -------------------------------------------------------------
+        const neverSubmittedLeaf = await openCodexPaneAndGetLeaf(page, harness, tabId!)
+        const neverSubmittedTerminalIdBefore: string = neverSubmittedLeaf.content.terminalId
+        const neverSubmittedPaneId: string = neverSubmittedLeaf.id
+        expect(neverSubmittedTerminalIdBefore).toBeTruthy()
+        expect(neverSubmittedPaneId).not.toBe(positivePaneId)
+
+        await page.evaluate(() => {
+          (window as any).__FRESHELL_TEST_HARNESS__?.dispatch({ type: 'persist/flushNow' })
+        })
+
+        // -------------------------------------------------------------
+        // Full server restart (not a client reload) -- PTYs are lost; codex
+        // must respawn with `resume <id>` for the associated pane, and
+        // fresh (no `resume`) for the never-submitted one.
+        // -------------------------------------------------------------
+        if (!server.restart) {
+          throw new Error(`${e2eServerKind} E2eServerHandle does not implement restart()`)
+        }
+        await server.restart()
+
+        await page.reload({ waitUntil: 'domcontentloaded' })
+        await harness.waitForHarness()
+        await harness.waitForConnection()
+
+        await expect(async () => {
+          const status = await page.evaluate(() => (window as any).__FRESHELL_TEST_HARNESS__?.getWsReadyState())
+          expect(status).toBe('ready')
+        }).toPass({ timeout: 30_000 })
+
+        // Positive case: the restored pane's PTY receives
+        // `codex ... resume <id>` -- proven two independent ways: (1) the
+        // fixture's own greppable stdout marker, scoped to THIS pane's
+        // terminal, and (2) the argv log the fixture writes on every
+        // invocation (independent of terminal-buffer scraping).
+        await expect(async () => {
+          const leaf = await findLeafById(tabId!, positivePaneId)
+          expect(leaf?.content?.status).not.toBe('error')
+          expect(leaf?.content?.terminalId).toBeTruthy()
+        }).toPass({ timeout: 30_000 })
+
+        const restoredTerminalId: string | undefined = (await findLeafById(tabId!, positivePaneId))?.content?.terminalId
+        expect(restoredTerminalId).toBeTruthy()
+        await expect.poll(async () => {
+          const buffer = await harness.getTerminalBuffer(restoredTerminalId)
+          const unwrapped = typeof buffer === 'string' ? buffer.replace(/\n/g, '') : ''
+          return unwrapped.includes(`codex: resumed session ${associatedSessionId}`)
+        }, { timeout: 20_000 }).toBe(true)
+
+        // codex's `resumeArgs: ["resume", "{{sessionId}}"]` is a SUBCOMMAND
+        // appended LAST (after `-c` overrides) -- assert the ADJACENT PAIR
+        // anywhere in argv, never `argv[0]`.
+        const entries = await readArgvLog(argLogPath)
+        const resumed = entries.some((e) => {
+          const i = e.argv.indexOf('resume')
+          return i !== -1 && e.argv[i + 1] === associatedSessionId
+        })
+        expect(resumed).toBe(true)
+
+        // Negative case: the never-submitted pane restores FRESH -- no
+        // `resume` argv naming its (nonexistent) session, never a blank
+        // error state either. This is the "zero candidates -> keep
+        // watching, no bind" guarantee proven end-to-end.
+        await expect(async () => {
+          const leaf = await findLeafById(tabId!, neverSubmittedPaneId)
+          expect(leaf?.content?.status).not.toBe('error')
+          expect(leaf?.content?.terminalId).toBeTruthy()
+          // A fresh (non-resuming) codex launch never carries a
+          // sessionRef/resumeSessionId -- this pane never submitted, so the
+          // locator never resolved an association for it.
+          expect(leaf?.content?.sessionRef).toBeUndefined()
+          expect(leaf?.content?.resumeSessionId).toBeUndefined()
+        }).toPass({ timeout: 30_000 })
+
+        const restoredNeverSubmittedTerminalId: string | undefined =
+          (await findLeafById(tabId!, neverSubmittedPaneId))?.content?.terminalId
+        expect(restoredNeverSubmittedTerminalId).toBeTruthy()
+        await expect.poll(async () => {
+          const buffer = await page.evaluate((id: string) => {
+            return (window as any).__FRESHELL_TEST_HARNESS__?.getTerminalBuffer(id)
+          }, restoredNeverSubmittedTerminalId!)
+          return typeof buffer === 'string' && buffer.includes('codex> ')
+        }, { timeout: 15_000 }).toBe(true)
+      } finally {
+        await server.stop().catch(() => {})
+      }
+    } finally {
+      await fs.rm(sharedRoot, { recursive: true, force: true }).catch(() => {})
+    }
+  })
+})

From c64b4c3ee5b2a4660015efdb5fd523d6b4ac7697 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:56:32 -0700
Subject: [PATCH 61/87] fix(claude): resume-in-place reapplies
 model/permissionMode/effort from the ledger record (P1.13)

---
 crates/freshell-freshagent/src/claude.rs | 195 ++++++++++++++++++++++-
 1 file changed, 187 insertions(+), 8 deletions(-)

diff --git a/crates/freshell-freshagent/src/claude.rs b/crates/freshell-freshagent/src/claude.rs
index 029692424..0e4afc5e0 100644
--- a/crates/freshell-freshagent/src/claude.rs
+++ b/crates/freshell-freshagent/src/claude.rs
@@ -540,6 +540,30 @@ impl FreshClaudeState {
         let Some(transcript) = crate::claude_snapshot::locate_transcript(durable) else {
             return Err(ResumeClaudeError::NotFound);
         };
+        // P1.13 (Task 10): recover the pane's recorded settings from the ledger so a
+        // resume-in-place does not silently revert model/permissionMode/effort. V7/A10
+        // alarm gate: alarm ONLY when the ledger PROVES prior recording yet no snapshot
+        // is recoverable. Never-recorded transcripts (the entire pre-existing
+        // ~/.claude/projects population — resume_for_attach exists FOR them) stay silent.
+        let sink = self.identity_sink();
+        let recovered = sink
+            .as_ref()
+            .and_then(|s| s.load_settings("claude", durable));
+        if recovered.is_none()
+            && sink
+                .as_ref()
+                .is_some_and(|s| s.was_recorded("claude", durable))
+        {
+            // Recorded before, unrecoverable now — the genuine anomaly.
+            tracing::warn!(session = %durable, "freshagent.claude.settings_record_unrecoverable");
+            self.emit_fresh_agent_error(
+                durable,
+                session_type_str(msg.session_type), // preserves freshclaude vs kilroy in the frame
+                "SETTINGS_RESET",
+                "Session settings could not be recovered after restart - the agent is running with default model and permissions. Reconfirm your settings.",
+            );
+        }
+        let rec = recovered.clone().unwrap_or_default();
         // The CLI's resume lookup is scoped to the ORIGINAL cwd's project slug
         // (ledger A15) -- resume with the cwd recorded in the transcript itself.
         // If that directory is gone, fall back to path-based resume
@@ -549,7 +573,12 @@ impl FreshClaudeState {
             .filter(|c| std::path::Path::new(c).is_dir());
         let (resume_value, resume_cwd) = match original_cwd {
             Some(cwd) => (json!(durable), json!(cwd)),
-            None => (json!(transcript.to_string_lossy()), json!(msg.cwd)),
+            // Attach cwd stays primary; the ledger record's cwd is a FINAL
+            // fallback only when both existing sources are absent (Task 10).
+            None => (
+                json!(transcript.to_string_lossy()),
+                json!(msg.cwd.clone().or_else(|| rec.cwd.clone())),
+            ),
         };
 
         let (mut child, mut stdin, stdout, ownership_id) = spawn_sidecar()
@@ -560,9 +589,11 @@ impl FreshClaudeState {
             "type": "create",
             "requestId": request_id,
             "cwd": resume_cwd,
-            "model": Value::Null,
-            "permissionMode": Value::Null,
-            "effort": Value::Null,
+            // Recovered from the ledger record (Task 10); `json!` serializes `None`
+            // as `null`, preserving today's fallback wire shape exactly on a miss.
+            "model": rec.model,
+            "permissionMode": rec.permission_mode,
+            "effort": rec.effort,
             "resumeSessionId": resume_value,
         });
         if let Err(err) = write_line(&mut stdin, &create_req).await {
@@ -585,15 +616,16 @@ impl FreshClaudeState {
         // envelope and the frozen client routes by envelope sessionId
         // (fresh-agent-ws.ts:180-183) -- a fresh key would strand the pane.
         // The sidecar's created id is the eviction identity guard for this consumer.
-        // `settings: None` (P1.13): until Task 10 resolves the ledger record for the
-        // resume path, record NOTHING here — writing would launder a blank row under
-        // the new cliSessionId (V7/A10).
+        // `settings` (P1.13, Task 10): `Some(rec)` re-records the row under any new
+        // cliSessionId (the old durable's row keeps serving `load_settings`, so later
+        // attaches with the old id still resolve — no repeat-fire, V7 §4); `None`
+        // records nothing (no laundered blank row under the new id, V7/A10).
         let consumer = self.spawn_consumer(
             reader,
             msg.session_id.clone(),
             session_type.clone(),
             sidecar_session_id.clone(),
-            None,
+            recovered,
         );
         self.sessions.lock().await.insert(
             msg.session_id.clone(),
@@ -1990,6 +2022,153 @@ rl.on('line', (line) => {
         assert!(b.settings.cwd.is_some());
     }
 
+    // ── resume settings-from-ledger (P1.13, Task 10) ─────────────────────────────
+
+    /// P1.13 (Task 10): resume-in-place must reapply the pane's recorded
+    /// model/permissionMode/effort from the ledger record instead of sending Nulls —
+    /// the known defect where a restarted freshclaude/kilroy pane silently reverted
+    /// its settings. The fake sidecar logs the WHOLE create-request JSON per spawn,
+    /// so the wire itself is the assertion surface.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn resume_for_attach_reapplies_settings_from_ledger() {
+        let _guard = CLAUDE_ENV_LOCK.lock().await;
+        let env = FakeClaudeSidecarEnv::install();
+        let home = tempfile::tempdir().unwrap();
+        const DURABLE: &str = "dddddddd-dddd-4ddd-8ddd-dddddddddddd";
+        write_fake_transcript(home.path(), DURABLE);
+        std::env::set_var("CLAUDE_CONFIG_DIR", home.path());
+
+        let (state, _rx) = state_with_bus();
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        fake.seed(
+            "claude",
+            DURABLE,
+            crate::identity_sink::FreshAgentSettings {
+                model: Some("opus-x".into()),
+                sandbox: None,
+                permission_mode: Some("plan".into()),
+                effort: Some("high".into()),
+                cwd: None,
+            },
+        );
+        state.set_identity_sink(fake);
+
+        // Drive the donor resume flow (attach to DURABLE with a transcript on disk).
+        state
+            .handle_attach(attach_msg_with_resume("client-nanoid-settings", DURABLE))
+            .await;
+        std::env::remove_var("CLAUDE_CONFIG_DIR");
+
+        let log = std::fs::read_to_string(env.spawn_log_path()).unwrap();
+        let create_req: serde_json::Value =
+            serde_json::from_str(log.lines().next().expect("one spawn-logged create request"))
+                .unwrap();
+        assert_eq!(create_req["model"], "opus-x");
+        assert_eq!(create_req["permissionMode"], "plan");
+        assert_eq!(create_req["effort"], "high");
+        drop(env);
+    }
+
+    /// V7/A10: record misses are ROUTINE — `resume_for_attach` exists precisely to
+    /// serve never-tracked transcripts (every claude-CLI-created and pre-ship session
+    /// in the shared `~/.claude/projects` store). They resume silently with nulls
+    /// exactly as today (the preserved fallback), and record NOTHING under the new
+    /// cliSessionId (settings: None ⇒ no laundered blank row — Task 9).
+    #[tokio::test(flavor = "multi_thread")]
+    async fn resume_without_record_is_silent_and_sends_nulls() {
+        let _guard = CLAUDE_ENV_LOCK.lock().await;
+        let env = FakeClaudeSidecarEnv::install();
+        let home = tempfile::tempdir().unwrap();
+        const DURABLE: &str = "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee";
+        write_fake_transcript(home.path(), DURABLE);
+        std::env::set_var("CLAUDE_CONFIG_DIR", home.path());
+
+        let (state, mut rx) = state_with_bus();
+        // Deliberately empty: no record, no snapshot.
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        state.set_identity_sink(fake.clone());
+
+        state
+            .handle_attach(attach_msg_with_resume("client-nanoid-norec", DURABLE))
+            .await;
+        std::env::remove_var("CLAUDE_CONFIG_DIR");
+
+        // Today's behavior preserved as the silent fallback: nulls on the wire.
+        let log = std::fs::read_to_string(env.spawn_log_path()).unwrap();
+        let create_req: serde_json::Value =
+            serde_json::from_str(log.lines().next().expect("one spawn-logged create request"))
+                .unwrap();
+        assert_eq!(create_req["model"], Value::Null);
+        assert_eq!(create_req["permissionMode"], Value::Null);
+        assert_eq!(create_req["effort"], Value::Null);
+
+        // Bounded bus drain (pattern from Task 5): NO SETTINGS_RESET frame may appear.
+        while let Ok(frame) =
+            tokio::time::timeout(std::time::Duration::from_secs(1), rx.recv()).await
+        {
+            let Ok(text) = frame else { break };
+            assert!(
+                !text.contains("SETTINGS_RESET"),
+                "never-recorded resume must stay silent"
+            );
+        }
+        // No defaults laundering: no binding row was written under the new cliSessionId.
+        assert!(
+            fake.bindings.lock().unwrap().is_empty(),
+            "a load_settings miss must not write a blank row"
+        );
+        drop(env);
+    }
+
+    /// The genuine anomaly (V7/A10): the ledger PROVES prior fresh-agent recording,
+    /// yet no snapshot is recoverable — the only resume case that alarms.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn resume_with_prior_record_but_unrecoverable_settings_alarms() {
+        let _guard = CLAUDE_ENV_LOCK.lock().await;
+        let env = FakeClaudeSidecarEnv::install();
+        let home = tempfile::tempdir().unwrap();
+        const DURABLE: &str = "ffffffff-ffff-4fff-8fff-ffffffffffff";
+        write_fake_transcript(home.path(), DURABLE);
+        std::env::set_var("CLAUDE_CONFIG_DIR", home.path());
+
+        let (state, mut rx) = state_with_bus();
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        // was_recorded=true, load_settings=None — the SETTINGS_RESET-positive fixture.
+        fake.seed_recorded_only("claude", DURABLE);
+        state.set_identity_sink(fake);
+
+        state
+            .handle_attach(attach_msg_with_resume("client-nanoid-alarm", DURABLE))
+            .await;
+        std::env::remove_var("CLAUDE_CONFIG_DIR");
+
+        let mut found = false;
+        while let Ok(frame) =
+            tokio::time::timeout(std::time::Duration::from_secs(2), rx.recv()).await
+        {
+            let Ok(text) = frame else { break };
+            let frame: Value = serde_json::from_str(&text).unwrap();
+            if frame["event"]["code"] == "SETTINGS_RESET" {
+                // Top-level sessionType/provider (locator resolution) + a
+                // user-facing message (the banner shows the message, never the code).
+                assert_eq!(frame["event"]["type"], "freshAgent.error");
+                assert_eq!(frame["sessionType"], "freshclaude");
+                assert_eq!(frame["provider"], "claude");
+                assert!(frame["event"]["message"]
+                    .as_str()
+                    .unwrap()
+                    .contains("Reconfirm your settings"));
+                found = true;
+                break;
+            }
+        }
+        assert!(
+            found,
+            "recorded-but-unrecoverable resume must broadcast SETTINGS_RESET"
+        );
+        drop(env);
+    }
+
     /// Ledger A9: consumer exit (== sidecar death) must evict the dead session AND its
     /// `cli_index` entries — kill/shutdown are NOT the only eviction paths. Without this,
     /// a dead-but-tracked session makes the tracked⇒no-op attach row strand panes forever.

From 41b5013b4cb8d30828394a1ad7a545a847644308 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:56:51 -0700
Subject: [PATCH 62/87] test(e2e): codex SIGKILL-inside-locator-window leaves
 durable fresh-by-race pending marker

---
 .../specs/pane-ledger-restart-rust.spec.ts    | 73 +++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts b/test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts
index 3f6d4830d..2fb5ac8c5 100644
--- a/test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts
+++ b/test/e2e-browser/specs/pane-ledger-restart-rust.spec.ts
@@ -253,4 +253,77 @@ test.describe('pane-identity ledger restart durability', () => {
       await fs.rm(sharedRoot, { recursive: true, force: true }).catch(() => {})
     }
   })
+
+  test('SIGKILL inside the codex locator window leaves a durable fresh-by-race marker', async ({ page, e2eServerKind }) => {
+    expect(e2eServerKind).toBe('rust')
+    const sharedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'pane-ledger-locator-'))
+    let capturedHome = ''
+    try {
+      const fakeCodex = await installFakeCli(path.join(sharedRoot, 'bin'), 'codex', 'fake-codex-terminal.mjs')
+      const seed = seedConfig()
+      // ROLLOUT GATE (REQUIRED for this wall's premise): the fake codex
+      // WRITES a real rollout JSONL on its FIRST Enter unless
+      // FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH is set and the gate file
+      // never exists (fake-codex-terminal.mjs:76-86). Point it at a
+      // path we NEVER create, so identity deterministically never resolves
+      // and the pending marker is the only evidence — no race against the
+      // SIGKILL.
+      const rolloutGate = path.join(sharedRoot, 'rollout-gate-never-created')
+      const server = new RustServer({
+        env: { CODEX_CMD: fakeCodex, FAKE_CODEX_TERMINAL_ROLLOUT_GATE_PATH: rolloutGate },
+        setupHome: async (homeDir: string) => {
+          capturedHome = homeDir
+          await seed(homeDir)
+        },
+      })
+      const info = await server.start()
+      try {
+        await page.goto(`${info.baseUrl}/?token=${info.token}&e2e=1`)
+        const harness = new TestHarness(page)
+        await harness.waitForHarness()
+        await harness.waitForConnection()
+        await selectShellIfPickerShowing(page)
+        await expect(page.locator('.xterm').first()).toBeVisible({ timeout: 30_000 })
+
+        const ledgerDir = path.join(capturedHome, '.freshell', 'pane-ledger')
+        await openCliPane(page, /^Codex CLI$/i)
+        await within5s(
+          async () => (await listFiles(path.join(ledgerDir, 'pending'))).some((f) => f.endsWith('.json')),
+          'codex pending marker on disk',
+        )
+
+        // The codex pending marker exists from SPAWN (codex is in
+        // MARKER_MODES), but the locator WINDOW is Enter-anchored: it only
+        // opens on the pane's first submit. Click the fresh pane's xterm
+        // (`.last()` — only the boot shell and this pane exist) and type +
+        // Enter so the SIGKILL below lands INSIDE an open window. A short
+        // settle lets the Enter complete the browser -> WS -> PTY hop
+        // before the kill.
+        await page.locator('.xterm').last().click()
+        await page.keyboard.type('hello codex')
+        await page.keyboard.press('Enter')
+        await page.waitForTimeout(500)
+
+        // SIGKILL INSIDE the locator window (the never-created gate means
+        // no rollout exists for the fake, so identity never resolves — the
+        // marker is the only evidence identity was in flight).
+        await server.restartAbrupt()
+        await expect(async () => {
+          const status = await page.evaluate(() => (window as any).__FRESHELL_TEST_HARNESS__?.getWsReadyState())
+          expect(status).toBe('ready')
+        }).toPass({ timeout: 60_000 })
+
+        // The restarted boot scan PRESERVED the marker (fresh-by-race
+        // distinguishable from fresh-by-intent) — and nothing bound it.
+        const pending = (await listFiles(path.join(ledgerDir, 'pending'))).filter((f) => f.endsWith('.json'))
+        expect(pending.length).toBeGreaterThan(0)
+        const bindings = await listFiles(path.join(ledgerDir, 'bindings'))
+        expect(bindings.filter((f) => f.endsWith('.json'))).toHaveLength(0)
+      } finally {
+        await server.stop().catch(() => {})
+      }
+    } finally {
+      await fs.rm(sharedRoot, { recursive: true, force: true }).catch(() => {})
+    }
+  })
 })

From 557749e56554e85ebf003822ed52444ae1cc84bf Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 06:59:52 -0700
Subject: [PATCH 63/87] feat(client): verdict-driven create args; bounded
 SESSION_RESERVED/INVALID_TERMINAL_ID re-drive with auto-resolve exhaustion
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Task 12 of the pane.reconcile client adoption:

- A1 fix: add terminalContent?.reconcileEpoch to the create-or-attach
  effect dependency array so verdict folds into an already-mounted pane
  (same createRequestId - never re-minted) re-fire the effect. terminalId
  stays intentionally out of the deps.
- Create-arg precedence: pendingReconcile 'respawn' sends the server-named
  sessionRef with restore:true (loud guard on provider mismatch);
  'fresh' omits resume identity entirely; both suppress fresh-recovery
  intent. pendingReconcile is cleared by the reducer on terminal.created.
- SESSION_RESERVED bounded re-drive: re-send the SAME terminal.create
  after max(retryAfterMs, 250ms), inside a 30s wall-clock window
  (> 20s lease TTL + margin). Window survives effect re-fires (no refunds).
- Exhaustion auto-resolve (council rule 8): single-pane
  pane.reconcile.request via the existing ws.onMessage broadcast
  subscription, folding ONLY the reconcileId this pane minted
  (fold-ownership rule) - attach silently or dead_session/fresh with a
  visible notice; never a wedge, never a duplicate.
- F9: launch-time INVALID_TERMINAL_ID for a still-creating pane with no
  matching launch attempt gets a bounded 5 x 500ms same-requestId pump
  before surfacing status 'error'.
- One-shot reconcileNotice rendered via writeLocalXtermNotice after
  attach / terminal.created, then cleared from the store.

Tests: test/unit/client/components/TerminalView.session-reserved.test.tsx
(8 tests, written RED-first; the two fold-on-mounted tests failed
specifically because reconcileEpoch was missing from the effect deps).
All 23 TerminalView unit suites pass (286 tests); typecheck:client clean.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 src/components/TerminalView.tsx               | 230 ++++++++-
 .../TerminalView.session-reserved.test.tsx    | 454 ++++++++++++++++++
 2 files changed, 681 insertions(+), 3 deletions(-)
 create mode 100644 test/unit/client/components/TerminalView.session-reserved.test.tsx

diff --git a/src/components/TerminalView.tsx b/src/components/TerminalView.tsx
index 548d39943..3c07a9555 100644
--- a/src/components/TerminalView.tsx
+++ b/src/components/TerminalView.tsx
@@ -13,12 +13,15 @@ import { shallowEqual } from 'react-redux'
 import { useAppDispatch, useAppSelector, useAppStore } from '@/store/hooks'
 import { updateTab, switchToNextTab, switchToPrevTab } from '@/store/tabsSlice'
 import {
+  clearPaneReconcileNotice,
   consumePaneRefreshRequest,
   repairCodexIdentityMismatch,
   splitPane,
   updatePaneContent,
   updatePaneTitle,
 } from '@/store/panesSlice'
+import { buildReconcileRequestForPanes, foldVerdicts } from '@/lib/pane-reconcile'
+import type { PaneReconcileRequest } from '@shared/ws-protocol'
 import { updateSessionActivity } from '@/store/sessionActivitySlice'
 import { recordPaneTabActivity } from '@/store/tabRecencySlice'
 import { updateSettingsLocal } from '@/store/settingsSlice'
@@ -156,6 +159,15 @@ const QUARANTINE_REPAIR_TIMEOUT_MS = 2000
 export const RATE_LIMIT_RETRY_MAX_ATTEMPTS = 5
 export const RATE_LIMIT_RETRY_BASE_MS = 2000
 export const RATE_LIMIT_RETRY_MAX_MS = 12000
+// Bounded re-drive (Task 12): SESSION_RESERVED honors the server hint inside
+// a 30s window (> the 20s sessionRef lease TTL + margin — a wall-clock
+// backstop, NOT a spawn budget; keep it > TTL + margin if the TTL env knob
+// changes defaults); launch-time INVALID_TERMINAL_ID gets 5 x 500ms.
+// On exhaustion: single-pane reconcile -> fold (auto-resolve, council rule 8).
+export const RESERVE_RETRY_WINDOW_MS = 30_000
+export const RESERVE_RETRY_FLOOR_MS = 250
+export const INVALID_TERMINAL_LAUNCH_RETRY_MAX_ATTEMPTS = 5
+export const INVALID_TERMINAL_LAUNCH_RETRY_DELAY_MS = 500
 const MOBILE_KEYBAR_HEIGHT_PX = 40
 const MOBILE_KEY_REPEAT_INITIAL_DELAY_MS = 320
 const MOBILE_KEY_REPEAT_INTERVAL_MS = 70
@@ -567,6 +579,16 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
   const lastSessionActivityAtRef = useRef(0)
   const paneLastInputAtRef = useRef<number | undefined>(paneLastInputAt)
   const rateLimitRetryRef = useRef<{ count: number; timer: ReturnType<typeof setTimeout> | null }>({ count: 0, timer: null })
+  // Task 12 bounded re-drive state. reserveWindowStart is wall-clock so a
+  // remount mid-standoff cannot refund the SESSION_RESERVED window.
+  const reconcileRedriveRef = useRef<{
+    reserveWindowStart: number | null
+    invalidAttempts: number
+    timer: ReturnType<typeof setTimeout> | null
+  }>({ reserveWindowStart: null, invalidAttempts: 0, timer: null })
+  // Fold-ownership rule (see pane-reconcile.ts): this pane folds ONLY the
+  // pane.reconcile.result whose reconcileId it minted at exhaustion.
+  const exhaustionReconcileRef = useRef<PaneReconcileRequest | null>(null)
   const freshRecoveryRequestIdRef = useRef<string | null>(null)
   const freshRecoveryIntentRef = useRef<TerminalFreshRecoveryIntent | undefined>(undefined)
   const turnCompleteSignalStateRef = useRef(createTurnCompleteSignalParserState())
@@ -2755,6 +2777,25 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
       retryState.count = 0
     }
 
+    // Task 12 bounded re-drive (SESSION_RESERVED / launch INVALID_TERMINAL_ID).
+    // Timer cancellation is separate from a full reset: an effect re-fire must
+    // drop the stale closure's timer WITHOUT refunding the reserve window or
+    // the invalid-terminal attempt budget.
+    const clearReconcileRedriveTimer = () => {
+      const redriveState = reconcileRedriveRef.current
+      if (redriveState.timer) {
+        clearTimeout(redriveState.timer)
+        redriveState.timer = null
+      }
+    }
+
+    const resetReconcileRedrive = () => {
+      clearReconcileRedriveTimer()
+      const redriveState = reconcileRedriveRef.current
+      redriveState.reserveWindowStart = null
+      redriveState.invalidAttempts = 0
+    }
+
     // Cancels a pending create-retry resend WITHOUT refunding the attempt
     // count. Used when terminal.created arrives: the ack makes a pending
     // resend moot, but it is NOT launch success — a launch-time
@@ -2788,9 +2829,37 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
     }
 
     const sendCreate = (requestId: string) => {
-      const recoveryIntent = getFreshRecoveryIntent(requestId)
-      const restore = recoveryIntent ? false : getRestoreFlag(requestId)
-      const createSessionState = getCreateSessionStateFromRef(contentRef)
+      // Reconcile verdict precedence (Task 12): a folded respawn verdict's
+      // server-named sessionRef WINS over any other inference (restore flag,
+      // fresh-recovery intent); a folded fresh verdict omits resume identity
+      // entirely. pendingReconcile is cleared by the reducer once
+      // terminal.created folds a terminalId into this pane.
+      const pendingReconcile = contentRef.current?.pendingReconcile
+      const recoveryIntent = pendingReconcile ? undefined : getFreshRecoveryIntent(requestId)
+      if (pendingReconcile === 'respawn') {
+        const respawnSessionRef = contentRef.current?.sessionRef
+        if (!respawnSessionRef || respawnSessionRef.provider !== mode) {
+          // Invariant (shared with resetPaneForReconcileCreate): a respawn
+          // create must carry a mode-matching sessionRef — the server create
+          // path filters on it, and a mismatch spawns identity-less. The
+          // reducer degrades mismatches to fresh, so reaching here means
+          // unexpected state. Guard loudly rather than silently.
+          log.error('sendCreate: respawn create without a mode-matching sessionRef', {
+            paneId: paneIdRef.current,
+            requestId,
+            mode,
+            sessionRefProvider: respawnSessionRef?.provider,
+          })
+        }
+      }
+      const restore = pendingReconcile
+        ? pendingReconcile === 'respawn'
+        : recoveryIntent
+          ? false
+          : getRestoreFlag(requestId)
+      const createSessionState: ReturnType<typeof getCreateSessionStateFromRef> = pendingReconcile === 'fresh'
+        ? {}
+        : getCreateSessionStateFromRef(contentRef)
       launchAttemptRef.current = {
         requestId,
         restore,
@@ -3041,10 +3110,118 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
         return true
       }
 
+      // Bounded re-drive (Task 12): SESSION_RESERVED honors the server hint
+      // inside a 30s window (> lease TTL + margin); launch-time
+      // INVALID_TERMINAL_ID gets 5 x 500ms. On exhaustion: single-pane
+      // reconcile -> fold (auto-resolve, council rule 8) — never a permanent
+      // error card for a standoff, never a silent wedge, never a duplicate
+      // (the reconcile verdict is folded, not blindly re-created).
+      const resolveReserveExhaustionViaReconcile = () => {
+        resetReconcileRedrive()
+        const request = buildReconcileRequestForPanes(appStore.getState(), [
+          { tabId, paneId: paneIdRef.current },
+        ])
+        if (!request) {
+          // The pane lost its reconcilable state (no createRequestId) —
+          // degrade loudly instead of wedging silently.
+          failLaunch('The session stayed reserved and this pane could not be reconciled.', true)
+          return
+        }
+        exhaustionReconcileRef.current = request
+        ws.send(request)
+      }
+
+      const redriveAfterSessionReserved = (requestId: string, retryAfterMs?: number) => {
+        const redriveState = reconcileRedriveRef.current
+        const now = Date.now()
+        if (redriveState.reserveWindowStart === null) {
+          redriveState.reserveWindowStart = now
+        }
+        if (now - redriveState.reserveWindowStart >= RESERVE_RETRY_WINDOW_MS) {
+          resolveReserveExhaustionViaReconcile()
+          return
+        }
+        const delay = Math.max(
+          typeof retryAfterMs === 'number' ? retryAfterMs : RESERVE_RETRY_FLOOR_MS,
+          RESERVE_RETRY_FLOOR_MS,
+        )
+        clearReconcileRedriveTimer()
+        redriveState.timer = setTimeout(() => {
+          redriveState.timer = null
+          if (requestIdRef.current !== requestId) return
+          if (terminalIdRef.current) return // anchored meanwhile
+          // Re-send the SAME terminal.create — createRequestId is NEVER
+          // re-minted (council rule 2).
+          sendCreate(requestId)
+        }, delay)
+      }
+
+      // F9: the server no longer knows the terminal this still-launching pane
+      // points at. Pump bounded same-requestId re-creates instead of minting a
+      // fresh recovery identity for a pane that never finished launching.
+      const redriveAfterLaunchInvalidTerminal = (deadTerminalId: string | undefined): boolean => {
+        const requestId = requestIdRef.current
+        if (!requestId) return false
+        const redriveState = reconcileRedriveRef.current
+        if (redriveState.invalidAttempts >= INVALID_TERMINAL_LAUNCH_RETRY_MAX_ATTEMPTS) return false
+        // The terminal existed before the server lost it — keep restore
+        // semantics and the server-side rate-limit exemption on every resend.
+        addTerminalRestoreRequestId(requestId)
+        // Drop the dead terminal's identity so the retried create starts
+        // clean, but keep the pane in 'creating' (NOT 'error') while the
+        // pump runs. Mirrors retryLaunchAfterInvalidTerminal's cleanup.
+        clearQuarantineRepair()
+        setIsAttaching(false)
+        currentAttachRef.current = null
+        launchAttemptRef.current = null
+        deferredAttachStateRef.current = {
+          mode: 'none',
+          pendingIntent: null,
+          pendingSinceSeq: 0,
+          pendingReason: 'initial_hydrate',
+        }
+        if (deadTerminalId) {
+          clearTerminalCursor(deadTerminalId)
+          resetParserAppliedSurface()
+          forgetSentViewport(deadTerminalId)
+        }
+        lastSentViewportRef.current = null
+        terminalIdRef.current = undefined
+        applySeqState(createAttachSeqState())
+        updateContent({ terminalId: undefined, streamId: undefined, status: 'creating' })
+        const attempt = () => {
+          if (requestIdRef.current !== requestId) return
+          if (terminalIdRef.current) return // anchored — stop the pump
+          if (redriveState.invalidAttempts >= INVALID_TERMINAL_LAUNCH_RETRY_MAX_ATTEMPTS) {
+            failLaunch('The server no longer knows this terminal and recreating it kept failing.', true)
+            return
+          }
+          redriveState.invalidAttempts += 1
+          // SAME createRequestId — never re-minted (council rule 2).
+          sendCreate(requestId)
+          clearReconcileRedriveTimer()
+          redriveState.timer = setTimeout(attempt, INVALID_TERMINAL_LAUNCH_RETRY_DELAY_MS)
+        }
+        attempt()
+        return true
+      }
+
       unsub = ws.onMessage((msg) => {
         const tid = terminalIdRef.current
         const reqId = requestIdRef.current
 
+        if (msg.type === 'pane.reconcile.result') {
+          // Fold-ownership rule (pane-reconcile.ts): fold ONLY the result
+          // whose reconcileId this pane minted at exhaustion; foreign
+          // reconciles (App boot, other panes) are silently skipped.
+          const pendingReconcileRequest = exhaustionReconcileRef.current
+          if (pendingReconcileRequest && msg.reconcileId === pendingReconcileRequest.reconcileId) {
+            exhaustionReconcileRef.current = null
+            foldVerdicts(dispatch, pendingReconcileRequest, msg)
+          }
+          return
+        }
+
         const markFirstOutputIfNeeded = (raw: string) => {
           if (
             raw.length > 0
@@ -3769,6 +3946,9 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
 
         if (msg.type === 'terminal.created' && msg.requestId === reqId) {
           cancelCreateRetryTimer()
+          // The create round succeeded — the SESSION_RESERVED window and the
+          // launch INVALID_TERMINAL_ID attempt budget both reset.
+          resetReconcileRedrive()
           // This requestId has anchored -- it now has a real terminalId, so
           // any pending restore flag for it is resolved. Clear it explicitly
           // so it can't be resurrected (it's a non-destructive peek until
@@ -3874,6 +4054,13 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
           } else {
             attachTerminal(newId, 'viewport_hydrate', { clearViewportFirst: true })
           }
+          // One-shot reconcile notice (respawn/fresh verdicts): render it now
+          // that the pane anchored, then clear it from the store.
+          const createdReconcileNotice = contentRef.current?.reconcileNotice
+          if (createdReconcileNotice) {
+            writeLocalXtermNotice(term, `\r\n${createdReconcileNotice}\r\n`)
+            dispatch(clearPaneReconcileNotice({ tabId, paneId: paneIdRef.current }))
+          }
         }
 
         if (msg.type === 'terminal.status' && msg.terminalId === tid) {
@@ -4091,6 +4278,15 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
           return
         }
 
+        if (msg.type === 'error' && msg.code === 'SESSION_RESERVED' && reqId && msg.requestId === reqId) {
+          // Another create holds this sessionRef's lease. Re-drive the SAME
+          // terminal.create after the server's hint (floored), bounded by a
+          // wall-clock window; on exhaustion, auto-resolve via a single-pane
+          // reconcile instead of surfacing a dead-end error.
+          redriveAfterSessionReserved(reqId, msg.retryAfterMs)
+          return
+        }
+
         if (msg.type === 'error' && msg.requestId === reqId) {
           if (msg.code === 'RATE_LIMITED') {
             const scheduled = scheduleCreateRetry(reqId, 'rate-limit')
@@ -4194,6 +4390,18 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
             failLaunch(msg.message || 'The terminal failed before it finished starting.', launchAttempt!.restore, currentTerminalId)
             return
           }
+          // F9: launch-time INVALID_TERMINAL_ID for a pane that is still
+          // 'creating' but has no matching launch attempt (e.g. a remount or
+          // reconcile fold mid-launch). A numeric terminalExitCode means the
+          // CLI spawned and died — that shape must not be respawn-stormed.
+          if (
+            currentTerminalId
+            && current?.status === 'creating'
+            && typeof msg.terminalExitCode !== 'number'
+            && redriveAfterLaunchInvalidTerminal(currentTerminalId)
+          ) {
+            return
+          }
           // Only auto-reconnect if terminal hasn't already exited.
           // This prevents an infinite respawn loop when terminals fail immediately
           // (e.g., due to permission errors on cwd). User must explicitly restart.
@@ -4438,6 +4646,14 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
           attachTerminal(currentTerminalId, intent, intent === 'viewport_hydrate'
             ? viewportHydrateReplayOptions(contentRef.current)
             : undefined)
+          // One-shot reconcile notice (attach/corrected/duplicate verdicts):
+          // render it on the attach that the verdict fold re-fired, then
+          // clear it from the store.
+          const attachReconcileNotice = contentRef.current?.reconcileNotice
+          if (attachReconcileNotice) {
+            writeLocalXtermNotice(term, `\r\n${attachReconcileNotice}\r\n`)
+            dispatch(clearPaneReconcileNotice({ tabId, paneId: paneIdRef.current }))
+          }
         }
       } else {
         deferredAttachStateRef.current = {
@@ -4454,6 +4670,9 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
 
     return () => {
       clearRateLimitRetry()
+      // Cancel only the timer: the reserve window and the invalid-terminal
+      // attempt budget must survive effect re-fires (no refunds).
+      clearReconcileRedriveTimer()
       unsub()
       unsubReconnect()
       if (hydrationRegisteredRef.current) {
@@ -4465,6 +4684,10 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
   // - isTerminal: skip effect for non-terminal panes
   // - paneId: unique identifier for this pane instance
   // - terminalContent?.createRequestId: re-run when createRequestId changes (reconnect after INVALID_TERMINAL_ID)
+  // - terminalContent?.reconcileEpoch: re-run when a pane.reconcile verdict folds
+  //   into an already-mounted pane. Verdict folds PRESERVE createRequestId
+  //   (council rule 2 — never re-minted), so the epoch bump is the ONLY signal
+  //   that a fold needs a fresh create/attach round (A1 fix).
   // - updateContent: stable callback (uses refs internally)
   // - ws: WebSocket client instance
   //
@@ -4484,6 +4707,7 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
     suppressNetworkEffects,
     shouldWaitForProviderBehavior,
     terminalContent?.createRequestId,
+    terminalContent?.reconcileEpoch,
     updateContent,
     ws,
     dispatch,
diff --git a/test/unit/client/components/TerminalView.session-reserved.test.tsx b/test/unit/client/components/TerminalView.session-reserved.test.tsx
new file mode 100644
index 000000000..d816db718
--- /dev/null
+++ b/test/unit/client/components/TerminalView.session-reserved.test.tsx
@@ -0,0 +1,454 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render } from '@testing-library/react'
+import { configureStore } from '@reduxjs/toolkit'
+import { Provider, useSelector } from 'react-redux'
+import tabsReducer from '@/store/tabsSlice'
+import panesReducer, {
+  applyReconcileAttach,
+  resetPaneForReconcileCreate,
+  RECONCILE_NOTICE_CORRECTED,
+} from '@/store/panesSlice'
+import settingsReducer, { defaultSettings } from '@/store/settingsSlice'
+import connectionReducer from '@/store/connectionSlice'
+import type { PaneNode, TerminalPaneContent } from '@/store/paneTypes'
+
+// Task 12: verdict-driven create args, SESSION_RESERVED bounded re-drive,
+// launch-time INVALID_TERMINAL_ID bounded re-drive (F9), and exhaustion
+// auto-resolve via a single-pane reconcile (council rule 8).
+//
+// Mounting scaffold copied from TerminalView.restore-flag-persistence.test.tsx.
+
+const wsHarness = vi.hoisted(() => {
+  const messageHandlers = new Set<(msg: any) => void>()
+  const send = vi.fn()
+  const connect = vi.fn().mockResolvedValue(undefined)
+  const onMessage = vi.fn((handler: (msg: any) => void) => {
+    messageHandlers.add(handler)
+    return () => messageHandlers.delete(handler)
+  })
+  const onReconnect = vi.fn(() => () => {})
+  return {
+    send,
+    connect,
+    onMessage,
+    onReconnect,
+    emit(msg: any) {
+      for (const handler of [...messageHandlers]) handler(msg)
+    },
+    reset() {
+      messageHandlers.clear()
+      send.mockReset()
+      connect.mockClear()
+      onMessage.mockClear()
+      onReconnect.mockClear()
+    },
+  }
+})
+
+vi.mock('@/lib/ws-client', () => ({
+  getWsClient: () => ({
+    send: wsHarness.send,
+    connect: wsHarness.connect,
+    onMessage: wsHarness.onMessage,
+    onReconnect: wsHarness.onReconnect,
+  }),
+}))
+
+vi.mock('@/lib/terminal-themes', () => ({
+  getTerminalTheme: () => ({}),
+}))
+
+vi.mock('lucide-react', () => ({
+  Loader2: ({ className }: { className?: string }) => <svg data-testid="loader" className={className} />,
+}))
+
+const terminalInstances = vi.hoisted(() => [] as any[])
+
+vi.mock('@xterm/xterm', () => ({
+  Terminal: class {
+    options: Record<string, unknown> = {}
+    cols = 80
+    rows = 24
+    open = vi.fn()
+    loadAddon = vi.fn()
+    registerLinkProvider = vi.fn(() => ({ dispose: vi.fn() }))
+    write = vi.fn((_data: string, cb?: () => void) => cb?.())
+    writeln = vi.fn()
+    clear = vi.fn()
+    dispose = vi.fn()
+    onData = vi.fn(() => ({ dispose: vi.fn() }))
+    onTitleChange = vi.fn(() => ({ dispose: vi.fn() }))
+    attachCustomKeyEventHandler = vi.fn()
+    attachCustomWheelEventHandler = vi.fn()
+    getSelection = vi.fn(() => '')
+    focus = vi.fn()
+    constructor() {
+      terminalInstances.push(this)
+    }
+  },
+}))
+
+vi.mock('@xterm/addon-fit', () => ({
+  FitAddon: class {
+    fit = vi.fn()
+  },
+}))
+
+vi.mock('@xterm/xterm/css/xterm.css', () => ({}))
+
+class MockResizeObserver {
+  observe = vi.fn()
+  disconnect = vi.fn()
+  unobserve = vi.fn()
+}
+
+import TerminalView from '@/components/TerminalView'
+
+const TAB_ID = 'tab1'
+const PANE_ID = 'p1'
+
+function paneContentWith(overrides: Partial<TerminalPaneContent> = {}): TerminalPaneContent {
+  return {
+    kind: 'terminal',
+    createRequestId: 'cr-1',
+    status: 'creating',
+    mode: 'shell',
+    shell: 'system',
+    initialCwd: '/tmp',
+    ...overrides,
+  }
+}
+
+function buildStore(paneContent: TerminalPaneContent) {
+  const root: PaneNode = { type: 'leaf', id: PANE_ID, content: paneContent }
+  return configureStore({
+    reducer: {
+      tabs: tabsReducer,
+      panes: panesReducer,
+      settings: settingsReducer,
+      connection: connectionReducer,
+    },
+    preloadedState: {
+      tabs: {
+        tabs: [{
+          id: TAB_ID,
+          mode: paneContent.mode,
+          status: paneContent.status,
+          title: 'Terminal',
+          titleSetByUser: false,
+          createRequestId: paneContent.createRequestId,
+        }],
+        activeTabId: TAB_ID,
+      },
+      panes: {
+        layouts: { [TAB_ID]: root },
+        activePane: { [TAB_ID]: PANE_ID },
+        paneTitles: {},
+      },
+      settings: { settings: defaultSettings, status: 'loaded' },
+      connection: { status: 'connected', error: null },
+    } as any,
+  })
+}
+
+async function flushEffects() {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(0)
+  })
+}
+
+// Production passes paneContent selected from the store, so a store dispatch
+// (e.g. a reconcile verdict fold) re-renders TerminalView with fresh content.
+// Mirror that wiring instead of pinning a static prop.
+function ConnectedTerminalView() {
+  const content = useSelector((state: any) => {
+    const layout = state.panes.layouts[TAB_ID] as { type: 'leaf'; content: TerminalPaneContent }
+    return layout.content
+  })
+  return <TerminalView tabId={TAB_ID} paneId={PANE_ID} paneContent={content} />
+}
+
+async function mountPane(overrides: Partial<TerminalPaneContent> = {}) {
+  const paneContent = paneContentWith(overrides)
+  const store = buildStore(paneContent)
+  render(
+    <Provider store={store}>
+      <ConnectedTerminalView />
+    </Provider>
+  )
+  await flushEffects()
+  return { store }
+}
+
+function sentOfType(type: string) {
+  return wsHarness.send.mock.calls.map(([msg]) => msg).filter((msg) => msg?.type === type)
+}
+
+function countSentOfType(type: string) {
+  return sentOfType(type).length
+}
+
+function lastSentOfType(type: string) {
+  const all = sentOfType(type)
+  return all[all.length - 1]
+}
+
+function lastAttachedTerminalId(): string | undefined {
+  return lastSentOfType('terminal.attach')?.terminalId
+}
+
+function paneContent(store: ReturnType<typeof buildStore>): TerminalPaneContent {
+  const layout = store.getState().panes.layouts[TAB_ID] as { type: 'leaf'; content: TerminalPaneContent }
+  return layout.content
+}
+
+function xtermWrites(): string[] {
+  return terminalInstances.flatMap((t: any) => t.write.mock.calls.map(([data]: [string]) => String(data)))
+}
+
+describe('TerminalView reconcile adoption: verdict-driven create + bounded re-drive', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    wsHarness.reset()
+    terminalInstances.length = 0
+    vi.stubGlobal('ResizeObserver', MockResizeObserver)
+    vi.spyOn(window, 'requestAnimationFrame').mockImplementation((cb: FrameRequestCallback) => {
+      cb(0)
+      return 1
+    })
+    vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    cleanup()
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+  })
+
+  /// REQUIRED red test (A1 fix): folding a verdict into an ALREADY-MOUNTED pane
+  /// (same createRequestId — never re-minted) must re-fire the create-or-attach
+  /// effect via the reconcileEpoch bump. Without the dep-array change this is
+  /// inert (deps key on createRequestId only, TerminalView.tsx:4486).
+  it('respawn fold into a mounted pane re-fires the effect (terminal.create sent, same createRequestId)', async () => {
+    const { store } = await mountPane({
+      mode: 'claude',
+      status: 'running',
+      createRequestId: 'cr-1',
+      terminalId: 'term-old',
+    })
+    // A mounted pane with a live terminalId attaches — it never creates.
+    expect(countSentOfType('terminal.create')).toBe(0)
+
+    act(() => {
+      store.dispatch(resetPaneForReconcileCreate({
+        tabId: TAB_ID,
+        paneId: PANE_ID,
+        intent: 'respawn',
+        sessionRef: { provider: 'claude', sessionId: 'server-truth' },
+      }))
+    })
+    await flushEffects()
+
+    expect(countSentOfType('terminal.create')).toBe(1)               // effect re-fired
+    expect(lastSentOfType('terminal.create').requestId).toBe('cr-1') // never re-minted
+  })
+
+  it('attach fold into a mounted pane re-fires the effect (xterm attaches to the new terminalId)', async () => {
+    const { store } = await mountPane({
+      status: 'running',
+      createRequestId: 'cr-1',
+      terminalId: 'term-old',
+    })
+    expect(lastAttachedTerminalId()).toBe('term-old')
+
+    act(() => {
+      store.dispatch(applyReconcileAttach({
+        tabId: TAB_ID,
+        paneId: PANE_ID,
+        terminalId: 'term-new',
+      }))
+    })
+    await flushEffects()
+
+    expect(lastAttachedTerminalId()).toBe('term-new')
+  })
+
+  it('respawn create uses the server-named sessionRef with restore:true', async () => {
+    await mountPane({
+      mode: 'claude',
+      pendingReconcile: 'respawn',
+      sessionRef: { provider: 'claude', sessionId: 'server-truth' },
+      status: 'creating',
+      createRequestId: 'cr-1',
+    })
+    const create = lastSentOfType('terminal.create')
+    expect(create).toBeTruthy()
+    expect(create.restore).toBe(true)
+    expect(create.sessionRef).toMatchObject({ provider: 'claude', sessionId: 'server-truth' })
+  })
+
+  it('fresh create omits resume fields entirely', async () => {
+    await mountPane({
+      mode: 'claude',
+      pendingReconcile: 'fresh',
+      // Stale identity deliberately left in place: sendCreate must not send it.
+      sessionRef: { provider: 'claude', sessionId: 'stale-identity' },
+      resumeSessionId: 'stale-identity',
+      status: 'creating',
+      createRequestId: 'cr-1',
+    })
+    const create = lastSentOfType('terminal.create')
+    expect(create).toBeTruthy()
+    expect(create.sessionRef).toBeUndefined()
+    expect(create.codexDurability).toBeUndefined()
+    expect(create.liveTerminal).toBeUndefined()
+    expect(create.restore).toBeUndefined()
+  })
+
+  it('SESSION_RESERVED re-drives the same create after retryAfterMs, same createRequestId', async () => {
+    const { store } = await mountPane({
+      mode: 'claude',
+      pendingReconcile: 'respawn',
+      sessionRef: { provider: 'claude', sessionId: 'server-truth' },
+      status: 'creating',
+      createRequestId: 'cr-1',
+    })
+    expect(countSentOfType('terminal.create')).toBe(1)
+
+    act(() => {
+      wsHarness.emit({
+        type: 'error',
+        code: 'SESSION_RESERVED',
+        message: 'Session is reserved by another create',
+        requestId: 'cr-1',
+        retryAfterMs: 1000,
+      })
+    })
+    // No immediate resend, and NOT a terminal error state.
+    expect(countSentOfType('terminal.create')).toBe(1)
+    expect(paneContent(store).status).toBe('creating')
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1000)
+    })
+    expect(countSentOfType('terminal.create')).toBe(2)
+    expect(lastSentOfType('terminal.create').requestId).toBe('cr-1') // never re-minted
+  })
+
+  /// loser-exhausts-then-holder-fails (council red test, client half):
+  it('exhaustion auto-resolves via a single-pane reconcile — never a wedge', async () => {
+    const { store } = await mountPane({
+      mode: 'claude',
+      pendingReconcile: 'respawn',
+      sessionRef: { provider: 'claude', sessionId: 'server-truth' },
+      status: 'creating',
+      createRequestId: 'cr-1',
+    })
+    expect(countSentOfType('terminal.create')).toBe(1)
+
+    // Keep answering SESSION_RESERVED past the 30s window.
+    wsHarness.send.mockImplementation((msg: any) => {
+      if (msg?.type === 'terminal.create') {
+        queueMicrotask(() => {
+          wsHarness.emit({
+            type: 'error',
+            code: 'SESSION_RESERVED',
+            message: 'Session is reserved by another create',
+            requestId: msg.requestId,
+            retryAfterMs: 1000,
+          })
+        })
+      }
+    })
+    // Kick the loop with the response to the initial create.
+    act(() => {
+      wsHarness.emit({
+        type: 'error',
+        code: 'SESSION_RESERVED',
+        message: 'Session is reserved by another create',
+        requestId: 'cr-1',
+        retryAfterMs: 1000,
+      })
+    })
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(31_000)
+    })
+
+    const reconcileRequest = lastSentOfType('pane.reconcile.request')
+    expect(reconcileRequest).toBeTruthy()
+    expect(reconcileRequest.panes).toHaveLength(1)
+    expect(reconcileRequest.panes[0].createRequestId).toBe('cr-1')
+
+    // Holder failed -> server answers dead_session; the fold must run and
+    // leave a visible, adjudicable state (never a silent wedge).
+    act(() => {
+      wsHarness.emit({
+        type: 'pane.reconcile.result',
+        reconcileId: reconcileRequest.reconcileId,
+        serverInstanceId: 'srv-1',
+        verdicts: [{
+          paneKey: reconcileRequest.panes[0].paneKey,
+          verdict: 'dead_session',
+          reason: 'session_file_missing',
+          sessionRef: { provider: 'claude', sessionId: 'server-truth' },
+        }],
+      })
+    })
+    await flushEffects()
+
+    expect(paneContent(store).restoreError).toBeTruthy()
+    expect(store.getState().panes.deadSessionAdjudication).toHaveLength(1)
+  })
+
+  it('INVALID_TERMINAL_ID at launch is retried bounded (F9), not a permanent error', async () => {
+    const { store } = await mountPane({
+      status: 'creating',
+      createRequestId: 'cr-1',
+      terminalId: 'term-stale',
+      serverInstanceId: 'srv-old',
+    })
+    expect(countSentOfType('terminal.create')).toBe(0)
+
+    act(() => {
+      wsHarness.emit({
+        type: 'error',
+        code: 'INVALID_TERMINAL_ID',
+        message: 'Unknown terminalId',
+        terminalId: 'term-stale',
+      })
+    })
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500)
+    })
+
+    expect(countSentOfType('terminal.create')).toBeGreaterThanOrEqual(2)
+    // Every re-drive re-sends the SAME createRequestId (council rule 2).
+    for (const create of sentOfType('terminal.create')) {
+      expect(create.requestId).toBe('cr-1')
+    }
+    expect(paneContent(store).status).toBe('creating') // not a permanent error mid-retry
+  })
+
+  it('reconcileNotice is written to the terminal once after attach, then cleared', async () => {
+    const { store } = await mountPane({
+      status: 'running',
+      createRequestId: 'cr-1',
+      terminalId: 'term-old',
+    })
+
+    act(() => {
+      store.dispatch(applyReconcileAttach({
+        tabId: TAB_ID,
+        paneId: PANE_ID,
+        terminalId: 'term-new',
+        corrected: true,
+      }))
+    })
+    await flushEffects()
+
+    expect(xtermWrites().some((data) => data.includes(RECONCILE_NOTICE_CORRECTED))).toBe(true)
+    expect(paneContent(store).reconcileNotice).toBeUndefined()
+  })
+})

From ad338575ef13131523dbf72bd7e07b4e3cdb24bb Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 07:07:03 -0700
Subject: [PATCH 64/87] feat(ws): paneReconcileFreshAgentV1 capability -
 parsed, threaded, echoed via typed ReadyCapabilities; frozen client
 unaffected

---
 .../freshell-protocol/src/server_messages.rs  |   5 +
 .../freshell-protocol/tests/pane_reconcile.rs |   1 +
 crates/freshell-ws/src/lib.rs                 |  30 ++-
 crates/freshell-ws/src/terminal.rs            |  10 +-
 .../tests/pane_reconcile_freshagent.rs        | 232 ++++++++++++++++++
 5 files changed, 270 insertions(+), 8 deletions(-)
 create mode 100644 crates/freshell-ws/tests/pane_reconcile_freshagent.rs

diff --git a/crates/freshell-protocol/src/server_messages.rs b/crates/freshell-protocol/src/server_messages.rs
index e16b8776c..1b142976b 100644
--- a/crates/freshell-protocol/src/server_messages.rs
+++ b/crates/freshell-protocol/src/server_messages.rs
@@ -757,6 +757,11 @@ pub struct Pong {
 pub struct ReadyCapabilities {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub pane_reconcile_v1: Option<bool>,
+    /// Fresh-agent restart resilience: `Some(true)` iff the connection's
+    /// `hello` opted in via `capabilities.paneReconcileFreshAgentV1` —
+    /// omitted from the wire entirely otherwise (frozen-client inertness).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub pane_reconcile_fresh_agent_v1: Option<bool>,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
diff --git a/crates/freshell-protocol/tests/pane_reconcile.rs b/crates/freshell-protocol/tests/pane_reconcile.rs
index d2d9701a9..d8e7aed83 100644
--- a/crates/freshell-protocol/tests/pane_reconcile.rs
+++ b/crates/freshell-protocol/tests/pane_reconcile.rs
@@ -74,6 +74,7 @@ fn ready_capabilities_advertise_pane_reconcile_v1_when_negotiated() {
         server_instance_id: Some("srv-1".to_string()),
         capabilities: Some(ReadyCapabilities {
             pane_reconcile_v1: Some(true),
+            pane_reconcile_fresh_agent_v1: None,
         }),
     };
     let wire = serde_json::to_value(ServerMessage::Ready(ready)).expect("serializes");
diff --git a/crates/freshell-ws/src/lib.rs b/crates/freshell-ws/src/lib.rs
index d1b9d9f8d..09cf06fcb 100644
--- a/crates/freshell-ws/src/lib.rs
+++ b/crates/freshell-ws/src/lib.rs
@@ -357,7 +357,7 @@ pub fn spawn_idle_monitor(
 /// would lose scrollback). On a truly fresh boot the registry is empty, so this stays
 /// byte-identical to the clean-boot handshake the oracle's T0/determinism tiers pin.
 pub fn build_handshake(state: &WsState) -> Vec<ServerMessage> {
-    build_handshake_with_capabilities(state, false)
+    build_handshake_with_capabilities(state, false, false)
 }
 
 /// [`build_handshake`], parameterized on the connection's negotiated
@@ -368,6 +368,7 @@ pub fn build_handshake(state: &WsState) -> Vec<ServerMessage> {
 pub fn build_handshake_with_capabilities(
     state: &WsState,
     pane_reconcile_v1: bool,
+    pane_reconcile_fresh_agent_v1: bool,
 ) -> Vec<ServerMessage> {
     let boot_id = state.boot_id.as_ref().clone();
     let mut messages = vec![
@@ -375,9 +376,12 @@ pub fn build_handshake_with_capabilities(
             timestamp: now_iso(),
             boot_id: Some(boot_id.clone()),
             server_instance_id: Some(state.server_instance_id.as_ref().clone()),
-            capabilities: pane_reconcile_v1.then_some(freshell_protocol::ReadyCapabilities {
-                pane_reconcile_v1: Some(true),
-            }),
+            capabilities: (pane_reconcile_v1 || pane_reconcile_fresh_agent_v1).then_some(
+                freshell_protocol::ReadyCapabilities {
+                    pane_reconcile_v1: pane_reconcile_v1.then_some(true),
+                    pane_reconcile_fresh_agent_v1: pane_reconcile_fresh_agent_v1.then_some(true),
+                },
+            ),
         }),
         ServerMessage::SettingsUpdated(SettingsUpdated {
             settings: state.settings.as_ref().clone(),
@@ -577,8 +581,19 @@ async fn handle_socket(
         .and_then(|v| v.as_bool())
         .unwrap_or(false);
 
+    // Fresh-agent restart resilience: same opt-in gate as `paneReconcileV1`,
+    // for the fresh-agent verdict families. The frozen client never sends it,
+    // so its handshake stays byte-for-byte unchanged.
+    let pane_reconcile_fresh_agent_v1 = value
+        .get("capabilities")
+        .and_then(|c| c.get("paneReconcileFreshAgentV1"))
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+
     // Authenticated: emit the ordered handshake.
-    for msg in build_handshake_with_capabilities(&state, pane_reconcile_v1) {
+    for msg in
+        build_handshake_with_capabilities(&state, pane_reconcile_v1, pane_reconcile_fresh_agent_v1)
+    {
         let json = match serde_json::to_string(&msg) {
             Ok(json) => json,
             Err(_) => return,
@@ -615,6 +630,7 @@ async fn handle_socket(
         terminal_output_batch_v1,
         ui_screenshot_v1,
         pane_reconcile_v1,
+        pane_reconcile_fresh_agent_v1,
         origin_kind,
     )
     .await;
@@ -800,7 +816,7 @@ mod tests {
     #[test]
     fn handshake_advertises_pane_reconcile_only_when_negotiated() {
         let s = state();
-        let negotiated = build_handshake_with_capabilities(&s, true);
+        let negotiated = build_handshake_with_capabilities(&s, true, false);
         let ready = serde_json::to_value(&negotiated[0]).unwrap();
         assert_eq!(
             ready["capabilities"],
@@ -814,7 +830,7 @@ mod tests {
             "non-negotiating hello must not change ready's shape: {ready}"
         );
         // Same shape as an explicit `false` negotiation.
-        let unnegotiated = build_handshake_with_capabilities(&s, false);
+        let unnegotiated = build_handshake_with_capabilities(&s, false, false);
         let ready2 = serde_json::to_value(&unnegotiated[0]).unwrap();
         assert!(ready2.get("capabilities").is_none());
     }
diff --git a/crates/freshell-ws/src/terminal.rs b/crates/freshell-ws/src/terminal.rs
index eec05ee2b..bec22102a 100644
--- a/crates/freshell-ws/src/terminal.rs
+++ b/crates/freshell-ws/src/terminal.rs
@@ -122,6 +122,7 @@ pub async fn run(
     terminal_output_batch_v1: bool,
     ui_screenshot_v1: bool,
     pane_reconcile_v1: bool,
+    pane_reconcile_fresh_agent_v1: bool,
     origin_kind: &'static str,
 ) {
     let (mut ws_tx, mut ws_rx) = socket.split();
@@ -259,6 +260,7 @@ pub async fn run(
                             &conn_sink,
                             terminal_output_batch_v1,
                             pane_reconcile_v1,
+                            pane_reconcile_fresh_agent_v1,
                             &mut create_limiter,
                         )
                         .await
@@ -449,6 +451,7 @@ async fn handle_client_text(
     conn_sink: &FrameSink,
     terminal_output_batch_v1: bool,
     pane_reconcile_v1: bool,
+    pane_reconcile_fresh_agent_v1: bool,
     create_limiter: &mut crate::create_limit::CreateRateLimiter,
 ) -> bool {
     // Accept-and-strip: unknown/unparseable frames are ignored (matches the
@@ -708,7 +711,8 @@ async fn handle_client_text(
             // byte-inertness does not depend on this, since it never sends
             // the request at all (§3).
             if pane_reconcile_v1 {
-                return handle_pane_reconcile(request, ws_tx, state).await;
+                return handle_pane_reconcile(request, ws_tx, state, pane_reconcile_fresh_agent_v1)
+                    .await;
             }
             true
         }
@@ -1912,6 +1916,10 @@ async fn handle_pane_reconcile(
     request: freshell_protocol::PaneReconcileRequest,
     ws_tx: &mut WsSink,
     state: &WsState,
+    // `paneReconcileFreshAgentV1` negotiation: threaded here in Task 11,
+    // consumed by the fresh-agent verdict derivation in Task 13 (underscore
+    // prefix drops then).
+    _pane_reconcile_fresh_agent_v1: bool,
 ) -> bool {
     if request.panes.len() > crate::reconcile::MAX_RECONCILE_PANES {
         return send_create_error(
diff --git a/crates/freshell-ws/tests/pane_reconcile_freshagent.rs b/crates/freshell-ws/tests/pane_reconcile_freshagent.rs
new file mode 100644
index 000000000..39c43d880
--- /dev/null
+++ b/crates/freshell-ws/tests/pane_reconcile_freshagent.rs
@@ -0,0 +1,232 @@
+//! `paneReconcileFreshAgentV1` capability wire tests — raw-WS
+//! (tokio-tungstenite) integration against an in-process axum server, on the
+//! `pane_reconcile.rs` harness convention (ephemeral loopback ports, never a
+//! fixed one).
+//!
+//! Covered here (Task 11 — capability negotiation only):
+//! * negotiation — `hello.capabilities.paneReconcileFreshAgentV1` → echoed in
+//!   `ready.capabilities` (typed `ReadyCapabilities`, omitted when absent).
+//! * frozen-client protection — a connection WITHOUT the capability keeps the
+//!   pre-existing verdict for `kind: "fresh-agent"`: `invalid` /
+//!   `unsupported_kind` (the permanent regression guard).
+//!
+//! Task 13 extends this file with the fresh-agent verdict derivation tests.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use futures_util::{SinkExt, StreamExt};
+use tokio::net::TcpListener;
+use tokio_tungstenite::tungstenite::Message as WsMessage;
+
+use freshell_ws::WsState;
+
+const AUTH_TOKEN: &str = "s3cr3t-token-abcdef";
+
+fn test_settings_value() -> serde_json::Value {
+    serde_json::json!({
+        "ai": {},
+        "codingCli": { "enabledProviders": [], "mcpServer": true, "providers": {} },
+        "editor": { "externalEditor": "auto" },
+        "extensions": { "disabled": [] },
+        "freshAgent": { "defaultPlugins": [], "enabled": false, "providers": {} },
+        "logging": { "debug": false },
+        "network": { "configured": true, "host": "127.0.0.1" },
+        "panes": { "defaultNewPane": "ask" },
+        "safety": { "autoKillIdleMinutes": 15 },
+        "sidebar": {
+            "autoGenerateTitles": true,
+            "excludeFirstChatMustStart": false,
+            "excludeFirstChatSubstrings": []
+        },
+        "terminal": { "scrollback": 10000 }
+    })
+}
+
+struct Server {
+    url: String,
+    // Shared-registry handles, donor-shaped: Task 13's derivation tests seed
+    // generations through these; Task 11's negotiation tests don't need to.
+    #[allow(dead_code)]
+    registry: freshell_terminal::TerminalRegistry,
+    #[allow(dead_code)]
+    identity: freshell_ws::identity::TerminalIdentityRegistry,
+}
+
+/// Real axum server on an ephemeral loopback port. Returns handles to the
+/// SHARED registry + identity registry so tests can seed generations
+/// deterministically (the §9.1 headless convention).
+async fn spawn_server() -> Server {
+    let auth_token = Arc::new(AUTH_TOKEN.to_string());
+    let broadcast_tx = Arc::new(tokio::sync::broadcast::channel::<String>(64).0);
+    let settings =
+        Arc::new(serde_json::from_value(test_settings_value()).expect("valid settings fixture"));
+    let registry = freshell_terminal::TerminalRegistry::new();
+    let identity = freshell_ws::identity::TerminalIdentityRegistry::new();
+
+    let state = WsState {
+        pane_ledger: std::sync::Arc::new(freshell_ws::pane_ledger::PaneLedger::disabled()),
+        identity: identity.clone(),
+        auth_token: Arc::clone(&auth_token),
+        server_instance_id: Arc::new("srv-test".to_string()),
+        boot_id: Arc::new("boot-test".to_string()),
+        settings,
+        broadcast_tx: Arc::clone(&broadcast_tx),
+        fresh_codex: freshell_freshagent::FreshCodexState::new(
+            Arc::clone(&auth_token),
+            Arc::clone(&broadcast_tx),
+            serde_json::json!({ "freshAgent": { "enabled": false } }),
+        ),
+        fresh_claude: freshell_freshagent::FreshClaudeState::new(Arc::clone(&broadcast_tx)),
+        fresh_opencode: freshell_freshagent::FreshOpencodeState::new(
+            freshell_freshagent::FreshAgentState::new(
+                Arc::clone(&auth_token),
+                Arc::clone(&broadcast_tx),
+            ),
+        ),
+        registry: registry.clone(),
+        tabs: freshell_ws::tabs::TabsRegistry::new(),
+        screenshots: freshell_ws::screenshot::ScreenshotBroker::new(Arc::clone(&broadcast_tx)),
+        terminals_revision: Arc::new(std::sync::atomic::AtomicI64::new(0)),
+        sessions_revision: Arc::new(std::sync::atomic::AtomicI64::new(0)),
+        cli_commands: Arc::new(Vec::new()),
+        shutdown: Arc::new(tokio::sync::Notify::new()),
+        ping_interval_ms: 30_000,
+        hello_timeout_ms: 5_000,
+        allowed_origins: Arc::new(freshell_ws::origin::default_allowed_origins()),
+        ws_max_payload_bytes: 16 * 1024 * 1024,
+        term09: freshell_ws::backpressure::Term09Config::default(),
+        create_protect: freshell_ws::create_limit::CreateProtectConfig::default(),
+        spawn_gate: std::sync::Arc::new(freshell_ws::spawn_gate::SpawnGate::new(4, 64)),
+        config_fallback: None,
+        amplifier_locator: None,
+        opencode_locator: None,
+        activity: None,
+        session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+    };
+
+    let router = freshell_ws::router(state);
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind ephemeral loopback port");
+    let addr = listener.local_addr().expect("local addr");
+    tokio::spawn(async move {
+        let _ = axum::serve(listener, router).await;
+    });
+
+    Server {
+        url: format!("ws://{addr}/ws"),
+        registry,
+        identity,
+    }
+}
+
+type TestWs =
+    tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>;
+
+/// Connect + hello (negotiating `paneReconcileV1` / `paneReconcileFreshAgentV1`
+/// per the flags), consuming the 4-frame handshake. Returns the socket and the
+/// parsed `ready` frame.
+async fn connect(
+    url: &str,
+    pane_reconcile_v1: bool,
+    fresh_agent_v1: bool,
+) -> (TestWs, serde_json::Value) {
+    let (mut ws, _resp) = tokio_tungstenite::connect_async(url)
+        .await
+        .expect("ws connect");
+    let mut hello = serde_json::json!({
+        "type": "hello",
+        "token": AUTH_TOKEN,
+        "protocolVersion": freshell_protocol::WS_PROTOCOL_VERSION,
+    });
+    hello["capabilities"] = serde_json::json!({
+        "paneReconcileV1": pane_reconcile_v1,
+        "paneReconcileFreshAgentV1": fresh_agent_v1,
+    });
+    ws.send(WsMessage::Text(hello.to_string()))
+        .await
+        .expect("send hello");
+
+    let mut ready = serde_json::Value::Null;
+    for _ in 0..4u8 {
+        let msg = tokio::time::timeout(Duration::from_secs(5), ws.next())
+            .await
+            .expect("handshake message within timeout")
+            .expect("stream not ended")
+            .expect("no ws error");
+        if let WsMessage::Text(text) = &msg {
+            let value: serde_json::Value = serde_json::from_str(text).expect("json frame");
+            if value["type"] == serde_json::json!("ready") {
+                ready = value;
+            }
+        }
+    }
+    assert!(!ready.is_null(), "handshake must contain ready");
+    (ws, ready)
+}
+
+/// Read text frames until one with `type == wanted` arrives (bounded).
+async fn next_frame_of_type(ws: &mut TestWs, wanted: &str) -> serde_json::Value {
+    for _ in 0..30u8 {
+        let msg = tokio::time::timeout(Duration::from_secs(5), ws.next())
+            .await
+            .unwrap_or_else(|_| panic!("timed out waiting for a {wanted} frame"))
+            .expect("stream not ended")
+            .expect("no ws error");
+        if let WsMessage::Text(text) = &msg {
+            let value: serde_json::Value = serde_json::from_str(text).expect("json frame");
+            if value["type"] == serde_json::json!(wanted) {
+                return value;
+            }
+        }
+    }
+    panic!("no {wanted} frame within 30 messages");
+}
+
+/// Send a `pane.reconcile.request` for `panes` and return the result's
+/// `verdicts` array.
+async fn reconcile_request(ws: &mut TestWs, panes: serde_json::Value) -> serde_json::Value {
+    ws.send(WsMessage::Text(
+        serde_json::json!({
+            "type": "pane.reconcile.request",
+            "reconcileId": "rec-fa",
+            "panes": panes,
+        })
+        .to_string(),
+    ))
+    .await
+    .expect("send reconcile request");
+    let result = next_frame_of_type(ws, "pane.reconcile.result").await;
+    result["verdicts"].clone()
+}
+
+// --- negotiation ---------------------------------------------------------------
+
+#[tokio::test]
+async fn ready_echoes_fresh_agent_capability_when_negotiated() {
+    let server = spawn_server().await;
+    let (_ws, ready) = connect(&server.url, true, true).await;
+    assert_eq!(
+        ready["capabilities"]["paneReconcileFreshAgentV1"],
+        serde_json::json!(true)
+    );
+}
+
+// --- frozen-client protection (permanent regression guard) ----------------------
+
+#[tokio::test]
+async fn without_the_capability_fresh_agent_kind_stays_invalid_unsupported() {
+    let server = spawn_server().await;
+    let (mut ws, _ready) = connect(&server.url, true, false).await; // frozen-client shape
+    let verdicts = reconcile_request(
+        &mut ws,
+        serde_json::json!([{
+            "paneKey": "p1", "kind": "fresh-agent",
+            "sessionRef": {"provider": "claude", "sessionId": "s-1"}
+        }]),
+    )
+    .await;
+    assert_eq!(verdicts[0]["verdict"], "invalid");
+    assert_eq!(verdicts[0]["reason"], "unsupported_kind");
+}

From d1c59bb8f81c846573ab8c7c13313f2965326772 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 07:09:57 -0700
Subject: [PATCH 65/87] test(e2e): browser-loss recover-my-panes proof - offer,
 accept-resume, mixed-kind, reload guard, decline, live no-restart (B3/P1.9)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds test/e2e-browser/specs/recover-my-panes-rust.spec.ts (registered in
RUST_ONLY_SPECS + the rust-chromium testMatch), three serial scenarios on
one owned RustServer:

- Scenario 1: lost browser + server restart -> fresh context is offered
  recovery; accept recreates the tab (claude `--resume <sessionId>` argv
  proof + scrollback marker, mixed-kind browser pane at example.com), and
  a same-browser reload never re-offers.
- Scenario 2: decline closes the panel and adds no recovered tabs.
- Scenario 3 (D7): browser lost WITHOUT restart -> live claude PTY stays
  running; offer shows the live-session note; accept recreates the pane
  with NO `--resume` for that session (non-vacuous: the spawn is observed
  in the argv log first, and scenario 1 proves the same matcher matches).

Contexts block service workers (perf-harness precedent): the production
client reloads on SW controllerchange, which raced App mount and aborted
the panel's one-shot inventory fetch (net::ERR_ABORTED), flaking fresh-
context offers. Red-verification performed: with <RecoveryOfferPanel />
unmounted the spec fails on the offer-visibility assertion; App.tsx
restored byte-identical. 2 consecutive green runs.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 test/e2e-browser/playwright.config.ts         |   8 +
 .../specs/recover-my-panes-rust.spec.ts       | 476 ++++++++++++++++++
 2 files changed, 484 insertions(+)
 create mode 100644 test/e2e-browser/specs/recover-my-panes-rust.spec.ts

diff --git a/test/e2e-browser/playwright.config.ts b/test/e2e-browser/playwright.config.ts
index c4151f30e..2196795c4 100644
--- a/test/e2e-browser/playwright.config.ts
+++ b/test/e2e-browser/playwright.config.ts
@@ -127,6 +127,10 @@ const RUST_ONLY_SPECS = [
   // ledger-join coherence, A2xA3 dual claude identity stores). Imports
   // RustServer directly for restartAbrupt().
   /wavea-interactions-rust\.spec\.ts$/,
+  // B3/P1.9 recover-my-panes browser-loss recovery: drives the Rust-only
+  // GET /api/recovery/inventory + RecoveryOfferPanel; imports RustServer
+  // directly for restart(). See docs/plans/2026-07-26-recover-my-panes.md
+  /recover-my-panes-rust\.spec\.ts$/,
 ]
 
 export default defineConfig({
@@ -284,6 +288,10 @@ export default defineConfig({
         // ledger-join coherence, A2xA3 dual claude identity stores). Imports
         // RustServer directly for restartAbrupt().
         /wavea-interactions-rust\.spec\.ts$/,
+        // B3/P1.9 recover-my-panes browser-loss recovery (offer, accept-resume,
+        // mixed-kind, reload guard, decline, live no-restart). Rust-only:
+        // drives GET /api/recovery/inventory; imports RustServer for restart().
+        /recover-my-panes-rust\.spec\.ts$/,
       ],
     },
     // CONTINUITY SMOKE (pre-deploy gate): REAL freshell-server binary + REAL
diff --git a/test/e2e-browser/specs/recover-my-panes-rust.spec.ts b/test/e2e-browser/specs/recover-my-panes-rust.spec.ts
new file mode 100644
index 000000000..176cfd896
--- /dev/null
+++ b/test/e2e-browser/specs/recover-my-panes-rust.spec.ts
@@ -0,0 +1,476 @@
+/**
+ * B3/P1.9 recover-my-panes — the campaign's first browser-loss recovery e2e
+ * (docs/plans/2026-07-26-recover-my-panes.md, Task 8).
+ *
+ * Scenario 1 (accept path): a browser with a claude CLI pane + a browser pane
+ * is LOST (context closed), the server restarts, and a fresh browser context
+ * (empty storage = new machine) is OFFERED recovery — accepting recreates the
+ * panes, resumes the dead claude session (`--resume <sessionId>` argv proof +
+ * the fake CLI's scrollback marker), recreates the mixed-kind browser pane,
+ * and a same-browser reload never re-offers (localStorage now has a layout).
+ *
+ * Scenario 2 (decline path): a fresh context declines — the panel closes and
+ * no recovered tabs are added.
+ *
+ * Scenario 3 (no-restart browser loss, D7): the browser is lost WITHOUT a
+ * server restart, so the claude PTY stays Running (registry-owned). The next
+ * fresh context's offer shows the live-session note, and accepting recreates
+ * the pane WITHOUT `--resume` — the running session is left untouched.
+ *
+ * Fixture shapes (fake CLI, config seeding, shell-picker choreography) are
+ * COPIED from pane-ledger-restart-rust.spec.ts per this suite's
+ * per-spec-ownership convention.
+ *
+ * Rust-only: drives `GET /api/recovery/inventory` (no legacy equivalent) and
+ * owns a RustServer directly (ephemeral loopback port — NEVER 3001/3002).
+ * Registered ONLY under `rust-chromium` and testIgnore'd on every match-all
+ * project (see playwright.config.ts's RUST_ONLY_SPECS).
+ */
+import { test, expect } from '../helpers/fixtures.js'
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import { fileURLToPath } from 'node:url'
+import type { BrowserContext, Page } from '@playwright/test'
+import { RustServer, ensureRustServerBuilt } from '../helpers/rust-server.js'
+import type { TestServerInfo } from '../helpers/test-server.js'
+import { TestHarness } from '../helpers/test-harness.js'
+import { openPanePicker } from '../helpers/pane-picker.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+/** Donor: pane-ledger-restart-rust.spec.ts:29 */
+async function installFakeCli(binDir: string, name: string, source: string): Promise<string> {
+  await fs.mkdir(binDir, { recursive: true })
+  const target = path.join(binDir, name)
+  await fs.copyFile(path.resolve(__dirname, '../fixtures', source), target)
+  await fs.chmod(target, 0o755)
+  return target
+}
+
+/** Donor: pane-ledger-restart-rust.spec.ts:37 */
+function seedConfig() {
+  return async (homeDir: string): Promise<void> => {
+    const freshellDir = path.join(homeDir, '.freshell')
+    await fs.mkdir(freshellDir, { recursive: true })
+    await fs.writeFile(
+      path.join(freshellDir, 'config.json'),
+      JSON.stringify(
+        {
+          version: 1,
+          settings: { codingCli: { enabledProviders: ['claude', 'codex', 'opencode'] } },
+        },
+        null,
+        2,
+      ),
+    )
+  }
+}
+
+/**
+ * Donor: pane-ledger-restart-rust.spec.ts:65 (load-bearing comment there):
+ * a live shell terminal's cwd pre-fills the Starting-directory combobox the
+ * CLI-pane creates below depend on.
+ */
+async function selectShellIfPickerShowing(page: Page): Promise<void> {
+  await page.waitForTimeout(500)
+  const xtermVisible = await page.locator('.xterm').first().isVisible().catch(() => false)
+  if (xtermVisible) return
+  const shellNames = ['Shell', 'WSL', 'CMD', 'PowerShell', 'Bash']
+  for (const name of shellNames) {
+    try {
+      await page.getByRole('button', { name: new RegExp(`^${name}$`, 'i') }).click({ timeout: 5_000 })
+      await page.locator('.xterm').first().waitFor({ state: 'visible', timeout: 15_000 })
+      return
+    } catch {
+      continue
+    }
+  }
+}
+
+/** Donor: pane-ledger-restart-rust.spec.ts:81 */
+async function openCliPane(page: Page, buttonName: RegExp): Promise<void> {
+  const picker = await openPanePicker(page)
+  await picker.getByRole('button', { name: buttonName }).click({ force: true })
+  await page.getByRole('combobox', { name: /Starting directory/i }).press('Enter')
+}
+
+/** Read the fake CLI's argv-log JSONL (empty array if not yet written). */
+async function readArgvLog(logPath: string): Promise<Array<{ argv: string[] }>> {
+  const raw = await fs.readFile(logPath, 'utf8').catch(() => '')
+  if (!raw) return []
+  return raw.trim().split('\n').filter(Boolean).map((line) => JSON.parse(line) as { argv: string[] })
+}
+
+/**
+ * Claude-adapted adjacent-pair matcher (per the task brief's Interfaces): the
+ * fake claude CLI receives the `--resume <id>` FLAG (fake-claude-cli.mjs:26-30)
+ * — NOT codex's bare `resume` subcommand token, so snapshot-restore-rust's
+ * `hasResumePair` would never match here.
+ */
+const hasClaudeResumePair = (argv: string[], sessionId: string) => {
+  const i = argv.indexOf('--resume')
+  return i !== -1 && argv[i + 1] === sessionId
+}
+
+/** `--session-id <id>` values, in order, from a slice of argv-log entries. */
+function sessionIdsOf(entries: Array<{ argv: string[] }>): string[] {
+  return entries.flatMap((e) => {
+    const i = e.argv.indexOf('--session-id')
+    return i >= 0 ? [e.argv[i + 1]] : []
+  })
+}
+
+/** Donor: snapshot-restore-rust.spec.ts:74 — boot a page against the server. */
+async function connect(page: Page, info: { baseUrl: string; token: string }): Promise<TestHarness> {
+  await page.goto(`${info.baseUrl}/?token=${info.token}&e2e=1`)
+  const harness = new TestHarness(page)
+  await harness.waitForHarness()
+  await harness.waitForConnection()
+  return harness
+}
+
+/** Triage aid: log inventory request failures/non-200s (kept quiet on success). */
+function traceInventoryFailures(page: Page, label: string): void {
+  page.on('response', (r) => {
+    if (!r.url().includes('/api/recovery/inventory') || r.status() === 200) return
+    console.log(`[${label}] inventory response ${r.status()} ${r.url()}`)
+  })
+  page.on('requestfailed', (req) => {
+    if (!req.url().includes('/api/recovery/inventory')) return
+    console.log(`[${label}] inventory request FAILED: ${req.failure()?.errorText}`)
+  })
+}
+
+/** Create the browser pane the way a user would (browser-pane.spec.ts:8). */
+async function createBrowserPane(page: Page, url: string): Promise<void> {
+  const picker = await openPanePicker(page)
+  await picker.getByRole('button', { name: /^Browser$/i }).click({ force: true })
+  const urlInput = page.getByPlaceholder('Enter URL...')
+  await expect(urlInput).toBeVisible({ timeout: 10_000 })
+  await urlInput.fill(url)
+  await urlInput.press('Enter')
+  const iframe = page.locator('iframe[title="Browser content"]')
+  await iframe.waitFor({ state: 'attached', timeout: 10_000 })
+}
+
+test.describe('recover-my-panes browser-loss recovery (rust only)', () => {
+  // Scenarios share ONE owned server and build on each other's durable state
+  // (snapshots, ledger rows, a still-running PTY) — strict ordering required.
+  test.describe.configure({ mode: 'serial' })
+
+  let sharedRoot = ''
+  let capturedHome = ''
+  let argLog = ''
+  let server: RustServer
+  let info: TestServerInfo
+
+  /**
+   * Wait until SOME persisted snapshot generation contains every needle.
+   * Stronger than the brief's minimum (a device dir with >=1 .json): pushes
+   * fire on ready + every 5s, so an early generation may predate the panes
+   * under test — matching CONTENT guarantees the recoverable state actually
+   * includes them before we kill the context.
+   */
+  async function waitForSnapshotContaining(needles: string[], timeoutMs = 30_000): Promise<void> {
+    const snapshotsDir = path.join(capturedHome, '.freshell', 'tabs-snapshots')
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+      const devices = await fs.readdir(snapshotsDir).catch(() => [] as string[])
+      for (const device of devices) {
+        const deviceDir = path.join(snapshotsDir, device)
+        const files = await fs.readdir(deviceDir).catch(() => [] as string[])
+        for (const f of files.filter((f) => f.endsWith('.json'))) {
+          const body = await fs.readFile(path.join(deviceDir, f), 'utf8').catch(() => '')
+          if (needles.every((n) => body.includes(n))) return
+        }
+      }
+      await new Promise((r) => setTimeout(r, 500))
+    }
+    throw new Error(`No tabs-snapshot generation contained [${needles.join(', ')}] within ${timeoutMs}ms`)
+  }
+
+  test.beforeAll(async () => {
+    test.setTimeout(600_000) // first release build of freshell-server can take minutes
+    ensureRustServerBuilt()
+    sharedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'recover-my-panes-e2e-'))
+    argLog = path.join(sharedRoot, 'claude-argv.jsonl')
+    const fakeClaude = await installFakeCli(path.join(sharedRoot, 'bin'), 'claude', 'fake-claude-cli.mjs')
+    const seed = seedConfig()
+    server = new RustServer({
+      env: { CLAUDE_CMD: fakeClaude, FAKE_CLAUDE_ARGV_LOG: argLog },
+      setupHome: async (homeDir: string) => {
+        capturedHome = homeDir
+        await seed(homeDir)
+      },
+    })
+    info = await server.start()
+  })
+
+  test.afterAll(async () => {
+    await server?.stop().catch(() => {})
+    if (sharedRoot) await fs.rm(sharedRoot, { recursive: true, force: true }).catch(() => {})
+  })
+
+  /**
+   * SERVICE WORKERS ARE BLOCKED in every context this spec opens (the
+   * perf harness precedent, perf/create-audit-context.ts:18): the production
+   * client registers /sw.js and RELOADS on `controllerchange` (pwa.ts:24-34).
+   * On a FRESH context that reload races App mount, aborting in-flight boot
+   * fetches (observed: the recovery-inventory fetch dying with
+   * net::ERR_ABORTED) — and the panel's fetch is deliberately one-shot
+   * best-effort (RecoveryOfferPanel.tsx: on fetch failure, stay quiet), so a
+   * lost race means no offer for that boot. Blocking the SW removes the
+   * reload entirely; recovery behavior itself never depends on the SW.
+   */
+  const FRESH_CONTEXT_OPTIONS = { serviceWorkers: 'block' as const }
+
+  /**
+   * Open a FRESH context (empty storage) and require the recovery offer.
+   * Retries with a brand-new fresh context (same eligibility — the user
+   * opening another fresh window) as insurance against residual transient
+   * boot-fetch loss; a genuinely broken offer still fails all attempts —
+   * the red-verification (panel unmounted) proves this loop fails.
+   */
+  async function openFreshContextWithOffer(
+    browser: import('@playwright/test').Browser,
+    label: string,
+  ): Promise<{ ctx: BrowserContext; page: Page; harness: TestHarness }> {
+    const attempts = 3
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      const ctx = await browser.newContext(FRESH_CONTEXT_OPTIONS)
+      const page = await ctx.newPage()
+      traceInventoryFailures(page, label)
+      const harness = await connect(page, info)
+      try {
+        await page.getByTestId('recovery-offer-panel').waitFor({ state: 'visible', timeout: 15_000 })
+        return { ctx, page, harness }
+      } catch (err) {
+        if (attempt === attempts) throw err
+        console.log(`[${label}] offer absent in fresh context (attempt ${attempt}/${attempts}) — retrying with a new context`)
+        await ctx.close()
+      }
+    }
+    throw new Error('unreachable')
+  }
+
+  // Scenario 1's claude session — scenario 2/3 reason about the same log.
+  let sessionIdA = ''
+
+  test('scenario 1: lose the browser, restart the server, accept — panes recreated, claude resumed, reload never re-offers', async ({ browser, e2eServerKind }) => {
+    expect(e2eServerKind).toBe('rust')
+    test.setTimeout(240_000)
+
+    // ---- Context A: populate a tab with a claude CLI pane + a browser pane ----
+    const ctxA: BrowserContext = await browser.newContext(FRESH_CONTEXT_OPTIONS)
+    const pageA = await ctxA.newPage()
+    await connect(pageA, info)
+    await selectShellIfPickerShowing(pageA)
+    await expect(pageA.locator('.xterm').first()).toBeVisible({ timeout: 30_000 })
+
+    // Claude pane (button label is the extension manifest's "Claude CLI").
+    await openCliPane(pageA, /^Claude CLI$/i)
+
+    // Record the pre-allocated sessionId from the argv log's --session-id pair
+    // (pane-ledger-restart-rust.spec.ts:162-168 extraction).
+    await expect(async () => {
+      const sid = sessionIdsOf(await readArgvLog(argLog))[0]
+      expect(sid, 'fake claude received a pre-allocated --session-id').toBeTruthy()
+      sessionIdA = sid!
+    }).toPass({ timeout: 30_000 })
+
+    // Let it BIND: the ledger binding row for that sessionId hits disk (the
+    // donor spec's readiness wait) — the inventory's D4 resolve needs it.
+    await expect(async () => {
+      const dir = path.join(capturedHome, '.freshell', 'pane-ledger', 'bindings', 'claude')
+      const rows = await fs.readdir(dir, { recursive: true }).catch(() => [] as string[])
+      expect(rows.map(String).some((f) => f.includes(sessionIdA))).toBe(true)
+    }).toPass({ timeout: 15_000 })
+
+    // Mixed-kind coverage (A12): a browser pane at https://example.com in the
+    // SAME tab, created the way a user would (split + picker "Browser").
+    await createBrowserPane(pageA, 'https://example.com')
+
+    // A snapshot generation containing BOTH panes exists on disk (pushes fire
+    // on ready + every 5s).
+    await waitForSnapshotContaining([sessionIdA, 'example.com'])
+
+    // ---- The "lost browser" + server restart ----
+    await ctxA.close()
+    await server.restart()
+
+    // ---- Context B: fresh storage = new machine; the offer is REQUIRED ----
+    const { ctx: ctxB, page: pageB } = await openFreshContextWithOffer(browser, 'contextB')
+
+    const panelB = pageB.getByTestId('recovery-offer-panel')
+    await expect(panelB).toBeVisible()
+    await expect(panelB.getByRole('heading')).toHaveText(/restore \d+ pane/i)
+
+    const argvCountBeforeAccept = (await readArgvLog(argLog)).length
+    await pageB.getByTestId('recovery-accept').click()
+    await expect(panelB).toHaveCount(0)
+
+    // A recreated terminal pane renders.
+    await expect(pageB.locator('.xterm').first()).toBeVisible({ timeout: 30_000 })
+
+    // PRIMARY resume proof: the accept re-spawned claude with the adjacent
+    // pair `--resume <sessionIdA>` (delta past the pre-accept log).
+    await expect(async () => {
+      const entries = await readArgvLog(argLog)
+      expect(
+        entries.slice(argvCountBeforeAccept).some((e) => hasClaudeResumePair(e.argv, sessionIdA)),
+        'accept must exec `claude --resume <sessionId>`',
+      ).toBe(true)
+    }).toPass({ timeout: 30_000 })
+
+    // SECONDARY resume proof: the recreated pane's xterm text shows the fake
+    // CLI's startup marker (fake-claude-cli.mjs:26-30; scrollback replay
+    // delivers it to the late-attaching context). Buffers are read via the
+    // renderer-agnostic harness API across ALL registered terminals. The
+    // recovered claude pane is NARROW (third pane in a horizontal chain), so
+    // the ~60-char marker line WRAPS across buffer rows — compare with all
+    // whitespace stripped so wrapping (and trimmed wrap points) cannot hide it.
+    await pageB.waitForFunction(
+      (marker) => {
+        const harness = (window as any).__FRESHELL_TEST_HARNESS__
+        if (!harness) return false
+        const state = harness.getState()
+        const ids: string[] = []
+        for (const tab of state?.tabs?.tabs ?? []) {
+          const walk = (node: any) => {
+            if (!node) return
+            if (node.type === 'leaf') {
+              if (node.content?.kind === 'terminal' && node.content?.terminalId) ids.push(node.content.terminalId)
+              return
+            }
+            for (const child of node.children ?? []) walk(child)
+          }
+          walk(state?.panes?.layouts?.[tab.id])
+        }
+        const squash = (s: string) => s.replace(/\s+/g, '')
+        return ids.some((id) => squash(harness.getTerminalBuffer(id) ?? '').includes(squash(marker)))
+      },
+      `claude: resumed session ${sessionIdA}`,
+      { timeout: 30_000 },
+    )
+
+    // The browser pane was recreated too (mixed-kind restore, A12).
+    const iframeB = pageB.locator('iframe[title="Browser content"]')
+    await iframeB.waitFor({ state: 'attached', timeout: 15_000 })
+    expect(await iframeB.getAttribute('src')).toContain('example.com')
+
+    // ---- Same-browser reload guard: localStorage now has a layout ----
+    await pageB.reload()
+    const harnessB2 = new TestHarness(pageB)
+    await harnessB2.waitForHarness()
+    await harnessB2.waitForConnection()
+    // Eligibility is boot-captured and synchronous (hadPersistedLayoutAtBoot
+    // short-circuits BEFORE any fetch); the settle covers the async fetch path
+    // that would have to complete for a wrongful offer to appear.
+    await pageB.waitForTimeout(2_000)
+    await expect(pageB.getByTestId('recovery-offer-panel')).toHaveCount(0)
+
+    await ctxB.close()
+  })
+
+  test('scenario 2: decline path — panel closes, no recovered tabs added', async ({ browser, e2eServerKind }) => {
+    expect(e2eServerKind).toBe('rust')
+    test.setTimeout(120_000)
+
+    // Fresh context C against the same server (recoverable state still exists
+    // from scenario 1 — context B's accepted layout also pushed snapshots).
+    const { ctx: ctxC, page: pageC, harness: harnessC } = await openFreshContextWithOffer(browser, 'contextC')
+
+    const panelC = pageC.getByTestId('recovery-offer-panel')
+    await expect(panelC).toBeVisible()
+    await pageC.getByTestId('recovery-decline').click()
+    await expect(panelC).toHaveCount(0)
+
+    // No recovered tabs: only the auto-created default tab remains — settle
+    // first so a straggling (wrongful) recovery could have landed.
+    await expect(async () => {
+      expect(await harnessC.getTabCount()).toBe(1)
+    }).toPass({ timeout: 10_000 })
+    await pageC.waitForTimeout(1_500)
+    expect(await harnessC.getTabCount()).toBe(1)
+
+    await ctxC.close()
+  })
+
+  test('scenario 3: no-restart browser loss — live session recreates WITHOUT resume (D7)', async ({ browser, e2eServerKind }) => {
+    expect(e2eServerKind).toBe('rust')
+    test.setTimeout(240_000)
+
+    // ---- Context D against the SAME still-running server (no restart) ----
+    // The offer MODAL (role="dialog" + overlay) appears first — D's storage is
+    // empty and recoverable state exists — and would intercept all pointer
+    // events. Clear it BEFORE any pane interaction (this dismissal lives only
+    // in D's localStorage; context E below is a different fresh context).
+    const { ctx: ctxD, page: pageD } = await openFreshContextWithOffer(browser, 'contextD')
+    const panelD = pageD.getByTestId('recovery-offer-panel')
+    await pageD.getByTestId('recovery-decline').click()
+    await expect(panelD).toHaveCount(0)
+
+    await selectShellIfPickerShowing(pageD)
+    await expect(pageD.locator('.xterm').first()).toBeVisible({ timeout: 30_000 })
+
+    const argvCountBeforeCreate = (await readArgvLog(argLog)).length
+    await openCliPane(pageD, /^Claude CLI$/i)
+
+    // The NEW pane's sessionId = the --session-id pair past the pre-create count.
+    let sessionIdD = ''
+    await expect(async () => {
+      const entries = await readArgvLog(argLog)
+      const sid = sessionIdsOf(entries.slice(argvCountBeforeCreate))[0]
+      expect(sid, 'context D fake claude received a pre-allocated --session-id').toBeTruthy()
+      sessionIdD = sid!
+    }).toPass({ timeout: 30_000 })
+
+    // Ledger binding for D's session (inventory needs the bound row to
+    // resolve + join liveness), then a snapshot generation that includes it.
+    await expect(async () => {
+      const dir = path.join(capturedHome, '.freshell', 'pane-ledger', 'bindings', 'claude')
+      const rows = await fs.readdir(dir, { recursive: true }).catch(() => [] as string[])
+      expect(rows.map(String).some((f) => f.includes(sessionIdD))).toBe(true)
+    }).toPass({ timeout: 15_000 })
+    await waitForSnapshotContaining([sessionIdD])
+
+    // The argv-log watermark for the D7 negative assertion below.
+    const argvCountAtD = (await readArgvLog(argLog)).length
+
+    // ---- Lose the browser WITHOUT restarting the server: the claude PTY
+    // stays Running (registry-owned, not connection-owned). ----
+    await ctxD.close()
+
+    // ---- Context E: the offer appears (the new session changed the
+    // recoverable substance — scenario 2's dismissal cannot suppress it, and
+    // E is a different fresh context anyway) with the live-session note. ----
+    const { ctx: ctxE, page: pageE } = await openFreshContextWithOffer(browser, 'contextE')
+
+    const panelE = pageE.getByTestId('recovery-offer-panel')
+    await expect(pageE.getByTestId('recovery-live-note')).toBeVisible()
+
+    await pageE.getByTestId('recovery-accept').click()
+    await expect(panelE).toHaveCount(0)
+
+    // A terminal pane is recreated.
+    await expect(pageE.locator('.xterm').first()).toBeVisible({ timeout: 30_000 })
+
+    // D7 negative assertion, non-vacuously: FIRST wait until the recreated
+    // claude spawn is OBSERVED in the log (the live pane recreates as a fresh
+    // claude — a new entry past the watermark), THEN assert none of the new
+    // entries carries `--resume <sessionIdD>`. The matcher itself is proven
+    // non-vacuous by scenario 1's PRIMARY poll, which matched a real pair.
+    await expect(async () => {
+      const entries = await readArgvLog(argLog)
+      expect(entries.length, 'accept must re-spawn a claude CLI for the live pane').toBeGreaterThan(argvCountAtD)
+    }).toPass({ timeout: 30_000 })
+    const newEntries = (await readArgvLog(argLog)).slice(argvCountAtD)
+    expect(
+      newEntries.some((e) => hasClaudeResumePair(e.argv, sessionIdD)),
+      'live session must be recreated WITHOUT --resume (left untouched, D7)',
+    ).toBe(false)
+
+    await ctxE.close()
+  })
+})

From 6211336f55f975d81c9af699ec84837f22720700 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 07:15:10 -0700
Subject: [PATCH 66/87] feat(ws): reconcile_freshagent - pure fresh-agent
 verdict mapping with dedupe + respawn cap

---
 crates/freshell-ws/src/lib.rs                 |   1 +
 .../freshell-ws/src/reconcile_freshagent.rs   | 277 ++++++++++++++++++
 2 files changed, 278 insertions(+)
 create mode 100644 crates/freshell-ws/src/reconcile_freshagent.rs

diff --git a/crates/freshell-ws/src/lib.rs b/crates/freshell-ws/src/lib.rs
index 09cf06fcb..9cd115897 100644
--- a/crates/freshell-ws/src/lib.rs
+++ b/crates/freshell-ws/src/lib.rs
@@ -33,6 +33,7 @@ pub mod opencode_association;
 pub mod origin;
 pub mod pane_ledger;
 pub mod reconcile;
+pub mod reconcile_freshagent;
 pub mod screenshot;
 pub mod spawn_gate;
 pub mod tabs;
diff --git a/crates/freshell-ws/src/reconcile_freshagent.rs b/crates/freshell-ws/src/reconcile_freshagent.rs
new file mode 100644
index 000000000..560be8096
--- /dev/null
+++ b/crates/freshell-ws/src/reconcile_freshagent.rs
@@ -0,0 +1,277 @@
+//! Fresh-agent pane verdicts (P1.13, campaign §4.3): same verdict vocabulary
+//! as terminals — attach (tracked live) / respawn (resumable via
+//! provider-native resume) / dead_session (positively gone) / fresh — no new
+//! states. All async work (session maps, probes) happens in the snapshot
+//! builder (Task 13); this module is pure + sync so it stays legal inside
+//! derive_verdicts' catch_unwind.
+//!
+//! Verdict-mapping caveats (V5/A8, documented here for future readers):
+//! - Zero-turn codex threads have NO rollout file until the first PERSISTED
+//!   user message (vendor deferred materialization, verified at rust-v0.145.0)
+//!   ⇒ the probe answers Absent ⇒ verdict `fresh` (identity never observed)
+//!   or `dead_session` (ledger already bound it). Acceptable either way:
+//!   zero turns means there is no conversation content to lose.
+//! - WATCH: codex `.jsonl.zst` cold-rollout compression (vendor feature,
+//!   default-OFF today) would hide ≥7-day-old sessions from the `.jsonl`-only
+//!   index walk ⇒ false Absent. Revisit if the vendor flag graduates.
+//! - WATCH: CLAUDE_CONFIG_DIR/CLAUDE_HOME reader/writer split (pre-existing
+//!   wave-A exposure, out of scope this lane).
+
+use freshell_protocol::{PaneVerdict, ReconcilePane, ReconcileVerdict, SessionLocator};
+
+pub const FRESH_AGENT_RESPAWN_CAP: u32 = 3;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FreshAgentPresence {
+    Live,
+    OnDisk,
+    GoneObserved,
+    NeverObserved,
+    Unknown,
+}
+// B1 pre-decision (V9/A12): when B1's `SessionExistence::ProviderUnavailable`
+// lands, it maps to FreshAgentPresence::Unknown (conservative: respawn-with-cap,
+// never dead_session). Keep every SessionExistence match exhaustive, no catch-all.
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct FreshAgentPaneFacts {
+    pub presence: FreshAgentPresence,
+    pub duplicate_of: Option<String>, // paneKey of the earlier pane claiming the same session
+    pub respawn_exhausted: bool,
+    /// G3 supersession terminus (V8/A14): when the claimed sessionRef resolved
+    /// through the ledger's supersededBy chain to a DIFFERENT id, this is the
+    /// terminus id — the verdict answers with it + `corrected: true`.
+    pub resolved_session_id: Option<String>,
+}
+
+#[derive(Debug, Default)]
+pub struct FreshAgentReconcileSnapshot {
+    pub facts: std::collections::HashMap<String /* paneKey */, FreshAgentPaneFacts>,
+}
+
+/// The SINGLE PaneVerdict construction point in this module (B1-coexistence
+/// hardening, V9/A12 — keep it that way).
+fn base(pane: &ReconcilePane, verdict: ReconcileVerdict) -> PaneVerdict {
+    PaneVerdict {
+        pane_key: pane.pane_key.clone(),
+        verdict,
+        terminal_id: None,
+        session_ref: None,
+        corrected: None,
+        reason: None,
+        retry_after_ms: None, // DELETE-AT-MERGE: B1 removes this field
+        duplicate: None,
+    }
+}
+
+pub fn verdict_for_pane(
+    snapshot: Option<&FreshAgentReconcileSnapshot>,
+    pane: &ReconcilePane,
+) -> PaneVerdict {
+    let Some(snapshot) = snapshot else {
+        // Capability not negotiated: the frozen client keeps today's contract.
+        let mut v = base(pane, ReconcileVerdict::Invalid);
+        v.reason = Some("unsupported_kind".into());
+        return v;
+    };
+    let Some(sref) = pane.session_ref.clone() else {
+        let mut v = base(pane, ReconcileVerdict::Fresh);
+        v.reason = Some("no_recoverable_identity".into());
+        return v;
+    };
+    let Some(facts) = snapshot.facts.get(&pane.pane_key) else {
+        let mut v = base(pane, ReconcileVerdict::Fresh);
+        v.reason = Some("no_recoverable_identity".into());
+        return v;
+    };
+    if let Some(winner) = &facts.duplicate_of {
+        let mut v = base(pane, ReconcileVerdict::Fresh);
+        v.reason = Some("duplicate_session_claim".into());
+        v.duplicate = Some(winner.clone());
+        return v;
+    }
+    // G3 reader rule (V8/A14): when the claim resolved through the ledger's
+    // supersession chain, every echoed session_ref carries the TERMINUS id
+    // and the verdict is marked corrected (never answer the retired ref).
+    let (sref, corrected) = match &facts.resolved_session_id {
+        Some(terminus) if *terminus != sref.session_id => (
+            SessionLocator {
+                provider: sref.provider.clone(),
+                session_id: terminus.clone(),
+            },
+            Some(true),
+        ),
+        _ => (sref, None),
+    };
+    match facts.presence {
+        FreshAgentPresence::Live => {
+            let mut v = base(pane, ReconcileVerdict::Attach);
+            v.session_ref = Some(sref);
+            v.corrected = corrected;
+            v
+        }
+        FreshAgentPresence::OnDisk | FreshAgentPresence::Unknown => {
+            if facts.respawn_exhausted {
+                let mut v = base(pane, ReconcileVerdict::DeadSession);
+                v.reason = Some("respawn_exhausted".into());
+                v.session_ref = Some(sref);
+                v.corrected = corrected;
+                v
+            } else {
+                let mut v = base(pane, ReconcileVerdict::Respawn);
+                v.session_ref = Some(sref);
+                v.corrected = corrected;
+                v
+            }
+        }
+        FreshAgentPresence::GoneObserved => {
+            let mut v = base(pane, ReconcileVerdict::DeadSession);
+            v.reason = Some("session_not_on_disk".into());
+            v.session_ref = Some(sref);
+            v.corrected = corrected;
+            v
+        }
+        FreshAgentPresence::NeverObserved => {
+            let mut v = base(pane, ReconcileVerdict::Fresh);
+            v.reason = Some("identity_never_observed".into());
+            v
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn pane(key: &str, sref: Option<(&str, &str)>) -> ReconcilePane {
+        ReconcilePane {
+            pane_key: key.to_string(),
+            kind: Some("fresh-agent".into()),
+            mode: None,
+            create_request_id: None,
+            terminal_id: None,
+            server_instance_id: None,
+            session_ref: sref.map(|(provider, session_id)| SessionLocator {
+                provider: provider.to_string(),
+                session_id: session_id.to_string(),
+            }),
+            resume_session_id: None,
+            status: None,
+        }
+    }
+
+    fn snap(
+        entries: &[(&str, FreshAgentPresence, Option<&str>, bool)],
+    ) -> FreshAgentReconcileSnapshot {
+        let mut snapshot = FreshAgentReconcileSnapshot::default();
+        for (pane_key, presence, duplicate_of, respawn_exhausted) in entries {
+            snapshot.facts.insert(
+                pane_key.to_string(),
+                FreshAgentPaneFacts {
+                    presence: *presence,
+                    duplicate_of: duplicate_of.map(|s| s.to_string()),
+                    respawn_exhausted: *respawn_exhausted,
+                    resolved_session_id: None,
+                },
+            );
+        }
+        snapshot
+    }
+
+    #[test]
+    fn no_snapshot_means_capability_off_and_stays_invalid_unsupported() {
+        let v = verdict_for_pane(None, &pane("p", Some(("claude", "s"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Invalid);
+        assert_eq!(v.reason.as_deref(), Some("unsupported_kind"));
+    }
+
+    #[test]
+    fn missing_session_ref_is_fresh_no_recoverable_identity() {
+        let s = snap(&[]);
+        let v = verdict_for_pane(Some(&s), &pane("p", None));
+        assert_eq!(v.verdict, ReconcileVerdict::Fresh);
+        assert_eq!(v.reason.as_deref(), Some("no_recoverable_identity"));
+    }
+
+    #[test]
+    fn live_maps_to_attach_with_session_ref_echoed() {
+        let s = snap(&[("p", FreshAgentPresence::Live, None, false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("codex", "t1"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Attach);
+        assert_eq!(v.session_ref.as_ref().unwrap().session_id, "t1");
+        assert_eq!(v.terminal_id, None, "fresh-agent panes have no terminal id");
+    }
+
+    #[test]
+    fn on_disk_maps_to_respawn() {
+        let s = snap(&[("p", FreshAgentPresence::OnDisk, None, false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("opencode", "ses_1"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Respawn);
+        assert_eq!(v.session_ref.as_ref().unwrap().session_id, "ses_1");
+    }
+
+    #[test]
+    fn gone_observed_maps_to_dead_session_not_on_disk() {
+        let s = snap(&[("p", FreshAgentPresence::GoneObserved, None, false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("claude", "gone"))));
+        assert_eq!(v.verdict, ReconcileVerdict::DeadSession);
+        assert_eq!(v.reason.as_deref(), Some("session_not_on_disk"));
+        assert_eq!(
+            v.session_ref.as_ref().unwrap().session_id,
+            "gone",
+            "claimed identity echoed for the error UI"
+        );
+    }
+
+    #[test]
+    fn never_observed_maps_to_fresh_identity_never_observed() {
+        let s = snap(&[("p", FreshAgentPresence::NeverObserved, None, false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("claude", "never"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Fresh);
+        assert_eq!(v.reason.as_deref(), Some("identity_never_observed"));
+    }
+
+    #[test]
+    fn unknown_prefers_respawn_over_memory_loss() {
+        // Cost asymmetry: respawn on a gone session degrades gracefully via the
+        // providers' native not-found fallbacks; fresh on a live-on-disk session
+        // loses conversation memory permanently.
+        let s = snap(&[("p", FreshAgentPresence::Unknown, None, false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("codex", "warm"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Respawn);
+    }
+
+    #[test]
+    fn duplicate_claim_yields_fresh_with_duplicate_marker() {
+        let s = snap(&[("p2", FreshAgentPresence::OnDisk, Some("p1"), false)]);
+        let v = verdict_for_pane(Some(&s), &pane("p2", Some(("codex", "t1"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Fresh);
+        assert_eq!(v.reason.as_deref(), Some("duplicate_session_claim"));
+        assert_eq!(v.duplicate.as_deref(), Some("p1"));
+    }
+
+    #[test]
+    fn respawn_exhausted_yields_dead_session() {
+        let s = snap(&[("p", FreshAgentPresence::OnDisk, None, true)]);
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("codex", "t1"))));
+        assert_eq!(v.verdict, ReconcileVerdict::DeadSession);
+        assert_eq!(v.reason.as_deref(), Some("respawn_exhausted"));
+    }
+
+    #[test]
+    fn superseded_claim_is_answered_from_the_chain_terminus_with_corrected() {
+        // G3 reader rule (V8/A14): a client claiming a superseded ref is
+        // answered from the chain terminus — never respawn the retired ref.
+        // Facts built directly: presence OnDisk, resolved_session_id Some("t2").
+        let mut s = snap(&[("p", FreshAgentPresence::OnDisk, None, false)]);
+        s.facts.get_mut("p").unwrap().resolved_session_id = Some("t2".into());
+        let v = verdict_for_pane(Some(&s), &pane("p", Some(("codex", "t1"))));
+        assert_eq!(v.verdict, ReconcileVerdict::Respawn);
+        assert_eq!(
+            v.session_ref.as_ref().unwrap().session_id,
+            "t2",
+            "answer carries the terminus id, not the retired claim"
+        );
+        assert_eq!(v.corrected, Some(true));
+    }
+}

From 6b3a1631221811c80536a1e1ebfeb0a77f27535c Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 07:17:49 -0700
Subject: [PATCH 67/87] feat(client): batched dead-session adjudication panel +
 single warming banner with manual retry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DeadSessionPanel: ONE role="dialog" (aria-label "Dead sessions") listing
ALL dead panes (council rule 1 / F11-human — never N modals). Per-row
"Start fresh here" dispatches resetPaneForReconcileCreate({intent:'fresh'})
preserving createRequestId (I7) + resolves the row; "Close pane" goes
through closePaneWithCleanup (the established component-level close path,
handles the last-pane→close-tab case); "Dismiss" clears the list but keeps
per-pane restoreError cards. Nothing is auto-closed (council rule 12).

ReconcileWarmingBanner: ONE role="status" banner "Waiting for session
index — N pane(s)" (council rule 5). Prominent "Retry now" re-sends a
reconcile request for exactly the warming panes and folds ONLY results
whose reconcileId its own Retry minted (fold-ownership rule, Task 9),
via the Task-12 subscribe→match→foldVerdicts→unsubscribe pattern —
subscription exists only while a retry is in flight. Cardinality
violations keep the banner up for another retry.

Both mounted in App.tsx beside AuthRequiredModal.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 src/App.tsx                                   |   4 +
 src/components/DeadSessionPanel.tsx           |  98 +++++++
 src/components/ReconcileWarmingBanner.tsx     |  84 ++++++
 .../components/DeadSessionPanel.test.tsx      | 256 ++++++++++++++++++
 4 files changed, 442 insertions(+)
 create mode 100644 src/components/DeadSessionPanel.tsx
 create mode 100644 src/components/ReconcileWarmingBanner.tsx
 create mode 100644 test/unit/client/components/DeadSessionPanel.test.tsx

diff --git a/src/App.tsx b/src/App.tsx
index a2ca6f986..9cc4bb10a 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -52,6 +52,8 @@ import OverviewView from '@/components/OverviewView'
 import TabsView from '@/components/TabsView'
 import PaneDivider from '@/components/panes/PaneDivider'
 import { AuthRequiredModal } from '@/components/AuthRequiredModal'
+import { DeadSessionPanel } from '@/components/DeadSessionPanel'
+import { ReconcileWarmingBanner } from '@/components/ReconcileWarmingBanner'
 import { SetupWizard } from '@/components/SetupWizard'
 import { ErrorBoundary } from '@/components/ui/error-boundary'
 import { fetchNetworkStatus } from '@/store/networkSlice'
@@ -1827,6 +1829,8 @@ npm run serve`}</pre>
         </div>
       )}
       <AuthRequiredModal />
+      <DeadSessionPanel />
+      <ReconcileWarmingBanner />
       {showSetupWizard && (
         <SetupWizard
           initialStep={wizardInitialStep}
diff --git a/src/components/DeadSessionPanel.tsx b/src/components/DeadSessionPanel.tsx
new file mode 100644
index 000000000..a917e28e8
--- /dev/null
+++ b/src/components/DeadSessionPanel.tsx
@@ -0,0 +1,98 @@
+import { createPortal } from 'react-dom'
+import { useAppDispatch, useAppSelector } from '@/store/hooks'
+import {
+  clearDeadSessionAdjudication,
+  resetPaneForReconcileCreate,
+  resolveDeadSessionEntry,
+} from '@/store/panesSlice'
+import { closePaneWithCleanup } from '@/store/tabsSlice'
+import type { DeadSessionEntry } from '@/store/paneTypes'
+import { OVERLAY_Z } from '@/components/ui/overlay'
+
+/**
+ * Batched dead-session adjudication panel (council rule 1 / F11-human):
+ * ONE dialog listing ALL panes whose saved session the server reported
+ * dead — never one modal per pane. Council rule 12: dead_session is a UI
+ * state, not a deletion — nothing is auto-closed; every row waits for an
+ * explicit user decision.
+ */
+export function DeadSessionPanel() {
+  const dispatch = useAppDispatch()
+  // Default OUTSIDE the selector: `?? []` inside would mint a new array per
+  // call and trip react-redux's memoization warning.
+  const entries = useAppSelector((s) => s.panes.deadSessionAdjudication) ?? []
+
+  if (entries.length === 0) return null
+
+  const handleStartFresh = (entry: DeadSessionEntry) => {
+    // I7: same createRequestId — the reducer preserves it; only intent
+    // resets to a fresh, identity-less create.
+    dispatch(resetPaneForReconcileCreate({ tabId: entry.tabId, paneId: entry.paneId, intent: 'fresh' }))
+    dispatch(resolveDeadSessionEntry({ tabId: entry.tabId, paneId: entry.paneId }))
+  }
+
+  const handleClosePane = (entry: DeadSessionEntry) => {
+    dispatch(closePaneWithCleanup({ tabId: entry.tabId, paneId: entry.paneId }))
+    dispatch(resolveDeadSessionEntry({ tabId: entry.tabId, paneId: entry.paneId }))
+  }
+
+  return createPortal(
+    <div
+      className={`fixed inset-0 flex items-center justify-center bg-black/50 ${OVERLAY_Z.modal}`}
+      role="presentation"
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label="Dead sessions"
+        className="bg-background border border-border rounded-lg shadow-lg w-full max-w-lg mx-4 p-5 max-h-[80vh] flex flex-col"
+      >
+        <h2 className="text-lg font-semibold mb-2">Dead sessions</h2>
+        <p className="text-sm text-muted-foreground mb-4">
+          These panes reference saved sessions that no longer exist. Nothing has been
+          closed — choose what to do with each pane.
+        </p>
+        <ul className="space-y-3 overflow-y-auto flex-1 min-h-0">
+          {entries.map((entry) => (
+            <li
+              key={`${entry.tabId}:${entry.paneId}`}
+              className="flex items-center justify-between gap-3 border border-border rounded-md p-3"
+            >
+              <div className="min-w-0">
+                <div className="text-sm font-medium truncate">{entry.title}</div>
+                <div className="text-xs text-muted-foreground truncate">
+                  {entry.mode}
+                  {entry.reason ? ` — ${entry.reason}` : ''}
+                </div>
+              </div>
+              <div className="flex shrink-0 gap-2">
+                <button
+                  onClick={() => handleStartFresh(entry)}
+                  className="px-3 py-1.5 text-xs bg-primary text-primary-foreground rounded-md hover:bg-primary/90 transition-colors"
+                >
+                  Start fresh here
+                </button>
+                <button
+                  onClick={() => handleClosePane(entry)}
+                  className="px-3 py-1.5 text-xs border border-border rounded-md hover:bg-muted transition-colors"
+                >
+                  Close pane
+                </button>
+              </div>
+            </li>
+          ))}
+        </ul>
+        <div className="mt-4 flex justify-end">
+          {/* Dismiss keeps the per-pane restoreError cards — panes stay untouched. */}
+          <button
+            onClick={() => dispatch(clearDeadSessionAdjudication())}
+            className="px-4 py-2 text-sm border border-border rounded-md hover:bg-muted transition-colors"
+          >
+            Dismiss
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  )
+}
diff --git a/src/components/ReconcileWarmingBanner.tsx b/src/components/ReconcileWarmingBanner.tsx
new file mode 100644
index 000000000..bccda85e2
--- /dev/null
+++ b/src/components/ReconcileWarmingBanner.tsx
@@ -0,0 +1,84 @@
+import { useEffect, useRef } from 'react'
+import { useAppDispatch, useAppSelector, useAppStore } from '@/store/hooks'
+import { clearReconcileWarming } from '@/store/panesSlice'
+import { buildReconcileRequestForPanes, foldVerdicts } from '@/lib/pane-reconcile'
+import { getWsClient } from '@/lib/ws-client'
+import type { PaneReconcileRequest } from '@shared/ws-protocol'
+import { OVERLAY_Z } from '@/components/ui/overlay'
+
+/**
+ * ONE warming banner for ALL panes whose reconcile verdicts came back
+ * index_warming (council rule 5) — never one banner per pane. This state
+ * is EXPECTED on cold boots: the session index scan can take minutes, so
+ * "Retry now" is the prominent recovery path, not an edge case.
+ */
+export function ReconcileWarmingBanner() {
+  const dispatch = useAppDispatch()
+  const store = useAppStore()
+  const warming = useAppSelector((s) => s.panes.reconcileWarming)
+  const pendingRef = useRef<{ request: PaneReconcileRequest; unsubscribe: () => void } | null>(null)
+
+  // Unmount safety: drop any in-flight retry subscription.
+  useEffect(
+    () => () => {
+      pendingRef.current?.unsubscribe()
+      pendingRef.current = null
+    },
+    [],
+  )
+
+  if (!warming || warming.count <= 0) return null
+
+  const handleRetry = () => {
+    // Re-send a reconcile request for EXACTLY the warming panes.
+    const request = buildReconcileRequestForPanes(store.getState(), warming.paneRefs)
+    if (!request) {
+      // None of the warming panes are reconcilable any more (closed, etc.).
+      dispatch(clearReconcileWarming())
+      return
+    }
+    // Supersede an older in-flight retry: last click wins.
+    pendingRef.current?.unsubscribe()
+    const ws = getWsClient()
+    // Task-12 pattern: subscribe -> match reconcileId -> foldVerdicts -> unsubscribe.
+    const unsubscribe = ws.onMessage((msg) => {
+      if (msg.type !== 'pane.reconcile.result') return
+      // Fold-ownership rule (pane-reconcile.ts): fold ONLY the result whose
+      // reconcileId THIS Retry minted; foreign reconciles are silently skipped.
+      if (msg.reconcileId !== request.reconcileId) return
+      pendingRef.current?.unsubscribe()
+      pendingRef.current = null
+      const outcome = foldVerdicts(dispatch, request, msg)
+      if (outcome.cardinalityViolation) {
+        console.error(
+          'reconcile warming retry: cardinality violation in result — keeping the banner; Retry again',
+        )
+        return
+      }
+      if (outcome.warming === 0) {
+        // foldVerdicts re-sets the warming state itself when verdicts are
+        // still warm; a fully-resolved retry clears the banner here.
+        dispatch(clearReconcileWarming())
+      }
+    })
+    pendingRef.current = { request, unsubscribe }
+    ws.send(request)
+  }
+
+  return (
+    <div
+      role="status"
+      className={`fixed top-3 left-1/2 -translate-x-1/2 ${OVERLAY_Z.menu} flex items-center gap-3 bg-background border border-border rounded-md shadow-lg px-4 py-2`}
+    >
+      <span className="text-sm">
+        Waiting for session index — {warming.count} pane(s)
+      </span>
+      <button
+        onClick={handleRetry}
+        className="px-3 py-1.5 text-xs font-medium bg-primary text-primary-foreground rounded-md hover:bg-primary/90 transition-colors shrink-0"
+      >
+        Retry now
+      </button>
+    </div>
+  )
+}
diff --git a/test/unit/client/components/DeadSessionPanel.test.tsx b/test/unit/client/components/DeadSessionPanel.test.tsx
new file mode 100644
index 000000000..2b003b15d
--- /dev/null
+++ b/test/unit/client/components/DeadSessionPanel.test.tsx
@@ -0,0 +1,256 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, screen, cleanup, act } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Provider } from 'react-redux'
+import { configureStore } from '@reduxjs/toolkit'
+import type { Store } from '@reduxjs/toolkit'
+import panesReducer, { resetPaneForReconcileCreate, clearReconcileWarming } from '@/store/panesSlice'
+import type { DeadSessionEntry, PaneNode, ReconcileWarmingState } from '@/store/paneTypes'
+import { buildRestoreError } from '@shared/session-contract'
+import { DeadSessionPanel } from '@/components/DeadSessionPanel'
+import { ReconcileWarmingBanner } from '@/components/ReconcileWarmingBanner'
+
+// --- ws-client mock: capture sent frames, support multiple onMessage subscribers ---
+
+const wsMocks = vi.hoisted(() => ({
+  send: vi.fn(),
+  onMessage: vi.fn(),
+}))
+
+vi.mock('@/lib/ws-client', () => ({
+  getWsClient: () => ({
+    send: wsMocks.send,
+    onMessage: wsMocks.onMessage,
+  }),
+}))
+
+const sentFrames: any[] = []
+const messageHandlers = new Set<(msg: any) => void>()
+
+function lastSentOfType(type: string): any {
+  return [...sentFrames].reverse().find((f) => f?.type === type)
+}
+
+function deliverServerFrame(frame: Record<string, unknown>): void {
+  act(() => {
+    for (const handler of [...messageHandlers]) handler(frame)
+  })
+}
+
+// --- store helpers: real panes reducer, seeded layouts ---
+
+function leafPane(paneId: string, extra: Record<string, unknown> = {}): PaneNode {
+  return {
+    type: 'leaf',
+    id: paneId,
+    content: {
+      kind: 'terminal',
+      mode: 'shell',
+      shell: 'system',
+      status: 'running',
+      createRequestId: `cr-${paneId}`,
+      terminalId: `term-${paneId}`,
+      ...extra,
+    } as any,
+  }
+}
+
+function layoutFor(paneIds: string[], extraByPane: Record<string, Record<string, unknown>> = {}): PaneNode {
+  const leaves = paneIds.map((id) => leafPane(id, extraByPane[id] ?? {}))
+  return leaves.reduce((acc, leaf, i) =>
+    acc === null
+      ? leaf
+      : ({
+          type: 'split',
+          id: `split-${i}`,
+          direction: 'horizontal',
+          children: [acc, leaf],
+          sizes: [50, 50],
+        } as PaneNode),
+  null as PaneNode | null)!
+}
+
+function entry(paneId: string): DeadSessionEntry {
+  return { tabId: 'tab-1', paneId, title: `Terminal ${paneId}`, mode: 'shell' }
+}
+
+function ref(paneId: string): { tabId: string; paneId: string } {
+  return { tabId: 'tab-1', paneId }
+}
+
+function sevenRefs(): { tabId: string; paneId: string }[] {
+  return ['p1', 'p2', 'p3', 'p4', 'p5', 'p6', 'p7'].map(ref)
+}
+
+const storeDispatchedTypes = new WeakMap<Store, string[]>()
+
+function dispatchedTypes(store: Store): string[] {
+  return storeDispatchedTypes.get(store) ?? []
+}
+
+function renderWithStore(opts: {
+  deadSessionAdjudication?: DeadSessionEntry[]
+  reconcileWarming?: ReconcileWarmingState | null
+  paneIds?: string[]
+  extraContentByPane?: Record<string, Record<string, unknown>>
+}) {
+  const paneIds =
+    opts.paneIds ??
+    [...new Set([
+      ...(opts.deadSessionAdjudication ?? []).map((e) => e.paneId),
+      ...(opts.reconcileWarming?.paneRefs ?? []).map((r) => r.paneId),
+    ])]
+  const captured: string[] = []
+  const store = configureStore({
+    reducer: { panes: panesReducer },
+    middleware: (getDefault) =>
+      getDefault().concat(() => (next) => (action: any) => {
+        if (typeof action?.type === 'string') captured.push(action.type)
+        return next(action)
+      }),
+    preloadedState: {
+      panes: {
+        layouts: paneIds.length > 0 ? { 'tab-1': layoutFor(paneIds, opts.extraContentByPane ?? {}) } : {},
+        activePane: {},
+        paneTitles: {},
+        paneTitleSetByUser: {},
+        renameRequestTabId: null,
+        renameRequestPaneId: null,
+        zoomedPane: {},
+        refreshRequestsByPane: {},
+        restoreFallbackAttemptsByPane: {},
+        deadSessionAdjudication: opts.deadSessionAdjudication ?? [],
+        reconcileWarming: opts.reconcileWarming ?? null,
+      } as any,
+    },
+  })
+  storeDispatchedTypes.set(store, captured)
+  render(
+    <Provider store={store}>
+      <DeadSessionPanel />
+      <ReconcileWarmingBanner />
+    </Provider>,
+  )
+  return { store }
+}
+
+function findLeaf(node: any, paneId: string): any {
+  if (!node) return null
+  if (node.type === 'leaf') return node.id === paneId ? node : null
+  return findLeaf(node.children[0], paneId) ?? findLeaf(node.children[1], paneId)
+}
+
+describe('DeadSessionPanel + ReconcileWarmingBanner', () => {
+  beforeEach(() => {
+    cleanup()
+    vi.clearAllMocks()
+    sentFrames.length = 0
+    messageHandlers.clear()
+    wsMocks.send.mockImplementation((frame: unknown) => {
+      sentFrames.push(frame)
+    })
+    wsMocks.onMessage.mockImplementation((cb: (msg: any) => void) => {
+      messageHandlers.add(cb)
+      return () => messageHandlers.delete(cb)
+    })
+  })
+
+  afterEach(() => {
+    cleanup()
+  })
+
+  // F11-human: one panel, never N modals.
+  it('renders ONE dialog listing all dead panes', () => {
+    renderWithStore({ deadSessionAdjudication: [entry('p1'), entry('p2'), entry('p3')] })
+    expect(screen.getAllByRole('dialog')).toHaveLength(1)
+    expect(screen.getByRole('dialog')).toHaveAccessibleName('Dead sessions')
+    expect(screen.getAllByRole('button', { name: /start fresh here/i })).toHaveLength(3)
+  })
+
+  it('Start fresh dispatches a fresh reset preserving createRequestId and removes the row', async () => {
+    const { store } = renderWithStore({ deadSessionAdjudication: [entry('p1')] })
+    await userEvent.click(screen.getByRole('button', { name: /start fresh here/i }))
+    expect(dispatchedTypes(store)).toContain(resetPaneForReconcileCreate.type)
+    expect(store.getState().panes.deadSessionAdjudication).toHaveLength(0)
+    // I7: same createRequestId — never re-minted; pane reset for a fresh create.
+    const leaf = findLeaf(store.getState().panes.layouts['tab-1'], 'p1')
+    expect(leaf.content.createRequestId).toBe('cr-p1')
+    expect(leaf.content.status).toBe('creating')
+    expect(leaf.content.sessionRef).toBeUndefined()
+  })
+
+  // Council rule 12: dead_session is a UI state, not a deletion — closing is an explicit user act.
+  it('Close pane removes the pane from the layout and resolves the row', async () => {
+    const { store } = renderWithStore({
+      deadSessionAdjudication: [entry('p1')],
+      paneIds: ['p1', 'p2'],
+    })
+    await userEvent.click(screen.getByRole('button', { name: /close pane/i }))
+    const root = store.getState().panes.layouts['tab-1'] as any
+    expect(root.type).toBe('leaf')
+    expect(root.id).toBe('p2')
+    expect(store.getState().panes.deadSessionAdjudication).toHaveLength(0)
+  })
+
+  it('Dismiss clears the adjudication list but keeps the per-pane restoreError card', async () => {
+    const { store } = renderWithStore({
+      deadSessionAdjudication: [entry('p1')],
+      extraContentByPane: { p1: { restoreError: buildRestoreError('durable_artifact_missing') } },
+    })
+    await userEvent.click(screen.getByRole('button', { name: /dismiss/i }))
+    expect(store.getState().panes.deadSessionAdjudication).toHaveLength(0)
+    expect(screen.queryByRole('dialog')).toBeNull()
+    const leaf = findLeaf(store.getState().panes.layouts['tab-1'], 'p1')
+    expect(leaf.content.restoreError).toBeDefined()
+  })
+
+  it('renders nothing when the list is empty', () => {
+    renderWithStore({ deadSessionAdjudication: [] })
+    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+
+  // restart-storm-all-panes-warming (council red test, client half):
+  it('N warming panes produce exactly ONE banner with the count', () => {
+    renderWithStore({ reconcileWarming: { count: 7, paneRefs: sevenRefs() } })
+    expect(screen.getAllByRole('status')).toHaveLength(1)
+    expect(screen.getByRole('status')).toHaveTextContent(/waiting for session index/i)
+    expect(screen.getByRole('status')).toHaveTextContent(/7/)
+  })
+
+  it('Retry now re-sends a reconcile request for exactly the warming panes', async () => {
+    renderWithStore({ reconcileWarming: { count: 2, paneRefs: [ref('p1'), ref('p2')] } })
+    await userEvent.click(screen.getByRole('button', { name: /retry now/i }))
+    const req = lastSentOfType('pane.reconcile.request')
+    expect(req).toBeDefined()
+    expect(req.panes).toHaveLength(2)
+    expect(req.panes.map((p: any) => p.paneKey).sort()).toEqual(['tab-1:p1', 'tab-1:p2'])
+  })
+
+  // Fold-ownership rule (Task 9): the banner folds ONLY results whose reconcileId its own Retry minted.
+  it('Retry folds only its own reconcile result, skipping foreign reconcileIds', async () => {
+    const { store } = renderWithStore({ reconcileWarming: { count: 2, paneRefs: [ref('p1'), ref('p2')] } })
+    await userEvent.click(screen.getByRole('button', { name: /retry now/i }))
+    const req = lastSentOfType('pane.reconcile.request')
+
+    const resultFor = (reconcileId: string) => ({
+      type: 'pane.reconcile.result',
+      reconcileId,
+      bootId: 'boot-1',
+      serverInstanceId: 'srv-1',
+      verdicts: req.panes.map((pane: any) => ({
+        paneKey: pane.paneKey,
+        verdict: 'attach',
+        terminalId: `live-${pane.paneKey}`,
+      })),
+    })
+
+    deliverServerFrame(resultFor('foreign-reconcile-id'))
+    expect(store.getState().panes.reconcileWarming).not.toBeNull()
+    expect(dispatchedTypes(store)).not.toContain(clearReconcileWarming.type)
+
+    deliverServerFrame(resultFor(req.reconcileId))
+    expect(store.getState().panes.reconcileWarming).toBeNull()
+    expect(screen.queryByRole('status')).toBeNull()
+  })
+})

From 9962e0f19fc506b9e5a0620a81e38f2a5814683f Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 07:19:23 -0700
Subject: [PATCH 68/87] test(e2e): remove offer retry loop - fresh-context
 offer visibility is a single hard assertion (B3/P1.9 review fix)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

openFreshContextWithOffer no longer retries with new contexts: with
service workers blocked, the known cause of transient offer suppression
is gone, and the loop would silently absorb exactly the flaky-offer
regression class this feature already exhibited. The offer must appear
in ONE fresh context within 15s or the spec fails loud (the brief's
contract). 2 consecutive green runs.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../specs/recover-my-panes-rust.spec.ts       | 33 +++++++------------
 1 file changed, 12 insertions(+), 21 deletions(-)

diff --git a/test/e2e-browser/specs/recover-my-panes-rust.spec.ts b/test/e2e-browser/specs/recover-my-panes-rust.spec.ts
index 176cfd896..559f157ca 100644
--- a/test/e2e-browser/specs/recover-my-panes-rust.spec.ts
+++ b/test/e2e-browser/specs/recover-my-panes-rust.spec.ts
@@ -226,32 +226,23 @@ test.describe('recover-my-panes browser-loss recovery (rust only)', () => {
   const FRESH_CONTEXT_OPTIONS = { serviceWorkers: 'block' as const }
 
   /**
-   * Open a FRESH context (empty storage) and require the recovery offer.
-   * Retries with a brand-new fresh context (same eligibility — the user
-   * opening another fresh window) as insurance against residual transient
-   * boot-fetch loss; a genuinely broken offer still fails all attempts —
-   * the red-verification (panel unmounted) proves this loop fails.
+   * Open a FRESH context (empty storage) and REQUIRE the recovery offer —
+   * one context, one hard `toBeVisible` assertion (the brief's contract).
+   * No retry loop: with service workers blocked (above) the only known cause
+   * of transient offer suppression is gone, and a retry here would quietly
+   * absorb exactly the flaky-offer regression class this feature already
+   * exhibited once. If the offer ever goes flaky again, this MUST fail loud.
    */
   async function openFreshContextWithOffer(
     browser: import('@playwright/test').Browser,
     label: string,
   ): Promise<{ ctx: BrowserContext; page: Page; harness: TestHarness }> {
-    const attempts = 3
-    for (let attempt = 1; attempt <= attempts; attempt++) {
-      const ctx = await browser.newContext(FRESH_CONTEXT_OPTIONS)
-      const page = await ctx.newPage()
-      traceInventoryFailures(page, label)
-      const harness = await connect(page, info)
-      try {
-        await page.getByTestId('recovery-offer-panel').waitFor({ state: 'visible', timeout: 15_000 })
-        return { ctx, page, harness }
-      } catch (err) {
-        if (attempt === attempts) throw err
-        console.log(`[${label}] offer absent in fresh context (attempt ${attempt}/${attempts}) — retrying with a new context`)
-        await ctx.close()
-      }
-    }
-    throw new Error('unreachable')
+    const ctx = await browser.newContext(FRESH_CONTEXT_OPTIONS)
+    const page = await ctx.newPage()
+    traceInventoryFailures(page, label)
+    const harness = await connect(page, info)
+    await expect(page.getByTestId('recovery-offer-panel')).toBeVisible({ timeout: 15_000 })
+    return { ctx, page, harness }
   }
 
   // Scenario 1's claude session — scenario 2/3 reason about the same log.

From 786153d61934d300120541decac7eeed96a4d90e Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 07:33:39 -0700
Subject: [PATCH 69/87] =?UTF-8?q?feat(ws):=20fresh-agent=20panes=20enter?=
 =?UTF-8?q?=20the=20reconcile=20verdict=20system=20behind=20paneReconcileF?=
 =?UTF-8?q?reshAgentV1=20(P1.13=20=C2=A74.3)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 crates/freshell-freshagent/src/claude.rs      |  11 +
 crates/freshell-freshagent/src/codex.rs       |  11 +
 crates/freshell-freshagent/src/opencode_ws.rs |   8 +
 .../freshell-protocol/src/client_messages.rs  |   4 +-
 crates/freshell-server/src/main.rs            |   3 +
 .../freshell-ws/src/amplifier_association.rs  |   1 +
 crates/freshell-ws/src/lib.rs                 |  10 +
 .../freshell-ws/src/opencode_association.rs   |   1 +
 crates/freshell-ws/src/reconcile.rs           |  11 +-
 .../freshell-ws/src/reconcile_freshagent.rs   | 132 +++++
 crates/freshell-ws/src/terminal.rs            |  33 +-
 .../tests/codex_managed_launch_e2e.rs         |   1 +
 .../tests/codex_session_ref_resume.rs         |   1 +
 crates/freshell-ws/tests/common/mod.rs        |   4 +
 .../tests/diag01_lifecycle_events.rs          |   1 +
 .../tests/freshagent_claude_attach.rs         |   1 +
 .../tests/freshagent_claude_kill_interrupt.rs |   1 +
 crates/freshell-ws/tests/hello_timeout.rs     |   1 +
 crates/freshell-ws/tests/keepalive.rs         |   1 +
 crates/freshell-ws/tests/max_payload.rs       |   1 +
 crates/freshell-ws/tests/origin_policy.rs     |   1 +
 crates/freshell-ws/tests/pane_reconcile.rs    |   1 +
 .../tests/pane_reconcile_freshagent.rs        | 481 +++++++++++++++++-
 .../tests/safe08_restore_diagnostics.rs       |   1 +
 .../freshell-ws/tests/term09_output_queue.rs  |   1 +
 25 files changed, 694 insertions(+), 28 deletions(-)

diff --git a/crates/freshell-freshagent/src/claude.rs b/crates/freshell-freshagent/src/claude.rs
index 0e4afc5e0..d0bcd98a8 100644
--- a/crates/freshell-freshagent/src/claude.rs
+++ b/crates/freshell-freshagent/src/claude.rs
@@ -477,6 +477,17 @@ impl FreshClaudeState {
         ));
     }
 
+    /// Reconcile liveness probe (campaign §4.3, Task 13): resolve the DURABLE
+    /// claude UUID through [`Self::cli_index`] to its sessions-map key, then
+    /// check the map. The sessions map is read UNFILTERED — no session_type
+    /// filter, so kilroy sessions count for free (V2 N-A17-1).
+    pub async fn has_live_session(&self, session_id: &str) -> bool {
+        let Some(key) = self.cli_index.lock().await.get(session_id).cloned() else {
+            return false;
+        };
+        self.sessions.lock().await.contains_key(&key)
+    }
+
     // ── freshAgent.attach (restart parity: resume untracked sessions in place) ──────────
 
     /// Handle a `freshAgent.attach` for claude/kilroy. Decision table (restart parity):
diff --git a/crates/freshell-freshagent/src/codex.rs b/crates/freshell-freshagent/src/codex.rs
index eb625503d..aa63c68f1 100644
--- a/crates/freshell-freshagent/src/codex.rs
+++ b/crates/freshell-freshagent/src/codex.rs
@@ -1038,6 +1038,17 @@ impl FreshCodexState {
 
     // ── freshAgent.attach (reload-rehydrate, PR-4) ──────────────────────────
 
+    /// Reconcile liveness probe (campaign §4.3, Task 13): is this thread id
+    /// tracked in the sessions map with a sidecar that has NOT exited? The
+    /// exited check matters — a crashed sidecar stays mapped for lazy respawn
+    /// ([`Self::ensure_session_alive`]), but it is not attach-ably live.
+    pub async fn has_live_session(&self, session_id: &str) -> bool {
+        let guard = self.sessions.lock().await;
+        guard
+            .get(session_id)
+            .is_some_and(|s| !s.exited.load(Ordering::SeqCst))
+    }
+
     /// Handle a `freshAgent.attach` for codex (reload-rehydrate). Decision table:
     ///
     /// | State | Action |
diff --git a/crates/freshell-freshagent/src/opencode_ws.rs b/crates/freshell-freshagent/src/opencode_ws.rs
index 4e7ca4424..a0567c511 100644
--- a/crates/freshell-freshagent/src/opencode_ws.rs
+++ b/crates/freshell-freshagent/src/opencode_ws.rs
@@ -699,6 +699,14 @@ impl FreshOpencodeState {
         session.turn_task = Some(turn_task);
     }
 
+    /// Reconcile liveness probe (campaign §4.3, Task 13): is this id tracked
+    /// in the sessions map? The map is keyed by BOTH the placeholder AND the
+    /// durable `ses_*` id (the `remember()` mirror), so a durable-id lookup
+    /// resolves the same record.
+    pub async fn has_live_session(&self, session_id: &str) -> bool {
+        self.sessions.lock().await.contains_key(session_id)
+    }
+
     // ── freshAgent.kill (WS) ────────────────────────────────────────────────
 
     /// Handle a `freshAgent.kill` for opencode: remove the session's bookkeeping (both
diff --git a/crates/freshell-protocol/src/client_messages.rs b/crates/freshell-protocol/src/client_messages.rs
index 7f411e9b1..c6e5ae314 100644
--- a/crates/freshell-protocol/src/client_messages.rs
+++ b/crates/freshell-protocol/src/client_messages.rs
@@ -359,7 +359,9 @@ pub struct ReconcilePane {
     /// client omitted it (the entry is then `invalid`).
     #[serde(default)]
     pub pane_key: String,
-    /// v1: `"terminal"` only (fresh-agent extension deferred, §12).
+    /// v1: `"terminal"`; `"fresh-agent"` is answered on connections that
+    /// negotiated `paneReconcileFreshAgentV1` (campaign §4.3) — otherwise it
+    /// keeps the frozen-client `invalid{unsupported_kind}` contract.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub kind: Option<String>,
     /// `TerminalMode` string as persisted (`"shell"`, `"claude"`, …).
diff --git a/crates/freshell-server/src/main.rs b/crates/freshell-server/src/main.rs
index 53949ccf3..f5ab827d9 100644
--- a/crates/freshell-server/src/main.rs
+++ b/crates/freshell-server/src/main.rs
@@ -460,6 +460,9 @@ async fn main() -> ExitCode {
             )),
             None => std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
         },
+        // Per-boot fresh-agent respawn-answer counter (campaign §4.3, V2/A7):
+        // in-memory by design — a restart intentionally resets it.
+        fresh_agent_respawn_counts: Default::default(),
         auth_token: Arc::clone(&auth_token),
         // Shared (not moved) so `GET /api/health` reports the SAME `instanceId`.
         server_instance_id: Arc::clone(&server_instance_id),
diff --git a/crates/freshell-ws/src/amplifier_association.rs b/crates/freshell-ws/src/amplifier_association.rs
index 35c08f49c..6e1dd6f2c 100644
--- a/crates/freshell-ws/src/amplifier_association.rs
+++ b/crates/freshell-ws/src/amplifier_association.rs
@@ -316,6 +316,7 @@ mod tests {
             config_fallback: None,
             amplifier_locator: Some(StdArc::new(AmplifierLocator::new(amplifier_home))),
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+            fresh_agent_respawn_counts: Default::default(),
             opencode_locator: None,
             activity: None,
         };
diff --git a/crates/freshell-ws/src/lib.rs b/crates/freshell-ws/src/lib.rs
index 9cd115897..3e429cd01 100644
--- a/crates/freshell-ws/src/lib.rs
+++ b/crates/freshell-ws/src/lib.rs
@@ -230,6 +230,15 @@ pub struct WsState {
     /// of `identity` and the locator handles); [`crate::existence::NoIndexProbe`]
     /// when no provider home resolves.
     pub session_existence: crate::existence::SharedExistenceProbe,
+    /// Per-boot fresh-agent respawn-answer counter, keyed `(provider,
+    /// sessionId)` (campaign §4.3, V2/A7). Counts RESPAWN ANSWERS only —
+    /// incremented by [`crate::reconcile_freshagent::build_snapshot`] when an
+    /// answer goes out as `respawn`, and CLEARED when the session's presence
+    /// resolves Live (a successful respawn is OBSERVED as the session going
+    /// live), so healthy sessions are never exhausted by reconnect/reload
+    /// storms. In-memory only: a server restart intentionally resets it.
+    pub fresh_agent_respawn_counts:
+        std::sync::Arc<std::sync::Mutex<std::collections::HashMap<(String, String), u32>>>,
     /// The opencode terminal-pane session locator (restore-across-restart fix,
     /// `docs/plans/2026-07-18-opencode-terminal-restore-spec.md`): correlates a
     /// fresh opencode PTY's first Enter/submit (or a row written at spawn) with
@@ -758,6 +767,7 @@ mod tests {
             opencode_locator: None,
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+            fresh_agent_respawn_counts: Default::default(),
         }
     }
 
diff --git a/crates/freshell-ws/src/opencode_association.rs b/crates/freshell-ws/src/opencode_association.rs
index df20d50a6..6192fa511 100644
--- a/crates/freshell-ws/src/opencode_association.rs
+++ b/crates/freshell-ws/src/opencode_association.rs
@@ -291,6 +291,7 @@ mod tests {
             opencode_locator: Some(StdArc::new(OpencodeLocator::new(data_home))),
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+            fresh_agent_respawn_counts: Default::default(),
         };
         (state, rx)
     }
diff --git a/crates/freshell-ws/src/reconcile.rs b/crates/freshell-ws/src/reconcile.rs
index b82eef02e..74a205f1f 100644
--- a/crates/freshell-ws/src/reconcile.rs
+++ b/crates/freshell-ws/src/reconcile.rs
@@ -29,6 +29,11 @@ pub struct ReconcileDeps<'a> {
     pub registry: &'a TerminalRegistry,
     pub identity: &'a TerminalIdentityRegistry,
     pub existence: &'a dyn SessionExistenceProbe,
+    /// Fresh-agent facts snapshot (campaign §4.3): `Some` only on a
+    /// connection that negotiated `paneReconcileFreshAgentV1` AND presented
+    /// fresh-agent panes; `None` keeps the frozen client's
+    /// `invalid{unsupported_kind}` contract.
+    pub fresh_agent: Option<&'a crate::reconcile_freshagent::FreshAgentReconcileSnapshot>,
 }
 
 /// Derive one verdict per presented pane, 1:1 by `paneKey`, order preserved
@@ -166,6 +171,9 @@ fn verdict_for_pane(deps: &ReconcileDeps<'_>, pane: &ReconcilePane) -> PaneVerdi
     }
     match pane.kind.as_deref() {
         Some("terminal") => {}
+        Some("fresh-agent") => {
+            return crate::reconcile_freshagent::verdict_for_pane(deps.fresh_agent, pane)
+        }
         Some(_) => return invalid(pane, "unsupported_kind"),
         None => return invalid(pane, "missing_kind"),
     }
@@ -328,6 +336,7 @@ mod tests {
                 registry: &self.registry,
                 identity: &self.identity,
                 existence: &self.probe,
+                fresh_agent: None,
             }
         }
 
@@ -543,7 +552,7 @@ mod tests {
         assert_eq!(v.reason.as_deref(), Some("missing_create_request_id"));
 
         let mut bad_kind = pane("cr-10c");
-        bad_kind.kind = Some("fresh-agent".to_string());
+        bad_kind.kind = Some("browser".to_string());
         let v = f.one(bad_kind);
         assert_eq!(v.verdict, ReconcileVerdict::Invalid);
         assert_eq!(v.reason.as_deref(), Some("unsupported_kind"));
diff --git a/crates/freshell-ws/src/reconcile_freshagent.rs b/crates/freshell-ws/src/reconcile_freshagent.rs
index 560be8096..fa19041c3 100644
--- a/crates/freshell-ws/src/reconcile_freshagent.rs
+++ b/crates/freshell-ws/src/reconcile_freshagent.rs
@@ -49,6 +49,138 @@ pub struct FreshAgentReconcileSnapshot {
     pub facts: std::collections::HashMap<String /* paneKey */, FreshAgentPaneFacts>,
 }
 
+/// The ONE async gathering pass per reconcile request (Task 13): session-map
+/// liveness, disk existence, ledger supersession resolution, in-request
+/// dedupe, and the respawn cap all condense into per-pane facts here, so
+/// [`verdict_for_pane`] stays pure + sync inside derive_verdicts'
+/// catch_unwind. Built ONCE per request and REUSED if deps are re-derived —
+/// rebuilding would double-burn the respawn counter.
+///
+/// Respawn-cap rationale (V2/A7): the terminal donor counts actual process
+/// exits within a liveness window and RESETS on survival
+/// (`registry.rs:1271-1283`) — per-answer burning without decay would let 3
+/// reloads kill a healthy session. Counting respawn ANSWERS with
+/// reset-on-live means only a genuinely non-recovering loop trips the cap.
+/// Residual A19 (accepted): the next-wave client's reconcile cadence is
+/// unpinned — REVISIT the cap value/semantics when that client lands.
+pub async fn build_snapshot(
+    state: &crate::WsState,
+    panes: &[ReconcilePane],
+) -> FreshAgentReconcileSnapshot {
+    let mut facts = std::collections::HashMap::new();
+    let mut claimed: std::collections::HashMap<(String, String), String> =
+        std::collections::HashMap::new();
+    for pane in panes
+        .iter()
+        .filter(|p| p.kind.as_deref() == Some("fresh-agent"))
+    {
+        let Some(sref) = pane.session_ref.as_ref() else {
+            continue; // verdict fn answers no_recoverable_identity
+        };
+        // G3 reader rule (V8/A14): resolve the CLAIM through the ledger's
+        // supersession chain FIRST — dedupe, liveness, existence, and the
+        // respawn counter all key on the TERMINUS id (lookup_by_session is
+        // public + memory-only).
+        let resolved = state
+            .pane_ledger
+            .lookup_by_session(&sref.provider, &sref.session_id)
+            .filter(|r| r.corrected)
+            .map(|r| r.row.session_id);
+        let session_id = resolved.clone().unwrap_or_else(|| sref.session_id.clone());
+        let key = (sref.provider.clone(), session_id.clone());
+        if let Some(winner) = claimed.get(&key) {
+            facts.insert(
+                pane.pane_key.clone(),
+                FreshAgentPaneFacts {
+                    presence: FreshAgentPresence::Unknown,
+                    duplicate_of: Some(winner.clone()),
+                    respawn_exhausted: false,
+                    resolved_session_id: resolved,
+                },
+            );
+            continue;
+        }
+        claimed.insert(key.clone(), pane.pane_key.clone());
+        let live = match sref.provider.as_str() {
+            "codex" => state.fresh_codex.has_live_session(&session_id).await,
+            "claude" => state.fresh_claude.has_live_session(&session_id).await,
+            "opencode" => state.fresh_opencode.has_live_session(&session_id).await,
+            _ => false,
+        };
+        use crate::existence::SessionExistence as E;
+        let presence = if live {
+            FreshAgentPresence::Live
+        } else {
+            // Exhaustive match, NO catch-all (B1 hardening: when B1 adds
+            // E::ProviderUnavailable this goes non-exhaustive — add the
+            // pre-decided arm `E::ProviderUnavailable => FreshAgentPresence::Unknown`).
+            match state.session_existence.exists(&sref.provider, &session_id) {
+                E::Present => FreshAgentPresence::OnDisk,
+                E::Absent => {
+                    if state
+                        .session_existence
+                        .ever_observed(&sref.provider, &session_id)
+                    {
+                        FreshAgentPresence::GoneObserved
+                    } else {
+                        FreshAgentPresence::NeverObserved
+                    }
+                }
+                E::Unknown => {
+                    // The ledger is positive evidence the session existed.
+                    if state.pane_ledger.ever_bound(&sref.provider, &session_id) {
+                        FreshAgentPresence::OnDisk
+                    } else {
+                        FreshAgentPresence::Unknown
+                    }
+                }
+            }
+        };
+        // Respawn cap (V2/A7 — reworked): count only answers that actually
+        // come back `respawn`, and CLEAR the counter when presence resolves
+        // Live (a successful respawn is OBSERVED as the session going live).
+        // The counting lives HERE because for non-duplicate panes the verdict
+        // is fully determined by presence: OnDisk/Unknown + !exhausted ⇒
+        // respawn (see verdict_for_pane) — so "this answer will be respawn"
+        // is known at increment time. Mutation stays in this async builder,
+        // OUTSIDE derive_verdicts' catch_unwind.
+        let respawn_exhausted = match presence {
+            FreshAgentPresence::Live => {
+                state
+                    .fresh_agent_respawn_counts
+                    .lock()
+                    .expect("respawn counts poisoned")
+                    .remove(&key); // reset-on-live
+                false
+            }
+            FreshAgentPresence::OnDisk | FreshAgentPresence::Unknown => {
+                let mut counts = state
+                    .fresh_agent_respawn_counts
+                    .lock()
+                    .expect("respawn counts poisoned");
+                let c = counts.entry(key).or_insert(0);
+                if *c >= FRESH_AGENT_RESPAWN_CAP {
+                    true // this answer becomes dead_session{respawn_exhausted}; no burn
+                } else {
+                    *c += 1; // this answer goes out as `respawn` — burn one
+                    false
+                }
+            }
+            FreshAgentPresence::GoneObserved | FreshAgentPresence::NeverObserved => false,
+        };
+        facts.insert(
+            pane.pane_key.clone(),
+            FreshAgentPaneFacts {
+                presence,
+                duplicate_of: None,
+                respawn_exhausted,
+                resolved_session_id: resolved,
+            },
+        );
+    }
+    FreshAgentReconcileSnapshot { facts }
+}
+
 /// The SINGLE PaneVerdict construction point in this module (B1-coexistence
 /// hardening, V9/A12 — keep it that way).
 fn base(pane: &ReconcilePane, verdict: ReconcileVerdict) -> PaneVerdict {
diff --git a/crates/freshell-ws/src/terminal.rs b/crates/freshell-ws/src/terminal.rs
index bec22102a..984a84ae5 100644
--- a/crates/freshell-ws/src/terminal.rs
+++ b/crates/freshell-ws/src/terminal.rs
@@ -1906,20 +1906,21 @@ pub fn broadcast_sessions_changed(state: &WsState) {
 
 /// Send the reference's `sendError` frame for a failed `terminal.create`
 /// (`ws-handler.ts:2606-2614`): `{ code, message, requestId }`.
-/// `pane.reconcile.request` (reconciliation design §5): a PURE READ over the
-/// terminal registry × identity registry × disk index — one verdict per
-/// presented pane. Safe to receive N times on N sockets (§7); the only error
-/// paths are the explicit `RECONCILE_TOO_LARGE` cap and the
+/// `pane.reconcile.request` (reconciliation design §5): the terminal sources
+/// remain a PURE READ over the terminal registry × identity registry × disk
+/// index — one verdict per presented pane, safe to receive N times on N
+/// sockets (§7). The capability-gated fresh-agent snapshot is the ONE
+/// exception: it mutates the per-boot respawn counter
+/// (`WsState.fresh_agent_respawn_counts`, bounded per `(provider,
+/// sessionId)`; reset when the session resolves Live — V2/A7). The only
+/// error paths are the explicit `RECONCILE_TOO_LARGE` cap and the
 /// `RECONCILE_UNAVAILABLE` derivation-failure frame, both carrying the
 /// `reconcileId` for correlation.
 async fn handle_pane_reconcile(
     request: freshell_protocol::PaneReconcileRequest,
     ws_tx: &mut WsSink,
     state: &WsState,
-    // `paneReconcileFreshAgentV1` negotiation: threaded here in Task 11,
-    // consumed by the fresh-agent verdict derivation in Task 13 (underscore
-    // prefix drops then).
-    _pane_reconcile_fresh_agent_v1: bool,
+    pane_reconcile_fresh_agent_v1: bool,
 ) -> bool {
     if request.panes.len() > crate::reconcile::MAX_RECONCILE_PANES {
         return send_create_error(
@@ -1934,10 +1935,24 @@ async fn handle_pane_reconcile(
         )
         .await;
     }
+    // Built ONCE per reconcile request and reused for any re-derivation of deps
+    // (B1's warming deferral re-derives via rebuild_deps — rebuilding the
+    // snapshot would double-burn the respawn counter; V9 §3.6).
+    let fresh_agent_snapshot = if pane_reconcile_fresh_agent_v1
+        && request
+            .panes
+            .iter()
+            .any(|p| p.kind.as_deref() == Some("fresh-agent"))
+    {
+        Some(crate::reconcile_freshagent::build_snapshot(state, &request.panes).await)
+    } else {
+        None
+    };
     let deps = crate::reconcile::ReconcileDeps {
         registry: &state.registry,
         identity: &state.identity,
         existence: state.session_existence.as_ref(),
+        fresh_agent: fresh_agent_snapshot.as_ref(),
     };
     // §8 frame-level failure: a panicking derivation (poisoned lock) must
     // surface as an explicit error frame, never silence.
@@ -3203,6 +3218,7 @@ mod terminals_changed_tests {
             opencode_locator: None,
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+            fresh_agent_respawn_counts: Default::default(),
         };
         (state, rx)
     }
@@ -3410,6 +3426,7 @@ mod terminal_meta_created_tests {
             opencode_locator: None,
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+            fresh_agent_respawn_counts: Default::default(),
         };
         (state, rx)
     }
diff --git a/crates/freshell-ws/tests/codex_managed_launch_e2e.rs b/crates/freshell-ws/tests/codex_managed_launch_e2e.rs
index 3c87985f9..d517b72c3 100644
--- a/crates/freshell-ws/tests/codex_managed_launch_e2e.rs
+++ b/crates/freshell-ws/tests/codex_managed_launch_e2e.rs
@@ -155,6 +155,7 @@ async fn spawn_server() -> (String, freshell_terminal::TerminalRegistry) {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/codex_session_ref_resume.rs b/crates/freshell-ws/tests/codex_session_ref_resume.rs
index 57bc9d155..2442fa6a5 100644
--- a/crates/freshell-ws/tests/codex_session_ref_resume.rs
+++ b/crates/freshell-ws/tests/codex_session_ref_resume.rs
@@ -148,6 +148,7 @@ async fn spawn_server() -> (String, freshell_terminal::TerminalRegistry) {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/common/mod.rs b/crates/freshell-ws/tests/common/mod.rs
index 778e734e1..277689672 100644
--- a/crates/freshell-ws/tests/common/mod.rs
+++ b/crates/freshell-ws/tests/common/mod.rs
@@ -136,6 +136,7 @@ pub async fn spawn_server_with_specs(
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
@@ -216,6 +217,7 @@ pub async fn spawn_server_with_ledger(
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
@@ -292,6 +294,7 @@ pub async fn spawn_server_with_specs_and_activity(
         opencode_locator: None,
         activity: Some(activity_hub.clone()),
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
@@ -357,6 +360,7 @@ pub async fn spawn_server_with_create_protect(
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/diag01_lifecycle_events.rs b/crates/freshell-ws/tests/diag01_lifecycle_events.rs
index 912db6baf..65375db4e 100644
--- a/crates/freshell-ws/tests/diag01_lifecycle_events.rs
+++ b/crates/freshell-ws/tests/diag01_lifecycle_events.rs
@@ -172,6 +172,7 @@ async fn spawn_server(ping_interval_ms: u64) -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/freshagent_claude_attach.rs b/crates/freshell-ws/tests/freshagent_claude_attach.rs
index 6014b3f3b..48bb618df 100644
--- a/crates/freshell-ws/tests/freshagent_claude_attach.rs
+++ b/crates/freshell-ws/tests/freshagent_claude_attach.rs
@@ -176,6 +176,7 @@ async fn spawn_server() -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs b/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs
index df44c89ef..357cea544 100644
--- a/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs
+++ b/crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs
@@ -207,6 +207,7 @@ async fn spawn_server() -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/hello_timeout.rs b/crates/freshell-ws/tests/hello_timeout.rs
index c3d08eec0..f08727fca 100644
--- a/crates/freshell-ws/tests/hello_timeout.rs
+++ b/crates/freshell-ws/tests/hello_timeout.rs
@@ -92,6 +92,7 @@ async fn spawn_server(hello_timeout_ms: u64) -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/keepalive.rs b/crates/freshell-ws/tests/keepalive.rs
index 37132e772..906f94a77 100644
--- a/crates/freshell-ws/tests/keepalive.rs
+++ b/crates/freshell-ws/tests/keepalive.rs
@@ -93,6 +93,7 @@ async fn spawn_server(
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/max_payload.rs b/crates/freshell-ws/tests/max_payload.rs
index aa9a0b06c..f50cb092b 100644
--- a/crates/freshell-ws/tests/max_payload.rs
+++ b/crates/freshell-ws/tests/max_payload.rs
@@ -93,6 +93,7 @@ async fn spawn_server(ws_max_payload_bytes: usize) -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/origin_policy.rs b/crates/freshell-ws/tests/origin_policy.rs
index b8f197f4f..0d5519f39 100644
--- a/crates/freshell-ws/tests/origin_policy.rs
+++ b/crates/freshell-ws/tests/origin_policy.rs
@@ -83,6 +83,7 @@ async fn spawn_server(allowed_origins: Vec<String>) -> (String, String) {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/pane_reconcile.rs b/crates/freshell-ws/tests/pane_reconcile.rs
index c1db5b723..ae73baf0b 100644
--- a/crates/freshell-ws/tests/pane_reconcile.rs
+++ b/crates/freshell-ws/tests/pane_reconcile.rs
@@ -107,6 +107,7 @@ async fn spawn_server() -> Server {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/pane_reconcile_freshagent.rs b/crates/freshell-ws/tests/pane_reconcile_freshagent.rs
index 39c43d880..b5fb99daa 100644
--- a/crates/freshell-ws/tests/pane_reconcile_freshagent.rs
+++ b/crates/freshell-ws/tests/pane_reconcile_freshagent.rs
@@ -1,35 +1,153 @@
-//! `paneReconcileFreshAgentV1` capability wire tests — raw-WS
-//! (tokio-tungstenite) integration against an in-process axum server, on the
-//! `pane_reconcile.rs` harness convention (ephemeral loopback ports, never a
-//! fixed one).
+//! `paneReconcileFreshAgentV1` capability + verdict-derivation wire tests —
+//! raw-WS (tokio-tungstenite) integration against an in-process axum server,
+//! on the `pane_reconcile.rs` harness convention (ephemeral loopback ports,
+//! never a fixed one).
 //!
-//! Covered here (Task 11 — capability negotiation only):
+//! Covered here:
 //! * negotiation — `hello.capabilities.paneReconcileFreshAgentV1` → echoed in
 //!   `ready.capabilities` (typed `ReadyCapabilities`, omitted when absent).
 //! * frozen-client protection — a connection WITHOUT the capability keeps the
 //!   pre-existing verdict for `kind: "fresh-agent"`: `invalid` /
 //!   `unsupported_kind` (the permanent regression guard).
-//!
-//! Task 13 extends this file with the fresh-agent verdict derivation tests.
+//! * Task 13 — fresh-agent verdict derivation: the four states, live→attach,
+//!   in-request dedupe, the respawn cap + reset-on-live, and the G3
+//!   supersession-chain reader rule end-to-end through the real ledger.
 
-use std::sync::Arc;
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
 use futures_util::{SinkExt, StreamExt};
+use serde_json::Value;
 use tokio::net::TcpListener;
 use tokio_tungstenite::tungstenite::Message as WsMessage;
 
+use freshell_ws::existence::SessionExistence;
+use freshell_ws::pane_ledger::{FreshAgentBindingWrite, PaneLedger};
 use freshell_ws::WsState;
 
 const AUTH_TOKEN: &str = "s3cr3t-token-abcdef";
 
+/// Serializes every test in this file that mutates the process-global
+/// `FRESHELL_CLAUDE_SIDECAR` / `FRESHELL_CLAUDE_NODE` / `CLAUDE_CONFIG_DIR`
+/// env vars, mirroring `freshagent_claude_attach.rs`'s convention for the
+/// same hazard.
+static CLAUDE_ENV_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
+// ── scripted disk-truth probe ─────────────────────────────────────────────────
+
+#[derive(Default)]
+struct StubProbe {
+    answers: std::sync::Mutex<std::collections::HashMap<(String, String), SessionExistence>>,
+    observed: std::sync::Mutex<std::collections::HashSet<(String, String)>>,
+}
+impl freshell_ws::existence::SessionExistenceProbe for StubProbe {
+    fn exists(&self, provider: &str, session_id: &str) -> SessionExistence {
+        self.answers
+            .lock()
+            .unwrap()
+            .get(&(provider.into(), session_id.into()))
+            .copied()
+            .unwrap_or(SessionExistence::Unknown)
+    }
+    fn ever_observed(&self, provider: &str, session_id: &str) -> bool {
+        self.observed
+            .lock()
+            .unwrap()
+            .contains(&(provider.into(), session_id.into()))
+    }
+}
+
+// ── fake claude sidecar (donor: freshagent_claude_attach.rs) ──────────────────
+
+/// A minimal scripted fake claude sidecar (no real SDK, no network, no cost)
+/// speaking the SAME newline-JSON protocol `spawn_sidecar()` drives the
+/// vendored package with. On `create` it replies `created`, then
+/// `sdk.session.init` echoing `resumeSessionId` (or a fixed durable UUID the
+/// tests control) as the durable `cliSessionId`, then `sdk.status idle`; on
+/// `shutdown` it exits.
+const FAKE_CLAUDE_SIDECAR_SOURCE: &str = r#"
+import readline from 'node:readline'
+
+let counter = 0
+const rl = readline.createInterface({ input: process.stdin, terminal: false })
+rl.on('line', (line) => {
+  const trimmed = line.trim()
+  if (!trimmed) return
+  let msg
+  try {
+    msg = JSON.parse(trimmed)
+  } catch {
+    return
+  }
+  if (msg.type === 'create') {
+    counter += 1
+    const sessionId = `fake-claude-session-${process.pid}-${counter}`
+    process.stdout.write(JSON.stringify({ type: 'created', requestId: msg.requestId, sessionId }) + '\n')
+    const cliSessionId = msg.resumeSessionId || 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+    process.stdout.write(JSON.stringify({ type: 'sdk.session.init', sessionId, cliSessionId, model: 'fake-model', cwd: '/tmp', tools: [] }) + '\n')
+    process.stdout.write(JSON.stringify({ type: 'sdk.status', sessionId, status: 'idle' }) + '\n')
+  } else if (msg.type === 'shutdown') {
+    process.exit(0)
+  }
+})
+"#;
+
+/// The fixed durable `cliSessionId` the fake sidecar mints on a plain (non
+/// resume) `create` — the id the live-session tests key their probe on.
+const FAKE_DURABLE_ID: &str = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa";
+
+/// A fresh temp dir holding the fake sidecar script, with
+/// `FRESHELL_CLAUDE_SIDECAR`/`FRESHELL_CLAUDE_NODE` pointed at it, PLUS an
+/// empty claude store with `CLAUDE_CONFIG_DIR` pointed at it (so no test ever
+/// touches the real home). Caller must hold [`CLAUDE_ENV_LOCK`] for the
+/// lifetime of the returned guard.
+struct FakeClaudeEnv {
+    dir: std::path::PathBuf,
+}
+impl FakeClaudeEnv {
+    fn install() -> Self {
+        let dir = std::env::temp_dir().join(format!(
+            "freshell-fake-claude-reconcile-ws-{}",
+            uuid_like_suffix()
+        ));
+        std::fs::create_dir_all(&dir).expect("create fake sidecar temp dir");
+        let script = dir.join("fake-claude-sidecar.mjs");
+        std::fs::write(&script, FAKE_CLAUDE_SIDECAR_SOURCE).expect("write fake sidecar");
+        let store = dir.join("claude-store");
+        std::fs::create_dir_all(&store).expect("create claude store dir");
+        std::env::set_var("FRESHELL_CLAUDE_SIDECAR", &script);
+        std::env::set_var("FRESHELL_CLAUDE_NODE", "node");
+        std::env::set_var("CLAUDE_CONFIG_DIR", &store);
+        Self { dir }
+    }
+}
+impl Drop for FakeClaudeEnv {
+    fn drop(&mut self) {
+        std::env::remove_var("FRESHELL_CLAUDE_SIDECAR");
+        std::env::remove_var("FRESHELL_CLAUDE_NODE");
+        std::env::remove_var("CLAUDE_CONFIG_DIR");
+        let _ = std::fs::remove_dir_all(&self.dir);
+    }
+}
+
+/// Dependency-free unique suffix (avoids pulling in `uuid` for this test crate).
+fn uuid_like_suffix() -> String {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    let nanos = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_nanos();
+    format!("{nanos}-{:?}", std::thread::current().id())
+}
+
 fn test_settings_value() -> serde_json::Value {
     serde_json::json!({
         "ai": {},
         "codingCli": { "enabledProviders": [], "mcpServer": true, "providers": {} },
         "editor": { "externalEditor": "auto" },
         "extensions": { "disabled": [] },
-        "freshAgent": { "defaultPlugins": [], "enabled": false, "providers": {} },
+        "freshAgent": { "defaultPlugins": [], "enabled": true, "providers": {} },
         "logging": { "debug": false },
         "network": { "configured": true, "host": "127.0.0.1" },
         "panes": { "defaultNewPane": "ask" },
@@ -45,27 +163,41 @@ fn test_settings_value() -> serde_json::Value {
 
 struct Server {
     url: String,
-    // Shared-registry handles, donor-shaped: Task 13's derivation tests seed
-    // generations through these; Task 11's negotiation tests don't need to.
+    // Shared-registry handles, donor-shaped: derivation tests seed state
+    // through these; the negotiation tests don't need to.
     #[allow(dead_code)]
     registry: freshell_terminal::TerminalRegistry,
     #[allow(dead_code)]
     identity: freshell_ws::identity::TerminalIdentityRegistry,
+    /// The REAL temp-root ledger shared with the server (G3 tests seed it).
+    pane_ledger: Arc<PaneLedger>,
+    /// Clone of `WsState.fresh_agent_respawn_counts` for direct assertions.
+    respawn_counts: Arc<Mutex<HashMap<(String, String), u32>>>,
+    /// Keeps the ledger's temp root alive for the server's lifetime.
+    #[allow(dead_code)]
+    ledger_root: tempfile::TempDir,
 }
 
-/// Real axum server on an ephemeral loopback port. Returns handles to the
-/// SHARED registry + identity registry so tests can seed generations
-/// deterministically (the §9.1 headless convention).
-async fn spawn_server() -> Server {
+/// Real axum server on an ephemeral loopback port, with the scripted
+/// disk-truth probe + a REAL temp-root pane ledger injected via the pub
+/// `WsState` fields. Returns handles to the SHARED registries/ledger/counter
+/// so tests can seed and assert deterministically (the §9.1 headless
+/// convention).
+async fn spawn_server_with_probe(probe: Arc<StubProbe>) -> Server {
     let auth_token = Arc::new(AUTH_TOKEN.to_string());
     let broadcast_tx = Arc::new(tokio::sync::broadcast::channel::<String>(64).0);
     let settings =
         Arc::new(serde_json::from_value(test_settings_value()).expect("valid settings fixture"));
     let registry = freshell_terminal::TerminalRegistry::new();
     let identity = freshell_ws::identity::TerminalIdentityRegistry::new();
+    let ledger_root = tempfile::tempdir().expect("ledger temp root");
+    let pane_ledger = Arc::new(PaneLedger::new_locked(Some(
+        ledger_root.path().to_path_buf(),
+    )));
+    let respawn_counts: Arc<Mutex<HashMap<(String, String), u32>>> = Arc::default();
 
     let state = WsState {
-        pane_ledger: std::sync::Arc::new(freshell_ws::pane_ledger::PaneLedger::disabled()),
+        pane_ledger: Arc::clone(&pane_ledger),
         identity: identity.clone(),
         auth_token: Arc::clone(&auth_token),
         server_instance_id: Arc::new("srv-test".to_string()),
@@ -75,7 +207,7 @@ async fn spawn_server() -> Server {
         fresh_codex: freshell_freshagent::FreshCodexState::new(
             Arc::clone(&auth_token),
             Arc::clone(&broadcast_tx),
-            serde_json::json!({ "freshAgent": { "enabled": false } }),
+            serde_json::json!({ "freshAgent": { "enabled": true } }),
         ),
         fresh_claude: freshell_freshagent::FreshClaudeState::new(Arc::clone(&broadcast_tx)),
         fresh_opencode: freshell_freshagent::FreshOpencodeState::new(
@@ -102,7 +234,8 @@ async fn spawn_server() -> Server {
         amplifier_locator: None,
         opencode_locator: None,
         activity: None,
-        session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        session_existence: probe,
+        fresh_agent_respawn_counts: Arc::clone(&respawn_counts),
     };
 
     let router = freshell_ws::router(state);
@@ -118,9 +251,16 @@ async fn spawn_server() -> Server {
         url: format!("ws://{addr}/ws"),
         registry,
         identity,
+        pane_ledger,
+        respawn_counts,
+        ledger_root,
     }
 }
 
+async fn spawn_server() -> Server {
+    spawn_server_with_probe(Arc::new(StubProbe::default())).await
+}
+
 type TestWs =
     tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>;
 
@@ -201,6 +341,56 @@ async fn reconcile_request(ws: &mut TestWs, panes: serde_json::Value) -> serde_j
     result["verdicts"].clone()
 }
 
+/// Drain frames until one matching `predicate` arrives (or the budget expires).
+async fn await_frame(
+    ws: &mut TestWs,
+    budget: Duration,
+    predicate: impl Fn(&Value) -> bool,
+) -> Value {
+    tokio::time::timeout(budget, async {
+        loop {
+            let msg = ws
+                .next()
+                .await
+                .expect("stream not ended")
+                .expect("no ws error");
+            let WsMessage::Text(text) = msg else {
+                continue;
+            };
+            let value: Value = serde_json::from_str(&text).unwrap();
+            if predicate(&value) {
+                return value;
+            }
+        }
+    })
+    .await
+    .expect("expected frame did not arrive within budget")
+}
+
+/// Drive a claude `freshAgent.create` through the fake sidecar and return the
+/// durable `cliSessionId` from the `freshAgent.session.init` event.
+async fn create_live_claude_session(ws: &mut TestWs, request_id: &str) -> String {
+    ws.send(WsMessage::Text(
+        serde_json::json!({
+            "type": "freshAgent.create",
+            "requestId": request_id,
+            "sessionType": "freshclaude",
+            "provider": "claude",
+        })
+        .to_string(),
+    ))
+    .await
+    .expect("send freshAgent.create");
+    let init = await_frame(ws, Duration::from_secs(15), |v| {
+        v["type"] == "freshAgent.event" && v["event"]["type"] == "freshAgent.session.init"
+    })
+    .await;
+    init["event"]["cliSessionId"]
+        .as_str()
+        .expect("session.init carries the durable cliSessionId")
+        .to_string()
+}
+
 // --- negotiation ---------------------------------------------------------------
 
 #[tokio::test]
@@ -230,3 +420,258 @@ async fn without_the_capability_fresh_agent_kind_stays_invalid_unsupported() {
     assert_eq!(verdicts[0]["verdict"], "invalid");
     assert_eq!(verdicts[0]["reason"], "unsupported_kind");
 }
+
+// --- Task 13: fresh-agent verdict derivation -------------------------------------
+
+#[tokio::test]
+async fn fresh_agent_verdicts_cover_the_four_states() {
+    let probe = std::sync::Arc::new(StubProbe::default());
+    probe.answers.lock().unwrap().insert(
+        ("codex".into(), "resumable".into()),
+        SessionExistence::Present,
+    );
+    probe.answers.lock().unwrap().insert(
+        ("claude".into(), "deleted".into()),
+        SessionExistence::Absent,
+    );
+    probe
+        .observed
+        .lock()
+        .unwrap()
+        .insert(("claude".into(), "deleted".into()));
+    probe.answers.lock().unwrap().insert(
+        ("opencode".into(), "never".into()),
+        SessionExistence::Absent,
+    );
+    let server = spawn_server_with_probe(probe).await;
+    let (mut ws, _ready) = connect(&server.url, true, true).await;
+    let verdicts = reconcile_request(
+        &mut ws,
+        serde_json::json!([
+            { "paneKey": "a", "kind": "fresh-agent", "sessionRef": {"provider": "codex", "sessionId": "resumable"} },
+            { "paneKey": "b", "kind": "fresh-agent", "sessionRef": {"provider": "claude", "sessionId": "deleted"} },
+            { "paneKey": "c", "kind": "fresh-agent", "sessionRef": {"provider": "opencode", "sessionId": "never"} },
+            { "paneKey": "d", "kind": "fresh-agent" },
+            { "paneKey": "t", "kind": "terminal", "mode": "shell", "createRequestId": "cr-t" }
+        ]),
+    )
+    .await;
+    assert_eq!(
+        verdicts[0]["verdict"], "respawn",
+        "killed-server-but-resumable"
+    );
+    assert_eq!(verdicts[0]["sessionRef"]["sessionId"], "resumable");
+    assert_eq!(verdicts[1]["verdict"], "dead_session", "transcript deleted");
+    assert_eq!(verdicts[1]["reason"], "session_not_on_disk");
+    assert_eq!(verdicts[2]["verdict"], "fresh", "never existed");
+    assert_eq!(verdicts[2]["reason"], "identity_never_observed");
+    assert_eq!(verdicts[3]["verdict"], "fresh");
+    assert_eq!(verdicts[3]["reason"], "no_recoverable_identity");
+    // Terminal panes in the same request still work (mixed-kind request):
+    assert_eq!(verdicts[4]["paneKey"], "t");
+    assert_eq!(
+        verdicts[4]["verdict"], "fresh",
+        "shell terminal answered normally"
+    );
+}
+
+#[tokio::test]
+async fn live_fresh_agent_session_gets_attach() {
+    let _guard = CLAUDE_ENV_LOCK.lock().await;
+    let _env = FakeClaudeEnv::install();
+
+    let server = spawn_server().await;
+    let (mut ws, _ready) = connect(&server.url, true, true).await;
+
+    let cli_session_id = create_live_claude_session(&mut ws, "req-live-attach").await;
+    assert_eq!(cli_session_id, FAKE_DURABLE_ID);
+
+    let verdicts = reconcile_request(
+        &mut ws,
+        serde_json::json!([
+            { "paneKey": "live", "kind": "fresh-agent",
+              "sessionRef": {"provider": "claude", "sessionId": cli_session_id} }
+        ]),
+    )
+    .await;
+    assert_eq!(verdicts[0]["verdict"], "attach");
+    assert_eq!(verdicts[0]["sessionRef"]["sessionId"], cli_session_id);
+    assert!(verdicts[0].get("terminalId").is_none());
+}
+
+#[tokio::test]
+async fn duplicate_session_claims_dedupe_within_one_request() {
+    let probe = std::sync::Arc::new(StubProbe::default());
+    probe
+        .answers
+        .lock()
+        .unwrap()
+        .insert(("codex".into(), "t1".into()), SessionExistence::Present);
+    let server = spawn_server_with_probe(probe).await;
+    let (mut ws, _ready) = connect(&server.url, true, true).await;
+    let verdicts = reconcile_request(
+        &mut ws,
+        serde_json::json!([
+            { "paneKey": "first",  "kind": "fresh-agent", "sessionRef": {"provider": "codex", "sessionId": "t1"} },
+            { "paneKey": "second", "kind": "fresh-agent", "sessionRef": {"provider": "codex", "sessionId": "t1"} }
+        ]),
+    )
+    .await;
+    assert_eq!(verdicts[0]["verdict"], "respawn");
+    assert_eq!(verdicts[1]["verdict"], "fresh");
+    assert_eq!(verdicts[1]["reason"], "duplicate_session_claim");
+    assert_eq!(verdicts[1]["duplicate"], "first");
+}
+
+#[tokio::test]
+async fn respawn_cap_turns_the_fourth_answer_into_dead_session() {
+    // The session stays Present-but-never-live, so every answer maps to
+    // respawn; only RESPAWN ANSWERS burn the cap (V2/A7).
+    let probe = std::sync::Arc::new(StubProbe::default());
+    probe
+        .answers
+        .lock()
+        .unwrap()
+        .insert(("codex".into(), "cap".into()), SessionExistence::Present);
+    let server = spawn_server_with_probe(probe).await;
+    let (mut ws, _ready) = connect(&server.url, true, true).await;
+    for i in 0..4 {
+        let verdicts = reconcile_request(
+            &mut ws,
+            serde_json::json!([
+                { "paneKey": "p", "kind": "fresh-agent", "sessionRef": {"provider": "codex", "sessionId": "cap"} }
+            ]),
+        )
+        .await;
+        if i < 3 {
+            assert_eq!(verdicts[0]["verdict"], "respawn", "answer {i}");
+        } else {
+            assert_eq!(verdicts[0]["verdict"], "dead_session");
+            assert_eq!(verdicts[0]["reason"], "respawn_exhausted");
+        }
+    }
+}
+
+#[tokio::test]
+async fn a_session_resolving_live_clears_the_respawn_counter() {
+    // Reset-on-live (V2/A7): a successful respawn is OBSERVED as the session
+    // going live; the counter must clear so healthy sessions are never
+    // exhausted by reconnect/reload storms.
+    let _guard = CLAUDE_ENV_LOCK.lock().await;
+    let _env = FakeClaudeEnv::install();
+
+    let probe = std::sync::Arc::new(StubProbe::default());
+    probe.answers.lock().unwrap().insert(
+        ("claude".into(), FAKE_DURABLE_ID.into()),
+        SessionExistence::Present,
+    );
+    let server = spawn_server_with_probe(probe).await;
+    let (mut ws, _ready) = connect(&server.url, true, true).await;
+
+    // TWO reconcile requests while the session is NOT yet live → both respawn.
+    for i in 0..2 {
+        let verdicts = reconcile_request(
+            &mut ws,
+            serde_json::json!([
+                { "paneKey": "p", "kind": "fresh-agent",
+                  "sessionRef": {"provider": "claude", "sessionId": FAKE_DURABLE_ID} }
+            ]),
+        )
+        .await;
+        assert_eq!(verdicts[0]["verdict"], "respawn", "pre-live answer {i}");
+    }
+    assert_eq!(
+        server
+            .respawn_counts
+            .lock()
+            .unwrap()
+            .get(&("claude".to_string(), FAKE_DURABLE_ID.to_string()))
+            .copied(),
+        Some(2),
+        "two respawn answers burned two"
+    );
+
+    // Drive freshAgent.create through the fake sidecar so has_live_session
+    // becomes true for the durable id.
+    let cli_session_id = create_live_claude_session(&mut ws, "req-reset-on-live").await;
+    assert_eq!(cli_session_id, FAKE_DURABLE_ID);
+
+    let verdicts = reconcile_request(
+        &mut ws,
+        serde_json::json!([
+            { "paneKey": "p", "kind": "fresh-agent",
+              "sessionRef": {"provider": "claude", "sessionId": FAKE_DURABLE_ID} }
+        ]),
+    )
+    .await;
+    assert_eq!(verdicts[0]["verdict"], "attach");
+    assert!(
+        !server
+            .respawn_counts
+            .lock()
+            .unwrap()
+            .contains_key(&("claude".to_string(), FAKE_DURABLE_ID.to_string())),
+        "counter cleared (not merely un-incremented) when presence resolved Live"
+    );
+}
+
+#[tokio::test]
+async fn old_thread_claim_after_crash_respawn_answers_the_new_terminus() {
+    // G3 reader rule end-to-end (V8/A14). Seed the REAL temp-root ledger.
+    let probe = std::sync::Arc::new(StubProbe::default());
+    // The old rollout may ALSO still exist on disk — the point is we never
+    // answer the retired ref.
+    probe
+        .answers
+        .lock()
+        .unwrap()
+        .insert(("codex".into(), "new-t".into()), SessionExistence::Present);
+    let server = spawn_server_with_probe(probe).await;
+    let now = 1_000;
+    server
+        .pane_ledger
+        .record_fresh_agent_binding(&FreshAgentBindingWrite {
+            provider: "codex",
+            session_id: "old-t",
+            mode: "freshcodex",
+            cwd: Some("/w"),
+            create_request_id: None,
+            model: Some("m"),
+            sandbox: None,
+            permission_mode: None,
+            effort: None,
+            supersedes: None,
+            now_ms: now,
+        })
+        .unwrap();
+    server
+        .pane_ledger
+        .record_fresh_agent_binding(&FreshAgentBindingWrite {
+            provider: "codex",
+            session_id: "new-t",
+            mode: "freshcodex",
+            cwd: Some("/w"),
+            create_request_id: None,
+            model: Some("m"),
+            sandbox: None,
+            permission_mode: None,
+            effort: None,
+            supersedes: Some("old-t"),
+            now_ms: now + 1,
+        })
+        .unwrap();
+    let (mut ws, _ready) = connect(&server.url, true, true).await;
+    let verdicts = reconcile_request(
+        &mut ws,
+        serde_json::json!([
+            { "paneKey": "p", "kind": "fresh-agent", "sessionRef": {"provider": "codex", "sessionId": "old-t"} }
+        ]),
+    )
+    .await;
+    assert_eq!(verdicts[0]["verdict"], "respawn");
+    assert_eq!(
+        verdicts[0]["sessionRef"]["sessionId"], "new-t",
+        "answer from the chain terminus"
+    );
+    assert_eq!(verdicts[0]["corrected"], true);
+}
diff --git a/crates/freshell-ws/tests/safe08_restore_diagnostics.rs b/crates/freshell-ws/tests/safe08_restore_diagnostics.rs
index c0a949981..e07122875 100644
--- a/crates/freshell-ws/tests/safe08_restore_diagnostics.rs
+++ b/crates/freshell-ws/tests/safe08_restore_diagnostics.rs
@@ -179,6 +179,7 @@ async fn spawn_server() -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
diff --git a/crates/freshell-ws/tests/term09_output_queue.rs b/crates/freshell-ws/tests/term09_output_queue.rs
index 9edcedb52..50c372e93 100644
--- a/crates/freshell-ws/tests/term09_output_queue.rs
+++ b/crates/freshell-ws/tests/term09_output_queue.rs
@@ -86,6 +86,7 @@ async fn spawn_server(term09: Term09Config) -> String {
         opencode_locator: None,
         activity: None,
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);

From 2ed6b948415697039be62f17234bcce8d7fd6b98 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 07:46:38 -0700
Subject: [PATCH 70/87] refactor(server): delete operator tabs-sync restore
 endpoint, write-ahead marker, and screenshot delivery fence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Kata h9vt disposition: Option A. The tabs-snapshots store is now load-bearing
via GET /api/recovery/inventory + the client recover-my-panes flow. The
server-push restore machinery (marker, one-browser gate, delivery fence,
scripts/restore-tabs.sh, parse_restore_selection) served only the blind
operator push and has no UI-flow consumer; the unreachable fence was flagged
for deletion in campaign P2.17. The GET snapshots read API, parse_selector,
and the broadcast screenshot broker survive (audit table in the plan);
deploy-tab-diff remediation now points at the UI recovery flow.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-server/src/main.rs            |    5 -
 crates/freshell-server/src/tabs_snapshots.rs  |  804 +---------
 .../src/tabs_snapshots_create_body.rs         |   89 --
 .../src/tabs_snapshots_marker.rs              |  538 -------
 .../src/tabs_snapshots_restore_tests.rs       | 1348 -----------------
 .../src/tabs_snapshots_selectors.rs           |  101 +-
 .../src/tabs_snapshots_tests.rs               |  784 +---------
 crates/freshell-ws/src/screenshot.rs          |  154 +-
 .../src/tabs_persist_validation_tests.rs      |    2 +-
 scripts/deploy-tab-diff.sh                    |   38 +-
 scripts/restore-tabs.sh                       |  121 --
 test/e2e-browser/playwright.config.ts         |    5 -
 .../specs/continuity-smoke.spec.ts            |    4 +-
 .../specs/deploy-tab-diff-rust.spec.ts        |  236 +--
 .../specs/recover-my-panes-rust.spec.ts       |    6 +-
 .../specs/snapshot-restore-rust.spec.ts       |  304 ----
 16 files changed, 70 insertions(+), 4469 deletions(-)
 delete mode 100644 crates/freshell-server/src/tabs_snapshots_create_body.rs
 delete mode 100644 crates/freshell-server/src/tabs_snapshots_marker.rs
 delete mode 100644 crates/freshell-server/src/tabs_snapshots_restore_tests.rs
 delete mode 100755 scripts/restore-tabs.sh
 delete mode 100644 test/e2e-browser/specs/snapshot-restore-rust.spec.ts

diff --git a/crates/freshell-server/src/main.rs b/crates/freshell-server/src/main.rs
index 0ae00e06a..a416bb724 100644
--- a/crates/freshell-server/src/main.rs
+++ b/crates/freshell-server/src/main.rs
@@ -788,11 +788,6 @@ async fn main() -> ExitCode {
             snapshots_dir: home
                 .as_ref()
                 .map(|h| h.join(".freshell").join("tabs-snapshots")),
-            fresh_agent: fresh_agent_state.clone(),
-            screenshots: screenshots.clone(),
-            terminals: registry.clone(), // the SAME TerminalRegistry from main.rs:246
-            restore_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
-            restore_ack_timeout: std::time::Duration::from_secs(5),
         }))
         // B3/P1.9 Task 2: the recovery-inventory read surface. Joins the SAME
         // tabs-snapshots store as `tabs_snapshots` above (read-only), the
diff --git a/crates/freshell-server/src/tabs_snapshots.rs b/crates/freshell-server/src/tabs_snapshots.rs
index 8556284f8..f28be92a2 100644
--- a/crates/freshell-server/src/tabs_snapshots.rs
+++ b/crates/freshell-server/src/tabs_snapshots.rs
@@ -1,10 +1,12 @@
 //! Tabs-sync snapshot REST surface (continuity trio,
 //! docs/plans/2026-07-22-continuity-safety-trio.md). PURELY ADDITIVE: the legacy
-//! server has no on-disk snapshot generations and no snapshot/restore routes, so
-//! this diverges from no ported behavior and gets no DEVIATIONS ledger entry.
-//! Read endpoints serve the generations `freshell_ws::tabs_persist` persists;
-//! POST /api/tabs-sync/restore (Task 3) rebuilds tabs by driving the SAME
-//! `POST /api/tabs` create pipeline.
+//! server has no on-disk snapshot generations, so this diverges from no ported
+//! behavior and gets no DEVIATIONS ledger entry.
+//! Read endpoints serve the generations `freshell_ws::tabs_persist` persists.
+//! The store's consumers are these GET endpoints (operator tooling, e.g.
+//! `scripts/deploy-tab-diff.sh`) and `GET /api/recovery/inventory` + the
+//! client recover-my-panes flow (the operator server-push restore endpoint
+//! was deleted in the kata h9vt cleanup).
 
 use std::path::PathBuf;
 use std::sync::Arc;
@@ -22,27 +24,12 @@ use crate::boot::is_authed; // pub(crate) in boot.rs:686 — same crate, no copy
 pub struct TabsSnapshotsState {
     pub auth_token: Arc<String>,
     pub snapshots_dir: Option<PathBuf>,
-    pub fresh_agent: freshell_freshagent::FreshAgentState,
-    pub screenshots: freshell_ws::screenshot::ScreenshotBroker,
-    /// The SAME `TerminalRegistry` (`main.rs:246`) the WS handler + `fresh_agent`
-    /// use. Restore reconciles write-ahead marker entries against it by
-    /// `is_running(terminalId)` so a crash between create and marker-promotion
-    /// can't cause a duplicate on retry (Task 3, `:1532`).
-    pub terminals: freshell_terminal::TerminalRegistry,
-    /// Serializes restores so two concurrent requests can't both read an empty
-    /// marker and duplicate tabs (Task 3). One process-wide lock is sufficient —
-    /// restores are rare, operator-triggered recovery actions.
-    pub restore_lock: Arc<tokio::sync::Mutex<()>>,
-    /// Bounds each per-pane delivery-ack round-trip (Task 3, `:1460`). Production
-    /// ~5s; tests set it short so the connection-drop path is fast.
-    pub restore_ack_timeout: std::time::Duration,
 }
 
 pub fn router(state: TabsSnapshotsState) -> Router {
     Router::new()
         .route("/api/tabs-sync/snapshots", get(list_snapshots))
         .route("/api/tabs-sync/snapshots/{device_id}", get(get_snapshot))
-        .route("/api/tabs-sync/restore", axum::routing::post(restore_tabs))
         .with_state(state)
 }
 
@@ -68,11 +55,11 @@ fn snapshots_read_error(dir: &std::path::Path, err: &dyn std::fmt::Display) -> R
         .into_response()
 }
 
-// Fail-closed selector parsing (GET query params AND the restore body share
-// ONE code path) — see `tabs_snapshots_selectors.rs`.
+// Fail-closed selector parsing for the GET query params — see
+// `tabs_snapshots_selectors.rs`.
 #[path = "tabs_snapshots_selectors.rs"]
 mod selectors_mod;
-use selectors_mod::{parse_restore_selection, parse_selector, Selector};
+use selectors_mod::{parse_selector, Selector};
 
 async fn list_snapshots(State(state): State<TabsSnapshotsState>, headers: HeaderMap) -> Response {
     if !is_authed(&headers, &state.auth_token) {
@@ -155,777 +142,6 @@ async fn get_snapshot(
     }
 }
 
-// ── POST /api/tabs-sync/restore ─────────────────────────────────────────────
-// Rebuilds open panes through the normal create pipeline. A per-source
-// write-ahead ledger makes each `(device, source, tabKey, paneId)` idempotent;
-// targeted delivery plus a screenshot fence proves the selected connection
-// received each replayable tab.create. Selectors and marker corruption fail
-// closed, while unsupported pane kinds are reported as skips.
-
-#[path = "tabs_snapshots_marker.rs"]
-mod marker_mod;
-use marker_mod::{
-    prune_marker_doc, read_marker_doc, validate_restore_projection, write_marker_doc, Marker,
-    MarkerDoc, PaneMark, RESTORE_MARKER,
-};
-#[cfg(test)]
-use marker_mod::{
-    validate_marker_pane_count, MAX_RESTORE_MARKER_BYTES, MAX_RESTORE_MARKER_PANES_PER_SOURCE,
-    MAX_RESTORE_MARKER_PANE_KEY_BYTES, MAX_RESTORE_MARKER_SOURCES,
-    MAX_RESTORE_MARKER_SOURCE_ID_BYTES, MAX_RESTORE_MARKER_TERMINAL_ID_BYTES, RESTORE_MARKER_TMP,
-};
-
-#[path = "tabs_snapshots_create_body.rs"]
-mod tabs_snapshots_create_body;
-use tabs_snapshots_create_body::pane_to_create_body;
-
-/// Stable per-pane identity key (content-derived, NOT a positional index).
-fn pane_key(tab_key: &str, pane_id: &str) -> String {
-    format!("{tab_key}#{pane_id}")
-}
-
-/// Deterministic key for reconciling a create whose marker promotion did not land.
-fn restore_key_for(device_id: &str, source_id: &str, pane_key: &str) -> String {
-    format!("restore:{device_id}:{source_id}:{pane_key}")
-}
-
-/// Read the whole marker ledger off-runtime under the persistence lock.
-async fn read_marker_doc_async(device_dir: &std::path::Path) -> std::io::Result<MarkerDoc> {
-    let dd = device_dir.to_path_buf();
-    match tokio::task::spawn_blocking(move || {
-        freshell_ws::tabs_persist::with_persist_lock(|| read_marker_doc(&dd))
-    })
-    .await
-    {
-        Ok(r) => r,
-        Err(join) => Err(std::io::Error::other(join.to_string())),
-    }
-}
-
-/// Persist the updated source ledger under the shared persistence lock.
-async fn persist_marker(
-    device_dir: Option<&std::path::Path>,
-    doc: &mut MarkerDoc,
-    source_id: &str,
-    panes: &Marker,
-    at: i64,
-) -> std::io::Result<()> {
-    let Some(dd) = device_dir else { return Ok(()) };
-    doc.insert(source_id.to_string(), (at, panes.clone()));
-    prune_marker_doc(doc, Some(source_id));
-    let (dd, doc) = (dd.to_path_buf(), doc.clone());
-    match tokio::task::spawn_blocking(move || {
-        freshell_ws::tabs_persist::with_persist_lock(|| write_marker_doc(&dd, &doc))
-    })
-    .await
-    {
-        Ok(r) => r,
-        Err(join) => Err(std::io::Error::other(join.to_string())),
-    }
-}
-
-/// Fence tab.create with a screenshot reply from the same selected connection.
-/// A per-attempt nonce prevents a stale response from confirming a retry.
-async fn confirm_delivery(
-    state: &TabsSnapshotsState,
-    target_client_id: u64,
-    nonce: &str,
-    pane_key: &str,
-) -> bool {
-    let request_id = format!("restore-ack:{nonce}:{pane_key}");
-    let rx = state
-        .screenshots
-        .register_for_client(request_id.clone(), target_client_id);
-    if !state
-        .screenshots
-        .send_capture_to(target_client_id, &request_id, "view", None, None)
-    {
-        state.screenshots.cancel(&request_id);
-        return false;
-    }
-    match tokio::time::timeout(state.restore_ack_timeout, rx).await {
-        Ok(Ok(_)) => true, // ANY resolved result (ok OR error) == received
-        // A dropped sender (pending entry cancelled/purged before the client
-        // answered) is NOT an ack; its removal already dropped the entry.
-        Ok(Err(_)) => false,
-        Err(_) => {
-            state.screenshots.cancel(&request_id);
-            false
-        }
-    }
-}
-
-#[allow(clippy::result_large_err)]
-fn optional_bool(body: &Value, field: &str) -> Result<bool, Response> {
-    match body.get(field) {
-        None => Ok(false),
-        Some(Value::Bool(value)) => Ok(*value),
-        Some(_) => Err((
-            StatusCode::BAD_REQUEST,
-            Json(json!({ "error": format!("{field} must be a boolean") })),
-        )
-            .into_response()),
-    }
-}
-
-async fn restore_tabs(
-    State(state): State<TabsSnapshotsState>,
-    headers: HeaderMap,
-    Json(body): Json<Value>,
-) -> Response {
-    if !is_authed(&headers, &state.auth_token) {
-        return unauthorized();
-    }
-    let device_id = match body.get("deviceId").and_then(Value::as_str) {
-        Some(d) if !d.is_empty() => d.to_string(),
-        _ => {
-            return (
-                StatusCode::BAD_REQUEST,
-                Json(json!({ "error": "deviceId is required" })),
-            )
-                .into_response()
-        }
-    };
-    let dry_run = match optional_bool(&body, "dryRun") {
-        Ok(value) => value,
-        Err(response) => return response,
-    };
-    let force = match optional_bool(&body, "force") {
-        Ok(value) => value,
-        Err(response) => return response,
-    };
-
-    let Some(dir) = state.snapshots_dir.clone() else {
-        return (
-            StatusCode::NOT_FOUND,
-            Json(json!({ "error": "Snapshot not found" })),
-        )
-            .into_response();
-    };
-    // Malformed selectors fail closed; components have highest priority.
-    let selection = match parse_restore_selection(&body) {
-        Ok(s) => s,
-        Err(resp) => return resp,
-    };
-    // Protect the source generation and its write-ahead marker for the WHOLE
-    // restore, including async create and delivery waits between locked IO.
-    let _snapshot_lease = freshell_ws::tabs_persist::protect_snapshot_device(&dir, &device_id);
-    let (generation_n, generation_id_req) = match &selection.selector {
-        Selector::Index(n) => (Some(*n), None),
-        Selector::Id(id) => (None, Some(id.clone())),
-        Selector::Union => (None, None),
-    };
-    // Snapshot selection off the runtime (fail-loud). Errors -> 500.
-    enum Read {
-        Snap(Option<Value>),
-        MissingComponents(Vec<String>),
-    }
-    let sel = (
-        dir.clone(),
-        device_id.clone(),
-        selection.components.clone(),
-        generation_id_req.clone(),
-        generation_n,
-    );
-    let read = tokio::task::spawn_blocking(move || -> std::io::Result<Read> {
-        let (dir, device_id, comps, gid, gn) = sel;
-        if !comps.is_empty() {
-            // Every requested component must resolve; partial unions fail.
-            return Ok(
-                match freshell_ws::tabs_persist::read_generations_union_by_ids(
-                    &dir, &device_id, &comps,
-                )? {
-                    freshell_ws::tabs_persist::ComponentsUnion::Found(v) => Read::Snap(Some(v)),
-                    freshell_ws::tabs_persist::ComponentsUnion::Missing(m) => {
-                        Read::MissingComponents(m)
-                    }
-                },
-            );
-        }
-        Ok(Read::Snap(if let Some(id) = gid {
-            freshell_ws::tabs_persist::read_generation_by_id(&dir, &device_id, &id)?
-        } else if let Some(g) = gn {
-            freshell_ws::tabs_persist::read_generation(&dir, &device_id, g)?
-        } else {
-            freshell_ws::tabs_persist::read_device_union(&dir, &device_id)?
-        }))
-    })
-    .await;
-    let snap = match read {
-        Ok(Ok(Read::Snap(Some(snap)))) => snap,
-        Ok(Ok(Read::Snap(None))) => {
-            return (
-                StatusCode::NOT_FOUND,
-                Json(json!({ "error": "Snapshot not found" })),
-            )
-                .into_response()
-        }
-        Ok(Ok(Read::MissingComponents(missing))) => {
-            return (
-                StatusCode::CONFLICT,
-                Json(json!({
-                    "error": format!(
-                        "restore refused: requested component generation(s) not found for device {device_id}: {} (pruned or never captured). Re-capture, or pick available generations via GET /api/tabs-sync/snapshots.",
-                        missing.join(", ")
-                    ),
-                    "missingComponents": missing,
-                })),
-            )
-                .into_response()
-        }
-        Ok(Err(err)) => return snapshots_read_error(&dir, &err),
-        Err(join) => return snapshots_read_error(&dir, &join),
-    };
-    // Validate every targeted pane key before any side effect.
-    if let Some(filter) = &selection.panes {
-        let mut known: std::collections::HashSet<String> = std::collections::HashSet::new();
-        for record in snap
-            .get("records")
-            .and_then(Value::as_array)
-            .into_iter()
-            .flatten()
-        {
-            if record.get("status").and_then(Value::as_str) != Some("open") {
-                continue;
-            }
-            let tk = record.get("tabKey").and_then(Value::as_str).unwrap_or("");
-            for pane in record
-                .get("panes")
-                .and_then(Value::as_array)
-                .into_iter()
-                .flatten()
-            {
-                let pid = pane.get("paneId").and_then(Value::as_str).unwrap_or("");
-                known.insert(pane_key(tk, pid));
-            }
-        }
-        let mut unknown: Vec<String> = filter
-            .iter()
-            .filter(|k| !known.contains(*k))
-            .cloned()
-            .collect();
-        unknown.sort();
-        if !unknown.is_empty() {
-            return (
-                StatusCode::BAD_REQUEST,
-                Json(json!({
-                    "error": format!(
-                        "restore refused: requested pane(s) not present in the selected snapshot: {}",
-                        unknown.join(", ")
-                    ),
-                    "unknownPanes": unknown,
-                })),
-            )
-                .into_response();
-        }
-    }
-    let source_id = freshell_ws::tabs_persist::snapshot_content_id(&snap);
-    let captured_at = snap.get("capturedAt").and_then(Value::as_i64).unwrap_or(0);
-    // Distinguish delivery fences from replies to earlier attempts.
-    let nonce = uuid::Uuid::new_v4().to_string();
-
-    let _guard = state.restore_lock.lock().await;
-
-    // Bind all delivery and acknowledgements to this exact connection.
-    let (connected, target_client_id) = state.screenshots.client_snapshot();
-    if !dry_run && !force && target_client_id.is_none() {
-        return (StatusCode::CONFLICT, Json(json!({
-            "error": format!("restore requires exactly one connected browser (found {connected}); connect the target device only, or pass force"),
-            "connectedClients": connected,
-        }))).into_response();
-    }
-
-    let device_dir = freshell_ws::tabs_persist::encode_device_id(&device_id).map(|e| dir.join(e));
-    // Preserve per-source history, including under force. Corrupt idempotency
-    // state fails closed unless force explicitly rebuilds it.
-    let mut doc: MarkerDoc = match &device_dir {
-        Some(dd) => match read_marker_doc_async(dd).await {
-            Ok(doc) => doc,
-            Err(err) if force => {
-                tracing::warn!(target: "freshell_server::tabs_snapshots", device_id = %device_id,
-                    error = %err, "restore_marker_unreadable_force_override: rebuilding ledger");
-                MarkerDoc::new()
-            }
-            Err(err) => {
-                tracing::error!(target: "freshell_server::tabs_snapshots", device_id = %device_id,
-                    error = %err, "restore_marker_unreadable");
-                return (StatusCode::CONFLICT, Json(json!({
-                    "error": format!(
-                        "restore refused: the restore marker for device {device_id} is unreadable or corrupt ({err}). It is the sole idempotency record, so proceeding could duplicate previously-restored tabs. Inspect/repair or delete the marker file, or rerun with force:true to explicitly discard it."
-                    ),
-                    "markerError": true,
-                }))).into_response();
-            }
-        },
-        None => MarkerDoc::new(),
-    };
-    let prior: Marker = doc
-        .get(&source_id)
-        .map(|(_, panes)| panes.clone())
-        .unwrap_or_default();
-    let mut marker: Marker = prior.clone(); // the union we will persist
-    let records = snap
-        .get("records")
-        .and_then(Value::as_array)
-        .cloned()
-        .unwrap_or_default();
-
-    // Preflight the projected ledger, including UUID-sized terminal ids.
-    if !dry_run {
-        if let Some(device_dir) = &device_dir {
-            if let Err(error) = validate_restore_projection(
-                &device_dir.join(RESTORE_MARKER),
-                &doc,
-                &source_id,
-                captured_at,
-                force,
-                selection.panes.as_ref(),
-                &records,
-            ) {
-                return marker_preflight_error(&device_id, &error);
-            }
-        }
-    }
-
-    let mut restored = Vec::new();
-    let mut skipped = Vec::new();
-    let mut failed = Vec::new();
-    let mut delivery_confirmed = true;
-    let mut connection_dropped = false; // once true, remaining panes are FAILED
-    for record in &records {
-        if record.get("status").and_then(Value::as_str) != Some("open") {
-            continue;
-        }
-        let tab_key = record.get("tabKey").cloned().unwrap_or(Value::Null);
-        let tab_key_str = tab_key.as_str().unwrap_or("").to_string();
-        let tab_name = record.get("tabName");
-        for pane in record
-            .get("panes")
-            .and_then(Value::as_array)
-            .cloned()
-            .unwrap_or_default()
-            .iter()
-        {
-            let pane_id = pane.get("paneId").cloned().unwrap_or(Value::Null);
-            let pane_id_str = pane_id.as_str().unwrap_or("").to_string();
-            let kind = pane.get("kind").cloned().unwrap_or(Value::Null);
-            let kind_str = kind.as_str().unwrap_or("").to_string();
-            let pk = pane_key(&tab_key_str, &pane_id_str);
-
-            // Report unselected panes without touching state or the connection.
-            if selection
-                .panes
-                .as_ref()
-                .is_some_and(|filter| !filter.contains(&pk))
-            {
-                skipped.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                    "reason": "not-selected" }));
-                continue;
-            }
-
-            // Classify before touching the marker or connection.
-            let create_body = match pane_to_create_body(tab_name, pane) {
-                Err("unsupported-kind") => {
-                    skipped.push(json!({ "tabKey": tab_key, "paneId": pane_id,
-                        "kind": kind, "reason": "unsupported-kind" }));
-                    continue;
-                }
-                Err(reason) => {
-                    failed.push(json!({ "tabKey": tab_key, "paneId": pane_id,
-                        "kind": kind, "reason": reason }));
-                    continue;
-                }
-                Ok(b) => b,
-            };
-            let prior_mark = prior.get(&pk).cloned();
-            // Ordinary reruns report restored panes as no-ops. Force bypasses
-            // that skip and either replaces the UI identity or recreates.
-            if !force {
-                if let Some(pm) = &prior_mark {
-                    if pm.state == "restored" {
-                        skipped.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                            "reason": "already-restored" }));
-                        continue;
-                    }
-                }
-            }
-            if connection_dropped {
-                failed.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                    "reason": "connection-dropped" }));
-                continue;
-            }
-
-            // Reconcile a prior live process/tab through its replayable command.
-            // A new target receives tab.create before its fence. Force replaces
-            // no-process content tabs instead.
-            let restore_key = restore_key_for(&device_id, &source_id, &pk);
-            let ledger = state.fresh_agent.lookup_restore_key(&restore_key);
-            let ledger_live_terminal = ledger
-                .as_ref()
-                .and_then(|entry| entry.terminal_id.clone())
-                .filter(|terminal_id| state.terminals.is_running(terminal_id));
-            if force && !dry_run && kind_str == "terminal" && ledger_live_terminal.is_some() {
-                let (old_tab_id, replacement) = state
-                    .fresh_agent
-                    .reissue_restore_key_terminal(&restore_key)
-                    .expect("live restore-key terminal has tab bookkeeping");
-                let close =
-                    freshell_protocol::ServerMessage::UiCommand(freshell_protocol::UiCommand {
-                        command: "tab.close".to_string(),
-                        payload: Some(json!({ "id": old_tab_id })),
-                    });
-                let delivered = target_client_id.is_some_and(|target| {
-                    state.screenshots.send_to_client(target, close)
-                        && state
-                            .screenshots
-                            .send_to_client(target, replacement.ui_command.clone())
-                });
-                if delivered {
-                    state
-                        .fresh_agent
-                        .mark_restore_key_delivered(&restore_key, target_client_id.unwrap());
-                }
-                let confirmed = delivered
-                    && confirm_delivery(
-                        &state,
-                        target_client_id.expect("delivered requires a target"),
-                        &nonce,
-                        &pk,
-                    )
-                    .await;
-                if confirmed {
-                    marker.insert(
-                        pk.clone(),
-                        PaneMark {
-                            state: "restored".into(),
-                            terminal_id: replacement.terminal_id.clone(),
-                        },
-                    );
-                    restored.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                        "terminalId": replacement.terminal_id, "tabId": replacement.tab_id,
-                        "forcedReplacement": true }));
-                } else if target_client_id.is_some() {
-                    delivery_confirmed = false;
-                    connection_dropped = true;
-                    failed.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                        "reason": "delivery-unconfirmed",
-                        "terminalId": replacement.terminal_id }));
-                } else {
-                    delivery_confirmed = false;
-                    restored.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                        "terminalId": replacement.terminal_id, "tabId": replacement.tab_id,
-                        "forcedReplacement": true }));
-                }
-                continue;
-            }
-            if force && !dry_run && kind_str != "terminal" {
-                if let Some(entry) = ledger.as_ref().filter(|e| e.terminal_id.is_none()) {
-                    let close =
-                        freshell_protocol::ServerMessage::UiCommand(freshell_protocol::UiCommand {
-                            command: "tab.close".to_string(),
-                            payload: Some(json!({ "id": entry.tab_id })),
-                        });
-                    if target_client_id
-                        .is_some_and(|target| !state.screenshots.send_to_client(target, close))
-                    {
-                        delivery_confirmed = false;
-                        connection_dropped = true;
-                        failed.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                            "reason": "delivery-unconfirmed" }));
-                        continue;
-                    }
-                    state.fresh_agent.retire_restore_key_content(&restore_key);
-                }
-            } else if let Some(pm) = &prior_mark {
-                let live_terminal_id = pm
-                    .terminal_id
-                    .clone()
-                    .filter(|t| state.terminals.is_running(t))
-                    .or_else(|| {
-                        ledger
-                            .as_ref()
-                            .and_then(|e| e.terminal_id.clone())
-                            .filter(|t| state.terminals.is_running(t))
-                    });
-                let ledger_content_tab = ledger
-                    .as_ref()
-                    .filter(|e| e.terminal_id.is_none())
-                    .map(|e| e.tab_id.clone());
-                if live_terminal_id.is_some() || ledger_content_tab.is_some() {
-                    if dry_run {
-                        restored.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                            "terminalId": live_terminal_id,
-                            "tabId": ledger_content_tab.map(Value::from).unwrap_or(Value::Null),
-                            "reconciled": true, "dryRun": true }));
-                        continue;
-                    }
-                    let ready_for_fence = target_client_id.is_some_and(|target| {
-                        if ledger
-                            .as_ref()
-                            .is_some_and(|entry| entry.delivered_to.contains(&target))
-                        {
-                            return true;
-                        }
-                        let sent = ledger.as_ref().is_some_and(|entry| {
-                            state
-                                .screenshots
-                                .send_to_client(target, entry.ui_command.clone())
-                        });
-                        if sent {
-                            state
-                                .fresh_agent
-                                .mark_restore_key_delivered(&restore_key, target);
-                        }
-                        sent
-                    });
-                    let acked = ready_for_fence
-                        && confirm_delivery(
-                            &state,
-                            target_client_id.expect("checked Some"),
-                            &nonce,
-                            &pk,
-                        )
-                        .await;
-                    if !acked {
-                        delivery_confirmed = false;
-                        connection_dropped = target_client_id.is_some();
-                        marker.insert(pk.clone(), pm.clone());
-                        failed.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                            "reason": "delivery-unconfirmed",
-                            "terminalId": live_terminal_id }));
-                    } else {
-                        marker.insert(
-                            pk.clone(),
-                            PaneMark {
-                                state: "restored".into(),
-                                terminal_id: live_terminal_id.clone(),
-                            },
-                        );
-                        restored.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                            "terminalId": live_terminal_id,
-                            "tabId": ledger_content_tab.map(Value::from).unwrap_or(Value::Null),
-                            "reconciled": true }));
-                    }
-                    continue;
-                }
-                if pm.state == "in-progress" && kind_str != "terminal" && !force {
-                    marker.insert(pk.clone(), pm.clone());
-                    failed.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                        "reason": "in-progress-unconfirmed",
-                        "hint": "an earlier attempt's tab.create may have reached the client; verify the pane in the target browser, then rerun with force:true to recreate it" }));
-                    continue;
-                }
-            }
-            if dry_run {
-                restored.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                    "request": create_body, "tabId": Value::Null, "dryRun": true }));
-                continue;
-            }
-
-            // Write ahead before create; restoreKey reconciles the crash window.
-            marker.insert(
-                pk.clone(),
-                PaneMark {
-                    state: "in-progress".into(),
-                    terminal_id: None,
-                },
-            );
-            if let Err(err) = persist_marker(
-                device_dir.as_deref(),
-                &mut doc,
-                &source_id,
-                &marker,
-                captured_at,
-            )
-            .await
-            {
-                return marker_error(
-                    &device_id,
-                    &snap,
-                    connected,
-                    delivery_confirmed,
-                    restored,
-                    skipped,
-                    failed,
-                    &err,
-                );
-            }
-
-            let mut tagged_body = create_body.clone();
-            tagged_body["restoreKey"] = json!(restore_key);
-            let resp = freshell_freshagent::terminal_tabs::create_terminal_or_content_tab_deferred(
-                state.fresh_agent.clone(),
-                tagged_body,
-            )
-            .await;
-            let status = resp.status();
-            let rbytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
-                .await
-                .unwrap_or_default();
-            let resp_body: Value = serde_json::from_slice(&rbytes).unwrap_or(Value::Null);
-            if !(status.is_success()
-                && resp_body.get("status").and_then(Value::as_str) == Some("ok"))
-            {
-                // A failed create restores any prior marker entry.
-                match &prior_mark {
-                    Some(pm) => {
-                        marker.insert(pk.clone(), pm.clone());
-                    }
-                    None => {
-                        marker.remove(&pk);
-                    }
-                }
-                failed.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                    "status": status.as_u16(), "error": resp_body }));
-                continue;
-            }
-            let data = resp_body.get("data").cloned().unwrap_or(Value::Null);
-            let terminal_id = data
-                .get("terminalId")
-                .and_then(Value::as_str)
-                .map(str::to_string);
-            let ui_command = data.get("uiCommand").cloned().and_then(|value| {
-                serde_json::from_value::<freshell_protocol::ServerMessage>(value).ok()
-            });
-            // The durable pre-create record preserves write-ahead safety. Batch
-            // this terminal id into the next write-ahead or final marker write.
-            marker.insert(
-                pk.clone(),
-                PaneMark {
-                    state: "in-progress".into(),
-                    terminal_id: terminal_id.clone(),
-                },
-            );
-            // Deliver and fence on the exact selected target.
-            let delivered = target_client_id
-                .zip(ui_command)
-                .is_some_and(|(target, command)| {
-                    let sent = state.screenshots.send_to_client(target, command);
-                    if sent {
-                        state
-                            .fresh_agent
-                            .mark_restore_key_delivered(&restore_key, target);
-                    }
-                    sent
-                });
-            let confirmed = if delivered {
-                confirm_delivery(
-                    &state,
-                    target_client_id.expect("delivered requires a target"),
-                    &nonce,
-                    &pk,
-                )
-                .await
-            } else {
-                false
-            };
-            if confirmed {
-                marker.insert(
-                    pk.clone(),
-                    PaneMark {
-                        state: "restored".into(),
-                        terminal_id: terminal_id.clone(),
-                    },
-                );
-                restored.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                    "tabId": data.get("tabId").cloned().unwrap_or(Value::Null), "terminalId": terminal_id }));
-            } else if target_client_id.is_some() {
-                // Keep the created terminal in-progress for a safe retry.
-                delivery_confirmed = false;
-                connection_dropped = true;
-                failed.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                    "reason": "delivery-unconfirmed", "terminalId": terminal_id }));
-            } else {
-                // force + 0 clients: created but delivery cannot be confirmed.
-                delivery_confirmed = false;
-                restored.push(json!({ "tabKey": tab_key, "paneId": pane_id, "kind": kind,
-                    "tabId": data.get("tabId").cloned().unwrap_or(Value::Null), "terminalId": terminal_id }));
-            }
-        }
-    }
-
-    if !dry_run {
-        if let Err(err) = persist_marker(
-            device_dir.as_deref(),
-            &mut doc,
-            &source_id,
-            &marker,
-            captured_at,
-        )
-        .await
-        {
-            return marker_error(
-                &device_id,
-                &snap,
-                connected,
-                delivery_confirmed,
-                restored,
-                skipped,
-                failed,
-                &err,
-            );
-        }
-    }
-
-    Json(json!({
-        "deviceId": device_id,
-        "generation": generation_n,
-        "generationId": generation_id_req,
-        "sourceId": source_id,
-        "sourceCapturedAt": snap.get("capturedAt").cloned().unwrap_or(Value::Null),
-        "broadcastScope": if target_client_id.is_some() { "target-client" } else { "none" },
-        "connectedClients": connected,
-        "deliveryConfirmed": dry_run || delivery_confirmed,
-        "restored": restored,
-        "skipped": skipped,
-        "failed": failed,
-    }))
-    .into_response()
-}
-
-fn marker_preflight_error(device_id: &str, error: &dyn std::fmt::Display) -> Response {
-    tracing::warn!(target: "freshell_server::tabs_snapshots", device_id = %device_id,
-        error = %error, "restore_marker_limit_rejected");
-    (
-        StatusCode::CONFLICT,
-        Json(json!({
-            "error": format!("restore refused: restore marker limit exceeded ({error})"),
-            "markerError": true,
-        })),
-    )
-        .into_response()
-}
-
-/// A marker write failed AFTER side-effects: 500, fail LOUDLY, echoing what was
-/// done so a lost marker can never read as a clean success.
-#[allow(clippy::too_many_arguments)]
-fn marker_error(
-    device_id: &str,
-    snap: &Value,
-    connected: i64,
-    delivery_confirmed: bool,
-    restored: Vec<Value>,
-    skipped: Vec<Value>,
-    failed: Vec<Value>,
-    err: &dyn std::fmt::Display,
-) -> Response {
-    tracing::error!(target: "freshell_server::tabs_snapshots", device_id = %device_id,
-        error = %err, "restore_marker_write_failed");
-    (
-        StatusCode::INTERNAL_SERVER_ERROR,
-        Json(json!({
-            "deviceId": device_id,
-            "sourceCapturedAt": snap.get("capturedAt").cloned().unwrap_or(Value::Null),
-            "connectedClients": connected,
-            "deliveryConfirmed": delivery_confirmed,
-            "error": format!("restore marker write failed: {err}"),
-            "markerError": true,
-            "restored": restored, "skipped": skipped, "failed": failed,
-        })),
-    )
-        .into_response()
-}
-
 #[cfg(test)]
 #[path = "tabs_snapshots_tests.rs"]
 mod tests;
diff --git a/crates/freshell-server/src/tabs_snapshots_create_body.rs b/crates/freshell-server/src/tabs_snapshots_create_body.rs
deleted file mode 100644
index 6c6ca8563..000000000
--- a/crates/freshell-server/src/tabs_snapshots_create_body.rs
+++ /dev/null
@@ -1,89 +0,0 @@
-//! `pane_to_create_body` — extracted from `tabs_snapshots.rs` to honor the
-//! 1,000-line file cap (port/AGENTS.md) when the createRequestId passthrough
-//! was added. Included via `#[path]` from `tabs_snapshots.rs`, matching the
-//! sibling pattern used by `tabs_snapshots_marker.rs` / `tabs_snapshots_tests.rs`.
-
-use serde_json::{json, Value};
-
-/// Map a snapshot pane to its `POST /api/tabs` body. Invalid session identity
-/// fails before spawn; unsupported kinds are skips. Captured terminal, browser,
-/// and editor options pass through to the restored pane.
-pub(crate) fn pane_to_create_body(
-    tab_name: Option<&Value>,
-    pane: &Value,
-) -> Result<Value, &'static str> {
-    let payload = pane.get("payload").cloned().unwrap_or_else(|| json!({}));
-    let kind = pane.get("kind").and_then(Value::as_str).unwrap_or("");
-    let name = tab_name.cloned().unwrap_or(Value::Null);
-    match kind {
-        "terminal" => {
-            let mode = payload
-                .get("mode")
-                .and_then(Value::as_str)
-                .unwrap_or("shell");
-            let mut b = json!({ "mode": mode, "name": name });
-            if let Some(cwd) = payload.get("initialCwd").filter(|v| v.is_string()) {
-                b["cwd"] = cwd.clone();
-            }
-            if let Some(shell) = payload.get("shell").filter(|v| v.is_string()) {
-                b["shell"] = shell.clone();
-            }
-            // Stable pane identity key (reconciliation design §5.5): restore
-            // re-creates the pane under its CAPTURED key so server-side state
-            // keyed on it survives; absent on legacy snapshots (the REST
-            // ingress mints one in that case).
-            if let Some(crid) = payload.get("createRequestId").filter(|v| v.is_string()) {
-                b["createRequestId"] = crid.clone();
-            }
-            if let Some(cd) = payload.get("codexDurability").filter(|v| v.is_object()) {
-                if mode == "codex" {
-                    b["codexDurability"] = cd.clone();
-                }
-            }
-            // Present identity must be nonempty and match the terminal mode.
-            if let Some(sref) = payload.get("sessionRef").filter(|v| !v.is_null()) {
-                let ok = sref.is_object()
-                    && sref.get("provider").and_then(Value::as_str) == Some(mode)
-                    && sref
-                        .get("sessionId")
-                        .and_then(Value::as_str)
-                        .is_some_and(|s| !s.is_empty());
-                if !ok {
-                    return Err("session-identity-mismatch");
-                }
-                b["sessionRef"] = sref.clone();
-            }
-            Ok(b)
-        }
-        "browser" => match payload.get("url").and_then(Value::as_str) {
-            Some(url) => {
-                let mut b = json!({ "browser": url, "name": name });
-                if let Some(dt) = payload.get("devToolsOpen").filter(|v| v.is_boolean()) {
-                    b["devToolsOpen"] = dt.clone();
-                }
-                Ok(b)
-            }
-            None => Err("missing-url"),
-        },
-        "editor" => match payload.get("filePath") {
-            Some(file_path) if file_path.is_string() || file_path.is_null() => {
-                let mut b = json!({ "editor": file_path, "name": name });
-                if let Some(lang) = payload.get("language").filter(|v| v.is_string()) {
-                    b["language"] = lang.clone();
-                }
-                if let Some(ro) = payload.get("readOnly").filter(|v| v.is_boolean()) {
-                    b["readOnly"] = ro.clone();
-                }
-                if let Some(vm) = payload.get("viewMode").filter(|v| v.is_string()) {
-                    b["viewMode"] = vm.clone();
-                }
-                if let Some(ww) = payload.get("wordWrap").filter(|v| v.is_boolean()) {
-                    b["wordWrap"] = ww.clone();
-                }
-                Ok(b)
-            }
-            _ => Err("missing-filePath"),
-        },
-        _ => Err("unsupported-kind"),
-    }
-}
diff --git a/crates/freshell-server/src/tabs_snapshots_marker.rs b/crates/freshell-server/src/tabs_snapshots_marker.rs
deleted file mode 100644
index e0f32701f..000000000
--- a/crates/freshell-server/src/tabs_snapshots_marker.rs
+++ /dev/null
@@ -1,538 +0,0 @@
-//! Write-ahead restore marker: the on-disk idempotency ledger for
-//! `POST /api/tabs-sync/restore` (`tabs_snapshots.rs`). Split into its own
-//! `#[path]`-included module to keep the handler file under the repo's
-//! 1,000-line-per-file limit.
-//!
-//! FORMAT (v2, multi-source): one `last-restore.marker` per device dir holding
-//! EVERY source's pane history:
-//!
-//! ```json
-//! { "version": 2,
-//!   "sources": { "<sourceId>": { "at": 123, "panes": {
-//!       "<tabKey>#<paneId>": { "state": "in-progress|restored", "terminalId": null } } } } }
-//! ```
-//!
-//! Keeping history per `(deviceId, sourceId)` (NOT a single last-source entry)
-//! is what makes restore idempotent across source switches: restoring source
-//! A, then B, then A again must still see A's `restored` panes and skip them
-//! (`tabs_snapshots.rs:304`). A v1 single-source marker (top-level
-//! `sourceId`/`panes`) is migrated on read.
-//!
-//! READS FAIL LOUD (`tabs_snapshots.rs:306`): this file is the SOLE
-//! idempotency record, so an unreadable or unparsable marker is an `Err` the
-//! handler surfaces as HTTP 409 with recovery instructions — NEVER an empty
-//! marker (which would read as "nothing restored yet" and duplicate every
-//! previously-restored tab on an ordinary rerun).
-
-use std::collections::HashMap;
-use std::io::Write;
-use std::path::Path;
-
-use serde::ser::{SerializeMap, SerializeStruct};
-use serde::Serialize;
-use serde_json::Value;
-
-pub(super) const RESTORE_MARKER: &str = "last-restore.marker"; // .marker ext -> invisible to *.json listing
-
-/// In-flight temp filename for the atomic marker write. Deliberately `.new`,
-/// NOT `.tmp`: freshell-ws's `sweep_orphan_tmp` reaps every `*.tmp` in this
-/// SAME device dir. Marker IO now runs under the SHARED
-/// `freshell_ws::tabs_persist::with_persist_lock`, so the sweep can no longer
-/// run mid-write — the `.new` name stays as defense-in-depth (pinned by
-/// `marker_in_flight_temp_is_invisible_to_the_ws_orphan_tmp_sweep` and the
-/// freshell-ws sweep test).
-pub(super) const RESTORE_MARKER_TMP: &str = ".last-restore.marker.new";
-/// Bound the per-device restore history independently of source churn. This
-/// matches the maximum number of retained generation files for one device, so
-/// marker IO and disk usage cannot grow without limit.
-pub(super) const MAX_RESTORE_MARKER_SOURCES: usize =
-    freshell_ws::tabs_persist::MAX_SNAPSHOT_FILES_PER_DEVICE;
-/// One device retains at most 40 MiB of snapshot-generation payload. Allow a
-/// 64 MiB marker so ordinary ledger overhead fits while marker disk/memory use
-/// remains explicitly bounded.
-pub(super) const MAX_RESTORE_MARKER_BYTES: usize =
-    64 * freshell_ws::tabs_persist::MAX_SNAPSHOT_BYTES;
-/// A valid pane occupies more than 32 serialized bytes in its source snapshot,
-/// so this accommodates every pane that could fit in all 40 retained files.
-pub(super) const MAX_RESTORE_MARKER_PANES_PER_SOURCE: usize =
-    freshell_ws::tabs_persist::MAX_SNAPSHOT_FILES_PER_DEVICE
-        * (freshell_ws::tabs_persist::MAX_SNAPSHOT_BYTES / 32);
-/// Content source ids are 32 hex bytes today; leave room for future digests.
-pub(super) const MAX_RESTORE_MARKER_SOURCE_ID_BYTES: usize = 128;
-/// Browser-generated tab/pane ids are short. 64 KiB is deliberately generous
-/// while preventing repeated tab keys from amplifying one marker without bound.
-pub(super) const MAX_RESTORE_MARKER_PANE_KEY_BYTES: usize = 64 * 1024;
-/// Terminal ids are UUID-shaped today; leave room for future formats.
-pub(super) const MAX_RESTORE_MARKER_TERMINAL_ID_BYTES: usize = 128;
-
-/// One pane's marker state (`in-progress` = write-ahead, side-effect may exist,
-/// delivery NOT yet confirmed; `restored` = delivery-acked). `terminal_id` is
-/// recorded once the create returns, for crash reconciliation.
-#[derive(Clone)]
-pub(super) struct PaneMark {
-    pub state: String,
-    pub terminal_id: Option<String>,
-}
-/// paneKey -> mark, for ONE source.
-pub(super) type Marker = HashMap<String, PaneMark>;
-/// sourceId -> (at, panes): the whole on-disk ledger.
-pub(super) type MarkerDoc = HashMap<String, (i64, Marker)>;
-
-fn marker_limit(path: &Path, why: impl std::fmt::Display) -> std::io::Error {
-    std::io::Error::new(
-        std::io::ErrorKind::InvalidData,
-        format!("restore marker {} limit exceeded: {why}", path.display()),
-    )
-}
-
-fn validate_identifier(
-    path: &Path,
-    name: &str,
-    value: &str,
-    max_bytes: usize,
-) -> std::io::Result<()> {
-    if value.is_empty() {
-        return Err(marker_limit(path, format!("{name} must be non-empty")));
-    }
-    if value.len() > max_bytes {
-        return Err(marker_limit(
-            path,
-            format!(
-                "{name} identifier length limit is {max_bytes} bytes (got {})",
-                value.len()
-            ),
-        ));
-    }
-    Ok(())
-}
-
-pub(super) fn validate_marker_pane_count(
-    path: &Path,
-    source_id: &str,
-    pane_count: usize,
-) -> std::io::Result<()> {
-    if pane_count > MAX_RESTORE_MARKER_PANES_PER_SOURCE {
-        return Err(marker_limit(
-            path,
-            format!(
-                "source `{source_id}` pane-count limit is {MAX_RESTORE_MARKER_PANES_PER_SOURCE} (got {pane_count})"
-            ),
-        ));
-    }
-    Ok(())
-}
-
-fn parse_panes(path: &Path, source_id: &str, value: &Value) -> std::io::Result<Marker> {
-    let map = value.as_object().ok_or_else(|| {
-        corrupt(
-            path,
-            format!("source `{source_id}` `panes` is not an object"),
-        )
-    })?;
-    validate_marker_pane_count(path, source_id, map.len())?;
-    let mut out = Marker::new();
-    for (key, pane) in map {
-        validate_identifier(
-            path,
-            &format!("source `{source_id}` pane key"),
-            key,
-            MAX_RESTORE_MARKER_PANE_KEY_BYTES,
-        )?;
-        let pane = pane.as_object().ok_or_else(|| {
-            corrupt(
-                path,
-                format!("source `{source_id}` pane `{key}` is not an object"),
-            )
-        })?;
-        let state = pane
-            .get("state")
-            .and_then(Value::as_str)
-            .filter(|state| matches!(*state, "in-progress" | "restored"))
-            .ok_or_else(|| {
-                corrupt(
-                    path,
-                    format!("source `{source_id}` pane `{key}` has an invalid or missing `state`"),
-                )
-            })?
-            .to_string();
-        let terminal_id = match pane.get("terminalId") {
-            None | Some(Value::Null) => None,
-            Some(Value::String(id)) => {
-                validate_identifier(
-                    path,
-                    &format!("source `{source_id}` pane `{key}` terminal id"),
-                    id,
-                    MAX_RESTORE_MARKER_TERMINAL_ID_BYTES,
-                )?;
-                Some(id.clone())
-            }
-            Some(_) => {
-                return Err(corrupt(
-                    path,
-                    format!(
-                        "source `{source_id}` pane `{key}` `terminalId` must be null or a non-empty string"
-                    ),
-                ))
-            }
-        };
-        out.insert(key.clone(), PaneMark { state, terminal_id });
-    }
-    Ok(out)
-}
-
-fn corrupt(path: &Path, why: impl std::fmt::Display) -> std::io::Error {
-    std::io::Error::new(
-        std::io::ErrorKind::InvalidData,
-        format!("corrupt restore marker {}: {why}", path.display()),
-    )
-}
-
-/// Read the WHOLE marker ledger. A MISSING file is genuine absence
-/// (`Ok(empty)`); an unreadable file or unparsable/unrecognized content is an
-/// `Err` (fail LOUD — see module doc). Blocking fs — call via `spawn_blocking`
-/// under `freshell_ws::tabs_persist::with_persist_lock`.
-pub(super) fn read_marker_doc(device_dir: &Path) -> std::io::Result<MarkerDoc> {
-    let path = device_dir.join(RESTORE_MARKER);
-    match std::fs::metadata(&path) {
-        Ok(metadata) if metadata.len() > MAX_RESTORE_MARKER_BYTES as u64 => {
-            return Err(marker_limit(
-                &path,
-                format!(
-                    "serialized byte limit is {MAX_RESTORE_MARKER_BYTES} (got {})",
-                    metadata.len()
-                ),
-            ))
-        }
-        Ok(_) => {}
-        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(MarkerDoc::new()),
-        Err(error) => {
-            return Err(std::io::Error::new(
-                error.kind(),
-                format!("unreadable restore marker {}: {error}", path.display()),
-            ))
-        }
-    }
-    let text = match std::fs::read_to_string(&path) {
-        Ok(t) => t,
-        Err(e) => {
-            return Err(std::io::Error::new(
-                e.kind(),
-                format!("unreadable restore marker {}: {e}", path.display()),
-            ))
-        }
-    };
-    if text.len() > MAX_RESTORE_MARKER_BYTES {
-        return Err(marker_limit(
-            &path,
-            "serialized byte limit changed during read",
-        ));
-    }
-    let v: Value = serde_json::from_str(&text).map_err(|e| corrupt(&path, e))?;
-    let mut doc = MarkerDoc::new();
-    if v.get("version").is_some() || v.get("sources").is_some() {
-        if v.get("version").and_then(Value::as_i64) != Some(2) {
-            return Err(corrupt(&path, "`version` must be exactly 2"));
-        }
-        let map = v
-            .get("sources")
-            .and_then(Value::as_object)
-            .ok_or_else(|| corrupt(&path, "required `sources` is not an object"))?;
-        for (sid, s) in map {
-            validate_identifier(&path, "source id", sid, MAX_RESTORE_MARKER_SOURCE_ID_BYTES)?;
-            let source = s
-                .as_object()
-                .ok_or_else(|| corrupt(&path, format!("source `{sid}` is not an object")))?;
-            let at = source
-                .get("at")
-                .and_then(Value::as_i64)
-                .ok_or_else(|| corrupt(&path, format!("source `{sid}` is missing integer `at`")))?;
-            let panes = source
-                .get("panes")
-                .ok_or_else(|| corrupt(&path, format!("source `{sid}` is missing `panes`")))?;
-            doc.insert(sid.clone(), (at, parse_panes(&path, sid, panes)?));
-        }
-        prune_marker_doc(&mut doc, None);
-        validate_marker_doc(&path, &doc)?;
-        return Ok(doc);
-    }
-    // v1 migration: a single top-level {sourceId, at, panes}.
-    if let Some(sid) = v
-        .get("sourceId")
-        .and_then(Value::as_str)
-        .filter(|sid| !sid.is_empty())
-    {
-        validate_identifier(&path, "source id", sid, MAX_RESTORE_MARKER_SOURCE_ID_BYTES)?;
-        let at = v
-            .get("at")
-            .and_then(Value::as_i64)
-            .ok_or_else(|| corrupt(&path, "v1 marker is missing integer `at`"))?;
-        let panes = v
-            .get("panes")
-            .ok_or_else(|| corrupt(&path, "v1 marker is missing `panes`"))?;
-        doc.insert(sid.to_string(), (at, parse_panes(&path, sid, panes)?));
-        validate_marker_doc(&path, &doc)?;
-        return Ok(doc);
-    }
-    Err(corrupt(
-        &path,
-        "unrecognized marker shape (no sources/sourceId)",
-    ))
-}
-
-struct MarkerFile<'a>(&'a MarkerDoc);
-struct MarkerSources<'a>(&'a MarkerDoc);
-struct MarkerSource<'a> {
-    at: i64,
-    panes: &'a Marker,
-}
-struct MarkerPanes<'a> {
-    at: i64,
-    panes: &'a Marker,
-}
-struct MarkerPane<'a> {
-    at: i64,
-    mark: &'a PaneMark,
-}
-
-impl Serialize for MarkerFile<'_> {
-    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where
-        S: serde::Serializer,
-    {
-        let mut root = serializer.serialize_struct("RestoreMarker", 2)?;
-        root.serialize_field("version", &2)?;
-        root.serialize_field("sources", &MarkerSources(self.0))?;
-        root.end()
-    }
-}
-
-impl Serialize for MarkerSources<'_> {
-    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where
-        S: serde::Serializer,
-    {
-        let mut map = serializer.serialize_map(Some(self.0.len()))?;
-        for (source_id, (at, panes)) in self.0 {
-            map.serialize_entry(source_id, &MarkerSource { at: *at, panes })?;
-        }
-        map.end()
-    }
-}
-
-impl Serialize for MarkerSource<'_> {
-    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where
-        S: serde::Serializer,
-    {
-        let mut source = serializer.serialize_struct("RestoreMarkerSource", 2)?;
-        source.serialize_field("at", &self.at)?;
-        source.serialize_field(
-            "panes",
-            &MarkerPanes {
-                at: self.at,
-                panes: self.panes,
-            },
-        )?;
-        source.end()
-    }
-}
-
-impl Serialize for MarkerPanes<'_> {
-    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where
-        S: serde::Serializer,
-    {
-        let mut map = serializer.serialize_map(Some(self.panes.len()))?;
-        for (pane_key, mark) in self.panes {
-            map.serialize_entry(pane_key, &MarkerPane { at: self.at, mark })?;
-        }
-        map.end()
-    }
-}
-
-impl Serialize for MarkerPane<'_> {
-    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where
-        S: serde::Serializer,
-    {
-        let mut pane = serializer.serialize_struct("RestoreMarkerPane", 3)?;
-        pane.serialize_field("state", &self.mark.state)?;
-        pane.serialize_field("terminalId", &self.mark.terminal_id)?;
-        pane.serialize_field("at", &self.at)?;
-        pane.end()
-    }
-}
-
-struct MarkerSizeWriter<'a> {
-    path: &'a Path,
-    bytes: usize,
-}
-
-impl Write for MarkerSizeWriter<'_> {
-    fn write(&mut self, buffer: &[u8]) -> std::io::Result<usize> {
-        let next = self
-            .bytes
-            .checked_add(buffer.len())
-            .ok_or_else(|| marker_limit(self.path, "serialized byte count overflow"))?;
-        if next > MAX_RESTORE_MARKER_BYTES {
-            return Err(marker_limit(
-                self.path,
-                format!(
-                    "serialized byte limit is {MAX_RESTORE_MARKER_BYTES} (more than {MAX_RESTORE_MARKER_BYTES})"
-                ),
-            ));
-        }
-        self.bytes = next;
-        Ok(buffer.len())
-    }
-
-    fn flush(&mut self) -> std::io::Result<()> {
-        Ok(())
-    }
-}
-
-pub(super) fn validate_marker_doc(path: &Path, doc: &MarkerDoc) -> std::io::Result<()> {
-    for (source_id, (_, panes)) in doc {
-        validate_identifier(
-            path,
-            "source id",
-            source_id,
-            MAX_RESTORE_MARKER_SOURCE_ID_BYTES,
-        )?;
-        validate_marker_pane_count(path, source_id, panes.len())?;
-        for (pane_key, mark) in panes {
-            validate_identifier(
-                path,
-                &format!("source `{source_id}` pane key"),
-                pane_key,
-                MAX_RESTORE_MARKER_PANE_KEY_BYTES,
-            )?;
-            if !matches!(mark.state.as_str(), "in-progress" | "restored") {
-                return Err(marker_limit(
-                    path,
-                    format!("source `{source_id}` pane `{pane_key}` has invalid state"),
-                ));
-            }
-            if let Some(terminal_id) = &mark.terminal_id {
-                validate_identifier(
-                    path,
-                    &format!("source `{source_id}` pane `{pane_key}` terminal id"),
-                    terminal_id,
-                    MAX_RESTORE_MARKER_TERMINAL_ID_BYTES,
-                )?;
-            }
-        }
-    }
-    let mut writer = MarkerSizeWriter { path, bytes: 0 };
-    serde_json::to_writer(&mut writer, &MarkerFile(doc)).map_err(|error| {
-        marker_limit(
-            path,
-            format!("serialized byte limit validation failed: {error}"),
-        )
-    })
-}
-
-pub(super) fn validate_restore_projection(
-    path: &Path,
-    doc: &MarkerDoc,
-    source_id: &str,
-    captured_at: i64,
-    force: bool,
-    selected_panes: Option<&std::collections::HashSet<String>>,
-    records: &[Value],
-) -> std::io::Result<()> {
-    let current = doc.get(source_id).map(|(_, panes)| panes);
-    let mut projected = current.cloned().unwrap_or_default();
-    for record in records {
-        if record.get("status").and_then(Value::as_str) != Some("open") {
-            continue;
-        }
-        let tab_key = record.get("tabKey").and_then(Value::as_str).unwrap_or("");
-        for pane in record
-            .get("panes")
-            .and_then(Value::as_array)
-            .into_iter()
-            .flatten()
-        {
-            let pane_id = pane.get("paneId").and_then(Value::as_str).unwrap_or("");
-            let key = super::pane_key(tab_key, pane_id);
-            if selected_panes.is_some_and(|filter| !filter.contains(&key))
-                || super::pane_to_create_body(record.get("tabName"), pane).is_err()
-            {
-                continue;
-            }
-            if !force
-                && current
-                    .and_then(|panes| panes.get(&key))
-                    .is_some_and(|mark| mark.state == "restored")
-            {
-                continue;
-            }
-            let is_terminal = pane.get("kind").and_then(Value::as_str) == Some("terminal");
-            projected
-                .entry(key)
-                .and_modify(|mark| {
-                    mark.state = "in-progress".into();
-                    if is_terminal
-                        && mark
-                            .terminal_id
-                            .as_ref()
-                            .is_none_or(|terminal_id| terminal_id.len() < 36)
-                    {
-                        mark.terminal_id = Some("00000000-0000-0000-0000-000000000000".to_string());
-                    }
-                })
-                .or_insert_with(|| PaneMark {
-                    state: "in-progress".into(),
-                    terminal_id: is_terminal
-                        .then(|| "00000000-0000-0000-0000-000000000000".to_string()),
-                });
-        }
-    }
-    let mut projected_doc = doc.clone();
-    projected_doc.insert(source_id.to_string(), (captured_at, projected));
-    prune_marker_doc(&mut projected_doc, Some(source_id));
-    validate_marker_doc(path, &projected_doc)
-}
-
-/// Retain a deterministic newest-first source window. `keep_source_id` is the
-/// source currently being restored; it is never evicted by older capturedAt
-/// metadata while its write-ahead state is being updated.
-pub(super) fn prune_marker_doc(doc: &mut MarkerDoc, keep_source_id: Option<&str>) {
-    if doc.len() <= MAX_RESTORE_MARKER_SOURCES {
-        return;
-    }
-    let mut ranked: Vec<(i64, String)> = doc
-        .iter()
-        .filter(|(source_id, _)| keep_source_id != Some(source_id.as_str()))
-        .map(|(source_id, (at, _))| (*at, source_id.clone()))
-        .collect();
-    ranked.sort_by(|a, b| b.cmp(a));
-    let other_limit = MAX_RESTORE_MARKER_SOURCES
-        - usize::from(keep_source_id.is_some_and(|id| doc.contains_key(id)));
-    let retained: std::collections::HashSet<String> = ranked
-        .into_iter()
-        .take(other_limit)
-        .map(|(_, source_id)| source_id)
-        .collect();
-    doc.retain(|source_id, _| {
-        keep_source_id == Some(source_id.as_str()) || retained.contains(source_id)
-    });
-}
-
-/// Durable atomic write of the WHOLE ledger: the temporary file is synced,
-/// renamed, and the parent directory is synced before success is reported.
-/// Returns Err so the handler fails LOUDLY. Blocking fs — call via
-/// `spawn_blocking` under `freshell_ws::tabs_persist::with_persist_lock`.
-pub(super) fn write_marker_doc(device_dir: &Path, doc: &MarkerDoc) -> std::io::Result<()> {
-    std::fs::create_dir_all(device_dir)?;
-    let mut bounded = doc.clone();
-    prune_marker_doc(&mut bounded, None);
-    let destination = device_dir.join(RESTORE_MARKER);
-    validate_marker_doc(&destination, &bounded)?;
-    let bytes = serde_json::to_vec(&MarkerFile(&bounded))
-        .map_err(|error| std::io::Error::other(format!("restore marker serialization: {error}")))?;
-    debug_assert!(bytes.len() <= MAX_RESTORE_MARKER_BYTES);
-    let tmp = device_dir.join(RESTORE_MARKER_TMP);
-    freshell_ws::tabs_persist::atomic_write_durable(&destination, &tmp, &bytes)
-}
diff --git a/crates/freshell-server/src/tabs_snapshots_restore_tests.rs b/crates/freshell-server/src/tabs_snapshots_restore_tests.rs
deleted file mode 100644
index 3dbaa6414..000000000
--- a/crates/freshell-server/src/tabs_snapshots_restore_tests.rs
+++ /dev/null
@@ -1,1348 +0,0 @@
-//! Restore-hardening tests (cross-model review delta r1): marker ledger
-//! idempotency across source switches, fail-loud marker reads, fail-closed
-//! body selectors, loud missing-component bundles, full pane-state
-//! round-trips, the write-ahead crash window, invocation-unique delivery-ack
-//! ids, and the targeted `panes` filter. Nested `#[path]`-included child of
-//! `tabs_snapshots_tests.rs` so both files stay under the repo's
-//! 1,000-line-per-file limit; helpers (`rig`/`connected`/`post`/`rec`/...)
-//! come from the parent test module.
-
-use super::*;
-
-/// Drain every frame currently buffered on a broadcast receiver.
-fn drain(rx: &mut tokio::sync::broadcast::Receiver<String>) -> Vec<Value> {
-    let mut out = Vec::new();
-    while let Ok(frame) = rx.try_recv() {
-        if let Ok(v) = serde_json::from_str::<Value>(&frame) {
-            out.push(v);
-        }
-    }
-    out
-}
-fn tab_creates(frames: &[Value]) -> Vec<Value> {
-    frames
-        .iter()
-        .filter(|v| v["type"] == "ui.command" && v["command"] == "tab.create")
-        .map(|v| v["payload"].clone())
-        .collect()
-}
-fn ack_request_ids(frames: &[Value]) -> Vec<String> {
-    frames
-        .iter()
-        .filter(|v| v["type"] == "ui.command" && v["command"] == "screenshot.capture")
-        .filter_map(|v| v["payload"]["requestId"].as_str().map(str::to_string))
-        .collect()
-}
-fn device_dir(dir: &std::path::Path, device: &str) -> std::path::PathBuf {
-    dir.join(freshell_ws::tabs_persist::encode_device_id(device).unwrap())
-}
-fn union_source_id(dir: &std::path::Path, device: &str) -> String {
-    let snap = freshell_ws::tabs_persist::read_device_union(dir, device)
-        .unwrap()
-        .expect("seeded union");
-    freshell_ws::tabs_persist::snapshot_content_id(&snap)
-}
-fn gen_id(dir: &std::path::Path, device: &str, n: usize) -> String {
-    let snap = freshell_ws::tabs_persist::read_generation(dir, device, n)
-        .unwrap()
-        .expect("generation present");
-    freshell_ws::tabs_persist::snapshot_generation_id(&snap)
-}
-
-#[tokio::test]
-async fn restore_history_survives_source_switch_a_b_a() {
-    // MARKER LEDGER (`:304`): restore A, then B, then A again — A's panes must
-    // be skipped `already-restored`, never duplicated, even though B was
-    // restored in between (a single last-source marker would have wiped A).
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "tA",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    let id_a = gen_id(dir.path(), "dev-1", 0);
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        2,
-        vec![rec(
-            "tB",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    let id_b = gen_id(dir.path(), "dev-1", 0);
-    assert_ne!(id_a, id_b);
-    let (r, _on, _h) = connected(dir.path());
-    let go = |gid: String, r: &Rig| {
-        let router = router(r.state.clone());
-        async move {
-            post(
-                router,
-                "/api/tabs-sync/restore",
-                json!({ "deviceId": "dev-1", "generationId": gid }),
-                true,
-            )
-            .await
-            .1
-        }
-    };
-    let first_a = go(id_a.clone(), &r).await;
-    assert_eq!(
-        first_a["restored"].as_array().unwrap().len(),
-        1,
-        "{first_a}"
-    );
-    let first_b = go(id_b.clone(), &r).await;
-    assert_eq!(
-        first_b["restored"].as_array().unwrap().len(),
-        1,
-        "{first_b}"
-    );
-    // A again: NOTHING recreated (its history survived B's restore).
-    let second_a = go(id_a.clone(), &r).await;
-    assert_eq!(
-        second_a["restored"].as_array().unwrap().len(),
-        0,
-        "A's panes must not be duplicated after restoring B: {second_a}"
-    );
-    assert_eq!(second_a["skipped"][0]["reason"], "already-restored");
-}
-
-#[tokio::test]
-async fn corrupt_marker_fails_loud_409_and_force_overrides() {
-    // FAIL-LOUD MARKER READS (`:306`): a present-but-unparsable marker is a
-    // 409 telling the operator how to proceed — never "nothing restored yet".
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    let dd = device_dir(dir.path(), "dev-1");
-    std::fs::write(dd.join(RESTORE_MARKER), b"{ not json").unwrap();
-    let (r, _on, _h) = connected(dir.path());
-    let (status, body) = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::CONFLICT, "{body}");
-    assert_eq!(body["markerError"], true);
-    assert!(
-        body["error"].as_str().unwrap().contains("force"),
-        "must tell the operator how to proceed: {body}"
-    );
-    // force:true is the explicit override: discard the unreadable ledger.
-    let (status, body) = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "force": true }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::OK, "{body}");
-    assert_eq!(body["restored"].as_array().unwrap().len(), 1);
-}
-
-#[tokio::test]
-async fn unreadable_marker_fails_loud_409() {
-    // An UNREADABLE (not merely corrupt) marker — here the path is a
-    // directory, so read fails with EISDIR — must also refuse loudly.
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    std::fs::create_dir(device_dir(dir.path(), "dev-1").join(RESTORE_MARKER)).unwrap();
-    let (r, _on, _h) = connected(dir.path());
-    let (status, body) = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::CONFLICT, "{body}");
-    assert_eq!(body["markerError"], true);
-}
-
-#[test]
-fn semantically_corrupt_marker_documents_are_rejected() {
-    let dir = tempfile::tempdir().unwrap();
-    let dd = device_dir(dir.path(), "dev-1");
-    std::fs::create_dir_all(&dd).unwrap();
-    for bad in [
-        json!({ "version": 99, "sources": {} }),
-        json!({ "version": 2, "sources": { "source": {} } }),
-        json!({ "version": 2, "sources": { "source": { "at": 1 } } }),
-        json!({ "version": 2, "sources": { "source": { "panes": {} } } }),
-        json!({ "version": 2, "sources": { "source": {
-            "at": 1, "panes": { "tab#pane": { "state": "garbage", "terminalId": null } }
-        } } }),
-    ] {
-        std::fs::write(
-            dd.join(RESTORE_MARKER),
-            serde_json::to_vec_pretty(&bad).unwrap(),
-        )
-        .unwrap();
-        assert!(
-            read_marker_doc(&dd).is_err(),
-            "semantically corrupt marker was accepted: {bad}"
-        );
-    }
-}
-
-#[test]
-fn marker_ledger_retention_bounds_sources_and_keeps_the_newest() {
-    let dir = tempfile::tempdir().unwrap();
-    let dd = device_dir(dir.path(), "dev-1");
-    let mut doc = MarkerDoc::new();
-    for n in 0..(MAX_RESTORE_MARKER_SOURCES + 7) {
-        let mut panes = Marker::new();
-        panes.insert(
-            format!("tab-{n}#pane"),
-            PaneMark {
-                state: "restored".into(),
-                terminal_id: Some(format!("terminal-{n}")),
-            },
-        );
-        doc.insert(format!("source-{n:03}"), (n as i64, panes));
-    }
-    write_marker_doc(&dd, &doc).unwrap();
-    let retained = read_marker_doc(&dd).unwrap();
-    assert_eq!(retained.len(), MAX_RESTORE_MARKER_SOURCES);
-    assert!(retained.contains_key(&format!("source-{:03}", MAX_RESTORE_MARKER_SOURCES + 6)));
-    assert!(!retained.contains_key("source-000"));
-
-    // The source currently being updated remains even when it is older than
-    // every other entry; pruning may evict the next-oldest source instead.
-    let mut with_active = doc;
-    prune_marker_doc(&mut with_active, Some("source-000"));
-    assert_eq!(with_active.len(), MAX_RESTORE_MARKER_SOURCES);
-    assert!(with_active.contains_key("source-000"));
-}
-
-#[test]
-fn marker_serialized_byte_cap_accepts_boundary_and_rejects_over() {
-    let dir = tempfile::tempdir().unwrap();
-    let dd = device_dir(dir.path(), "dev-1");
-    std::fs::create_dir_all(&dd).unwrap();
-    let mut bytes = br#"{"version":2,"sources":{}}"#.to_vec();
-    bytes.resize(MAX_RESTORE_MARKER_BYTES, b' ');
-    std::fs::write(dd.join(RESTORE_MARKER), &bytes).unwrap();
-    assert!(
-        read_marker_doc(&dd).is_ok(),
-        "a marker exactly at the byte cap must remain readable"
-    );
-
-    bytes.push(b' ');
-    std::fs::write(dd.join(RESTORE_MARKER), &bytes).unwrap();
-    let error = match read_marker_doc(&dd) {
-        Ok(_) => panic!("over-cap marker must fail loudly"),
-        Err(error) => error,
-    };
-    assert!(
-        error.to_string().contains("byte limit"),
-        "clear byte-cap error: {error}"
-    );
-}
-
-#[test]
-fn marker_pane_count_cap_accepts_boundary_and_rejects_over() {
-    let path = std::path::Path::new("<marker-count-test>");
-    assert!(
-        validate_marker_pane_count(path, "source", MAX_RESTORE_MARKER_PANES_PER_SOURCE).is_ok()
-    );
-    let error = validate_marker_pane_count(path, "source", MAX_RESTORE_MARKER_PANES_PER_SOURCE + 1)
-        .expect_err("over-cap pane count must fail loudly");
-    assert!(
-        error.to_string().contains("pane-count limit"),
-        "clear pane-count error: {error}"
-    );
-}
-
-#[test]
-fn marker_identifier_caps_accept_boundaries_and_reject_over() {
-    fn doc(source: String, pane_key: String, terminal_id: String) -> MarkerDoc {
-        let mut panes = Marker::new();
-        panes.insert(
-            pane_key,
-            PaneMark {
-                state: "restored".into(),
-                terminal_id: Some(terminal_id),
-            },
-        );
-        MarkerDoc::from([(source, (1, panes))])
-    }
-
-    let dir = tempfile::tempdir().unwrap();
-    let dd = device_dir(dir.path(), "dev-1");
-    write_marker_doc(
-        &dd,
-        &doc(
-            "s".repeat(MAX_RESTORE_MARKER_SOURCE_ID_BYTES),
-            "p".repeat(MAX_RESTORE_MARKER_PANE_KEY_BYTES),
-            "t".repeat(MAX_RESTORE_MARKER_TERMINAL_ID_BYTES),
-        ),
-    )
-    .expect("identifier lengths exactly at their caps are accepted");
-
-    for (name, over) in [
-        (
-            "source id",
-            doc(
-                "s".repeat(MAX_RESTORE_MARKER_SOURCE_ID_BYTES + 1),
-                "pane".into(),
-                "terminal".into(),
-            ),
-        ),
-        (
-            "pane key",
-            doc(
-                "source".into(),
-                "p".repeat(MAX_RESTORE_MARKER_PANE_KEY_BYTES + 1),
-                "terminal".into(),
-            ),
-        ),
-        (
-            "terminal id",
-            doc(
-                "source".into(),
-                "pane".into(),
-                "t".repeat(MAX_RESTORE_MARKER_TERMINAL_ID_BYTES + 1),
-            ),
-        ),
-    ] {
-        let error = match write_marker_doc(&dd, &over) {
-            Ok(()) => panic!("over-cap {name} must fail loudly"),
-            Err(error) => error,
-        };
-        assert!(
-            error.to_string().contains("identifier length limit"),
-            "clear {name} error: {error}"
-        );
-    }
-}
-
-#[tokio::test]
-async fn restore_rejects_over_limit_marker_plan_before_side_effects() {
-    let dir = tempfile::tempdir().unwrap();
-    let mut record = rec(
-        "t1",
-        "browser",
-        json!({ "url": "https://example.com", "devToolsOpen": false }),
-    );
-    record["tabKey"] = json!("k".repeat(MAX_RESTORE_MARKER_PANE_KEY_BYTES + 1));
-    seed_records(dir.path(), "dev-1", "c1", 1, vec![record]);
-    let (r, _on, _client) = connected(dir.path());
-
-    let (status, body) = post(
-        router(r.state),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::CONFLICT, "{body}");
-    assert_eq!(body["markerError"], true, "{body}");
-    assert!(
-        body["error"]
-            .as_str()
-            .is_some_and(|error| error.contains("limit")),
-        "{body}"
-    );
-    assert!(
-        !device_dir(dir.path(), "dev-1")
-            .join(RESTORE_MARKER)
-            .exists(),
-        "preflight rejection must not write a marker or create a pane"
-    );
-}
-
-#[tokio::test]
-async fn write_ahead_marker_is_durable_before_tab_create_is_sent() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "browser",
-            json!({ "url": "https://example.com", "devToolsOpen": false }),
-        )],
-    );
-    let r = rig(dir.path());
-    let broker = r.state.screenshots.clone();
-    let dd = device_dir(dir.path(), "dev-1");
-    let saw_write_ahead = std::sync::Arc::new(AtomicBool::new(false));
-    let saw_write_ahead_in_sink = saw_write_ahead.clone();
-    let client_id = 9_001;
-    r.state.screenshots.add_capable_client(
-        client_id,
-        std::sync::Arc::new(move |message| {
-            let value = serde_json::to_value(message).unwrap();
-            if value["type"] == "ui.command" && value["command"] == "tab.create" {
-                let marker = read_marker_doc(&dd).expect("write-ahead marker is durable");
-                let panes = &marker.values().next().expect("source exists").1;
-                assert_eq!(
-                    panes.get("dev-1:t1#p-t1").map(|mark| mark.state.as_str()),
-                    Some("in-progress"),
-                    "tab.create must not be sent before its durable write-ahead entry"
-                );
-                saw_write_ahead_in_sink.store(true, Ordering::SeqCst);
-            }
-            if value["type"] == "ui.command" && value["command"] == "screenshot.capture" {
-                broker.resolve_from(
-                    client_id,
-                    value["payload"]["requestId"].as_str().unwrap(),
-                    freshell_ws::screenshot::ScreenshotResult {
-                        ok: true,
-                        ..Default::default()
-                    },
-                );
-            }
-            true
-        }),
-    );
-
-    let (status, body) = post(
-        router(r.state),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::OK, "{body}");
-    assert!(saw_write_ahead.load(Ordering::SeqCst));
-}
-
-#[tokio::test]
-async fn dropped_ack_sender_is_not_delivery_confirmation() {
-    // A dropped oneshot sender (the pending ack entry was cancelled/purged
-    // before the client answered) resolves the receiver with `Err(RecvError)`.
-    // That is NOT a delivery ack: the pane must be reported failed
-    // (`delivery-unconfirmed`) and stay `in-progress` for a safe retry.
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "browser",
-            json!({ "url": "https://example.com", "devToolsOpen": false }),
-        )],
-    );
-    let r = rig(dir.path());
-    let broker = r.state.screenshots.clone();
-    let client_id = 9_102;
-    r.state.screenshots.add_capable_client(
-        client_id,
-        std::sync::Arc::new(move |message| {
-            let value = serde_json::to_value(message).unwrap();
-            if value["type"] == "ui.command" && value["command"] == "screenshot.capture" {
-                // Simulate the pending ack being purged (sender dropped)
-                // instead of answered by the client.
-                broker.cancel(value["payload"]["requestId"].as_str().unwrap());
-            }
-            true
-        }),
-    );
-
-    let (status, body) = post(
-        router(r.state),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::OK, "{body}");
-    assert_eq!(
-        body["deliveryConfirmed"], false,
-        "a dropped ack sender must not read as confirmation: {body}"
-    );
-    let failed = body["failed"].as_array().unwrap();
-    assert_eq!(failed.len(), 1, "{body}");
-    assert_eq!(failed[0]["reason"], "delivery-unconfirmed", "{body}");
-    assert_eq!(body["restored"].as_array().unwrap().len(), 0, "{body}");
-    assert_eq!(
-        marker_panes(dir.path(), "dev-1")["dev-1:t1#p-t1"]["state"],
-        "in-progress",
-        "unconfirmed delivery must keep the write-ahead entry for retry"
-    );
-}
-
-#[tokio::test]
-async fn restore_rejects_malformed_body_selectors_with_400_never_broader_union() {
-    // FAIL-CLOSED BODY SELECTORS (`:459`): every malformed shape is a 400 —
-    // never a silent fall-through to the broader coherent union. dryRun keeps
-    // the client gate out of the way (parsing runs regardless).
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    for bad in [
-        json!({ "deviceId": "dev-1", "dryRun": true, "generation": -1 }),
-        json!({ "deviceId": "dev-1", "dryRun": true, "generation": "3" }), // wrong type
-        json!({ "deviceId": "dev-1", "dryRun": true, "generation": 1.5 }),
-        json!({ "deviceId": "dev-1", "dryRun": true, "generation": true }),
-        json!({ "deviceId": "dev-1", "dryRun": true, "generationId": 5 }), // wrong type
-        json!({ "deviceId": "dev-1", "dryRun": true, "generationId": "" }),
-        json!({ "deviceId": "dev-1", "dryRun": true, "components": "abc" }), // non-array
-        json!({ "deviceId": "dev-1", "dryRun": true, "components": [1] }),   // non-string entry
-        json!({ "deviceId": "dev-1", "dryRun": true, "components": [""] }),
-        json!({ "deviceId": "dev-1", "dryRun": true, "components": [] }),
-        json!({ "deviceId": "dev-1", "dryRun": true, "components": ["a"], "generationId": "b" }),
-        json!({ "deviceId": "dev-1", "dryRun": true, "panes": "x" }), // non-array
-        json!({ "deviceId": "dev-1", "dryRun": true, "panes": [1] }),
-        json!({ "deviceId": "dev-1", "dryRun": true, "panes": [] }),
-    ] {
-        let (status, body) = post(
-            router(test_state(dir.path())),
-            "/api/tabs-sync/restore",
-            bad.clone(),
-            true,
-        )
-        .await;
-        assert_eq!(status, StatusCode::BAD_REQUEST, "must 400: {bad} -> {body}");
-    }
-}
-
-#[tokio::test]
-async fn restore_components_fails_loud_when_any_component_is_pruned() {
-    // MISSING COMPONENT BUNDLES (`tabs_persist.rs:232`): one present + one
-    // pruned component must refuse loudly NAMING the missing id — a partial
-    // union restored with `failed=0` would silently convert an incomplete
-    // recovery into success.
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    let present = gen_id(dir.path(), "dev-1", 0);
-    let pruned = "deadbeefdeadbeefdeadbeefdeadbeef".to_string();
-    let (status, body) = post(
-        router(test_state(dir.path())),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "dryRun": true,
-                "components": [present, pruned] }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::CONFLICT, "{body}");
-    assert_eq!(
-        body["missingComponents"],
-        json!(["deadbeefdeadbeefdeadbeefdeadbeef"])
-    );
-    assert!(body["error"]
-        .as_str()
-        .unwrap()
-        .contains("deadbeefdeadbeefdeadbeefdeadbeef"));
-}
-
-#[test]
-fn create_body_carries_full_terminal_state_including_codex_durability() {
-    // `:245` unit slice: the codex pane's captured shell + codexDurability
-    // flow into the create body (the codex CLI itself can't spawn in tests,
-    // so the freshagent leg for codexDurability is proven at body level here
-    // and end-to-end for shell/browser/editor below).
-    let pane = json!({ "paneId": "p1", "kind": "terminal", "payload": {
-        "mode": "codex", "shell": "wsl", "initialCwd": "/tmp",
-        "codexDurability": { "schemaVersion": 1, "state": "durable" },
-        "sessionRef": { "provider": "codex", "sessionId": "s-1" }
-    }});
-    let body = pane_to_create_body(None, &pane).unwrap();
-    assert_eq!(body["shell"], "wsl");
-    assert_eq!(body["codexDurability"]["state"], "durable");
-    assert_eq!(body["sessionRef"]["sessionId"], "s-1");
-}
-
-#[test]
-fn create_body_carries_create_request_id_and_omits_when_absent() {
-    // Captured key passes through (P1.6: snapshot-restored panes keep identity).
-    let pane = json!({ "paneId": "p1", "kind": "terminal", "payload": {
-        "mode": "shell", "shell": "system",
-        "createRequestId": "crid-from-snapshot"
-    }});
-    let body = pane_to_create_body(None, &pane).unwrap();
-    assert_eq!(body["createRequestId"], "crid-from-snapshot");
-
-    // Legacy snapshot without the field: body omits it entirely (the REST
-    // ingress mints a fresh key in that case — never emit null/empty).
-    let legacy = json!({ "paneId": "p2", "kind": "terminal", "payload": {
-        "mode": "shell", "shell": "system"
-    }});
-    let legacy_body = pane_to_create_body(None, &legacy).unwrap();
-    assert!(legacy_body.get("createRequestId").is_none());
-
-    // Wrong-typed field is dropped, not an error (same tolerance as shell/cwd).
-    let wrong = json!({ "paneId": "p3", "kind": "terminal", "payload": {
-        "mode": "shell", "createRequestId": 42
-    }});
-    let wrong_body = pane_to_create_body(None, &wrong).unwrap();
-    assert!(wrong_body.get("createRequestId").is_none());
-}
-
-#[tokio::test]
-async fn restore_round_trips_non_default_pane_state_to_the_client() {
-    // FULL PANE STATE (`:245`): NON-default captured values must reach the
-    // frozen client's `tab.create` paneContent — terminal `shell`, browser
-    // `devToolsOpen`, editor `language`/`readOnly`/`viewMode`/`wordWrap`.
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![
-            rec(
-                "t1",
-                "terminal",
-                json!({ "mode": "shell", "shell": "wsl", "initialCwd": "/tmp" }),
-            ),
-            rec(
-                "t2",
-                "browser",
-                json!({ "url": "https://example.com", "devToolsOpen": true }),
-            ),
-            rec(
-                "t3",
-                "editor",
-                json!({ "filePath": "/tmp/x.md", "language": "markdown",
-                        "readOnly": true, "viewMode": "preview", "wordWrap": false }),
-            ),
-        ],
-    );
-    let (r, _on, _h) = connected(dir.path());
-    let mut rx = r.bus.subscribe();
-    let body = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-    assert_eq!(body["restored"].as_array().unwrap().len(), 3, "{body}");
-    let creates = tab_creates(&drain(&mut rx));
-    let by_kind = |k: &str| {
-        creates
-            .iter()
-            .find(|p| p["paneContent"]["kind"] == k)
-            .unwrap_or_else(|| panic!("no {k} tab.create broadcast"))
-            .clone()
-    };
-    assert_eq!(by_kind("terminal")["paneContent"]["shell"], "wsl");
-    assert_eq!(by_kind("browser")["paneContent"]["devToolsOpen"], true);
-    let ed = by_kind("editor");
-    assert_eq!(ed["paneContent"]["language"], "markdown");
-    assert_eq!(ed["paneContent"]["readOnly"], true);
-    assert_eq!(ed["paneContent"]["viewMode"], "preview");
-    assert_eq!(ed["paneContent"]["wordWrap"], false);
-}
-
-#[tokio::test]
-async fn restore_round_trips_scratch_editor_with_null_file_path() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "scratch",
-            "editor",
-            json!({
-                "filePath": null,
-                "language": null,
-                "readOnly": false,
-                "viewMode": "source",
-                "wordWrap": true,
-            }),
-        )],
-    );
-    let (r, _on, _client) = connected(dir.path());
-    let mut frames = r.bus.subscribe();
-    let body = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-
-    assert_eq!(body["failed"], json!([]), "{body}");
-    assert_eq!(body["restored"].as_array().unwrap().len(), 1, "{body}");
-    let creates = tab_creates(&drain(&mut frames));
-    assert_eq!(creates.len(), 1);
-    assert_eq!(creates[0]["paneContent"]["kind"], "editor");
-    assert_eq!(creates[0]["paneContent"]["filePath"], Value::Null);
-}
-
-#[tokio::test]
-async fn crash_window_terminal_reconciles_via_restore_key_ledger() {
-    // CRASH WINDOW (`:632`), terminal leg: the create succeeded but NEITHER
-    // marker write after it landed (in-progress entry with NO terminalId on
-    // disk). The create was tagged with the deterministic restoreKey, so a
-    // same-process retry finds the live terminal and its DEFERRED tab.create
-    // in the fresh-agent ledger. The retry must deliver that command before
-    // accepting the screenshot fence, without spawning a duplicate.
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    let (r, _on, _h) = connected(dir.path());
-    let source_id = union_source_id(dir.path(), "dev-1");
-    let pk = pane_key("dev-1:t1", "p-t1");
-    let key = restore_key_for("dev-1", &source_id, &pk);
-    let mut rx = r.bus.subscribe();
-    // Exercise the production restore create path: the process was created,
-    // but the deferred tab.create was never sent.
-    let resp = freshell_freshagent::terminal_tabs::create_terminal_or_content_tab_deferred(
-        r.state.fresh_agent.clone(),
-        json!({ "mode": "shell", "cwd": "/tmp", "restoreKey": key }),
-    )
-    .await;
-    let rbytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
-        .await
-        .unwrap();
-    let created: Value = serde_json::from_slice(&rbytes).unwrap();
-    let tid = created["data"]["terminalId"].as_str().unwrap().to_string();
-    assert!(r.terminals.is_running(&tid));
-    // ...but the on-disk marker never got past the write-ahead entry.
-    let mut doc = MarkerDoc::new();
-    let mut panes = Marker::new();
-    panes.insert(
-        pk.clone(),
-        PaneMark {
-            state: "in-progress".into(),
-            terminal_id: None,
-        },
-    );
-    doc.insert(source_id.clone(), (0, panes));
-    write_marker_doc(&device_dir(dir.path(), "dev-1"), &doc).unwrap();
-    // Retry: reconciled to the SAME terminal — no duplicate create.
-    let body = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-    let rec0 = &body["restored"][0];
-    assert_eq!(rec0["reconciled"], true, "{body}");
-    assert_eq!(rec0["terminalId"], tid.as_str(), "no duplicate: {body}");
-    assert_eq!(body["failed"].as_array().unwrap().len(), 0);
-    let creates = tab_creates(&drain(&mut rx));
-    assert_eq!(
-        creates.len(),
-        1,
-        "retry must deliver deferred create: {body}"
-    );
-    assert_eq!(creates[0]["terminalId"], tid);
-}
-
-#[tokio::test]
-async fn reconciled_delivery_drop_fails_and_stops_before_later_panes() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![
-            rec(
-                "t1",
-                "terminal",
-                json!({ "mode": "shell", "initialCwd": "/tmp" }),
-            ),
-            rec(
-                "t2",
-                "terminal",
-                json!({ "mode": "shell", "initialCwd": "/tmp" }),
-            ),
-        ],
-    );
-    let r = rig(dir.path());
-    let source_id = union_source_id(dir.path(), "dev-1");
-    let first_pk = pane_key("dev-1:t1", "p-t1");
-    let key = restore_key_for("dev-1", &source_id, &first_pk);
-    let resp = freshell_freshagent::terminal_tabs::create_terminal_or_content_tab_deferred(
-        r.state.fresh_agent.clone(),
-        json!({ "mode": "shell", "cwd": "/tmp", "restoreKey": key }),
-    )
-    .await;
-    let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
-        .await
-        .unwrap();
-    let created: Value = serde_json::from_slice(&bytes).unwrap();
-    let first_tid = created["data"]["terminalId"].as_str().unwrap().to_string();
-    let mut panes = Marker::new();
-    panes.insert(
-        first_pk,
-        PaneMark {
-            state: "in-progress".into(),
-            terminal_id: Some(first_tid.clone()),
-        },
-    );
-    let mut doc = MarkerDoc::new();
-    doc.insert(source_id, (0, panes));
-    write_marker_doc(&device_dir(dir.path(), "dev-1"), &doc).unwrap();
-
-    let frames = std::sync::Arc::new(std::sync::Mutex::new(Vec::<Value>::new()));
-    let frames_for_sink = frames.clone();
-    r.state.screenshots.add_capable_client(
-        811,
-        std::sync::Arc::new(move |message| {
-            frames_for_sink
-                .lock()
-                .unwrap()
-                .push(serde_json::to_value(message).unwrap());
-            true
-        }),
-    );
-    let body = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-
-    assert_eq!(body["restored"].as_array().unwrap().len(), 0, "{body}");
-    assert_eq!(body["skipped"].as_array().unwrap().len(), 0, "{body}");
-    assert_eq!(
-        body["failed"][0]["reason"], "delivery-unconfirmed",
-        "{body}"
-    );
-    assert_eq!(body["failed"][0]["terminalId"], first_tid, "{body}");
-    assert_eq!(body["failed"][1]["reason"], "connection-dropped", "{body}");
-    let creates = tab_creates(&frames.lock().unwrap());
-    assert_eq!(creates.len(), 1, "later pane must not be created: {body}");
-    assert_eq!(
-        r.terminals.inventory().len(),
-        1,
-        "only reconciled terminal exists"
-    );
-}
-
-#[tokio::test]
-async fn retry_replays_create_when_target_connection_changes() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    let r = rig(dir.path());
-    let first_on = std::sync::Arc::new(AtomicBool::new(false));
-    let first_client = spawn_browser(&r, first_on);
-    let first = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-    let terminal_id = first["failed"][0]["terminalId"]
-        .as_str()
-        .unwrap()
-        .to_string();
-    r.state.screenshots.remove_capable_client(first_client);
-
-    let second_on = std::sync::Arc::new(AtomicBool::new(true));
-    let _second_client = spawn_browser(&r, second_on);
-    let mut rx = r.bus.subscribe();
-    let second = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-
-    assert_eq!(second["restored"][0]["terminalId"], terminal_id, "{second}");
-    let creates = tab_creates(&drain(&mut rx));
-    assert_eq!(
-        creates.len(),
-        1,
-        "new target must receive the existing terminal's create: {second}"
-    );
-    assert_eq!(creates[0]["terminalId"], terminal_id);
-}
-
-#[tokio::test]
-async fn force_recreates_content_pane_in_same_server_process() {
-    for (kind, payload) in [
-        (
-            "browser",
-            json!({ "url": "https://example.com", "devToolsOpen": false }),
-        ),
-        (
-            "editor",
-            json!({ "filePath": "/tmp/x.md", "language": "markdown", "readOnly": false,
-                    "viewMode": "preview", "wordWrap": true }),
-        ),
-    ] {
-        let dir = tempfile::tempdir().unwrap();
-        seed_records(dir.path(), "dev-1", "c1", 1, vec![rec("t1", kind, payload)]);
-        let (r, _on, _client) = connected(dir.path());
-        let first = post(
-            router(r.state.clone()),
-            "/api/tabs-sync/restore",
-            json!({ "deviceId": "dev-1" }),
-            true,
-        )
-        .await
-        .1;
-        let original_tab_id = first["restored"][0]["tabId"].as_str().unwrap().to_string();
-        let mut rx = r.bus.subscribe();
-        let forced = post(
-            router(r.state.clone()),
-            "/api/tabs-sync/restore",
-            json!({ "deviceId": "dev-1", "force": true }),
-            true,
-        )
-        .await
-        .1;
-
-        assert_eq!(forced["restored"].as_array().unwrap().len(), 1, "{forced}");
-        assert_ne!(forced["restored"][0]["tabId"], original_tab_id, "{forced}");
-        assert_ne!(forced["restored"][0]["reconciled"], true, "{forced}");
-        let frames = drain(&mut rx);
-        let closes: Vec<_> = frames
-            .iter()
-            .filter(|v| v["command"] == "tab.close")
-            .collect();
-        assert_eq!(closes.len(), 1, "{kind}: force should retire stale tab");
-        assert_eq!(closes[0]["payload"]["id"], original_tab_id);
-        assert_eq!(tab_creates(&frames).len(), 1, "{kind}: missing create");
-    }
-}
-
-#[tokio::test]
-async fn forced_terminal_retry_closes_and_replays_one_stable_identity() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    let (r, _on, first_client) = connected(dir.path());
-    let first = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-    let original_tab_id = first["restored"][0]["tabId"].as_str().unwrap().to_string();
-    let terminal_id = first["restored"][0]["terminalId"]
-        .as_str()
-        .unwrap()
-        .to_string();
-    r.state.screenshots.remove_capable_client(first_client);
-
-    let first_attempt_frames = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
-    let first_attempt_sink = first_attempt_frames.clone();
-    r.state.screenshots.add_capable_client(
-        850,
-        std::sync::Arc::new(move |message| {
-            first_attempt_sink
-                .lock()
-                .unwrap()
-                .push(serde_json::to_value(message).unwrap());
-            true
-        }),
-    );
-    let unconfirmed = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "force": true }),
-        true,
-    )
-    .await
-    .1;
-    assert_eq!(
-        unconfirmed["failed"][0]["reason"], "delivery-unconfirmed",
-        "{unconfirmed}"
-    );
-    let first_attempt_frames = first_attempt_frames.lock().unwrap().clone();
-    let first_close = first_attempt_frames
-        .iter()
-        .find(|frame| frame["command"] == "tab.close")
-        .unwrap();
-    let first_create = tab_creates(&first_attempt_frames);
-    assert_eq!(first_close["payload"]["id"], original_tab_id);
-    assert_eq!(first_create.len(), 1);
-    assert_eq!(first_create[0]["id"], original_tab_id);
-
-    r.state.screenshots.remove_capable_client(850);
-    let responsive = std::sync::Arc::new(AtomicBool::new(true));
-    let _retry_client = spawn_browser(&r, responsive);
-    let mut retry_frames = r.bus.subscribe();
-    let retry = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "force": true }),
-        true,
-    )
-    .await
-    .1;
-    assert_eq!(retry["failed"], json!([]), "{retry}");
-    assert_eq!(retry["restored"][0]["tabId"], original_tab_id, "{retry}");
-    assert_eq!(retry["restored"][0]["terminalId"], terminal_id, "{retry}");
-    let retry_frames = drain(&mut retry_frames);
-    let retry_close = retry_frames
-        .iter()
-        .find(|frame| frame["command"] == "tab.close")
-        .unwrap();
-    let retry_create = tab_creates(&retry_frames);
-    assert_eq!(retry_close["payload"]["id"], original_tab_id);
-    assert_eq!(retry_create.len(), 1);
-    assert_eq!(retry_create[0]["id"], original_tab_id);
-    assert_eq!(
-        r.terminals.inventory().len(),
-        1,
-        "unconfirmed delivery and retry must not spawn or orphan another PTY"
-    );
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn active_restore_survives_production_device_eviction_interleaving() {
-    let dir = tempfile::tempdir().unwrap();
-    for n in 0..freshell_ws::tabs_persist::MAX_SNAPSHOT_DEVICES {
-        let device = format!("dev-{n:03}");
-        seed_records(
-            dir.path(),
-            &device,
-            "c1",
-            1,
-            vec![rec(
-                "t1",
-                "terminal",
-                json!({ "mode": "shell", "initialCwd": "/tmp" }),
-            )],
-        );
-        let device_dir = device_dir(dir.path(), &device);
-        let generation = std::fs::read_dir(&device_dir)
-            .unwrap()
-            .flatten()
-            .map(|entry| entry.path())
-            .find(|path| path.extension().is_some_and(|ext| ext == "json"))
-            .unwrap();
-        let mut value: Value =
-            serde_json::from_slice(&std::fs::read(&generation).unwrap()).unwrap();
-        value["capturedAt"] = json!(n as i64 + 1);
-        std::fs::write(generation, serde_json::to_vec_pretty(&value).unwrap()).unwrap();
-    }
-    let source_dir = device_dir(dir.path(), "dev-000");
-    let r = rig(dir.path());
-    let (fence_tx, fence_rx) = tokio::sync::oneshot::channel();
-    let fence_tx = std::sync::Arc::new(std::sync::Mutex::new(Some(fence_tx)));
-    let fence_for_sink = fence_tx.clone();
-    r.state.screenshots.add_capable_client(
-        912,
-        std::sync::Arc::new(move |message| {
-            let value = serde_json::to_value(message).unwrap();
-            if value["command"] == "screenshot.capture" {
-                if let Some(tx) = fence_for_sink.lock().unwrap().take() {
-                    let _ = tx.send(());
-                }
-            }
-            true
-        }),
-    );
-    let app = router(r.state.clone());
-    let restore = tokio::spawn(async move {
-        post(
-            app,
-            "/api/tabs-sync/restore",
-            json!({ "deviceId": "dev-000" }),
-            true,
-        )
-        .await
-        .1
-    });
-    fence_rx.await.expect("restore reached delivery fence");
-
-    seed_records(
-        dir.path(),
-        "dev-new-1",
-        "c1",
-        1,
-        vec![rec(
-            "new1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    assert!(source_dir.exists(), "active restore source was evicted");
-    assert!(
-        source_dir.join(RESTORE_MARKER).exists(),
-        "active restore marker was evicted"
-    );
-    let body = restore.await.unwrap();
-    assert_eq!(
-        body["failed"][0]["reason"], "delivery-unconfirmed",
-        "{body}"
-    );
-
-    seed_records(
-        dir.path(),
-        "dev-new-2",
-        "c1",
-        1,
-        vec![rec(
-            "new2",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    assert!(
-        !source_dir.exists(),
-        "source should be evictable after restore lease release"
-    );
-}
-
-#[tokio::test]
-async fn crash_window_content_pane_fails_needs_operator_not_silent_recreate() {
-    // CRASH WINDOW (`:632`), non-terminal leg: browser/editor creates return
-    // no terminal id and the client persists tabs locally, so an in-progress
-    // entry with no ledger record (process restarted) is UNRECONCILABLE — it
-    // must FAIL for the operator, never silently recreate. force recreates.
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t2",
-            "browser",
-            json!({ "url": "https://example.com", "devToolsOpen": false }),
-        )],
-    );
-    let source_id = union_source_id(dir.path(), "dev-1");
-    let pk = pane_key("dev-1:t2", "p-t2");
-    let mut doc = MarkerDoc::new();
-    let mut panes = Marker::new();
-    panes.insert(
-        pk.clone(),
-        PaneMark {
-            state: "in-progress".into(),
-            terminal_id: None,
-        },
-    );
-    doc.insert(source_id.clone(), (0, panes));
-    write_marker_doc(&device_dir(dir.path(), "dev-1"), &doc).unwrap();
-    // Fresh rig == fresh process (empty restore-key ledger).
-    let (r, _on, _h) = connected(dir.path());
-    let mut rx = r.bus.subscribe();
-    let body = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-    assert_eq!(body["restored"].as_array().unwrap().len(), 0, "{body}");
-    assert_eq!(body["failed"][0]["reason"], "in-progress-unconfirmed");
-    assert!(
-        body["failed"][0]["hint"]
-            .as_str()
-            .unwrap()
-            .contains("force"),
-        "hint must tell the operator how to proceed: {body}"
-    );
-    assert!(
-        tab_creates(&drain(&mut rx)).is_empty(),
-        "nothing may be broadcast for an unconfirmed non-terminal pane"
-    );
-    // force is the explicit operator override: recreate.
-    let forced = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "force": true }),
-        true,
-    )
-    .await
-    .1;
-    assert_eq!(forced["restored"].as_array().unwrap().len(), 1, "{forced}");
-}
-
-#[tokio::test]
-async fn delivery_ack_request_ids_are_invocation_unique() {
-    // ACK NONCE (`:403`): two restore attempts over the SAME pane must use
-    // DIFFERENT ack request ids, so a stale reply from a timed-out attempt
-    // can never resolve a later attempt's registration (the broker resolves
-    // by exact id).
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    let (r, _on, _h) = connected(dir.path());
-    let pk = pane_key("dev-1:t1", "p-t1");
-    let mut rx = r.bus.subscribe();
-    let _ = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    let ids1 = ack_request_ids(&drain(&mut rx));
-    // force re-acks the (live, already-restored) pane on a SECOND attempt.
-    let _ = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "force": true }),
-        true,
-    )
-    .await;
-    let ids2 = ack_request_ids(&drain(&mut rx));
-    assert_eq!(ids1.len(), 1, "{ids1:?}");
-    assert_eq!(ids2.len(), 1, "{ids2:?}");
-    for id in ids1.iter().chain(ids2.iter()) {
-        assert!(id.starts_with("restore-ack:"), "{id}");
-        assert!(id.ends_with(&pk), "id embeds the paneKey: {id}");
-    }
-    assert_ne!(
-        ids1[0], ids2[0],
-        "attempts must not share an ack request id"
-    );
-}
-
-#[tokio::test]
-async fn restore_panes_filter_restores_only_requested_and_rejects_unknown() {
-    // TARGETED REMEDIATION (`deploy-tab-diff.sh:175`, server leg): `panes`
-    // restores ONLY the named panes (everything else reported skipped
-    // `not-selected`), and an unknown pane key is a fail-closed 400 naming it
-    // BEFORE any side effect.
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![
-            rec(
-                "t1",
-                "terminal",
-                json!({ "mode": "shell", "initialCwd": "/tmp" }),
-            ),
-            rec(
-                "t2",
-                "browser",
-                json!({ "url": "https://example.com", "devToolsOpen": false }),
-            ),
-        ],
-    );
-    let (r, _on, _h) = connected(dir.path());
-    let browser_pk = pane_key("dev-1:t2", "p-t2");
-    let body = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "panes": [browser_pk] }),
-        true,
-    )
-    .await
-    .1;
-    let restored = body["restored"].as_array().unwrap();
-    assert_eq!(restored.len(), 1, "{body}");
-    assert_eq!(restored[0]["kind"], "browser");
-    assert!(
-        body["skipped"]
-            .as_array()
-            .unwrap()
-            .iter()
-            .any(|s| s["reason"] == "not-selected" && s["tabKey"] == "dev-1:t1"),
-        "unselected panes are reported, never silently dropped: {body}"
-    );
-    // Unknown pane key -> 400 naming it (fail-closed, nothing created).
-    let (status, err) = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "panes": ["dev-1:ghost#p-ghost"] }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::BAD_REQUEST, "{err}");
-    assert_eq!(err["unknownPanes"], json!(["dev-1:ghost#p-ghost"]));
-}
diff --git a/crates/freshell-server/src/tabs_snapshots_selectors.rs b/crates/freshell-server/src/tabs_snapshots_selectors.rs
index bfc31a56e..88635bb28 100644
--- a/crates/freshell-server/src/tabs_snapshots_selectors.rs
+++ b/crates/freshell-server/src/tabs_snapshots_selectors.rs
@@ -1,9 +1,7 @@
 //! Fail-closed snapshot selection parsing for the tabs-sync REST surface
 //! (`tabs_snapshots.rs`). Split into its own `#[path]`-included module to keep
-//! the handler file under the repo's 1,000-line-per-file limit. ONE code path
-//! validates selectors for BOTH the GET read endpoints (query params) and the
-//! POST restore endpoint (JSON body) — see [`parse_restore_selection`]'s doc
-//! for how the body shares [`parse_selector`].
+//! the handler file under the repo's 1,000-line-per-file limit.
+//! [`parse_selector`] validates the GET read endpoints' query params.
 
 // The Err variant is a ready-to-send axum `Response` (the same pattern every
 // handler in `tabs_snapshots.rs` uses); its size is irrelevant on this
@@ -12,7 +10,7 @@
 
 use axum::http::StatusCode;
 use axum::response::{IntoResponse, Json, Response};
-use serde_json::{json, Value};
+use serde_json::json;
 
 /// The parsed generation selector, or a 400 response. FAIL-CLOSED (`:1101`): an
 /// invalid, negative, duplicated, or conflicting selector is a 400, never a
@@ -59,96 +57,3 @@ pub(super) fn parse_selector(params: &[(String, String)]) -> Result<Selector, Re
     }
     Ok(Selector::Union)
 }
-
-/// The restore body's fail-closed snapshot selection (`:459`). Malformed
-/// values are a 400, NEVER a silent fall-through to the (broader) coherent
-/// union. `generation`/`generationId` REUSE the GET endpoint's
-/// [`parse_selector`] by materializing the same query-param shape it
-/// validates: a JSON value of the WRONG TYPE is serialized (`"3"` -> `"\"3\""`,
-/// `1.5` -> `"1.5"`, `-1` -> `"-1"`, `true` -> `"true"`), all of which that
-/// parser rejects, so both endpoints share ONE validation code path.
-pub(super) struct RestoreSelection {
-    pub components: Vec<String>,
-    pub selector: Selector,
-    pub panes: Option<std::collections::HashSet<String>>,
-}
-
-pub(super) fn parse_restore_selection(body: &Value) -> Result<RestoreSelection, Response> {
-    let bad = |msg: &str| (StatusCode::BAD_REQUEST, Json(json!({ "error": msg }))).into_response();
-    let components: Vec<String> = match body.get("components") {
-        None | Some(Value::Null) => Vec::new(),
-        Some(Value::Array(a)) => {
-            let mut out = Vec::new();
-            for x in a {
-                match x.as_str().filter(|s| !s.is_empty()) {
-                    Some(s) => out.push(s.to_string()),
-                    None => {
-                        return Err(bad(
-                            "`components` must be an array of non-empty generation-id strings",
-                        ))
-                    }
-                }
-            }
-            if out.is_empty() {
-                return Err(bad(
-                    "`components` must be a non-empty array of generation-id strings",
-                ));
-            }
-            out
-        }
-        Some(_) => {
-            return Err(bad(
-                "`components` must be an array of generation-id strings",
-            ))
-        }
-    };
-    let mut params: Vec<(String, String)> = Vec::new();
-    match body.get("generation") {
-        None | Some(Value::Null) => {}
-        // A valid u64 serializes to the digits parse_selector accepts; EVERY
-        // other JSON type serializes to something it rejects ("\"3\"", "1.5",
-        // "-1", "true") — fail-closed by construction.
-        Some(v) => params.push(("generation".to_string(), v.to_string())),
-    }
-    match body.get("generationId") {
-        None | Some(Value::Null) => {}
-        Some(Value::String(s)) => params.push(("generationId".to_string(), s.clone())),
-        Some(_) => return Err(bad("`generationId` must be a string")),
-    }
-    let selector = parse_selector(&params)?;
-    if !components.is_empty() && !matches!(selector, Selector::Union) {
-        return Err(bad(
-            "provide `components` OR `generation`/`generationId`, not both",
-        ));
-    }
-    let panes: Option<std::collections::HashSet<String>> = match body.get("panes") {
-        None | Some(Value::Null) => None,
-        Some(Value::Array(a)) => {
-            let mut set = std::collections::HashSet::new();
-            for x in a {
-                match x.as_str().filter(|s| !s.is_empty()) {
-                    Some(s) => {
-                        set.insert(s.to_string());
-                    }
-                    None => {
-                        return Err(bad(
-                            "`panes` must be an array of non-empty \"tabKey#paneId\" strings",
-                        ))
-                    }
-                }
-            }
-            if set.is_empty() {
-                return Err(bad(
-                    "`panes` must be a non-empty array of \"tabKey#paneId\" strings",
-                ));
-            }
-            Some(set)
-        }
-        Some(_) => return Err(bad("`panes` must be an array of \"tabKey#paneId\" strings")),
-    };
-    Ok(RestoreSelection {
-        components,
-        selector,
-        panes,
-    })
-}
diff --git a/crates/freshell-server/src/tabs_snapshots_tests.rs b/crates/freshell-server/src/tabs_snapshots_tests.rs
index 076e46dc9..98fa454d3 100644
--- a/crates/freshell-server/src/tabs_snapshots_tests.rs
+++ b/crates/freshell-server/src/tabs_snapshots_tests.rs
@@ -6,7 +6,6 @@ use super::*;
 use axum::body::Body;
 use axum::http::{Request, StatusCode};
 use serde_json::json;
-use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
 use tower::ServiceExt;
 
 const TOKEN: &str = "test-token";
@@ -38,43 +37,12 @@ fn seed(dir: &std::path::Path, device: &str, client: &str, rev: i64, session_id:
     .unwrap();
 }
 
-// A test rig wiring the screenshot broker + the fresh-agent create pipeline to
-// ONE shared broadcast bus (exactly as `main.rs:196,202,232` do), plus the ONE
-// shared TerminalRegistry restore uses for marker reconciliation. `bus` is kept
-// so a test can subscribe an in-process "browser" that answers the delivery-ack
-// screenshot round-trip. Ack timeout is short so the connection-drop test is fast.
-struct Rig {
-    state: TabsSnapshotsState,
-    bus: std::sync::Arc<tokio::sync::broadcast::Sender<String>>,
-    terminals: freshell_terminal::TerminalRegistry,
-}
-fn rig(dir: &std::path::Path) -> Rig {
-    let bus = std::sync::Arc::new(tokio::sync::broadcast::channel::<String>(256).0);
-    let terminals = freshell_terminal::TerminalRegistry::new();
-    let fresh_agent = freshell_freshagent::FreshAgentState::new(
-        std::sync::Arc::new(TOKEN.to_string()),
-        bus.clone(),
-    )
-    .with_terminal_registry(terminals.clone());
-    let state = TabsSnapshotsState {
+fn test_state(dir: &std::path::Path) -> TabsSnapshotsState {
+    TabsSnapshotsState {
         auth_token: std::sync::Arc::new(TOKEN.to_string()),
         snapshots_dir: Some(dir.to_path_buf()),
-        fresh_agent,
-        screenshots: freshell_ws::screenshot::ScreenshotBroker::new(bus.clone()),
-        terminals: terminals.clone(),
-        restore_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
-        restore_ack_timeout: std::time::Duration::from_millis(300),
-    };
-    Rig {
-        state,
-        bus,
-        terminals,
     }
 }
-// Back-compat helper for the read-endpoint tests (no delivery needed).
-fn test_state(dir: &std::path::Path) -> TabsSnapshotsState {
-    rig(dir).state
-}
 
 async fn get(router: axum::Router, uri: &str, auth: bool) -> (StatusCode, serde_json::Value) {
     let mut req = Request::builder().method("GET").uri(uri);
@@ -238,751 +206,3 @@ async fn corrupt_generation_file_returns_500_not_404() {
         "list must also 500 on a corrupt store"
     );
 }
-
-// ── POST /api/tabs-sync/restore (Task 3) ────────────────────────────────────
-
-async fn post(
-    router: axum::Router,
-    uri: &str,
-    body: serde_json::Value,
-    auth: bool,
-) -> (StatusCode, serde_json::Value) {
-    let mut req = Request::builder()
-        .method("POST")
-        .uri(uri)
-        .header("content-type", "application/json");
-    if auth {
-        req = req.header("x-auth-token", TOKEN);
-    }
-    let resp = router
-        .oneshot(req.body(Body::from(body.to_string())).unwrap())
-        .await
-        .unwrap();
-    let status = resp.status();
-    let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
-        .await
-        .unwrap();
-    (
-        status,
-        serde_json::from_slice(&bytes).unwrap_or(serde_json::Value::Null),
-    )
-}
-
-// Seed a real generation (encoded layout) via the registry.
-fn seed_records(dir: &std::path::Path, device: &str, client: &str, rev: i64, records: Vec<Value>) {
-    let reg = freshell_ws::tabs::TabsRegistry::with_persist_dir(dir.to_path_buf());
-    reg.replace_client_snapshot("srv", device, "Dev One", client, rev, records)
-        .unwrap();
-}
-
-// NOTE: every shell payload below carries an explicit `initialCwd: "/tmp"`.
-// Sibling tests in this binary (`files.rs`) set `HOME=/home/tester` (nonexistent)
-// process-wide and never restore it, and portable-pty falls back to the child
-// env's HOME as the spawn cwd when none is given — a cwd-less shell spawn then
-// fails ENOENT under the full suite. An explicit, always-present cwd keeps these
-// tests deterministic regardless of sibling env pollution.
-fn rec(tab: &str, kind: &str, payload: Value) -> Value {
-    json!({ "tabKey": format!("dev-1:{tab}"), "tabId": tab, "tabName": tab, "status": "open",
-            "revision": 1, "updatedAt": 2000, "paneCount": 1,
-            "panes": [{ "paneId": format!("p-{tab}"), "kind": kind, "payload": payload }] })
-}
-
-fn mixed_records() -> Vec<Value> {
-    vec![
-        rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        ),
-        rec(
-            "t2",
-            "browser",
-            json!({ "url": "https://example.com", "devToolsOpen": false }),
-        ),
-        rec(
-            "t3",
-            "fresh-agent",
-            json!({ "provider": "claude", "sessionType": "freshclaude",
-                "sessionRef": { "provider": "claude", "sessionId": "x" } }),
-        ),
-    ]
-}
-
-// The in-process "browser" registers the same per-connection sink a real WS
-// connection does and answers every targeted `screenshot.capture` while `on`
-// is true. The connection id is carried into `resolve_from`, so another
-// browser cannot acknowledge this target's restore.
-fn spawn_browser(r: &Rig, on: std::sync::Arc<AtomicBool>) -> u64 {
-    static NEXT_CLIENT_ID: AtomicU64 = AtomicU64::new(1);
-    let client_id = NEXT_CLIENT_ID.fetch_add(1, Ordering::SeqCst);
-    let broker = r.state.screenshots.clone();
-    let observed = r.bus.clone();
-    r.state.screenshots.add_capable_client(
-        client_id,
-        std::sync::Arc::new(move |message| {
-            if !on.load(Ordering::SeqCst) {
-                return true;
-            }
-            let v = serde_json::to_value(message).expect("server message serializes");
-            let _ = observed.send(v.to_string());
-            if v["type"] == "ui.command" && v["command"] == "screenshot.capture" {
-                if let Some(request_id) = v["payload"]["requestId"].as_str() {
-                    broker.resolve_from(
-                        client_id,
-                        request_id,
-                        freshell_ws::screenshot::ScreenshotResult {
-                            ok: true,
-                            ..Default::default()
-                        },
-                    );
-                }
-            }
-            true
-        }),
-    );
-    client_id
-}
-// A rig with exactly one connected, RESPONSIVE browser.
-fn connected(dir: &std::path::Path) -> (Rig, std::sync::Arc<AtomicBool>, u64) {
-    let r = rig(dir);
-    let on = std::sync::Arc::new(AtomicBool::new(true));
-    let h = spawn_browser(&r, on.clone());
-    (r, on, h)
-}
-fn marker_json(dir: &std::path::Path, device: &str) -> Value {
-    let enc = freshell_ws::tabs_persist::encode_device_id(device).unwrap();
-    serde_json::from_slice(&std::fs::read(dir.join(enc).join(RESTORE_MARKER)).unwrap()).unwrap()
-}
-// The v2 marker is a per-source LEDGER (`tabs_snapshots_marker.rs`); these
-// tests restore exactly one source, so return that single source's panes map.
-fn marker_panes(dir: &std::path::Path, device: &str) -> Value {
-    let doc = marker_json(dir, device);
-    let sources = doc["sources"].as_object().expect("v2 marker sources");
-    assert_eq!(sources.len(), 1, "single-source test marker: {doc}");
-    sources.values().next().unwrap()["panes"].clone()
-}
-
-#[tokio::test]
-async fn restore_rebuilds_supported_panes_and_reports_skips() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(dir.path(), "dev-1", "c1", 3, mixed_records());
-    let (r, _on, _h) = connected(dir.path());
-    let (status, body) = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::OK);
-    assert_eq!(body["broadcastScope"], "target-client");
-    assert_eq!(
-        body["deliveryConfirmed"], true,
-        "single responsive browser acked every tab.create"
-    );
-    assert!(body["sourceId"].is_string());
-    let restored = body["restored"].as_array().unwrap();
-    assert_eq!(
-        restored.len(),
-        2,
-        "shell terminal + browser restored: {body}"
-    );
-    assert!(restored
-        .iter()
-        .any(|r| r["kind"] == "terminal" && r["terminalId"].is_string()));
-    assert!(restored
-        .iter()
-        .any(|r| r["kind"] == "browser" && r["tabId"].is_string()));
-    let skipped = body["skipped"].as_array().unwrap();
-    assert_eq!(skipped.len(), 1);
-    assert_eq!(skipped[0]["reason"], "unsupported-kind");
-    assert_eq!(body["failed"].as_array().unwrap().len(), 0);
-}
-
-#[tokio::test]
-async fn restore_rejects_non_boolean_control_flags() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "browser",
-            json!({ "url": "https://example.com", "devToolsOpen": false }),
-        )],
-    );
-    for (field, value) in [
-        ("dryRun", json!("true")),
-        ("dryRun", json!(1)),
-        ("dryRun", Value::Null),
-        ("force", json!("true")),
-        ("force", json!(1)),
-        ("force", Value::Null),
-    ] {
-        let mut request = json!({ "deviceId": "dev-1", "dryRun": true });
-        request[field] = value;
-        let (status, body) = post(
-            router(test_state(dir.path())),
-            "/api/tabs-sync/restore",
-            request,
-            true,
-        )
-        .await;
-        assert_eq!(status, StatusCode::BAD_REQUEST, "{field}: {body}");
-        assert_eq!(
-            body["error"],
-            format!("{field} must be a boolean"),
-            "{field}: {body}"
-        );
-    }
-}
-
-#[tokio::test]
-async fn dry_run_reads_and_classifies_the_restore_marker() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "browser",
-            json!({ "url": "https://example.com", "devToolsOpen": false }),
-        )],
-    );
-    let (connected_rig, _on, _client) = connected(dir.path());
-    let (_, first) = post(
-        router(connected_rig.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(first["restored"].as_array().unwrap().len(), 1, "{first}");
-
-    let (_, preview) = post(
-        router(test_state(dir.path())),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "dryRun": true }),
-        true,
-    )
-    .await;
-    assert_eq!(
-        preview["restored"].as_array().unwrap().len(),
-        0,
-        "{preview}"
-    );
-    assert_eq!(preview["skipped"][0]["reason"], "already-restored");
-
-    let marker_path = dir
-        .path()
-        .join(freshell_ws::tabs_persist::encode_device_id("dev-1").unwrap())
-        .join(RESTORE_MARKER);
-    let mut marker = marker_json(dir.path(), "dev-1");
-    let pane = marker["sources"]
-        .as_object_mut()
-        .unwrap()
-        .values_mut()
-        .next()
-        .unwrap()["panes"]
-        .as_object_mut()
-        .unwrap()
-        .values_mut()
-        .next()
-        .unwrap();
-    pane["state"] = json!("in-progress");
-    std::fs::write(&marker_path, serde_json::to_vec(&marker).unwrap()).unwrap();
-
-    let (_, reconciled) = post(
-        router(connected_rig.state),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "dryRun": true }),
-        true,
-    )
-    .await;
-    assert_eq!(
-        reconciled["restored"][0]["reconciled"], true,
-        "{reconciled}"
-    );
-
-    let (_, unconfirmed) = post(
-        router(test_state(dir.path())),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "dryRun": true }),
-        true,
-    )
-    .await;
-    assert_eq!(
-        unconfirmed["failed"][0]["reason"], "in-progress-unconfirmed",
-        "{unconfirmed}"
-    );
-
-    std::fs::write(&marker_path, b"{corrupt").unwrap();
-    let (status, corrupt) = post(
-        router(test_state(dir.path())),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "dryRun": true }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::CONFLICT, "{corrupt}");
-    assert_eq!(corrupt["markerError"], true);
-}
-
-#[tokio::test]
-async fn connection_churn_cannot_redirect_delivery_or_acknowledgement() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "browser",
-            json!({ "url": "https://example.com", "devToolsOpen": false }),
-        )],
-    );
-    let r = rig(dir.path());
-    let target_id = 71;
-    let late_id = 72;
-    let broker = r.state.screenshots.clone();
-    let late_frames = std::sync::Arc::new(AtomicUsize::new(0));
-    let late_frames_for_sink = late_frames.clone();
-    r.state.screenshots.add_capable_client(
-        target_id,
-        std::sync::Arc::new(move |message| {
-            let value = serde_json::to_value(message).unwrap();
-            if value["command"] == "tab.create" {
-                let late_frames = late_frames_for_sink.clone();
-                broker.add_capable_client(
-                    late_id,
-                    std::sync::Arc::new(move |_| {
-                        late_frames.fetch_add(1, Ordering::SeqCst);
-                        true
-                    }),
-                );
-            }
-            if value["command"] == "screenshot.capture" {
-                let request_id = value["payload"]["requestId"].as_str().unwrap();
-                // A late client guesses the request id, but cannot satisfy the
-                // target-bound pending request.
-                broker.resolve_from(
-                    late_id,
-                    request_id,
-                    freshell_ws::screenshot::ScreenshotResult {
-                        ok: true,
-                        ..Default::default()
-                    },
-                );
-            }
-            true
-        }),
-    );
-
-    let (status, body) = post(
-        router(r.state),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::OK, "{body}");
-    assert_eq!(body["restored"].as_array().unwrap().len(), 0, "{body}");
-    assert_eq!(body["failed"][0]["reason"], "delivery-unconfirmed");
-    assert_eq!(late_frames.load(Ordering::SeqCst), 0);
-}
-
-#[tokio::test]
-async fn restore_rejects_mismatched_or_malformed_session_ref_before_spawning() {
-    let dir = tempfile::tempdir().unwrap();
-    // (a) codex mode + CLAUDE sessionRef; (b) codex mode + sessionRef object
-    // MISSING sessionId -> both must FAIL (never silently spawn fresh).
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![
-            rec(
-                "t1",
-                "terminal",
-                json!({ "mode": "codex",
-                "sessionRef": { "provider": "claude", "sessionId": "z" } }),
-            ),
-            rec(
-                "t2",
-                "terminal",
-                json!({ "mode": "codex",
-                "sessionRef": { "provider": "codex" } }),
-            ),
-        ],
-    ); // no sessionId
-    let (r, _on, _h) = connected(dir.path());
-    let (status, body) = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::INTERNAL_SERVER_ERROR, "{body}");
-    assert_eq!(body["error"], "snapshot store unreadable");
-    assert!(
-        r.terminals.inventory().is_empty(),
-        "semantic validation must fail before spawning"
-    );
-}
-
-#[tokio::test]
-async fn restore_is_idempotent_and_force_bypasses_skip() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    // Run 1: restore (marker persisted on disk).
-    let (r1, _on1, _h1) = connected(dir.path());
-    let first = post(
-        router(r1.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-    assert_eq!(first["restored"].as_array().unwrap().len(), 1);
-    // Run 2: a DIFFERENT server instance (fresh TerminalRegistry, SAME on-disk
-    // marker dir). The restored terminal isn't in THIS registry, so live-reconcile
-    // can't fire -> the pane is skipped `already-restored` (idempotent), nothing
-    // recreated. Deterministic (no reliance on kill-exit timing).
-    let (r2, _on2, _h2) = connected(dir.path());
-    let second = post(
-        router(r2.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-    assert_eq!(second["restored"].as_array().unwrap().len(), 0);
-    assert_eq!(second["skipped"][0]["reason"], "already-restored");
-    // force bypasses the skip -> re-creates (the terminal is not live in r2).
-    let forced = post(
-        router(r2.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "force": true }),
-        true,
-    )
-    .await
-    .1;
-    assert_eq!(forced["restored"].as_array().unwrap().len(), 1);
-}
-
-#[tokio::test]
-async fn restore_refuses_unless_exactly_one_browser_connected() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    // ZERO clients -> 409.
-    let (status, body) = post(
-        router(test_state(dir.path())),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::CONFLICT, "zero clients must be refused");
-    assert_eq!(body["connectedClients"], 0);
-    // TWO clients -> 409 (would duplicate onto the bystander).
-    let two = rig(dir.path());
-    let on2 = std::sync::Arc::new(AtomicBool::new(true));
-    let _h2 = spawn_browser(&two, on2); // count -> 1 (responsive)
-    two.state
-        .screenshots
-        .add_capable_client(9_999_999, std::sync::Arc::new(|_| true)); // count -> 2
-    let (status, body) = post(
-        router(two.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::CONFLICT);
-    assert_eq!(body["connectedClients"], 2);
-    // force overrides the gate even at 2 (the responsive browser still acks).
-    let (status, _) = post(
-        router(two.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "force": true }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::OK);
-    // EXACTLY ONE -> OK.
-    let (r, _on, _h) = connected(dir.path());
-    let (status, _) = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::OK);
-}
-
-#[tokio::test]
-async fn restore_dry_run_creates_nothing_and_404_on_missing_snapshot() {
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(dir.path(), "dev-1", "c1", 3, mixed_records());
-    // dryRun is allowed regardless of client count (creates nothing).
-    let (status, body) = post(
-        router(test_state(dir.path())),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "dryRun": true }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::OK);
-    assert_eq!(
-        body["deliveryConfirmed"], true,
-        "dryRun is trivially confirmed"
-    );
-    assert_eq!(body["restored"].as_array().unwrap().len(), 2);
-    assert!(body["restored"][0]["tabId"].is_null());
-    // dryRun writes no marker.
-    assert!(!dir
-        .path()
-        .join(freshell_ws::tabs_persist::encode_device_id("dev-1").unwrap())
-        .join(RESTORE_MARKER)
-        .exists());
-    // Missing snapshot -> 404 even under dryRun (gate bypassed, lookup fails).
-    let (status, _) = post(
-        router(test_state(dir.path())),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "ghost", "dryRun": true }),
-        true,
-    )
-    .await;
-    assert_eq!(status, StatusCode::NOT_FOUND);
-}
-
-#[tokio::test]
-async fn delivery_drop_fails_remaining_panes_and_writes_in_progress_marker() {
-    // VERIFIED DELIVERY (:1460): one connected but UNRESPONSIVE browser. The
-    // first pane's create succeeds but its delivery ack times out -> that pane
-    // AND every remaining pane are FAILED (not restored), deliveryConfirmed is
-    // false, and the created terminal is recorded IN-PROGRESS (with its id) for
-    // reconciliation -- NOT restored.
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![
-            rec(
-                "t1",
-                "terminal",
-                json!({ "mode": "shell", "initialCwd": "/tmp" }),
-            ),
-            rec(
-                "t2",
-                "terminal",
-                json!({ "mode": "shell", "initialCwd": "/tmp" }),
-            ),
-        ],
-    );
-    let r = rig(dir.path());
-    let off = std::sync::Arc::new(AtomicBool::new(false)); // never answers
-    let _h = spawn_browser(&r, off); // count 1, unresponsive
-    let body = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-    assert_eq!(body["restored"].as_array().unwrap().len(), 0);
-    assert_eq!(body["deliveryConfirmed"], false);
-    let failed = body["failed"].as_array().unwrap();
-    assert!(failed.iter().any(|f| f["reason"] == "delivery-unconfirmed"));
-    assert!(
-        failed.iter().any(|f| f["reason"] == "connection-dropped"),
-        "the pane after the drop must be FAILED, never restored"
-    );
-    // The created terminal is recorded IN-PROGRESS in the marker.
-    let m = marker_panes(dir.path(), "dev-1");
-    let states: Vec<&str> = m
-        .as_object()
-        .unwrap()
-        .values()
-        .filter_map(|p| p["state"].as_str())
-        .collect();
-    assert!(
-        states.iter().all(|s| *s == "in-progress"),
-        "nothing marked restored: {m}"
-    );
-}
-
-#[tokio::test]
-async fn write_ahead_reconciles_live_terminal_no_duplicate_on_retry() {
-    // MARKER-BEFORE-SIDE-EFFECTS (:1532): run 1 drops delivery after creating
-    // the terminal (write-ahead in-progress). Run 2 (now responsive) must
-    // RECONCILE that still-live terminal -- promote to restored WITHOUT creating
-    // a duplicate. The same terminalId proves no second create happened.
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    let r = rig(dir.path());
-    let on = std::sync::Arc::new(AtomicBool::new(false));
-    let _h = spawn_browser(&r, on.clone());
-    let first = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-    let tid = first["failed"][0]["terminalId"]
-        .as_str()
-        .unwrap()
-        .to_string();
-    assert!(
-        r.terminals.is_running(&tid),
-        "terminal created despite delivery drop"
-    );
-    on.store(true, Ordering::SeqCst); // browser comes back
-    let second = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-    let rec0 = &second["restored"][0];
-    assert_eq!(
-        rec0["reconciled"], true,
-        "in-progress live pane reconciled, not recreated"
-    );
-    assert_eq!(
-        rec0["terminalId"], tid,
-        "SAME terminal -> no duplicate create"
-    );
-    assert_eq!(second["failed"].as_array().unwrap().len(), 0);
-    assert_eq!(
-        marker_panes(dir.path(), "dev-1")[pane_key("dev-1:t1", "p-t1").as_str()]["state"],
-        "restored"
-    );
-}
-
-#[tokio::test]
-async fn force_preserves_prior_marker_and_never_duplicates_live_terminal() {
-    // FORCE PRESERVES HISTORY (:1497): a normal restore records t1 restored.
-    // A subsequent FORCE restore must LOAD + preserve that record and must NOT
-    // duplicate the still-live terminal (reconciled), so a later ordinary
-    // restore still sees t1 restored (no re-create).
-    let dir = tempfile::tempdir().unwrap();
-    seed_records(
-        dir.path(),
-        "dev-1",
-        "c1",
-        1,
-        vec![rec(
-            "t1",
-            "terminal",
-            json!({ "mode": "shell", "initialCwd": "/tmp" }),
-        )],
-    );
-    let (r, _on, _h) = connected(dir.path());
-    let first = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1" }),
-        true,
-    )
-    .await
-    .1;
-    let tid = first["restored"][0]["terminalId"]
-        .as_str()
-        .unwrap()
-        .to_string();
-    let first_tab_id = first["restored"][0]["tabId"].as_str().unwrap().to_string();
-    let forced = post(
-        router(r.state.clone()),
-        "/api/tabs-sync/restore",
-        json!({ "deviceId": "dev-1", "force": true }),
-        true,
-    )
-    .await
-    .1;
-    assert_eq!(forced["restored"][0]["forcedReplacement"], true);
-    assert_eq!(
-        forced["restored"][0]["terminalId"], tid,
-        "no duplicate under force"
-    );
-    assert_eq!(
-        forced["restored"][0]["tabId"], first_tab_id,
-        "the reused PTY must keep the ids injected into its environment"
-    );
-    // The marker STILL records t1 restored -- force did not discard prior history.
-    assert_eq!(
-        marker_panes(dir.path(), "dev-1")[pane_key("dev-1:t1", "p-t1").as_str()]["state"],
-        "restored"
-    );
-}
-
-#[test]
-fn marker_in_flight_temp_is_invisible_to_the_ws_orphan_tmp_sweep() {
-    // freshell-ws's `sweep_orphan_tmp` reaps every `*.tmp` in the device dir
-    // without any lock shared with the restore path, so the marker's in-flight
-    // temp must never carry the `tmp` extension (see RESTORE_MARKER_TMP docs
-    // and the freshell-ws test
-    // `restore_marker_in_flight_temp_survives_the_sweep_while_stray_tmp_is_reaped`).
-    assert!(
-        std::path::Path::new(RESTORE_MARKER_TMP)
-            .extension()
-            .is_none_or(|e| e != "tmp"),
-        "RESTORE_MARKER_TMP must not use the .tmp extension: freshell-ws's \
-         orphan-tmp sweep would reap it mid-write"
-    );
-    // And it must still be a hidden dotfile so the *.json generation listing
-    // never sees it either.
-    assert!(RESTORE_MARKER_TMP.starts_with('.'));
-}
-
-// Restore-hardening tests (cross-model review delta r1) live in a sibling file
-// so both test files stay under the repo's 1,000-line-per-file limit.
-#[path = "tabs_snapshots_restore_tests.rs"]
-mod restore_tests;
diff --git a/crates/freshell-ws/src/screenshot.rs b/crates/freshell-ws/src/screenshot.rs
index e455c6e83..005ebc110 100644
--- a/crates/freshell-ws/src/screenshot.rs
+++ b/crates/freshell-ws/src/screenshot.rs
@@ -7,29 +7,23 @@
 //! 1. the REST handler [`register`]s a `requestId` and gets a [`oneshot`] receiver;
 //! 2. it [`send_capture`]s a `{type:"ui.command", command:"screenshot.capture",
 //!    payload:{requestId, scope, tabId?, paneId?}}` frame onto the shared broadcast
-//!    bus (the exact shape `src/lib/ui-commands.ts:73` dispatches), or
-//!    [`send_capture_to`] sends it to one connection for a restore delivery fence;
+//!    bus (the exact shape `src/lib/ui-commands.ts:73` dispatches);
 //! 3. the screenshot-capable SPA client renders the DOM (`captureUiScreenshot` /
 //!    html2canvas) and replies `{type:"ui.screenshot.result", requestId, ...}`
 //!    (`src/lib/ui-commands.ts:51`);
 //! 4. the `/ws` inbound loop routes that reply through [`resolve_from`], waking the
 //!    awaiting REST handler with the base64 PNG.
-//!
-//! Ordinary screenshot requests retain broadcast behavior. Restore uses the
-//! connection registry plus target-bound requests: a result from any connection
-//! other than the selected target is ignored, closing the connection-churn race
-//! between the exactly-one-client gate, tab delivery, and acknowledgement.
 
 use std::collections::HashMap;
 use std::sync::{Arc, Mutex};
 
-use freshell_protocol::{ServerMessage, UiCommand};
+use freshell_protocol::ServerMessage;
 use serde_json::json;
 use tokio::sync::oneshot;
 
-/// A direct per-connection delivery sink. Unlike the terminal registry's
-/// fire-and-forget `FrameSink`, restore needs to know whether the outbound
-/// channel actually accepted a command.
+/// A direct per-connection delivery sink registered alongside each
+/// screenshot-capable connection (`add_capable_client`). Reports whether the
+/// outbound channel actually accepted a command.
 pub type ClientSink = Arc<dyn Fn(ServerMessage) -> bool + Send + Sync>;
 
 /// The normalized screenshot outcome the REST handler consumes. Mirrors the
@@ -105,44 +99,11 @@ impl ScreenshotBroker {
         self.capable_client_count() > 0
     }
 
-    /// Return the stable connection id iff exactly one capable client is
-    /// connected at this instant.
-    pub fn exclusive_client_id(&self) -> Option<u64> {
-        self.client_snapshot().1
-    }
-
-    /// Atomically snapshot the capable-client count and exclusive id.
-    pub fn client_snapshot(&self) -> (i64, Option<u64>) {
-        let capable = self.inner.capable.lock().unwrap();
-        let exclusive = (capable.len() == 1)
-            .then(|| capable.keys().next().copied())
-            .flatten();
-        (capable.len() as i64, exclusive)
-    }
-
-    /// Whether the selected capable connection is still registered.
-    pub fn has_client(&self, connection_id: u64) -> bool {
-        self.inner
-            .capable
-            .lock()
-            .unwrap()
-            .contains_key(&connection_id)
-    }
-
     /// Register a pending request, returning the receiver the REST handler awaits.
     pub fn register(&self, request_id: String) -> oneshot::Receiver<ScreenshotResult> {
         self.register_expected(request_id, None)
     }
 
-    /// Register a request that only `connection_id` is permitted to resolve.
-    pub fn register_for_client(
-        &self,
-        request_id: String,
-        connection_id: u64,
-    ) -> oneshot::Receiver<ScreenshotResult> {
-        self.register_expected(request_id, Some(connection_id))
-    }
-
     fn register_expected(
         &self,
         request_id: String,
@@ -195,23 +156,6 @@ impl ScreenshotBroker {
         }
     }
 
-    /// Send one already-typed frame to a specific capable connection. Returns
-    /// false when that exact connection is no longer registered.
-    pub fn send_to_client(&self, connection_id: u64, frame: ServerMessage) -> bool {
-        let sink = self
-            .inner
-            .capable
-            .lock()
-            .unwrap()
-            .get(&connection_id)
-            .cloned();
-        if let Some(sink) = sink {
-            sink(frame)
-        } else {
-            false
-        }
-    }
-
     /// Broadcast the `screenshot.capture` `ui.command` to every connection; the
     /// capable SPA client renders + replies. Frame shape is byte-compatible with
     /// `ws-handler.ts:1072` (`{type, command, payload:{requestId, scope, tabId?,
@@ -239,31 +183,6 @@ impl ScreenshotBroker {
         // and reports the same "no UI answered" outcome the original would.
         let _ = self.inner.broadcast_tx.send(frame.to_string());
     }
-
-    /// Send the capture fence only to `connection_id`.
-    pub fn send_capture_to(
-        &self,
-        connection_id: u64,
-        request_id: &str,
-        scope: &str,
-        tab_id: Option<&str>,
-        pane_id: Option<&str>,
-    ) -> bool {
-        let mut payload = json!({ "requestId": request_id, "scope": scope });
-        if let Some(tab_id) = tab_id {
-            payload["tabId"] = json!(tab_id);
-        }
-        if let Some(pane_id) = pane_id {
-            payload["paneId"] = json!(pane_id);
-        }
-        self.send_to_client(
-            connection_id,
-            ServerMessage::UiCommand(UiCommand {
-                command: "screenshot.capture".to_string(),
-                payload: Some(payload),
-            }),
-        )
-    }
 }
 
 #[cfg(test)]
@@ -284,10 +203,8 @@ mod tests {
         b.add_capable_client(2, sink);
         assert_eq!(b.capable_client_count(), 2);
         assert!(b.has_capable_client());
-        assert_eq!(b.exclusive_client_id(), None);
         b.remove_capable_client(1);
         assert_eq!(b.capable_client_count(), 1);
-        assert_eq!(b.exclusive_client_id(), Some(2));
         b.remove_capable_client(2);
         b.remove_capable_client(2);
         assert_eq!(b.capable_client_count(), 0);
@@ -339,67 +256,6 @@ mod tests {
         assert!(rx.await.is_err(), "cancelled sender dropped");
     }
 
-    #[tokio::test]
-    async fn target_bound_request_ignores_another_client() {
-        let b = broker();
-        let mut rx = b.register_for_client("targeted".to_string(), 7);
-        b.resolve_from(
-            8,
-            "targeted",
-            ScreenshotResult {
-                ok: true,
-                ..Default::default()
-            },
-        );
-        assert!(rx.try_recv().is_err(), "wrong client must not resolve");
-        b.resolve_from(
-            7,
-            "targeted",
-            ScreenshotResult {
-                ok: true,
-                ..Default::default()
-            },
-        );
-        assert!(rx.await.expect("target resolved").ok);
-    }
-
-    #[test]
-    fn direct_capture_reaches_only_the_selected_client() {
-        let b = broker();
-        let seen_1 = Arc::new(Mutex::new(Vec::new()));
-        let seen_2 = Arc::new(Mutex::new(Vec::new()));
-        for (id, seen) in [(1, seen_1.clone()), (2, seen_2.clone())] {
-            b.add_capable_client(
-                id,
-                Arc::new(move |message| {
-                    seen.lock().unwrap().push(message);
-                    true
-                }),
-            );
-        }
-        assert!(b.send_capture_to(1, "req-direct", "view", None, None));
-        assert_eq!(seen_1.lock().unwrap().len(), 1);
-        assert!(seen_2.lock().unwrap().is_empty());
-    }
-
-    #[test]
-    fn direct_send_reports_a_closed_outbound_channel() {
-        let b = broker();
-        let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
-        drop(rx);
-        b.add_capable_client(7, Arc::new(move |message| tx.send(message).is_ok()));
-        assert!(
-            !b.send_to_client(
-                7,
-                ServerMessage::UiCommand(UiCommand {
-                    command: "tab.create".to_string(),
-                    payload: None,
-                }),
-            ),
-            "a registered sink with a closed channel is not successful delivery"
-        );
-    }
-
     #[test]
     fn send_capture_frame_matches_ui_command_shape() {
         let b = broker();
diff --git a/crates/freshell-ws/src/tabs_persist_validation_tests.rs b/crates/freshell-ws/src/tabs_persist_validation_tests.rs
index f0e2fbc10..5c2a3bbb2 100644
--- a/crates/freshell-ws/src/tabs_persist_validation_tests.rs
+++ b/crates/freshell-ws/src/tabs_persist_validation_tests.rs
@@ -110,7 +110,7 @@ fn wrong_typed_create_request_id_never_poisons_the_device() {
         .expect("wrong-typed createRequestId must NOT make the device unreadable")
         .expect("generation present");
     // Current (locked) behavior: the unknown field passes through verbatim —
-    // nothing strips it; the CONSUMERS (pane_to_create_body, REST ingress)
+    // nothing strips it; the CONSUMERS (REST ingress, recovery inventory)
     // drop non-strings, so the only cost is that one pane loses key identity.
     let panes = &union["records"][0]["panes"];
     assert_eq!(panes[0]["payload"]["createRequestId"], 42);
diff --git a/scripts/deploy-tab-diff.sh b/scripts/deploy-tab-diff.sh
index 24b64be32..159f33296 100755
--- a/scripts/deploy-tab-diff.sh
+++ b/scripts/deploy-tab-diff.sh
@@ -266,43 +266,27 @@ case "$CMD" in
     echo "================ TAB-DIFF DIVERGENCE (${COUNT}) ================"
     jq -r '.[] | "\(.verdict)\tdevice=\(.pane.device)\ttab=\(.pane.tabName) (\(.pane.tabKey))\tpane=\(.pane.paneId)\tkind=\(.pane.kind)\twas=\(.pane.sessionRef.provider // "-"):\(.pane.sessionRef.sessionId // "-")\(if .after then "\tnow=\(.after.provider):\(.after.sessionId)" else "" end)"' <<<"$DIFF"
     echo "================================================================"
-    # Remediation is TARGETED (:175): it restores ONLY the diverged panes (one
-    # --pane per diverged paneKey, the restore API's selective mode) from the
-    # IMMUTABLE multi-client BUNDLE recorded in the BEFORE capture (the exact
-    # set of per-client component generation ids at capture), via --components
-    # -- the SAME coherent union the capture saw, NEVER a single client's
-    # generationId (:2621), and never the WHOLE union (which would duplicate
-    # every still-healthy pane). Everything is read from the BEFORE file +
+    # Remediation points at the UI recovery flow (recover-my-panes): the
+    # tabs-snapshots store is read by GET /api/recovery/inventory, and a
+    # fresh browser context connecting to the server is offered the captured
+    # panes to rebuild. Everything below is read from the BEFORE file +
     # $DIFF, so verify performs ZERO network operations in --after/offline
     # mode (:2619).
     # NO CAPTURED IDENTITY panes are NOT snapshot-remediable: no generation
-    # carries a sessionRef for them, so restore-tabs.sh could only rebuild a
-    # blank session (a duplicate of the loss). They get a manual-recovery
-    # note instead of a --pane entry.
+    # carries a sessionRef for them, so any snapshot-driven recovery could
+    # only rebuild a blank session (a duplicate of the loss). They get a
+    # manual-recovery note instead.
     UNVERIFIABLE=$(jq '[.[] | select(.verdict == "NO CAPTURED IDENTITY")]' <<<"$DIFF")
     REMEDIABLE=$(jq '[.[] | select(.verdict != "NO CAPTURED IDENTITY")]' <<<"$DIFF")
     if [[ "$(jq 'length' <<<"$UNVERIFIABLE")" != "0" ]]; then
-      echo "UNRECOVERABLE FROM SNAPSHOTS: identity was never captured for these live CLI panes, so restore-tabs.sh cannot rebuild them."
+      echo "UNRECOVERABLE FROM SNAPSHOTS: identity was never captured for these live CLI panes, so no snapshot-driven recovery can rebuild them."
       echo "Recover manually from the provider's own session store (e.g. 'amplifier resume', 'codex resume', 'claude --resume'), matching by cwd and last activity."
       jq -r '.[] | "  NO-IDENTITY device=\(.pane.device)\ttab=\(.pane.tabName) (\(.pane.tabKey))\tpane=\(.pane.paneId)\tmode=\(.pane.mode // "-")"' <<<"$UNVERIFIABLE"
     fi
     if [[ "$(jq 'length' <<<"$REMEDIABLE")" != "0" ]]; then
-      echo "REMEDIATION (rebuild each diverged device's MISSING panes from its captured immutable bundle):"
-      while IFS= read -r -d '' dev; do
-        comps=$(jq -r --arg d "$dev" '(.bundles[$d].components // []) | join(",")' "$BEFORE")
-        if [[ -z "$comps" ]]; then
-          printf 'ERROR: no captured bundle for device %q in the before-file; cannot recommend a union-consistent restore.\n' "$dev" >&2
-          continue
-        fi
-        pane_args=""
-        while IFS= read -r -d '' pk; do
-          pane_args+=$(printf ' --pane %q' "$pk")
-        done < <(jq -j --arg d "$dev" \
-          '[.[] | select(.pane.device == $d) | "\(.pane.tabKey)#\(.pane.paneId)"] | unique | .[] | . + "\u0000"' \
-          <<<"$REMEDIABLE")
-        printf '  scripts/restore-tabs.sh --url %q --token <TOKEN> --device %q --components %s --force%s\n' \
-          "$URL" "$dev" "$comps" "$pane_args"
-      done < <(jq -j '[.[].pane.device] | unique | .[] | . + "\u0000"' <<<"$REMEDIABLE")
+      echo "REMEDIATION (UI recovery flow): open a FRESH browser context (new profile or incognito window) against ${URL} and sign in."
+      echo "The recover-my-panes offer surfaces the captured snapshot for each affected device; accept it to rebuild the missing panes with their captured session identity."
+      jq -r '[.[].pane.device] | unique | .[] | "  affected device: \(.)"' <<<"$REMEDIABLE"
     fi
     cleanup; exit 1
     ;;
diff --git a/scripts/restore-tabs.sh b/scripts/restore-tabs.sh
deleted file mode 100755
index e6d47d538..000000000
--- a/scripts/restore-tabs.sh
+++ /dev/null
@@ -1,121 +0,0 @@
-#!/usr/bin/env bash
-# restore-tabs.sh -- rebuild a device's tabs from its newest (or Nth) tabs-sync
-# snapshot generation. Continuity trio deliverable 1
-# (docs/plans/2026-07-22-continuity-safety-trio.md).
-#
-#   scripts/restore-tabs.sh --url http://127.0.0.1:PORT --token TOK --list
-#   scripts/restore-tabs.sh --url http://127.0.0.1:PORT --token TOK \
-#       --device <deviceId> [--generation N | --generation-id ID] [--force] [--dry-run]
-#
-# DEFAULT (no --generation/--generation-id): restores the COHERENT all-clients
-# UNION for the device -- no single client's tabs are dropped. Pass
-# --generation-id ID (a stable content digest from --list) to restore a specific
-# past point-in-time file; --generation N is the positional (index) form.
-#
-# The target browser/device should be CONNECTED when you run this: restored
-# tabs are delivered live via ui.command{tab.create}. Requires curl + jq.
-# NOTE: --url is REQUIRED on purpose (no default) -- never point tooling at a
-# server you did not intend.
-set -euo pipefail
-
-URL="" TOKEN="${FRESHELL_TOKEN:-}" DEVICE="" GENERATION="" GENERATION_ID="" COMPONENTS="" DRY_RUN=false FORCE=false LIST=false
-PANES=()   # repeatable --pane "tabKey#paneId": restore ONLY these panes (targeted remediation)
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --url) URL="$2"; shift 2 ;;
-    --token) TOKEN="$2"; shift 2 ;;
-    --device) DEVICE="$2"; shift 2 ;;
-    --generation) GENERATION="$2"; shift 2 ;;
-    --generation-id) GENERATION_ID="$2"; shift 2 ;;
-    --components) COMPONENTS="$2"; shift 2 ;;   # comma-separated generation ids (the deploy bundle)
-    --pane) PANES+=("$2"); shift 2 ;;           # repeatable; server rejects unknown keys fail-closed
-    --dry-run) DRY_RUN=true; shift ;;
-    --force) FORCE=true; shift ;;
-    --list) LIST=true; shift ;;
-    -h|--help) grep '^#' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
-    *) echo "unknown argument: $1" >&2; exit 2 ;;
-  esac
-done
-[[ -n "$URL" ]] || { echo "ERROR: --url is required" >&2; exit 2; }
-[[ -n "$TOKEN" ]] || { echo "ERROR: --token (or FRESHELL_TOKEN) is required" >&2; exit 2; }
-
-auth=(-H "x-auth-token: ${TOKEN}")
-
-# Print a loud failure WITHOUT masking the server's refusal: curl runs with
-# --fail-with-body so an HTTP error still yields the response body, and the
-# server's explanation (e.g. the 409 "restore requires exactly one connected
-# browser" gate) reaches the operator. Prefers the JSON .message/.error field,
-# falls back to the raw body, and keeps the generic hint when there is no body.
-#   $1 = what failed, $2 = generic hint, $3 = response body (may be empty)
-fail_loud() {
-  local msg=""
-  if [[ -n "$3" ]]; then
-    msg=$(jq -r '.message // .error // empty' <<<"$3" 2>/dev/null) || msg=""
-    printf 'ERROR: %s: %s\n' "$1" "${msg:-$3}" >&2
-  else
-    printf 'ERROR: %s (%s)\n' "$1" "$2" >&2
-  fi
-  exit 1
-}
-
-if $LIST; then
-  resp=$(curl --fail-with-body -sS "${auth[@]}" "${URL}/api/tabs-sync/snapshots") ||
-    fail_loud "list request failed" "URL/token correct? server up?" "${resp:-}"
-  jq -r '
-    .devices[] | .deviceId as $d | .generations[] |
-    "\($d)\tgen=\(.generation)\tid=\(.generationId)\trev=\(.snapshotRevision)\trecords=\(.recordCount)\tcapturedAt=\(.capturedAt)\tlabel=\(.deviceLabel)"' <<<"$resp"
-  exit 0
-fi
-
-[[ -n "$DEVICE" ]] || { echo "ERROR: --device is required (try --list)" >&2; exit 2; }
-
-# Send a selector ONLY when explicitly asked; otherwise the server restores the
-# coherent union (the safe multi-client default). Priority mirrors the server:
-# --components (immutable multi-client bundle) > --generation-id > --generation.
-body=$(jq -n --arg d "$DEVICE" --argjson dry "$DRY_RUN" --argjson force "$FORCE" \
-  '{deviceId: $d, dryRun: $dry, force: $force}')
-sel="union"
-if [[ -n "$COMPONENTS" ]]; then
-  # Split the CSV into a JSON string array (no single-client substitution).
-  comps=$(jq -Rn --arg c "$COMPONENTS" '$c | split(",") | map(select(length>0))')
-  body=$(jq --argjson c "$comps" '. + {components: $c}' <<<"$body"); sel="components=$COMPONENTS"
-elif [[ -n "$GENERATION_ID" ]]; then
-  body=$(jq --arg g "$GENERATION_ID" '. + {generationId: $g}' <<<"$body"); sel="generationId=$GENERATION_ID"
-elif [[ -n "$GENERATION" ]]; then
-  body=$(jq --argjson g "$GENERATION" '. + {generation: $g}' <<<"$body"); sel="generation=$GENERATION"
-fi
-# Targeted remediation (deploy-tab-diff): restore ONLY the named panes. Each
-# --pane value becomes one JSON string; the server 400s on unknown keys and
-# reports unselected panes as skipped{not-selected} -- never a silent drop.
-if [[ ${#PANES[@]} -gt 0 ]]; then
-  panes_json=$(printf '%s\0' "${PANES[@]}" | jq -Rs 'split("\u0000") | map(select(length>0))')
-  body=$(jq --argjson p "$panes_json" '. + {panes: $p}' <<<"$body")
-  sel="$sel panes=${#PANES[@]}"
-fi
-resp=$(curl --fail-with-body -sS "${auth[@]}" -H 'content-type: application/json' \
-  -d "$body" "${URL}/api/tabs-sync/restore") ||
-  fail_loud "restore request failed" "is the snapshot/device id right? try --list" "${resp:-}"
-
-echo "== restore ${DEVICE} (${sel}) =="
-echo "$resp" | jq -r '
-  (.restored[] | "RESTORED  \(.kind)\t\(.tabKey)  tabId=\(.tabId)  terminalId=\(.terminalId // "-")"),
-  (.skipped[]  | "SKIPPED   \(.kind)\t\(.tabKey)  reason=\(.reason)"),
-  (.failed[]   | "FAILED    \(.kind)\t\(.tabKey)  reason=\(.reason // "-")  status=\(.status // "-")  \(.error // "" | tostring)")'
-restored=$(echo "$resp" | jq '.restored | length')
-skipped=$(echo "$resp" | jq '.skipped | length')
-failedn=$(echo "$resp" | jq '.failed | length')
-confirmed=$(echo "$resp" | jq -r '.deliveryConfirmed == true')
-echo "-- restored=${restored} skipped=${skipped} failed=${failedn}"
-[[ "$failedn" == "0" ]] || exit 1
-if $FORCE && [[ "$confirmed" != "true" ]]; then
-  echo "ERROR: forced restore was not confirmed by the target browser" >&2
-  exit 1
-fi
-if $FORCE && [[ "$restored" == "0" ]]; then
-  echo "ERROR: forced restore created no panes" >&2
-  exit 1
-fi
-if [[ ${#PANES[@]} -gt 0 && "$restored" == "0" ]]; then
-  echo "ERROR: targeted restore created no panes; rerun with --force if they are missing" >&2
-  exit 1
-fi
diff --git a/test/e2e-browser/playwright.config.ts b/test/e2e-browser/playwright.config.ts
index 2196795c4..f98e14f15 100644
--- a/test/e2e-browser/playwright.config.ts
+++ b/test/e2e-browser/playwright.config.ts
@@ -79,7 +79,6 @@ const MATRIX_SPECS = [
 // CONTINUITY TRIO: rust-only specs kept out of every match-all project
 // (their e2eServerKind:'rust' guard FAILS under the fixture-default 'legacy').
 const RUST_ONLY_SPECS = [
-  /snapshot-restore-rust\.spec\.ts$/,
   /continuity-smoke\.spec\.ts$/,
   /deploy-tab-diff-rust\.spec\.ts$/,
   // COMPOUND-RESTART: drives RustServer.restartAbrupt() (SIGKILL + reboot),
@@ -237,10 +236,6 @@ export default defineConfig({
         // frozen legacy server/ tree has no equivalent. See
         // diag03-rotation-redaction-rust.spec.ts.
         /diag03-rotation-redaction-rust\.spec\.ts$/,
-        // CONTINUITY TRIO deliverable 1 (docs/plans/2026-07-22-continuity-safety-trio.md):
-        // snapshot generations + one-command restore round-trip. Rust-only:
-        // legacy has no persisted snapshot generations or restore endpoint.
-        /snapshot-restore-rust\.spec\.ts$/,
         // CONTINUITY TRIO deliverable 3: deploy tab-diff ritual acceptance
         // (capture -> restart -> verify OK; identity loss fails loudly + remediates).
         /deploy-tab-diff-rust\.spec\.ts$/,
diff --git a/test/e2e-browser/specs/continuity-smoke.spec.ts b/test/e2e-browser/specs/continuity-smoke.spec.ts
index a8dcf0b7c..2f6be2e05 100644
--- a/test/e2e-browser/specs/continuity-smoke.spec.ts
+++ b/test/e2e-browser/specs/continuity-smoke.spec.ts
@@ -106,8 +106,8 @@ async function selectShellIfPickerShowing(page: import('@playwright/test').Page)
 
 // Find a provider pane's Redux content by scanning every tab's pane layout
 // (uniform same-session evidence -- GET /api/terminals DELIBERATELY omits
-// `sessionRef` for codex/shell items, see terminals.rs). Same shape as
-// snapshot-restore-rust.spec.ts's codexPane, parameterized by mode.
+// `sessionRef` for codex/shell items, see terminals.rs). Same shape as the
+// retired snapshot-restore-rust spec's codexPane, parameterized by mode.
 async function paneByMode(harness: TestHarness, mode: Provider): Promise<any | null> {
   const state = await harness.getState()
   for (const tab of state?.tabs?.tabs ?? []) {
diff --git a/test/e2e-browser/specs/deploy-tab-diff-rust.spec.ts b/test/e2e-browser/specs/deploy-tab-diff-rust.spec.ts
index 3455e030f..101bc7b5e 100644
--- a/test/e2e-browser/specs/deploy-tab-diff-rust.spec.ts
+++ b/test/e2e-browser/specs/deploy-tab-diff-rust.spec.ts
@@ -16,14 +16,13 @@ import { TestHarness } from '../helpers/test-harness.js'
  *
  *   (1) LIVE: capture -> restart -> verify passes when identity survives;
  *       then a provably-removed codex pane makes verify FAIL LOUDLY
- *       (non-zero exit, named tab, MISSING verdict, remediation line), and
- *       EXECUTING the printed `--components` bundle remediation brings the
- *       session back -- proven by the fake-CLI argv `resume <sessionId>` log.
+ *       (non-zero exit, named tab, MISSING verdict, and a remediation note
+ *       pointing the operator at the UI recovery flow -- recover-my-panes,
+ *       whose end-to-end acceptance lives in recover-my-panes-rust.spec.ts).
  *   (2) OFFLINE: a deterministic diff-engine run (`verify --before F --after F`)
- *       over synthetic fixtures exercises ALL FOUR verdicts, the
- *       partial-coverage set-difference guard, and the multi-client bundle
- *       remediation -- with a fake `curl` proving verify makes ZERO network
- *       calls in --after mode.
+ *       over synthetic fixtures exercises ALL FIVE verdicts and the
+ *       partial-coverage set-difference guard -- with a fake `curl` proving
+ *       verify makes ZERO network calls in --after mode.
  *
  * Rust-only: legacy has no persisted snapshot generations. Registered ONLY
  * under `rust-chromium`; testIgnore'd via RUST_ONLY_SPECS everywhere else.
@@ -50,16 +49,6 @@ async function installFakeCodexCli(binDir: string): Promise<string> {
   return target
 }
 
-// Fake-CLI argv resume proof (copied from codex-terminal-bounce-rust.spec.ts:75-85).
-async function readArgvLog(logPath: string): Promise<Array<{ argv: string[] }>> {
-  const raw = await fs.readFile(logPath, 'utf8').catch(() => '')
-  return raw.trim().split('\n').filter(Boolean).map((l) => JSON.parse(l) as { argv: string[] })
-}
-function hasResumePair(argv: string[], sessionId: string): boolean {
-  const idx = argv.indexOf('resume')
-  return idx >= 0 && argv[idx + 1] === sessionId
-}
-
 async function connect(page: import('@playwright/test').Page, info: any): Promise<TestHarness> {
   await page.goto(`${info.baseUrl}/?token=${info.token}&e2e=1`)
   const harness = new TestHarness(page)
@@ -96,18 +85,17 @@ test.describe('deploy tab-diff ritual (rust only, ephemeral server)', () => {
     test.setTimeout(240_000)
     // EPHEMERAL-ONLY: new RustServer(...) directly (never createE2eServerHandle).
     const sharedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'fakecodex-'))
-    const argLogPath = path.join(sharedRoot, 'argv.jsonl')
     const projectDir = path.join(sharedRoot, 'project')
     await fs.mkdir(projectDir, { recursive: true })
     const fakeCodexPath = await installFakeCodexCli(path.join(sharedRoot, 'bin'))
     const server = new RustServer({
-      // CODEX_CMD + FAKE_CODEX_ARGV_LOG wiring copied from codex-terminal-bounce-rust.spec.ts.
-      env: { CODEX_CMD: fakeCodexPath, FAKE_CODEX_ARGV_LOG: argLogPath },
+      // CODEX_CMD wiring copied from codex-terminal-bounce-rust.spec.ts.
+      env: { CODEX_CMD: fakeCodexPath },
       setupHome: async (homeDir) => {
-        // Config seeding copied from codex-terminal-bounce-rust.spec.ts /
-        // snapshot-restore-rust.spec.ts: enabled providers + a real-reader
-        // codex session seed (`session_meta` + message records) so
-        // `codex resume <SESSION_ID>` targets an existing session.
+        // Config seeding copied from codex-terminal-bounce-rust.spec.ts:
+        // enabled providers + a real-reader codex session seed
+        // (`session_meta` + message records) so `codex resume <SESSION_ID>`
+        // targets an existing session.
         const freshellDir = path.join(homeDir, '.freshell')
         await fs.mkdir(freshellDir, { recursive: true })
         await fs.writeFile(path.join(freshellDir, 'config.json'), JSON.stringify({
@@ -207,72 +195,19 @@ test.describe('deploy tab-diff ritual (rust only, ephemeral server)', () => {
         expect(r.devices.some((d: any) => d.generations[0]?.capturedAt > before2Cap)).toBe(true)
       }).toPass({ timeout: 30_000 })
 
-      const tabCountBeforeRemediation = await harness.getTabCount() // codex closed; shell survives
       const bad = await tabDiff(['verify', '--url', info.baseUrl, '--token', info.token, '--before', before2])
       expect(bad.code).not.toBe(0)                         // exits non-zero
       expect(bad.out).toContain('TAB-DIFF DIVERGENCE')     // loud
       expect(bad.out).toMatch(/MISSING/)                   // names the category (closed codex pane)
       expect(bad.out).toContain('tab=work')                // names the diverged tab
-      expect(bad.out).toContain('scripts/restore-tabs.sh') // prints the remediation
-      // Remediation references the immutable multi-client BUNDLE (--components,
-      // stable digests), NEVER a single-client --generation-id (:2621), and is
-      // TARGETED (:175): one --pane per diverged pane, so still-healthy panes
-      // are never re-restored.
-      expect(bad.out).toMatch(/--components [0-9a-f,]+/)
-      expect(bad.out).toMatch(/--pane \S+/)
-      expect(bad.out).toMatch(/--force/)
-      expect(bad.out).not.toMatch(/--generation-id/)
-      expect(bad.out).not.toMatch(/--generation \d/)
-
-      // -- EXECUTE the printed remediation (substituting the real token) and prove
-      //    the missing codex session comes back. Only 1 browser connected -> the
-      //    restore exactly-one-client gate allows it. --
-      const comps = bad.out.match(/--components ([0-9a-f,]+)/)![1]
-      const dev = bad.out.match(/--device (\S+)/)![1]
-      // The printed pane keys are %q-quoted for the shell; strip backslash
-      // escapes when passing them as direct argv entries.
-      const paneArgs = [...bad.out.matchAll(/--pane (\S+)/g)]
-        .flatMap((m) => ['--pane', m[1].replace(/\\/g, '')])
-      expect(paneArgs.length).toBeGreaterThan(0)
-      const argvBefore = (await readArgvLog(argLogPath)).length
-      const rem = await run('scripts/restore-tabs.sh',
-        ['--url', info.baseUrl, '--token', info.token, '--device', dev, '--components', comps, '--force', ...paneArgs],
-        { cwd: process.cwd() })
-      expect(rem.stdout).toContain('failed=0')
-      await expect(async () => {
-        expect(await codexPaneSession(harness)).toBe(SESSION_ID) // the session identity returned
-      }).toPass({ timeout: 20_000 })
-      // RESUME PROOF: the remediation re-spawned codex with `resume <sessionId>`
-      // (argv-log delta), not plain `codex` -- identity echo alone is insufficient.
-      await expect(async () => {
-        const entries = (await readArgvLog(argLogPath)).slice(argvBefore)
-        expect(entries.some((e) => hasResumePair(e.argv, SESSION_ID)),
-          'remediation must exec `codex resume <sessionId>`').toBe(true)
-      }).toPass({ timeout: 20_000 })
-      // TARGETED (:175): ONLY the missing codex pane was restored -- the
-      // surviving shell pane is NOT duplicated and the total tab count is
-      // exactly the pre-failure count (codex back, shell untouched).
-      await expect(async () => {
-        const st = await harness.getState()
-        const shellTabs = st.tabs.tabs.filter((t: any) => t.title === 'sh' || t.name === 'sh')
-        expect(shellTabs.length, 'surviving shell tab must not be duplicated').toBeLessThanOrEqual(1)
-        expect(await harness.getTabCount()).toBe(tabCountBeforeRemediation + 1) // codex back, nothing else
-      }).toPass({ timeout: 20_000 })
-
-      // Repeat recovery: remove the pane AFTER its marker says restored, then
-      // execute the same forced remediation again in the same server process.
-      // This is the path that used to return only `already-restored`/a fence.
-      const tabCountBeforeRepeat = await harness.getTabCount()
-      await closeCodexTab(page, harness)
-      const repeat = await run('scripts/restore-tabs.sh',
-        ['--url', info.baseUrl, '--token', info.token, '--device', dev, '--components', comps, '--force', ...paneArgs],
-        { cwd: process.cwd() })
-      expect(repeat.stdout).toContain('restored=1')
-      expect(repeat.stdout).toContain('failed=0')
-      await expect(async () => {
-        expect(await codexPaneSession(harness)).toBe(SESSION_ID)
-        expect(await harness.getTabCount()).toBe(tabCountBeforeRepeat)
-      }).toPass({ timeout: 20_000 })
+      // Remediation points the operator at the UI recovery flow (the operator
+      // server-push restore machinery was deleted in the kata h9vt cleanup;
+      // the UI flow's end-to-end acceptance lives in
+      // recover-my-panes-rust.spec.ts).
+      expect(bad.out).toContain('REMEDIATION (UI recovery flow)')
+      expect(bad.out).toMatch(/recover-my-panes offer/)
+      expect(bad.out).toMatch(/affected device: \S+/)
+      expect(bad.out).not.toContain('restore-tabs.sh')
     } finally {
       await server.stop()
       await fs.rm(tmpDir, { recursive: true, force: true })
@@ -281,11 +216,11 @@ test.describe('deploy tab-diff ritual (rust only, ephemeral server)', () => {
   })
 
   // (2) DETERMINISTIC OFFLINE diff-engine coverage: drive `verify --before F
-  // --after F` over synthetic fixtures so ALL FIVE verdicts, the full-set-difference
-  // coverage guard, and the multi-client bundle remediation are exercised (the live
-  // path can only produce MISSING). With --after supplied verify does ZERO network
-  // ops (:2619) -- proven by prepending a fake `curl` that ABORTS if invoked.
-  test('verify classifies verdicts, guards partial coverage, remediates via bundle -- fully offline', async () => {
+  // --after F` over synthetic fixtures so ALL FIVE verdicts and the
+  // full-set-difference coverage guard are exercised (the live path can only
+  // produce MISSING). With --after supplied verify does ZERO network ops
+  // (:2619) -- proven by prepending a fake `curl` that ABORTS if invoked.
+  test('verify classifies verdicts, guards partial coverage, points at the UI recovery flow -- fully offline', async () => {
     const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'tabdiff-unit-'))
     // A fake `curl` that aborts (exit 99) on ANY invocation -- the offline guard.
     const binDir = path.join(tmp, 'bin'); await fs.mkdir(binDir)
@@ -345,26 +280,15 @@ test.describe('deploy tab-diff ritual (rust only, ephemeral server)', () => {
     expect(d.out).toContain('NO CAPTURED IDENTITY')
     expect(d.out).toContain('dev-1:cliNoId')
     expect((d.out.match(/NO CAPTURED IDENTITY/g) ?? []).length).toBe(1)
-    // Snapshots carry no identity for it, so restore-tabs.sh CANNOT rebuild
-    // it -- it must be excluded from the --pane remediation and called out
-    // for manual provider-store recovery instead.
-    expect(d.out).not.toContain('--pane dev-1:cliNoId#p-terminal')
+    // Snapshots carry no identity for it, so no snapshot-driven recovery can
+    // rebuild it -- it must be called out for manual provider-store recovery.
     expect(d.out).toMatch(/identity was never captured/i)
-    // Remediation uses the immutable MULTI-CLIENT bundle (BOTH component ids), not
-    // a single-client --generation-id (:2621).
-    expect(d.out).toMatch(/--components aaaa1111,bbbb2222/)
-    expect(d.out).toMatch(/--force/)
-    expect(d.out).not.toMatch(/--generation-id/)
-    // ...and is TARGETED (:175): one --pane per diverged paneKey, so a restore
-    // of the whole union (which would duplicate healthy panes) is never printed.
-    for (const key of [
-      'dev-1:codexMiss#p-terminal',
-      'dev-1:codexRepoint#p-terminal',
-      'dev-1:codexFresh#p-terminal',
-      'dev-1:sh#p-terminal',
-    ]) {
-      expect(d.out).toContain(`--pane ${key}`)
-    }
+    // Remediation points the operator at the UI recovery flow (recover-my-panes)
+    // and names the affected device.
+    expect(d.out).toContain('REMEDIATION (UI recovery flow)')
+    expect(d.out).toMatch(/recover-my-panes offer/)
+    expect(d.out).toContain('affected device: dev-1')
+    expect(d.out).not.toContain('restore-tabs.sh')
 
     // PARTIAL-coverage guard (:2559): TWO running terminals, only ONE covered by a
     // snapshot pane -> still FAILS, LISTING the uncovered one (not a silent OK).
@@ -381,100 +305,6 @@ test.describe('deploy tab-diff ritual (rust only, ephemeral server)', () => {
     await fs.rm(tmp, { recursive: true, force: true })
   })
 
-  test('targeted restore fails on an all-skipped response and passes force through to the API', async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'restore-tabs-contract-'))
-    try {
-      const binDir = path.join(tmp, 'bin')
-      const requestBody = path.join(tmp, 'request.json')
-      await fs.mkdir(binDir)
-      await fs.writeFile(path.join(binDir, 'curl'), `#!/usr/bin/env bash
-set -euo pipefail
-body=""
-while [[ $# -gt 0 ]]; do
-  if [[ "$1" == "-d" ]]; then
-    body="$2"
-    shift 2
-  else
-    shift
-  fi
-done
-printf '%s' "$body" > "$FAKE_CURL_BODY"
-printf '%s' "$FAKE_CURL_RESPONSE"
-`, { mode: 0o755 })
-      const invoke = async (response: unknown, force = false) => {
-        const args = [
-          '--url', 'http://unused.invalid',
-          '--token', 't',
-          '--device', 'dev-1',
-          '--pane', 'dev-1:work#pane-1',
-          ...(force ? ['--force'] : []),
-        ]
-        try {
-          const { stdout, stderr } = await run('scripts/restore-tabs.sh', args, {
-            cwd: process.cwd(),
-            env: {
-              ...process.env,
-              PATH: `${binDir}:${process.env.PATH}`,
-              FAKE_CURL_BODY: requestBody,
-              FAKE_CURL_RESPONSE: JSON.stringify(response),
-            },
-          })
-          return { code: 0, out: `${stdout}${stderr}` }
-        } catch (err: any) {
-          return { code: err.code ?? 1, out: `${err.stdout ?? ''}${err.stderr ?? ''}` }
-        }
-      }
-
-      const skipped = await invoke({
-        deliveryConfirmed: true,
-        restored: [],
-        skipped: [{
-          tabKey: 'dev-1:work',
-          paneId: 'pane-1',
-          kind: 'terminal',
-          reason: 'already-restored',
-        }],
-        failed: [],
-      })
-      expect(skipped.code).not.toBe(0)
-      expect(skipped.out).toContain('targeted restore created no panes')
-      expect(JSON.parse(await fs.readFile(requestBody, 'utf8')).force).toBe(false)
-
-      const unconfirmed = await invoke({
-        deliveryConfirmed: false,
-        restored: [{
-          tabKey: 'dev-1:work',
-          paneId: 'pane-1',
-          kind: 'terminal',
-          tabId: 'undelivered-tab',
-          terminalId: 'existing-terminal',
-        }],
-        skipped: [],
-        failed: [],
-      }, true)
-      expect(unconfirmed.code).not.toBe(0)
-      expect(unconfirmed.out).toContain('forced restore was not confirmed')
-
-      const forced = await invoke({
-        deliveryConfirmed: true,
-        restored: [{
-          tabKey: 'dev-1:work',
-          paneId: 'pane-1',
-          kind: 'terminal',
-          tabId: 'replacement-tab',
-          terminalId: 'existing-terminal',
-        }],
-        skipped: [],
-        failed: [],
-      }, true)
-      expect(forced.code).toBe(0)
-      expect(forced.out).toContain('restored=1')
-      expect(JSON.parse(await fs.readFile(requestBody, 'utf8')).force).toBe(true)
-    } finally {
-      await fs.rm(tmp, { recursive: true, force: true })
-    }
-  })
-
   test('capture rejects same-digest generation churn and preserves the prior artifact', async () => {
     const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'tabdiff-coherence-'))
     try {
diff --git a/test/e2e-browser/specs/recover-my-panes-rust.spec.ts b/test/e2e-browser/specs/recover-my-panes-rust.spec.ts
index 559f157ca..2db0e62cf 100644
--- a/test/e2e-browser/specs/recover-my-panes-rust.spec.ts
+++ b/test/e2e-browser/specs/recover-my-panes-rust.spec.ts
@@ -105,8 +105,8 @@ async function readArgvLog(logPath: string): Promise<Array<{ argv: string[] }>>
 /**
  * Claude-adapted adjacent-pair matcher (per the task brief's Interfaces): the
  * fake claude CLI receives the `--resume <id>` FLAG (fake-claude-cli.mjs:26-30)
- * — NOT codex's bare `resume` subcommand token, so snapshot-restore-rust's
- * `hasResumePair` would never match here.
+ * — NOT codex's bare `resume` subcommand token, so a codex-style
+ * `resume <id>` adjacent-pair matcher would never match here.
  */
 const hasClaudeResumePair = (argv: string[], sessionId: string) => {
   const i = argv.indexOf('--resume')
@@ -121,7 +121,7 @@ function sessionIdsOf(entries: Array<{ argv: string[] }>): string[] {
   })
 }
 
-/** Donor: snapshot-restore-rust.spec.ts:74 — boot a page against the server. */
+/** Boot a page against the server (donor: the retired snapshot-restore-rust spec). */
 async function connect(page: Page, info: { baseUrl: string; token: string }): Promise<TestHarness> {
   await page.goto(`${info.baseUrl}/?token=${info.token}&e2e=1`)
   const harness = new TestHarness(page)
diff --git a/test/e2e-browser/specs/snapshot-restore-rust.spec.ts b/test/e2e-browser/specs/snapshot-restore-rust.spec.ts
deleted file mode 100644
index e26986d90..000000000
--- a/test/e2e-browser/specs/snapshot-restore-rust.spec.ts
+++ /dev/null
@@ -1,304 +0,0 @@
-import { execFile } from 'node:child_process'
-import fs from 'node:fs/promises'
-import os from 'node:os'
-import path from 'node:path'
-import { promisify } from 'node:util'
-import { fileURLToPath } from 'node:url'
-import { test, expect } from '../helpers/fixtures.js'
-import { RustServer } from '../helpers/rust-server.js'
-import { TestHarness } from '../helpers/test-harness.js'
-
-/**
- * CONTINUITY TRIO deliverable 1 acceptance
- * (docs/plans/2026-07-22-continuity-safety-trio.md): the full
- * snapshot -> wipe -> one-command restore round-trip.
- *
- * Scenario:
- *   1. A browser client populates mixed tabs (shell terminal, browser pane,
- *      and a codex terminal carrying session identity in `sessionRef`).
- *   2. The client's tabs.sync push persists a snapshot generation server-side
- *      (Task 1), readable via GET /api/tabs-sync/snapshots[/{deviceId}] (Task 2).
- *   3. The client's state is WIPED (fresh browser context = empty tab set).
- *   4. `scripts/restore-tabs.sh` (Task 4) drives POST /api/tabs-sync/restore
- *      (Task 3): exactly-one-browser gate (proven with a bystander -> 409),
- *      then a real restore into the single wiped client.
- *   5. The restored tabs point at the SAME sessions: the codex pane carries
- *      the identical `sessionRef` on a NEW terminal, AND the recorded fake-CLI
- *      argv proves the server re-spawned `codex resume <sessionId>` (a Redux
- *      sessionRef echo alone would not prove the server passed resume args).
- *   6. A second restore of the same generation is a no-op (marker idempotency).
- *
- * Rust-only: legacy has no persisted snapshot generations or restore endpoint.
- * This spec is registered ONLY under `rust-chromium` and testIgnore'd on every
- * match-all project (see playwright.config.ts's RUST_ONLY_SPECS).
- *
- * EPHEMERAL-ONLY SAFETY: the server is constructed DIRECTLY via `new
- * RustServer(...)` -- throwaway binary, ephemeral loopback port, mkdtemp HOME.
- * NEVER `createE2eServerHandle(process.env, ...)`: with FRESHELL_E2E_TARGET_URL
- * set it silently retargets to an already-running (possibly LIVE) server.
- */
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-
-const FAKE_CODEX_CLI_SOURCE = path.resolve(__dirname, '../fixtures/fake-codex-cli.mjs')
-const RESTORE_SCRIPT = path.resolve(__dirname, '../../../scripts/restore-tabs.sh')
-
-const run = promisify(execFile)
-const CODEX_SESSION_ID = '11111111-2222-4333-8444-555555555555'
-const SESSION_TITLE = 'snapshot-restore seeded codex session'
-
-async function installFakeCodexCli(binDir: string): Promise<string> {
-  await fs.mkdir(binDir, { recursive: true })
-  const target = path.join(binDir, 'codex')
-  await fs.copyFile(FAKE_CODEX_CLI_SOURCE, target)
-  await fs.chmod(target, 0o755)
-  return target
-}
-
-/** Read the fake CLI's argv-log JSONL (empty array if not yet written). */
-async function readArgvLog(logPath: string): Promise<Array<{ argv: string[] }>> {
-  const raw = await fs.readFile(logPath, 'utf8').catch(() => '')
-  if (!raw) return []
-  return raw.trim().split('\n').filter(Boolean).map((line) => JSON.parse(line) as { argv: string[] })
-}
-
-/** True when the argv tokens contain the adjacent pair `resume <sessionId>`. */
-function hasResumePair(argv: string[], sessionId: string): boolean {
-  const idx = argv.indexOf('resume')
-  return idx >= 0 && argv[idx + 1] === sessionId
-}
-
-// Boot a page against an already-started server (mirror of the inline sequence
-// in codex-terminal-bounce-rust.spec.ts; there is NO bootAndConnect helper).
-async function connect(
-  page: import('@playwright/test').Page,
-  info: { baseUrl: string; token: string },
-): Promise<TestHarness> {
-  await page.goto(`${info.baseUrl}/?token=${info.token}&e2e=1`)
-  const harness = new TestHarness(page)
-  await harness.waitForHarness()
-  await harness.waitForConnection()
-  return harness
-}
-
-// Find the codex pane's Redux content by scanning every tab's pane layout
-// (uniform same-session evidence for codex, which GET /api/terminals
-// DELIBERATELY omits `sessionRef` for -- terminals.rs).
-async function codexPane(harness: TestHarness): Promise<any | null> {
-  const state = await harness.getState()
-  for (const tab of state?.tabs?.tabs ?? []) {
-    const layout = state?.panes?.layouts?.[tab.id]
-    if (layout?.type === 'leaf' && layout.content?.kind === 'terminal' && layout.content?.mode === 'codex') {
-      return layout.content
-    }
-  }
-  return null
-}
-
-test.describe('tabs-sync snapshot -> wipe -> one-command restore (rust only)', () => {
-  test('restored tabs point at the SAME sessions', async ({ browser, e2eServerKind }) => {
-    expect(e2eServerKind).toBe('rust') // rust-only guard (spec is also in every match-all project's testIgnore)
-    test.setTimeout(240_000)
-
-    const sharedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'freshell-snapshot-restore-'))
-    const argLogPath = path.join(sharedRoot, 'fake-codex-argv.jsonl')
-    const projectDir = path.join(sharedRoot, 'project')
-    await fs.mkdir(projectDir, { recursive: true })
-
-    try {
-      const fakeCodexPath = await installFakeCodexCli(path.join(sharedRoot, 'bin'))
-
-      // EPHEMERAL-ONLY: construct RustServer directly (throwaway port +
-      // mkdtemp HOME). NEVER createE2eServerHandle -- see file doc comment.
-      const server = new RustServer({
-        env: { CODEX_CMD: fakeCodexPath, FAKE_CODEX_ARGV_LOG: argLogPath },
-        setupHome: async (homeDir) => {
-          const freshellDir = path.join(homeDir, '.freshell')
-          await fs.mkdir(freshellDir, { recursive: true })
-          await fs.writeFile(path.join(freshellDir, 'config.json'), JSON.stringify({
-            version: 1,
-            settings: {
-              codingCli: { enabledProviders: ['claude', 'codex', 'opencode'] },
-            },
-          }, null, 2))
-
-          // Same real-reader seed shape as `codex-terminal-bounce-rust.spec.ts` /
-          // `sidebar-click-resume.spec.ts`: a `session_meta` record carrying
-          // `payload.id`/`cwd` plus message records for a title.
-          const codexSessionsDir = path.join(homeDir, '.codex', 'sessions')
-          await fs.mkdir(codexSessionsDir, { recursive: true })
-          const lines = [
-            JSON.stringify({
-              timestamp: '2026-07-21T08:00:00.000Z',
-              type: 'session_meta',
-              payload: { id: CODEX_SESSION_ID, cwd: projectDir },
-            }),
-            JSON.stringify({
-              timestamp: '2026-07-21T08:00:01.000Z',
-              type: 'response_item',
-              payload: {
-                type: 'message',
-                role: 'user',
-                content: [{ type: 'input_text', text: `${SESSION_TITLE} request 1` }],
-              },
-            }),
-            JSON.stringify({
-              timestamp: '2026-07-21T08:00:02.000Z',
-              type: 'response_item',
-              payload: {
-                type: 'message',
-                role: 'assistant',
-                content: [{ type: 'output_text', text: `${SESSION_TITLE} reply 1` }],
-              },
-            }),
-          ]
-          await fs.writeFile(
-            path.join(codexSessionsDir, `${CODEX_SESSION_ID}.jsonl`),
-            `${lines.join('\n')}\n`,
-          )
-        },
-      })
-      const info = await server.start()
-
-      try {
-        // -- populate: one page = one deviceId/clientInstanceId --
-        const ctx1 = await browser.newContext()
-        const page1 = await ctx1.newPage()
-        const harness1 = await connect(page1, info)
-        const baseline = await harness1.getTabCount()
-
-        const auth = { 'x-auth-token': info.token, 'content-type': 'application/json' }
-        const mk = async (body: unknown) => {
-          const r = await fetch(`${info.baseUrl}/api/tabs`, {
-            method: 'POST',
-            headers: auth,
-            body: JSON.stringify(body),
-          })
-          expect(r.ok).toBe(true)
-          return (await r.json()).data // unwrap the {status,data,message} envelope
-        }
-        await mk({ mode: 'shell', name: 'plain shell' })
-        await mk({ browser: 'https://example.com', name: 'docs' })
-        const codex = await mk({
-          mode: 'codex',
-          name: 'codex work',
-          sessionRef: { provider: 'codex', sessionId: CODEX_SESSION_ID },
-        })
-        expect(codex.terminalId).toBeTruthy()
-        const codexTerminalIdBefore = codex.terminalId
-
-        // -- wait for the client's tabs.sync push to persist a generation with
-        //    all three tabs (incl. the codex sessionRef) --
-        let deviceId = ''
-        await expect(async () => {
-          const data = await (await fetch(`${info.baseUrl}/api/tabs-sync/snapshots`, { headers: auth })).json()
-          const dev = (data.devices ?? []).find((d: any) => d.recordCount >= baseline + 3)
-          expect(dev).toBeTruthy()
-          deviceId = dev.deviceId
-          const snap = await (await fetch(
-            `${info.baseUrl}/api/tabs-sync/snapshots/${encodeURIComponent(deviceId)}`,
-            { headers: auth },
-          )).json()
-          const codexPaneSnap = (snap.records ?? []).flatMap((rec: any) => rec.panes ?? [])
-            .find((p: any) => p.payload?.sessionRef?.provider === 'codex')
-          expect(codexPaneSnap?.payload?.sessionRef?.sessionId).toBe(CODEX_SESSION_ID)
-        }).toPass({ timeout: 30_000 })
-
-        // -- BYSTANDER: a SECOND connected browser context stays open. Restore
-        //    drives the create pipeline, which broadcasts tab.create to ALL
-        //    clients; with the wiped client also connected there would be 2
-        //    clients, so restore's connected-client gate must 409. We (a) prove
-        //    the gate with 2 clients, then (b) close the bystander and restore
-        //    into the single wiped client. --
-        const bystanderCtx = await browser.newContext()
-        await connect(await bystanderCtx.newPage(), info)
-
-        // -- wipe: close the populated context (that client's state is gone) --
-        await ctx1.close()
-
-        // -- fresh browser context = the wiped client (empty tab set) --
-        const ctx2 = await browser.newContext()
-        const page2 = await ctx2.newPage()
-        const harness2 = await connect(page2, info)
-        const freshCount = await harness2.getTabCount()
-
-        // (a) GATE: with the wiped client + the bystander connected (>1),
-        // restore is refused (409 -> curl -f fails -> script exits 1).
-        const gated = await run(
-          'bash',
-          [RESTORE_SCRIPT, '--url', info.baseUrl, '--token', info.token, '--device', deviceId],
-        ).catch((e: any) => e)
-        expect(String(gated.stderr ?? gated.stdout ?? '')).toMatch(/refused|409/i)
-
-        // The restore leg's RESUME PROOF is a DELTA beyond this point: the
-        // initial REST create above already spawned `codex resume <id>` once.
-        const argvCountBeforeRestore = (await readArgvLog(argLogPath)).length
-
-        // Close the bystander so exactly ONE client remains, then restore for
-        // real. Retry until the server's connected-client count settles to 1
-        // (a 409 creates nothing + writes no marker, so retrying is safe).
-        await bystanderCtx.close()
-        await expect(async () => {
-          const { stdout } = await run(
-            'bash',
-            [RESTORE_SCRIPT, '--url', info.baseUrl, '--token', info.token, '--device', deviceId],
-          )
-          expect(stdout).toContain('failed=0')
-        }).toPass({ timeout: 20_000 })
-
-        // -- the wiped client received the restored tabs live --
-        await expect(async () => {
-          expect(await harness2.getTabCount()).toBe(freshCount + 3)
-        }).toPass({ timeout: 20_000 })
-
-        // -- SAME session: the restored codex pane carries the identical
-        //    sessionRef (Redux, from the ui.command tab.create payload) on a
-        //    NEW terminal --
-        await expect(async () => {
-          const content = await codexPane(harness2)
-          expect(content?.sessionRef?.sessionId).toBe(CODEX_SESSION_ID)
-          expect(content?.terminalId).toBeTruthy()
-          expect(content?.terminalId).not.toBe(codexTerminalIdBefore)
-        }).toPass({ timeout: 20_000 })
-
-        // -- RESUME PROOF (not identity-echo only): the restore RE-spawned
-        //    codex with `resume <sessionId>` argv (delta beyond the
-        //    pre-restore log, like codex-terminal-bounce-rust.spec.ts's
-        //    bounce leg). A Redux sessionRef could survive even if the server
-        //    ignored it, so assert the RECORDED argv. --
-        await expect(async () => {
-          const entries = await readArgvLog(argLogPath)
-          expect(
-            entries.slice(argvCountBeforeRestore).some((e) => hasResumePair(e.argv, CODEX_SESSION_ID)),
-            'restore must exec `codex resume <sessionId>`',
-          ).toBe(true)
-        }).toPass({ timeout: 20_000 })
-
-        // -- a live codex terminal exists server-side (RAW JSON array; codex
-        //    items deliberately have no sessionRef here) --
-        const terms = await (await fetch(`${info.baseUrl}/api/terminals`, { headers: auth })).json()
-        expect(Array.isArray(terms)).toBe(true)
-        expect(terms.some((t: any) => t.mode === 'codex')).toBe(true)
-
-        // -- IDEMPOTENCY: a second restore of the same generation is a no-op
-        //    (marker skips every pane; nothing new is created) --
-        const { stdout: rerun } = await run(
-          'bash',
-          [RESTORE_SCRIPT, '--url', info.baseUrl, '--token', info.token, '--device', deviceId],
-        )
-        expect(rerun).toMatch(/restored=0/)
-        expect(rerun).toContain('failed=0')
-        await expect(async () => {
-          expect(await harness2.getTabCount()).toBe(freshCount + 3) // unchanged
-        }).toPass({ timeout: 10_000 })
-
-        await ctx2.close()
-      } finally {
-        await server.stop()
-      }
-    } finally {
-      await fs.rm(sharedRoot, { recursive: true, force: true }).catch(() => {})
-    }
-  })
-})

From 10aaa7215ec482d708df3f4d273e490c2af37599 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 07:55:14 -0700
Subject: [PATCH 71/87] test(e2e): reconcile client adoption proofs; flip P1.7
 D8 pin - two clients one sessionRef now yields exactly 1 PTY
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New reconcile-client-adoption-rust.spec.ts (3 scenarios): mixed-pane
  restart recovery driven by verdicts (census never destroys), ONE
  batched dead-session adjudication panel with per-row decisions, and
  double-restart mid-reconcile convergence with no duplicate PTYs.
- Flip the P1.7 (D8) wall pin: the sessionRef single-flight lease +
  reconcile attach-to-winner landed (Tasks 2-13), so the two-clients
  test's exactly-1-PTY assertion now passes; the test.fail pin is
  deleted (an unexpected pass is a hard suite failure).
- Rewrite the double-restart guard's legacy observation: the adopted
  client sends pane.reconcile.request after every ready (asserted via
  the harness sent-message log) and the pane converges to exactly one
  running PTY (asserted via /api/terminals). Name+scenario unchanged.
- Wall claude-terminal fixture realism: real claude writes the session
  transcript to ~/.claude/projects at session start; the fake CLI does
  not. Under the adopted client the post-restart verdict derives from
  disk truth (claimed-but-missing = loud dead_session), so the test now
  mirrors what real claude persists before the SIGKILL. No assertions
  changed.
- Register the new spec in RUST_ONLY_SPECS AND the rust-chromium
  testMatch (collection verified: 3 tests).

Wall audit (A12): full wall run green (15 passed) - no other test.fail
pin unexpectedly passed; all remaining pins still hold.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 test/e2e-browser/playwright.config.ts         |   8 +
 .../reconcile-client-adoption-rust.spec.ts    | 613 ++++++++++++++++++
 .../specs/restore-contract-wall-rust.spec.ts  |  80 ++-
 3 files changed, 684 insertions(+), 17 deletions(-)
 create mode 100644 test/e2e-browser/specs/reconcile-client-adoption-rust.spec.ts

diff --git a/test/e2e-browser/playwright.config.ts b/test/e2e-browser/playwright.config.ts
index c4151f30e..05b1bc551 100644
--- a/test/e2e-browser/playwright.config.ts
+++ b/test/e2e-browser/playwright.config.ts
@@ -127,6 +127,9 @@ const RUST_ONLY_SPECS = [
   // ledger-join coherence, A2xA3 dual claude identity stores). Imports
   // RustServer directly for restartAbrupt().
   /wavea-interactions-rust\.spec\.ts$/,
+  // Reconcile client adoption (Task 14): verdict-driven recovery with the
+  // real SPA. Imports RustServer directly (restart()/restartAbrupt()).
+  /reconcile-client-adoption-rust\.spec\.ts$/,
 ]
 
 export default defineConfig({
@@ -284,6 +287,11 @@ export default defineConfig({
         // ledger-join coherence, A2xA3 dual claude identity stores). Imports
         // RustServer directly for restartAbrupt().
         /wavea-interactions-rust\.spec\.ts$/,
+        // Reconcile client adoption (Task 14): mixed-pane restart recovery,
+        // batched dead-session adjudication, double-restart convergence --
+        // all driven by pane.reconcile verdicts in the real SPA. Rust-only:
+        // imports RustServer directly (restart()/restartAbrupt()).
+        /reconcile-client-adoption-rust\.spec\.ts$/,
       ],
     },
     // CONTINUITY SMOKE (pre-deploy gate): REAL freshell-server binary + REAL
diff --git a/test/e2e-browser/specs/reconcile-client-adoption-rust.spec.ts b/test/e2e-browser/specs/reconcile-client-adoption-rust.spec.ts
new file mode 100644
index 000000000..6e2d1f277
--- /dev/null
+++ b/test/e2e-browser/specs/reconcile-client-adoption-rust.spec.ts
@@ -0,0 +1,613 @@
+/**
+ * RECONCILE CLIENT ADOPTION (Task 14) -- e2e proof that pane.reconcile
+ * verdicts drive recovery end-to-end with the REAL SPA against the REAL Rust
+ * server (docs/plans reconcile-client-adoption lane, Tasks 2-13 merged).
+ *
+ * Three scenario contracts:
+ *   1. restart with mixed pane types: verdicts drive recovery, the legacy
+ *      destructive census never destroys a pane (F3 closed);
+ *   2. dead sessions surface as ONE batched adjudication panel (council
+ *      rule 1) -- nothing auto-closed, per-row explicit decisions;
+ *   3. double-restart mid-reconcile converges: no permanent 'creating'
+ *      wedge, exactly one live PTY per pane (no duplicates).
+ *
+ * Rust-only: registered in RUST_ONLY_SPECS + rust-chromium testMatch, because
+ * this spec imports RustServer directly (restart()/restartAbrupt()).
+ *
+ * Helpers are copied, not imported, per the e2e suite's per-spec-ownership
+ * convention (donor: restore-contract-wall-rust.spec.ts).
+ */
+import { test, expect } from '../helpers/fixtures.js'
+import { RustServer, type TestServerInfo } from '../helpers/rust-server.js'
+import { TestHarness } from '../helpers/test-harness.js'
+import { openPanePicker } from '../helpers/pane-picker.js'
+import type { Page } from '@playwright/test'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const FAKE_CLAUDE_CLI_SOURCE = path.resolve(__dirname, '../fixtures/fake-claude-cli.mjs')
+
+// ---------------------------------------------------------------------------
+// Shared helpers (per-spec copies -- see file doc comment)
+// ---------------------------------------------------------------------------
+
+/** Copy a fixture into <binDir>/<binName> and make it executable. */
+async function installFakeCli(source: string, binName: string, binDir: string): Promise<string> {
+  await fs.mkdir(binDir, { recursive: true })
+  const target = path.join(binDir, binName)
+  await fs.copyFile(source, target)
+  await fs.chmod(target, 0o755)
+  return target
+}
+
+/** Read a fake CLI's argv-log JSONL (empty array if not yet written). */
+async function readArgvLog(logPath: string): Promise<Array<{ argv: string[] }>> {
+  const raw = await fs.readFile(logPath, 'utf8').catch(() => '')
+  if (!raw) return []
+  return raw.trim().split('\n').filter(Boolean).map((line) => JSON.parse(line) as { argv: string[] })
+}
+
+/** True when argv contains the adjacent pair `<flag> <value>` (claude --resume). */
+function hasFlagPair(argv: string[], flag: string, value: string): boolean {
+  const idx = argv.indexOf(flag)
+  return idx >= 0 && argv[idx + 1] === value
+}
+
+/** Dismiss the initial pane-type picker by choosing the first visible shell. */
+async function selectShellIfPickerShowing(page: Page): Promise<void> {
+  const picker = page.getByRole('toolbar', { name: /pane type picker/i }).last()
+  if (!(await picker.isVisible().catch(() => false))) return
+  for (const name of ['Shell', 'WSL', 'CMD', 'PowerShell', 'Bash']) {
+    const option = picker.getByRole('button', { name: new RegExp(`^${name}$`, 'i') })
+    if (await option.isVisible().catch(() => false)) {
+      await option.click({ force: true })
+      return
+    }
+  }
+}
+
+/** Poll the in-page harness until the WS transport reports 'ready'. */
+async function waitForWsReady(page: Page, timeoutMs = 60_000): Promise<void> {
+  await expect(async () => {
+    const status = await page.evaluate(
+      () => (window as any).__FRESHELL_TEST_HARNESS__?.getWsReadyState(),
+    )
+    expect(status).toBe('ready')
+  }).toPass({ timeout: timeoutMs })
+}
+
+/** Force the persistence middleware to write localStorage NOW. */
+async function flushPersistence(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    ;(window as any).__FRESHELL_TEST_HARNESS__?.dispatch({ type: 'persist/flushNow' })
+  })
+}
+
+/**
+ * index_warming is EXPECTED on cold boots (the server's single 2s deferral is
+ * far shorter than a worst-case index scan) and the warming banner's manual
+ * "Retry now" is the DESIGNED recovery path (council rule 5). Poll bodies
+ * call this so a slow index warm never wedges a settle-loop -- the retry only
+ * succeeds once the server-side index actually resolves, so this cannot mask
+ * a real failure.
+ */
+async function retryWarmingIfVisible(page: Page): Promise<void> {
+  const banner = page.getByRole('status').filter({ hasText: /Waiting for session index/i }).first()
+  if (await banner.isVisible().catch(() => false)) {
+    await banner
+      .getByRole('button', { name: /Retry now/i })
+      .click({ force: true })
+      .catch(() => {})
+  }
+}
+
+/**
+ * Idempotent home seed (setupHome re-runs on every boot/restart): the wizard
+ * bypass config with claude enabled, PLUS the claude provider ROOT
+ * (~/.claude/projects/<proj>) so the existence probe can warm -- a missing
+ * provider root is an immediate error{provider_unavailable}, not warming.
+ * Deliberately does NOT write transcripts: tests write/delete those
+ * themselves and a restart must not resurrect a deleted session file.
+ */
+const CLAUDE_PROJECT_SLUG = 'reconcile-adoption-proj'
+function seedClaudeHome(): (homeDir: string) => Promise<void> {
+  return async (homeDir: string) => {
+    const freshellDir = path.join(homeDir, '.freshell')
+    await fs.mkdir(freshellDir, { recursive: true })
+    await fs.writeFile(
+      path.join(freshellDir, 'config.json'),
+      JSON.stringify(
+        {
+          version: 1,
+          settings: { codingCli: { enabledProviders: ['claude'] } },
+        },
+        null,
+        2,
+      ),
+    )
+    await fs.mkdir(path.join(homeDir, '.claude', 'projects', CLAUDE_PROJECT_SLUG), {
+      recursive: true,
+    })
+  }
+}
+
+function claudeTranscriptPath(homeDir: string, sessionId: string): string {
+  return path.join(homeDir, '.claude', 'projects', CLAUDE_PROJECT_SLUG, `${sessionId}.jsonl`)
+}
+
+/** Minimal claude transcript the session index accepts (carries `cwd`). */
+async function writeClaudeTranscript(
+  homeDir: string,
+  sessionId: string,
+  cwd: string,
+): Promise<void> {
+  const line = JSON.stringify({
+    type: 'user',
+    message: 'hello from the reconcile adoption fixture',
+    uuid: 'msg-1',
+    cwd,
+    timestamp: '2026-07-22T10:00:00.000Z',
+  })
+  await fs.writeFile(claudeTranscriptPath(homeDir, sessionId), `${line}\n`, 'utf8')
+}
+
+/** Boot an owned RustServer, navigate, and wait for harness + WS. */
+async function bootAdoption(
+  page: Page,
+  options: {
+    env?: Record<string, string>
+    setupHome?: (homeDir: string) => Promise<void>
+  } = {},
+): Promise<{ server: RustServer; info: TestServerInfo; harness: TestHarness }> {
+  const server = new RustServer({ env: options.env, setupHome: options.setupHome })
+  const info = await server.start()
+  await page.goto(`${info.baseUrl}/?token=${info.token}&e2e=1`)
+  const harness = new TestHarness(page)
+  await harness.waitForHarness()
+  await harness.waitForConnection()
+  return { server, info, harness }
+}
+
+// --- layout tree walkers (donor: restore-contract-wall-rust.spec.ts) ---
+
+function collectLeaves(node: any): any[] {
+  if (!node) return []
+  if (node.type === 'leaf') return [node]
+  if (node.type === 'split') return (node.children ?? []).flatMap(collectLeaves)
+  return []
+}
+
+function findLeavesByMode(layout: any, mode: string): any[] {
+  return collectLeaves(layout).filter((leaf) => leaf?.content?.mode === mode)
+}
+
+/** Every terminal-pane leaf across every tab layout. */
+async function allTerminalLeaves(harness: TestHarness): Promise<any[]> {
+  const state = await harness.getState()
+  const layouts = state?.panes?.layouts ?? {}
+  const leaves: any[] = []
+  for (const layout of Object.values(layouts)) {
+    leaves.push(...collectLeaves(layout).filter((l) => l?.content?.kind === 'terminal'))
+  }
+  return leaves
+}
+
+// --- REST directory helper (donor: reconcile-handshake-rust.spec.ts) ---
+
+async function listTerminals(
+  info: TestServerInfo,
+): Promise<Array<{ terminalId: string; mode: string; status: string; sessionRef?: { provider: string; sessionId: string } }>> {
+  const res = await fetch(`${info.baseUrl}/api/terminals`, {
+    headers: { 'x-auth-token': info.token },
+  })
+  expect(res.ok).toBe(true)
+  return (await res.json()) as Array<{
+    terminalId: string
+    mode: string
+    status: string
+    sessionRef?: { provider: string; sessionId: string }
+  }>
+}
+
+// --- claude pane creation (donor: restore-contract-wall-rust.spec.ts's
+// claude terminal contract; the picker/WS path pre-allocates --session-id) ---
+
+/**
+ * Open a NEW claude pane via the picker and return its leaf plus the
+ * pre-allocated session id (the Nth distinct `--session-id` value in the
+ * fake CLI's argv log).
+ */
+async function openClaudePaneAndGetLeaf(
+  page: Page,
+  harness: TestHarness,
+  tabId: string,
+  projectDir: string,
+  argLogPath: string,
+): Promise<{ leaf: any; sessionId: string }> {
+  const beforeIds = new Set(
+    findLeavesByMode(await harness.getPaneLayout(tabId), 'claude').map((l) => l.id),
+  )
+  const sessionIdsBefore = new Set(
+    (await readArgvLog(argLogPath))
+      .filter((e) => e.argv.includes('--session-id'))
+      .map((e) => e.argv[e.argv.indexOf('--session-id') + 1]),
+  )
+  const picker = await openPanePicker(page)
+  await picker.getByRole('button', { name: /^Claude CLI$/i }).click({ force: true })
+  const dirInput = page.getByRole('combobox', { name: /Starting directory for Claude/i })
+  await expect(dirInput).toBeVisible({ timeout: 15_000 })
+  await dirInput.fill(projectDir)
+  await dirInput.press('Enter')
+
+  const leaf = await expect
+    .poll(async () => {
+      const layout = await harness.getPaneLayout(tabId)
+      const newLeaf = findLeavesByMode(layout, 'claude').find((l) => !beforeIds.has(l.id))
+      return newLeaf?.content?.terminalId ? newLeaf : null
+    }, { timeout: 20_000 })
+    .not.toBeNull()
+    .then(async () => {
+      const layout = await harness.getPaneLayout(tabId)
+      return findLeavesByMode(layout, 'claude').find((l) => !beforeIds.has(l.id))!
+    })
+
+  const sessionId: string = await expect
+    .poll(async () => {
+      const entries = await readArgvLog(argLogPath)
+      const fresh = entries
+        .filter((e) => e.argv.includes('--session-id'))
+        .map((e) => e.argv[e.argv.indexOf('--session-id') + 1]!)
+        .find((id) => id && !sessionIdsBefore.has(id))
+      return fresh ?? null
+    }, { timeout: 20_000 })
+    .not.toBeNull()
+    .then(async () => {
+      const entries = await readArgvLog(argLogPath)
+      return entries
+        .filter((e) => e.argv.includes('--session-id'))
+        .map((e) => e.argv[e.argv.indexOf('--session-id') + 1]!)
+        .find((id) => id && !sessionIdsBefore.has(id))!
+    })
+  expect(sessionId).toMatch(/^[0-9a-f-]{36}$/)
+  return { leaf, sessionId }
+}
+
+/** Look up a single leaf by pane id in a tab's current layout. */
+async function findLeafById(harness: TestHarness, tabId: string, paneId: string): Promise<any> {
+  const layout = await harness.getPaneLayout(tabId)
+  return collectLeaves(layout).find((leaf) => leaf.id === paneId) ?? null
+}
+
+// ---------------------------------------------------------------------------
+// The scenarios
+// ---------------------------------------------------------------------------
+
+test.describe('reconcile client adoption (rust server, real SPA)', () => {
+  test.setTimeout(240_000)
+
+  test('restart with mixed pane types: verdicts drive recovery, census never destroys', async ({
+    page,
+    e2eServerKind,
+  }) => {
+    expect(e2eServerKind).toBe('rust')
+    const sharedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'freshell-adopt-mixed-'))
+    const projectDir = path.join(sharedRoot, 'project')
+    await fs.mkdir(projectDir, { recursive: true })
+    const argLogPath = path.join(sharedRoot, 'claude-argv.jsonl')
+    const fakeClaudePath = await installFakeCli(
+      FAKE_CLAUDE_CLI_SOURCE,
+      'claude',
+      path.join(sharedRoot, 'bin'),
+    )
+    const { server, harness, info } = await bootAdoption(page, {
+      env: { CLAUDE_CMD: fakeClaudePath, FAKE_CLAUDE_ARGV_LOG: argLogPath },
+      setupHome: seedClaudeHome(),
+    })
+    try {
+      // 1. Boot SPA: a shell pane (the boot picker) + a fake-CLI claude pane
+      //    whose pre-allocated session gets a REAL fixture transcript in the
+      //    server home (so the post-restart verdict is a respawn, not fresh).
+      await selectShellIfPickerShowing(page)
+      const tabId = (await harness.getActiveTabId())!
+      await expect(page.locator('.xterm').first()).toBeVisible({ timeout: 30_000 })
+      const shellLeaf = collectLeaves(await harness.getPaneLayout(tabId)).find(
+        (l) => l?.content?.mode === 'shell',
+      )!
+      expect(shellLeaf).toBeTruthy()
+      const shellTerminalIdBefore: string = await expect
+        .poll(async () => (await findLeafById(harness, tabId, shellLeaf.id))?.content?.terminalId ?? null, {
+          timeout: 20_000,
+        })
+        .not.toBeNull()
+        .then(async () => (await findLeafById(harness, tabId, shellLeaf.id))!.content.terminalId)
+
+      const { leaf: claudeLeaf, sessionId } = await openClaudePaneAndGetLeaf(
+        page,
+        harness,
+        tabId,
+        projectDir,
+        argLogPath,
+      )
+      await writeClaudeTranscript(info.homeDir, sessionId, projectDir)
+      const claudeTerminalIdBefore: string = claudeLeaf.content.terminalId
+      // Client persisted the identity on the pane (fold via terminal.created).
+      await expect
+        .poll(async () => (await findLeafById(harness, tabId, claudeLeaf.id))?.content?.sessionRef?.sessionId ?? null, {
+          timeout: 20_000,
+        })
+        .toBe(sessionId)
+      await flushPersistence(page)
+
+      const leavesBefore = await allTerminalLeaves(harness)
+      const tabCountBefore = await harness.getTabCount()
+      const argvCountBeforeRestart = (await readArgvLog(argLogPath)).length
+
+      // 2. Graceful restart on the same home/port/token; the live client
+      //    reconnects and reconciles on the new ready.
+      await server.restart()
+      await waitForWsReady(page)
+
+      // 3a. Shell pane comes back LIVE (fresh per contract row 8): a new
+      //     terminalId, working terminal, no restoreError.
+      await expect
+        .poll(async () => {
+          await retryWarmingIfVisible(page)
+          const l = await findLeafById(harness, tabId, shellLeaf.id)
+          const tid = l?.content?.terminalId ?? null
+          return tid && tid !== shellTerminalIdBefore && l?.content?.status === 'running' ? tid : null
+        }, { timeout: 60_000 })
+        .not.toBeNull()
+      expect((await findLeafById(harness, tabId, shellLeaf.id))?.content?.restoreError).toBeFalsy()
+
+      // 3b. CLI pane RESUMES with the SAME sessionRef: new terminalId,
+      //     `claude --resume <sessionId>` argv in the post-restart round,
+      //     pane sessionRef unchanged.
+      await expect
+        .poll(async () => {
+          await retryWarmingIfVisible(page)
+          const l = await findLeafById(harness, tabId, claudeLeaf.id)
+          const tid = l?.content?.terminalId ?? null
+          return tid && tid !== claudeTerminalIdBefore ? tid : null
+        }, { timeout: 60_000 })
+        .not.toBeNull()
+      await expect
+        .poll(async () => {
+          const entries = await readArgvLog(argLogPath)
+          return entries
+            .slice(argvCountBeforeRestart)
+            .some((e) => hasFlagPair(e.argv, '--resume', sessionId))
+        }, { timeout: 30_000 })
+        .toBe(true)
+      const claudeAfter = (await findLeafById(harness, tabId, claudeLeaf.id))?.content
+      expect(claudeAfter?.sessionRef?.sessionId).toBe(sessionId)
+      expect(claudeAfter?.status).not.toBe('error')
+      expect(claudeAfter?.restoreError).toBeFalsy()
+
+      //     ...and the resume is visible server-side via /api/terminals: the
+      //     running claude terminal carries the SAME sessionRef (the
+      //     directory derives it from the resume args the create ran with).
+      await expect
+        .poll(async () => {
+          const terms = await listTerminals(info)
+          const running = terms.filter((t) => t.mode === 'claude' && t.status === 'running')
+          return (
+            running.length === 1
+            && running[0].sessionRef?.provider === 'claude'
+            && running[0].sessionRef?.sessionId === sessionId
+          )
+        }, { timeout: 30_000 })
+        .toBe(true)
+
+      // 3c. Pane count unchanged -- NOTHING destroyed by the census (F3
+      //     closed), no dead-session adjudication for healthy panes.
+      const leavesAfter = await allTerminalLeaves(harness)
+      expect(leavesAfter.length).toBe(leavesBefore.length)
+      expect(await harness.getTabCount()).toBe(tabCountBefore)
+      await expect(page.getByRole('dialog', { name: 'Dead sessions' })).toHaveCount(0)
+    } finally {
+      await server.stop()
+      await fs.rm(sharedRoot, { recursive: true, force: true })
+    }
+  })
+
+  test('dead sessions surface as ONE batched adjudication panel', async ({
+    page,
+    e2eServerKind,
+  }) => {
+    expect(e2eServerKind).toBe('rust')
+    const sharedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'freshell-adopt-dead-'))
+    const projectDir = path.join(sharedRoot, 'project')
+    await fs.mkdir(projectDir, { recursive: true })
+    const argLogPath = path.join(sharedRoot, 'claude-argv.jsonl')
+    const fakeClaudePath = await installFakeCli(
+      FAKE_CLAUDE_CLI_SOURCE,
+      'claude',
+      path.join(sharedRoot, 'bin'),
+    )
+    const { server, harness, info } = await bootAdoption(page, {
+      env: { CLAUDE_CMD: fakeClaudePath, FAKE_CLAUDE_ARGV_LOG: argLogPath },
+      setupHome: seedClaudeHome(),
+    })
+    try {
+      // 1. Two fake-CLI claude panes, each with an on-disk fixture transcript
+      //    (the durable pane ledger records the bindings, so 'ever observed'
+      //    survives the restart); verify both live.
+      await selectShellIfPickerShowing(page)
+      const tabId = (await harness.getActiveTabId())!
+      await expect(page.locator('.xterm').first()).toBeVisible({ timeout: 30_000 })
+      const paneA = await openClaudePaneAndGetLeaf(page, harness, tabId, projectDir, argLogPath)
+      await writeClaudeTranscript(info.homeDir, paneA.sessionId, projectDir)
+      const paneB = await openClaudePaneAndGetLeaf(page, harness, tabId, projectDir, argLogPath)
+      await writeClaudeTranscript(info.homeDir, paneB.sessionId, projectDir)
+      expect(paneB.sessionId).not.toBe(paneA.sessionId)
+      for (const pane of [paneA, paneB]) {
+        await expect
+          .poll(async () => (await findLeafById(harness, tabId, pane.leaf.id))?.content?.sessionRef?.sessionId ?? null, {
+            timeout: 20_000,
+          })
+          .toBe(pane.sessionId)
+      }
+      await expect
+        .poll(async () =>
+          (await listTerminals(info)).filter((t) => t.mode === 'claude' && t.status === 'running').length,
+        { timeout: 20_000 })
+        .toBe(2)
+      await flushPersistence(page)
+      const leavesBefore = await allTerminalLeaves(harness)
+      const tabCountBefore = await harness.getTabCount()
+
+      // 2. Stop + delete both session files + start on the SAME home/port/
+      //    token (RustServer.restart() -- the isolated HOME is never touched
+      //    in between, so the deletion below is exactly "gone while down").
+      await fs.rm(claudeTranscriptPath(info.homeDir, paneA.sessionId))
+      await fs.rm(claudeTranscriptPath(info.homeDir, paneB.sessionId))
+      await server.restart()
+      await waitForWsReady(page)
+
+      // 3. EXACTLY ONE [role=dialog] (aria-label "Dead sessions") listing
+      //    BOTH panes -- never one modal per pane, nothing auto-closed.
+      const dialog = page.getByRole('dialog', { name: 'Dead sessions' })
+      await expect(async () => {
+        await retryWarmingIfVisible(page)
+        await expect(dialog).toHaveCount(1)
+        await expect(dialog.getByRole('listitem')).toHaveCount(2)
+      }).toPass({ timeout: 90_000 })
+      // The adjudication panel is the ONLY dialog on screen.
+      await expect(page.getByRole('dialog')).toHaveCount(1)
+
+      // Click "Start fresh here" on the FIRST row -> that pane becomes a
+      // live terminal (same createRequestId -- the reducer preserves it;
+      // exactly ONE running claude PTY serves it).
+      await dialog.getByRole('listitem').first().getByRole('button', { name: 'Start fresh here' }).click()
+
+      // Exactly one of the two panes is now a live fresh terminal...
+      await expect
+        .poll(async () => {
+          const contents = await Promise.all(
+            [paneA, paneB].map(async (p) => (await findLeafById(harness, tabId, p.leaf.id))?.content),
+          )
+          const live = contents.filter(
+            (c) => c?.status === 'running' && c?.terminalId && !c?.restoreError,
+          )
+          return live.length
+        }, { timeout: 60_000 })
+        .toBe(1)
+      //    ...backed by EXACTLY ONE running claude PTY server-side (one
+      //    create for the pane's createRequestId, no duplicates).
+      await expect
+        .poll(async () =>
+          (await listTerminals(info)).filter((t) => t.mode === 'claude' && t.status === 'running').length,
+        { timeout: 30_000 })
+        .toBe(1)
+
+      // The second entry is STILL listed; nothing was auto-closed.
+      await expect(dialog.getByRole('listitem')).toHaveCount(1)
+      expect((await allTerminalLeaves(harness)).length).toBe(leavesBefore.length)
+      expect(await harness.getTabCount()).toBe(tabCountBefore)
+    } finally {
+      await server.stop()
+      await fs.rm(sharedRoot, { recursive: true, force: true })
+    }
+  })
+
+  test('double-restart mid-reconcile converges with no duplicates', async ({
+    page,
+    e2eServerKind,
+  }) => {
+    expect(e2eServerKind).toBe('rust')
+    const sharedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'freshell-adopt-dbl-'))
+    const projectDir = path.join(sharedRoot, 'project')
+    await fs.mkdir(projectDir, { recursive: true })
+    const argLogPath = path.join(sharedRoot, 'claude-argv.jsonl')
+    const fakeClaudePath = await installFakeCli(
+      FAKE_CLAUDE_CLI_SOURCE,
+      'claude',
+      path.join(sharedRoot, 'bin'),
+    )
+    const { server, harness, info } = await bootAdoption(page, {
+      env: { CLAUDE_CMD: fakeClaudePath, FAKE_CLAUDE_ARGV_LOG: argLogPath },
+      setupHome: seedClaudeHome(),
+    })
+    try {
+      // 1. Boot SPA with 2 CLI panes (fixture transcripts on disk).
+      await selectShellIfPickerShowing(page)
+      const tabId = (await harness.getActiveTabId())!
+      await expect(page.locator('.xterm').first()).toBeVisible({ timeout: 30_000 })
+      const paneA = await openClaudePaneAndGetLeaf(page, harness, tabId, projectDir, argLogPath)
+      await writeClaudeTranscript(info.homeDir, paneA.sessionId, projectDir)
+      const paneB = await openClaudePaneAndGetLeaf(page, harness, tabId, projectDir, argLogPath)
+      await writeClaudeTranscript(info.homeDir, paneB.sessionId, projectDir)
+      for (const pane of [paneA, paneB]) {
+        await expect
+          .poll(async () => (await findLeafById(harness, tabId, pane.leaf.id))?.content?.sessionRef?.sessionId ?? null, {
+            timeout: 20_000,
+          })
+          .toBe(pane.sessionId)
+      }
+      await flushPersistence(page)
+      const leavesBefore = await allTerminalLeaves(harness)
+      const tabCountBefore = await harness.getTabCount()
+
+      // 2. SIGKILL + reboot; ~300ms into the reconcile window, SIGKILL again.
+      await server.restartAbrupt()
+      await page.waitForTimeout(300)
+      await server.restartAbrupt()
+      await waitForWsReady(page)
+
+      // 3a. Within the recovery timeout every pane settles: a LIVE terminal
+      //     or an explicit labeled state (restoreError) -- never a permanent
+      //     'creating' wedge.
+      await expect
+        .poll(async () => {
+          await retryWarmingIfVisible(page)
+          const leaves = await allTerminalLeaves(harness)
+          const unsettled = leaves.filter((l) => {
+            const c = l?.content
+            const live = c?.status === 'running' && c?.terminalId
+            const labeled = !!c?.restoreError
+            return !(live || labeled)
+          })
+          return unsettled.length
+        }, { timeout: 120_000 })
+        .toBe(0)
+
+      // 3b. /api/terminals shows exactly one live PTY per pane
+      //     (createRequestId is the pane-owned create key, so pane:PTY is
+      //     1:1): every live pane's terminalId is a distinct running
+      //     terminal, and NO running terminal is unclaimed (a stray
+      //     duplicate from the interrupted first recovery round would show
+      //     up as an orphan or a shared terminalId).
+      await expect(async () => {
+        const leaves = await allTerminalLeaves(harness)
+        const liveIds = leaves
+          .map((l) => l?.content)
+          .filter((c) => c?.status === 'running' && c?.terminalId)
+          .map((c) => c.terminalId as string)
+        expect(new Set(liveIds).size).toBe(liveIds.length) // no shared PTYs
+        const running = (await listTerminals(info)).filter((t) => t.status === 'running')
+        const runningIds = new Set(running.map((t) => t.terminalId))
+        for (const id of liveIds) expect(runningIds.has(id)).toBe(true)
+        expect(running.length).toBe(liveIds.length) // no orphan duplicates
+      }).toPass({ timeout: 60_000 })
+
+      // Structural convergence: same tabs, same pane count, and any pane
+      // that settled live with an identity kept ITS OWN session.
+      expect(await harness.getTabCount()).toBe(tabCountBefore)
+      expect((await allTerminalLeaves(harness)).length).toBe(leavesBefore.length)
+      for (const pane of [paneA, paneB]) {
+        const c = (await findLeafById(harness, tabId, pane.leaf.id))?.content
+        if (c?.status === 'running' && c?.sessionRef?.sessionId) {
+          expect(c.sessionRef.sessionId).toBe(pane.sessionId)
+        }
+      }
+    } finally {
+      await server.stop()
+      await fs.rm(sharedRoot, { recursive: true, force: true })
+    }
+  })
+})
diff --git a/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts b/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
index bf2da4b55..c5f63382b 100644
--- a/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
+++ b/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
@@ -621,7 +621,7 @@ test.describe('Restore Contract Wall (P0.1)', () => {
       path.join(sharedRoot, 'bin'),
     )
 
-    const { server, harness } = await bootWall(page, {
+    const { server, harness, info } = await bootWall(page, {
       env: { CLAUDE_CMD: fakeClaudePath, FAKE_CLAUDE_ARGV_LOG: argLogPath },
       setupHome: seedWallConfig({ providers: ['claude'] }),
     })
@@ -697,6 +697,26 @@ test.describe('Restore Contract Wall (P0.1)', () => {
         })
         .toBe(preallocatedId)
 
+      // FIXTURE REALISM (reconcile adoption): real claude writes
+      // ~/.claude/projects/<proj>/<sessionId>.jsonl as soon as the session
+      // starts; the fake CLI does not. Under the adopted client the
+      // post-restart verdict is derived from DISK truth (a claimed session
+      // with no file is a loud dead_session, never an optimistic silent
+      // respawn), so mirror what real claude persists before the kill.
+      const claudeProjDir = path.join(info.homeDir, '.claude', 'projects', 'wall-claude-proj')
+      await fs.mkdir(claudeProjDir, { recursive: true })
+      await fs.writeFile(
+        path.join(claudeProjDir, `${preallocatedId}.jsonl`),
+        `${JSON.stringify({
+          type: 'user',
+          message: 'wall claude fixture transcript',
+          uuid: 'msg-1',
+          cwd: projectDir,
+          timestamp: '2026-07-21T08:00:00.000Z',
+        })}\n`,
+        'utf8',
+      )
+
       const argvCountBeforeKill = (await readArgvLog(argLogPath)).length
 
       // --- SIGKILL + revive; live client recovers on its own reconnect. ---
@@ -1870,15 +1890,11 @@ test.describe('Restore Contract Wall (P0.1)', () => {
     e2eServerKind,
   }) => {
     expect(e2eServerKind).toBe('rust')
-    // EXPECTED-FAIL WALL PIN -- P1.7 (D8, §4.3): dedupe keys on
-    // createRequestId only; two clients holding the same sessionRef carry
-    // different createRequestIds, so BOTH respawn -> two PTYs -> two JSONL
-    // writers on one session file. FLIP when sessionRef-level single-flight
-    // lands (Phase 3 multi-client spec).
-    test.fail(
-      e2eServerKind === 'rust',
-      'P1.7 (D8): two clients on one sessionRef respawn two PTYs after SIGKILL',
-    )
+    // P1.7 (D8, §4.3) LANDED -- pin flipped by the reconcile-client-adoption
+    // lane: the server now runs a per-sessionRef single-flight lease on the
+    // create path (losers get error{SESSION_RESERVED}) and reconcile verdicts
+    // attach every other client's claim to the winner, so two clients holding
+    // the same sessionRef converge to EXACTLY ONE PTY after SIGKILL.
     const CODEX_SESSION_ID = '77777777-6666-4555-8444-333333333333'
     const SESSION_TITLE = 'two-client codex session'
     const sharedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'freshell-wall-twoclient-'))
@@ -1938,9 +1954,8 @@ test.describe('Restore Contract Wall (P0.1)', () => {
         .toBeGreaterThan(0)
       // STABLE-COUNT settle (not a fixed sleep): accept only when two samples
       // >=5s apart agree, so a tail-latency straggler cannot make the count
-      // read 1 spuriously -- an unexpected PASS of this pin is a hard suite
-      // failure. Under today's bug the stable count is 2 (pin holds); when
-      // sessionRef single-flight lands it is 1 (pin flips loudly).
+      // read 1 spuriously. Under the pre-lease bug the stable count was 2;
+      // with sessionRef single-flight landed it must be exactly 1.
       await expect
         .poll(
           async () => {
@@ -2044,9 +2059,12 @@ test.describe('Restore Contract Wall (P0.1)', () => {
     e2eServerKind,
   }) => {
     expect(e2eServerKind).toBe('rust')
-    // OBSERVE-THEN-PIN -- if red, pin P1.7 (§4.3): respawn caps and keyed-
-    // create dedupe are dormant (paneReconcileV1 never sent), so a restart
-    // landing mid-recovery can double-create or dead-end panes (F9).
+    // ADOPTED REALITY (reconcile-client-adoption lane): the client advertises
+    // capabilities.paneReconcileV1 in hello and sends pane.reconcile.request
+    // after EVERY ready, so a restart landing mid-recovery is answered by a
+    // fresh verdict round on the next reconnect -- panes converge to exactly
+    // one live terminal each (asserted via /api/terminals), never a
+    // double-create or a dead-ended pane (F9).
     const CODEX_SESSION_ID = '55555555-4444-4333-8222-111111111111'
     const SESSION_TITLE = 'double-restart codex session'
     const sharedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'freshell-wall-dblrestart-'))
@@ -2058,7 +2076,7 @@ test.describe('Restore Contract Wall (P0.1)', () => {
       'codex',
       path.join(sharedRoot, 'bin'),
     )
-    const { server, harness } = await bootWall(page, {
+    const { server, harness, info } = await bootWall(page, {
       env: { CODEX_CMD: fakeCodexPath, FAKE_CODEX_ARGV_LOG: argLogPath },
       setupHome: seedCodexHome(CODEX_SESSION_ID, SESSION_TITLE, projectDir),
     })
@@ -2073,6 +2091,11 @@ test.describe('Restore Contract Wall (P0.1)', () => {
         .not.toBeNull()
       const tabCountBefore = await harness.getTabCount()
       const argvCountBeforeKill = (await readArgvLog(argLogPath)).length
+      const countReconcileRequests = async () =>
+        (await harness.getSentWsMessages()).filter(
+          (m) => (m as { type?: string })?.type === 'pane.reconcile.request',
+        ).length
+      const reconcileRequestsBeforeKill = await countReconcileRequests()
 
       // First SIGKILL; wait until recovery is IN FLIGHT (a new spawn hit the
       // argv log), then SIGKILL again mid-recovery.
@@ -2083,6 +2106,13 @@ test.describe('Restore Contract Wall (P0.1)', () => {
       await server.restartAbrupt()
       await waitForWsReady(page)
 
+      // ADOPTED CONTRACT: the client re-sends pane.reconcile.request on the
+      // post-restart ready (the request is per-connection, so the reconnect
+      // after the final SIGKILL must have produced at least one more).
+      await expect
+        .poll(countReconcileRequests, { timeout: 30_000 })
+        .toBeGreaterThan(reconcileRequestsBeforeKill)
+
       // CONTRACT: the pane settles resumed on the same session -- exactly one
       // pane, same tab count, not status:error, resumed argv in the final
       // recovery round.
@@ -2103,6 +2133,22 @@ test.describe('Restore Contract Wall (P0.1)', () => {
         ).length
       }
       expect(codexLeaves).toBe(1)
+      // CONVERGENCE via the REST directory: the persisted codex pane ends
+      // with EXACTLY ONE live PTY -- the one the pane is attached to. A
+      // stray duplicate from the interrupted first recovery round would
+      // show up here as a second running codex terminal.
+      const paneTerminalId = (await harness.getPaneLayout(tabId))?.content?.terminalId
+      await expect
+        .poll(async () => {
+          const res = await fetch(`${info.baseUrl}/api/terminals`, {
+            headers: restApiHeaders(info),
+          })
+          if (!res.ok) return null
+          const terms = (await res.json()) as Array<{ terminalId: string; mode: string; status: string }>
+          const runningCodex = terms.filter((t) => t.mode === 'codex' && t.status === 'running')
+          return runningCodex.length === 1 && runningCodex[0].terminalId === paneTerminalId
+        }, { timeout: 30_000 })
+        .toBe(true)
     } finally {
       await server.stop()
       await fs.rm(sharedRoot, { recursive: true, force: true })

From 1440d13f03d03b0136edfe63606a3b311c0faac8 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 08:00:37 -0700
Subject: [PATCH 72/87] test(e2e): per-provider settings survive restart +
 codex crash memory-loss banner (P1.13)

---
 test/e2e-browser/fixtures/fake-opencode.cjs   |   4 +
 test/e2e-browser/playwright.config.ts         |   7 +
 .../freshagent-settings-resume-rust.spec.ts   | 651 ++++++++++++++++++
 .../codex-app-server/fake-app-server.mjs      |  16 +
 4 files changed, 678 insertions(+)
 create mode 100644 test/e2e-browser/specs/freshagent-settings-resume-rust.spec.ts

diff --git a/test/e2e-browser/fixtures/fake-opencode.cjs b/test/e2e-browser/fixtures/fake-opencode.cjs
index 491f620ea..85f679b8a 100644
--- a/test/e2e-browser/fixtures/fake-opencode.cjs
+++ b/test/e2e-browser/fixtures/fake-opencode.cjs
@@ -796,6 +796,10 @@ const server = http.createServer(async (req, res) => {
         routeDirectory: directory,
         directory: session.directory,
         prompt: appended.promptText,
+        // Parsed prompt-body settings (V4/A5): on the wire (build_prompt_body,
+        // crates/freshell-opencode/src/serve.rs) `model` is an OBJECT
+        // `{providerID, modelID}` and effort is the string field `variant`.
+        body: { model: body.model, variant: body.variant },
       })
       sendJson(res, 200, { ok: true })
       setTimeout(() => {
diff --git a/test/e2e-browser/playwright.config.ts b/test/e2e-browser/playwright.config.ts
index c4151f30e..b851231fe 100644
--- a/test/e2e-browser/playwright.config.ts
+++ b/test/e2e-browser/playwright.config.ts
@@ -127,6 +127,9 @@ const RUST_ONLY_SPECS = [
   // ledger-join coherence, A2xA3 dual claude identity stores). Imports
   // RustServer directly for restartAbrupt().
   /wavea-interactions-rust\.spec\.ts$/,
+  // P1.13 (Lane B4 Task 14): per-provider settings survive restart + codex
+  // crash memory-loss banner. Imports RustServer directly for restartAbrupt().
+  /freshagent-settings-resume-rust\.spec\.ts$/,
 ]
 
 export default defineConfig({
@@ -284,6 +287,10 @@ export default defineConfig({
         // ledger-join coherence, A2xA3 dual claude identity stores). Imports
         // RustServer directly for restartAbrupt().
         /wavea-interactions-rust\.spec\.ts$/,
+        // P1.13 (Lane B4 Task 14): per-provider settings survive restart +
+        // codex crash memory-loss banner. Imports RustServer directly for
+        // restartAbrupt().
+        /freshagent-settings-resume-rust\.spec\.ts$/,
       ],
     },
     // CONTINUITY SMOKE (pre-deploy gate): REAL freshell-server binary + REAL
diff --git a/test/e2e-browser/specs/freshagent-settings-resume-rust.spec.ts b/test/e2e-browser/specs/freshagent-settings-resume-rust.spec.ts
new file mode 100644
index 000000000..d8809bce6
--- /dev/null
+++ b/test/e2e-browser/specs/freshagent-settings-resume-rust.spec.ts
@@ -0,0 +1,651 @@
+// FRESHAGENT SETTINGS RESUME (P1.13, Lane B4 Task 14) -- end-to-end proof that
+// per-provider fresh-agent settings survive a server restart, plus the codex
+// crash-respawn memory-loss degradation banner:
+//   1. codex: a create-shaped resume after restartAbrupt (the exact wire shape
+//      the frozen client sends after page.reload -- V2/A4) carries the RECORDED
+//      model/sandbox on `thread/resume`, filled from the pane ledger (Task 5(d)),
+//      NOT from the resume message (which deliberately omits them).
+//   2. opencode: REST-seeded session (V3: the REST surface is opencode-only);
+//      after restart, a create-shaped resume + a settings-less send carries the
+//      recorded model/effort on the wire (`{providerID,modelID}` object + the
+//      `variant` string field -- build_prompt_body, serve.rs).
+//   3. claude: the ATTACH resume path (`resume_for_attach`, Task 10) reapplies
+//      the recorded model/permissionMode from the ledger on the sidecar resume
+//      create. Attach is the no-reload reconnect topology (V2/A4).
+//   4. codex crash respawn: THREAD_MEMORY_LOST must be USER-VISIBLE (Task 6) --
+//      a role="alert" banner in the real browser UI, asserted with NO reload
+//      anywhere (the banner is in-memory Redux state and does not survive
+//      reload -- V1 N3).
+//
+// Rust-only: registered in RUST_ONLY_SPECS + rust-chromium testMatch
+// (restartAbrupt exists only on RustServer). Tests 1-3 drive the server
+// directly (REST + raw WS, no browser page); test 4 is a browser test.
+//
+// Donors: boot/env/restart plumbing from freshclaude-restart-parity-rust.spec.ts
+// (:212-310); the raw node-side WS client from
+// codex-status-completeness-rust.spec.ts (WsCapture); the raw-create message
+// sequence from crates/freshell-ws/tests/freshagent_claude_kill_interrupt.rs
+// (:295); the raw-attach frame from freshagent_claude_attach.rs; the REST
+// opencode seeding from agent-continuity-matrix.spec.ts; the Freshcodex UI
+// pane-creation flow from agent-checkpoint-rewind.spec.ts (:207). Helpers are
+// copied, not imported, per this suite's per-spec-ownership convention.
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import WebSocket from 'ws'
+import { test, expect } from '../helpers/fixtures.js'
+import { RustServer } from '../helpers/rust-server.js'
+import { TestHarness } from '../helpers/test-harness.js'
+import { openPanePicker } from '../helpers/pane-picker.js'
+import type { Page } from '@playwright/test'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const CODEX_FIXTURE = path.resolve(
+  __dirname,
+  '../../fixtures/coding-cli/codex-app-server/fake-app-server.mjs',
+)
+const CLAUDE_FIXTURE = path.resolve(__dirname, '../fixtures/fake-claude-sidecar.mjs')
+const OPENCODE_FIXTURE = path.resolve(__dirname, '../fixtures/fake-opencode.cjs')
+
+// ---------------------------------------------------------------------------
+// Copied helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Raw node-side WS client with a real hello handshake and a frame buffer
+ * (donor: codex-status-completeness-rust.spec.ts's WsCapture).
+ */
+class WsCapture {
+  private ws: WebSocket
+  readonly frames: any[] = []
+  private opened: Promise<void>
+
+  constructor(baseUrl: string, token: string) {
+    const wsUrl = `${baseUrl.replace(/^http/, 'ws')}/ws`
+    this.ws = new WebSocket(wsUrl)
+    this.opened = new Promise((resolve, reject) => {
+      this.ws.on('open', () => {
+        this.ws.send(JSON.stringify({ type: 'hello', protocolVersion: 7, token }))
+        resolve()
+      })
+      this.ws.on('error', reject)
+    })
+    this.ws.on('message', (data) => {
+      try {
+        this.frames.push(JSON.parse(String(data)))
+      } catch {
+        // non-JSON frames are not part of this protocol; ignore
+      }
+    })
+  }
+
+  async ready(): Promise<void> {
+    await this.opened
+    await this.waitFor((f) => f.type === 'ready', 10_000, 'ready')
+  }
+
+  async waitFor(pred: (frame: any) => boolean, timeoutMs: number, label: string): Promise<any> {
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+      const hit = this.frames.find(pred)
+      if (hit) return hit
+      await new Promise((r) => setTimeout(r, 100))
+    }
+    throw new Error(`WsCapture: timed out waiting for ${label}`)
+  }
+
+  send(frame: unknown): void {
+    this.ws.send(JSON.stringify(frame))
+  }
+
+  close(): void {
+    try {
+      this.ws.close()
+    } catch {
+      // already closed
+    }
+  }
+}
+
+/**
+ * `PATCH /api/settings` -- flip the shared `settings.freshAgent.enabled` gate
+ * the fresh-agent WS dispatch requires (`crates/freshell-ws/src/terminal.rs`).
+ * Endpoint shape verified against settings-live-reload.spec.ts (:38-45).
+ */
+async function enableFreshAgent(baseUrl: string, token: string): Promise<void> {
+  const res = await fetch(`${baseUrl}/api/settings`, {
+    method: 'PATCH',
+    headers: { 'content-type': 'application/json', 'x-auth-token': token },
+    body: JSON.stringify({ freshAgent: { enabled: true } }),
+  })
+  if (!res.ok) {
+    throw new Error(`PATCH /api/settings failed: ${res.status} ${await res.text()}`)
+  }
+}
+
+/** Parse a JSONL file, tolerating absence (returns []). */
+function readJsonl(filePath: string): any[] {
+  if (!fs.existsSync(filePath)) return []
+  return fs
+    .readFileSync(filePath, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => JSON.parse(l))
+}
+
+/** Dismiss the initial pane-type picker by choosing the first visible shell.
+ * (donor: restore-contract-wall-rust.spec.ts :95-105) */
+async function selectShellIfPickerShowing(page: Page): Promise<void> {
+  const picker = page.getByRole('toolbar', { name: /pane type picker/i }).last()
+  if (!(await picker.isVisible().catch(() => false))) return
+  for (const name of ['Shell', 'WSL', 'CMD', 'PowerShell', 'Bash']) {
+    const option = picker.getByRole('button', { name: new RegExp(`^${name}$`, 'i') })
+    if (await option.isVisible().catch(() => false)) {
+      await option.click({ force: true })
+      return
+    }
+  }
+}
+
+/** Idempotent .freshell/config.json seed (setupHome re-runs on every boot).
+ * (donor: freshclaude-restart-parity-rust.spec.ts :76-98) */
+function seedWallConfig(input: {
+  providers: string[]
+  freshAgent?: boolean
+}): (homeDir: string) => Promise<void> {
+  return async (homeDir: string) => {
+    const freshellDir = path.join(homeDir, '.freshell')
+    await fsp.mkdir(freshellDir, { recursive: true })
+    await fsp.writeFile(
+      path.join(freshellDir, 'config.json'),
+      JSON.stringify(
+        {
+          version: 1,
+          settings: {
+            codingCli: { enabledProviders: input.providers },
+            ...(input.freshAgent ? { freshAgent: { enabled: true } } : {}),
+          },
+        },
+        null,
+        2,
+      ),
+    )
+  }
+}
+
+/** Boot an owned RustServer, navigate, and wait for harness + WS.
+ * (donor: freshclaude-restart-parity-rust.spec.ts :102-116) */
+async function bootWall(
+  page: Page,
+  options: {
+    env?: Record<string, string>
+    setupHome?: (homeDir: string) => Promise<void>
+  } = {},
+): Promise<{ server: RustServer; info: Awaited<ReturnType<RustServer['start']>>; harness: TestHarness }> {
+  const server = new RustServer({ env: options.env, setupHome: options.setupHome })
+  const info = await server.start()
+  await page.goto(`${info.baseUrl}/?token=${info.token}&e2e=1`)
+  const harness = new TestHarness(page)
+  await harness.waitForHarness()
+  await harness.waitForConnection()
+  return { server, info, harness }
+}
+
+/** Find the (first) fresh-agent leaf within a possibly-split pane layout tree.
+ * (donor: agent-checkpoint-rewind.spec.ts :109-119) */
+function findFreshAgentLeaf(node: any): any {
+  if (!node) return null
+  if (node.type === 'leaf' && node.content?.kind === 'fresh-agent') return node
+  if (node.type === 'split') {
+    for (const child of node.children ?? []) {
+      const found = findFreshAgentLeaf(child)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+/** Create a Freshcodex pane through the real pane-picker UI.
+ * (donor: agent-checkpoint-rewind.spec.ts :188-214, availableClis preamble from
+ * freshclaude-restart-parity-rust.spec.ts :177-205) */
+async function createFreshcodexPane(page: Page, cwd: string): Promise<void> {
+  // setAvailableClis is client-only AND gets overwritten by the app bootstrap +
+  // /api/platform fetch; callers reach this only after waitForConnection().
+  await page.evaluate(() => {
+    ;(window as any).__FRESHELL_TEST_HARNESS__?.dispatch({
+      type: 'connection/setAvailableClis',
+      payload: { claude: false, codex: true },
+    })
+  })
+  const picker = await openPanePicker(page)
+  await picker.getByRole('button', { name: /^Freshcodex$/i }).click({ force: true })
+  const directoryInput = page.getByRole('combobox', { name: 'Starting directory for Freshcodex' })
+  await expect(directoryInput).toBeVisible({ timeout: 15_000 })
+  await directoryInput.fill(cwd)
+  await directoryInput.press('Enter')
+  await expect(page.locator('[data-context="fresh-agent"]').last()).toBeVisible({
+    timeout: 15_000,
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+test.describe('fresh-agent settings survive restart (rust)', () => {
+  test('codex: create-shaped resume after restart carries the recorded model', async ({ e2eServerKind }) => {
+    test.setTimeout(180_000)
+    expect(e2eServerKind).toBe('rust')
+    const sharedRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'fa-settings-codex-'))
+    const opLogPath = path.join(sharedRoot, 'codex-ops.jsonl')
+    const projectDir = path.join(sharedRoot, 'proj')
+    await fsp.mkdir(projectDir, { recursive: true })
+    const server = new RustServer({
+      env: {
+        // Whitespace-split by spawn_sidecar (codex.rs): interpreter + script.
+        CODEX_CMD: `${process.execPath} ${CODEX_FIXTURE}`,
+        // STATIC per server boot (V4/A6): resume succeeds by default.
+        FAKE_CODEX_APP_SERVER_BEHAVIOR: JSON.stringify({
+          appendThreadOperationLogPath: opLogPath,
+        }),
+      },
+    })
+    let ws: WsCapture | null = null
+    try {
+      const info = await server.start()
+      await enableFreshAgent(info.baseUrl, info.token)
+      ws = new WsCapture(info.baseUrl, info.token)
+      await ws.ready()
+
+      // Raw create WITH settings -- the values the ledger must record.
+      ws.send({
+        type: 'freshAgent.create',
+        requestId: 'req-codex-settings-1',
+        sessionType: 'freshcodex',
+        provider: 'codex',
+        model: 'gpt-5.3-codex-spark',
+        sandbox: 'workspace-write',
+        cwd: projectDir,
+      })
+      const created = await ws.waitFor(
+        (f) => f.type === 'freshAgent.created' && f.requestId === 'req-codex-settings-1',
+        30_000,
+        'freshAgent.created (codex create)',
+      )
+      const threadId = created.sessionId as string
+      expect(threadId).toBeTruthy()
+
+      // One turn. `freshAgent.send.accepted` is broadcast after `turn/start`
+      // resolves (codex.rs handle_send), and the fake answers turn/start with a
+      // completed turn -- so this IS the turn's completion edge on this fixture.
+      ws.send({
+        type: 'freshAgent.send',
+        provider: 'codex',
+        sessionId: threadId,
+        sessionType: 'freshcodex',
+        text: 'settings-resume first turn',
+      })
+      await ws.waitFor(
+        (f) => f.type === 'freshAgent.send.accepted' && f.sessionId === threadId,
+        30_000,
+        'freshAgent.send.accepted (codex first turn)',
+      )
+      ws.close()
+      ws = null
+
+      // ── SIGKILL + reboot on the same home/port/token.
+      await server.restartAbrupt()
+      await enableFreshAgent(server.info.baseUrl, server.info.token)
+      ws = new WsCapture(server.info.baseUrl, server.info.token)
+      await ws.ready()
+
+      // Create-shaped resume with NO model/sandbox -- the values must come from
+      // the LEDGER (R1 fills gaps, Task 5(d)), not from this message.
+      ws.send({
+        type: 'freshAgent.create',
+        requestId: 'req-codex-settings-resume',
+        sessionType: 'freshcodex',
+        provider: 'codex',
+        resumeSessionId: threadId,
+      })
+      await ws.waitFor(
+        (f) => f.type === 'freshAgent.created' && f.requestId === 'req-codex-settings-resume',
+        30_000,
+        'freshAgent.created (codex resume)',
+      )
+
+      const ops = fs.readFileSync(opLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
+      const resume = ops.find((o) => o.method === 'thread/resume')
+      expect(resume, 'restart must resume the durable thread').toBeTruthy()
+      expect(resume.params.model, 'resume must carry the recorded model, not null').toBe('gpt-5.3-codex-spark')
+      expect(resume.params.sandbox, 'resume must carry the recorded sandbox').toBe('workspace-write')
+    } finally {
+      ws?.close()
+      await server.stop().catch(() => {})
+      await fsp.rm(sharedRoot, { recursive: true, force: true }).catch(() => {})
+    }
+  })
+
+  test('opencode: create-shaped resume after restart -> next send carries the recorded model/effort', async ({ e2eServerKind }) => {
+    test.setTimeout(180_000)
+    expect(e2eServerKind).toBe('rust')
+    const sharedRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'fa-settings-opencode-'))
+    const binDir = path.join(sharedRoot, 'bin')
+    const auditLogPath = path.join(sharedRoot, 'opencode-audit.jsonl')
+    const projectDir = path.join(sharedRoot, 'proj')
+    await fsp.mkdir(projectDir, { recursive: true })
+    // Install the fake as an executable named `opencode` (donor:
+    // agent-continuity-matrix.spec.ts installFakeOpencode) and point
+    // OPENCODE_CMD at it (serve.rs ServeConfig).
+    await fsp.mkdir(binDir, { recursive: true })
+    const fakeOpencode = path.join(binDir, 'opencode')
+    await fsp.copyFile(OPENCODE_FIXTURE, fakeOpencode)
+    await fsp.chmod(fakeOpencode, 0o755)
+    const server = new RustServer({
+      env: {
+        PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ''}`,
+        OPENCODE_CMD: fakeOpencode,
+        FAKE_OPENCODE_AUDIT_LOG: auditLogPath,
+      },
+      // Re-seeded on every boot; keeps the freshAgent gate + provider enabled
+      // across the restart (donor: agent-continuity-matrix.spec.ts).
+      setupHome: seedWallConfig({ providers: ['opencode'], freshAgent: true }),
+    })
+    let ws: WsCapture | null = null
+    try {
+      const info = await server.start()
+
+      // REST seeding (V3: this surface is opencode-only). The model id MUST be
+      // `provider/model`-shaped -- split_opencode_model returns None for
+      // slashless ids and build_prompt_body then omits `model` entirely.
+      const tabRes = await fetch(`${info.baseUrl}/api/tabs`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-auth-token': info.token },
+        body: JSON.stringify({
+          agent: 'opencode',
+          model: 'fakeprov/big-model',
+          effort: 'high',
+          cwd: projectDir,
+        }),
+      })
+      expect(tabRes.ok, `POST /api/tabs must succeed: ${tabRes.status}`).toBe(true)
+      const tabBody = (await tabRes.json()) as any
+      const paneId = (tabBody?.data ?? tabBody)?.paneId as string
+      expect(paneId, 'POST /api/tabs must return a paneId').toBeTruthy()
+
+      // One send-keys materializes the ses_* session (Task 7's REST-site
+      // ledger write records the settings).
+      const sendRes = await fetch(`${info.baseUrl}/api/panes/${encodeURIComponent(paneId)}/send-keys`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-auth-token': info.token },
+        body: JSON.stringify({ data: 'settings-resume first opencode turn' }),
+      })
+      const sendResText = await sendRes.text()
+      expect(sendRes.ok, `send-keys must succeed: ${sendRes.status} ${sendResText}`).toBe(true)
+
+      // Read the durable ses_* id from the audit log's prompt_async entry
+      // (V4/A5: entries are keyed by `event`, never `path`).
+      await expect
+        .poll(
+          () => readJsonl(auditLogPath).find((e) => e.event === 'prompt_async')?.sessionId ?? null,
+          { timeout: 30_000 },
+        )
+        .toMatch(/^ses_/)
+      const sesId = readJsonl(auditLogPath).find((e) => e.event === 'prompt_async')!.sessionId as string
+      const promptsBeforeRestart = readJsonl(auditLogPath).filter((e) => e.event === 'prompt_async').length
+
+      // ── The REST panes map is in-memory and gone after this; post-restart
+      // driving is via raw WS.
+      await server.restartAbrupt()
+      await enableFreshAgent(server.info.baseUrl, server.info.token)
+      ws = new WsCapture(server.info.baseUrl, server.info.token)
+      await ws.ready()
+
+      // Create-shaped resume with NO model/effort (the P1.13 pin, Task 8(b)).
+      ws.send({
+        type: 'freshAgent.create',
+        requestId: 'req-opencode-settings-resume',
+        sessionType: 'freshopencode',
+        provider: 'opencode',
+        resumeSessionId: sesId,
+      })
+      const created = await ws.waitFor(
+        (f) => f.type === 'freshAgent.created' && f.requestId === 'req-opencode-settings-resume',
+        30_000,
+        'freshAgent.created (opencode resume)',
+      )
+      expect(created.sessionId, 'resume must answer the durable ses_* id, not a placeholder').toBe(sesId)
+
+      // One send with NO per-send settings.
+      ws.send({
+        type: 'freshAgent.send',
+        provider: 'opencode',
+        sessionId: sesId,
+        sessionType: 'freshopencode',
+        text: 'settings-resume post-restart turn',
+      })
+      await expect
+        .poll(
+          () => readJsonl(auditLogPath).filter((e) => e.event === 'prompt_async').length,
+          { timeout: 30_000 },
+        )
+        .toBeGreaterThan(promptsBeforeRestart)
+
+      const audit = fs.readFileSync(auditLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
+      const prompts = audit.filter((e) => e.event === 'prompt_async') // V4: entries have `event`, never `path`
+      const afterRestart = prompts[prompts.length - 1]
+      // On the wire (build_prompt_body, serve.rs:939-955): model is the OBJECT
+      // { providerID: 'fakeprov', modelID: 'big-model' }, effort is the string
+      // field `variant` -- never `effort`/`reasoningEffort`.
+      expect(afterRestart.body?.model, 'post-restart send must carry the recorded model').toEqual({ providerID: 'fakeprov', modelID: 'big-model' })
+      expect(afterRestart.body?.variant, 'post-restart send must carry the recorded effort (wire field: variant)').toBe('high')
+    } finally {
+      ws?.close()
+      await server.stop().catch(() => {})
+      await fsp.rm(sharedRoot, { recursive: true, force: true }).catch(() => {})
+    }
+  })
+
+  test('claude: attach resume request carries model/permissionMode', async ({ e2eServerKind }) => {
+    test.setTimeout(180_000)
+    expect(e2eServerKind).toBe('rust')
+    const sharedRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'fa-settings-claude-'))
+    const sidecarLogPath = path.join(sharedRoot, 'sidecar-requests.jsonl')
+    const projectDir = path.join(sharedRoot, 'proj')
+    await fsp.mkdir(projectDir, { recursive: true })
+    const server = new RustServer({
+      env: {
+        FRESHELL_CLAUDE_SIDECAR: CLAUDE_FIXTURE,
+        FAKE_CLAUDE_SIDECAR_LOG: sidecarLogPath,
+      },
+    })
+    let ws: WsCapture | null = null
+    try {
+      const info = await server.start()
+      await enableFreshAgent(info.baseUrl, info.token)
+      ws = new WsCapture(info.baseUrl, info.token)
+      await ws.ready()
+
+      // Raw create WITH settings; the server forwards model/permissionMode to
+      // the sidecar verbatim and records the binding row at sdk.session.init.
+      ws.send({
+        type: 'freshAgent.create',
+        requestId: 'req-claude-settings-1',
+        sessionType: 'freshclaude',
+        provider: 'claude',
+        model: 'opus-x',
+        permissionMode: 'plan',
+        cwd: projectDir,
+      })
+      const created = await ws.waitFor(
+        (f) => f.type === 'freshAgent.created' && f.requestId === 'req-claude-settings-1',
+        30_000,
+        'freshAgent.created (claude create)',
+      )
+      const bridgeSessionId = created.sessionId as string
+      // sdk.session.init -> freshAgent.session.init carries the durable UUID.
+      const init = await ws.waitFor(
+        (f) =>
+          f.type === 'freshAgent.event' &&
+          f.sessionId === bridgeSessionId &&
+          f.event?.type === 'freshAgent.session.init',
+        30_000,
+        'freshAgent.session.init',
+      )
+      const durable = init.event.cliSessionId as string
+      expect(durable).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/)
+
+      // One turn (fixture completes it with sdk.turn.complete).
+      ws.send({
+        type: 'freshAgent.send',
+        provider: 'claude',
+        sessionId: bridgeSessionId,
+        sessionType: 'freshclaude',
+        text: 'settings-resume first claude turn',
+      })
+      await ws.waitFor(
+        (f) =>
+          f.type === 'freshAgent.event' &&
+          f.sessionId === bridgeSessionId &&
+          f.event?.type === 'freshAgent.turn.complete',
+        30_000,
+        'freshAgent.turn.complete (claude first turn)',
+      )
+      ws.close()
+      ws = null
+
+      await server.restartAbrupt()
+      await enableFreshAgent(server.info.baseUrl, server.info.token)
+      ws = new WsCapture(server.info.baseUrl, server.info.token)
+      await ws.ready()
+
+      // Attach with the durable UUID. `provider` is a REQUIRED attach field
+      // (client_messages.rs FreshAgentAttach); the durable id must ride
+      // resumeSessionId/sessionRef -- `attach_durable_id` (claude.rs:858-864)
+      // reads ONLY those two fields, exactly what the frozen client writes
+      // (FreshAgentView.tsx:303-313).
+      ws.send({
+        type: 'freshAgent.attach',
+        provider: 'claude',
+        sessionId: durable,
+        sessionType: 'freshclaude',
+        resumeSessionId: durable,
+        sessionRef: { provider: 'claude', sessionId: durable },
+      })
+
+      // The resume-on-attach spawns a fresh sidecar whose create carries
+      // resumeSessionId + the LEDGER-recorded settings (Task 10).
+      await expect
+        .poll(
+          () =>
+            readJsonl(sidecarLogPath).some((m) => m.msg && m.msg.resumeSessionId === durable),
+          { timeout: 30_000 },
+        )
+        .toBe(true)
+
+      const msgs = fs.readFileSync(sidecarLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
+      const resumeCreate = msgs.filter((m) => m.msg && m.msg.resumeSessionId).pop()
+      expect(resumeCreate, 'restart must issue a resume create').toBeTruthy()
+      expect(resumeCreate.msg.model, 'resume must carry the recorded model, not null').toBe('opus-x')
+      expect(resumeCreate.msg.permissionMode, 'resume must carry the recorded permissionMode').toBe('plan')
+    } finally {
+      ws?.close()
+      await server.stop().catch(() => {})
+      await fsp.rm(sharedRoot, { recursive: true, force: true }).catch(() => {})
+    }
+  })
+
+  test('codex: crash respawn shows a visible memory-loss notice', async ({ page, e2eServerKind }) => {
+    test.setTimeout(180_000)
+    expect(e2eServerKind).toBe('rust')
+    const sharedRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'fa-crash-banner-'))
+    const threadOpsPath = path.join(sharedRoot, 'thread-ops.jsonl')
+    const projectDir = path.join(sharedRoot, 'proj')
+    await fsp.mkdir(projectDir, { recursive: true })
+    // ONE static behavior for the whole test (V4/A6). The static thread/resume
+    // error is fine: the first spawn goes through thread/start (a fresh session
+    // never resumes) and the only resume attempt is the post-crash one, which
+    // must fail so the respawn mints a new thread.
+    const behavior = {
+      overrides: { 'thread/resume': { error: { code: -32602, message: 'thread not found' } } },
+      crashOnPromptMarker: 'CRASH_NOW',
+      crashOnPromptMarkerOnceMarkerPath: path.join(sharedRoot, 'crash.once'),
+      appendThreadOperationLogPath: threadOpsPath,
+    }
+    const { server, harness } = await bootWall(page, {
+      env: {
+        CODEX_CMD: `${process.execPath} ${CODEX_FIXTURE}`,
+        FAKE_CODEX_APP_SERVER_BEHAVIOR: JSON.stringify(behavior),
+      },
+      setupHome: seedWallConfig({ providers: ['codex'], freshAgent: true }),
+    })
+    let ws: WsCapture | null = null
+    try {
+      await selectShellIfPickerShowing(page)
+      const tabId = (await harness.getActiveTabId())!
+      // Wait for the boot pane to become a REAL terminal before opening the
+      // pane picker (donor: freshclaude-restart-parity-rust.spec.ts :229-232).
+      await expect(page.locator('.xterm').first()).toBeVisible({ timeout: 30_000 })
+      await createFreshcodexPane(page, projectDir)
+
+      const paneRoot = page.locator('[data-context="fresh-agent"]').last()
+      await expect
+        .poll(async () => findFreshAgentLeaf(await harness.getPaneLayout(tabId))?.content?.status, {
+          timeout: 30_000,
+        })
+        .toBe('idle')
+      const sessionId: string = findFreshAgentLeaf(await harness.getPaneLayout(tabId))?.content?.sessionId
+      expect(sessionId).toBeTruthy()
+
+      // First send via the pane composer: the sidecar hard-exits(1) mid-turn
+      // (once, cross-process marker), simulating a codex crash.
+      const composer = paneRoot.getByRole('textbox', { name: 'Chat message input' })
+      await composer.fill('CRASH_NOW')
+      await paneRoot.getByRole('button', { name: 'Send' }).click()
+
+      // The exit watcher broadcasts freshAgent.status 'exited' (the self-heal
+      // edge); the frozen client folds it into the freshAgent slice (NOT the
+      // pane-layout content.status) and shows the session-ended card while
+      // DISABLING the composer (FreshAgentView's sessionEnded gate,
+      // :1699/:1714). So the recovery-triggering second send is driven over a
+      // raw WS client for the SAME session -- crash recovery is send-triggered
+      // server-side regardless of which client sends, and the BANNER assertion
+      // below still runs against the real browser UI, which receives the
+      // broadcast frames. NO page.reload() anywhere: the banner is in-memory
+      // Redux state (V1 N3).
+      await expect(
+        paneRoot.getByText('This session has ended'),
+        'the sidecar crash must surface the exited state client-side first',
+      ).toBeVisible({ timeout: 30_000 })
+
+      ws = new WsCapture(server.info.baseUrl, server.info.token)
+      await ws.ready()
+      ws.send({
+        type: 'freshAgent.send',
+        provider: 'codex',
+        sessionId,
+        sessionType: 'freshcodex',
+        text: 'post-crash recovery message',
+      })
+
+      // Task 6's contract: memory loss must be user-visible, not server-log-only.
+      const banner = page.getByRole('alert').filter({ hasText: 'no longer has memory' })
+      await expect(banner, 'memory loss must be user-visible, not just a server warn').toBeVisible({ timeout: 15000 })
+
+      // "New thread minted" = TWO thread/start entries in the op log. The fake
+      // reuses the same thread id (threadStartThreadId default) and errored
+      // thread/resume ops are NOT logged -- do NOT assert id inequality or a
+      // logged resume (V4/A6).
+      const ops = fs.readFileSync(threadOpsPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l))
+      expect(ops.filter((o) => o.method === 'thread/start').length, 'respawn must mint a second thread').toBe(2)
+    } finally {
+      ws?.close()
+      await server.stop().catch(() => {})
+      await fsp.rm(sharedRoot, { recursive: true, force: true }).catch(() => {})
+    }
+  })
+})
diff --git a/test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs b/test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs
index 77b54aca1..adc6fe198 100644
--- a/test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs
+++ b/test/fixtures/coding-cli/codex-app-server/fake-app-server.mjs
@@ -476,6 +476,22 @@ wss.on('connection', (socket) => {
       return
     }
 
+    // behavior.crashOnPromptMarker + behavior.crashOnPromptMarkerOnceMarkerPath:
+    // if the inbound turn input contains the marker AND this process wins the
+    // cross-process once-claim (claimCrossProcessOnce's 'wx' marker file),
+    // hard-exit(1) BEFORE responding to simulate a mid-turn sidecar crash.
+    // The respawned process finds the marker file on disk and proceeds
+    // normally. Cross-process (unlike exitProcessAfterMethodsOnce's
+    // per-process "once" set, which would make the respawn exit again).
+    if (
+      method === 'turn/start' &&
+      behavior.crashOnPromptMarker &&
+      JSON.stringify(message.params?.input ?? '').includes(behavior.crashOnPromptMarker) &&
+      claimCrossProcessOnce(behavior.crashOnPromptMarkerOnceMarkerPath, 'crashOnPromptMarker')
+    ) {
+      process.exit(1)
+    }
+
     const override = behavior.overrides?.[method]
     const delayMs = Number(behavior.delayMethodsMs?.[method] || 0)
     const floodStdoutBytes = Number(behavior.floodStdoutBeforeMethodsBytes?.[method] || 0)

From db236ec60f6f6e3670878a84d1d5658eb4807934 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 08:21:17 -0700
Subject: [PATCH 73/87] test(wall): flip/narrow P1.13 freshopencode settings
 pin - fresh-agent resume record live

---
 .../specs/restore-contract-wall-rust.spec.ts  | 38 +++++++++++--------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts b/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
index bf2da4b55..5400d4840 100644
--- a/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
+++ b/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
@@ -1003,21 +1003,25 @@ test.describe('Restore Contract Wall (P0.1)', () => {
     e2eServerKind,
   }) => {
     expect(e2eServerKind).toBe('rust')
-    // PINNED (observed failure mode, run of 2026-07-24): after
-    // SIGKILL+restart+RELOAD the rehydrated pane does NOT carry the durable
-    // ses_* identity -- leafDurableIdentity returns a freshly minted
-    // `freshopencode-<requestId>` placeholder (the lazy-create shape,
-    // server/fresh-agent/adapters/opencode/adapter.ts:75 /
-    // crates/freshell-freshagent/src/opencode_ws.rs:245) and no message
-    // history is visible, even though the durable ses_http_* session
-    // SURVIVED the kill (it still lists in the sidebar). The serve-DB
-    // survival half of §2.7 holds; the pane rebind half does not. The donor
-    // (freshopencode-restart-recovery.spec.ts) stays green because it never
-    // reloads the page -- live reconnect preserves in-memory pane state.
-    test.fail(
-      e2eServerKind === 'rust',
-      'P1.8/P1.13 (§2.7): post-reload freshopencode pane re-mints a freshopencode-* placeholder instead of rebinding the surviving ses_* session',
-    )
+    // HISTORY: this test was pinned `test.fail()` as P1.8/P1.13 (observed
+    // 2026-07-24): after SIGKILL+restart+RELOAD the pane re-minted a
+    // lazy-create `freshopencode-<requestId>` placeholder instead of
+    // rebinding the surviving ses_* session, and no history was visible.
+    // Fixed by this lane's settings-from-ledger resume work (run of
+    // 2026-07-26): post-reload the frozen client sends
+    // `freshAgent.create{resumeSessionId: ses_*}` (never attach), and
+    // opencode's `handle_create` now honors `resume_session_id`
+    // (crates/freshell-freshagent/src/opencode_ws.rs, unit pin
+    // `create_with_resume_session_id_rebinds_the_surviving_session`), so
+    // the pane rebinds the durable identity and rehydrates history -- the
+    // pin is removed (flip pattern: restore-matrix.spec.ts TERM-25).
+    // NOTE: the flip unmasked a latent strict-mode locator ambiguity in
+    // the history assertion below -- the prompt text renders in THREE
+    // places post-rehydrate (pane-header detail span, transcript "You"
+    // turn, and the response line), so `page.getByText(prompt)` was never
+    // satisfiable once rehydration worked. The assertion now targets the
+    // transcript's "You" turn explicitly, a strictly stronger check
+    // (history in the transcript, not merely the prompt echoed anywhere).
     const sharedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'freshell-wall-freshopencode-'))
     const projectDir = path.join(sharedRoot, 'project')
     await fs.mkdir(projectDir, { recursive: true })
@@ -1085,7 +1089,9 @@ test.describe('Restore Contract Wall (P0.1)', () => {
           timeout: 30_000,
         })
         .toBe(sessionId)
-      await expect(page.getByText(prompt)).toBeVisible({ timeout: 30_000 })
+      await expect(page.getByLabel('You transcript turn').getByText(prompt)).toBeVisible({
+        timeout: 30_000,
+      })
       await expect(page.getByText(`Fake OpenCode response: ${prompt}`)).toBeVisible({
         timeout: 30_000,
       })

From b2ce5cb8fd8cc4814e43be3a9a2a959c8d392ef6 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 08:39:15 -0700
Subject: [PATCH 74/87] fix(review): claude all-blank binding guard, shared
 retire-and-link helper, wall-spec comment fix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Final whole-branch review fixes (Lane B4):

- claude.rs: the sdk.session.init recording arm now skips the binding
  write when the threaded settings snapshot is entirely blank (V7/A10
  parity with codex record_codex_binding) -- an all-blank row would make
  was_recorded true while load_settings returns None, arming a FALSE
  SETTINGS_RESET for a legitimately-default session on a later resume.
  New test session_init_with_all_blank_settings_records_no_binding
  (shown RED before the guard, GREEN after).

- pane_ledger.rs: extracted the duplicated supersession retire block
  from record_binding_locked and record_fresh_agent_binding into ONE
  private retire_and_link_locked helper (behavior identical, no public
  API change) -- removes the two-copies drift hazard.

- restore-contract-wall-rust.spec.ts: HISTORY note now cites the actual
  Rust test name (create_with_resume_session_id_rebinds_the_durable_session).

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-freshagent/src/claude.rs      | 55 +++++++++++++++-
 crates/freshell-ws/src/pane_ledger.rs         | 65 +++++++++++++++----
 .../specs/restore-contract-wall-rust.spec.ts  |  2 +-
 3 files changed, 104 insertions(+), 18 deletions(-)

diff --git a/crates/freshell-freshagent/src/claude.rs b/crates/freshell-freshagent/src/claude.rs
index d0bcd98a8..4536addb8 100644
--- a/crates/freshell-freshagent/src/claude.rs
+++ b/crates/freshell-freshagent/src/claude.rs
@@ -731,9 +731,16 @@ impl FreshClaudeState {
                         // BEFORE the init-driven broadcast below proceeds (V8/A11).
                         // A failed write is surfaced user-visibly, never
                         // warn-and-drop, then the identity event proceeds.
-                        if let (Some(sink), Some(settings)) =
-                            (identity_sink.clone(), settings.as_ref())
-                        {
+                        // No-laundering guard (V7/A10, parity with codex's
+                        // `record_codex_binding`): never persist an all-blank
+                        // snapshot — it would make `was_recorded` true while
+                        // `load_settings` returns None (the server sink's
+                        // blank-snapshot guard), arming a FALSE SETTINGS_RESET
+                        // for a legitimately-default create on a later resume.
+                        let recordable = settings
+                            .as_ref()
+                            .filter(|s| **s != crate::identity_sink::FreshAgentSettings::default());
+                        if let (Some(sink), Some(settings)) = (identity_sink.clone(), recordable) {
                             if let Err(e) = sink
                                 .record_binding(crate::identity_sink::FreshAgentBindingUpsert {
                                     provider: PROVIDER.into(),
@@ -2033,6 +2040,48 @@ rl.on('line', (line) => {
         assert!(b.settings.cwd.is_some());
     }
 
+    /// No-laundering guard (V7/A10, parity with codex's `record_codex_binding`):
+    /// a create carrying NO optional settings (model/permissionMode/effort/cwd all
+    /// None) must NOT persist an all-blank binding row at `sdk.session.init`. A blank
+    /// row makes `was_recorded` true while `load_settings` returns None (the server
+    /// sink's blank-snapshot guard) — the exact SETTINGS_RESET alarm condition — so a
+    /// legitimately-default session would false-alarm on a later resume. The init
+    /// frame itself still broadcasts; only the ledger write is skipped.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn session_init_with_all_blank_settings_records_no_binding() {
+        let _guard = CLAUDE_ENV_LOCK.lock().await;
+        let env = FakeClaudeSidecarEnv::install();
+        let (state, mut rx) = state_with_bus();
+        let fake = std::sync::Arc::new(crate::identity_sink::FakeIdentitySink::default());
+        state.set_identity_sink(fake.clone());
+
+        // dedup_create_msg carries no model/permissionMode/effort/cwd — the
+        // all-blank snapshot shape.
+        state
+            .handle_create(dedup_create_msg("req-binding-blank"))
+            .await;
+        await_claude_created(&mut rx, "req-binding-blank").await;
+
+        // The init frame still broadcasts (the skip affects ONLY the ledger write).
+        tokio::time::timeout(std::time::Duration::from_secs(15), async {
+            loop {
+                let frame: Value = serde_json::from_str(&rx.recv().await.unwrap()).unwrap();
+                if frame["event"]["type"] == "freshAgent.session.init" {
+                    break;
+                }
+            }
+        })
+        .await
+        .expect("freshAgent.session.init consumed within budget");
+
+        assert!(
+            fake.bindings.lock().unwrap().is_empty(),
+            "an all-blank settings snapshot must not be persisted \
+             (it would arm a false SETTINGS_RESET on resume)"
+        );
+        drop(env);
+    }
+
     // ── resume settings-from-ledger (P1.13, Task 10) ─────────────────────────────
 
     /// P1.13 (Task 10): resume-in-place must reapply the pane's recorded
diff --git a/crates/freshell-ws/src/pane_ledger.rs b/crates/freshell-ws/src/pane_ledger.rs
index dc0e2be1b..a970b8825 100644
--- a/crates/freshell-ws/src/pane_ledger.rs
+++ b/crates/freshell-ws/src/pane_ledger.rs
@@ -409,24 +409,61 @@ impl PaneLedger {
         };
         self.write_binding(root, index, &row)?; // new bound row FIRST (pinned)
 
-        if let Some(mut old) = previous {
-            old.state = RowState::Retired;
-            old.retired_reason = Some(RetiredReason::Superseded);
-            old.superseded_by = Some(SessionLocator {
-                provider: w.provider.to_string(),
-                session_id: w.session_id.to_string(),
-            });
-            old.updated_at = w.now_ms;
-            tracing::info!(
+        if let Some(old) = previous {
+            self.retire_and_link_locked(
+                root,
+                index,
+                old,
+                SessionLocator {
+                    provider: w.provider.to_string(),
+                    session_id: w.session_id.to_string(),
+                },
+                w.now_ms,
+                Some(w.terminal_id),
+            )?;
+        }
+        Ok(())
+    }
+
+    /// Retire an old bound row and link it to the session that superseded it
+    /// (G3 retire-never-defend; the ONE supersession block shared by
+    /// [`Self::record_binding_locked`] and [`Self::record_fresh_agent_binding`]
+    /// so the two sites can never drift): state→Retired,
+    /// retired_reason→Superseded, superseded_by→the new session's locator,
+    /// updated_at→now, one info log, then persist. Callers write the new bound
+    /// row FIRST and call this AFTER (order pinned). `terminal_id` is `Some`
+    /// for terminal-pane rows (logged) and `None` for fresh-agent rows (which
+    /// own no terminal).
+    fn retire_and_link_locked(
+        &self,
+        root: &Path,
+        index: &mut LedgerIndex,
+        mut old: BindingRow,
+        superseded_by: SessionLocator,
+        now_ms: i64,
+        terminal_id: Option<&str>,
+    ) -> std::io::Result<()> {
+        old.state = RowState::Retired;
+        old.retired_reason = Some(RetiredReason::Superseded);
+        old.updated_at = now_ms;
+        match terminal_id {
+            Some(terminal_id) => tracing::info!(
                 target: "freshell_ws::pane_ledger",
-                terminal_id = %w.terminal_id,
+                terminal_id = %terminal_id,
                 old_session_id = %old.session_id,
-                new_session_id = %w.session_id,
+                new_session_id = %superseded_by.session_id,
                 "pane_ledger_superseded: binding moved; old row retired, never defended"
-            );
-            self.write_binding(root, index, &old)?; // THEN retire the old
+            ),
+            None => tracing::info!(
+                target: "freshell_ws::pane_ledger",
+                old_session_id = %old.session_id,
+                new_session_id = %superseded_by.session_id,
+                "pane_ledger_superseded: fresh-agent binding moved; \
+                 old row retired, never defended"
+            ),
         }
-        Ok(())
+        old.superseded_by = Some(superseded_by);
+        self.write_binding(root, index, &old) // THEN retire the old
     }
 
     /// Record (or refresh) a `bound` row for a fresh-agent identity event
diff --git a/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts b/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
index 5400d4840..00693fbf5 100644
--- a/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
+++ b/test/e2e-browser/specs/restore-contract-wall-rust.spec.ts
@@ -1012,7 +1012,7 @@ test.describe('Restore Contract Wall (P0.1)', () => {
     // `freshAgent.create{resumeSessionId: ses_*}` (never attach), and
     // opencode's `handle_create` now honors `resume_session_id`
     // (crates/freshell-freshagent/src/opencode_ws.rs, unit pin
-    // `create_with_resume_session_id_rebinds_the_surviving_session`), so
+    // `create_with_resume_session_id_rebinds_the_durable_session`), so
     // the pane rebinds the durable identity and rehydrates history -- the
     // pin is removed (flip pattern: restore-matrix.spec.ts TERM-25).
     // NOTE: the flip unmasked a latent strict-mode locator ambiguity in

From 2571097a7cb0899633e7747b76a97daae002085e Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 08:44:33 -0700
Subject: [PATCH 75/87] fix(review): complete retire-and-link helper extraction
 at the fresh-agent call site
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Commit b2ce5cb8 extracted retire_and_link_locked but only converted
record_binding_locked, leaving record_fresh_agent_binding with its
original inline retire-and-link block — and leaving the helper's
fresh-agent (terminal_id: None) log arm unreachable. Replace the inline
block with a helper call, preserving the old_id != session_id guard,
the silent no-op on a missing old row, the pinned new-row-first order,
and the exact fresh-agent log message. RetiredReason::Superseded now
appears in pane_ledger.rs only inside the helper.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-ws/src/pane_ledger.rs | 28 ++++++++++++---------------
 1 file changed, 12 insertions(+), 16 deletions(-)

diff --git a/crates/freshell-ws/src/pane_ledger.rs b/crates/freshell-ws/src/pane_ledger.rs
index a970b8825..b7adaa4de 100644
--- a/crates/freshell-ws/src/pane_ledger.rs
+++ b/crates/freshell-ws/src/pane_ledger.rs
@@ -515,22 +515,18 @@ impl PaneLedger {
         if let Some(old_id) = w.supersedes {
             if old_id != w.session_id {
                 let old_key = (w.provider.to_string(), old_id.to_string());
-                if let Some(mut old) = index.bindings.get(&old_key).cloned() {
-                    old.state = RowState::Retired;
-                    old.retired_reason = Some(RetiredReason::Superseded);
-                    old.superseded_by = Some(SessionLocator {
-                        provider: w.provider.to_string(),
-                        session_id: w.session_id.to_string(),
-                    });
-                    old.updated_at = w.now_ms;
-                    tracing::info!(
-                        target: "freshell_ws::pane_ledger",
-                        old_session_id = %old_id,
-                        new_session_id = %w.session_id,
-                        "pane_ledger_superseded: fresh-agent binding moved; \
-                         old row retired, never defended"
-                    );
-                    self.write_binding(root, &mut index, &old)?; // THEN retire the old
+                if let Some(old) = index.bindings.get(&old_key).cloned() {
+                    self.retire_and_link_locked(
+                        root,
+                        &mut index,
+                        old,
+                        SessionLocator {
+                            provider: w.provider.to_string(),
+                            session_id: w.session_id.to_string(),
+                        },
+                        w.now_ms,
+                        None, // fresh-agent rows own no terminal
+                    )?;
                 }
                 // Missing old row: silent no-op.
             }

From 402e3ed3cd690b25226c646e9aefabdc1dfd78ec Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 09:31:51 -0700
Subject: [PATCH 76/87] test(e2e): fixture realism + adopted-reality fixes for
 7 reconcile gate failures
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Task 15 gate-fix: the reconcile-adoption full run failed 7 specs; triage in
isolation reproduced 6 (harness-01-rust-server passed in isolation — parallel-
load flake, hardened below). No assertion was weakened or deleted; per-test
justification:

- fake-amplifier-cli.mjs, fake-amplifier-activity-cli.mjs (fixes
  amplifier-restore-rust, amplifier-lane-resilience-rust): FIXTURE REALISM —
  real amplifier persists metadata.json, the CANONICAL record the session
  index reads (amplifier.rs); the fakes wrote only events.jsonl, so the
  adopted client's disk-truth verdict was honestly
  dead_session{session_not_on_disk} (dialog captured in error-context)
  instead of respawn-with-resume. The fakes now mirror the real CLI's
  persistence. Assertions untouched.

- wavea-interactions-rust (A2xA3): FIXTURE REALISM — same Task-14 precedent
  as restore-contract-wall-rust's claude scenario: write the
  ~/.claude/projects/<proj>/<sessionId>.jsonl a real claude would have
  persisted before the abrupt kill. Assertions untouched.

- opencode-terminal-restore-rust, amplifier-restore-rust: stale-terminalId
  capture race — the adopted client is non-destructive on boot (pane keeps
  persisted terminalId+status until the verdict folds), so the old
  "status not error && terminalId truthy" gate matched the STALE pre-restart
  id and the resume-marker poll scraped a dead terminal (error-context showed
  the resume marker ALIVE in the new terminal). Now polls until the id
  provably changed (wall-spec pattern) — a STRICTER gate; the marker/argv
  assertions are untouched.

- multi-client (reconnecting second viewer): legacy-observation rewrite —
  toHaveLength(1) encoded the pre-reconcile client's single attach source.
  Under paneReconcileV1 a reconnect legitimately has two: TerminalView's own
  reconnect path + the attach-verdict fold's deliberate reconcileEpoch
  re-fire (the A1 design pin: "every fold bumps reconcileEpoch"). Contract
  guarded is unchanged and still asserted: not dropped (>=1), no retry storm
  (<=2), reconnect-shaped intent, PTY size stable, shared output intact.

- session-directory-matrix: latent time bomb, NOT branch-caused — amplifier
  lastActivityAt folds transcript.jsonl/events.jsonl mtimes
  (getActivityMtimeMs port); seed-time mtime "now" began dominating the
  seeded 2026-07-19T08:00:02Z metadata timestamp the moment the wall clock
  passed it. FIXTURE REALISM: fs.utimes the seeded files to the seeded
  activity instant. Exact-match assertion untouched.

- harness-01-rust-server: parallel-load flake — passed in isolation both
  runs; under full-project load (14 workers + cargo build-lock contention)
  the post-restart marker wait exceeded its 20s budget. Budget raised to
  60s; the assertion itself (marker MUST appear) is unchanged.

All six reproducing specs re-run green in isolation (7, 6, 1, 1, 3, 2
passed); harness-01 green in isolation (1 passed).

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../fixtures/fake-amplifier-activity-cli.mjs  | 17 ++++++++++++
 .../fixtures/fake-amplifier-cli.mjs           | 18 +++++++++++++
 .../specs/amplifier-restore-rust.spec.ts      | 27 ++++++++++++++-----
 .../specs/harness-01-rust-server.spec.ts      | 10 ++++++-
 test/e2e-browser/specs/multi-client.spec.ts   | 15 ++++++++++-
 .../opencode-terminal-restore-rust.spec.ts    | 27 ++++++++++++++-----
 .../specs/session-directory-matrix.spec.ts    | 13 +++++++++
 .../specs/wavea-interactions-rust.spec.ts     | 21 +++++++++++++++
 8 files changed, 132 insertions(+), 16 deletions(-)

diff --git a/test/e2e-browser/fixtures/fake-amplifier-activity-cli.mjs b/test/e2e-browser/fixtures/fake-amplifier-activity-cli.mjs
index e6547f468..eb9471ca9 100644
--- a/test/e2e-browser/fixtures/fake-amplifier-activity-cli.mjs
+++ b/test/e2e-browser/fixtures/fake-amplifier-activity-cli.mjs
@@ -68,6 +68,23 @@ process.stdin.on('data', () => {
           data: { raw: { working_dir: cwd } },
         }),
     )
+    // FIXTURE REALISM (reconcile adoption): real amplifier persists
+    // `metadata.json` alongside `events.jsonl` -- and `metadata.json` is the
+    // CANONICAL record the session index reads
+    // (`crates/freshell-sessions/src/amplifier.rs`; R10b requires
+    // `working_dir`). Without it, a claimed amplifier session is invisible
+    // to the disk-truth existence probe and the post-restart reconcile
+    // verdict is honestly `dead_session{session_not_on_disk}` instead of
+    // respawn-with-resume. Mirror what the real CLI writes.
+    fs.writeFileSync(
+      path.join(sessionDir, 'metadata.json'),
+      JSON.stringify({
+        session_id: sessionId,
+        working_dir: cwd,
+        created: new Date().toISOString(),
+        name: `fake amplifier activity e2e session ${sessionId}`,
+      }),
+    )
     process.stdout.write(`amplifier: session ${sessionId} started\r\n`)
   }
   fs.appendFileSync(eventsPath, record('prompt:submit', { session_id: sessionId }))
diff --git a/test/e2e-browser/fixtures/fake-amplifier-cli.mjs b/test/e2e-browser/fixtures/fake-amplifier-cli.mjs
index a079dba6e..af2f216ba 100644
--- a/test/e2e-browser/fixtures/fake-amplifier-cli.mjs
+++ b/test/e2e-browser/fixtures/fake-amplifier-cli.mjs
@@ -76,6 +76,24 @@ if (argv[0] === 'resume') {
       JSON.stringify({ event: 'session:config', working_dir: cwd }),
     ]
     fs.writeFileSync(path.join(sessionDir, 'events.jsonl'), `${lines.join('\n')}\n`)
+    // FIXTURE REALISM (reconcile adoption): real amplifier persists
+    // `metadata.json` alongside `events.jsonl` -- and `metadata.json` is the
+    // CANONICAL record the session index reads
+    // (`crates/freshell-sessions/src/amplifier.rs`: "Only metadata.json is
+    // read+parsed for the session-directory listing"; R10b requires
+    // `working_dir`). Without it, a claimed amplifier session is invisible
+    // to the disk-truth existence probe and the post-restart reconcile
+    // verdict is honestly `dead_session{session_not_on_disk}` instead of
+    // respawn-with-resume. Mirror what the real CLI writes.
+    fs.writeFileSync(
+      path.join(sessionDir, 'metadata.json'),
+      JSON.stringify({
+        session_id: sessionId,
+        working_dir: cwd,
+        created: new Date().toISOString(),
+        name: `fake amplifier e2e session ${sessionId}`,
+      }),
+    )
 
     process.stdout.write(`amplifier: session ${sessionId} started\r\n`)
   })
diff --git a/test/e2e-browser/specs/amplifier-restore-rust.spec.ts b/test/e2e-browser/specs/amplifier-restore-rust.spec.ts
index 519665c6c..652e74779 100644
--- a/test/e2e-browser/specs/amplifier-restore-rust.spec.ts
+++ b/test/e2e-browser/specs/amplifier-restore-rust.spec.ts
@@ -319,14 +319,27 @@ test.describe('Amplifier Restore (Rust only)', () => {
         // own greppable stdout marker, scoped to THIS pane's terminal, and
         // (2) the argv log the fixture writes on every invocation
         // (independent of terminal-buffer scraping).
-        await expect(async () => {
-          const leaf = await findLeafById(tabId!, positivePaneId)
-          expect(leaf?.content?.status).not.toBe('error')
-          expect(leaf?.content?.terminalId).toBeTruthy()
-        }).toPass({ timeout: 30_000 })
-
-        const restoredTerminalId: string | undefined = (await findLeafById(tabId!, positivePaneId))?.content?.terminalId
+        // Wait for the pane to hold a NEW terminalId (the respawn's), not
+        // the persisted pre-restart one. Under the adopted reconcile client
+        // the pane is non-destructive on boot: it keeps its persisted
+        // terminalId + status until the verdict folds, so a "status not
+        // error && terminalId truthy" gate is satisfiable by the STALE
+        // pre-restart identity and racing it captured a dead terminal id
+        // (the resume marker then lands in the NEW terminal's buffer,
+        // invisible to a poll scoped to the stale one). Same pattern the
+        // restore-contract wall's claude scenario uses: poll until the id
+        // provably changed.
+        const restoredTerminalId: string = await expect
+          .poll(async () => {
+            const leaf = await findLeafById(tabId!, positivePaneId)
+            if (leaf?.content?.status === 'error') return null
+            const tid = leaf?.content?.terminalId
+            return tid && tid !== terminalIdBefore ? tid : null
+          }, { timeout: 30_000 })
+          .not.toBeNull()
+          .then(async () => (await findLeafById(tabId!, positivePaneId))!.content.terminalId)
         expect(restoredTerminalId).toBeTruthy()
+        expect(restoredTerminalId).not.toBe(terminalIdBefore)
         // Same xterm line-wrap caveat as the "session started" marker above
         // -- strip newlines before matching.
         await expect.poll(async () => {
diff --git a/test/e2e-browser/specs/harness-01-rust-server.spec.ts b/test/e2e-browser/specs/harness-01-rust-server.spec.ts
index 9021cd09f..80d5ab85e 100644
--- a/test/e2e-browser/specs/harness-01-rust-server.spec.ts
+++ b/test/e2e-browser/specs/harness-01-rust-server.spec.ts
@@ -135,9 +135,17 @@ test.describe('HARNESS-01: owned Rust-server fixture', () => {
       // Prove the reconnected terminal is FUNCTIONALLY alive (not just
       // showing stale pre-restart DOM content): a brand-new command must
       // still execute correctly after the client recreates/reattaches.
+      // Budget note: 60s, not 20s. The assertion is unchanged (the marker
+      // MUST appear); only the wait budget grew. Under a full-project run
+      // this spec shares the host with ~14 parallel workers each spawning
+      // rust servers (and cargo build-lock contention), and the
+      // post-restart recreate/reattach round-trip was observed to
+      // legitimately exceed 20s under that load while passing comfortably
+      // in isolation (both observed on 2026-07-26). The spec-level
+      // test.setTimeout(180_000) already anticipated slow full-suite runs.
       const marker2 = `HARNESS01-POST-RESTART-${randomUUID()}`
       await terminal.executeCommand(`echo ${marker2}`)
-      await terminal.waitForOutput(marker2, { timeout: 20_000 })
+      await terminal.waitForOutput(marker2, { timeout: 60_000 })
 
       const xtermText = await page.locator('.xterm').first().textContent()
       expect(xtermText).not.toContain('[Error]')
diff --git a/test/e2e-browser/specs/multi-client.spec.ts b/test/e2e-browser/specs/multi-client.spec.ts
index 1b2baa258..1d9f7a9bf 100644
--- a/test/e2e-browser/specs/multi-client.spec.ts
+++ b/test/e2e-browser/specs/multi-client.spec.ts
@@ -294,7 +294,20 @@ test.describe('Multi-Client', () => {
         && (msg?.intent === 'transport_reconnect' || msg?.intent === 'viewport_hydrate')
       )
     }, terminalId!)
-    expect(reconnectAttachMessages).toHaveLength(1)
+    // Under paneReconcileV1 (the adopted client) a reconnect has TWO
+    // legitimate attach sources for a live pane: (1) TerminalView's own
+    // reconnect/reveal path, and (2) the pane.reconcile `attach` verdict
+    // fold, which bumps `reconcileEpoch` and deliberately re-fires the
+    // attach effect so the pane converges on server truth even when the
+    // client's own bookkeeping is wrong (the A1 epoch-bump design pin in
+    // `panesSlice.reconcile.test.ts`: "every fold bumps reconcileEpoch").
+    // The pre-reconcile client had only source (1), which is what the old
+    // `toHaveLength(1)` encoded. The behavior this test actually guards is
+    // unchanged and still asserted: the reconnect was not silently dropped
+    // (>= 1), and there is no runaway retry storm (<= 2 -- exactly the two
+    // named sources, nothing unbounded).
+    expect(reconnectAttachMessages.length).toBeGreaterThanOrEqual(1)
+    expect(reconnectAttachMessages.length).toBeLessThanOrEqual(2)
 
     await executeCommand(page1, 'printf "__PTY_SIZE_AFTER__:%s\\n" "$(stty size)"')
     const afterSize = await waitForMarkedPtySize(page1, '__PTY_SIZE_AFTER__', terminalId!)
diff --git a/test/e2e-browser/specs/opencode-terminal-restore-rust.spec.ts b/test/e2e-browser/specs/opencode-terminal-restore-rust.spec.ts
index fe2313d18..58d0dfcaa 100644
--- a/test/e2e-browser/specs/opencode-terminal-restore-rust.spec.ts
+++ b/test/e2e-browser/specs/opencode-terminal-restore-rust.spec.ts
@@ -302,14 +302,27 @@ test.describe('OpenCode Terminal Restore (Rust only)', () => {
         // fixture's own greppable stdout marker, scoped to THIS pane's
         // terminal, and (2) the argv log the fixture writes on every
         // invocation (independent of terminal-buffer scraping).
-        await expect(async () => {
-          const leaf = await findLeafById(tabId!, positivePaneId)
-          expect(leaf?.content?.status).not.toBe('error')
-          expect(leaf?.content?.terminalId).toBeTruthy()
-        }).toPass({ timeout: 30_000 })
-
-        const restoredTerminalId: string | undefined = (await findLeafById(tabId!, positivePaneId))?.content?.terminalId
+        // Wait for the pane to hold a NEW terminalId (the respawn's), not
+        // the persisted pre-restart one. Under the adopted reconcile client
+        // the pane is non-destructive on boot: it keeps its persisted
+        // terminalId + status until the verdict folds, so a "status not
+        // error && terminalId truthy" gate is satisfiable by the STALE
+        // pre-restart identity and racing it captured a dead terminal id
+        // (the resume marker then lands in the NEW terminal's buffer,
+        // invisible to a poll scoped to the stale one). Same pattern the
+        // restore-contract wall's claude scenario uses: poll until the id
+        // provably changed.
+        const restoredTerminalId: string = await expect
+          .poll(async () => {
+            const leaf = await findLeafById(tabId!, positivePaneId)
+            if (leaf?.content?.status === 'error') return null
+            const tid = leaf?.content?.terminalId
+            return tid && tid !== terminalIdBefore ? tid : null
+          }, { timeout: 30_000 })
+          .not.toBeNull()
+          .then(async () => (await findLeafById(tabId!, positivePaneId))!.content.terminalId)
         expect(restoredTerminalId).toBeTruthy()
+        expect(restoredTerminalId).not.toBe(terminalIdBefore)
         await expect.poll(async () => {
           const buffer = await harness.getTerminalBuffer(restoredTerminalId)
           const unwrapped = typeof buffer === 'string' ? buffer.replace(/\n/g, '') : ''
diff --git a/test/e2e-browser/specs/session-directory-matrix.spec.ts b/test/e2e-browser/specs/session-directory-matrix.spec.ts
index ade240051..4ca1d9315 100644
--- a/test/e2e-browser/specs/session-directory-matrix.spec.ts
+++ b/test/e2e-browser/specs/session-directory-matrix.spec.ts
@@ -286,6 +286,19 @@ const test = base.extend({
               JSON.stringify({ role: 'assistant', content: 'harness-02 matrix epsilon reply 1' }),
             ].join('\n') + '\n',
           )
+          // FIXTURE REALISM: the amplifier recency formula folds the
+          // activity-sidecar mtimes into lastActivityAt --
+          // `max(metadata timestamps, mtime(transcript.jsonl), mtime(events.jsonl))`
+          // (`crates/freshell-sessions/src/amplifier.rs`'s
+          // `getActivityMtimeMs` port). Seed-time mtimes are "now", which
+          // silently dominated the seeded 2026-07-19 metadata timestamp the
+          // moment the real-world clock passed it (a time bomb, detonated
+          // 2026-07-19T08:00:02Z). A session genuinely last active at the
+          // seeded instant would carry file mtimes from that instant -- set
+          // them explicitly so the fixture matches what it claims.
+          const amplifierSeededActivity = new Date(AMPLIFIER_LAST_ACTIVITY_AT_ISO)
+          await fs.utimes(path.join(amplifierSessionDir, 'metadata.json'), amplifierSeededActivity, amplifierSeededActivity)
+          await fs.utimes(path.join(amplifierSessionDir, 'transcript.jsonl'), amplifierSeededActivity, amplifierSeededActivity)
         },
       },
     })
diff --git a/test/e2e-browser/specs/wavea-interactions-rust.spec.ts b/test/e2e-browser/specs/wavea-interactions-rust.spec.ts
index 73ae19c26..a06372182 100644
--- a/test/e2e-browser/specs/wavea-interactions-rust.spec.ts
+++ b/test/e2e-browser/specs/wavea-interactions-rust.spec.ts
@@ -342,6 +342,27 @@ test.describe('wave-A cross-lane interactions', () => {
           }, { timeout: 30_000 })
           .toBe(FRESH_DURABLE)
 
+        // FIXTURE REALISM (reconcile adoption): real claude writes
+        // ~/.claude/projects/<proj>/<sessionId>.jsonl as soon as the session
+        // starts; the fake CLI does not. Under the adopted client the
+        // post-restart verdict is derived from DISK truth (a claimed session
+        // with no file is a loud dead_session, never an optimistic silent
+        // respawn), so mirror what real claude persists before the kill --
+        // same precedent as restore-contract-wall-rust.spec.ts's claude
+        // scenario.
+        const claudeProjDir = path.join(capturedHome, '.claude', 'projects', 'wavea-a2a3-proj')
+        await fs.mkdir(claudeProjDir, { recursive: true })
+        await fs.writeFile(
+          path.join(claudeProjDir, `${terminalSession}.jsonl`),
+          `${JSON.stringify({
+            type: 'user',
+            message: 'wavea a2a3 fixture transcript',
+            uuid: 'msg-1',
+            cwd: capturedHome,
+            timestamp: '2026-07-21T08:00:00.000Z',
+          })}\n`,
+        )
+
         // ── ONE abrupt restart; both stores must restore, independently. ──
         await server.restartAbrupt()
         await waitForWsReady(page)

From 3918fbc07e1564df6b500cec6e0417919eedf33a Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 10:12:44 -0700
Subject: [PATCH 77/87] fix: final-review findings - claim-side TOCTOU re-check
 + App fold clears stale batched UI state
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Finding 1 (registry.rs): claim_session_ref's lease phase now re-checks
session_ref_bindings WHILE HOLDING the leases lock before acquiring. A
loser that passed checks 1a/1b pre-registration and was preempted across
the winner's register->complete window previously saw no lease and
answered Acquired -> second spawn on one sessionRef (the D8
duplicate-writer shape). Lock order leases->bindings matches
complete_session_ref_claim; acyclic. Lease phase extracted so the
interleave is pinnable sequentially (step 1b intercepts any full claim
while a binding exists, so only direct lease-phase entry exercises the
re-check). New test: lease_phase_rechecks_bindings_under_leases_lock
(RED pre-fix: got Acquired).

Finding 2 (App.tsx): after a non-cardinality-violation fold, App's
all-pane fold site (authoritative) dispatches clearReconcileWarming()
when the round reports 0 warming and clearDeadSessionAdjudication()
when 0 dead - a clean round after a WS reconnect no longer leaves the
warming banner or dead-sessions dialog up forever. Deliberately NOT in
foldVerdicts: single-pane requesters must not clear other panes' state.
New test in App.reconcile-adoption.test.tsx (RED pre-fix: warming state
survived the clean round).

Finding 3 (TerminalView.tsx, comment-only): reserveWindowStart comment
now claims exactly the effect-re-fire protection; a full unmount/remount
DOES reset the window (the ref dies with the component).

Finding 4 (multi-client.spec.ts, comment-only): stale "exactly one
re-attach" comment updated to the bounded 1..2 contract (reconnect
attach + at most one designed reconcileEpoch fold re-fire).

Gates: cargo fmt/clippy clean; cargo test -p freshell-terminal 131
passed; vitest App.reconcile-adoption + pane-reconcile 27 passed;
typecheck:client clean. No existing assertions weakened.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-terminal/src/registry.rs      | 89 +++++++++++++++++++
 src/App.tsx                                   | 18 +++-
 src/components/TerminalView.tsx               |  7 +-
 test/e2e-browser/specs/multi-client.spec.ts   | 12 +--
 .../App.reconcile-adoption.test.tsx           | 38 +++++++-
 5 files changed, 155 insertions(+), 9 deletions(-)

diff --git a/crates/freshell-terminal/src/registry.rs b/crates/freshell-terminal/src/registry.rs
index 83dbc453b..6a8d0c80a 100644
--- a/crates/freshell-terminal/src/registry.rs
+++ b/crates/freshell-terminal/src/registry.rs
@@ -1792,12 +1792,56 @@ impl TerminalRegistry {
             }
         }
 
+        self.claim_session_ref_lease_phase(locator, holder_create_request_id, holder_conn, now_ms)
+    }
+
+    /// Lease phase of [`Self::claim_session_ref`] (steps 2-4: held /
+    /// expired / free). Split out so the claim-side TOCTOU re-check
+    /// (final review finding 1) can be pinned by a test that stages
+    /// "loser passed checks 1a/1b before the winner registered" without
+    /// threads: a full `claim_session_ref` call is always caught by step
+    /// 1b while a binding exists, so only a direct entry here can
+    /// exercise the under-lock re-check.
+    fn claim_session_ref_lease_phase(
+        &self,
+        locator: &SessionLocator,
+        holder_create_request_id: &str,
+        holder_conn: u64,
+        now_ms: u64,
+    ) -> SessionRefClaim {
+        let key = session_ref_key(locator);
         let mut leases = self
             .session_ref_leases
             .lock()
             .expect("session-ref lease lock");
         match leases.get_mut(&key) {
             None => {
+                // Claim-side TOCTOU (final review finding 1): checks 1a/1b
+                // ran BEFORE this lock was taken. A loser preempted across
+                // the winner's register -> `complete_session_ref_claim`
+                // window arrives here after complete removed the winner's
+                // lease -- seeing no lease -- while only the bindings map
+                // records the winner. Re-check bindings WHILE HOLDING the
+                // leases lock: a recorded binding means a winner already
+                // completed, so answer `BoundElsewhere` instead of
+                // double-acquiring (a second spawn on one sessionRef is the
+                // duplicate-writer shape D8 exists to close). Lock order
+                // leases -> bindings matches `complete_session_ref_claim`
+                // and is acyclic: step 1b's bindings block ends before the
+                // leases lock is taken, and no path acquires the leases
+                // lock while holding bindings. A binding observed here is
+                // either freshly completed (live winner) or, if its winner
+                // has since died, handled on the loser's retry claim, whose
+                // step 1b prunes known-dead winners.
+                let bound = self
+                    .session_ref_bindings
+                    .lock()
+                    .expect("session-ref bindings lock")
+                    .get(&key)
+                    .cloned();
+                if let Some(terminal_id) = bound {
+                    return SessionRefClaim::BoundElsewhere { terminal_id };
+                }
                 leases.insert(
                     key,
                     SessionRefLease {
@@ -4122,6 +4166,51 @@ mod tests {
         ));
     }
 
+    /// Final-review finding 1 (claim-side TOCTOU): loser B passes checks
+    /// 1a/1b while both maps are still empty, is preempted across the
+    /// winner's register -> `complete_session_ref_claim` window, then takes
+    /// the leases lock AFTER complete removed the lease. Pre-fix the lease
+    /// phase saw "no lease" and answered `Acquired` -> a second spawn for
+    /// the same sessionRef (the duplicate-writer shape D8 exists to close).
+    ///
+    /// Staged sequentially, no threads: the winner claims, registers its
+    /// row, and completes (binding recorded, lease gone); B then enters the
+    /// lease phase DIRECTLY -- exactly the state B is in after its early
+    /// (empty) 1a/1b pass. A full `claim_session_ref` call from B cannot
+    /// pin the fix: while the binding exists, step 1b always intercepts it,
+    /// so only direct entry exercises the under-lock bindings re-check.
+    #[test]
+    fn lease_phase_rechecks_bindings_under_leases_lock() {
+        let reg = test_registry();
+        let s = locator("claude", "s1");
+        assert!(matches!(
+            reg.claim_session_ref(&s, "cr-A", 1, 1000),
+            SessionRefClaim::Acquired
+        ));
+        reg.register_headless(HeadlessTerminal {
+            terminal_id: "T-win".to_string(),
+            stream_id: "S-win".to_string(),
+            mode: "claude".to_string(),
+            resume_session_id: Some("s1".to_string()),
+            create_request_id: Some("cr-A".to_string()),
+            created_at: Some(1_000),
+        });
+        assert!(reg.complete_session_ref_claim(&s, "cr-A", "T-win"));
+        // B resumes at the lease phase; its 1a/1b ran before the winner
+        // existed, so neither check fired. It must NOT acquire.
+        match reg.claim_session_ref_lease_phase(&s, "cr-B", 2, 2000) {
+            SessionRefClaim::BoundElsewhere { terminal_id } => {
+                assert_eq!(terminal_id, "T-win")
+            }
+            other => panic!("expected BoundElsewhere, got {other:?}"),
+        }
+        // The full claim path agrees (step 1a/1b catch it sequentially).
+        assert!(matches!(
+            reg.claim_session_ref(&s, "cr-B", 2, 2000),
+            SessionRefClaim::BoundElsewhere { .. }
+        ));
+    }
+
     /// §5.1 atomic-stamp insert-edge interleave (§9.1 test 5): the key is part
     /// of the row inserted under the registry lock, so an observer's
     /// `newest_live_by_create_request_id` sees either no row or the
diff --git a/src/App.tsx b/src/App.tsx
index 9cc4bb10a..5fe834544 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -64,7 +64,7 @@ import { X, Copy, Check, PanelLeft, AlertTriangle } from 'lucide-react'
 import { updateSettingsLocal } from '@/store/settingsSlice'
 
 import { setTerminalMetaSnapshot, upsertTerminalMeta, removeTerminalMeta } from '@/store/terminalMetaSlice'
-import { clearDeadTerminals, clearTerminalLiveHandles } from '@/store/panesSlice'
+import { clearDeadSessionAdjudication, clearDeadTerminals, clearReconcileWarming, clearTerminalLiveHandles } from '@/store/panesSlice'
 import { addTerminalFreshRecoveryRequestId, addTerminalRestoreRequestId, setPaneReconcileActive } from '@/lib/terminal-restore'
 import { reconcileTerminalSessionAssociation } from '@/lib/terminal-session-association'
 import { setCodexActivitySnapshot, upsertCodexActivity, removeCodexActivity, resetCodexActivity } from '@/store/codexActivitySlice'
@@ -1060,6 +1060,22 @@ export default function App() {
           if (outcome.cardinalityViolation) {
             console.error('[reconcile] cardinality violation — falling back to legacy census')
             fallBackToLegacyCensus()
+            return
+          }
+          // Final-review finding 2: foldVerdicts only SETS the batched
+          // warming/dead-adjudication state (counts > 0) — it never clears
+          // it, so a later clean round (e.g. after a WS reconnect) would
+          // leave the warming banner or dead-sessions dialog up forever.
+          // App's request covers EVERY terminal pane, so its outcome is
+          // authoritative — clear whichever batched state this round
+          // reported none of. Deliberately NOT inside foldVerdicts:
+          // single-pane requesters (TerminalView exhaustion auto-resolve,
+          // warming-banner Retry) must not clear state about other panes.
+          if (outcome.warming === 0) {
+            dispatch(clearReconcileWarming())
+          }
+          if (outcome.dead === 0) {
+            dispatch(clearDeadSessionAdjudication())
           }
           return
         }
diff --git a/src/components/TerminalView.tsx b/src/components/TerminalView.tsx
index 3c07a9555..96b11e7b5 100644
--- a/src/components/TerminalView.tsx
+++ b/src/components/TerminalView.tsx
@@ -579,8 +579,11 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
   const lastSessionActivityAtRef = useRef(0)
   const paneLastInputAtRef = useRef<number | undefined>(paneLastInputAt)
   const rateLimitRetryRef = useRef<{ count: number; timer: ReturnType<typeof setTimeout> | null }>({ count: 0, timer: null })
-  // Task 12 bounded re-drive state. reserveWindowStart is wall-clock so a
-  // remount mid-standoff cannot refund the SESSION_RESERVED window.
+  // Task 12 bounded re-drive state. reserveWindowStart is wall-clock so an
+  // effect re-fire mid-standoff (deps change on the still-mounted pane)
+  // cannot refund the SESSION_RESERVED window. A full unmount/remount DOES
+  // reset it — the ref dies with the component — so the window is bounded
+  // per component instance, not per pane lifetime.
   const reconcileRedriveRef = useRef<{
     reserveWindowStart: number | null
     invalidAttempts: number
diff --git a/test/e2e-browser/specs/multi-client.spec.ts b/test/e2e-browser/specs/multi-client.spec.ts
index 1d9f7a9bf..411afa788 100644
--- a/test/e2e-browser/specs/multi-client.spec.ts
+++ b/test/e2e-browser/specs/multi-client.spec.ts
@@ -272,11 +272,13 @@ test.describe('Multi-Client', () => {
     // either way. So the specific intent value is an internal implementation
     // choice, not the behavior this test is meant to guard -- asserting the
     // exact intent was over-constraining an implementation detail rather than
-    // the contract. What DOES matter, and is still asserted: page2 issued
-    // exactly one re-attach for this terminal (not zero -- a silently dropped
-    // reconnect -- and not a runaway retry storm), using a reconnect-shaped
-    // intent (not a cold 'keepalive_delta', which would mean it never
-    // recognized this as a reconnect at all).
+    // the contract. What DOES matter, and is still asserted: page2 issued a
+    // BOUNDED 1..2 re-attaches for this terminal (not zero -- a silently
+    // dropped reconnect -- and not a runaway retry storm; the 2 covers the
+    // reconnect attach plus at most one designed pane.reconcile fold
+    // re-fire via the reconcileEpoch bump, detailed below), using a
+    // reconnect-shaped intent (not a cold 'keepalive_delta', which would
+    // mean it never recognized this as a reconnect at all).
     await page2.waitForFunction((id) => {
       const sent = window.__FRESHELL_TEST_HARNESS__?.getSentWsMessages?.() ?? []
       return sent.some((msg: any) =>
diff --git a/test/unit/client/components/App.reconcile-adoption.test.tsx b/test/unit/client/components/App.reconcile-adoption.test.tsx
index c3dfa006b..28ded5191 100644
--- a/test/unit/client/components/App.reconcile-adoption.test.tsx
+++ b/test/unit/client/components/App.reconcile-adoption.test.tsx
@@ -7,7 +7,7 @@ import settingsReducer, { defaultSettings } from '@/store/settingsSlice'
 import tabsReducer from '@/store/tabsSlice'
 import connectionReducer, { setLiveTerminalIds } from '@/store/connectionSlice'
 import sessionsReducer from '@/store/sessionsSlice'
-import panesReducer, { applyReconcileAttach, clearDeadTerminals } from '@/store/panesSlice'
+import panesReducer, { applyReconcileAttach, clearDeadTerminals, setDeadSessionAdjudication } from '@/store/panesSlice'
 import tabRegistryReducer from '@/store/tabRegistrySlice'
 import terminalMetaReducer from '@/store/terminalMetaSlice'
 import extensionsReducer from '@/store/extensionsSlice'
@@ -423,6 +423,42 @@ describe('App pane.reconcile adoption', () => {
     expect(dispatched.types).toContain(clearDeadTerminals.type) // census ran from cached liveTerminalIds
   })
 
+  it('a later clean App-level fold clears stale warming banner and dead-session adjudication', async () => {
+    // Final-review finding 2: foldVerdicts only SETS the batched warming /
+    // dead state (counts > 0) — App's fold site must clear it when its
+    // all-pane round reports none, or a banner/dialog from an earlier
+    // round survives forever.
+    seedPersistedTerminalPane({ createRequestId: 'cr-1' })
+    const { sentFrames, store } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })
+    const req1 = sentFrames.find((f) => f.type === 'pane.reconcile.request')!
+    // Warming round: banner state set.
+    await receiveServerFrame({
+      type: 'pane.reconcile.result',
+      reconcileId: req1.reconcileId,
+      bootId: 'boot-1',
+      serverInstanceId: 'srv-1',
+      verdicts: req1.panes.map((pane: any) => ({
+        paneKey: pane.paneKey,
+        verdict: 'error',
+        reason: 'index_warming',
+      })),
+    })
+    expect(store.getState().panes.reconcileWarming).not.toBeNull()
+    // A dead-sessions dialog from an earlier round is also still up.
+    act(() => {
+      store.dispatch(setDeadSessionAdjudication([
+        { tabId: 'tab-1', paneId: 'pane-1', title: 'Terminal', mode: 'shell' },
+      ]))
+    })
+    // WS reconnect: ready re-sends the App-level request (covers every pane).
+    await simulateReconnectWithReady({ capabilities: { paneReconcileV1: true } })
+    const req2 = sentFrames.filter((f) => f.type === 'pane.reconcile.request')[1]
+    // Clean all-attach round: authoritative — stale batched UI state clears.
+    await receiveServerFrame(attachResultFor(req2, 'term-new'))
+    expect(store.getState().panes.reconcileWarming).toBeNull()
+    expect(store.getState().panes.deadSessionAdjudication ?? []).toHaveLength(0)
+  })
+
   it('re-sends the reconcile request on EVERY ready (reconnect covers loss windows)', async () => {
     seedPersistedTerminalPane({ createRequestId: 'cr-1' })
     const { sentFrames } = await bootAppWithReady({ capabilities: { paneReconcileV1: true } })

From c2eb82dcc5bce1b9e6f191988920f122d3803a45 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 10:46:11 -0700
Subject: [PATCH 78/87] fix: cross-lane compile fallout from waveB merges
 (designed B1xB4 seams)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- reconcile_freshagent.rs: honor B4's DELETE-AT-MERGE annotation (drop
  retry_after_ms from the single PaneVerdict construction point) and add
  the pre-decided ProviderUnavailable => Unknown presence arm (V9/A12:
  conservative respawn-with-cap, never dead_session).
- terminal.rs: fold B4's fresh_agent snapshot borrow into B1's rebuilt-deps
  derive closure (snapshot built ONCE per request - rebuilding would
  double-burn the respawn counter; V9 3.6); drop the now-dead outer deps.
- codex_association.rs / common/mod.rs / pane_reconcile_freshagent.rs:
  test fixtures gain the other lanes' WsState fields
  (reconcile_deferral_budget_ms, fresh_agent_respawn_counts, codex_locator).
- recovery_inventory_tests.rs: BindingRow fixtures gain B4's five optional
  resume-invocation fields.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../freshell-server/src/recovery_inventory_tests.rs   |  5 +++++
 crates/freshell-ws/src/codex_association.rs           |  2 ++
 crates/freshell-ws/src/reconcile_freshagent.rs        |  7 ++++---
 crates/freshell-ws/src/terminal.rs                    | 11 ++++-------
 crates/freshell-ws/tests/common/mod.rs                |  2 ++
 crates/freshell-ws/tests/pane_reconcile_freshagent.rs |  2 ++
 6 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/crates/freshell-server/src/recovery_inventory_tests.rs b/crates/freshell-server/src/recovery_inventory_tests.rs
index b8a557fda..07938738b 100644
--- a/crates/freshell-server/src/recovery_inventory_tests.rs
+++ b/crates/freshell-server/src/recovery_inventory_tests.rs
@@ -72,6 +72,11 @@ fn binding_row_at(
         state,
         retired_reason,
         superseded_by,
+        pane_kind: None,
+        model: None,
+        sandbox: None,
+        permission_mode: None,
+        effort: None,
     }
 }
 
diff --git a/crates/freshell-ws/src/codex_association.rs b/crates/freshell-ws/src/codex_association.rs
index f61c28e5b..32ab6c3b3 100644
--- a/crates/freshell-ws/src/codex_association.rs
+++ b/crates/freshell-ws/src/codex_association.rs
@@ -226,6 +226,8 @@ mod tests {
             codex_locator: Some(StdArc::new(CodexLocator::new(data_home))),
             activity: None,
             session_existence: std::sync::Arc::new(crate::existence::NoIndexProbe::default()),
+            reconcile_deferral_budget_ms: crate::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
+            fresh_agent_respawn_counts: Default::default(),
         };
         (state, rx)
     }
diff --git a/crates/freshell-ws/src/reconcile_freshagent.rs b/crates/freshell-ws/src/reconcile_freshagent.rs
index 0818c4e23..402a44d5b 100644
--- a/crates/freshell-ws/src/reconcile_freshagent.rs
+++ b/crates/freshell-ws/src/reconcile_freshagent.rs
@@ -111,11 +111,12 @@ pub async fn build_snapshot(
         let presence = if live {
             FreshAgentPresence::Live
         } else {
-            // Exhaustive match, NO catch-all (B1 hardening: when B1 adds
-            // E::ProviderUnavailable this goes non-exhaustive — add the
-            // pre-decided arm `E::ProviderUnavailable => FreshAgentPresence::Unknown`).
+            // Exhaustive match, NO catch-all (B1 hardening). ProviderUnavailable
+            // arm is the B4 pre-decision (V9/A12, module doc above): conservative
+            // respawn-with-cap via Unknown, never dead_session.
             match state.session_existence.exists(&sref.provider, &session_id) {
                 E::Present => FreshAgentPresence::OnDisk,
+                E::ProviderUnavailable => FreshAgentPresence::Unknown,
                 E::Absent => {
                     if state
                         .session_existence
diff --git a/crates/freshell-ws/src/terminal.rs b/crates/freshell-ws/src/terminal.rs
index b6cef9a29..6bff79f64 100644
--- a/crates/freshell-ws/src/terminal.rs
+++ b/crates/freshell-ws/src/terminal.rs
@@ -2342,21 +2342,18 @@ async fn handle_pane_reconcile(
     } else {
         None
     };
-    let deps = crate::reconcile::ReconcileDeps {
-        registry: &state.registry,
-        identity: &state.identity,
-        existence: state.session_existence.as_ref(),
-        fresh_agent: fresh_agent_snapshot.as_ref(),
-    };
     // §8 frame-level failure: a panicking derivation (poisoned lock) must
     // surface as an explicit error frame, never silence. The deps are rebuilt
     // per derivation so nothing borrowed for the pure read is ever held
-    // across the deferral await below.
+    // across the deferral await below. The fresh-agent snapshot is NOT
+    // rebuilt — it was built once above (rebuilding would double-burn the
+    // respawn counter; V9 §3.6) and each rebuilt deps borrows the same one.
     let derive = || {
         let deps = crate::reconcile::ReconcileDeps {
             registry: &state.registry,
             identity: &state.identity,
             existence: state.session_existence.as_ref(),
+            fresh_agent: fresh_agent_snapshot.as_ref(),
         };
         std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
             crate::reconcile::derive_verdicts(&deps, &request.panes)
diff --git a/crates/freshell-ws/tests/common/mod.rs b/crates/freshell-ws/tests/common/mod.rs
index c8b2672af..f3b38e8b4 100644
--- a/crates/freshell-ws/tests/common/mod.rs
+++ b/crates/freshell-ws/tests/common/mod.rs
@@ -300,6 +300,7 @@ pub async fn spawn_server_with_specs_and_activity(
         activity: Some(activity_hub.clone()),
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
         reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
+        fresh_agent_respawn_counts: Default::default(),
     };
 
     let router = freshell_ws::router(state);
@@ -378,6 +379,7 @@ pub async fn spawn_server_with_specs_activity_and_codex_locator(
         )),
         activity: Some(activity_hub.clone()),
         session_existence: std::sync::Arc::new(freshell_ws::existence::NoIndexProbe::default()),
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
         fresh_agent_respawn_counts: Default::default(),
     };
 
diff --git a/crates/freshell-ws/tests/pane_reconcile_freshagent.rs b/crates/freshell-ws/tests/pane_reconcile_freshagent.rs
index b5fb99daa..aab83c213 100644
--- a/crates/freshell-ws/tests/pane_reconcile_freshagent.rs
+++ b/crates/freshell-ws/tests/pane_reconcile_freshagent.rs
@@ -233,8 +233,10 @@ async fn spawn_server_with_probe(probe: Arc<StubProbe>) -> Server {
         config_fallback: None,
         amplifier_locator: None,
         opencode_locator: None,
+        codex_locator: None,
         activity: None,
         session_existence: probe,
+        reconcile_deferral_budget_ms: freshell_ws::reconcile::RECONCILE_DEFERRAL_BUDGET_MS_DEFAULT,
         fresh_agent_respawn_counts: Arc::clone(&respawn_counts),
     };
 

From fc6d909f142b4610d77c52d4372d170ea2c6fa73 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 10:55:21 -0700
Subject: [PATCH 79/87] fix: B1xB3 test seam - App reconcile-adoption mock
 gains getRecoveryInventory
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

B3's RecoveryOfferPanel calls getRecoveryInventory on App mount; B1's
App.reconcile-adoption.test.tsx mocks @/lib/api completely and predates
that export. Mirror the stub B3's own App tests use (recoverable: false).

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 test/unit/client/components/App.reconcile-adoption.test.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/test/unit/client/components/App.reconcile-adoption.test.tsx b/test/unit/client/components/App.reconcile-adoption.test.tsx
index 28ded5191..be7684df3 100644
--- a/test/unit/client/components/App.reconcile-adoption.test.tsx
+++ b/test/unit/client/components/App.reconcile-adoption.test.tsx
@@ -113,6 +113,7 @@ vi.mock('@/lib/api', () => ({
     post: vi.fn().mockResolvedValue({}),
   },
   fetchSidebarSessionsSnapshot: (options?: unknown) => fetchSidebarSessionsSnapshot(options),
+  getRecoveryInventory: async () => ({ recoverable: false, contentId: 'test', device: null, otherDevices: [], ledgerOnly: [] }),
   getTerminalDirectoryPage: (options?: unknown, init?: unknown) => getTerminalDirectoryPage(options, init),
   searchTerminalView: (terminalId: string, query: string, options?: unknown) => searchTerminalView(terminalId, query, options),
   isApiUnauthorizedError: (err: any) => !!err && typeof err === 'object' && err.status === 401,

From 6e59828fb7064f2436c880fa53a9e0e84e8956f2 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:29:47 -0700
Subject: [PATCH 80/87] fix: B1xB2 e2e seam - codex restore spec polls the
 pane's CURRENT terminal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Under B1's adopted client, the page.reload restore path can assign the
pane a transient pre-verdict terminal that the pane.reconcile respawn
fold then replaces (reconcileEpoch bump). The spec sampled the FIRST
truthy terminalId and polled that stale terminal's buffer forever. Poll
the pane's current terminalId each iteration instead - the assertion now
targets the converged state the verdict produces. Evidence: argv log
shows the resume spawn ('resume <id>' adjacent pair) and the converged
buffer carries 'codex: resumed session <id>'.

The transient pre-verdict create itself (fresh CLI spawn racing the
verdict on reload) is documented as a wave-C follow-up - not silently
fixed here.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../specs/codex-terminal-restore-rust.spec.ts      | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/test/e2e-browser/specs/codex-terminal-restore-rust.spec.ts b/test/e2e-browser/specs/codex-terminal-restore-rust.spec.ts
index 101c4ba1e..815cadcc6 100644
--- a/test/e2e-browser/specs/codex-terminal-restore-rust.spec.ts
+++ b/test/e2e-browser/specs/codex-terminal-restore-rust.spec.ts
@@ -328,10 +328,18 @@ test.describe('Codex Terminal Restore (Rust only)', () => {
           expect(leaf?.content?.terminalId).toBeTruthy()
         }).toPass({ timeout: 30_000 })
 
-        const restoredTerminalId: string | undefined = (await findLeafById(tabId!, positivePaneId))?.content?.terminalId
-        expect(restoredTerminalId).toBeTruthy()
+        // WAVE-B INTEGRATION NOTE (B1 reconcile adoption x this spec): on the
+        // page.reload path the pane's terminalId can change ONCE MORE after
+        // it first turns truthy -- a transient pre-verdict create is replaced
+        // when the pane.reconcile respawn verdict folds (reconcileEpoch bump,
+        // panesSlice.resetPaneForReconcileCreate). Poll the pane's CURRENT
+        // terminal each iteration instead of sampling the first terminalId,
+        // so the assertion targets the converged state the verdict produces.
         await expect.poll(async () => {
-          const buffer = await harness.getTerminalBuffer(restoredTerminalId)
+          const leaf = await findLeafById(tabId!, positivePaneId)
+          const currentTerminalId = leaf?.content?.terminalId
+          if (!currentTerminalId) return false
+          const buffer = await harness.getTerminalBuffer(currentTerminalId)
           const unwrapped = typeof buffer === 'string' ? buffer.replace(/\n/g, '') : ''
           return unwrapped.includes(`codex: resumed session ${associatedSessionId}`)
         }, { timeout: 20_000 }).toBe(true)

From 8d1f21b9c65094da0c55d5c3fb48ff5d43aeb211 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:31:07 -0700
Subject: [PATCH 81/87] test: narrow wave-A A2xA3 ledger pin for B4's
 kind:fresh-agent rows
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

B4 (freshagent-verdicts-resume) deliberately writes fresh-agent ledger
rows (paneKind: 'fresh-agent', pane_ledger.rs write_fresh_agent path),
obsoleting the wave-A pin 'fresh-agent UUID must never appear in the
pane ledger'. The invariant survives narrowed: the fresh-agent UUID may
appear ONLY as a kind:fresh-agent row (never a terminal row, and never
owning a liveTerminalId).

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../specs/wavea-interactions-rust.spec.ts      | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/test/e2e-browser/specs/wavea-interactions-rust.spec.ts b/test/e2e-browser/specs/wavea-interactions-rust.spec.ts
index a06372182..20d5818c8 100644
--- a/test/e2e-browser/specs/wavea-interactions-rust.spec.ts
+++ b/test/e2e-browser/specs/wavea-interactions-rust.spec.ts
@@ -409,11 +409,21 @@ test.describe('wave-A cross-lane interactions', () => {
           }, { timeout: 30_000 })
           .not.toBeNull()
 
-        // NO CROSS-TALK: the fresh-agent identity never leaks into the pane
-        // ledger (its store is the sidecar bridge index), and no ledger row
-        // was rebound to it.
+        // NO CROSS-TALK (wave-B update): B4 (freshagent-verdicts-resume) now
+        // DELIBERATELY writes kind:fresh-agent ledger rows (paneKind:
+        // 'fresh-agent', pane_ledger.rs), so the fresh-agent identity IS
+        // allowed in the ledger -- but ONLY as a fresh-agent row. The wave-A
+        // invariant this pin protects survives narrowed: the fresh-agent UUID
+        // must never appear as a TERMINAL row, and no terminal row was
+        // rebound to it.
         for (const row of rowsAfter) {
-          expect(row.sessionId, 'fresh-agent UUID must never appear in the pane ledger').not.toBe(FRESH_DURABLE)
+          if (row.sessionId === FRESH_DURABLE) {
+            expect(
+              row.paneKind,
+              'fresh-agent UUID may only appear as a kind:fresh-agent ledger row (B4), never a terminal row',
+            ).toBe('fresh-agent')
+            expect(row.liveTerminalId, 'fresh-agent ledger rows own no terminal').toBeFalsy()
+          }
         }
         // ...and nothing got quarantined by the boot scan.
         const allFiles = await listFiles(ledgerDir)

From 6f273362ab8795c5117a16050d0636330a36d46a Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:35:51 -0700
Subject: [PATCH 82/87] test(ws): pin B1xB4 seams - single-burn across warming
 deferral + ProviderUnavailable respawn mapping
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two integration-branch pins for the designed B1xB4 coexistence:
- warming_deferral_rederivation_burns_the_respawn_counter_once: a mixed
  terminal+fresh-agent request whose terminal pane triggers B1's bounded
  index-warming deferral re-derives ONCE reusing the fresh-agent snapshot
  (V9 3.6) - respawn counter burns exactly once (red-checked by mutating
  the burn to +2: test fails).
- provider_unavailable_existence_maps_to_respawn_with_cap: B1's new
  SessionExistence::ProviderUnavailable maps to B4's pre-decided arm
  (V9/A12): presence Unknown => respawn-with-cap, never dead_session and
  never the terminal arm's error{provider_unavailable}.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .../tests/pane_reconcile_freshagent.rs        | 69 +++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/crates/freshell-ws/tests/pane_reconcile_freshagent.rs b/crates/freshell-ws/tests/pane_reconcile_freshagent.rs
index aab83c213..d7d526bd4 100644
--- a/crates/freshell-ws/tests/pane_reconcile_freshagent.rs
+++ b/crates/freshell-ws/tests/pane_reconcile_freshagent.rs
@@ -501,6 +501,75 @@ async fn live_fresh_agent_session_gets_attach() {
     assert!(verdicts[0].get("terminalId").is_none());
 }
 
+/// WAVE-B B1xB4 seam pin (V9 3.6): a mixed request whose TERMINAL pane
+/// triggers B1's bounded index-warming deferral re-derives the verdicts ONCE
+/// -- and that re-derivation must REUSE the fresh-agent snapshot built at
+/// request start, so the fresh-agent respawn counter burns exactly once per
+/// request (never once per derivation).
+#[tokio::test]
+async fn warming_deferral_rederivation_burns_the_respawn_counter_once() {
+    let probe = std::sync::Arc::new(StubProbe::default());
+    probe.answers.lock().unwrap().insert(
+        ("codex".into(), "fa-once".into()),
+        SessionExistence::Present,
+    );
+    // The terminal claim "warm-x" stays unset => Unknown => error{index_warming}
+    // on BOTH derivations, so the deferral + re-derive path definitely runs.
+    let server = spawn_server_with_probe(probe).await;
+    let (mut ws, _ready) = connect(&server.url, true, true).await;
+    let verdicts = reconcile_request(
+        &mut ws,
+        serde_json::json!([
+            { "paneKey": "t", "kind": "terminal", "mode": "codex", "createRequestId": "cr-warm",
+              "sessionRef": {"provider": "codex", "sessionId": "warm-x"} },
+            { "paneKey": "fa", "kind": "fresh-agent",
+              "sessionRef": {"provider": "codex", "sessionId": "fa-once"} }
+        ]),
+    )
+    .await;
+    assert_eq!(verdicts[0]["verdict"], "error");
+    assert_eq!(verdicts[0]["reason"], "index_warming");
+    assert_eq!(verdicts[1]["verdict"], "respawn");
+    let counts = server.respawn_counts.lock().expect("counts lock");
+    assert_eq!(
+        counts.get(&("codex".into(), "fa-once".into())).copied(),
+        Some(1),
+        "the deferral's re-derivation must not double-burn the respawn counter"
+    );
+}
+
+/// WAVE-B B1xB4 seam pin: B1's `ProviderUnavailable` existence answer maps to
+/// the B4 pre-decision (V9/A12): presence Unknown => conservative
+/// respawn-with-cap -- never dead_session, and never the terminal arm's
+/// error{provider_unavailable} shape (fresh-agent liveness does not depend on
+/// the disk index being able to warm).
+#[tokio::test]
+async fn provider_unavailable_existence_maps_to_respawn_with_cap() {
+    let probe = std::sync::Arc::new(StubProbe::default());
+    probe.answers.lock().unwrap().insert(
+        ("codex".into(), "pu-1".into()),
+        SessionExistence::ProviderUnavailable,
+    );
+    let server = spawn_server_with_probe(probe).await;
+    let (mut ws, _ready) = connect(&server.url, true, true).await;
+    let verdicts = reconcile_request(
+        &mut ws,
+        serde_json::json!([
+            { "paneKey": "pu", "kind": "fresh-agent",
+              "sessionRef": {"provider": "codex", "sessionId": "pu-1"} }
+        ]),
+    )
+    .await;
+    assert_eq!(verdicts[0]["verdict"], "respawn");
+    assert_eq!(verdicts[0]["sessionRef"]["sessionId"], "pu-1");
+    let counts = server.respawn_counts.lock().expect("counts lock");
+    assert_eq!(
+        counts.get(&("codex".into(), "pu-1".into())).copied(),
+        Some(1),
+        "the answer counted against the respawn cap"
+    );
+}
+
 #[tokio::test]
 async fn duplicate_session_claims_dedupe_within_one_request() {
     let probe = std::sync::Arc::new(StubProbe::default());

From 857c9d4867f53174071ec57bf3cf6fbff7677f1b Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:41:55 -0700
Subject: [PATCH 83/87] fix(ws): B2xB4 misbind hardening - codex adoption
 refuses freshagent-known thread ids
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes B2 plan item 10 (residual A4 risk, fix assigned to B4's
territory): the freshagent codex sidecar writes rollouts into the SAME
$HOME/.codex/sessions root the locator walks, so a foreign same-cwd
rollout appearing after a pane's first Enter could misbind as a sole
candidate. B4's kind:fresh-agent ledger rows (durable-before-answer at
thread start) + the live fresh_codex session map are the exclusion
signals: adopt_codex_identity now refuses a thread id that is live in
fresh_codex or recorded as a fresh-agent ledger row.

TDD: located_freshagent_known_thread_is_rejected written first (red -
adoption succeeded), guard added (green - 7/7 codex_association tests).

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-ws/src/codex_association.rs | 101 ++++++++++++++++++++
 crates/freshell-ws/src/codex_identity.rs    |  28 ++++++
 2 files changed, 129 insertions(+)

diff --git a/crates/freshell-ws/src/codex_association.rs b/crates/freshell-ws/src/codex_association.rs
index 32ab6c3b3..7c5fbd5c9 100644
--- a/crates/freshell-ws/src/codex_association.rs
+++ b/crates/freshell-ws/src/codex_association.rs
@@ -622,4 +622,105 @@ mod tests {
         state.registry.kill("t1");
         let _ = std::fs::remove_dir_all(&home);
     }
+
+    /// B2xB4 misbind hardening (B2 plan item 10, fix assigned to B4's
+    /// territory): a freshagent codex sidecar writes rollouts into the SAME
+    /// `$HOME/.codex/sessions` root, so a later bare Enter on a codex
+    /// TERMINAL pane could adopt the fresh-agent thread as a sole candidate.
+    /// B4's kind:fresh-agent ledger rows (written durable-before-answer at
+    /// thread start) are the exclusion signal: the adoption tail must refuse
+    /// a freshagent-known thread id.
+    #[tokio::test]
+    async fn located_freshagent_known_thread_is_rejected() {
+        const TID: &str = "aaaabbbb-cccc-4ddd-8eee-ffff00001111";
+        let home = unique_temp_dir("freshagent-known");
+        let ledger_dir = unique_temp_dir("freshagent-known-ledger");
+        let (state, _rx) = state_with_locator_and_ledger(home.clone(), &ledger_dir);
+
+        // The fresh-agent thread's ledger row, exactly what B4's
+        // record_codex_binding persists at thread/start (durable BEFORE the
+        // create reply goes out).
+        state
+            .pane_ledger
+            .record_fresh_agent_binding(&crate::pane_ledger::FreshAgentBindingWrite {
+                provider: "codex",
+                session_id: TID,
+                mode: "freshcodex",
+                cwd: Some("/tmp"),
+                create_request_id: None,
+                model: Some("gpt-5"),
+                sandbox: None,
+                permission_mode: None,
+                effort: None,
+                supersedes: None,
+                now_ms: now_ms(),
+            })
+            .expect("seed fresh-agent ledger row");
+
+        // A real PTY "t1" (codex mode), armed.
+        let spec = freshell_platform::build_spawn_spec(
+            freshell_platform::ShellType::System,
+            freshell_platform::detect::HostOs::Linux,
+            false,
+            Some("/tmp"),
+            &freshell_platform::RealEnv,
+            &freshell_platform::RealFileProbe,
+            &std::collections::BTreeMap::new(),
+            None,
+            None,
+        );
+        state
+            .registry
+            .create(
+                &spec,
+                &std::collections::BTreeMap::new(),
+                "t1".to_string(),
+                "stream-1".to_string(),
+                "codex",
+                None,
+                None,
+                None,
+                None,
+            )
+            .expect("spawn a real shell for the test PTY");
+        state
+            .registry
+            .set_meta("t1", None, None, Some("codex".to_string()), None);
+
+        maybe_arm(&state, "t1", "codex", Some("/tmp"), None);
+        let locator = state.codex_locator.as_ref().unwrap().clone();
+        assert_eq!(locator.armed_count(), 1);
+
+        // Bare Enter opens the window, THEN the freshagent sidecar's rollout
+        // appears in the shared sessions root with the pane's own cwd -- the
+        // exact misbind shape from B2 plan item 10.
+        note_possible_submit(&state, "t1", "\r").await;
+        write_rollout(&home, "2026/07/26", TID, Some("/tmp"));
+
+        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+        for _ in 0..40 {
+            drain_and_associate(&state).await;
+            if locator.armed_count() == 0 {
+                break;
+            }
+            tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+        }
+
+        // Resolution HAPPENED (locator disarmed) -- so the refusal below is
+        // the adoption-tail guard's doing, not a locator no-op.
+        assert_eq!(locator.armed_count(), 0);
+        // Guard refused: the fresh-agent thread never binds to the terminal.
+        assert!(state.identity.session_ref_for("t1").is_none());
+        let dir_entry = state
+            .registry
+            .directory()
+            .into_iter()
+            .find(|e| e.terminal_id == "t1")
+            .unwrap();
+        assert!(dir_entry.resume_session_id.is_none());
+
+        state.registry.kill("t1");
+        let _ = std::fs::remove_dir_all(&home);
+        let _ = std::fs::remove_dir_all(&ledger_dir);
+    }
 }
diff --git a/crates/freshell-ws/src/codex_identity.rs b/crates/freshell-ws/src/codex_identity.rs
index 7bda3595b..ae91cf479 100644
--- a/crates/freshell-ws/src/codex_identity.rs
+++ b/crates/freshell-ws/src/codex_identity.rs
@@ -70,6 +70,34 @@ pub(crate) async fn adopt_codex_identity(state: &WsState, a: CodexAdoption<'_>)
             return false;
         }
     }
+    // B2xB4 misbind hardening (B2 plan item 10, fix enabled by B4's
+    // kind:fresh-agent ledger rows): the freshagent codex sidecar writes
+    // rollouts into the SAME sessions root the locator walks, so a foreign
+    // same-cwd rollout appearing after a pane's first Enter could misbind as
+    // a sole candidate. A thread id the server knows as a FRESH-AGENT
+    // session -- live in the fresh_codex session map, or recorded by B4's
+    // durable-before-answer ledger write at thread start -- must never bind
+    // to a terminal pane.
+    if state.fresh_codex.has_live_session(a.thread_id).await {
+        tracing::warn!(
+            terminal_id = %a.terminal_id,
+            thread_id = %a.thread_id,
+            "codex_adopt_rejected: freshagent_live_session"
+        );
+        return false;
+    }
+    if state
+        .pane_ledger
+        .lookup_by_session("codex", a.thread_id)
+        .is_some_and(|r| r.row.pane_kind.as_deref() == Some("fresh-agent"))
+    {
+        tracing::warn!(
+            terminal_id = %a.terminal_id,
+            thread_id = %a.thread_id,
+            "codex_adopt_rejected: freshagent_ledger_row"
+        );
+        return false;
+    }
     // Both identity homes -- different consumers (see opencode_association.rs:135-148).
     state.identity.upsert(
         a.terminal_id,

From 143bfd262bdc7e306e4f5ed4ddd70370cd51acda Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:45:22 -0700
Subject: [PATCH 84/87] docs: B3xB4 - mark freshopencode fresh-start limitation
 RESOLVED at waveB integration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

B4 rewrote opencode handle_create to rebind durable ses_* ids from
resumeSessionId/sessionRef (handle_create_resume; pinned by
create_with_resume_session_id_rebinds_the_durable_session). B3's kept
sessionRef passthrough (build-recovery-plan) means recovered
freshopencode panes now RESUME, exactly as the forward-compat note
anticipated. No test pinned the fresh-start behavior (the pin was this
doc's known-limitation note).

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 docs/plans/2026-07-26-recover-my-panes.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/plans/2026-07-26-recover-my-panes.md b/docs/plans/2026-07-26-recover-my-panes.md
index bb8026d84..a0267a167 100644
--- a/docs/plans/2026-07-26-recover-my-panes.md
+++ b/docs/plans/2026-07-26-recover-my-panes.md
@@ -48,7 +48,7 @@ Bound ledger rows whose `(provider, sessionId)` matches no **effective** pane re
 
 **D7 — Live sessions are surfaced, not resumed.** The inventory joins terminal-registry liveness (read-only): every response pane carries `live: true|false` (true iff its effective `(provider, sessionId)` is owned by a currently-Running terminal), and `ledgerOnly` excludes live rows. Panes with `live: true` are recreated WITHOUT resume — `build-recovery-plan` strips their `sessionRef`, they are never armed for terminal restore, and the offer panel notes that sessions still running on the server were left untouched; layout/cwd/mode are still recreated. Attach-to-live was considered and REJECTED: the attach path from a fresh browser is unverified and collides with Lane B1's attach-gate/reconcile ownership. Why this matters: the direct wire-`sessionRef` rung (`terminal.rs:1074-1078`) bypasses the ladder that holds every existing live-guard (`terminal.rs:1690-1745`), so a create carrying a live session's ref would silently spawn a duplicate `claude --resume S` while the original live PTY owns S — the repo's own corruption doctrine (`terminal.rs:1671-1674` "silently wrong"; `:933` one-JSONL-writer). The server-side liveness guard on that direct rung (Task 2b) is defense-in-depth: it closes the inventory-fetch→accept race that client-side stripping alone cannot.
 
-**Known limitation — freshopencode recovers fresh.** Recovered `freshopencode` panes start FRESH: `opencode_ws.rs` `handle_create` never reads `resume_session_id` — a pre-existing bug shared with `reopenClosedTab`, and `crates/freshell-freshagent` is Lane B4's fenced crate, so this lane cannot fix it. We keep the `sessionRef` passthrough anyway (forward-compatible: recovery becomes resume-correct the moment B4 fixes the handler), and Task 10 Step 3's final report must flag this to B4. Claude and codex fresh-agent resume are verified working (`claude.rs:224`, `codex.rs:369-391`).
+**Known limitation — freshopencode recovers fresh.** ~~Recovered `freshopencode` panes start FRESH: `opencode_ws.rs` `handle_create` never reads `resume_session_id` — a pre-existing bug shared with `reopenClosedTab`, and `crates/freshell-freshagent` is Lane B4's fenced crate, so this lane cannot fix it.~~ **RESOLVED at wave-B integration:** Lane B4 rewrote the opencode resume path — `handle_create` now rebinds a durable `ses_*` id from `resumeSessionId`/`sessionRef` (`opencode_ws.rs` resume_target → `handle_create_resume`; pinned by `create_with_resume_session_id_rebinds_the_durable_session`). The `sessionRef` passthrough this lane kept (forward-compatible by design) means recovered `freshopencode` panes now RESUME. Claude and codex fresh-agent resume were already verified working (`claude.rs:224`, `codex.rs:369-391`).
 
 ## Global Constraints
 

From 2b3b4fa9ac6095d5cacb1479d6e55887e2e3a12d Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:54:02 -0700
Subject: [PATCH 85/87] fix(freshagent): no-laundering guard on the REST
 send-keys binding write (B4 fast-follow)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The REST send-keys materialization site now gets the SAME all-blank
settings guard as record_codex_binding and claude's consumer arm
(V7/A10): a pane with no model/effort/cwd never persists a blank
snapshot - it would make was_recorded true while load_settings returns
None, arming a FALSE SETTINGS_RESET for a legitimately-default create.

TDD: rest_send_keys_materialization_skips_all_blank_settings written
first (red - blank binding was recorded), guard added (green; the
populated-settings sibling still passes).

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-freshagent/src/lib.rs | 67 ++++++++++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

diff --git a/crates/freshell-freshagent/src/lib.rs b/crates/freshell-freshagent/src/lib.rs
index ad92cfbfa..f9c9a9d51 100644
--- a/crates/freshell-freshagent/src/lib.rs
+++ b/crates/freshell-freshagent/src/lib.rs
@@ -1523,7 +1523,19 @@ async fn send_keys(
         // broadcast -- durable-before-answer), resolving the pane's placeholder id.
         // Without this site, REST-created sessions (the e2e seeding surface) never get
         // a resume record (V10 A13-N1). Opencode has no sandbox/permission concepts.
-        if let Some(sink) = state.identity_sink() {
+        // No-laundering guard (V7/A10, parity with `record_codex_binding` and
+        // claude's consumer arm): never persist an all-blank settings snapshot --
+        // it would make `was_recorded` true while `load_settings` returns None,
+        // arming a FALSE SETTINGS_RESET for a legitimately-default create.
+        let has_recordable_settings =
+            pane.model.is_some() || pane.effort.is_some() || pane.cwd.is_some();
+        if !has_recordable_settings {
+            tracing::debug!(
+                session = %durable_id,
+                "freshagent.opencode.rest_binding_skipped: all-blank settings snapshot"
+            );
+        }
+        if let (Some(sink), true) = (state.identity_sink(), has_recordable_settings) {
             if let Err(e) = sink
                 .record_binding(identity_sink::FreshAgentBindingUpsert {
                     provider: PROVIDER.into(),
@@ -2512,6 +2524,59 @@ mod tests {
         assert_eq!(b.settings.cwd.as_deref(), Some("/w"));
     }
 
+    /// WAVE-B fast-follow (B4 lane review): the REST send-keys materialization
+    /// site gets the SAME no-laundering guard as `record_codex_binding` /
+    /// claude's consumer arm (V7/A10): never persist an all-blank settings
+    /// snapshot -- it would make `was_recorded` true while `load_settings`
+    /// returns None, arming a FALSE SETTINGS_RESET for a
+    /// legitimately-default create on a later resume.
+    #[tokio::test]
+    async fn rest_send_keys_materialization_skips_all_blank_settings() {
+        let st = state();
+        let deps = ServeDeps {
+            spawner: Arc::new(NoopSpawner),
+            http: Arc::new(CreateCapableHttp),
+            ports: Arc::new(FakeAllocator),
+            events: Arc::new(NoopEventSource),
+        };
+        let manager = OpencodeServeManager::new(deps, ServeConfig::default());
+        manager
+            .ensure_started()
+            .await
+            .expect("healthy fake serve starts");
+        st.set_manager_for_test(manager).await;
+
+        let fake = Arc::new(identity_sink::FakeIdentitySink::default());
+        st.set_identity_sink(fake.clone());
+
+        // A REST-created pane with NO model/effort/cwd -- the all-blank shape.
+        st.panes.lock().expect("panes mutex").insert(
+            "pane-blank".to_string(),
+            PaneEntry {
+                placeholder_id: "freshopencode-b1".to_string(),
+                cwd: None,
+                model: None,
+                effort: None,
+                durable_id: None,
+            },
+        );
+
+        let mut headers = HeaderMap::new();
+        headers.insert("x-auth-token", "tok".parse().unwrap());
+        let _resp = send_keys(
+            State(st.clone()),
+            Path("pane-blank".to_string()),
+            headers,
+            Json(json!({ "text": "hello", "timeout": 0 })),
+        )
+        .await;
+
+        assert!(
+            fake.bindings.lock().unwrap().is_empty(),
+            "an all-blank settings snapshot must never be persisted (V7/A10 no-laundering guard)"
+        );
+    }
+
     // -- Batch D PR-6: rich transcript items for the opencode snapshot endpoint --
 
     #[test]

From acf8fe997b43e107121bbd5904026b0fde25298a Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:57:08 -0700
Subject: [PATCH 86/87] fix(pwa): first SW claim never reloads - closes B3's
 first-boot offer/reload race
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

sw.js does install -> skipWaiting -> clients.claim, so on FIRST boot the
controllerchange fires on a page that was never controlled. The
unconditional stale-client reload raced B3's recovery offer: by the time
the reload landed, the auto shell tab had persisted a layout,
hadPersistedLayoutAtBoot flipped true on the reloaded boot, and the
offer was permanently lost. Only a genuine update swap (controller
already existed at registration) reloads now.

TDD: first-claim-no-reload test written first (red - reload fired);
guard added (green, 6/6); the update-swap reload test sharpened to seed
an existing controller.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 src/lib/pwa.ts                     | 13 +++++++++
 test/unit/client/pwa-shell.test.ts | 46 +++++++++++++++++++++++++++++-
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/src/lib/pwa.ts b/src/lib/pwa.ts
index d42639949..36a20e53f 100644
--- a/src/lib/pwa.ts
+++ b/src/lib/pwa.ts
@@ -21,8 +21,21 @@ export function registerServiceWorker(options?: RegisterServiceWorkerOptions): v
     // Ignore sessionStorage access failures.
   }
 
+  // First-boot guard (wave-B B3 fast-follow): when the page was NOT already
+  // controlled, the first controllerchange is the service worker's initial
+  // claim (install -> skipWaiting -> clients.claim in sw.js), not an update
+  // swap. Reloading there races the first-boot recovery offer: by the time
+  // the reload lands, the auto shell tab has persisted a layout, so
+  // hadPersistedLayoutAtBoot flips true on the reloaded boot and the offer
+  // is permanently lost. Only a genuine update (controller already existed)
+  // reloads stale clients.
+  let hadController = !!navigator.serviceWorker.controller
   let reloading = false
   const onControllerChange = () => {
+    if (!hadController) {
+      hadController = true
+      return
+    }
     if (reloading) return
     reloading = true
     try {
diff --git a/test/unit/client/pwa-shell.test.ts b/test/unit/client/pwa-shell.test.ts
index 5a043ee79..215377d70 100644
--- a/test/unit/client/pwa-shell.test.ts
+++ b/test/unit/client/pwa-shell.test.ts
@@ -110,7 +110,7 @@ describe('PWA shell registration', () => {
     })
   })
 
-  it('reloads once when a new service worker takes control', () => {
+  it('reloads once when a new service worker takes control of an already-controlled page', () => {
     const register = vi.fn().mockResolvedValue({ update: vi.fn().mockResolvedValue(undefined) })
     const addEventListener = vi.fn()
     const handlers: Record<string, EventListener> = {}
@@ -122,6 +122,9 @@ describe('PWA shell registration', () => {
       writable: true,
       value: {
         register,
+        // The page is ALREADY controlled -- this controllerchange is an
+        // UPDATE swap, the case the stale-client reload exists for.
+        controller: {},
         addEventListener: vi.fn((event: string, handler: EventListener) => {
           handlers[event] = handler
           addEventListener(event, handler)
@@ -144,6 +147,47 @@ describe('PWA shell registration', () => {
     expect(addEventListener).toHaveBeenCalledWith('controllerchange', expect.any(Function))
   })
 
+  it('does not reload on the first controllerchange of an uncontrolled page (first-boot claim)', () => {
+    // WAVE-B fast-follow (B3 lane review): on FIRST boot the SW's
+    // install -> skipWaiting -> clients.claim fires controllerchange on a
+    // page that was never controlled. Reloading there races the first-boot
+    // recovery offer: by the time the reload lands, the auto shell tab has
+    // persisted a layout, hadPersistedLayoutAtBoot flips true, and the
+    // offer is permanently lost. The first claim must NOT reload; only a
+    // real update swap (controller already existed) does.
+    const register = vi.fn().mockResolvedValue({ update: vi.fn().mockResolvedValue(undefined) })
+    const handlers: Record<string, EventListener> = {}
+    const reload = vi.fn()
+    const storage = createStorageMock()
+
+    Object.defineProperty(navigator, 'serviceWorker', {
+      configurable: true,
+      writable: true,
+      value: {
+        register,
+        // No controller: the page was NOT controlled when we registered.
+        controller: null,
+        addEventListener: vi.fn((event: string, handler: EventListener) => {
+          handlers[event] = handler
+        }),
+      },
+    })
+
+    Object.defineProperty(window, 'sessionStorage', {
+      configurable: true,
+      writable: true,
+      value: storage,
+    })
+
+    registerServiceWorker({ enabled: true, reload, storage })
+    // First claim: no reload.
+    handlers.controllerchange?.(new Event('controllerchange'))
+    expect(reload).not.toHaveBeenCalled()
+    // A LATER swap (a genuine update) still reloads.
+    handlers.controllerchange?.(new Event('controllerchange'))
+    expect(reload).toHaveBeenCalledTimes(1)
+  })
+
   it('clears the stale reload sentinel on startup', () => {
     const register = vi.fn().mockResolvedValue({ update: vi.fn().mockResolvedValue(undefined) })
     const storage = createStorageMock({ 'freshell.sw.controller-reload': '1' })

From d9b71f502190f40654585e9f4786acfa7f36ebba Mon Sep 17 00:00:00 2001
From: Dan Shapiro <3732858+danshapiro@users.noreply.github.com>
Date: Sun, 26 Jul 2026 12:04:33 -0700
Subject: [PATCH 87/87] fix(server): widen recovery-inventory D7 liveness join
 to match the create-rung guard (B3 fast-follow)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The D7 server guard on the direct wire-sessionRef rung checks BOTH
stores (identity-registry owner probed Running + the registry-row scan);
the inventory's live_session_keys checked only registry rows with
resume_session_id. A locator-adopted terminal (codex/opencode/amplifier)
holds its session in the identity registry while the row's resume id
stays unset, so the inventory offered it for resume and the accept died
on the guard. live_session_keys now joins the identity registry too
(live entries whose owning terminal probes Running), so the offer and
the guard agree.

TDD: live_session_keys_includes_identity_registry_bound_sessions +
retired/dead negative pin written first (red - signature/behavior),
join added (green; freshell-server 323/323).

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 crates/freshell-server/src/main.rs            |  1 +
 .../freshell-server/src/recovery_inventory.rs | 42 +++++++++++++--
 .../src/recovery_inventory_tests.rs           | 54 +++++++++++++++++++
 3 files changed, 93 insertions(+), 4 deletions(-)

diff --git a/crates/freshell-server/src/main.rs b/crates/freshell-server/src/main.rs
index 94ca6e956..b2607c799 100644
--- a/crates/freshell-server/src/main.rs
+++ b/crates/freshell-server/src/main.rs
@@ -854,6 +854,7 @@ async fn main() -> ExitCode {
                     .map(|h| h.join(".freshell").join("tabs-snapshots")),
                 ledger: std::sync::Arc::clone(&pane_ledger),
                 registry: registry.clone(),
+                identity: terminal_identity.clone(),
             },
         ))
         .merge(network::router(network_state))
diff --git a/crates/freshell-server/src/recovery_inventory.rs b/crates/freshell-server/src/recovery_inventory.rs
index e7fd72d38..d24f0c9bb 100644
--- a/crates/freshell-server/src/recovery_inventory.rs
+++ b/crates/freshell-server/src/recovery_inventory.rs
@@ -342,6 +342,10 @@ pub struct RecoveryInventoryState {
     pub snapshots_dir: Option<std::path::PathBuf>,
     pub ledger: std::sync::Arc<freshell_ws::pane_ledger::PaneLedger>,
     pub registry: freshell_terminal::TerminalRegistry,
+    /// The SAME shared identity registry the WS state receives — read-only
+    /// here (the wave-B widened D7 liveness join: locator-adopted terminals
+    /// hold their session identity here, not on the registry row).
+    pub identity: freshell_ws::identity::TerminalIdentityRegistry,
 }
 
 #[derive(serde::Deserialize)]
@@ -411,7 +415,7 @@ async fn inventory_handler(
             }
         }
     };
-    let live = live_session_keys(&state.registry);
+    let live = live_session_keys(&state.registry, &state.identity);
     Json(build_inventory(unions, state.ledger.list_bindings(), live)).into_response()
 }
 
@@ -419,8 +423,20 @@ async fn inventory_handler(
 /// currently-Running terminal row — the same row fields the ladder's A13 guard
 /// reads (`terminal.rs:1690-1745`: mode + resume session id, status ==
 /// `TerminalRunStatus::Running`).
-fn live_session_keys(registry: &freshell_terminal::TerminalRegistry) -> HashSet<(String, String)> {
-    registry
+///
+/// WAVE-B widening (B3 lane review): the D7 create-rung server guard checks
+/// BOTH stores — the identity-registry owner (probed Running) AND the
+/// registry-row scan. A locator-adopted terminal (codex/opencode/amplifier)
+/// holds its session in the identity registry while the row's
+/// `resume_session_id` stays unset, so the registry-row scan alone under-counts
+/// live sessions: the inventory would offer them for resume and the accept
+/// would die on the server guard. Join both stores here so the offer and the
+/// guard agree.
+fn live_session_keys(
+    registry: &freshell_terminal::TerminalRegistry,
+    identity: &freshell_ws::identity::TerminalIdentityRegistry,
+) -> HashSet<(String, String)> {
+    let mut keys: HashSet<(String, String)> = registry
         .directory()
         .into_iter()
         .filter(|row| row.status == freshell_protocol::TerminalRunStatus::Running)
@@ -429,7 +445,25 @@ fn live_session_keys(registry: &freshell_terminal::TerminalRegistry) -> HashSet<
                 .filter(|s| !s.is_empty())
                 .map(|sid| (row.mode, sid))
         })
-        .collect()
+        .collect();
+    // Identity-registry side of the join: live (non-retired) entries whose
+    // owning terminal probes Running — mirrors the guard's
+    // `identity_owner_live` arm.
+    for entry in identity.list() {
+        let (Some(provider), Some(session_id)) = (entry.provider, entry.session_id) else {
+            continue;
+        };
+        if session_id.is_empty() {
+            continue;
+        }
+        let owner_running = registry
+            .probe(&entry.terminal_id)
+            .is_some_and(|r| r.status == freshell_protocol::TerminalRunStatus::Running);
+        if owner_running {
+            keys.insert((provider, session_id));
+        }
+    }
+    keys
 }
 
 fn read_foreign_unions(
diff --git a/crates/freshell-server/src/recovery_inventory_tests.rs b/crates/freshell-server/src/recovery_inventory_tests.rs
index 07938738b..d6a5e6231 100644
--- a/crates/freshell-server/src/recovery_inventory_tests.rs
+++ b/crates/freshell-server/src/recovery_inventory_tests.rs
@@ -84,6 +84,59 @@ fn binding_row(provider: &str, session_id: &str, state_parts: StateParts) -> Bin
     binding_row_at(provider, session_id, state_parts, 1000)
 }
 
+/// WAVE-B fast-follow (B3 lane review): the inventory's D7 liveness join must
+/// match the server guard's width (terminal.rs D7 live-guard: identity-registry
+/// owner check PLUS the registry-row scan). A locator-adopted terminal holds
+/// its session in the IDENTITY registry while the registry row's
+/// resume_session_id stays unset (fresh pane, never resumed) -- the inventory
+/// must still report that session live, or it gets offered for resume and the
+/// accept dies on the server guard instead of never being offered.
+#[test]
+fn live_session_keys_includes_identity_registry_bound_sessions() {
+    let registry = freshell_terminal::TerminalRegistry::new();
+    registry.register_headless(freshell_terminal::registry::HeadlessTerminal {
+        terminal_id: "t-live".into(),
+        stream_id: "s1".into(),
+        mode: "codex".into(),
+        resume_session_id: None, // fresh pane: row carries no resume id
+        create_request_id: None,
+        created_at: None,
+    });
+    let identity = freshell_ws::identity::TerminalIdentityRegistry::new();
+    identity.upsert("t-live", Some("codex"), Some("sess-live-1"), None, 0);
+
+    let keys = live_session_keys(&registry, &identity);
+    assert!(
+        keys.contains(&("codex".to_string(), "sess-live-1".to_string())),
+        "identity-registry-bound session of a Running terminal must be live"
+    );
+}
+
+/// Retired identity entries and identity entries whose terminal is not
+/// Running never widen the live set.
+#[test]
+fn live_session_keys_ignores_retired_and_dead_identity_entries() {
+    let registry = freshell_terminal::TerminalRegistry::new();
+    // No registry row at all for "t-gone" -- its identity entry must not count.
+    let identity = freshell_ws::identity::TerminalIdentityRegistry::new();
+    identity.upsert("t-gone", Some("codex"), Some("sess-gone"), None, 0);
+    // A retired entry on a live terminal must not count either.
+    registry.register_headless(freshell_terminal::registry::HeadlessTerminal {
+        terminal_id: "t-retired".into(),
+        stream_id: "s2".into(),
+        mode: "claude".into(),
+        resume_session_id: None,
+        create_request_id: None,
+        created_at: None,
+    });
+    identity.upsert("t-retired", Some("claude"), Some("sess-retired"), None, 0);
+    assert!(identity.retire("t-retired"));
+
+    let keys = live_session_keys(&registry, &identity);
+    assert!(!keys.contains(&("codex".to_string(), "sess-gone".to_string())));
+    assert!(!keys.contains(&("claude".to_string(), "sess-retired".to_string())));
+}
+
 #[test]
 fn empty_inputs_not_recoverable() {
     let out = build_inventory(vec![], vec![], no_live());
@@ -355,6 +408,7 @@ fn test_state(
             ledger_root,
         )),
         registry: test_registry(),
+        identity: freshell_ws::identity::TerminalIdentityRegistry::new(),
     }
 }