claws-code 0.8.0

package/extension/src/task-registry.ts

@@ -0,0 +1,51 @@
+/**
+ * Task registry types for the claws/2 Agentic SDLC protocol.
+ * Tasks are in-memory only — cleared when the extension reloads.
+ */
+
+/**
+ * Lifecycle status of a task. Terminal states are 'succeeded', 'failed',
+ * and 'skipped' — a task in any of these cannot be mutated by further
+ * update/complete calls (complete is idempotent on the terminal state).
+ */
+export type TaskStatus = 'pending' | 'running' | 'blocked' | 'succeeded' | 'failed' | 'skipped';
+
+/**
+ * In-memory record of a single task tracked by the server. Created by
+ * `task.assign` and mutated by `task.update` / `task.complete` / `task.cancel`.
+ * Exposed verbatim (shallow-copied) in `task.list` responses.
+ */
+export interface TaskRecord {
+  /** Unique task id, format "t_NNN" (zero-padded to 3 digits). */
+  taskId: string;
+  /** Short human-readable description of the task. */
+  title: string;
+  /** The prompt or instruction to deliver to the assignee. */
+  prompt: string;
+  /** peerId of the worker assigned this task. */
+  assignee: string;
+  /** peerId of the orchestrator that created the task. */
+  assignedBy: string;
+  status: TaskStatus;
+  progressPct?: number;
+  note?: string;
+  result?: unknown;
+  artifacts?: Array<{ type: string; path: string }>;
+  assignedAt: number;
+  updatedAt: number;
+  completedAt?: number;
+  timeoutMs?: number;
+  /** Set to true when task.cancel has been called; worker should observe and complete with skipped. */
+  cancelRequested?: boolean;
+  cancelReason?: string;
+}
+
+/**
+ * Allocates a task id from a monotonic sequence. The wire format is a
+ * stable "t_" prefix followed by the sequence number zero-padded to 3
+ * digits (e.g. "t_001", "t_042"). Callers must pre-increment their own
+ * counter and pass the new value in — this function is pure.
+ */
+export function allocTaskId(seq: number): string {
+  return `t_${String(seq).padStart(3, '0')}`;
+}

package/extension/src/terminal-backend.ts

@@ -0,0 +1,211 @@
+// extension/src/terminal-backend.ts
+// TerminalBackend interface — the single seam between Claws core and the
+// platform that actually runs terminal processes.
+//
+// Implementations:
+//   VsCodeBackend  — extension/src/backends/vscode/vscode-backend.ts
+//   TmuxBackend    — extension/src/backends/tmux/tmux-backend.ts (v0.9)
+
+// ─── Shared data types ────────────────────────────────────────────────────
+
+/** Options for creating a new terminal. */
+export interface BackendCreateOptions {
+  name?: string;
+  cwd?: string;
+  /** When true, the backend MUST capture all pty output to a log. Required for readLog. */
+  wrapped?: boolean;
+  shellPath?: string;
+  shellArgs?: string[];
+  env?: Record<string, string>;
+  /** AC-1: when present, propagated as CLAWS_TERMINAL_CORR_ID env var to the spawned pty
+   *  and used to emit system.terminal.ready on the first pty byte. */
+  correlationId?: string;
+}
+
+/** Snapshot of one terminal as seen by the backend. */
+export interface BackendTerminalInfo {
+  /** Backend-assigned stable string ID (e.g. "3" for VS Code, "claws:@3" for tmux window index). */
+  id: string;
+  name: string;
+  /** PID of the shell (or primary process) running inside the terminal. null if unknown. */
+  shellPid: number | null;
+  /** True if this terminal is capturing pty output to a log file. */
+  wrapped: boolean;
+  /** Absolute path to the log file if wrapped and file-based. null for in-memory capture. */
+  logPath: string | null;
+  /** Platform-specific status. */
+  status: 'alive' | 'closed' | 'unknown';
+  /** Vehicle lifecycle state (VsCodeBackend only — optional). */
+  vehicleState?: string;
+  /** Shell process PID (VS Code terminal.processId — separate from pty shellPid in wrapped case). */
+  pid?: number | null;
+  /** True if VS Code shell integration is active (VS Code only). */
+  hasShellIntegration?: boolean;
+  /** pty mode ('pty' | 'pipe' | 'none') — VsCodeBackend only. */
+  ptyMode?: string;
+}
+
+/** Result of a readLog call. Mirrors the existing CaptureSlice shape. */
+export interface BackendLogSlice {
+  bytes: string;
+  offset: number;
+  nextOffset: number;
+  totalSize: number;
+  truncated: boolean;
+}
+
+/** Options for sendText. */
+export interface BackendSendOptions {
+  /** Append a newline/Enter after the text. Default true. */
+  newline?: boolean;
+  /**
+   * Use bracketed-paste mode to wrap the text (prevents line-by-line
+   * fragmentation in shell/TUI programs). Default false.
+   */
+  paste?: boolean;
+}
+
+// ─── Events emitted by a TerminalBackend ─────────────────────────────────
+
+export interface TerminalCreatedEvent {
+  id: string;
+  name: string;
+  wrapped: boolean;
+  logPath: string | null;
+}
+
+export interface TerminalClosedEvent {
+  id: string;
+  /** Who initiated the close. Matches TerminalCloseOrigin enum in event-schemas.ts. */
+  origin: 'orchestrator' | 'user' | 'process_exit' | 'backend'
+        | 'marker' | 'error' | 'timeout' | 'pub_complete'
+        | 'wave_violation' | 'idle_timeout' | 'ttl_max';
+}
+
+export interface TerminalDataEvent {
+  id: string;
+  /** Raw pty bytes (may contain ANSI codes). */
+  data: string;
+}
+
+/** AC-1: emitted by a backend on the first pty byte of a wrapped terminal that was created
+ *  with a correlationId. Subscribers (server.ts) translate this into system.terminal.ready. */
+export interface TerminalReadyEvent {
+  id: string;
+  correlationId: string;
+}
+
+/** AF-AC Phase 1: emitted by a backend when the underlying pty process exits, before the
+ *  VS Code terminal UI is torn down. Fires from ClawsPty.handleExit via onProcessExitHook. */
+export interface TerminalProcessExitedEvent {
+  id: string;
+  correlationId: string | null;
+  exitCode: number;
+}
+
+export interface ForegroundProcessInfo {
+  pid: number | null;
+  /** Basename of the foreground command (e.g. 'claude', 'bash', 'vim'). null if unknown. */
+  basename: string | null;
+}
+
+// ─── The interface ────────────────────────────────────────────────────────
+
+/**
+ * TerminalBackend is the single seam between Claws core (server.ts, lifecycle,
+ * wave army) and the platform that actually runs terminal processes.
+ */
+export interface TerminalBackend {
+  // ── Lifecycle ──────────────────────────────────────────────────────────
+
+  /**
+   * Start the backend. Called once at server startup.
+   * Resolves when the backend is ready to accept commands.
+   */
+  start(): Promise<void>;
+
+  /**
+   * Tear down the backend. Called on extension deactivate or server stop.
+   * Does NOT close terminals — call closeTerminal for that.
+   */
+  dispose(): void;
+
+  // ── Terminal CRUD ──────────────────────────────────────────────────────
+
+  /**
+   * Create a new terminal. If opts.wrapped is true, the backend MUST pipe pty
+   * output so readLog works.
+   */
+  createTerminal(opts: BackendCreateOptions): Promise<{ id: string; logPath: string | null }>;
+
+  /** List all currently live terminals managed by this backend instance. */
+  listTerminals(): Promise<BackendTerminalInfo[]>;
+
+  /**
+   * Send text into the terminal's pty input stream.
+   * Must be a no-op if the terminal is not alive; MUST NOT throw.
+   */
+  sendText(id: string, text: string, opts?: BackendSendOptions): Promise<void>;
+
+  /**
+   * Close and destroy a terminal. Idempotent — does not throw if already closed.
+   */
+  closeTerminal(id: string, origin?: TerminalClosedEvent['origin']): Promise<void>;
+
+  // ── Log reading ────────────────────────────────────────────────────────
+
+  /**
+   * Read pty output from a wrapped terminal's capture log.
+   * Throws if the terminal is not wrapped.
+   * offset: byte position to read from (undefined → tail N bytes)
+   * limit: max bytes to return
+   * strip: strip ANSI escape codes before returning
+   */
+  readLog(id: string, offset: number | undefined, limit: number, strip: boolean): Promise<BackendLogSlice>;
+
+  // ── Process inspection ─────────────────────────────────────────────────
+
+  /**
+   * Return the foreground process running inside the terminal.
+   * Returns { pid: null, basename: null } if the backend cannot determine this.
+   */
+  getForegroundProcess(id: string): Promise<ForegroundProcessInfo>;
+
+  // ── Events ─────────────────────────────────────────────────────────────
+
+  on(event: 'terminal:created',          listener: (ev: TerminalCreatedEvent)         => void): this;
+  on(event: 'terminal:closed',           listener: (ev: TerminalClosedEvent)          => void): this;
+  on(event: 'terminal:data',             listener: (ev: TerminalDataEvent)            => void): this;
+  /** AC-1: first pty byte for a wrapped terminal created with correlationId. */
+  on(event: 'terminal:ready',            listener: (ev: TerminalReadyEvent)           => void): this;
+  /** AF-AC Phase 1: pty process exited, fires before VS Code UI teardown. */
+  on(event: 'terminal:process_exited',   listener: (ev: TerminalProcessExitedEvent)   => void): this;
+  off(event: string, listener: (...args: unknown[]) => void): this;
+
+  // ── Optional capabilities ──────────────────────────────────────────────
+
+  /**
+   * Bring the terminal into the foreground. No-op if not supported.
+   */
+  focusTerminal?(id: string): Promise<void>;
+
+  /**
+   * Execute a command with output capture and exit code detection.
+   * Optional — server falls back to sendText + readLog polling if absent.
+   */
+  execCommand?(id: string, command: string, timeoutMs: number): Promise<{
+    output: string;
+    exitCode: number | null;
+  }>;
+}
+
+/**
+ * Factory function signature. Each backend module exports a function matching this.
+ */
+export type TerminalBackendFactory = (opts: BackendFactoryOptions) => TerminalBackend;
+
+export interface BackendFactoryOptions {
+  workspaceRoot: string;
+  logger: (msg: string) => void;
+  captureStore: import('./capture-store').CaptureStore;
+}

package/extension/src/terminal-manager.ts

@@ -0,0 +1,395 @@
+import * as vscode from 'vscode';
+import { CaptureStore } from './capture-store';
+import { ClawsPty } from './backends/vscode/claws-pty';
+import { TerminalDescriptor } from './protocol';
+import { VehicleStateName, TerminalCloseOrigin } from './event-schemas';
+
+type StateChangeCallback = (id: string, from: VehicleStateName | null, to: VehicleStateName) => void;
+type ContentChangeCallback = (id: string, pid: number | null, basename: string | null) => void;
+type TerminalCloseCallback = (id: string, wrapped: boolean, origin: TerminalCloseOrigin) => void;
+
+const VALID_TRANSITIONS: Readonly<Record<VehicleStateName, readonly VehicleStateName[]>> = {
+  PROVISIONING: ['BOOTING', 'CLOSING'],
+  BOOTING:      ['READY', 'CLOSING'],
+  READY:        ['BUSY', 'IDLE', 'CLOSING'],
+  BUSY:         ['IDLE', 'CLOSING'],
+  IDLE:         ['BUSY', 'CLOSING'],
+  CLOSING:      ['CLOSED'],
+  CLOSED:       [],
+};
+
+const CONTENT_DETECTION_INTERVAL_MS = 2000;
+
+interface TerminalRecord {
+  id: string;
+  terminal: vscode.Terminal;
+  pty: ClawsPty | null;
+  wrapped: boolean;
+  logPath: string | null;
+  name: string;
+  vehicleState: VehicleStateName;
+  contentDetectionTimer: NodeJS.Timeout | null;
+  lastForegroundBasename: string | null | undefined;
+}
+
+export interface CreateOptions {
+  name?: string;
+  cwd?: string;
+  wrapped?: boolean;
+  shellPath?: string;
+  env?: Record<string, string>;
+  show?: boolean;
+  preserveFocus?: boolean;
+  /** AC-1: propagated as CLAWS_TERMINAL_CORR_ID env var to the spawned pty. */
+  correlationId?: string;
+  /** AC-1: called on the first pty byte; used by VsCodeBackend to emit terminal:ready. */
+  onFirstOutput?: (id: string) => void;
+  /** AF-AC Phase 1: called from ClawsPty.handleExit before closeEmitter.fire. */
+  onProcessExit?: (termId: string, code: number) => void;
+}
+
+// If VS Code never calls our Pseudoterminal.open() hook within this window
+// after a programmatic createWrapped, we treat the ClawsPty as orphaned and
+// dispose it. Covers the pathological case where the extension host crashes
+// or VS Code silently drops the terminal spec.
+const UNOPENED_PTY_TIMEOUT_MS = 60_000;
+// Interval at which we scan for stale un-opened PTYs. 10s is frequent enough
+// that cleanup feels responsive but infrequent enough that it's invisible
+// in perf traces.
+const UNOPENED_PTY_SCAN_INTERVAL_MS = 10_000;
+
+export class TerminalManager {
+  private readonly records = new Map<string, TerminalRecord>();
+  private readonly byTerminal = new Map<vscode.Terminal, string>();
+  private nextId = 1;
+  private unopenedScanTimer: NodeJS.Timeout | null = null;
+  private onStateChange: StateChangeCallback | null = null;
+  private onContentChange: ContentChangeCallback | null = null;
+  private onTerminalClose: TerminalCloseCallback | null = null;
+
+  constructor(
+    private readonly captureStore: CaptureStore,
+    private readonly logger: (msg: string) => void,
+  ) {
+    this.startUnopenedScan();
+  }
+
+  /** Wire the vehicle state change callback. Called by ClawsServer after construction. */
+  setStateChangeCallback(cb: StateChangeCallback): void {
+    this.onStateChange = cb;
+  }
+
+  /** Wire the content change callback. Called by ClawsServer after construction. */
+  setContentChangeCallback(cb: ContentChangeCallback): void {
+    this.onContentChange = cb;
+  }
+
+  /** Wire the terminal close callback. Fires for every Claws-tracked terminal on close. */
+  setTerminalCloseCallback(cb: TerminalCloseCallback): void {
+    this.onTerminalClose = cb;
+  }
+
+  private transitionState(rec: TerminalRecord, to: VehicleStateName): void {
+    const from = rec.vehicleState;
+    if (!VALID_TRANSITIONS[from]?.includes(to)) {
+      this.logger(`[terminal-manager] invalid state transition ${from} → ${to} for terminal ${rec.id}`);
+      return;
+    }
+    rec.vehicleState = to;
+    this.onStateChange?.(rec.id, from, to);
+  }
+
+  private emitInitialState(rec: TerminalRecord): void {
+    this.onStateChange?.(rec.id, null, rec.vehicleState);
+  }
+
+  private startContentDetection(rec: TerminalRecord): void {
+    if (rec.contentDetectionTimer || !rec.pty) return;
+    const poll = () => {
+      if (!rec.pty) return;
+      const { pid, basename } = rec.pty.getForegroundProcess();
+      if (basename !== rec.lastForegroundBasename) {
+        rec.lastForegroundBasename = basename;
+        this.onContentChange?.(rec.id, pid, basename);
+      }
+    };
+    // Fire immediately after a short delay to capture the initial shell state.
+    setTimeout(poll, 1500);
+    const timer = setInterval(poll, CONTENT_DETECTION_INTERVAL_MS);
+    if (typeof timer.unref === 'function') timer.unref();
+    rec.contentDetectionTimer = timer;
+  }
+
+  private stopContentDetection(rec: TerminalRecord): void {
+    if (rec.contentDetectionTimer) {
+      clearInterval(rec.contentDetectionTimer);
+      rec.contentDetectionTimer = null;
+    }
+  }
+
+  adoptExisting(terminals: readonly vscode.Terminal[]): void {
+    for (const t of terminals) this.idFor(t);
+  }
+
+  get terminalCount(): number { return this.records.size; }
+
+  idFor(terminal: vscode.Terminal): string {
+    const existing = this.byTerminal.get(terminal);
+    if (existing) return existing;
+    const id = String(this.nextId++);
+    this.byTerminal.set(terminal, id);
+    this.records.set(id, {
+      id,
+      terminal,
+      pty: null,
+      wrapped: false,
+      logPath: null,
+      name: terminal.name,
+      vehicleState: 'PROVISIONING',
+      contentDetectionTimer: null,
+      lastForegroundBasename: undefined,
+    });
+    return id;
+  }
+
+  terminalById(id: string | number): vscode.Terminal | null {
+    return this.records.get(String(id))?.terminal ?? null;
+  }
+
+  recordById(id: string | number): TerminalRecord | null {
+    return this.records.get(String(id)) ?? null;
+  }
+
+  /**
+   * LH-9: Snapshot of currently-tracked terminal IDs. Used for boot
+   * reconciliation against lifecycle-state.json — any spawned_worker not
+   * in this set has died while we were down and should be marked closed.
+   */
+  liveTerminalIds(): Set<string> {
+    return new Set(this.records.keys());
+  }
+
+  /**
+   * Describe a terminal WITHOUT mutating state. If the terminal has never
+   * been adopted by the manager (no entry in byTerminal), we return a
+   * minimal descriptor with `status: 'unknown'` and no stable id. Adoption
+   * happens elsewhere — typically in the `onDidOpenTerminal` event handler.
+   */
+  async describe(terminal: vscode.Terminal): Promise<TerminalDescriptor> {
+    const existingId = this.byTerminal.get(terminal);
+    let pid: number | null = null;
+    try {
+      const p = await terminal.processId;
+      pid = p ?? null;
+    } catch {
+      pid = null;
+    }
+    if (!existingId) {
+      return {
+        id: '',
+        name: terminal.name,
+        pid,
+        ptyPid: null,
+        hasShellIntegration: !!terminal.shellIntegration,
+        active: vscode.window.activeTerminal === terminal,
+        logPath: null,
+        wrapped: false,
+        status: 'unknown',
+      };
+    }
+    const rec = this.records.get(existingId);
+    // R7: surface the real shell pid from our ClawsPty (ptyProc.pid or childProc.pid).
+    // VS Code's `terminal.processId` is null for Pseudoterminal-based terminals.
+    const ptyPid = rec?.pty?.pid ?? null;
+    const ptyMode = rec?.pty?.mode;
+    return {
+      id: existingId,
+      name: terminal.name,
+      pid,
+      ptyPid,
+      ptyMode,
+      hasShellIntegration: !!terminal.shellIntegration,
+      active: vscode.window.activeTerminal === terminal,
+      logPath: rec?.logPath ?? null,
+      wrapped: rec?.wrapped ?? false,
+      status: 'adopted',
+      vehicleState: rec?.vehicleState,
+    };
+  }
+
+  async describeAll(): Promise<TerminalDescriptor[]> {
+    const out: TerminalDescriptor[] = [];
+    for (const t of vscode.window.terminals) {
+      out.push(await this.describe(t));
+    }
+    return out;
+  }
+
+  createWrapped(options: CreateOptions): { id: string; terminal: vscode.Terminal; pty: ClawsPty } {
+    const id = String(this.nextId++);
+    const rec: TerminalRecord = {
+      id,
+      terminal: null as unknown as vscode.Terminal, // set below after createTerminal
+      pty: null,
+      wrapped: true,
+      logPath: null,
+      name: options.name || `Claws ${id}`,
+      vehicleState: 'PROVISIONING',
+      contentDetectionTimer: null,
+      lastForegroundBasename: undefined,
+    };
+    this.records.set(id, rec);
+
+    // Emit PROVISIONING immediately, then transition to BOOTING synchronously.
+    this.emitInitialState(rec);
+    this.transitionState(rec, 'BOOTING');
+
+    const pty = new ClawsPty({
+      terminalId: id,
+      shellPath: options.shellPath,
+      cwd: options.cwd,
+      env: options.env,
+      correlationId: options.correlationId,
+      captureStore: this.captureStore,
+      logger: this.logger,
+      // When VS Code calls open() on the Pseudoterminal, flip to READY and
+      // start polling for foreground process changes.
+      onOpenHook: () => {
+        this.transitionState(rec, 'READY');
+        this.startContentDetection(rec);
+      },
+      onFirstOutputHook: options.onFirstOutput ? () => options.onFirstOutput!(id) : undefined,
+      onProcessExitHook: options.onProcessExit ? (code: number) => options.onProcessExit!(id, code) : undefined,
+    });
+    rec.pty = pty;
+
+    const terminal = vscode.window.createTerminal({
+      name: options.name || `Claws ${id}`,
+      pty,
+    });
+    rec.terminal = terminal;
+    this.byTerminal.set(terminal, id);
+
+    if (options.show !== false) terminal.show(options.preserveFocus !== false);
+    return { id, terminal, pty };
+  }
+
+  createStandard(options: CreateOptions): { id: string; terminal: vscode.Terminal } {
+    const id = String(this.nextId++);
+    const terminal = vscode.window.createTerminal({
+      name: options.name || `Claws ${id}`,
+      cwd: options.cwd,
+      shellPath: options.shellPath,
+      env: options.env,
+    });
+    this.byTerminal.set(terminal, id);
+    this.records.set(id, {
+      id,
+      terminal,
+      pty: null,
+      wrapped: false,
+      logPath: null,
+      name: terminal.name,
+      vehicleState: 'PROVISIONING',
+      contentDetectionTimer: null,
+      lastForegroundBasename: undefined,
+    });
+    if (options.show !== false) terminal.show(options.preserveFocus !== false);
+    return { id, terminal };
+  }
+
+  close(id: string | number, origin: TerminalCloseOrigin = 'orchestrator'): boolean {
+    const key = String(id);
+    const rec = this.records.get(key);
+    if (!rec) return false;
+    this.stopContentDetection(rec);
+    this.transitionState(rec, 'CLOSING');
+    this.transitionState(rec, 'CLOSED');
+    // Invoke callback synchronously BEFORE dispose+map mutation. VS Code fires
+    // onDidCloseTerminal asynchronously, so by the time onTerminalClosed runs,
+    // byTerminal.delete has already cleared the entry and the function bails at
+    // its early-return guard — the callback was never reached. This direct call
+    // ensures system.terminal.closed always emits for programmatic closes.
+    // See .local/audits/lifecycle-silent-mutation-trace.md.
+    this.onTerminalClose?.(key, rec.wrapped, origin);
+    try { rec.terminal.dispose(); } catch { /* ignore */ }
+    this.byTerminal.delete(rec.terminal);
+    this.records.delete(key);
+    this.captureStore.clear(key);
+    return true;
+  }
+
+  onTerminalClosed(terminal: vscode.Terminal): void {
+    const id = this.byTerminal.get(terminal);
+    if (!id) return;
+    this.byTerminal.delete(terminal);
+    const rec = this.records.get(id);
+    if (rec) {
+      this.stopContentDetection(rec);
+      this.transitionState(rec, 'CLOSING');
+      this.transitionState(rec, 'CLOSED');
+      this.onTerminalClose?.(id, rec.wrapped, 'user');
+    }
+    if (rec?.pty) rec.pty.close();
+    this.records.delete(id);
+    this.captureStore.clear(id);
+  }
+
+  reserveNextId(): string {
+    return String(this.nextId++);
+  }
+
+  linkProfileTerminal(id: string, terminal: vscode.Terminal, pty: ClawsPty): void {
+    this.byTerminal.set(terminal, id);
+    this.records.set(id, {
+      id,
+      terminal,
+      pty,
+      wrapped: true,
+      logPath: null,
+      name: terminal.name,
+      vehicleState: 'PROVISIONING',
+      contentDetectionTimer: null,
+      lastForegroundBasename: undefined,
+    });
+  }
+
+  /**
+   * Tear down internal timers and dispose any tracked ClawsPty instances.
+   * Call this during extension deactivation.
+   */
+  dispose(): void {
+    for (const rec of this.records.values()) {
+      this.stopContentDetection(rec);
+    }
+    if (this.unopenedScanTimer) {
+      clearInterval(this.unopenedScanTimer);
+      this.unopenedScanTimer = null;
+    }
+  }
+
+  private startUnopenedScan(): void {
+    // setInterval is `unref`ed so it never holds the event loop open on its
+    // own — matters for unit-test processes that shouldn't hang on exit.
+    const timer = setInterval(() => this.scanUnopenedPtys(), UNOPENED_PTY_SCAN_INTERVAL_MS);
+    if (typeof timer.unref === 'function') timer.unref();
+    this.unopenedScanTimer = timer;
+  }
+
+  private scanUnopenedPtys(): void {
+    for (const [id, rec] of this.records) {
+      if (!rec.pty) continue;
+      if (rec.pty.hasOpened()) continue;
+      if (rec.pty.ageMs() < UNOPENED_PTY_TIMEOUT_MS) continue;
+      this.logger(
+        `[terminal-manager] pty id=${id} never opened after ${rec.pty.ageMs()}ms — disposing orphan`,
+      );
+      this.stopContentDetection(rec);
+      try { rec.pty.close(); } catch { /* ignore */ }
+      try { rec.terminal.dispose(); } catch { /* ignore */ }
+      this.byTerminal.delete(rec.terminal);
+      this.records.delete(id);
+      this.captureStore.clear(id);
+    }
+  }
+}