fix(terminals): preserve saved tmux sessions during workspace recovery

[Juliusolsson05]

A normal v2 workspace could lose its surviving terminals at startup: recovery read only the legacy workspace.sessions path, supplied an empty reference list, and classified managed tmux sessions as orphans.

This change collects references from every window through the canonical workspace decoder. It retains legacy v1 recovery and ordinary complete-empty cleanup. Discarded/duplicate windows, malformed session references, unreadable state, and read failures now withhold cleanup of unmatched sessions while retaining known-reference recovery. Startup reports inventory completeness, bounded issue counts, preserved-session counts, and a SHA-256 receipt identifying the exact workspace byte snapshot used for the decision. Failed reads carry no digest.

The decoder's completeness evidence is additive and is not persisted as a format change. Hidden/detached terminals are collected from saved metadata without copying renderer layout ownership rules. Registry failures still propagate as failures. WHY comments explain the distinction between partial restoration and authority to terminate a process.

Validation:

• Before the fix: existing 20 workspace tests passed; the first 25 composed startup cases exposed 21 failures under the extracted legacy startup reader, including lost v2 references and unsafe cleanup of partial inventory. Read-error cases additionally establish the new reporting contract, not a claim that every old read error killed a process.
• After the fix: 58 focused tests passed, including 36 new recovery cases using the real decoder and reconciliation with a fake tmux registry.
• npm run typecheck, npm run test:contract, npm run submodules:check (seven pins), npm run test:package, and git diff --check passed.
• Reviewed the full implementation diff and existing decoder/store call sites. Both CI gates passed on the current head d424520c (run 34716892305).

Limits: no live user tmux processes were touched. The build verified app entry points; runtime archives were not downloaded, so this is not a signed release or bundled-tmux smoke test. Preservation applies to the workspace read for this startup; durable quarantine/repair provenance across later saves remains part of #918. Unknown-owner routing (#920) is a separate slice.

Fixes #898
Refs #918

First implementation-loop slice of the program documented in #931. The branch begins with the focused implementation plan.

Program-plan conformance follow-up: commit d424520c adds the inventory snapshot receipt. The original implementation at ff9724de passed both CI gates. The follow-up passed the updated 58-test suite and type checking locally, and both CI gates passed on d424520c in run 34716892305. Review-ready; unmerged.

---

2026-09-19 update (release readiness)

• Refreshed onto main (93f60755). That was 340 commits, and the only conflict was in the imports of src/main/index.ts. Startup order is unchanged: state lock → tmux detection → recovery → SessionManager → store open.
• A real-fixture regression was added (b3961fba): the live v2 workspace.json the app persisted on 2026-09-19, sanitized (testing/fixtures/workspace-v2/, provenance README).
  • The reviewer ran the pre-PR reconcile with the old startup read against this file, and it kills the file's detached terminal. That is bug(terminals): read v2 workspace references before tmux reconciliation #898 reproduced on a real file.
  • The fixed path marks the terminal recoverable and still kills an injected proven orphan.
• Current state: 37 recovery cases, and 79/79 across src/main/tmux plus src/main/storage. CI was green on b3961fba (run 35426719774) and is re-running on the docs commit.
• Independent review: GREEN. Its two doc findings are fixed in 7da7a255:
  • the ARCHITECTURE.md §11 row no longer calls bug(terminals): read v2 workspace references before tmux reconciliation #898 open;
  • the plan status is updated.
• The remaining, narrower gap is pre-existing and not made worse: a complete but stale file (after a partial restore, a crash inside the autosave debounce, or two apps sharing state, bug(setup): two main processes share one state dir with no process lock (dev + installed app) #993). It is recorded in §11 and on refactor(sessions): make operation ownership and project membership authoritative #918, with the fix direction: never kill a session created after the inspected file's mtime.

🤖 Generated with Claude Code