fix(terminal): polish pass — node-pty diagnostics, Ctrl+W guards, black flash, split grouping

[StiensWout]

Terminal polish pass

Five terminal fixes that share one theme: the terminal backend fails loudly instead of silently, and the terminal UI stops eating destructive or surprising interactions.

Fixes #4924
Fixes #2787
Addresses #5129

Server: node-pty load failures are loud and actionable

A broken node-pty install (missing toolchain, wrong Node ABI) died as a bare startup defect that headless logging could swallow — npx t3 exited cleanly with no output. The failure stays typed in the adapter, and the CLI entrypoint now renders its diagnostic to stderr (what node-pty is, the two usual causes, the reinstall steps) and forces a non-zero exit code.

This makes the failure diagnosable; it does not solve the underlying missing-toolchain/prebuild problem in #5129, and it overlaps with #5132 — happy to rebase on whichever lands first.

Server: spawn-helper exec-bit repair and diagnosis

When npm extracts node-pty without the exec bit on spawn-helper, every shell candidate fails with posix_spawnp failed and the final error read like no working shell existed on the machine. Now:

• the chmod repair retries instead of disabling itself after one failure, and is skipped entirely when the helper is already executable (so a read-only package store does not re-log the same warning on every spawn);
• executability is judged against the calling process's uid/gids rather than "any exec bit", since an owner-only helper is not executable for anyone else and FileSystem.access cannot test X_OK;
• the diagnosis is a typed SpawnHelperNotExecutableError carrying helperPath, and the shell-candidate fallback short-circuits on its tag rather than on message text.

Web + desktop: held Ctrl+W cannot close the window

The terminal close shortcut never called preventDefault in the terminal key handler, and after the last terminal closes, held-key auto-repeats resolve no command and leak to Electron's windowMenu close accelerator — one hold could close the window (and on Windows/Linux, quit the app). The web handler now prevents the default like its sibling shortcuts, and the desktop window drops auto-repeated CmdOrCtrl+W in before-input-event. Deliberate single presses still close terminals and windows as before.

Web: brand-new terminals no longer flash black

The ghostty surface appends an opaque (alpha: false) canvas to the drawer before awaiting webfonts and the WASM core, and an opaque backing store is pure black until the first paint. The canvas is now prefilled with the theme background as soon as the 2D context exists.

Web: bottom-bar splits stay in their group

The drawer's reconcile-against-server-metadata pass compared raw server session ids while the store filters suppressed (closed) ids. One stale server session defeated the "server list is lagging" guard on every local change: a fresh split's id is not server-known yet, so reconcile dropped it and the next metadata update re-added it as its own group. The guard decision is now a pure store helper that filters suppressed ids before comparing, with regression tests. The right panel never ran this reconcile pass, which is why splitting only misbehaved in the bottom bar.

Web: PTY and grid resize in lockstep, sequenced through the stream

Resizing a narrow pane left stranded fragments of the wrapped prompt above the live one. The PTY resize was trailing-debounced while the local grid reflowed immediately, so the shell's redraw sequences were computed for one width and interpreted at another; each mismatched redraw orphaned the previous prompt. The grid now requests the resize and applies it only when the PTY acknowledges — the acknowledgement arrives on the same socket after all old-width output, so every byte is interpreted at the width it was generated for. Verified in a live paired session: wrap-crossing resize sequences that previously stacked a fragment per redraw now leave a single correctly wrapped prompt.

Web: panel opens reserved, interrupted panel closes settled by metadata

Follow-ups from the re-check: the right-panel add/split paths now allocate against the in-flight reservation registry and open through the shared rollback helper, and an interrupted panel close parks its surface snapshot until authoritative session metadata either restores the terminal into its original surface (session survived) or drops it (session closed), instead of guessing.

Server: replayable query traffic stripped from terminal history

Reopening a terminal replays its history, and stored capability queries made the terminal answer again — the shell echoed the replies as visible junk at the prompt (the 2026;2$y…1$r0m / 1;2c / 11;rgb:… gibberish from #1238). The history sanitizer now also strips DECRQM/DECRPM ($p/$y), XTVERSION and kitty-keyboard queries, and DECRQSS/XTGETTCAP DCS traffic, while setters sharing final bytes (DECSTR, DECSCL, DECSCUSR, restore-cursor) survive. This prevents new junk at the source; residue already flattened into stored scrollback as plain text is deliberately left to #3508, which tackles that broader live-stream stripping.

Work done by Claude Fable 5 via Claude Code.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes span PTY spawn/exec-bit logic, terminal event ordering, and optimistic UI rollback across drawer and right panel; regressions could affect terminal open/close, resize timing, or split grouping, though coverage is strong in tests.

Overview
This PR tightens terminal backend failures and web/desktop terminal UX so broken installs and optimistic UI do not strand users.

Server: The CLI now writes typed startup defects (e.g. node-pty load) to stderr and sets a non-zero exit. node-pty spawn-helper repair retries chmod, judges exec against the caller’s uid/gids, and surfaces SpawnHelperNotExecutableError with a chmod fix instead of retrying every shell. Resize queues a flush sentinel so resize replies publish after old-width output. History sanitization strips more replayable CSI/DCS query traffic (DECRQM, XTVERSION, kitty keyboard, DECRQSS/XTGETTCAP) while keeping setters like DECSCUSR.

Web: The ghostty canvas is prefilled with the theme background and grid resize waits on PTY ack (single-flight with retry). Terminal UI state adds pending vs suppressed ids, reconcilableServerTerminalIds, and rollback via unsuppressTerminal / abandonPendingTerminal. Open reservations avoid id collisions; failed/interrupted closes restore drawer tabs or park panel snapshots until metadata settles (terminalPendingPanelCloses). Ctrl+W auto-repeat is swallowed at window and chat level; terminal close uses preventDefault in the surface.

Desktop: Electron blocks auto-repeated Cmd/Ctrl+W so held close shortcuts do not close the window after the last terminal unmounts.

^{Reviewed by Cursor Bugbot for commit 013841c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Fix terminal black flash, Ctrl+W auto-repeat, split grouping, and node-pty spawn diagnostics

• Fills the terminal canvas with the theme background color immediately after acquiring the 2D context, eliminating the black flash before fonts load
• Suppresses CmdOrCtrl+W auto-repeat events in both the Electron before-input-event handler and the web keydown handler, preventing accidental window/tab closure when holding the close shortcut as a terminal unmounts
• Delays the terminal grid resize until the PTY acknowledges the new dimensions, keeping rendering aligned with the shell's redrawn width
• Adds per-thread in-flight open reservations (terminalOpenReservations.ts) to prevent ID collisions across drawer and panel opens; failed opens abandon the optimistic ID and roll back any optimistic UI
• Records interrupted right-panel terminal closes as pending and restores the pane on failure via a new restoreTerminal action in the right-panel store
• Tracks pending terminal IDs in useTerminalUiStateStore so unconfirmed locally opened terminals stay visible across reconcile cycles; adds unsuppressTerminal and abandonPendingTerminal actions
• Surfaces a SpawnHelperNotExecutableError with a chmod remedy when node-pty spawn fails due to a non-executable spawn-helper, skipping shell retries and reporting diagnostics to stderr on startup
• Strips additional CSI/DCS query-reply sequences (DECRQM, DECRPM, XTVERSION, kitty-keyboard, DECRQSS, XTGETTCAP) from stored terminal history to reduce replay noise

^{Macroscope summarized 013841c.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3ecffecf-bd70-4a26-8764-8c074afff743

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Reviewed the Effect service changes in apps/server/src/terminal/NodePtyAdapter.ts (plus its test) against the service conventions. Two findings, both in the new spawn-failure diagnostics path.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One new finding in this revision. The previously raised points about the manufactured plain Error and the process-exit side effects in the adapter still stand and are not re-posted here.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Reviewed the terminal-polish changes for Effect service conventions. One leftover from the ChatView.tsx helper extraction; the earlier findings on NodePtyAdapter.ts/Manager.ts still stand and are not re-posted here.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One convention finding on the new SpawnHelperNotExecutableError declaration. The earlier feedback on error modeling and process-exit policy has been addressed.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant new terminal state management (pending/suppressed id tracking, async resize acknowledgment, new error handling paths) spanning server and client. While each fix addresses real issues, the aggregate introduces new coordination patterns and state concepts that warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[t3-code]

found four actionable issues in this pass.

[t3-code]

re-check: the original server, reconciliation, and held-shortcut fixes look good. 4 web edge cases remain.

[t3-code]

re-check on e72a: the 4 reported fixes are materially addressed, but 2 related web edge cases remain.

[t3-code]

rechecked at e38c250. the previous fixes are present, but 7 actionable edge cases remain. focused web tests and web/server typechecks pass.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8026b6a. Configure here.}