ubume 0.1.0

package/src/core/terminal/frameLock.ts

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveUbumeDebugLogPath } from "../workspace/appData.js";
+import { isTerminalResizing } from "./terminalControl.js";
+
+export interface FrameLockOptions {
+  stdout: any;
+  env: Record<string, string | undefined>;
+}
+
+const resizeFrameCacheResetters = new WeakMap<object, () => void>();
+
+export function resetFrameLockForResize(stdout: object): void {
+  resizeFrameCacheResetters.get(stdout)?.();
+}
+
+/**
+ * Wraps the stdout stream to enforce frame-level deduplication, a flush lock,
+ * and width-safe row padding via ANSI clear-to-EOL (\x1b[K) injection.
+ */
+export function wrapStdoutWithFrameLock({
+  stdout,
+  env,
+}: FrameLockOptions) {
+  let lastFrame = "";
+  let isFlushing = false;
+  let debugLogStream: fs.WriteStream | null = null;
+
+  if (env.UBUME_RENDER_DEBUG === "1") {
+    try {
+      const logPath = env.UBUME_RENDER_DEBUG_FILE?.trim()
+        || resolveUbumeDebugLogPath(env);
+      const logDir = path.dirname(logPath);
+      if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+      }
+      debugLogStream = fs.createWriteStream(logPath, { flags: "a" });
+    } catch (e) {
+      // Gracefully fall back if logging fails (e.g. read-only filesystem)
+      void e;
+    }
+  }
+
+  const logDebug = (msg: string) => {
+    if (debugLogStream) {
+      debugLogStream.write(`${new Date().toISOString()} ${msg}\n`);
+    }
+  };
+
+  const originalWrite = stdout.write.bind(stdout);
+
+  // A terminal resize can make an otherwise identical Ink frame meaningful:
+  // rows reflow at a new width and height-driven spacer/layout changes must be
+  // written even when their source text did not change. src/index.tsx owns the
+  // single resize listener and invokes this reset through the exported helper.
+  resizeFrameCacheResetters.set(stdout, () => {
+    lastFrame = "";
+    logDebug("Frame cache reset: terminal resize");
+  });
+
+  stdout.write = (chunk: string | Uint8Array) => {
+    if (typeof chunk !== "string") {
+      return originalWrite(chunk);
+    }
+
+    // Task 7: Frame Lock
+    // Ensure only one render flush can write to stdout at a time.
+    if (isFlushing) {
+      logDebug("Frame dropped: lock active (concurrent flush)");
+      return true;
+    }
+
+    // Task 8: Full-frame Deduplication
+    // Skip if identical to last frame.
+    if (chunk === lastFrame) {
+      logDebug("Frame dropped: identical to last frame");
+      return true;
+    }
+
+    // Task 4: Width-Safe Injection
+    // Ensure every row clears to the end of the line. This fixes artifacts
+    // left behind when a shorter row replaces a longer row or when terminal
+    // wrapping occurs during resize.
+    //
+    // We inject \x1b[K before every newline and at the end of the frame.
+    // padding via \x1b[K injection.
+    // Only apply if the chunk is non-empty and doesn't look like a control-only 
+    // sequence (e.g. terminal title OSC).
+    let processed = chunk;
+    const isControlSequence = chunk.includes("\x1b]");
+    if (chunk.length > 0 && !isControlSequence) {
+      processed = chunk.replace(/\n/g, "\x1b[K\n");
+      if (!processed.endsWith("\x1b[K") && !processed.endsWith("\x1b[K\n")) {
+        processed += "\x1b[K";
+      }
+    }
+
+    isFlushing = true;
+    try {
+      lastFrame = chunk;
+      const resizing = isTerminalResizing();
+      logDebug(`Frame written: length=${processed.length} original=${chunk.length} resizing=${resizing}`);
+      return originalWrite(processed);
+    } finally {
+      isFlushing = false;
+    }
+  };
+
+  return stdout;
+}

package/src/core/terminal/inkRenderReset.ts

@@ -0,0 +1,123 @@
+import * as renderDebug from "../perf/renderDebug.js";
+
+/**
+ * Typed subset of the internal Ink class instance we reach into.
+ *
+ * `unsubscribeResize` is used at startup to disable Ink's competing resize
+ * handler (see src/index.tsx). The remaining fields are Ink's per-frame render
+ * caches; we reset them on the explicit /clear boundary so the next frame is
+ * written authoritatively from a clean baseline — exactly like the first frame
+ * after a cold startup — rather than diffed against pre-clear output.
+ *
+ * All fields are optional so the type also describes the minimal capability
+ * needed by callers that only disable resize, and so resolution degrades
+ * gracefully across Ink versions / test mocks.
+ */
+export interface InkRenderInstance {
+  unsubscribeResize?: () => void;
+  renderInteractiveFrame?: (output: string, outputHeight: number, staticOutput: string) => void;
+  lastOutput?: string;
+  lastOutputToRender?: string;
+  lastOutputHeight?: number;
+  lastTerminalWidth?: number;
+  fullStaticOutput?: string;
+  log?: { reset?: () => void };
+  throttledOnRender?: { cancel?: () => void };
+  throttledLog?: { cancel?: () => void };
+}
+
+export interface AppStdoutLike {
+  columns?: number;
+  rows?: number;
+}
+
+/**
+ * Resolve the real Ink class instance via Ink's internal WeakMap<stdout, Ink>.
+ * Returns null if resolution fails (e.g. different Ink version, test mocks).
+ *
+ * Bun doesn't resolve bare subpath imports like "ink/build/instances.js" so we
+ * resolve ink's main entry first, then derive the sibling path.
+ */
+export function resolveInkRenderInstance(stdout: object): InkRenderInstance | null {
+  try {
+    const { createRequire } = require("node:module");
+    const req = createRequire(import.meta.url);
+    const inkMain = req.resolve("ink");
+    const instancesPath = inkMain.replace(/index\.js$/, "instances.js");
+    const instances = req(instancesPath);
+    const weakMap: WeakMap<object, InkRenderInstance> =
+      instances.default ?? instances;
+    return weakMap.get(stdout) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export interface ResetInkOutputOptions {
+  instance: InkRenderInstance | null;
+  /** Current terminal column count, used to reseat lastTerminalWidth. */
+  columns?: number;
+}
+
+/**
+ * Reset Ink's render-state caches to the fresh-startup baseline.
+ *
+ * Call this immediately AFTER the terminal has been physically cleared (e.g. by
+ * terminalControl.clearTranscript on /clear) and BEFORE the post-clear React
+ * render commits. It mirrors what a brand-new Ink instance looks like at cold
+ * startup: empty frame caches and zero previous height, so the next frame is
+ * authoritative and the subsequent resize math (Ink's renderInteractiveFrame /
+ * shouldClearTerminalForFrame) is evaluated against truthful state.
+ *
+ * This does NOT emit any clear/erase escape sequences itself — the terminal is
+ * already physically cleared, and Ink's log.reset() zeroes log-update's
+ * accounting without writing. Returns false (graceful no-op) if no live Ink
+ * instance is available.
+ */
+export function resetInkOutputForFreshFrame({ instance, columns }: ResetInkOutputOptions): boolean {
+  if (!instance) {
+    renderDebug.traceEvent("terminal", "clearRenderReset", { instanceResolved: false });
+    return false;
+  }
+
+  const before = {
+    lastOutputLength: instance.lastOutput?.length ?? 0,
+    lastOutputToRenderLength: instance.lastOutputToRender?.length ?? 0,
+    lastOutputHeight: instance.lastOutputHeight ?? 0,
+    fullStaticOutputLength: instance.fullStaticOutput?.length ?? 0,
+    lastTerminalWidth: instance.lastTerminalWidth,
+  };
+
+  // Drop any pending throttled render/log so a stale pre-clear frame can't be
+  // flushed after we reset the caches.
+  instance.throttledOnRender?.cancel?.();
+  instance.throttledLog?.cancel?.();
+
+  // Zero log-update's previousOutput/previousLineCount WITHOUT emitting escape
+  // sequences (the terminal was already physically cleared).
+  instance.log?.reset?.();
+
+  // Reset Ink's frame caches to the constructor/startup state.
+  instance.lastOutput = "";
+  instance.lastOutputToRender = "";
+  instance.lastOutputHeight = 0;
+  instance.fullStaticOutput = "";
+  if (typeof columns === "number" && Number.isFinite(columns)) {
+    instance.lastTerminalWidth = columns;
+  }
+
+  renderDebug.traceEvent("terminal", "clearRenderReset", {
+    instanceResolved: true,
+    columns,
+    before,
+    after: {
+      lastOutputLength: instance.lastOutput.length,
+      lastOutputToRenderLength: instance.lastOutputToRender.length,
+      lastOutputHeight: instance.lastOutputHeight,
+      fullStaticOutputLength: instance.fullStaticOutput.length,
+      lastTerminalWidth: instance.lastTerminalWidth,
+    },
+  });
+
+  return true;
+}

package/src/core/terminal/startupClear.ts

@@ -0,0 +1,20 @@
+export interface StartupClearOptions {
+  write: (chunk: string) => boolean | void;
+  /** True when --no-clear was passed on the CLI. */
+  noClear: boolean;
+  env: Record<string, string | undefined>;
+}
+
+/**
+ * Writes a full terminal clear (viewport + scrollback + cursor home) to stdout
+ * before the first Ink render. Skipped when --no-clear or UBUME_NO_CLEAR=1.
+ *
+ * Only call this from startApp() in TTY mode — never inside render loops.
+ */
+export function performStartupClear(options: StartupClearOptions): void {
+  if (options.noClear || options.env["UBUME_NO_CLEAR"] === "1") return;
+  // \x1b[2J: clear visible viewport
+  // \x1b[3J: clear scrollback buffer
+  // \x1b[H:  move cursor to top-left
+  options.write("\x1b[2J\x1b[3J\x1b[H");
+}

package/src/core/terminal/terminalCapabilities.ts

@@ -0,0 +1,100 @@
+export interface TerminalCapabilityInput {
+  stdinIsTTY: boolean;
+  stdoutIsTTY: boolean;
+  platform: NodeJS.Platform | string;
+  env: Record<string, string | undefined>;
+}
+
+export interface TerminalCapabilityResult {
+  supported: boolean;
+  reason: "supported" | "notty" | "unsupported-terminal";
+  message: string;
+  warning?: string;
+}
+
+const WINDOWS_SUPPORTED_TERM_PATTERNS = [
+  /^xterm/i,
+  /^screen/i,
+  /^tmux/i,
+  /^vt\d+/i,
+  /^ansi/i,
+  /^cygwin/i,
+  /^linux/i,
+];
+
+function hasSupportedWindowsTerminal(env: Record<string, string | undefined>): boolean {
+  const term = env.TERM ?? "";
+  const termProgram = env.TERM_PROGRAM ?? "";
+
+  if (env.WT_SESSION) return true;
+  if (env.ANSICON) return true;
+  if ((env.ConEmuANSI ?? "").toUpperCase() === "ON") return true;
+  if (termProgram.toLowerCase() === "vscode") return true;
+  if (termProgram.toLowerCase() === "hyper") return true;
+  if (termProgram.toLowerCase() === "jetbrains-jediterm") return true;
+
+  return WINDOWS_SUPPORTED_TERM_PATTERNS.some((pattern) => pattern.test(term));
+}
+
+export function getTerminalCapability(input: TerminalCapabilityInput): TerminalCapabilityResult {
+  if (!input.stdinIsTTY || !input.stdoutIsTTY) {
+    return {
+      supported: false,
+      reason: "notty",
+      message: "This UI requires an interactive terminal.",
+    };
+  }
+
+  // UBUME_FORCE_VT=1 bypasses terminal detection entirely — useful when the terminal
+  // doesn't advertise VT support through standard env vars but is actually compatible.
+  if (input.env.UBUME_FORCE_VT === "1") {
+    return {
+      supported: true,
+      reason: "supported",
+      message: "",
+    };
+  }
+
+  const term = (input.env.TERM ?? "").trim().toLowerCase();
+  if (term === "dumb") {
+    return {
+      supported: false,
+      reason: "unsupported-terminal",
+      message: "This terminal does not support the VT control sequences required by the Ubume UI. Use a VT-compatible terminal such as Windows Terminal or the VS Code terminal.",
+    };
+  }
+
+  if (input.platform !== "win32") {
+    return {
+      supported: true,
+      reason: "supported",
+      message: "",
+    };
+  }
+
+  // Windows-specific terminal detection below.
+  if (hasSupportedWindowsTerminal(input.env)) {
+    return {
+      supported: true,
+      reason: "supported",
+      message: "",
+    };
+  }
+
+  const message = "This terminal does not advertise VT control sequence support. Ubume will continue because modern Windows terminals usually support VT; set UBUME_REQUIRE_VT=1 to hard-fail when support is not detected.";
+
+  if (input.env.UBUME_REQUIRE_VT === "1") {
+    return {
+      supported: false,
+      reason: "unsupported-terminal",
+      message: "This terminal does not appear to support the VT control sequences required by the Ubume UI. Use Windows Terminal, the VS Code terminal, or another VT-compatible terminal, or set UBUME_FORCE_VT=1 to bypass this check.",
+    };
+  }
+
+  return {
+    supported: true,
+    reason: "supported",
+    message: "",
+    warning: message,
+  };
+}

package/src/core/terminal/terminalControl.ts

@@ -0,0 +1,169 @@
+import * as renderDebug from "../perf/renderDebug.js";
+import { APP_NAME } from "../../config/settings.js";
+import { setTerminalTitleLifecycleState, traceTerminalTitleSequences, writeGuardedTerminalOutput } from "./terminalTitle.js";
+
+export const TERMINAL_TITLE = APP_NAME;
+
+export const TERMINAL_SEQUENCES = {
+  // \x1b[2J clears the visible viewport; \x1b[3J clears scrollback.
+  hardRepaint: "\x1b[2J\x1b[H",
+  viewportClear: "\x1b[2J\x1b[H",
+  transcriptClear: "\x1b[2J\x1b[3J\x1b[H",
+  bracketedPasteEnable: "\x1b[?2004h",
+  bracketedPasteDisable: "\x1b[?2004l",
+  mouseEnable: "\x1b[?1000h\x1b[?1006h",
+  mouseDisable: "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?1015l",
+  title: `\x1b]0;${TERMINAL_TITLE}\x07\x1b]2;${TERMINAL_TITLE}\x07`,
+  alternateScreenEnable: "\x1b[?1049h",
+  alternateScreenDisable: "\x1b[?1049l",
+} as const;
+
+export type TerminalWrite = (chunk: string) => boolean | void;
+export type TerminalChannel = "stdout" | "stderr";
+
+// Tracks whether the terminal is currently in a live resize debounce.
+let terminalResizing = false;
+
+export function setTerminalResizing(resizing: boolean): void {
+  terminalResizing = resizing;
+}
+
+export function isTerminalResizing(): boolean {
+  return terminalResizing;
+}
+
+// Tracks current UI state kind for diagnostic assertions.
+let currentUIStateKind: string = "IDLE";
+
+export function setTerminalControlUIState(kind: string): void {
+  if (currentUIStateKind !== kind) {
+    renderDebug.traceEvent("terminal", "uiStateTransition", {
+      from: currentUIStateKind,
+      to: kind,
+    });
+    currentUIStateKind = kind;
+    setTerminalTitleLifecycleState(kind);
+  }
+}
+
+export function writeTerminalControl(
+  write: TerminalWrite,
+  channel: TerminalChannel,
+  source: string,
+  sequence: string,
+): boolean {
+  traceTerminalTitleSequences(sequence, {
+    source,
+    stream: channel,
+    origin: "ubume",
+    action: "allowed",
+    lifecycleState: currentUIStateKind,
+  });
+  renderDebug.traceTerminalWrite(channel, source, sequence);
+  const containsClearOrReset = sequence.includes("\x1b[2J")
+    || sequence.includes("\x1b[3J")
+    || sequence.includes("\x1bc")
+    || sequence.includes("\x1b[H");
+  const isStartupWrite = source.includes(":startup");
+  const isTranscriptClear = source.includes(":transcriptClear");
+  const isViewportClear = source.includes(":viewportClear");
+
+  // Aggressively block any clearing or reset sequences after startup,
+  // especially during active states, to prevent the UI from disappearing.
+  if (containsClearOrReset && !isStartupWrite && !isTranscriptClear && !isViewportClear) {
+    renderDebug.traceEvent("terminal", "blockedPostStartupClearOrReset", {
+      source,
+      uiStateKind: currentUIStateKind,
+      sequenceLength: sequence.length,
+      containsViewportClear: sequence.includes("\x1b[2J"),
+      containsScrollbackClear: sequence.includes("\x1b[3J"),
+      containsCursorHome: sequence.includes("\x1b[H"),
+      containsTerminalReset: sequence.includes("\x1bc"),
+    });
+    return true;
+  }
+
+  // Diagnostic: warn if a viewport-clearing sequence fires during streaming
+  // even if it claims to be from startup (which shouldn't happen).
+  if (
+    (currentUIStateKind === "RESPONDING" || currentUIStateKind === "THINKING")
+    && (sequence.includes("\x1b[2J") || sequence.includes("\x1b[3J"))
+  ) {
+    renderDebug.traceEvent("terminal", "unexpectedClearDuringStreaming", {
+      source,
+      uiStateKind: currentUIStateKind,
+      sequenceLength: sequence.length,
+      isStartupWrite,
+    });
+
+    if (!isStartupWrite && !isTranscriptClear) {
+      return true;
+    }
+  }
+
+  return writeGuardedTerminalOutput(write, sequence, {
+    source,
+    stream: channel,
+    origin: "ubume",
+    action: "allowed",
+    lifecycleState: currentUIStateKind,
+  });
+}
+
+export function traceTerminalClear(source: string, fields: Record<string, unknown>): void {
+  renderDebug.traceTerminalClear(source, fields);
+}
+
+export interface TerminalModeController {
+  write(sequence: string, source: string): boolean;
+  clearTranscript(source: string): void;
+  clearViewport(source: string): void;
+  setMouseReporting(enabled: boolean, source: string): void;
+  setBracketedPaste(enabled: boolean, source: string): void;
+  setAlternateScreen(enabled: boolean, source: string): void;
+  resetModes(): void;
+}
+
+export function createTerminalModeController(write: TerminalWrite): TerminalModeController {
+  let mouseReporting: boolean | null = null;
+  let bracketedPaste: boolean | null = null;
+  let alternateScreen: boolean | null = null;
+
+  const writeStdout = (sequence: string, source: string) =>
+    writeTerminalControl(write, "stdout", source, sequence);
+
+  return {
+    write: writeStdout,
+    clearTranscript(source) {
+      writeStdout(TERMINAL_SEQUENCES.transcriptClear, source.includes(":transcriptClear") ? source : `${source}:transcriptClear`);
+    },
+    clearViewport(source) {
+      writeStdout(TERMINAL_SEQUENCES.viewportClear, source.includes(":viewportClear") ? source : `${source}:viewportClear`);
+    },
+    setMouseReporting(enabled, source) {
+      if (mouseReporting === enabled) return;
+      mouseReporting = enabled;
+      writeStdout(enabled ? TERMINAL_SEQUENCES.mouseEnable : TERMINAL_SEQUENCES.mouseDisable, source);
+    },
+    setBracketedPaste(enabled, source) {
+      if (bracketedPaste === enabled) return;
+      bracketedPaste = enabled;
+      writeStdout(enabled ? TERMINAL_SEQUENCES.bracketedPasteEnable : TERMINAL_SEQUENCES.bracketedPasteDisable, source);
+    },
+    setAlternateScreen(enabled, source) {
+      if (alternateScreen === enabled) return;
+      alternateScreen = enabled;
+      writeStdout(enabled ? TERMINAL_SEQUENCES.alternateScreenEnable : TERMINAL_SEQUENCES.alternateScreenDisable, source);
+    },
+    resetModes() {
+      renderDebug.traceEvent("terminal", "resetModes", {
+        mouseReporting,
+        bracketedPaste,
+        alternateScreen,
+      });
+      mouseReporting = null;
+      bracketedPaste = null;
+      alternateScreen = null;
+    },
+  };
+}

package/src/core/terminal/terminalSanitize.ts

@@ -0,0 +1,147 @@
+// ─── terminalSanitize ─────────────────────────────────────────────────────────
+// Strips unsafe ANSI/control sequences from subprocess and user input.
+//
+// Two levels of sanitization are provided:
+//
+//  1. sanitizeTerminalOutput / sanitizeTerminalLines / sanitizeTerminalInput
+//     — Full strip: removes ALL escape sequences (OSC, CSI, DCS, etc.) plus
+//       non-printable control bytes.  Used for arbitrary subprocess output,
+//       user-typed text, and assistant deltas where we cannot trust the source.
+//
+//  2. sanitizeDiffOutput
+//     — Safe-passthrough mode for diff content that has already been classified
+//       as a code/diff segment by the markdown parser.  Strips dangerous
+//       sequences (cursor movement, screen clear, bracketed-paste toggle, OSC
+//       hyperlinks, etc.) but INTENTIONALLY preserves SGR colour-only sequences
+//       (e.g. \x1b[32m … \x1b[0m) so that raw diff colour codes from tools like
+//       `git diff --color=always` survive into the Ink layer.
+//       NOTE: The recommended rendering path still uses React/Ink theme-based
+//       colouring (no raw ANSI needed), so this helper is available for future
+//       use but diff colour is primarily applied via getDiffTone() tones.
+
+export interface SanitizeTerminalOptions {
+  preserveTabs?: boolean;
+  tabSize?: number;
+}
+
+const DEFAULT_TAB_SIZE = 2;
+
+// ── Dangerous sequence patterns (always stripped) ─────────────────────────────
+// OSC: Operating System Command — can set window titles, hyperlinks, etc.
+const OSC_SEQUENCE = /\u001B\][^\u0007\u001B]*(?:\u0007|\u001B\\)/g;
+// DCS/PM/APC: Device Control String and friends — rare but risky
+const DCS_PM_APC_SEQUENCE = /\u001B[PX^_][\s\S]*?\u001B\\/g;
+// CSI: Control Sequence Introducer — covers cursor movement, erase, colour, etc.
+const CSI_SEQUENCE = /\u001B\[[0-?]*[ -/]*[@-~]/g;
+// ESC + single intermediate — Fe sequences (e.g. ESC M = reverse index)
+const ESC_INTERMEDIATE_SEQUENCE = /\u001B[@-Z\\-_]/g;
+// C1 control codes (0x80–0x9F) — can masquerade as CSI openers on some terminals
+const SINGLE_C1_SEQUENCE = /[\u0080-\u009F]/g;
+// Remaining non-printable bytes after the above passes
+const DISALLOWED_CONTROL_BYTES = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
+
+// ── SGR-only colour-safe allowlist (used by sanitizeDiffOutput) ───────────────
+// Matches ONLY SGR (Select Graphic Rendition) sequences — the subset of CSI
+// that carries colour/style information and has no side-effects on terminal
+// state (no cursor movement, no erase, no mode changes).
+// Pattern: ESC [ <params> m  where <params> is digits/semicolons only.
+// We keep these sequences when the caller asserts the content is safe diff output.
+const SGR_COLOUR_SEQUENCE = /\u001B\[[\d;]*m/g;
+
+function normalizeTabs(text: string, preserveTabs: boolean, tabSize: number): string {
+  if (preserveTabs) return text;
+  return text.replace(/\t/g, " ".repeat(Math.max(1, tabSize)));
+}
+
+/** Strip all terminal escape sequences. */
+function stripTerminalSequences(raw: string): string {
+  return raw
+    .replace(OSC_SEQUENCE, "")
+    .replace(DCS_PM_APC_SEQUENCE, "")
+    .replace(CSI_SEQUENCE, "")
+    .replace(ESC_INTERMEDIATE_SEQUENCE, "")
+    .replace(SINGLE_C1_SEQUENCE, "");
+}
+
+/**
+ * Strip only the dangerous subset of terminal sequences, preserving SGR colour codes.
+ * Used for content we know is diff output and want to pass colour through.
+ * NOTE: Only call this on content that has already been classified as a safe diff
+ * segment — never on arbitrary subprocess or user input.
+ */
+function stripDangerousSequencesPreserveSGR(raw: string): string {
+  return raw
+    .replace(OSC_SEQUENCE, "")          // OSC: hyperlinks, titles — always strip
+    .replace(DCS_PM_APC_SEQUENCE, "")  // DCS/PM/APC — always strip
+    // Strip CSI sequences that are NOT pure SGR colour codes.
+    // First mark safe SGR sequences with a placeholder, strip all CSI,
+    // then restore the safe ones.
+    .replace(SGR_COLOUR_SEQUENCE, (match) => `\u0000SGR:${match}\u0000`)  // protect SGR
+    .replace(CSI_SEQUENCE, "")                                              // strip dangerous CSI
+    .replace(/\u0000SGR:(\u001B\[[\d;]*m)\u0000/g, "$1")                 // restore SGR
+    .replace(ESC_INTERMEDIATE_SEQUENCE, "")
+    .replace(SINGLE_C1_SEQUENCE, "");
+}
+
+function stripUnsafeControls(text: string): string {
+  return text.replace(DISALLOWED_CONTROL_BYTES, "");
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+export function sanitizeTerminalOutput(raw: string, options: SanitizeTerminalOptions = {}): string {
+  if (!raw) return "";
+  const preserveTabs = options.preserveTabs ?? false;
+  const tabSize = options.tabSize ?? DEFAULT_TAB_SIZE;
+
+  const withoutSequences = stripTerminalSequences(raw);
+  const normalizedBreaks = withoutSequences
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n");
+  const withoutUnsafeControls = stripUnsafeControls(normalizedBreaks);
+  return normalizeTabs(withoutUnsafeControls, preserveTabs, tabSize);
+}
+
+export function sanitizeTerminalInput(raw: string): string {
+  return sanitizeTerminalOutput(raw, { preserveTabs: false, tabSize: DEFAULT_TAB_SIZE });
+}
+
+export function sanitizeTerminalLines(lines: string[]): string[] {
+  return lines
+    .map((line) => sanitizeTerminalOutput(line))
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+}
+
+/**
+ * Sanitize diff output while preserving SGR colour escape sequences.
+ *
+ * This is intentionally less aggressive than sanitizeTerminalOutput so that
+ * diffs piped through `git diff --color=always` or similar tools retain their
+ * ANSI colour information.  Only safe SGR (colour/style) codes are preserved;
+ * all cursor-movement, erase, and other side-effecting sequences are stripped.
+ *
+ * Width measurement of the resulting text must account for the invisible ANSI
+ * bytes — use stripAnsiForMeasurement() on the string before measuring.
+ *
+ * Safety: Never call this on arbitrary subprocess or user input.  Only use it
+ * after the markdown parser has classified a segment as a code/diff block.
+ */
+export function sanitizeDiffOutput(raw: string): string {
+  if (!raw) return "";
+  const withSafrSgr = stripDangerousSequencesPreserveSGR(raw);
+  const normalizedBreaks = withSafrSgr
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n");
+  return stripUnsafeControls(normalizedBreaks);
+}
+
+/**
+ * Strip ALL ANSI sequences from a string purely for width measurement purposes.
+ * Use this when you need the visual width of a string that may contain SGR codes.
+ */
+export function stripAnsiForMeasurement(text: string): string {
+  return text
+    .replace(SGR_COLOUR_SEQUENCE, "")
+    .replace(DISALLOWED_CONTROL_BYTES, "");
+}