@volter/supercode-terminal 0.2.30 → 0.2.31

package/index.d.ts

@@ -72,6 +72,42 @@ export class TmuxTerminalHost {
   dispose(): void;
 }
 
+/**
+ * Terminal panes without tmux (Windows): ConPTY children of this process, each with a headless screen for
+ * capture and attach. Same surface as TmuxTerminalHost; panes end with the host.
+ */
+export class PtyTerminalHost {
+  constructor(options?: { attachmentTtlMs?: number });
+  listSessions(): Promise<TerminalSession[]>;
+  createSession(input: {
+    command: TmuxCommand;
+    contextKey?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    name?: string;
+  }): Promise<TerminalSession>;
+  capture(sessionId: string, options?: { lines?: number; preserveEscapes?: boolean }): string;
+  sendInput(
+    sessionId: string,
+    data: string,
+    options?: { deadlineMs?: number; submitMode?: 'retry' | 'single' },
+  ): Promise<TerminalInputDelivery>;
+  bindContext(sessionId: string, contextKey: string): Promise<TerminalSession>;
+  /** A ConPTY pane has no window to rename; returns its label. */
+  renameWindow(sessionId: string, title?: string | null): string;
+  issueAttachment(sessionId: string, options?: { mode?: 'observe' | 'control' }): TerminalAttachmentGrant;
+  attachSocket(
+    attachmentId: string,
+    socket: unknown,
+    size?: { cols?: number; rows?: number },
+  ): Promise<TerminalAttachment>;
+  /** Unsupported: throws `unsupported`. */
+  localAttachLaunch(sessionId: string): StructuredLaunch;
+  openLocalTerminal(sessionId: string): Promise<void>;
+  closeSession(sessionId: string): void;
+  dispose(): void;
+}
+
 export class TerminalWebSocketBridge {
   constructor(options: {
     host: Pick<TmuxTerminalHost, 'issueAttachment' | 'attachSocket'>;

package/index.mjs

@@ -1,4 +1,6 @@
+import { execFile, spawn, spawnSync } from 'node:child_process';
 import { randomBytes, randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
 import { createServer as defaultCreateServer } from 'node:http';
 
 import { NativeTerminalSessionHost } from './substrate/native-host.js';
@@ -431,6 +433,626 @@ export class TmuxTerminalHost {
   }
 }
 
+// The submit cadence tmux.js keeps for a submitted line: one Enter after the paste settles, or three spaced ones.
+const SINGLE_SUBMIT_DELAY_MS = 500;
+const SUBMITTED_LINE_DELAYS_MS = [500, 1500, 3500];
+const PTY_DEFAULT_SIZE = Object.freeze({ cols: 80, rows: 24 });
+const PTY_SCROLLBACK = 5_000;
+// How long one read of the Windows process table answers every pane's activeCommand: the read costs a
+// PowerShell start, and panes are listed on every attention and pane call.
+const PROCESS_TABLE_TTL_MS = 3_000;
+// The shells a pane's root may be: its activeCommand is the first process beneath them that is not one.
+const PTY_SHELLS = new Set(['cmd', 'powershell', 'pwsh', 'bash', 'sh', 'wsl', 'nu']);
+// Console hosts appear as children of a pane's processes and are never its command.
+const CONSOLE_HOSTS = new Set(['conhost.exe', 'openconsole.exe']);
+/**
+ * Ends the process trees of the roots in SUPERCODE_SWEEP_ROOTS (`pid:ticks:exact;…`, ticks being CIM CreationDate
+ * ticks). A root is taken while it still runs as itself: by its exact start when that was read, else only if it
+ * started no earlier than a moment before its pane was spawned. Beneath a root, a process counts only if it started
+ * no earlier than its parent (ParentProcessId). A root that has ended is left, with whatever it detached, unless
+ * SUPERCODE_SWEEP_BEFORE names the moment the host died: the host's death closes every pane's console, ending the
+ * roots with it, so then a dead root's descendants are taken too, but only those started before that moment, which
+ * a stranger reusing the root's pid afterwards cannot have.
+ */
+const SWEEP_SCRIPT = [
+  '$all = @(Get-CimInstance Win32_Process | ForEach-Object { [pscustomobject]@{ Id = [int]$_.ProcessId; Parent = [int]$_.ParentProcessId; T = $_.CreationDate.Ticks } })',
+  '$kill = New-Object System.Collections.Generic.List[int]',
+  'foreach ($root in ($env:SUPERCODE_SWEEP_ROOTS -split ";" | Where-Object { $_ })) {',
+  '  $pid0, $t0, $exact = $root -split ":"',
+  '  $self = $all | Where-Object { $_.Id -eq [int]$pid0 -and (($exact -eq "1" -and $_.T -eq [long]$t0) -or ($exact -ne "1" -and $_.T -ge [long]$t0)) } | Select-Object -First 1',
+  '  $before = if ($env:SUPERCODE_SWEEP_BEFORE) { [long]$env:SUPERCODE_SWEEP_BEFORE } else { [long]::MaxValue }',
+  '  if ($self) { $kill.Add($self.Id) } elseif ($env:SUPERCODE_SWEEP_BEFORE) { $self = [pscustomobject]@{ Id = [int]$pid0; T = [long]$t0 } } else { continue }',
+  '  $queue = New-Object System.Collections.Generic.Queue[object]; $queue.Enqueue($self)',
+  '  while ($queue.Count) { $p = $queue.Dequeue(); foreach ($c in ($all | Where-Object { $_.Parent -eq $p.Id -and $_.T -ge $p.T -and $_.T -le $before })) { if (-not $kill.Contains($c.Id)) { $kill.Add($c.Id); $queue.Enqueue($c) } } }',
+  '}',
+  'foreach ($id in $kill) { Stop-Process -Id $id -Force -ErrorAction SilentlyContinue }',
+].join('\n');
+/**
+ * The pane watchdog, a detached node process per host. A process cannot hold a Windows Job Object without a native
+ * addon, so nothing makes the OS end a pane's tree when the daemon dies; this does instead. Its stdin is a pipe from
+ * the host, which sends each change to the live panes as a line of sweep roots and `bye` when it disposes cleanly.
+ * When the pipe ends without a `bye`, the host is gone (the OS closes the pipe whatever killed it), and the watchdog
+ * sweeps the last panes it was told of, up to that moment. No file and no pid: neither can be lost or reused under it.
+ */
+const WATCHDOG_SOURCE = `
+const { execFileSync } = require('node:child_process');
+const script = process.argv[1];
+let roots = '', pending = '', finished = false;
+// Now, as CIM gives a process's CreationDate (local-time .NET ticks), with a second's slack for a root still dying.
+const cutoff = () => { const ms = Date.now() + 1000; return String(BigInt(ms - new Date(ms).getTimezoneOffset() * 60000) * 10000n + 621355968000000000n); };
+const sweep = () => {
+  if (finished) return;
+  finished = true;
+  try { if (roots) execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { env: { ...process.env, SUPERCODE_SWEEP_ROOTS: roots, SUPERCODE_SWEEP_BEFORE: cutoff() }, stdio: 'ignore', windowsHide: true, timeout: 60000 }); }
+  finally { process.exit(0); }
+};
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  pending += chunk;
+  for (let end; (end = pending.indexOf('\\n')) >= 0; pending = pending.slice(end + 1)) {
+    const line = pending.slice(0, end);
+    if (line === 'bye') { finished = true; process.exit(0); }
+    roots = line;
+  }
+});
+for (const event of ['end', 'close', 'error']) process.stdin.on(event, sweep);
+`;
+
+/**
+ * Terminal panes where there is no tmux (Windows): each pane is a ConPTY child of this process, and a headless
+ * xterm keeps its screen for `capture` and for a viewer who attaches mid-session. The surface is
+ * TmuxTerminalHost's, so a daemon drives either the same way. Panes live as long as this host: tmux panes
+ * outlive the daemon that launched them, these end with it (a watchdog ends them if the host dies without
+ * disposing), so every pane here is this host's own. As with tmux's `remain-on-exit failed`, a pane whose program
+ * fails stays listed and capturable, marked dead, until it is closed; one that exits cleanly leaves at once.
+ */
+export class PtyTerminalHost {
+  #attachments = new Map();
+  #liveAttachments = new Set();
+  #now;
+  #processTable = null;
+  #processTableRead = null;
+  #randomToken;
+  #sessions = new Map();
+  #ttlMs;
+  #watchdog = null;
+
+  constructor(options = {}) {
+    this.#now = options.now ?? Date.now;
+    this.#randomToken = options.randomToken ?? randomToken;
+    this.#ttlMs = positiveInteger(options.attachmentTtlMs ?? DEFAULT_ATTACHMENT_TTL_MS, 'attachmentTtlMs');
+  }
+
+  async listSessions() {
+    this.#pruneAttachments();
+    const table = this.#sessions.size ? await this.#readProcessTable() : null;
+    return [...this.#sessions.values()].map((entry) => this.#describe(entry, table));
+  }
+
+  async createSession(input) {
+    const name = input.name ?? `supercode-${this.#randomToken().slice(0, 16)}`;
+    if (!SESSION_NAME.test(name)) {
+      throw new TerminalHostError('invalid_session_name', 'A pane name must contain 1–64 letters, numbers, underscores, or hyphens.');
+    }
+    if (!input.command?.program) {
+      throw new TerminalHostError('invalid_command', 'A structured command program is required.');
+    }
+    if (input.contextKey !== undefined) assertContextKey(input.contextKey);
+    if ([...this.#sessions.values()].some((entry) => entry.name === name)) {
+      throw new TerminalHostError('session_exists', `A pane named ${name} already exists.`);
+    }
+    const [{ default: pty }, { default: headless }, { default: serialize }] = await Promise.all([
+      import('@homebridge/node-pty-prebuilt-multiarch'),
+      import('@xterm/headless'),
+      import('@xterm/addon-serialize'),
+    ]);
+    const env = { ...process.env, ...(input.env ?? {}) };
+    const { file, args } = windowsLaunch(input.command.program, input.command.arguments ?? [], env);
+    // The watchdog is running before the pane is, and the pane is on its list the moment it exists.
+    this.#startWatchdog();
+    let child;
+    const spawnedAt = Date.now();
+    try {
+      child = pty.spawn(file, args, { cols: PTY_DEFAULT_SIZE.cols, rows: PTY_DEFAULT_SIZE.rows, cwd: input.cwd ?? process.cwd(), env, name: 'xterm-256color' });
+    } catch (error) {
+      throw new TerminalHostError('session_not_found', `The pane could not start ${input.command.program}: ${errorMessage(error)}`);
+    }
+    const screen = new headless.Terminal({ allowProposedApi: true, cols: PTY_DEFAULT_SIZE.cols, rows: PTY_DEFAULT_SIZE.rows, scrollback: PTY_SCROLLBACK });
+    const serializer = new serialize.SerializeAddon();
+    screen.loadAddon(serializer);
+    const id = `scts_${this.#randomToken()}`;
+    const entry = {
+      // Replaced by the root's own start once the process table has it; a program gone by then keeps this floor.
+      child, contextKey: input.contextKey ?? null, created: cimTicks(spawnedAt - 2_000), exact: false, cwd: input.cwd ?? process.cwd(), exit: null, gone: new Set(),
+      id, listeners: new Set(), name, program: input.command.program, screen, serializer, settled: null,
+    };
+    const settled = new Promise((resolve) => { entry.settled = resolve; });
+    // Output reaches viewers once the screen has taken it, so a viewer's snapshot and its live output never
+    // overlap or leave a gap (attachSocket reads the snapshot in the same order).
+    child.onData((data) => {
+      if (!this.#sessions.has(id)) return;
+      screen.write(data, () => { for (const listener of entry.listeners) listener.output(data); });
+    });
+    child.onExit(({ exitCode, signal }) => {
+      if (!this.#sessions.has(id) || entry.exit) return releasePane(child);
+      const settle = () => {
+        if (!this.#sessions.has(id) || entry.exit) return;
+        entry.exit = { exitCode, signal };
+        // Nothing is swept when a pane's program ends by itself: what it deliberately detached (a browser, a
+        // server) outlives it, as it outlives a tmux pane. What stayed in the pane's console ends with the console.
+        // Only closing a pane, or its daemon dying, ends a whole tree.
+        releasePane(child);
+        this.#tellExit(entry);
+        this.#writeWatchList();
+        if (exitCode === 0) this.#forget(entry);
+        entry.settled();
+      };
+      screen.write('', settle);
+    });
+    this.#sessions.set(id, entry);
+    this.#writeWatchList();
+    // A table read that began before the spawn cannot hold the new root, so this one starts now.
+    const table = await this.#readProcessTable({ fresh: true });
+    const root = table?.find((row) => row.pid === child.pid);
+    if (root) Object.assign(entry, { created: root.ticks, exact: true });
+    // A program that already ended cleanly left no pane, as with tmux. node-pty reports an exit about a second
+    // after it happens (it flushes the output first), so a root missing from the table is waited on.
+    else if (table) await Promise.race([settled, sleep(3_000)]);
+    if (!this.#sessions.has(id)) {
+      throw new TerminalHostError('session_not_found', `${input.command.program} exited before its pane could be attached.`);
+    }
+    this.#writeWatchList();
+    return this.#describe(entry, table);
+  }
+
+  capture(sessionId, options = {}) {
+    const { screen } = this.#entry(sessionId);
+    if (options.lines !== undefined && (!Number.isInteger(options.lines) || options.lines < 1)) {
+      throw new Error('--lines must be a positive integer.');
+    }
+    // capture-pane's range: the visible screen of the active buffer (the alternate one while a full-screen
+    // program runs), plus `lines` of history above it when asked. Rows stay rows, wrapped or not.
+    const buffer = screen.buffer.active;
+    const start = Math.max(0, buffer.baseY - (options.lines ?? 0));
+    const end = buffer.baseY + screen.rows - 1;
+    const lines = [];
+    const cell = buffer.getNullCell();
+    for (let row = start; row <= end; row += 1) {
+      const line = buffer.getLine(row);
+      lines.push(!line ? '' : options.preserveEscapes ? styledRow(line, cell) : line.translateToString(true));
+    }
+    return `${lines.join('\n')}\n`;
+  }
+
+  async sendInput(sessionId, data, options = {}) {
+    const entry = this.#live(sessionId);
+    if (typeof data !== 'string') throw new Error('Input data must be a string.');
+    const deadline = options.deadlineMs;
+    const write = (bytes) => {
+      if (deadline !== undefined && deadline - Date.now() <= 0) throw new Error('Terminal input expired before delivery.');
+      this.#live(entry.id).child.write(bytes);
+    };
+    const submit = async () => {
+      for (const delayMs of options.submitMode === 'single' ? [SINGLE_SUBMIT_DELAY_MS] : SUBMITTED_LINE_DELAYS_MS) {
+        await sleep(delayMs);
+        write('\r');
+      }
+    };
+    const submittedText = defaultTmux.submittedTextFromInput(data);
+    if (submittedText !== undefined) {
+      if (submittedText.length > 0) {
+        // tmux's `paste-buffer -p`: bracketed when the program asked for bracketed paste, else newlines as Enter.
+        write(entry.screen.modes.bracketedPasteMode ? `\u001b[200~${submittedText}\u001b[201~` : submittedText.replace(/\n/g, '\r'));
+        await submit();
+        return 'submitted-paste';
+      }
+      await submit();
+      return 'submitted-line';
+    }
+    // tmux sends a newline in a keystream as Enter.
+    write(data.replace(/\n/g, '\r'));
+    return 'keystream';
+  }
+
+  async bindContext(sessionId, contextKey) {
+    assertContextKey(contextKey);
+    this.#entry(sessionId).contextKey = contextKey;
+    const bound = (await this.listSessions()).find((session) => session.id === sessionId);
+    if (!bound) throw new TerminalHostError('session_not_found', 'The pane exited before it could be bound.');
+    return bound;
+  }
+
+  /** There is no window to rename: a pane's title lives with the daemon that asked. */
+  renameWindow(sessionId) {
+    return this.#entry(sessionId).name;
+  }
+
+  issueAttachment(sessionId, options = {}) {
+    this.#pruneAttachments();
+    const entry = this.#entry(sessionId);
+    const mode = options.mode ?? 'observe';
+    if (mode !== 'observe' && mode !== 'control') {
+      throw new TerminalHostError('invalid_attachment_mode', 'Attachment mode must be observe or control.');
+    }
+    const id = `sct_${this.#randomToken()}`;
+    const expiresAt = this.#now() + this.#ttlMs;
+    this.#attachments.set(id, { expiresAt, mode, sessionId: entry.id });
+    return Object.freeze({ expiresAt, id, mode });
+  }
+
+  /** The tmux-stream protocol over a pane: `hello`, the current screen, then live `output` and `exit`. */
+  async attachSocket(attachmentId, socket, size = {}) {
+    this.#pruneAttachments();
+    const grant = this.#attachments.get(attachmentId);
+    this.#attachments.delete(attachmentId);
+    if (!grant) {
+      throw new TerminalHostError('attachment_invalid', 'The terminal attachment is invalid, expired, or already used.');
+    }
+    const entry = this.#entry(grant.sessionId);
+    // A remote viewer names the size: bounded like a resize, or one attach could make the screen any size.
+    for (const label of ['cols', 'rows']) {
+      if (size[label] !== undefined) {
+        try { assertDimension(size[label], label); } catch (error) { throw new TerminalHostError('invalid_size', error.message); }
+      }
+    }
+    const readOnly = grant.mode === 'observe';
+    // Observers take the pane's size as it is: a read-only mirror never reflows someone else's terminal.
+    if (!readOnly && !entry.exit && size.cols && size.rows) resizePane(entry, size.cols, size.rows);
+    const send = (value) => { if (socket.readyState === socket.OPEN) socket.send(JSON.stringify(value)); };
+    const refuse = (error) => {
+      send({ message: `\r\n[supercode] ${errorMessage(error)}\r\n`, type: 'error' });
+      return error;
+    };
+    let disposed = false;
+    const listener = {
+      exit: (exitCode, signal) => {
+        send({ exitCode, signal, type: 'exit' });
+        if (socket.readyState === socket.OPEN) socket.close(1000, 'pane exited');
+        wrapped.dispose();
+      },
+      output: (data) => send({ data: wellFormed(data), type: 'output' }),
+    };
+    const onMessage = (raw) => {
+      try {
+        const message = JSON.parse(raw.toString());
+        if (message.type === 'resize') {
+          if (readOnly) throw new Error('Read-only terminal attachments cannot resize the pane.');
+          assertDimension(message.cols, 'cols');
+          assertDimension(message.rows, 'rows');
+          if (this.#sessions.has(entry.id) && !entry.exit) resizePane(entry, message.cols, message.rows);
+          return;
+        }
+        if (message.type !== 'input') throw new Error(`Unsupported websocket message type: ${message.type}`);
+        if (typeof message.data !== 'string') throw new Error('Input message did not include string data.');
+        if (readOnly) {
+          refuse(new TerminalHostError('input_not_allowed', 'This is a read-only terminal attachment.'));
+          socket.close(1008, 'terminal access ended');
+          return;
+        }
+        if (this.#sessions.has(entry.id) && !entry.exit) entry.child.write(message.data);
+      } catch (error) {
+        refuse(error);
+      }
+    };
+    const onClose = () => wrapped.dispose();
+    const wrapped = {
+      dispose: () => {
+        if (disposed) return;
+        disposed = true;
+        socket?.off?.('close', onClose);
+        socket?.off?.('message', onMessage);
+        entry.listeners.delete(listener);
+        this.#liveAttachments.delete(wrapped);
+      },
+    };
+    socket?.once?.('close', onClose);
+    send({ cols: entry.screen.cols, rows: entry.screen.rows, type: 'hello' });
+    // The screen as it stands once the output already received has been parsed, and live output from exactly
+    // there: both happen in the screen's own write order. A pane closed meanwhile ends the wait.
+    const attached = await new Promise((resolve) => {
+      const gone = () => resolve(false);
+      entry.gone.add(gone);
+      entry.screen.write('', () => {
+        entry.gone.delete(gone);
+        if (disposed || !this.#sessions.has(entry.id)) return resolve(false);
+        send({ data: wellFormed(entry.serializer.serialize({ scrollback: PTY_SCROLLBACK })), type: 'output' });
+        if (entry.exit) listener.exit(entry.exit.exitCode, entry.exit.signal);
+        else entry.listeners.add(listener);
+        resolve(true);
+      });
+    });
+    if (!attached && !disposed) {
+      wrapped.dispose();
+      throw new TerminalHostError('session_not_found', 'The pane closed while it was being attached.');
+    }
+    if (!disposed) {
+      this.#liveAttachments.add(wrapped);
+      socket?.on?.('message', onMessage);
+    }
+    return wrapped;
+  }
+
+  localAttachLaunch() {
+    throw new TerminalHostError('unsupported', 'A pane on this platform has no local terminal to attach: open it through a viewer.');
+  }
+
+  async openLocalTerminal(sessionId) {
+    this.localAttachLaunch(sessionId);
+  }
+
+  closeSession(sessionId) {
+    const entry = this.#entry(sessionId);
+    if (!entry.exit) endPane(entry.child);
+    this.#forget(entry);
+    this.#writeWatchList();
+  }
+
+  /** The daemon is going, and its panes with it: none is left running unowned. */
+  dispose() {
+    for (const attachment of [...this.#liveAttachments]) attachment.dispose();
+    for (const entry of [...this.#sessions.values()]) {
+      if (!entry.exit) endPane(entry.child);
+      this.#forget(entry);
+    }
+    this.#attachments.clear();
+    // Released cleanly: the watchdog leaves without sweeping.
+    this.#watchdog?.stdin.end('bye\n');
+    this.#watchdog = null;
+  }
+
+  #describe(entry, table) {
+    return Object.freeze({
+      // A dead pane runs nothing; otherwise the first program beneath its shell, else what it launched.
+      activeCommand: entry.exit ? null : foregroundCommand(entry.child.pid, table) ?? commandName(entry.program),
+      contextKey: entry.contextKey,
+      // The launch directory: another process's current directory is not readable here as tmux reads it.
+      cwd: entry.cwd,
+      dead: entry.exit !== null,
+      id: entry.id,
+      label: entry.name,
+      owned: true,
+      rootPid: entry.exit ? null : entry.child.pid,
+      size: Object.freeze({ columns: entry.screen.cols, rows: entry.screen.rows }),
+    });
+  }
+
+  #entry(id) {
+    const entry = this.#sessions.get(id);
+    if (!entry) throw new TerminalHostError('session_not_found', 'The pane no longer exists.');
+    return entry;
+  }
+
+  /** A pane whose program still runs. */
+  #live(id) {
+    const entry = this.#entry(id);
+    if (entry.exit) throw new TerminalHostError('session_not_found', `The pane's program has exited (${entry.exit.exitCode}).`);
+    return entry;
+  }
+
+  #forget(entry) {
+    if (!this.#sessions.delete(entry.id)) return;
+    for (const [id, grant] of this.#attachments) if (grant.sessionId === entry.id) this.#attachments.delete(id);
+    this.#tellExit(entry);
+    for (const gone of [...entry.gone]) gone();
+    entry.gone.clear();
+    entry.screen.dispose();
+  }
+
+  /** Every viewer hears the pane end, once. */
+  #tellExit(entry) {
+    const { exitCode = 0, signal } = entry.exit ?? {};
+    for (const listener of [...entry.listeners]) listener.exit(exitCode, signal);
+    entry.listeners.clear();
+  }
+
+  #pruneAttachments() {
+    const now = this.#now();
+    for (const [id, grant] of this.#attachments) if (grant.expiresAt <= now) this.#attachments.delete(id);
+  }
+
+  /**
+   * The process table, read at most once per PROCESS_TABLE_TTL_MS and shared by every caller that asks while a read
+   * runs. `fresh` starts a read now, for a caller that needs a process started since the last one began.
+   */
+  async #readProcessTable({ fresh = false } = {}) {
+    if (!fresh && this.#processTable && this.#now() - this.#processTable.at < PROCESS_TABLE_TTL_MS) return this.#processTable.rows;
+    if (!fresh && this.#processTableRead) return this.#processTableRead;
+    const at = this.#now();
+    const read = new Promise((resolve) => {
+      execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+        'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId) $($_.CreationDate.Ticks) $($_.Name)" }'],
+      { timeout: 10_000, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => {
+        if (error) return resolve(null);
+        // `ticks` is exact (past 2^53, so text); `created` orders processes, where microseconds do not matter.
+        resolve(stdout.split(/\r?\n/).map((line) => /^(\d+) (\d+) (\d*) (.+)$/.exec(line.trim())).filter(Boolean)
+          .map(([, pid, parent, ticks, name]) => ({ pid: Number(pid), parent: Number(parent), created: Number(ticks) || 0, ticks: ticks || '0', name })));
+      });
+    }).then((rows) => {
+      if (this.#processTableRead === read) this.#processTableRead = null;
+      if (!this.#processTable || this.#processTable.at <= at) this.#processTable = { at, rows };
+      return rows;
+    });
+    this.#processTableRead = read;
+    return read;
+  }
+
+  #startWatchdog() {
+    if (this.#watchdog) return;
+    this.#watchdog = spawn(process.execPath, ['-e', WATCHDOG_SOURCE, SWEEP_SCRIPT], { detached: true, stdio: ['pipe', 'ignore', 'ignore'], windowsHide: true });
+    this.#watchdog.stdin.on('error', () => {});
+    // Neither the watchdog nor its pipe keeps this process running.
+    this.#watchdog.unref();
+    this.#watchdog.stdin.unref?.();
+  }
+
+  /** Tell the watchdog the live panes, each named exactly where the table gave its start. */
+  #writeWatchList() {
+    if (!this.#watchdog) return;
+    const roots = [...this.#sessions.values()].filter((entry) => !entry.exit).map((entry) => `${entry.child.pid}:${entry.created}:${entry.exact ? 1 : 0}`);
+    this.#watchdog.stdin.write(`${roots.join(';')}\n`);
+  }
+}
+
+/** What a Windows pane runs: the program itself, or a `.cmd`/`.bat` (npm's shims: `claude`, `codex`) through cmd. */
+function windowsLaunch(program, args, env) {
+  const resolved = resolveWindowsProgram(program, env);
+  if (!/\.(cmd|bat)$/i.test(resolved)) return { file: resolved, args };
+  const line = [resolved, ...args].map(batchArgument).join(' ');
+  // A string is node-pty's raw command line: `/s` makes cmd take everything between the outer quotes as it is.
+  // As Rust runs batch files: `/v:OFF` so a machine that turns on delayed expansion cannot expand `!x!` or eat
+  // `^`, `/e:ON` for the command extensions the `%%cd:~,%` escape relies on, `/d` for no AutoRun.
+  return { file: env.ComSpec ?? 'cmd.exe', args: `/e:ON /v:OFF /d /s /c "${line}"` };
+}
+
+function resolveWindowsProgram(program, env) {
+  if (/[\\/]/.test(program) || /\.[^.\\/]+$/.test(program)) return program;
+  const extensions = (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
+  for (const directory of (env.PATH ?? env.Path ?? '').split(';').filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = `${directory.replace(/[\\/]+$/, '')}\\${program}${extension.toLowerCase()}`;
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return program;
+}
+
+/**
+ * One argument of a batch file's command line, quoted so cmd passes it on whole and the program behind the batch
+ * file (a C runtime's parser) reads it back exactly: Rust's BatBadBut rules. Always quoted, so cmd's `&|<>^` are
+ * text; a quote is doubled; backslashes are doubled before a quote and before the closing quote; each `%` becomes
+ * `%%cd:~,%`, which cmd expands to a bare `%`, so no variable is ever expanded. A line break would end cmd's line,
+ * so it is refused.
+ */
+function batchArgument(value) {
+  const text = String(value);
+  if (/[\r\n\0]/.test(text)) {
+    throw new TerminalHostError('invalid_command', 'An argument to a batch program cannot contain a line break.');
+  }
+  let quoted = '"';
+  let backslashes = 0;
+  for (const character of text) {
+    if (character === '\\') {
+      backslashes += 1;
+    } else {
+      if (character === '"') quoted += '\\'.repeat(backslashes);
+      backslashes = 0;
+    }
+    if (character === '"') quoted += '"';
+    else if (character === '%') quoted += '%%cd:~,';
+    quoted += character;
+  }
+  return `${quoted}${'\\'.repeat(backslashes)}"`;
+}
+
+/** The first process beneath a pane's shell that is not a shell, as tmux names a pane's foreground command. */
+function foregroundCommand(rootPid, table) {
+  if (!table) return null;
+  let current = table.find((row) => row.pid === rootPid);
+  if (!current) return null;
+  for (;;) {
+    const name = commandName(current.name);
+    if (!PTY_SHELLS.has(name.toLowerCase())) return name;
+    const children = table.filter((row) => row.parent === current.pid && row.created >= current.created && !CONSOLE_HOSTS.has(row.name.toLowerCase()));
+    if (!children.length) return name;
+    current = children.reduce((oldest, row) => (row.created < oldest.created ? row : oldest));
+  }
+}
+
+/** A moment as CIM gives a process's CreationDate: .NET ticks of local time. */
+function cimTicks(ms) {
+  return String((BigInt(ms - new Date(ms).getTimezoneOffset() * 60_000) * 10_000n) + 621_355_968_000_000_000n);
+}
+
+function commandName(value) {
+  return value ? String(value).split(/[\\/]/).pop().replace(/\.(exe|cmd|bat|com)$/i, '') : null;
+}
+
+/** One captured row as `capture-pane -e` gives it: the row's text with an SGR sequence wherever its style changes. */
+function styledRow(line, cell) {
+  let text = '';
+  let current = '';
+  let pending = '';
+  for (let column = 0; column < line.length; column += 1) {
+    line.getCell(column, cell);
+    if (cell.getWidth() === 0) continue;
+    const style = sgrOf(cell);
+    const character = cell.getChars() || ' ';
+    if (character === ' ' && style === '') { pending += ' '; continue; }
+    if (style !== current) {
+      pending += style === '' ? '\u001b[0m' : `\u001b[0;${style}m`;
+      current = style;
+    }
+    text += pending + character;
+    pending = '';
+  }
+  return current === '' ? text : `${text}\u001b[0m`;
+}
+
+function sgrOf(cell) {
+  const codes = [];
+  if (cell.isBold()) codes.push(1);
+  if (cell.isDim()) codes.push(2);
+  if (cell.isItalic()) codes.push(3);
+  if (cell.isUnderline()) codes.push(4);
+  if (cell.isBlink()) codes.push(5);
+  if (cell.isInverse()) codes.push(7);
+  if (cell.isInvisible()) codes.push(8);
+  if (cell.isStrikethrough()) codes.push(9);
+  colorCodes(codes, cell.isFgPalette(), cell.isFgRGB(), cell.getFgColor(), 30, 90, 38);
+  colorCodes(codes, cell.isBgPalette(), cell.isBgRGB(), cell.getBgColor(), 40, 100, 48);
+  return codes.join(';');
+}
+
+function colorCodes(codes, palette, rgb, color, base, bright, extended) {
+  if (palette) codes.push(...(color < 8 ? [base + color] : color < 16 ? [bright + color - 8] : [extended, 5, color]));
+  else if (rgb) codes.push(extended, 2, (color >> 16) & 255, (color >> 8) & 255, color & 255);
+}
+
+function resizePane(entry, cols, rows) {
+  entry.child.resize(cols, rows);
+  entry.screen.resize(cols, rows);
+}
+
+/** End a live pane and everything it started (`taskkill /T` follows the tree), then release its ConPTY. */
+function endPane(child) {
+  spawnSync('taskkill', ['/T', '/F', '/PID', String(child.pid)], { stdio: 'ignore', windowsHide: true, timeout: 10_000 });
+  releasePane(child);
+}
+
+/**
+ * Close a pane's pseudoconsole and pipes, which otherwise hold this process open after its program ends. node-pty's
+ * kill first forks a helper to list the console's processes, and once the console is gone that helper prints
+ * "AttachConsole failed" to this process's stderr for every pane; the pane's tree is ended here instead (taskkill
+ * on close, the watchdog when the host dies). node-pty also defers kill until a pane's first output, so a pane that never printed
+ * is released through its agent directly.
+ */
+function releasePane(child) {
+  const agent = child._agent;
+  if (typeof agent?._getConsoleProcessList === 'function') agent._getConsoleProcessList = async () => [];
+  try {
+    if (child._isReady === false && agent) {
+      child._close?.();
+      agent.kill();
+    } else {
+      child.kill();
+    }
+  } catch { /* already released */ }
+}
+
+function assertDimension(value, label) {
+  if (!Number.isInteger(value) || value < 1 || value > 1_000) {
+    throw new Error(`Terminal ${label} must be an integer between 1 and 1000.`);
+  }
+}
+
+function wellFormed(value) {
+  return value.toWellFormed?.() ?? value;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 /**
  * Complete reusable terminal companion for Supercode frontends.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-terminal",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "type": "module",
   "description": "Optional leak-safe terminal and tmux host adapter for Volter Harness frontends",
   "exports": {
@@ -103,7 +103,9 @@
     "preact": ">=10.19.0 <11",
     "react": ">=18 <20",
     "ws": "^8.21.0",
-    "@volter/supercode-harness-sdk": "^0.3.18"
+    "@volter/supercode-harness-sdk": "^0.3.18",
+    "@xterm/headless": "^6.0.0",
+    "@xterm/addon-serialize": "^0.14.0"
   },
   "peerDependenciesMeta": {
     "@homebridge/node-pty-prebuilt-multiarch": {
@@ -132,16 +134,24 @@
     },
     "@volter/supercode-harness-sdk": {
       "optional": true
+    },
+    "@xterm/headless": {
+      "optional": true
+    },
+    "@xterm/addon-serialize": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@homebridge/node-pty-prebuilt-multiarch": "^0.13.1",
     "@types/node": "^22.20.1",
     "@types/ws": "^8.18.1",
-    "@volter/supercode-harness-sdk": "npm:@volter-ai-dev/supercode-harness-sdk@^0.3.18",
+    "@volter/supercode-harness-sdk": "^0.3.18",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-search": "^0.16.0",
+    "@xterm/addon-serialize": "^0.14.0",
     "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/headless": "^6.0.0",
     "@xterm/xterm": "^6.0.0",
     "esbuild": "^0.25.0",
     "preact": "^10.19.0",