@adhdev/daemon-core 0.9.82-rc.43 → 0.9.82-rc.430

package/src/cli-adapters/raw-terminal-io.ts

@@ -0,0 +1,252 @@
+import { randomUUID } from 'crypto';
+import {
+    SessionHostClient,
+    type SessionHostEndpoint,
+    type SessionHostRequest,
+    type SessionHostResponse,
+    type SessionTerminalSnapshot,
+    type SessionTerminalState,
+} from '@adhdev/session-host-core';
+
+type LowercaseLetter =
+    | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm'
+    | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
+
+type FunctionKey = 'f1' | 'f2' | 'f3' | 'f4' | 'f5' | 'f6' | 'f7' | 'f8' | 'f9' | 'f10' | 'f11' | 'f12';
+type BaseNamedKey =
+    | 'enter' | 'escape' | 'tab' | 'backspace'
+    | 'up' | 'down' | 'left' | 'right'
+    | 'home' | 'end' | 'pageup' | 'pagedown' | 'space'
+    | FunctionKey;
+type ShiftNamedKey = BaseNamedKey | LowercaseLetter | `ctrl+${LowercaseLetter}` | `alt+${LowercaseLetter}`;
+
+export type NamedKey =
+    | BaseNamedKey
+    | `ctrl+${LowercaseLetter}`
+    | `alt+${LowercaseLetter}`
+    | `shift+${ShiftNamedKey}`;
+
+const BASE_KEY_SEQUENCES: Record<BaseNamedKey, string> = {
+    enter: '\r',
+    escape: '\x1b',
+    tab: '\t',
+    backspace: '\x7f',
+    up: '\x1b[A',
+    down: '\x1b[B',
+    right: '\x1b[C',
+    left: '\x1b[D',
+    home: '\x1b[H',
+    end: '\x1b[F',
+    pageup: '\x1b[5~',
+    pagedown: '\x1b[6~',
+    space: ' ',
+    f1: '\x1bOP',
+    f2: '\x1bOQ',
+    f3: '\x1bOR',
+    f4: '\x1bOS',
+    f5: '\x1b[15~',
+    f6: '\x1b[17~',
+    f7: '\x1b[18~',
+    f8: '\x1b[19~',
+    f9: '\x1b[20~',
+    f10: '\x1b[21~',
+    f11: '\x1b[23~',
+    f12: '\x1b[24~',
+};
+
+const SHIFTED_CSI_KEYS: Partial<Record<BaseNamedKey, string>> = {
+    up: '\x1b[1;2A',
+    down: '\x1b[1;2B',
+    right: '\x1b[1;2C',
+    left: '\x1b[1;2D',
+    home: '\x1b[1;2H',
+    end: '\x1b[1;2F',
+    pageup: '\x1b[5;2~',
+    pagedown: '\x1b[6;2~',
+    f1: '\x1b[1;2P',
+    f2: '\x1b[1;2Q',
+    f3: '\x1b[1;2R',
+    f4: '\x1b[1;2S',
+    f5: '\x1b[15;2~',
+    f6: '\x1b[17;2~',
+    f7: '\x1b[18;2~',
+    f8: '\x1b[19;2~',
+    f9: '\x1b[20;2~',
+    f10: '\x1b[21;2~',
+    f11: '\x1b[23;2~',
+    f12: '\x1b[24;2~',
+};
+
+function isLowercaseLetter(value: string): value is LowercaseLetter {
+    return /^[a-z]$/.test(value);
+}
+
+function encodeControlLetter(letter: LowercaseLetter): string {
+    return String.fromCharCode(letter.charCodeAt(0) - 96);
+}
+
+function encodeShiftedKey(key: string): string {
+    if (isLowercaseLetter(key)) return key.toUpperCase();
+    if (key.startsWith('ctrl+') && isLowercaseLetter(key.slice(5))) {
+        return encodeControlLetter(key.slice(5) as LowercaseLetter);
+    }
+    if (key.startsWith('alt+') && isLowercaseLetter(key.slice(4))) {
+        return `\x1b${key.slice(4).toUpperCase()}`;
+    }
+    if (key === 'tab') return '\x1b[Z';
+    if (key in SHIFTED_CSI_KEYS) return SHIFTED_CSI_KEYS[key as BaseNamedKey]!;
+    if (key in BASE_KEY_SEQUENCES) return BASE_KEY_SEQUENCES[key as BaseNamedKey];
+    throw new Error(`Unsupported named key: shift+${key}`);
+}
+
+export function namedKeyToAnsi(key: NamedKey | string): string {
+    const normalized = String(key || '').trim().toLowerCase();
+    if (normalized in BASE_KEY_SEQUENCES) return BASE_KEY_SEQUENCES[normalized as BaseNamedKey];
+    if (normalized.startsWith('ctrl+') && isLowercaseLetter(normalized.slice(5))) {
+        return encodeControlLetter(normalized.slice(5) as LowercaseLetter);
+    }
+    if (normalized.startsWith('alt+') && isLowercaseLetter(normalized.slice(4))) {
+        return `\x1b${normalized.slice(4)}`;
+    }
+    if (normalized.startsWith('shift+')) return encodeShiftedKey(normalized.slice(6));
+    throw new Error(`Unsupported named key: ${key}`);
+}
+
+export function namedKeysToAnsi(keys: readonly (NamedKey | string)[]): string {
+    if (!Array.isArray(keys)) throw new Error('keys must be an array');
+    return keys.map(namedKeyToAnsi).join('');
+}
+
+export interface RawTerminalSessionHostClient {
+    connect(): Promise<void>;
+    request<T = unknown>(request: SessionHostRequest): Promise<SessionHostResponse<T>>;
+    close(): Promise<void>;
+}
+
+export interface RawTerminalAttachmentOptions {
+    endpoint?: SessionHostEndpoint;
+    sessionId: string;
+    mode?: 'read' | 'write';
+    clientId?: string;
+    client?: RawTerminalSessionHostClient;
+}
+
+export class RawTerminalAttachment {
+    private closed = false;
+
+    private constructor(
+        readonly sessionId: string,
+        private readonly clientId: string,
+        private readonly mode: 'read' | 'write',
+        private readonly client: RawTerminalSessionHostClient,
+    ) {}
+
+    static async attach(options: RawTerminalAttachmentOptions): Promise<RawTerminalAttachment> {
+        const sessionId = String(options.sessionId || '').trim();
+        if (!sessionId) throw new Error('sessionId is required');
+        const mode = options.mode || 'read';
+        const clientId = options.clientId || `raw-terminal-${process.pid}-${randomUUID().slice(0, 8)}`;
+        const client = options.client || new SessionHostClient({ endpoint: options.endpoint });
+        await client.connect();
+
+        const attachResponse = await client.request({
+            type: 'attach_session',
+            payload: {
+                sessionId,
+                clientId,
+                clientType: 'web',
+                readOnly: mode === 'read',
+            },
+        });
+        if (!attachResponse.success) {
+            await client.close().catch(() => {});
+            throw new Error(attachResponse.error || `Failed to attach terminal session ${sessionId}`);
+        }
+
+        if (mode === 'write') {
+            const ownerResponse = await client.request({
+                type: 'acquire_write',
+                payload: {
+                    sessionId,
+                    clientId,
+                    ownerType: 'user',
+                    force: true,
+                },
+            });
+            if (!ownerResponse.success) {
+                await client.request({
+                    type: 'detach_session',
+                    payload: { sessionId, clientId },
+                }).catch(() => ({ success: false }));
+                await client.close().catch(() => {});
+                throw new Error(ownerResponse.error || `Failed to acquire terminal session ${sessionId}`);
+            }
+        }
+
+        return new RawTerminalAttachment(sessionId, clientId, mode, client);
+    }
+
+    async readSnapshot(): Promise<SessionTerminalSnapshot> {
+        const response = await this.client.request<SessionTerminalSnapshot>({
+            type: 'get_terminal_snapshot',
+            payload: { sessionId: this.sessionId },
+        });
+        if (!response.success || !response.result) {
+            throw new Error(response.error || `Terminal screen unavailable for ${this.sessionId}`);
+        }
+        return response.result;
+    }
+
+    async readScreenText(): Promise<string> {
+        return (await this.readSnapshot()).text;
+    }
+
+    async readState(): Promise<SessionTerminalState> {
+        return (await this.readSnapshot()).state;
+    }
+
+    async writeInput(text: string): Promise<void> {
+        if (this.mode !== 'write') throw new Error('Raw terminal attachment is read-only');
+        const response = await this.client.request({
+            type: 'send_input',
+            payload: {
+                sessionId: this.sessionId,
+                clientId: this.clientId,
+                data: text,
+            },
+        });
+        if (!response.success) throw new Error(response.error || `Failed to write terminal input to ${this.sessionId}`);
+    }
+
+    async writeKeys(keys: readonly (NamedKey | string)[]): Promise<void> {
+        await this.writeInput(namedKeysToAnsi(keys));
+    }
+
+    async close(): Promise<void> {
+        if (this.closed) return;
+        this.closed = true;
+        if (this.mode === 'write') {
+            await this.client.request({
+                type: 'release_write',
+                payload: { sessionId: this.sessionId, clientId: this.clientId },
+            }).catch(() => ({ success: false }));
+        }
+        await this.client.request({
+            type: 'detach_session',
+            payload: { sessionId: this.sessionId, clientId: this.clientId },
+        }).catch(() => ({ success: false }));
+        await this.client.close().catch(() => {});
+    }
+}
+
+export async function withRawTerminalAttachment<T>(
+    options: RawTerminalAttachmentOptions,
+    operation: (attachment: RawTerminalAttachment) => Promise<T>,
+): Promise<T> {
+    const attachment = await RawTerminalAttachment.attach(options);
+    try {
+        return await operation(attachment);
+    } finally {
+        await attachment.close();
+    }
+}

package/src/cli-adapters/resolve-executable.ts

@@ -0,0 +1,204 @@
+import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import * as path from 'path';
+
+// Extensions ConPTY/CreateProcess can launch directly (not .cmd/.bat, which
+// need a cmd.exe wrapper).
+const DIRECT_EXEC_EXT = new Set(['.exe', '.com']);
+
+// Batch-style shims: absolute and launchable by node-pty's ConPTY, but NOT by
+// child_process.execFile/spawn without a cmd.exe wrapper (Node ≥18.20/20.12/22/24
+// refuse to exec a .cmd/.bat directly — CVE-2024-27980 mitigation). Preferred
+// over extensionless Unix wrappers, which are not win32-executable at all.
+const SHIM_EXEC_EXT = new Set(['.cmd', '.bat']);
+
+// Executable extensions to probe when scanning a directory ourselves, ordered
+// most-directly-launchable first. node-pty's ConPTY backend launches an
+// absolute `.cmd`/`.bat` shim fine (verified) — it only fails to *resolve* a
+// bare command against an incomplete PATH — so once we hand it an absolute
+// path, a `.cmd` shim works just as well as a real `.exe`.
+const WIN_EXEC_EXT = ['.exe', '.com', '.cmd', '.bat'];
+
+/**
+ * Resolve a bare command against well-known global-bin directories that are
+ * frequently NOT on the daemon's inherited PATH, so `where` (which only
+ * searches PATH) misses them. A daemon running under one Node install (e.g.
+ * nvm) never sees another npm prefix's bin dir — notably npm's Windows default
+ * prefix at %APPDATA%\npm, where `npm i -g @openai/codex` lands. Returns an
+ * absolute path on the first hit, or null. Mirrors findBinary()'s extraDirs in
+ * provider-cli-shared.ts; kept inline here so this lightweight module (loaded
+ * by pty-transport) need not pull in the heavier shared module.
+ */
+function resolveWin32GlobalBin(trimmed: string): string | null {
+  // Only resolve a bare command name — anything with a path separator is the
+  // caller's explicit location and must not be re-pointed at a global bin dir.
+  if (path.isAbsolute(trimmed) || trimmed.includes('/') || trimmed.includes('\\')) {
+    return null;
+  }
+  const extraDirs: string[] = [];
+  if (process.env.APPDATA) extraDirs.push(path.join(process.env.APPDATA, 'npm'));
+  try { extraDirs.push(path.dirname(process.execPath)); } catch { /* best-effort */ }
+  for (const dir of extraDirs) {
+    if (!dir) continue;
+    for (const ext of WIN_EXEC_EXT) {
+      const full = path.join(dir, trimmed + ext);
+      if (existsSync(full)) return full;
+    }
+  }
+  return null;
+}
+
+/**
+ * Pick the best launch target from `where`'s match list on win32.
+ *
+ * `where npm` on a typical install returns BOTH the extensionless Unix wrapper
+ * (e.g. `C:\Program Files\nodejs\npm`, a bash shell script) AND the `npm.cmd`
+ * shim. The extensionless wrapper is NOT a win32 executable — handing it to a
+ * spawn boundary ENOENTs (errno -4058). So:
+ *   1. Prefer a directly-launchable `.exe`/`.com`.
+ *   2. Otherwise take a `.cmd`/`.bat` shim (absolute → works for ConPTY, and for
+ *      execFile once wrapped via buildWin32ExecFileSpawn).
+ *   3. NEVER fall back to an extensionless match — return null so the caller can
+ *      try other resolution strategies (global-bin scan) rather than emit a
+ *      path that cannot be exec'd.
+ */
+export function selectWin32ExecutableMatch(matches: string[]): string | null {
+  const cleaned = matches.map((m) => m.trim()).filter(Boolean);
+  const direct = cleaned.find((m) => DIRECT_EXEC_EXT.has(path.extname(m).toLowerCase()));
+  if (direct) return direct;
+  const shim = cleaned.find((m) => SHIM_EXEC_EXT.has(path.extname(m).toLowerCase()));
+  if (shim) return shim;
+  return null;
+}
+
+/**
+ * Resolve a launch command to an absolute executable path on Windows.
+ *
+ * node-pty's ConPTY backend resolves a bare/relative command against the
+ * *calling process's* `Path` env var and — critically — does NOT apply PATHEXT.
+ * So a provider command like `claude` never matches `claude.exe` and the native
+ * layer throws `File not found:` (empty), which crashes the daemon. We resolve
+ * it to an absolute `.exe` here (in the daemon process, which has the full PATH)
+ * before the command ever reaches node-pty.
+ *
+ * No-op on non-Windows and when the command is already an existing absolute path
+ * or cannot be resolved (caller keeps the original behaviour).
+ */
+export function resolveWin32Executable(command: string): string {
+  if (process.platform !== 'win32') return command;
+  const trimmed = (command || '').trim();
+  if (!trimmed) return command;
+
+  // Already an absolute path that exists — keep it.
+  if (path.isAbsolute(trimmed) && existsSync(trimmed)) return trimmed;
+
+  try {
+    const out = execFileSync('where', [trimmed], {
+      encoding: 'utf8',
+      windowsHide: true,
+    }).trim();
+    if (out) {
+      const matches = out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+      // Prefer .exe/.com, then a .cmd/.bat shim; never an extensionless Unix
+      // wrapper (the old `matches[0]` fallback returned exactly that and made
+      // the spawn boundary ENOENT). On no usable match, fall through to the
+      // off-PATH global-bin scan below rather than returning a dead path.
+      const selected = selectWin32ExecutableMatch(matches);
+      if (selected) return selected;
+    }
+  } catch {
+    // `where` not found / non-zero exit — fall through to the global-bin scan.
+  }
+
+  // `where` found nothing on PATH. Before giving up (and letting node-pty crash
+  // with "File not found:" on the bare command), search npm's off-PATH global
+  // bin dir(s). This is the codex case: `npm i -g @openai/codex` installs to
+  // %APPDATA%\npm, which is absent from a nvm-launched daemon's PATH, so a spec
+  // binary of "codex" never resolved and the spawn ENOENT'd.
+  const globalBin = resolveWin32GlobalBin(trimmed);
+  if (globalBin) return globalBin;
+
+  return command;
+}
+
+/**
+ * Quote one argument for a cmd.exe command line using the standard
+ * CommandLineToArgvW rules (the same algorithm Node uses internally): wrap in
+ * double quotes only when needed, double up the backslashes that precede a
+ * quote, and escape embedded quotes. We do per-argument quoting ourselves
+ * (rather than `{ shell: true }`) because Node's shell mode joins argv with bare
+ * spaces and applies NO quoting — any argument containing a space (a path, a
+ * test name) would split. Inputs here are repo-mesh validation/bootstrap command
+ * tokens (trusted config, not network data), so argv-quoting for spaces/quotes
+ * is sufficient; we deliberately do not attempt full cmd.exe metacharacter
+ * (& | < > ^ %) escaping.
+ */
+export function quoteWin32CmdArg(arg: string): string {
+  if (arg.length > 0 && !/[ \t"]/.test(arg)) return arg;
+  let result = '"';
+  let backslashes = 0;
+  for (const ch of arg) {
+    if (ch === '\\') {
+      backslashes += 1;
+      continue;
+    }
+    if (ch === '"') {
+      // Escape every pending backslash (they precede a quote) plus the quote.
+      result += '\\'.repeat(backslashes * 2 + 1) + '"';
+      backslashes = 0;
+      continue;
+    }
+    result += '\\'.repeat(backslashes) + ch;
+    backslashes = 0;
+  }
+  // Trailing backslashes precede the closing quote → must be doubled.
+  result += '\\'.repeat(backslashes * 2) + '"';
+  return result;
+}
+
+export interface Win32ExecFileSpawn {
+  file: string;
+  args: string[];
+  /** Set when the args are pre-quoted for cmd.exe and must not be re-quoted. */
+  windowsVerbatimArguments?: boolean;
+}
+
+/**
+ * Build child_process.execFile/spawn parameters for an already-resolved command.
+ *
+ * On win32 a `.cmd`/`.bat` shim (what `npm`/`npx`/`tsc`/`vitest` resolve to)
+ * cannot be launched by execFile directly — modern Node refuses it (CVE-2024-27980
+ * mitigation) and CreateProcess cannot exec a batch file. So wrap it in
+ * `cmd.exe /d /s /c "<quoted command line>"` with `windowsVerbatimArguments` so
+ * our own per-argument quoting is preserved. `.exe`/`.com` (and every non-win32
+ * platform, and any already-cmd.exe target) pass through unchanged — this is a
+ * strict no-op off win32, guarding against regressions on linux/macOS.
+ */
+export function buildWin32ExecFileSpawn(resolvedCommand: string, args: string[]): Win32ExecFileSpawn {
+  if (process.platform !== 'win32') return { file: resolvedCommand, args };
+  const ext = path.extname(resolvedCommand).toLowerCase();
+  if (!SHIM_EXEC_EXT.has(ext)) return { file: resolvedCommand, args };
+  // cmd.exe /d (skip AutoRun) /s (treat the rest, between the outer quotes, as
+  // the verbatim command) /c (run then exit). Mirrors Node's internal shell
+  // wrapping but with each token individually quoted.
+  const commandLine = [resolvedCommand, ...args].map(quoteWin32CmdArg).join(' ');
+  return {
+    file: process.env.ComSpec || 'cmd.exe',
+    args: ['/d', '/s', '/c', `"${commandLine}"`],
+    windowsVerbatimArguments: true,
+  };
+}
+
+/**
+ * Convenience: resolve a bare command to an absolute win32 path AND build the
+ * execFile spawn parameters (cmd.exe-wrapping a .cmd/.bat shim). Returns the
+ * resolved command alongside the spawn spec so callers can still surface the
+ * resolved path in diagnostics.
+ */
+export function resolveWin32ExecFileSpawn(
+  command: string,
+  args: string[],
+): Win32ExecFileSpawn & { resolvedCommand: string } {
+  const resolvedCommand = resolveWin32Executable(command);
+  return { resolvedCommand, ...buildWin32ExecFileSpawn(resolvedCommand, args) };
+}

package/src/cli-adapters/session-host-transport.ts

@@ -6,6 +6,7 @@ import {
     type SessionHostRecord,
 } from '@adhdev/session-host-core';
 import { LOG } from '../logging/logger.js';
+import { resolveWin32Executable } from './resolve-executable.js';
 import type { PtyRuntimeMetadata, PtyRuntimeTransport, PtySpawnOptions, PtyTransportFactory } from './pty-transport.js';
 
 interface SessionHostPtyTransportFactoryOptions {
@@ -435,7 +436,7 @@ export class SessionHostPtyTransportFactory implements PtyTransportFactory {
     spawn(command: string, args: string[], spawnOptions: PtySpawnOptions): PtyRuntimeTransport {
         return new SessionHostRuntimeTransport({
             ...this.options,
-            command,
+            command: resolveWin32Executable(command),
             args,
             spawnOptions,
         });

package/src/cli-adapters/terminal-backends/ghostty-vt-backend.ts

@@ -1,7 +1,6 @@
 import type {
     TerminalViewportBackend,
     TerminalViewportBackendOptions,
-    TerminalViewportBackendPreference,
 } from './types.js';
 
 type GhosttyVtTerminal = {
@@ -30,6 +29,15 @@ function isModuleNotFoundError(error: unknown, ref: string): boolean {
     return code === 'MODULE_NOT_FOUND' && message.includes(ref);
 }
 
+// Identifies the host runtime so a binding-load failure names the exact ABI it
+// looked for. The underlying binding is N-API (ABI-stable), so a failure here is
+// almost always "no prebuilt directory addressed this triplet" rather than a
+// true ABI incompatibility — making the triplet the single most useful
+// diagnostic to surface in an env-blocker report.
+function runtimeTriplet(): string {
+    return `${process.platform}-${process.arch}-node${process.versions.modules}`;
+}
+
 function normalizeBinding(mod: any, ref: string): GhosttyVtBinding {
     const binding = mod?.default?.createTerminal
         ? mod.default
@@ -49,12 +57,10 @@ function getBindingCandidates(): string[] {
     return explicit ? [explicit] : DEFAULT_BINDING_CANDIDATES;
 }
 
-function loadGhosttyVtBinding(required: boolean): GhosttyVtBinding | null {
+function loadGhosttyVtBinding(): GhosttyVtBinding {
     if (cachedBinding !== undefined) {
-        if (!cachedBinding && required && cachedBindingError) {
-            throw cachedBindingError;
-        }
-        return cachedBinding;
+        if (!cachedBinding && cachedBindingError) throw cachedBindingError;
+        return cachedBinding!;
     }
 
     const errors: string[] = [];
@@ -65,7 +71,7 @@ function loadGhosttyVtBinding(required: boolean): GhosttyVtBinding | null {
             const mod = require(ref);
             cachedBinding = normalizeBinding(mod, ref);
             cachedBindingError = null;
-            return cachedBinding;
+            return cachedBinding!;
         } catch (error) {
             if (isModuleNotFoundError(error, ref)) {
                 errors.push(`${ref}: module not found`);
@@ -78,57 +84,85 @@ function loadGhosttyVtBinding(required: boolean): GhosttyVtBinding | null {
 
     cachedBinding = null;
     cachedBindingError = new Error(
-        `ghostty-vt backend requested but no binding is available (${errors.join('; ') || 'no candidates tried'})`,
+        `ghostty-vt binding unavailable for runtime ${runtimeTriplet()} ` +
+            `(${errors.join('; ') || 'no candidates tried'})`,
     );
-
-    if (required) throw cachedBindingError;
-    return null;
-}
-
-export function resolveTerminalBackendPreference(): TerminalViewportBackendPreference {
-    const raw = process.env.ADHDEV_TERMINAL_BACKEND?.trim().toLowerCase();
-    if (raw === 'ghostty-vt' || raw === 'xterm' || raw === 'auto') return raw;
-    return 'auto';
-}
-
-export function isGhosttyVtBackendAvailable(): boolean {
-    return !!loadGhosttyVtBinding(false);
+    throw cachedBindingError;
 }
 
 export class GhosttyVtTerminalBackend implements TerminalViewportBackend {
     readonly kind = 'ghostty-vt' as const;
     private terminal: GhosttyVtTerminal;
+    private rows: number;
+    private disposed = false;
 
     constructor(options: TerminalViewportBackendOptions) {
-        const binding = loadGhosttyVtBinding(true);
-        if (!binding) {
-            throw new Error('ghostty-vt backend requested but no binding is available');
-        }
+        const binding = loadGhosttyVtBinding();
+        this.rows = Math.max(1, options.rows | 0);
         this.terminal = binding.createTerminal({
             cols: Math.max(1, options.cols | 0),
-            rows: Math.max(1, options.rows | 0),
+            rows: this.rows,
             scrollback: Math.max(0, options.scrollback | 0),
         });
     }
 
     resize(rows: number, cols: number): void {
-        this.terminal.resize(Math.max(1, cols | 0), Math.max(1, rows | 0));
+        this.rows = Math.max(1, rows | 0);
+        this.terminal.resize(Math.max(1, cols | 0), this.rows);
     }
 
     write(data: string): void {
-        if (!data) return;
+        if (!data || this.disposed) return;
         this.terminal.write(data);
     }
 
+    private formatLines(): string[] {
+        // ghostty's `trim:true` collapses CUF-advanced cells — many TUIs including
+        // Claude Code render spaces via cursor-forward rather than literal spaces,
+        // which would break downstream regex matching. Keep per-row padding and
+        // trim trailing whitespace ourselves.
+        //
+        // formatPlainText uses a .screen pin which includes scrollback history.
+        const raw = this.terminal.formatPlainText({ trim: false }) || '';
+        if (!raw) return [];
+        return raw.split('\n').map((row) => row.replace(/\s+$/, ''));
+    }
+
+    private static trimBlankEnds(lines: string[]): string {
+        let first = 0;
+        let last = lines.length;
+        while (first < last && !lines[first]) first += 1;
+        while (last > first && !lines[last - 1]) last -= 1;
+        return lines.slice(first, last).join('\n');
+    }
+
     getText(): string {
-        return this.terminal.formatPlainText({ trim: true }) || '';
+        if (this.disposed) return '';
+        const lines = this.formatLines();
+        if (lines.length === 0) return '';
+        // Take only the viewport (last `rows` lines) to exclude scrollback history.
+        const viewport = lines.length > this.rows ? lines.slice(-this.rows) : lines;
+        return GhosttyVtTerminalBackend.trimBlankEnds(viewport);
+    }
+
+    getTextWithScrollback(): string {
+        if (this.disposed) return '';
+        const lines = this.formatLines();
+        if (lines.length === 0) return '';
+        // Full buffer including scrollback — does NOT slice to the viewport, so a
+        // tall prompt whose top has scrolled above the visible rows is still
+        // matchable by content patterns.
+        return GhosttyVtTerminalBackend.trimBlankEnds(lines);
     }
 
     getCursorPosition(): { col: number; row: number } {
+        if (this.disposed) return { col: 0, row: 0 };
         return this.terminal.getCursorPosition();
     }
 
     dispose(): void {
+        if (this.disposed) return;
+        this.disposed = true;
         this.terminal.dispose();
     }
 }

package/src/cli-adapters/terminal-backends/types.ts

@@ -1,6 +1,4 @@
-export type TerminalViewportBackendKind = 'xterm' | 'ghostty-vt';
-
-export type TerminalViewportBackendPreference = TerminalViewportBackendKind | 'auto';
+export type TerminalViewportBackendKind = 'ghostty-vt';
 
 export type TerminalViewportBackendOptions = {
     rows: number;
@@ -13,6 +11,15 @@ export interface TerminalViewportBackend {
     resize(rows: number, cols: number): void;
     write(data: string): void;
     getText(): string;
+    /**
+     * Like getText() but includes scrollback history (the lines that have
+     * scrolled above the visible viewport). Used by content-pattern matching
+     * (e.g. approval/modal button extraction) that must stay correct when a
+     * tall prompt — a big diff or long explanation — pushes part of the
+     * prompt box above the viewport. NOT for cursor-relative / stable_ms
+     * conditions, whose row indices are viewport-relative.
+     */
+    getTextWithScrollback(): string;
     getCursorPosition(): { col: number; row: number };
     dispose(): void;
 }