feat(terminal): shell fallback retry + persisted sanitized history

[sambitcreate]

Summary

Two improvements adapted from studying t3code's terminal, building directly on the posix_spawnp fix in #20.

Stacks on #20. Target this branch's base (fix/terminal-posix-spawnp-mac) until #20 merges, then rebase onto main.

1. Shell-candidate fallback with retry-on-spawn-failure

A broken $SHELL (or a shell that vanishes after a Homebrew uninstall) no longer breaks terminal creation. The spawn path now walks an executable candidate list — $SHELL → /bin/zsh → /bin/bash → /bin/sh — and retries the next candidate on a retryable failure (posix_spawnp failed, ENOENT, not found). Genuine errors (EINVAL, out of fds) surface immediately and are never masked.

When the preferred shell is skipped and a fallback launches the terminal, the session reports preferredShellSkipped: true + resolvedShell, and the renderer shows a one-time toast: "Used /bin/zsh because $SHELL was unavailable."

Ported from t3code's trySpawn / isRetryableShellSpawnError (Manager.ts:567,1830).

2. Per-workspace persisted + sanitized history

Terminal output now survives close/reopen and app restart:

• New terminal-history.ts store — one debounced (40ms), line-capped (5000) log per workspace under <userData>/terminal-history/. File names are sha256(workspaceId) so worktree paths with separators are safe.
• Control-sequence sanitization — device-query/reply traffic is stripped before persisting and before the live snapshot is replayed, so a reopened terminal doesn't make the shell answer stale cursor-position/device-attribute queries and echo junk at the prompt. Stripped: CSI CPR (…R), DSR (…n), DA (…c), DECRQM/PM ($p/$y), XTVERSION (>q), Kitty keyboard (?u), DCS DECRQSS/XTGETTCAP, OSC color queries. Benign SGR/cursor sequences survive. This also fixes a latent bug in the existing snapshot() reconnect flow, which replayed raw (un-sanitized) output.
• Seed-on-open — create() reads the prior history and seeds the session buffer; the renderer's existing xterm-hydrate-from-snapshot shows it with no renderer change needed.

Ported from t3code's sanitizeTerminalHistoryChunk (Manager.ts:953).

Files

• main/services/terminal-history.ts — new store + sanitizer
• main/services/terminal-history.test.ts — new (12 tests)
• main/services/terminal.ts — retry loop, history wiring, resolvedShell/preferredShellSkipped
• main/services/terminal.test.ts — 5 new tests (retry, non-retryable, all-fail, happy path, history seeding)
• renderer/lib/ipc.ts — TerminalSession gains two fields
• renderer/components/terminal-drawer.tsx — fallback toast
• package.json — register both test files in test + test:coverage (they weren't in CI before)

Verification

• tsc --noEmit clean
• npm run lint clean
• 15/15 terminal tests + 12/12 history tests (27 total, all green)

Scope (deliberately out of scope)

No architecture change — Aiden's PTY lives in the main process so t3code's server/contract model doesn't map; we adapt the logic, not the architecture. In-place restart, subprocess-aware labels, clickable links, and a reconnect stream are the medium-effort items from the comparison and are natural follow-ups.

[pullfrog]

✅ No new issues found.

Reviewed changes — 7 commits across the shell-fallback retry loop, persisted sanitized history store, IPC contract additions, renderer toast, and test registration.

• Shell-candidate retry loop — trySpawnShell walks $SHELL → /bin/zsh → /bin/bash → /bin/sh, retries on retryable spawn errors, and surfaces non-retryable errors without masking. isRetryableShellSpawnError walks the full error + cause chain with cycle detection. The pre-filter via isExecutable avoids wasting spawn attempts on obviously-missing binaries.
• Persisted sanitized history — TerminalHistoryStore provides debounced per-workspace file persistence under <userData>/terminal-history/ with SHA-256 hashed filenames. sanitizeTerminalHistoryChunk strips device-query/reply sequences (CSI CPR/DSR/DA/DECRQM/XTVERSION/Kitty keyboard, DCS DECRQSS/XTGETTCAP, OSC color queries) while preserving benign SGR/cursor sequences, with chunk-boundary carry for incomplete sequences.
• Buffer seeding on open — create() seeds the session buffer from the history store so xterm rehydrates with prior output via the existing snapshot path. The sequence starts at 1 for restored sessions so the renderer's lastSequence guard correctly treats the seed as already-consumed.
• Renderer toast — a one-time toast.info when preferredShellSkipped is true, telling the user which fallback shell was used.
• Test coverage — 17 new tests (12 for the history store + 5 for the retry loop), all with tight exact-value assertions. Both test files registered in npm test and npm run test:coverage.

The design decisions are sound: the TerminalHistoryStoreLike interface decouples the service from the filesystem for testability, persist is best-effort (a terminal must never block on disk trouble), and pending half-sequences are intentionally not persisted (incomplete control sequences have no visual value).

  ^{｜ View workflow run ｜ Using DeepSeek Pro ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — 1 new commit since the prior review at 15ad2d2.

• Source-reading test assertion update — subagent-phase3-contract.test.ts:563 now searches for "const { pty," instead of "const pty = (this.options.spawnPty ?? spawn)(", reflecting the create() refactor that destructures trySpawnShell's return value. The ordering assertion (abort check → spawn → post-spawn check) is preserved.

  ^{｜ View workflow run ｜ Using DeepSeek Pro ｜ 𝕏}