@golba98/codexa 1.0.1

package/src/core/providers/registry.ts

@@ -0,0 +1,21 @@
+import { AVAILABLE_BACKENDS, DEFAULT_BACKEND } from "../../config/settings.js";
+import { codexSubprocessProvider } from "./codexSubprocess.js";
+import { openaiNativeProvider } from "./openaiNative.js";
+import type { BackendProvider } from "./types.js";
+
+export const BACKEND_PROVIDERS: BackendProvider[] = [
+  codexSubprocessProvider,
+  openaiNativeProvider,
+];
+
+export function getBackendProvider(id: string): BackendProvider {
+  return (
+    BACKEND_PROVIDERS.find((provider) => provider.id === id) ??
+    BACKEND_PROVIDERS.find((provider) => provider.id === DEFAULT_BACKEND) ??
+    codexSubprocessProvider
+  );
+}
+
+export function listBackendSummaries(): string {
+  return AVAILABLE_BACKENDS.map((backend, index) => `  ${index + 1}. ${backend.label} (${backend.id})`).join("\n");
+}

package/src/core/providers/types.ts

@@ -0,0 +1,59 @@
+import type { AvailableBackend } from "../../config/settings.js";
+import type { ResolvedRuntimeConfig } from "../../config/runtimeConfig.js";
+import type { ProjectInstructions } from "../projectInstructions.js";
+import type { RunProgressSource, RunToolActivity } from "../../session/types.js";
+
+export interface BackendProgressUpdate {
+  id: string;
+  source: RunProgressSource;
+  text: string;
+}
+
+export type BackendAuthState = "delegated" | "api-key-required" | "coming-soon";
+
+export interface BackendRunHandlers {
+  onResponse: (response: string) => void;
+  onError: (message: string, rawOutput?: string) => void;
+  /** Called with each new structured thinking/progress update while the process is still running. */
+  onProgress?: (update: BackendProgressUpdate) => void;
+  /** Called with each new assistant content delta while the process is still running. */
+  onAssistantDelta?: (chunk: string) => void;
+  /** Called when the backend indicates the final assistant answer is complete and visible. */
+  onFinalAnswerObserved?: (response: string) => void;
+  /** Called when the backend starts or finishes a tool/shell action during a run. */
+  onToolActivity?: (activity: RunToolActivity) => void;
+  /** Called around backend child-process lifecycle boundaries. */
+  onProcessLifecycle?: (event: "before-spawn" | "spawned" | "exit" | "error" | "cleanup") => void;
+  /** Lightweight hooks used only by headless benchmark diagnostics. */
+  benchmarkHooks?: {
+    onProviderPromptPrepared?: (context: { policy: "raw" | "wrapped"; characterCount: number }) => void;
+    onProviderPrepStart?: () => void;
+    onProviderPrepComplete?: () => void;
+    onCodexProcessSpawned?: (context: { executable: string; argv: string[] }) => void;
+    onFirstStdout?: (observed?: boolean) => void;
+    onFirstStderr?: (observed?: boolean) => void;
+    onCodexProcessExit?: (exitCode: number | null) => void;
+    onCleanupStart?: () => void;
+    onCleanupComplete?: (context: { skipped: boolean }) => void;
+  };
+}
+
+export interface BackendProvider {
+  id: AvailableBackend;
+  label: string;
+  description: string;
+  authState: BackendAuthState;
+  authLabel: string;
+  statusMessage: string;
+  supportsModels: (model: string) => boolean;
+  run?: (
+    prompt: string,
+    options: {
+      runtime: ResolvedRuntimeConfig;
+      workspaceRoot: string;
+      projectInstructions?: ProjectInstructions | null;
+      promptPolicy?: "raw" | "wrapped";
+    },
+    handlers: BackendRunHandlers,
+  ) => () => void;
+}

package/src/core/terminal/terminalCapabilities.test.ts

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { getTerminalCapability } from "./terminalCapabilities.js";
+
+test("allows Windows Terminal", () => {
+  const result = getTerminalCapability({
+    stdinIsTTY: true,
+    stdoutIsTTY: true,
+    platform: "win32",
+    env: { WT_SESSION: "1" },
+  });
+
+  assert.equal(result.supported, true);
+  assert.equal(result.reason, "supported");
+  assert.equal(result.warning, undefined);
+});
+
+test("allows the VS Code terminal", () => {
+  const result = getTerminalCapability({
+    stdinIsTTY: true,
+    stdoutIsTTY: true,
+    platform: "win32",
+    env: { TERM_PROGRAM: "vscode" },
+  });
+
+  assert.equal(result.supported, true);
+  assert.equal(result.reason, "supported");
+  assert.equal(result.warning, undefined);
+});
+
+test("allows modern Windows TTY when TERM is missing but warns", () => {
+  const result = getTerminalCapability({
+    stdinIsTTY: true,
+    stdoutIsTTY: true,
+    platform: "win32",
+    env: {},
+  });
+
+  assert.equal(result.supported, true);
+  assert.equal(result.reason, "supported");
+  assert.match(result.warning ?? "", /continue/i);
+});
+
+test("CODEXA_FORCE_VT bypasses VT compatibility detection", () => {
+  const result = getTerminalCapability({
+    stdinIsTTY: true,
+    stdoutIsTTY: true,
+    platform: "win32",
+    env: { CODEXA_FORCE_VT: "1", TERM: "dumb" },
+  });
+
+  assert.equal(result.supported, true);
+  assert.equal(result.reason, "supported");
+  assert.equal(result.warning, undefined);
+});
+
+test("CODEXA_REQUIRE_VT hard-fails when Windows VT support is not detected", () => {
+  const result = getTerminalCapability({
+    stdinIsTTY: true,
+    stdoutIsTTY: true,
+    platform: "win32",
+    env: { CODEXA_REQUIRE_VT: "1" },
+  });
+
+  assert.equal(result.supported, false);
+  assert.equal(result.reason, "unsupported-terminal");
+  assert.match(result.message, /CODEXA_FORCE_VT=1/i);
+});
+
+test("rejects a dumb terminal even when it is interactive", () => {
+  const result = getTerminalCapability({
+    stdinIsTTY: true,
+    stdoutIsTTY: true,
+    platform: "linux",
+    env: { TERM: "dumb" },
+  });
+
+  assert.equal(result.supported, false);
+  assert.equal(result.reason, "unsupported-terminal");
+});
+
+test("rejects redirected or non-interactive output", () => {
+  const result = getTerminalCapability({
+    stdinIsTTY: true,
+    stdoutIsTTY: false,
+    platform: "linux",
+    env: { TERM: "xterm-256color" },
+  });
+
+  assert.equal(result.supported, false);
+  assert.equal(result.reason, "notty");
+  assert.match(result.message, /interactive terminal/i);
+});

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.",
+    };
+  }
+
+  // CODEXA_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.CODEXA_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 Codexa 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. Codexa will continue because modern Windows terminals usually support VT; set CODEXA_REQUIRE_VT=1 to hard-fail when support is not detected.";
+
+  if (input.env.CODEXA_REQUIRE_VT === "1") {
+    return {
+      supported: false,
+      reason: "unsupported-terminal",
+      message: "This terminal does not appear to support the VT control sequences required by the Codexa UI. Use Windows Terminal, the VS Code terminal, or another VT-compatible terminal, or set CODEXA_FORCE_VT=1 to bypass this check.",
+    };
+  }
+
+  return {
+    supported: true,
+    reason: "supported",
+    message: "",
+    warning: message,
+  };
+}

package/src/core/terminal/terminalControl.test.ts

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createTerminalModeController, setTerminalControlUIState, TERMINAL_SEQUENCES, writeTerminalControl } from "./terminalControl.js";
+
+test("mouse reporting enables only normal mouse tracking with SGR coordinates", () => {
+  let writes = "";
+  const controller = createTerminalModeController((chunk) => {
+    writes += chunk;
+  });
+
+  controller.setMouseReporting(true, "test");
+
+  assert.equal(writes, "\x1b[?1000h\x1b[?1006h");
+  assert.equal(TERMINAL_SEQUENCES.mouseEnable, "\x1b[?1000h\x1b[?1006h");
+  assert.doesNotMatch(writes, /\x1b\[\?1002h|\x1b\[\?1003h|\x1b\[\?1004h|\x1b\[\?1005h|\x1b\[\?1015h/);
+  assert.doesNotMatch(writes, /\x1b\[\?1049h|\x1b\[\?1049l|\x1b\[3J/);
+});
+
+test("mouse reporting cleanup disables broad modes defensively", () => {
+  let writes = "";
+  const controller = createTerminalModeController((chunk) => {
+    writes += chunk;
+  });
+
+  controller.setMouseReporting(false, "test");
+
+  assert.match(writes, /\x1b\[\?1000l/);
+  assert.match(writes, /\x1b\[\?1002l/);
+  assert.match(writes, /\x1b\[\?1003l/);
+  assert.match(writes, /\x1b\[\?1006l/);
+  assert.match(writes, /\x1b\[\?1015l/);
+});
+
+test("post-startup viewport clears are blocked except for transcript clear", () => {
+  let writes = "";
+  const write = (chunk: string) => {
+    writes += chunk;
+  };
+
+  writeTerminalControl(write, "stdout", "test:resize", TERMINAL_SEQUENCES.viewportClear);
+  assert.equal(writes, "");
+
+  writeTerminalControl(write, "stdout", "test:transcriptClear", TERMINAL_SEQUENCES.transcriptClear);
+  assert.equal(writes, TERMINAL_SEQUENCES.transcriptClear);
+  assert.match(writes, /\x1b\[3J/);
+});
+
+test("terminal controller exposes an intentional transcript clear with scrollback erase", () => {
+  let writes = "";
+  const controller = createTerminalModeController((chunk) => {
+    writes += chunk;
+  });
+
+  controller.clearTranscript("test");
+
+  assert.equal(writes, TERMINAL_SEQUENCES.transcriptClear);
+  assert.match(writes, /\x1b\[2J/);
+  assert.match(writes, /\x1b\[3J/);
+  assert.match(writes, /\x1b\[H/);
+});
+
+test("transcript clear is allowed while streaming state is active", () => {
+  let writes = "";
+  setTerminalControlUIState("RESPONDING");
+
+  try {
+    writeTerminalControl((chunk) => {
+      writes += chunk;
+    }, "stdout", "test:transcriptClear", TERMINAL_SEQUENCES.transcriptClear);
+  } finally {
+    setTerminalControlUIState("IDLE");
+  }
+
+  assert.equal(writes, TERMINAL_SEQUENCES.transcriptClear);
+});

package/src/core/terminal/terminalControl.ts

@@ -0,0 +1,147 @@
+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`,
+} as const;
+
+export type TerminalWrite = (chunk: string) => boolean | void;
+export type TerminalChannel = "stdout" | "stderr";
+
+// 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: "codexa",
+    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: "codexa",
+    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;
+  resetModes(): void;
+}
+
+export function createTerminalModeController(write: TerminalWrite): TerminalModeController {
+  let mouseReporting: boolean | null = null;
+  let bracketedPaste: 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);
+    },
+    resetModes() {
+      renderDebug.traceEvent("terminal", "resetModes", {
+        mouseReporting,
+        bracketedPaste,
+      });
+      mouseReporting = null;
+      bracketedPaste = null;
+    },
+  };
+}

package/src/core/terminal/terminalSanitize.test.ts

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  sanitizeTerminalInput,
+  sanitizeTerminalLines,
+  sanitizeTerminalOutput,
+} from "./terminalSanitize.js";
+
+test("sanitizeTerminalOutput strips ANSI/OSC/control bytes and normalizes line breaks", () => {
+  const raw = "A\u001B[31mred\u001B[0m\u001B]0;title\u0007\r\nB\rC\u0007";
+  assert.equal(sanitizeTerminalOutput(raw), "Ared\nB\nC");
+});
+
+test("sanitizeTerminalInput removes layout-breaking escapes", () => {
+  const raw = "hello\u001B[2J\u001B[H\tworld";
+  assert.equal(sanitizeTerminalInput(raw), "hello  world");
+});
+
+test("sanitizeTerminalLines sanitizes and drops empty lines", () => {
+  const lines = ["\u001B[32mok\u001B[0m", " \u0007", "next\rline"];
+  assert.deepEqual(sanitizeTerminalLines(lines), ["ok", "next\nline"]);
+});

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, "");
+}