feat: reconciliation-on-connect handshake — Phases 1–2 (server + protocol, synthetic-client proof)

[danshapiro]

Reconciliation-on-connect handshake — Phases 1–2 (server + protocol, synthetic-client proof)

Implements docs/plans/2026-07-22-reconciliation-handshake-design.md Phase 1 and Phase 2 ONLY. Client adoption (Phase 3) and the §12 fresh-agent extension are explicitly out of scope.

Ship-alone safety (frozen client untouched — proven, not asserted)

Three independent gates keep the feature dark: hello capability → ready advertisement → result-only-in-response-to-request.

• handshake_advertises_pane_reconcile_only_when_negotiated (unit) + hello_without_capability_gets_unchanged_ready_and_with_it_gets_advertised (wire): a non-negotiating hello produces a ready with no capabilities key — clean-boot handshake bytes unchanged.
• frozen_client_create_path_is_unchanged_no_dedupe (wire): a non-negotiating connection's terminal.create keeps today's blind-spawn behavior byte-for-byte.
• non_negotiating_connection_gets_no_reconcile_response (wire): the request is accept-and-strip ignored off-capability.
• Full existing PW-RUST e2e + coordinated npm test suite green against this server build (§9.2 scenario 6, e2e-level inertness).

What landed (8 commits)

1. protocol — pane.reconcile.request/.result frames, paneReconcileV1 on hello + ready.capabilities, RECONCILE_TOO_LARGE/RECONCILE_UNAVAILABLE; inventory 27→28 / 52→53; protocolVersion stays 7.
2. terminal — createRequestId stamped atomically with the registry insert (field of the inserted row; concurrent insert/reader race test); newest_live_by_create_request_id / newest_by_create_request_id (newest generation first, live vs exited-inclusive); is_live/probe; always-on ws.reconcile.duplicate_pty backstop detector; public register_headless seam for cross-crate tests.
3. terminal — §7.5 respawn-generation cap (respawn_exhausted), healthy-generation reset.
4. ws — SessionExistenceProbe (Present/Absent/Unknown with the §5.1 defined semantics; unknown provider → Absent never Unknown) + pure derive_verdicts (§5.2/§5.3) with decision-table unit tests for rows 1, 2, 2b, 3, 4, 4b, 5, 6, 8, 9, 10 plus §9.1 tests 3/4a/9/11/12/14/15 and the Assumption-1 Phase-1 acceptance check (REST-created resume resolves identity via the registry-side resume_session_id across the crate boundary); capability negotiation; handle_pane_reconcile (cap → TOO_LARGE, catch_unwind → UNAVAILABLE, both carrying reconcileId).
5. ws — §5.4 single-flight create-dedupe (capability-gated adopt branch) + the wire-level §9.1 test file.
6. server — index-backed probe over the shared SessionIndex (peek()/is_fresh() sync accessors added to freshell-sessions); §9.1 test 13 real-index staleness (session written after a cold read resolves Present on re-query, no latched stale Absent); monotone ever_observed set gating dead_session vs fresh(identity_never_observed); main.rs wiring (NoIndexProbe fallback when no provider home).
7. ws/terminal — keyed-create reservation (begin/end_keyed_create + RAII guard) closing the check-then-spawn window between two truly concurrent creates for one key (the spawn takes ms; the row is only observable at insert).
8. e2e — test/e2e-browser/specs/reconcile-handshake-rust.spec.ts (§9.2, raw Node WebSocket synthetic client on the HARNESS-01 owned RustServer): restart → shell fresh / resumed CLI respawn with correct sessionRef → complete respawn → attach (doubles as WSL-restart equivalence + refreshed-browser analogue); observed-then-deleted session → explicit dead_session, disk untouched; two concurrent reconciling connections → exactly one live PTY per key (the council-blocker regression). All 3 green in 25.8s.

Verification evidence

• cargo test --workspace: green (61 suite results, 0 failures).
• cargo clippy --workspace --all-targets: no new warnings — every remaining warning verified present at origin/main (e.g. the TabsPushResponse large-variant warning exists at ec9970c, terminal.rs:1638).
• cargo fmt applied to all touched crates.
• Coordinated FRESHELL_TEST_SUMMARY="track1 handshake pre-PR" npm test: full-suite success exit=0 at HEAD 5de61ec, dirty:0.
• Playwright: npx playwright test ... reconcile-handshake-rust → 3 passed.

Open decision (recorded, not resolved)

• §8.0 retry mechanism (change #4a) is USER DECISION PENDING. This PR ships the design's documented placeholder: retry{reason:'index_warming', retryAfterMs:2000}. Adopting Sam's Option B later collapses row 5 into the existing RECONCILE_UNAVAILABLE path with no other table change.

Deferred (out of this track's scope)

• Phase 3 client adoption (§10) and Phase 4 convergence — including the §5.5 client-side createRequestId contract fixes (persistMiddleware.ts re-mint on hydrate; REST ingress minting none — REST creates pass None for the stamp today, documented at the call site).
• Incident-4 sidebar-grey quick win (assessment Option A): it is a client-side change (src/store/selectors/sidebarSelectors.ts open-state join) — another track owns client alerting/selector files, so per the wave brief it is noted here instead of implemented.
• §12 fresh-agent verdicts (explicitly fenced out of v1).
• §9.2 scenario 2 as a separate spec (double-restart with a kill between request and result) — the interrupted-round convergence shape is pinned at wire level (interrupted_create_converges_to_attach_on_the_next_reconcile); a dedicated e2e double-restart spec would be additive.

Environment notes for the orchestrator

• The shared disk hit 100% (0 bytes free) mid-run. Freed regenerable caches only: npm cache clean --force, uv cache clean, go clean -cache, and cargo clean of the stale, merged .worktrees/rust-tauri-port/target (34 GB, untouched since 2026-07-18). No live worktrees or processes were touched.