Harden terminal catch-up stream safety

[danshapiro]

Summary

This is the all-at-once terminal catch-up stream-safety implementation. It makes long-hidden terminal catch-up fast, loss-explicit, and safe across server replay batching, xterm parser semantics, attach races, side-effect parsing, stream identity, and WebSocket backpressure.

Major pieces:

• adds shared terminal WebSocket sending with serialized application payload budgeting, backpressure handling, send callbacks, and structured logs
• adds protocol v6 with mandatory terminal stream identity and terminalOutputBatchV1 gated batch output
• adds pre-sequence fragmentation, barrier-aware output batching, replay deque retention metadata, and stream rotation/retention-loss handling
• adds client parser-applied checkpoints, attach generation/write-scope fencing, stale callback rejection, gap/lost-range accounting, and quarantine timeout recovery
• adds deny-by-default terminal output side-effect gating for replay-sensitive paths
• adds visible-first terminal catch-up metrics plus a browser process-suspend stop/resume proof
• commits the architecture plan and evidence dossier under docs/superpowers/

Local proof on current HEAD

HEAD: 568befab7c9e7c44c6cc5a4e32aaaff2ad97b4a4

• npm run check passed through the coordinator on a clean worktree.
  • reusable baseline: full-suite|568befab7c9e7c44c6cc5a4e32aaaff2ad97b4a4|dirty:0|node:v22.21.1|linux|x64
  • client: 377 files / 3938 tests passed
  • server: 251 files / 3821 passed, 2 skipped
  • electron: 27 files / 276 passed
• npm run perf:audit:visible-first -- --output /tmp/freshell-terminal-catchup-audit-568befab.json --scenario terminal-reconnect-backlog --profile desktop_local passed.
  • artifact git commit: 568befab7c9e7c44c6cc5a4e32aaaff2ad97b4a4
  • dirty: false
  • scenario status: ok
  • focusedReadyMs: 946
  • maxRafGapMs: 16.568
  • terminalReplayMessageCount: 7
  • terminalReplaySerializedBytes: 38900
  • terminalParserAppliedLagMs: 206.365
  • terminalReplayGapCount: 0
  • terminalFullHydrateFallbackCount: 0
  • terminalSurfaceQuarantineCount: 0
  • terminalStaleGenerationRejectionCount: 0
  • terminalStoppedRetentionCoveredMs: 910
  • terminalStopResumeGapCount: 0
• npm run test:e2e:chromium -- test/e2e-browser/specs/terminal-background-freeze-catchup.spec.ts passed.
  • artifact: test-results/terminal-background-freeze-d47cd-t-silent-gaps-or-quarantine-chromium/terminal-background-freeze-catchup.json
  • stoppedDurationMs: 2502
  • wsBehavior: buffered_resumed
  • cdpCatchupOutputMessageCount: 13
  • pageCatchupOutputMessageCount: 13
  • outputGapCount: 0
  • quarantineCount: 0
  • hydrateFallbackCount: 0
  • staleGenerationRejectionCount: 0
• git diff --check passed.
• Worktree was clean before push.

Focused proof already run on the same code path before the final doc-only plan cleanup:

• focused client terminal suites: 5 files / 169 tests passed
• focused server/protocol terminal suites: 10 files / 205 tests passed

Final adversarial review result before the doc-only cleanup: NO BLOCKER. The reviewer specifically checked protocol v6 enforcement, server stream identity fail-closed paths, retention-loss stream retagging, client stale attach/stream rejection, invalid batch fail-closed behavior, and lost-range checkpoint blocking.

Browser acceptance scope

The local PR gate is the production-style visible-first audit plus the process-suspend stop/resume positive control on an isolated local server. Real Windows Chrome long-background soak remains useful release/user-acceptance evidence, but it is not a blocker for this PR; CDP freeze and Xvfb tab switching were previously shown not to prove stopped browser execution in this environment.