fix(server): stop garbled escape sequences leaking into the terminal

[olafura]

What Changed

The server's terminal output now filters out the invisible terminal "control codes" that were leaking onto the screen as garbage (e.g. 2026;2$y2027;0$y2031;0$y2048;0$y1$r0m, 1;2c, 11;rgb:…) when you reopen or restore a terminal.

It handles the three families these codes come in — CSI (…$y/…$p), OSC (colour rgb:/?), and DCS ($r/$q, the 1$r0m piece in #1238) — always stripping the machine answers, stripping the questions from saved scrollback, and still passing the questions through during live use so the terminal can keep negotiating features normally. Both views are produced in a single parse of each output chunk.

Why

Programs and the terminal constantly exchange invisible control codes. Some are questions the program asks ("do you support this mode?", "where is the cursor?"); the terminal replies with an answer that is meant to be machine-readable, not shown.

The bug: the server was saving those questions into the terminal's scrollback history. When you reopened or restored a terminal (toggling it with Cmd+J, switching projects — see the repro in #1238), the history was replayed, the questions got asked again, and the answers got printed as visible junk at the shell prompt.

The fix removes the questions from saved history (so a replay can't trigger fresh answers) and removes stray answers from the live stream (normal program output never contains them). The web app and the TUI both render this same server-sanitized stream, so this fixes it in both.

UI Changes

No UI code changed — this is a server-side output filter. The visible symptom and a video are in #1238; the exact gibberish string from that report is now covered by a regression test.

Checklist

• This PR is small and focused (2 files, server-side; the bulk is tests)
• I explained what changed and why
• before/after screenshots for UI changes — N/A (no UI change; symptom + video are in [Bug]: gibberish rgb escape codes appear in terminal #1238)
• video for animation/interaction changes — N/A

Fixes the bug reported in #1238.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes core terminal byte handling for all sessions (history replay, live attach, and client→PTY writes); wrong stripping could break vim/tmux or drop legitimate output, though behavior is heavily tested.

Overview
Fixes #1238 by filtering terminal capability traffic so reopening or restoring a session no longer replays junk like 2026;2$y… at the shell prompt.

Output path: sanitizeTerminalChunkDual parses each PTY chunk once and builds two views—scrollback drops both host queries and terminal responses; the live stream drops only responses so the client emulator can still answer queries. Persisted history is sanitized on load (and on legacy migration), rewriting dirty logs from older builds. A flattened-residue pass strips echo fragments when the ESC introducer is already gone.

Input path: stripTerminalResponsesFromInput removes browser auto-replies (DECRPM, DA, CPR, OSC/DCS colour, etc.) before write reaches the PTY, breaking the echo/re-query feedback loop; focus events and real keystrokes are kept.

Most of the diff is regression tests for CSI/OSC/DCS, 8-bit C1, chunk boundaries, and ReDoS safety.

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

Note

Strip garbled terminal escape sequences from PTY output, history, and client input

• Introduces dual-mode sanitization (sanitizeTerminalChunkDual) that produces both a liveText (responses stripped, queries kept) and historyText (both stripped) in a single pass over each PTY output chunk.
• Adds stripTerminalResponsesFromInput to filter auto-generated terminal replies (CPR, DA, DSR, OSC color, DECRPSS) out of client writes before they reach the PTY; writes are skipped entirely if nothing remains.
• Adds stripFlattenedModeReplyResidue to remove reply fragments that appear as plain text at prompts (no ESC introducer), covering patterns like 2026;2$y and rgb:… runs.
• On load, existing history files are re-sanitized and persisted back clean, so legacy garble is removed on first access.
• Behavioral Change: PTY output events now carry sanitized liveText instead of raw data; history logs are rewritten on load; client input containing only terminal responses produces no PTY write.

^{Macroscope summarized cc465ea.}

Summary by CodeRabbit

• Tests

  • Added comprehensive test suite for terminal escape sequence sanitization across various control sequence types and edge cases.

• Refactor

  • Improved terminal output processing to efficiently handle both history and live stream views in a single pass, with enhanced escape sequence handling.

[coderabbitai]

📝 Walkthrough

Walkthrough

Replaces the single-view terminal escape-sequence sanitizer with sanitizeTerminalChunkDual, which parses one byte chunk and produces separate historyText and liveText outputs. Adds parameterized shouldStripCsiSequence, shouldStripOscSequence, and shouldStripDcsSequence helpers. Updates drainProcessEvents to use the dual parser and updates the public sanitizeTerminalHistoryChunk signature. Adds 134 lines of tests covering the new behavior.

Changes

Dual-view terminal sanitization

Layer / File(s)	Summary
Parameterized CSI/OSC/DCS strip helpers apps/server/src/terminal/Manager.ts	shouldStripCsiSequence gains a responsesOnly parameter for query-vs-reply discrimination; shouldStripOscSequence and shouldStripDcsSequence helpers are added with the same live-vs-history distinction.
sanitizeTerminalChunkDual dual-buffer parser apps/server/src/terminal/Manager.ts	New sanitizeTerminalChunkDual parses one byte chunk with a shared pending-sequence boundary, maintaining historyText and liveText buffers simultaneously and routing each CSI/OSC/DCS sequence to the appropriate buffer via the strip helpers.
Public API update and runtime drain wiring apps/server/src/terminal/Manager.ts	sanitizeTerminalHistoryChunk accepts an optional responsesOnly option and selects liveText vs historyText from the dual result. drainProcessEvents is updated to call sanitizeTerminalChunkDual, appending historyText to session history and publishing liveText as the streamed data payload.
sanitizeTerminalHistoryChunk test suite apps/server/src/terminal/Manager.test.ts	Adds a describe("sanitizeTerminalHistoryChunk") suite covering DECRPM/DECRQM stripping, normal CSI preservation, split-sequence buffering, responsesOnly live-vs-scrollback differences, 8-bit CSI/OSC introducers, incomplete 8-bit sequence buffering, and DCS DECRQSS/DECRPSS handling.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 Hop hop through the escape bytes I go,
Two buffers now: one live, one for the show!
CSI queries hop left, replies hop right,
DCS and OSC sorted out just right.
The pending chunk waits snug in my pouch —
No replay glitch shall make the terminal grouch! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 44.44% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main fix: preventing garbled escape sequences from leaking into the terminal, which is the core objective.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description follows the template and clearly covers what changed, why, UI impact, and the checklist.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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]

Approvability

Verdict: Needs human review

2 blocking correctness issues found. This bug fix introduces substantial new terminal sanitization logic (~550 lines) with complex regex-based escape sequence handling that modifies runtime behavior for terminal input/output processing. Additionally, there are two unresolved medium-severity review comments identifying potential bugs in the sanitization logic that could cause incomplete fixes or unintended side effects.

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

[olafura]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Dismissing prior approval to re-evaluate 700a3e2

[olafura]

Addressed the code-review findings (all in apps/server/src/terminal/Manager.ts):

1. DCS DECRPSS not stripped from client input — added \x1bP[01]?$r…ST to the input filter so the browser's status-string replies are dropped before they reach the PTY, not just CSI/OSC replies.
2. Bare DA query over-matched on input — the secondary/primary DA pattern now requires parameters (\x1b[[?>][0-9;]+c), so a user/app's bare \x1b[c / \x1b[>c query is preserved while the …;…c reply is still stripped.
3. Flattened DECRPSS residue not stripped from history — the flattened-residue cleaner now recognizes 1$r0m-style runs (echoed status-string replies with the ESC/P/ST framing already stripped by the terminal).
4. Residue guard skipped c-only / $r runs — the fast-path guard now also triggers on $r, so command-only and status-string residue runs aren't skipped.

Validated each fix against the real byte forms and the captured #1238 log. Added permanent tests: an input-strip suite (stripTerminalResponsesFromInput drops the auto-reply/focus flood, keeps keystrokes, arrows, Ctrl-C, CPR, and bare DA/DSR queries) and a flattened-DECRPSS history assertion. pnpm --filter t3 typecheck, the terminal suite (68 passing), and lint are green. Squashed into the single commit and rebased on upstream/main.

[olafura]

On the latest round:

Cursor — "Flattened garble splits across chunks" (Medium). Confirmed the mechanism: stripFlattenedModeReplyResidue runs per output chunk, so a flattened reply (the ESC introducer is already gone, so the pending-escape buffer can't hold it) that a PTY read splits mid-token — 2026;2 then $y — has both halves written to history live.

I investigated a cross-chunk carry (hold back a trailing partial token, prepend to the next chunk) and validated it against the ~30 real captured terminal logs. It cleanly handles the common case but is not complete — a split before the first ; (2026 | ;2$y) still leaks, and making it complete requires a streaming residue state machine (an unbounded line buffer, since flattened replies aren't newline-delimited and progress bars redraw with \r). Shipping a partial carry adds real complexity and a new pending-state semantic for a sub-second cosmetic transient, so I've left it out.

The finding's actual persistence concern — "the same garbled scrollback can return after restore" — is already mitigated by the load-time sanitize in this PR: the split halves land contiguously in the log, and readHistory() runs a whole-buffer sanitize on load that rejoins and strips the token. Verified two ways:

• New regression test self-heals a flattened token split across PTY chunks on the next reload: "prompt$ 2026;2" + "$y done" → written as "prompt$ 2026;2$y done" → sanitized on reload to "prompt$ done".
• Whole-file sanitize across all ~30 real logs leaves zero …;…$y / …;rgb:… / …$r…m residue.

So the residue is transient live-only (and the input-side strip already prevents the runaway echo loop that previously made it flood en masse), and it does not survive a restart.

The three findings from the prior round (DCS DECRPSS not stripped from input, bare DA query over-matched, flattened 1$r0m + $r guard) are already addressed in the current commit ab220ef4 — the bots reviewed 700a3e2c, before that push. pnpm --filter t3 typecheck, the terminal suite (69 passing), and lint are green; rebased on upstream/main.

[olafura]

Self-review (multi-angle, max effort) of 207f31eb

Ran a 10-angle adversarial review over the sanitizer diff and applied the clear-cut fixes (folded into this commit). Posting the findings for visibility.

Fixed

Sev	Finding	Fix
Critical	ReDoS — the (?:[0-9]+;)+rgb:[0-9a-fA-F/]+ alternative in FLATTENED_FRAGMENT/FLATTENED_REPLY_TOKEN backtracks catastrophically on program-controlled output. Measured ~40s on a 336 KB "<digits>;"-run that never reaches rgb:. It runs per output chunk on both views and on the whole history file at load, so a program printing such a run stalls the server event loop (DoS).	Pinned the colour alternative to the real OSC numbers — (?:1[012];|4;[0-9]+;)rgb: — removing the unbounded run. 40s → 18ms. Added a ReDoS regression test.
High	FLATTENED_REPLY_TOKEN's trailing n? swallowed the next character ("1;2$ynext" → "ext"), corrupting both history and live.	Removed the n?.
High	[01]$r[0-9;]*[a-zA-Z] greedily consumed a following digit/; run of legitimate text ("1$r0;12;34;Hello" ate through H).	Length-bounded the payload to {0,8}.
High	(?:[0-9]+;)+rgb: matched ordinary "<n>;rgb:…" program text (e.g. a CSS/colour dump), deleting it from the live stream.	Same OSC-number pin as the ReDoS fix.
High	The input filter stripped focus events (CSI I / CSI O), so a program that enabled focus reporting (DECSET ?1004 — vim, tmux) never received them. Focus events are user-action-driven and don't feed the redraw→requery loop, so stripping them was pure regression.	Dropped CSI I/CSI O from INPUT_TERMINAL_RESPONSE; added a test asserting focus events are forwarded.
Low	The input OSC/DCS reply patterns rejected the 8-bit ST (0x9c) terminator the output sanitizer accepts, so a 0x9c-terminated auto-reply leaked to the PTY and could re-arm the echo loop.	Added \x9c to the terminator alternation (and excluded it from the DCS body class).

Re-validated against ~30 real captured terminal logs: residue still fully stripped, in bounded time. 73 unit tests pass; typecheck + lint clean.

Considered and deliberately not changed

• Live stream runs the flattened-residue heuristic. Applying stripFlattenedModeReplyResidue to liveText is a heuristic over arbitrary program output; the fixes above shrink its false-positive surface to genuinely reply-shaped text. The deeper "strip only at the precise escape layer, since the input-side filter already breaks the loop" argument is valid, but removing the live strip would reintroduce the transient garbage this PR set out to remove. Kept it — happy to revisit if reviewers prefer the narrower approach.
• Bracketed-paste corruption. The input filter has no ESC[200~/ESC[201~ awareness, so pasted text containing escape sequences can be edited mid-paste. Real but needs a paste-mode state machine — out of scope here.
• Two-c-token run bridging ("1;2c 3;4c" → stripped): tightening risks under-stripping real DA-reply runs, and that literal shape in plain text is rare. Left as-is.
• Pre-existing efficiency (O(n²) history concat, dual-buffer build for identical views, per-chunk closures): not introduced by this diff; left alone.

No CLAUDE.md/AGENTS.md convention violations found.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 3 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 200b323. Configure here.}

[olafura]

Addressed the latest review round (2fd9f6eb)

Three OSC-4 / 8-bit-C1 findings — all fixed. (One, the framed-OSC-4 mangling, was a regression introduced by my earlier flattened-residue change; thanks for catching it.)

🟡 "Framed OSC 4 reports mangled" (r3466310762) — The escape walk keeps a framed OSC 4 palette report (only OSC 10/11/12 are stripped there), and the flattened pass then deleted its inner 4;<idx>;rgb:…, leaving a broken ESC ] … ST. Added a negative lookbehind (?<!\x1b\]|\x9d) to the flattened colour pattern so it only matches unframed residue, never a colour run still inside an intact OSC frame.

🟡 "OSC 4 replies reach PTY" (r3466310747) — stripTerminalResponsesFromInput now strips OSC 4 palette rgb: replies alongside OSC 10/11/12, breaking that arm of the echo loop at the source.

🟡 "Eight-bit C1 input bypasses filter" (r3466310756) — Every input pattern now accepts the 8-bit C1 introducer (\x9b/\x9d/\x90) as well as the 7-bit ESC form, and the pre-filter triggers on either — symmetric with the output walk. (Defense-in-depth: the browser emulator emits 7-bit, but the asymmetry is now closed.)

Validation: 76 unit tests pass (+4: framed-OSC-4 preserved, OSC-4 input, C1 input), typecheck + lint clean, and re-validated against the ~30 real captured logs (no residue survives, no empty ESC ] ST frames introduced). Rebased onto the latest upstream/main and force-pushed.

[macroscopeapp]

🟡 Medium terminal/Manager.ts:914

shouldStripOscSequence only matches OSC 10/11/12, so OSC 4;<idx>;? palette queries leak into history scrollback. The code elsewhere strips OSC 4;<idx>;rgb:… replies from client input, so replaying saved history containing an OSC 4 query causes the emulator to re-answer and reintroduce garbled prompt output.

-  // OSC 10/11/12 colour: `rgb:…` is a response; `?` is a query.
-  return responsesOnly ? /^(10|11|12);rgb:/.test(content) : /^(10|11|12);(?:\?|rgb:)/.test(content);
+  // OSC 4/10/11/12 colour: `rgb:…` is a response; `?` is a query.
+  return responsesOnly
+    ? /^(4;\d+|10|11|12);rgb:/.test(content)
+    : /^(4;\d+|10|11|12);(?:\?|rgb:)/.test(content);

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/terminal/Manager.ts around lines 914-917:

`shouldStripOscSequence` only matches OSC `10`/`11`/`12`, so OSC `4;<idx>;?` palette queries leak into history scrollback. The code elsewhere strips OSC `4;<idx>;rgb:…` replies from client input, so replaying saved history containing an OSC 4 query causes the emulator to re-answer and reintroduce garbled prompt output.

[macroscopeapp]

🟡 Medium terminal/Manager.ts:1007

FLATTENED_REPLY_RUN uses [\x07\r n] as a separator, where the literal space allows matching across ordinary text like "see 1;2c 2026;2$y now". This incorrectly deletes the entire span as terminal residue, even though 1;2c alone is ambiguous and the comment says such lone tokens should be preserved. Consider removing the literal space from the separator class.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/terminal/Manager.ts around line 1007:

`FLATTENED_REPLY_RUN` uses `[\x07\r n]` as a separator, where the literal space allows matching across ordinary text like `"see 1;2c 2026;2$y now"`. This incorrectly deletes the entire span as terminal residue, even though `1;2c` alone is ambiguous and the comment says such lone tokens should be preserved. Consider removing the literal space from the separator class.