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

package/src/providers/sdk/v1/validators/manifest.ts

@@ -0,0 +1,110 @@
+/**
+ * Manifest validators — runtime JSON Schema check for v1 provider manifests.
+ *
+ * The schemas live under `schemas/{category}/provider.schema.json` and are
+ * the authoritative contract for what a v1 manifest may contain. Daemon
+ * code that loads a manifest at install or boot time runs it through
+ * `validateCliProviderManifest()` first; failures are reported back to
+ * the caller with structured paths so manifest authors can locate the
+ * offending field without guessing.
+ *
+ * Validation lives in the SDK layer (not in provider-loader) so dashboards,
+ * registry workers, and the provider publish flow can all reuse the
+ * same code path and produce identical error messages.
+ */
+
+import Ajv2020, { type ErrorObject, type ValidateFunction } from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import cliProviderSchema from '../schemas/cli/provider.schema.json';
+
+export interface ManifestValidationIssue {
+    /** JSON Pointer-style path into the manifest. Empty string for the root. */
+    path: string;
+    /** Schema-keyword that failed. */
+    keyword: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** Allowed values when the failure is an `enum` / `const` / `additionalProperties`. */
+    allowed?: unknown;
+}
+
+export interface ManifestValidationResult {
+    ok: boolean;
+    issues: ManifestValidationIssue[];
+}
+
+let _ajv: Ajv2020 | null = null;
+let _cliValidator: ValidateFunction | null = null;
+
+function getAjv(): Ajv2020 {
+    if (_ajv) return _ajv;
+    // strict=false because the schema authors freely use schema-level
+    // `description`/`examples` fields that ajv would otherwise warn about.
+    // allErrors=true so a single validation run reports every problem at
+    // once instead of bailing on the first — that's what makes the
+    // structured-error output usable for manifest authors.
+    _ajv = new Ajv2020({
+        strict: false,
+        allErrors: true,
+        allowUnionTypes: true,
+    });
+    addFormats(_ajv);
+    return _ajv;
+}
+
+function getCliValidator(): ValidateFunction {
+    if (_cliValidator) return _cliValidator;
+    _cliValidator = getAjv().compile(cliProviderSchema as unknown as object);
+    return _cliValidator;
+}
+
+function formatIssue(err: ErrorObject): ManifestValidationIssue {
+    const path = err.instancePath || '';
+    const params = err.params as Record<string, unknown>;
+    let message = err.message || 'validation failed';
+    let allowed: unknown;
+
+    if (err.keyword === 'additionalProperties') {
+        const extra = params.additionalProperty;
+        message = `unexpected property "${extra}"`;
+    } else if (err.keyword === 'required') {
+        message = `missing required property "${params.missingProperty}"`;
+    } else if (err.keyword === 'enum') {
+        allowed = params.allowedValues;
+        message = `must be one of ${JSON.stringify(allowed)}`;
+    } else if (err.keyword === 'const') {
+        allowed = params.allowedValue;
+        message = `must equal ${JSON.stringify(allowed)}`;
+    } else if (err.keyword === 'type') {
+        message = `must be ${params.type}`;
+    }
+
+    return { path, keyword: err.keyword, message, ...(allowed !== undefined ? { allowed } : {}) };
+}
+
+/**
+ * Validate a CLI provider.v1.json manifest. Returns `{ ok: true, issues: [] }`
+ * on success and `{ ok: false, issues: [...] }` on failure with each issue
+ * pointing at the offending field. Never throws — manifest parse errors
+ * should be caught by the caller before this is called.
+ */
+export function validateCliProviderManifest(manifest: unknown): ManifestValidationResult {
+    const validator = getCliValidator();
+    const ok = validator(manifest) as boolean;
+    if (ok) return { ok: true, issues: [] };
+    const issues = (validator.errors || []).map(formatIssue);
+    return { ok: false, issues };
+}
+
+/**
+ * Render a list of validation issues as a single multi-line string,
+ * suitable for log lines or daemon command error fields.
+ */
+export function formatManifestValidationIssues(issues: ManifestValidationIssue[]): string {
+    return issues
+        .map((issue) => {
+            const where = issue.path || '<root>';
+            return `  - ${where}: ${issue.message} (${issue.keyword})`;
+        })
+        .join('\n');
+}

package/src/providers/sdk/v1/validators/taint.ts

@@ -0,0 +1,309 @@
+/**
+ * Static taint analyzer for extended-tier override JS.
+ *
+ * Goal: classify the override JS shipped with an extended-tier provider into
+ * one of three risk tiers, so the dashboard + daemon trust prompt can
+ * surface accurate language to the operator instead of a single generic
+ * "this provider contains JS" warning.
+ *
+ *   - clean    : no flagged APIs at all. The override looks like pure string
+ *                manipulation. Still extended-tier, but the warning copy is
+ *                "this provider contains JS; nothing dangerous was detected".
+ *   - elevated : touches process / dynamic codegen / dynamic require / eval
+ *                / Function constructor / child_process. The warning copy is
+ *                explicit ("this provider can run shell commands / dynamically
+ *                load code").
+ *   - hostile  : combines elevated APIs with network egress, AND uses obvious
+ *                obfuscation (base64-decoded strings fed into Function / eval).
+ *                The publish endpoint should reject these.
+ *
+ * Implementation note: this is a *static* analyzer — string + light AST scan
+ * via Node's built-in parser. It is intentionally fail-loud: anything that
+ * looks suspicious is flagged. False positives are fine; this exists to gate
+ * the trust prompt, not to be a real sandbox. The real sandbox lives in
+ * Phase 5 (isolated-vm).
+ *
+ * Used by:
+ *   - `adhdev provider validate` (CLI tier classification)
+ *   - registry publish endpoint static-check
+ *   - daemon at provider-load time, to size the warning
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+
+// ─── Findings ──────────────────────────────────────────────────────────
+
+export type TaintLevel = 'clean' | 'elevated' | 'hostile';
+
+export interface TaintFinding {
+  /** What was found, e.g. "child_process.exec". */
+  api: string;
+  /** Coarse category. */
+  category: TaintCategory;
+  /** File the finding came from. */
+  file: string;
+  /** Line number (1-indexed) of the first character of the matched token. */
+  line: number;
+  /** The surrounding source excerpt, trimmed. */
+  excerpt: string;
+}
+
+export type TaintCategory =
+  | 'process-control'   // process.exit, process.kill
+  | 'shell-exec'        // child_process.{exec,execSync,spawn,spawnSync,fork}
+  | 'fs-write'          // fs.writeFile / writeFileSync outside override dir
+  | 'fs-read'           // fs.readFile / readFileSync
+  | 'network'           // http(s).request, fetch, net.connect, dgram
+  | 'dynamic-codegen'   // eval, new Function(), Function('...')
+  | 'dynamic-require'   // require(variable), import(variable)
+  | 'obfuscation'       // Buffer.from(...,'base64').toString + (eval|Function)
+  | 'global-mutation';  // mutating Object.prototype, process.env
+
+export interface TaintResult {
+  level: TaintLevel;
+  findings: TaintFinding[];
+  files: string[];
+}
+
+// ─── Patterns ──────────────────────────────────────────────────────────
+
+interface PatternRule {
+  category: TaintCategory;
+  /** Display label. */
+  label: string;
+  /** Regex applied per-line. */
+  pattern: RegExp;
+}
+
+const PATTERNS: PatternRule[] = [
+  {
+    category: 'shell-exec',
+    label: 'child_process.exec',
+    pattern: /\bchild_process\b[\s\S]{0,40}?\b(exec|execSync|spawn|spawnSync|fork|execFile)\b/,
+  },
+  {
+    category: 'shell-exec',
+    label: 'require("child_process")',
+    pattern: /\brequire\s*\(\s*['"]child_process['"]\s*\)/,
+  },
+  {
+    category: 'shell-exec',
+    label: 'import child_process',
+    pattern: /\bfrom\s+['"](?:node:)?child_process['"]/,
+  },
+  {
+    category: 'process-control',
+    label: 'process.exit / kill',
+    pattern: /\bprocess\.(exit|kill|abort)\s*\(/,
+  },
+  {
+    category: 'global-mutation',
+    label: 'process.env mutation',
+    pattern: /\bprocess\.env\.[A-Z_][A-Z0-9_]*\s*=/,
+  },
+  {
+    category: 'global-mutation',
+    label: 'prototype pollution',
+    pattern: /\bObject\.prototype\b.*=/,
+  },
+  {
+    category: 'dynamic-codegen',
+    label: 'eval()',
+    pattern: /(?<![A-Za-z0-9_$])eval\s*\(/,
+  },
+  {
+    category: 'dynamic-codegen',
+    label: 'new Function()',
+    pattern: /\bnew\s+Function\s*\(/,
+  },
+  {
+    category: 'dynamic-require',
+    label: 'require(variable)',
+    pattern: /\brequire\s*\(\s*(?!['"`])/,
+  },
+  {
+    category: 'dynamic-require',
+    label: 'import(variable)',
+    pattern: /(?<![.\w])import\s*\(\s*(?!['"`])/,
+  },
+  {
+    category: 'network',
+    label: 'fetch()',
+    pattern: /(?<![A-Za-z0-9_$])fetch\s*\(/,
+  },
+  {
+    category: 'network',
+    label: 'http(s).request',
+    pattern: /\b(https?)\.(request|get)\s*\(/,
+  },
+  {
+    category: 'network',
+    label: 'net.connect / Socket',
+    pattern: /\b(net\.connect|tls\.connect|new\s+net\.Socket)\b/,
+  },
+  {
+    category: 'network',
+    label: 'dgram',
+    pattern: /\brequire\s*\(\s*['"](?:node:)?dgram['"]/,
+  },
+  {
+    category: 'fs-write',
+    label: 'fs.writeFile / writeFileSync',
+    pattern: /\bfs\.(writeFile|writeFileSync|appendFile|appendFileSync|unlink|unlinkSync|rm|rmSync)\b/,
+  },
+  {
+    category: 'fs-read',
+    label: 'fs.readFile / readFileSync',
+    pattern: /\bfs\.(readFile|readFileSync|readdir|readdirSync|stat|statSync)\b/,
+  },
+];
+
+// Obfuscation heuristic: base64 / hex decode feeding into eval or Function.
+const OBFUSCATION_PATTERN =
+  /Buffer\.from\s*\([^)]*['"](?:base64|hex)['"]\s*\)\s*\.toString\s*\([^)]*\)[\s\S]{0,80}?(eval|Function)\s*\(/;
+
+// ─── File walker — picks up everything reachable from overrides ────────
+
+function listOverrideJsFiles(manifestPath: string): string[] {
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8')) as { overrides?: Record<string, unknown> };
+  if (!manifest.overrides) return [];
+  const base = dirname(manifestPath);
+  const out = new Set<string>();
+  for (const value of Object.values(manifest.overrides)) {
+    let rel: string | null = null;
+    if (typeof value === 'string') rel = value;
+    else if (value && typeof value === 'object' && 'path' in value && typeof (value as { path: unknown }).path === 'string') {
+      rel = (value as { path: string }).path;
+    }
+    if (!rel) continue;
+    const abs = resolve(base, rel);
+    if (existsSync(abs)) out.add(abs);
+  }
+  // Best-effort: also scan sibling scripts/ tree, since overrides commonly
+  // require() helpers from there.
+  for (const candidate of ['scripts']) {
+    const dir = join(base, candidate);
+    if (existsSync(dir)) {
+      try {
+        walk(dir, out);
+      } catch {
+        // Ignore individual unreadable files.
+      }
+    }
+  }
+  return [...out];
+}
+
+function walk(dir: string, into: Set<string>): void {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { readdirSync, statSync } = require('node:fs') as typeof import('node:fs');
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry);
+    let st;
+    try { st = statSync(abs); } catch { continue; }
+    if (st.isDirectory()) walk(abs, into);
+    else if (st.isFile() && /\.(?:m|c)?js$/.test(entry)) into.add(abs);
+  }
+}
+
+// ─── Scanner ───────────────────────────────────────────────────────────
+
+function scanFile(file: string): TaintFinding[] {
+  const source = readFileSync(file, 'utf-8');
+  const findings: TaintFinding[] = [];
+  // Per-line scan keeps line numbers honest.
+  const lines = source.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    for (const rule of PATTERNS) {
+      if (rule.pattern.test(line)) {
+        findings.push({
+          api: rule.label,
+          category: rule.category,
+          file,
+          line: i + 1,
+          excerpt: line.trim().slice(0, 200),
+        });
+      }
+    }
+  }
+  // Whole-file scan for obfuscation pattern (may span lines).
+  if (OBFUSCATION_PATTERN.test(source)) {
+    findings.push({
+      api: 'base64/hex → eval|Function',
+      category: 'obfuscation',
+      file,
+      line: 1,
+      excerpt: '<obfuscation pattern across multiple lines>',
+    });
+  }
+  return findings;
+}
+
+// ─── Classification ────────────────────────────────────────────────────
+
+const ELEVATED_CATEGORIES = new Set<TaintCategory>([
+  'shell-exec',
+  'process-control',
+  'dynamic-codegen',
+  'dynamic-require',
+  'fs-write',
+  'global-mutation',
+]);
+
+const HOSTILE_REQUIRES = new Set<TaintCategory>([
+  'obfuscation',
+]);
+
+function classify(findings: TaintFinding[]): TaintLevel {
+  if (findings.length === 0) return 'clean';
+  const cats = new Set(findings.map((f) => f.category));
+  if ([...cats].some((c) => HOSTILE_REQUIRES.has(c))) return 'hostile';
+  // Hostile also: elevated + network combined.
+  const hasElevated = [...cats].some((c) => ELEVATED_CATEGORIES.has(c));
+  const hasNetwork = cats.has('network');
+  if (hasElevated && hasNetwork) return 'hostile';
+  if (hasElevated || hasNetwork) return 'elevated';
+  return 'clean'; // only fs-read on its own is fine.
+}
+
+// ─── Public API ────────────────────────────────────────────────────────
+
+export function analyzeOverrideTaint(manifestPath: string): TaintResult {
+  const files = listOverrideJsFiles(manifestPath);
+  const findings: TaintFinding[] = [];
+  for (const f of files) findings.push(...scanFile(f));
+  return {
+    level: classify(findings),
+    findings,
+    files,
+  };
+}
+
+/** Format a result as a single CLI-friendly block. */
+export function formatTaintResult(result: TaintResult): string {
+  const lines: string[] = [];
+  lines.push(`Tier: extended (override JS present)`);
+  lines.push(`Risk level: ${result.level}`);
+  lines.push(`Files scanned: ${result.files.length}`);
+  if (result.findings.length === 0) {
+    lines.push('No flagged APIs detected.');
+    return lines.join('\n');
+  }
+  // Group by category for a tighter report.
+  const byCat = new Map<TaintCategory, TaintFinding[]>();
+  for (const f of result.findings) {
+    const arr = byCat.get(f.category) ?? [];
+    arr.push(f);
+    byCat.set(f.category, arr);
+  }
+  for (const [cat, items] of byCat) {
+    lines.push(`  ${cat}: ${items.length} occurrence(s)`);
+    for (const f of items.slice(0, 5)) {
+      lines.push(`    ${f.file}:${f.line}  ${f.api}`);
+    }
+    if (items.length > 5) lines.push(`    …and ${items.length - 5} more`);
+  }
+  return lines.join('\n');
+}

package/src/providers/spec/adapter.ts

@@ -0,0 +1,235 @@
+/**
+ * PTY + terminal-screen adapter for the spec driver.
+ *
+ * Spawns a PTY, feeds bytes into a TerminalScreen (ghostty-vt when available,
+ * xterm fallback otherwise) so a visible-screen snapshot is always available,
+ * and exposes a small hook surface for the SpecDriver to consume:
+ *
+ *   init({ pid })               — PTY spawned
+ *   on_pty_data(chunk)          — raw PTY byte chunk received
+ *   on_screen_changed(snapshot) — coalesced visible-screen change
+ *   on_exit({ exitCode })       — PTY exited
+ *   tick()                      — periodic tick (if tickIntervalMs > 0)
+ */
+'use strict';
+
+import { TerminalScreen } from '../../cli-adapters/terminal-screen.js';
+import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+import type { PtyRuntimeTransport } from '../../cli-adapters/pty-transport.js';
+import { DEFAULT_SESSION_HOST_COLS, DEFAULT_SESSION_HOST_ROWS } from '@adhdev/session-host-core';
+
+export type { PtyTransportFactory };
+
+export interface TerminalAdapterOpts {
+    binary: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    /**
+     * When true, `env` is already a COMPLETE, sanitized environment (the spawn
+     * planner merged + stripped process.env already) and must be passed to the
+     * PTY verbatim — NOT overlaid on top of process.env. Overlaying would
+     * re-introduce the npm_/PNPM_/parent-session keys the planner explicitly
+     * stripped, so the spec path's spawn env would diverge from the legacy
+     * path's. Defaults to false (legacy overlay behaviour) for any caller that
+     * still passes a partial env.
+     */
+    envIsComplete?: boolean;
+    cols?: number;
+    rows?: number;
+    /** Coalesce screen snapshots: emit on_screen_changed at most this often. */
+    screenChangeDebounceMs?: number;
+    tickIntervalMs?: number;
+    transportFactory?: PtyTransportFactory;
+}
+
+export interface TerminalAdapterHandlers {
+    init?(info: { pid: number }): void;
+    on_pty_data?(chunk: string): void;
+    on_screen_changed?(snapshot: string): void;
+    on_exit?(info: { exitCode: number }): void;
+    tick?(): void;
+}
+
+/**
+ * One entry in the PTY input/output event timeline (debug-only). Captured at
+ * the single common point every spec@4 provider funnels through — this adapter
+ * — so the Spec Debug Snapshot can answer "what input / output preceded a status
+ * transition?". Observation only; nothing here feeds the FSM decision.
+ */
+export interface SpecPtyEvent {
+    /** Wall-clock ms. */
+    ts: number;
+    kind: 'spawn' | 'input' | 'output' | 'resize' | 'cursor' | 'exit';
+    /** Human-readable, control-char-escaped, length-capped preview. */
+    content: string;
+    /** Raw byte length before truncation (output/input only). */
+    bytes?: number;
+}
+
+const MAX_PTY_EVENTS = 300;
+const EVENT_CONTENT_CAP = 240;
+
+/** Escape control characters into a visible form so the timeline is readable
+ *  (CR/LF/ESC/tab become \r \n \x1b \t; other C0 controls become \xNN). */
+function escapeControl(text: string): string {
+    // eslint-disable-next-line no-control-regex
+    return String(text).replace(/[\x00-\x1f\x7f]/g, (ch) => {
+        const code = ch.charCodeAt(0);
+        if (ch === '\r') return '\\r';
+        if (ch === '\n') return '\\n';
+        if (ch === '\t') return '\\t';
+        if (code === 0x1b) return '\\x1b';
+        return '\\x' + code.toString(16).padStart(2, '0');
+    });
+}
+
+function capPreview(text: string): string {
+    return text.length > EVENT_CONTENT_CAP ? text.slice(0, EVENT_CONTENT_CAP) + `…(+${text.length - EVENT_CONTENT_CAP})` : text;
+}
+
+export class TerminalAdapter {
+    private rows: number;
+    private cols: number;
+    private readonly screenDebounceMs: number;
+    private readonly tickIntervalMs: number;
+    private readonly factory: PtyTransportFactory;
+    private screen: TerminalScreen;
+    private pty: PtyRuntimeTransport | null = null;
+    private screenTimer: ReturnType<typeof setTimeout> | null = null;
+    private tickTimer: ReturnType<typeof setInterval> | null = null;
+    private lastScreen = '';
+    /** Debug-only ring buffer of PTY input/output/resize/cursor events. */
+    private events: SpecPtyEvent[] = [];
+    private lastCursorKey = '';
+
+    constructor(
+        private readonly opts: TerminalAdapterOpts,
+        private readonly handlers: TerminalAdapterHandlers,
+    ) {
+        this.cols = opts.cols ?? DEFAULT_SESSION_HOST_COLS;
+        this.rows = opts.rows ?? DEFAULT_SESSION_HOST_ROWS;
+        this.screenDebounceMs = opts.screenChangeDebounceMs ?? 80;
+        this.tickIntervalMs = opts.tickIntervalMs ?? 0;
+        // Import NodePtyTransportFactory lazily to avoid loading node-pty in
+        // environments that don't need it (tests, fixture runners) — only when
+        // no transport factory was injected. Doing it unconditionally pulled in
+        // the node-pty module (and broke source-level test runs) even when a
+        // fake factory was supplied.
+        if (opts.transportFactory) {
+            this.factory = opts.transportFactory;
+        } else {
+            const { NodePtyTransportFactory } = require('../../cli-adapters/pty-transport.js');
+            this.factory = new NodePtyTransportFactory();
+        }
+        this.screen = new TerminalScreen(this.rows, this.cols);
+    }
+
+    start(): void {
+        const env = this.opts.envIsComplete
+            ? ((this.opts.env ?? {}) as Record<string, string>)
+            : ({ ...process.env, ...(this.opts.env ?? {}) } as Record<string, string>);
+        this.pty = this.factory.spawn(this.opts.binary, this.opts.args ?? [], {
+            cwd: this.opts.cwd ?? process.cwd(),
+            env,
+            cols: this.cols,
+            rows: this.rows,
+        });
+        this.recordEvent('spawn', `${this.opts.binary} (${this.cols}x${this.rows})`);
+        this.handlers.init?.({ pid: this.pty.pid });
+        this.pty.onData((chunk) => this.onChunk(chunk));
+        this.pty.onExit((info) => {
+            this.stopTimers();
+            this.recordEvent('exit', `exitCode=${typeof info.exitCode === 'number' ? info.exitCode : 0}`);
+            this.handlers.on_exit?.({ exitCode: typeof info.exitCode === 'number' ? info.exitCode : 0 });
+            this.pty = null;
+        });
+        if (this.tickIntervalMs > 0) {
+            this.tickTimer = setInterval(() => this.handlers.tick?.(), this.tickIntervalMs);
+        }
+    }
+
+    resize(cols: number, rows: number): void {
+        this.cols = cols; this.rows = rows;
+        this.recordEvent('resize', `${cols}x${rows}`);
+        this.pty?.resize(cols, rows);
+        this.screen.resize(rows, cols);
+    }
+
+    snapshot(): string {
+        return this.lastScreen || this.computeScreen();
+    }
+
+    /**
+     * Full-buffer snapshot including scrollback history. Unlike snapshot()
+     * (visible viewport only), this survives a tall prompt whose top has
+     * scrolled off-screen — used for content-pattern extraction (modal
+     * buttons / approval anchors), NOT for cursor-relative conditions.
+     */
+    snapshotWithScrollback(): string {
+        return this.screen.getTextWithScrollback();
+    }
+
+    getCursorPosition(): { row: number; col: number } {
+        const pos = this.screen.getCursorPosition();
+        return { row: pos.row, col: pos.col };
+    }
+
+    send_keys(text: string): void {
+        this.recordEvent('input', capPreview(escapeControl(text)), text.length);
+        this.pty?.write(text);
+    }
+
+    /** Debug-only: most-recent PTY input/output/resize/cursor events, oldest
+     *  first. Pure observation — never consulted by the FSM. */
+    getEventTimeline(limit = MAX_PTY_EVENTS): SpecPtyEvent[] {
+        const n = Math.max(0, Math.min(limit, this.events.length));
+        return this.events.slice(this.events.length - n);
+    }
+
+    private recordEvent(kind: SpecPtyEvent['kind'], content: string, bytes?: number): void {
+        const ev: SpecPtyEvent = { ts: Date.now(), kind, content };
+        if (typeof bytes === 'number') ev.bytes = bytes;
+        this.events.push(ev);
+        if (this.events.length > MAX_PTY_EVENTS) this.events.splice(0, this.events.length - MAX_PTY_EVENTS);
+    }
+
+    kill(): void {
+        this.stopTimers();
+        try { this.pty?.kill(); } catch { /* ignore */ }
+        this.pty = null;
+        this.screen.dispose();
+    }
+
+    private onChunk(chunk: string): void {
+        this.recordEvent('output', capPreview(escapeControl(chunk)), chunk.length);
+        try { this.handlers.on_pty_data?.(chunk); } catch { /* user side */ }
+        this.screen.write(chunk);
+        // Coalesce snapshot emission — rapid bursts shouldn't fire 200x.
+        if (this.screenTimer) return;
+        this.screenTimer = setTimeout(() => {
+            this.screenTimer = null;
+            const snap = this.computeScreen();
+            // Record cursor movement at the (debounced) screen-change boundary
+            // rather than per output chunk, so the timeline isn't flooded.
+            const cur = this.screen.getCursorPosition();
+            const curKey = `${cur.row},${cur.col}`;
+            if (curKey !== this.lastCursorKey) {
+                this.lastCursorKey = curKey;
+                this.recordEvent('cursor', `(${cur.row},${cur.col})`);
+            }
+            if (snap === this.lastScreen) return;
+            this.lastScreen = snap;
+            try { this.handlers.on_screen_changed?.(snap); } catch { /* user side */ }
+        }, this.screenDebounceMs);
+    }
+
+    private computeScreen(): string {
+        return this.screen.getText();
+    }
+
+    private stopTimers(): void {
+        if (this.screenTimer) { clearTimeout(this.screenTimer); this.screenTimer = null; }
+        if (this.tickTimer)   { clearInterval(this.tickTimer); this.tickTimer = null; }
+    }
+}