open-claude-p 1.0.0

package/src/parsers/tui-frame.js

@@ -0,0 +1,256 @@
+// TUI frame parser.
+//
+// A line-oriented state machine that classifies upstream TUI output into
+// structured events. The line model is approximate: we DO NOT run a real
+// terminal emulator, but we do honor the most common TTY redraw idiom —
+// a bare carriage return (`\r`) returns the cursor to column 0 and any
+// subsequent characters on the same logical line overwrite what was
+// there. We model this by splitting each `\n`-terminated segment on `\r`
+// and keeping only the last subsegment (i.e. what survives all redraws).
+//
+// Events emitted:
+//
+//   { type: 'assistant-region-entered', n }      a `⏺` opened the region
+//   { type: 'assistant-region-exited',  n }      a horizontal rule, the
+//                                                request's sentinel, or
+//                                                an unrecoverable break
+//                                                closed the region
+//   { type: 'assistant-text', text, region: n }  one line of response
+//   { type: 'session-id', id }                   from "claude --resume <uuid>"
+//   { type: 'prompt-box-shown' }                 first `─{3,}` rule
+//   { type: 'spinner', label }                   `✻…` thinking/work lines
+//
+// `region` numbers increment per response area; a `--resume` session that
+// re-renders prior history therefore produces region=1..k for old turns
+// and a higher number for the new response. The driver filters on the
+// MAX region when extracting clean assistant text.
+//
+// All version-sensitive patterns live in PATTERNS so future drift is a
+// localized edit.
+
+export const PATTERNS = {
+  assistantRegionMarker: '⏺',
+  boxBorder: /^─{3,}/,
+  spinnerLeading: /^[✻✶✺✹✸✷✵●✢✳✽·✾✿❀❁❂❃❄❅❆❇❈❉❊❋]/,
+  blankLine: /^\s*$/,
+  sessionIdBanner:
+    /claude\s+--resume\s+([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})/,
+  /** Stripped-form sentinel — nonce-agnostic, used to close the region. */
+  sentinel: /⟦OCP_END:[0-9a-fA-F]+⟧/,
+  /** The `❯` chevron that marks the start of the input prompt line.
+   * Once we see this we know we have reached the input box; everything
+   * that follows on subsequent lines is the statusline / HUD plugin
+   * area, not response content, and is suppressed from parsing. */
+  promptInputChevron: /^[❯›❮‹]/,
+};
+
+/**
+ * Resolve carriage-return (`\r`) redraws within a single logical line.
+ *
+ * Real terminal semantics: a bare `\r` returns the cursor to column 0 of
+ * the current line, and any subsequent characters overwrite from that
+ * position. If the overwrite is shorter than the previous content, the
+ * trailing characters of the previous content remain visible. This
+ * function simulates that minimal cursor model and returns the final
+ * visible content of the line.
+ *
+ * Examples:
+ *   resolveCarriageReturns("xxxxx\ryy")        // "yyxxx"
+ *   resolveCarriageReturns("⏺ apple\rstatus")  // "status"   (status fully overwrote)
+ *   resolveCarriageReturns("⏺ apple\ra")       // "appale" — kept the tail
+ *
+ * Strings without any `\r` are returned as-is.
+ *
+ * @param {string} line
+ * @returns {string}
+ */
+export function resolveCarriageReturns(line) {
+  if (line.indexOf('\r') === -1) return line;
+  let buf = '';
+  let cursor = 0;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '\r') {
+      cursor = 0;
+    } else {
+      if (cursor >= buf.length) {
+        buf += ch;
+      } else {
+        buf = buf.slice(0, cursor) + ch + buf.slice(cursor + 1);
+      }
+      cursor += 1;
+    }
+  }
+  return buf;
+}
+
+export const tuiFrameParser = {
+  name: 'tui-frame',
+  priority: 20,
+  create() {
+    /** Pending text awaiting a newline. */
+    let pending = '';
+    let regionActive = false;
+    let regionsEntered = 0;
+    let promptBoxShownEmitted = false;
+    let lastSessionId = null;
+    /**
+     * Becomes true the moment we see the input chevron (`❯`) line. Every
+     * subsequent line is statusline / HUD content (e.g. claude-hud
+     * plugin output, context meter, mode indicator) — none of it is
+     * response content, so we drop it. Reset only when a new response
+     * region begins (`⏺` marker), which is the upstream's signal that
+     * the screen scrolled and we're back above the prompt box.
+     */
+    let belowPromptBox = false;
+    /**
+     * Tracks the most recent assistant-text emission to dedupe consecutive
+     * blank-line emissions. Real paragraph breaks survive (one blank
+     * between text); runs of blanks from redraw artifacts collapse to one.
+     */
+    let lastEmittedBlank = false;
+
+    function closeRegion(events) {
+      if (!regionActive) return;
+      regionActive = false;
+      events.push({ type: 'assistant-region-exited', n: regionsEntered });
+    }
+
+    function emitText(events, raw) {
+      if (!regionActive) return;
+      const isBlank = raw === '' || /^\s*$/.test(raw);
+      if (isBlank && lastEmittedBlank) return; // collapse runs of blanks
+      lastEmittedBlank = isBlank;
+      events.push({
+        type: 'assistant-text',
+        text: raw,
+        region: regionsEntered,
+      });
+    }
+
+    function processLine(line, events) {
+      const trimmedStart = line.trimStart();
+
+      // A new assistant region marker (`⏺`) means the upstream is
+      // re-drawing above the prompt box. Whatever statusline/HUD content
+      // we were ignoring is now stale — fall back into normal parsing.
+      if (trimmedStart.startsWith(PATTERNS.assistantRegionMarker)) {
+        belowPromptBox = false;
+      }
+
+      // Once we have seen the input chevron, every line below it is
+      // statusline / HUD plugin content (claude-hud, mode indicator,
+      // context meter, queued-message hints, …). Suppress all parsing
+      // until a new assistant region is opened above.
+      if (belowPromptBox) return;
+
+      // Session-id banner — accept anywhere in the buffer.
+      const sm = line.match(PATTERNS.sessionIdBanner);
+      if (sm && sm[1] !== lastSessionId) {
+        lastSessionId = sm[1];
+        events.push({ type: 'session-id', id: sm[1] });
+      }
+
+      // Input chevron (`❯`) marks the prompt input line itself. This is
+      // the only reliable "the input box is ready" signal — box borders
+      // alone fire too early on the welcome banner's bottom border, so
+      // we anchor `prompt-box-shown` to the chevron. The line may
+      // legitimately contain queued draft text after the chevron, but
+      // it is not response content — drop it and from here on suppress
+      // everything until a new response region opens.
+      if (PATTERNS.promptInputChevron.test(trimmedStart)) {
+        closeRegion(events);
+        if (!promptBoxShownEmitted) {
+          promptBoxShownEmitted = true;
+          events.push({ type: 'prompt-box-shown' });
+        }
+        belowPromptBox = true;
+        return;
+      }
+
+      // Box border closes any open assistant region. We do NOT fire
+      // `prompt-box-shown` here — the welcome banner and tool-output
+      // panels both use box borders, so chevron-based emission above is
+      // the authoritative signal.
+      if (PATTERNS.boxBorder.test(line.trim())) {
+        closeRegion(events);
+        return;
+      }
+
+      const trimmed = trimmedStart;
+
+      // New assistant region: first character is the response marker.
+      if (trimmed.startsWith(PATTERNS.assistantRegionMarker)) {
+        regionActive = true;
+        regionsEntered += 1;
+        events.push({ type: 'assistant-region-entered', n: regionsEntered });
+        let after = trimmed.slice(PATTERNS.assistantRegionMarker.length).trimStart();
+        // The sentinel may sit on the same line as the marker (e.g.
+        // `⏺hello⟦OCP_END:…⟧`); split it out and close the region.
+        const sIdx = after.search(PATTERNS.sentinel);
+        if (sIdx !== -1) {
+          const before = after.slice(0, sIdx).replace(/\s+$/, '');
+          if (before) emitText(events, before);
+          closeRegion(events);
+        } else if (after) {
+          emitText(events, after);
+        }
+        return;
+      }
+
+      // Spinner / working status — emit a typed event and otherwise skip.
+      if (PATTERNS.spinnerLeading.test(trimmed)) {
+        events.push({ type: 'spinner', label: trimmed });
+        return;
+      }
+
+      if (!regionActive) return; // outside any region — ignore noise
+
+      // Inside an active region: the sentinel closes it.
+      const sIdx = line.search(PATTERNS.sentinel);
+      if (sIdx !== -1) {
+        const before = line.slice(0, sIdx).replace(/\s+$/, '');
+        if (before) emitText(events, before);
+        closeRegion(events);
+        return;
+      }
+
+      if (PATTERNS.blankLine.test(line)) {
+        emitText(events, ''); // paragraph break
+        return;
+      }
+      emitText(events, line.replace(/\s+$/, ''));
+    }
+
+    return {
+      feed(text) {
+        const events = [];
+        pending += text;
+        // Split on any of CR / LF / CRLF as a line boundary. Treating
+        // bare `\r` as a line ender is essential: many response lines
+        // arrive as `…content\r` without a following `\n` (the upstream
+        // does in-place updates of the current row), and a parser that
+        // waited for `\n` alone would block forever on those rows.
+        // Each segment is processed as its own line; consumers
+        // (extractAssistantTextFromEvents) pick the highest region.
+        const parts = pending.split(/\r\n|\r|\n/);
+        pending = parts.pop() ?? '';
+        for (const line of parts) {
+          processLine(line, events);
+        }
+        // text is passed through unchanged for downstream parsers (the
+        // sentinel parser still scans the raw stream).
+        return { text, events };
+      },
+      reset() {
+        pending = '';
+        regionActive = false;
+        regionsEntered = 0;
+        promptBoxShownEmitted = false;
+        lastSessionId = null;
+        lastEmittedBlank = false;
+        belowPromptBox = false;
+      },
+    };
+  },
+};

package/src/print-mode.js

@@ -0,0 +1,214 @@
+// Direct `claude --print` mode — opt-in alternative to the default PTY+TUI
+// pipeline. The default driver spawns `claude` interactively and captures
+// the rendered TUI output, which means markdown formatting characters
+// (``` fences, ## headings, **bold**, etc.) are consumed during rendering
+// and never reach the caller.
+//
+// Print mode bypasses the TUI entirely:
+//   - spawns `claude --print "<prompt>" [forwarded args]` via child_process
+//   - claude detects non-TTY stdout and emits raw output
+//   - markdown formatting is preserved verbatim
+//
+// Trade-offs (vs. the default PTY path):
+//   + raw markdown reaches the caller (the original motivation)
+//   + simpler — no PTY, no ANSI strip, no TUI frame parser
+//   - claude's native schemas pass through unchanged (json / stream-json
+//     no longer match ocp's wrapped schema; document this for callers)
+//   - tool-approval prompts and other interactive flows are not available
+//   - print-mode MCP calls have a known upstream hang; callers using
+//     MCP servers should stay on the default path
+
+import { spawn } from 'node:child_process';
+import { readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import { OPTION_SPEC } from './options/spec.js';
+import { sanitizePassThroughArgv, redactArgvForLog } from './index.js';
+
+/**
+ * Translate a runOneShot-style request into a `claude --print` argv list.
+ * Flags come first, then a `--` end-of-options separator, then the prompt as
+ * a positional argument so the upstream parser cannot mistake a prompt
+ * starting with `-` for a flag.
+ *
+ * @param {object} req
+ * @returns {string[]}
+ */
+export function buildPrintModeArgs(req) {
+  const args = ['--print'];
+  for (const spec of OPTION_SPEC) {
+    if (spec.forward?.type !== 'argv') continue;
+    const value = req[fieldNameOf(spec)];
+    if (value === undefined || value === null || value === false) continue;
+    if (spec.kind === 'boolean') {
+      if (value === true) args.push(spec.forward.flag);
+    } else if (spec.kind === 'array') {
+      if (Array.isArray(value) && value.length > 0) {
+        args.push(spec.forward.flag, ...value.map(String));
+      }
+    } else {
+      args.push(spec.forward.flag, String(value));
+    }
+  }
+  if (req.outputFormat) args.push('--output-format', String(req.outputFormat));
+  if (Array.isArray(req.passThroughArgv) && req.passThroughArgv.length > 0) {
+    const { sanitized } = sanitizePassThroughArgv(req.passThroughArgv);
+    args.push(...sanitized);
+  }
+  args.push('--', req.prompt);
+  return args;
+}
+
+function fieldNameOf(spec) {
+  return spec.name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * Run a single prompt against `claude --print` and stream stdout to the
+ * provided sink (typically process.stdout).
+ *
+ * @param {object} opts
+ * @param {string} opts.bin                Binary to spawn (default 'claude').
+ * @param {string} opts.prompt
+ * @param {object} opts.req                Full request object (forwarded fields used).
+ * @param {{ write: (s: string) => void }} [opts.sink]   stdout sink (default: capture-only).
+ * @param {string} [opts.cwd]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {AbortSignal} [opts.abortSignal]
+ * @param {number} [opts.timeoutMs]
+ * @param {(msg: string) => void} [opts.logDebug]
+ * @returns {Promise<{ text: string, sessionId: string|null, isError: boolean, exitCode: number|null, durationMs: number, completionReason: string }>}
+ */
+export async function runPrintMode(opts) {
+  const startMs = Date.now();
+  const args = buildPrintModeArgs(opts.req);
+  if (opts.logDebug) opts.logDebug(`print-mode spawn ${opts.bin} ${redactArgvForLog(args).join(' ')}`);
+
+  const sessionFilesBefore = await listSessionFiles(opts.cwd);
+
+  return new Promise((resolve) => {
+    const child = spawn(opts.bin, args, {
+      cwd: opts.cwd ?? process.cwd(),
+      env: opts.env ?? process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let textBuf = '';
+    let stderrBuf = '';
+    let timedOut = false;
+    let aborted = false;
+
+    const timer = opts.timeoutMs && opts.timeoutMs > 0
+      ? setTimeout(() => { timedOut = true; child.kill('SIGTERM'); }, opts.timeoutMs)
+      : null;
+
+    let onAbort;
+    if (opts.abortSignal) {
+      onAbort = () => { aborted = true; child.kill('SIGTERM'); };
+      opts.abortSignal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    child.stdout.on('data', (chunk) => {
+      const s = chunk.toString('utf8');
+      textBuf += s;
+      if (opts.sink) opts.sink.write(s);
+    });
+    child.stderr.on('data', (chunk) => { stderrBuf += chunk.toString('utf8'); });
+
+    child.on('close', async (code) => {
+      if (timer) clearTimeout(timer);
+      if (onAbort && opts.abortSignal) opts.abortSignal.removeEventListener('abort', onAbort);
+
+      let sessionId = extractSessionIdFromOutput(textBuf, opts.req.outputFormat);
+      if (!sessionId) {
+        sessionId = await scanForNewSessionFile(opts.cwd, sessionFilesBefore);
+      }
+
+      const completionReason =
+        aborted ? 'cancelled' :
+        timedOut ? 'timeout' :
+        code === 0 ? 'sentinel' :
+        'upstream-exited';
+
+      if (opts.logDebug && stderrBuf) opts.logDebug(`print-mode stderr: ${stderrBuf.slice(-400)}`);
+
+      resolve({
+        text: textBuf,
+        sessionId,
+        isError: code !== 0,
+        exitCode: code,
+        durationMs: Date.now() - startMs,
+        completionReason,
+      });
+    });
+
+    child.on('error', (err) => {
+      if (timer) clearTimeout(timer);
+      if (opts.logDebug) opts.logDebug(`print-mode spawn error: ${err.message}`);
+      resolve({
+        text: textBuf,
+        sessionId: null,
+        isError: true,
+        exitCode: null,
+        durationMs: Date.now() - startMs,
+        completionReason: 'spawn-error',
+      });
+    });
+  });
+}
+
+// Pull session_id from claude --output-format=json or stream-json output.
+function extractSessionIdFromOutput(text, outputFormat) {
+  if (!text) return null;
+  if (outputFormat === 'json') {
+    try {
+      const obj = JSON.parse(text.trim());
+      return obj.session_id ?? null;
+    } catch { return null; }
+  }
+  if (outputFormat === 'stream-json') {
+    for (const line of text.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        const obj = JSON.parse(line);
+        if (obj.session_id) return obj.session_id;
+      } catch { /* ignore non-JSON lines */ }
+    }
+  }
+  return null;
+}
+
+async function listSessionFiles(cwd) {
+  const absCwd = path.resolve(cwd ?? process.cwd());
+  // Upstream encodes BOTH path separators and underscores as `-`, so
+  // `/Users/alice/gen_keypair` lands in `-Users-alice-gen-keypair/`.
+  // A `/`-only replacement misses any cwd containing `_` and silently
+  // looks in the wrong directory.
+  const encoded = absCwd.replace(/[/_]/g, '-');
+  const dir = path.join(os.homedir(), '.claude', 'projects', encoded);
+  const out = new Map();
+  let entries;
+  try { entries = await readdir(dir); } catch { return out; }
+  for (const name of entries) {
+    if (!/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\.jsonl$/.test(name)) continue;
+    try {
+      const st = await stat(path.join(dir, name));
+      out.set(name, st.mtimeMs);
+    } catch { /* ignore */ }
+  }
+  return out;
+}
+
+async function scanForNewSessionFile(cwd, before) {
+  const after = await listSessionFiles(cwd);
+  let best = null;
+  let bestMtime = 0;
+  for (const [name, mtime] of after) {
+    const prev = before.get(name);
+    if (prev === undefined || mtime > prev) {
+      if (mtime > bestMtime) { bestMtime = mtime; best = name; }
+    }
+  }
+  return best ? best.replace(/\.jsonl$/, '') : null;
+}

package/src/pty/index.js

@@ -0,0 +1,3 @@
+// Barrel re-export for the pty module.
+export { PtySession } from './session.js';
+export { PtyPool } from './pool.js';

package/src/pty/pool.js

@@ -0,0 +1,127 @@
+// Warm pool of idle PTY sessions.
+//
+// Key design decisions:
+//   - No /clear on release — conversation context is preserved across calls.
+//   - Sliding TTL: lastUsedAt is updated on each acquire, not at park time.
+//   - acquire() does NOT spawn — it tells the caller what to do:
+//       { session, isReuse: true }                → reuse warm session
+//       { session: null, resumeSessionId }        → caller must spawn (use resumeSessionId for --resume if set)
+//   - release(session, key, sessionId) parks the session with its sessionId so
+//     a future respawn can --resume into the same conversation.
+//   - initialSessionId: on the very first acquire (empty pool), return this as
+//     resumeSessionId so the caller can --resume an earlier conversation.
+
+export class PtyPool {
+  /**
+   * @param {object} opts
+   * @param {number} [opts.maxIdlePerKey=1]
+   * @param {number} [opts.maxAgeMs=600000]     sliding idle TTL (10 min default)
+   * @param {string|null} [opts.initialSessionId]  resume target for first spawn
+   */
+  constructor({ maxIdlePerKey = 1, maxAgeMs = 600_000, initialSessionId = null } = {}) {
+    this.maxIdlePerKey = maxIdlePerKey;
+    this.maxAgeMs = maxAgeMs;
+    /** Used once on the first empty-pool acquire, then cleared. */
+    this.initialSessionId = initialSessionId;
+    /** @type {Map<string, Array<{session, lastUsedAt: number, sessionId: string|null}>>} */
+    this.idle = new Map();
+    this.closed = false;
+  }
+
+  /**
+   * Compute a canonical pool key for a request.
+   * @param {object} opts
+   * @param {string} [opts.cwd]
+   * @param {string[]} [opts.spawnArgs]
+   * @returns {string}
+   */
+  static canonicalKey({ cwd, spawnArgs } = {}) {
+    return JSON.stringify({
+      cwd: cwd ?? '',
+      args: Array.isArray(spawnArgs) ? [...spawnArgs] : [],
+    });
+  }
+
+  /**
+   * Try to get a warm session for key.
+   *
+   * Returns one of:
+   *   { session: PtySession, isReuse: true,  resumeSessionId: null }
+   *     → warm hit; caller uses this session directly (no spawn needed).
+   *   { session: null,       isReuse: false, resumeSessionId: string|null }
+   *     → miss; caller must spawn a new PTY.
+   *       If resumeSessionId is non-null, caller should pass --resume to the spawn.
+   *
+   * @param {{ key: string }} opts
+   */
+  async acquire({ key }) {
+    if (this.closed) throw new Error('PtyPool.acquire: pool is closed');
+    const list = this.idle.get(key);
+
+    while (list && list.length > 0) {
+      const entry = list.pop();
+      const age = Date.now() - entry.lastUsedAt;
+
+      if (entry.session.state === 'idle' && age <= this.maxAgeMs) {
+        // Warm hit — session is now checked out; do NOT push back into idle.
+        // release() will re-add it when the caller is done.
+        return { session: entry.session, isReuse: true, resumeSessionId: null };
+      }
+
+      // Stale — kill the dead/expired session and bubble up its sessionId
+      // so the caller can --resume into the same conversation.
+      const staleId = entry.sessionId;
+      try { await entry.session.kill(); } catch {}
+      return { session: null, isReuse: false, resumeSessionId: staleId };
+    }
+
+    // Empty pool — use initialSessionId (if any) so the first spawn can
+    // --resume an earlier conversation from a previous daemon run.
+    const resumeId = this.initialSessionId;
+    this.initialSessionId = null; // consume once
+    return { session: null, isReuse: false, resumeSessionId: resumeId };
+  }
+
+  /**
+   * Park a session for reuse. No /clear is sent — conversation context is
+   * intentionally preserved so the next acquire continues the same thread.
+   *
+   * @param {import('./session.js').PtySession} session
+   * @param {string} key
+   * @param {string|null} sessionId  the claude session UUID from the last response
+   */
+  async release(session, key, sessionId = null) {
+    if (this.closed || session.state !== 'idle') {
+      try { await session.kill(); } catch {}
+      return;
+    }
+
+    const list = this.idle.get(key) ?? [];
+
+    if (list.length >= this.maxIdlePerKey) {
+      try { await session.kill(); } catch {}
+      return;
+    }
+
+    if (!this.idle.has(key)) this.idle.set(key, list);
+    list.push({ session, lastUsedAt: Date.now(), sessionId });
+  }
+
+  /** Kill all parked sessions and mark the pool unusable. */
+  async close() {
+    this.closed = true;
+    for (const list of this.idle.values()) {
+      for (const { session } of list) {
+        try { await session.kill(); } catch {}
+      }
+    }
+    this.idle.clear();
+  }
+
+  /** Number of currently parked sessions across all keys. */
+  size() {
+    let n = 0;
+    for (const list of this.idle.values()) n += list.length;
+    return n;
+  }
+}

package/src/pty/session.js

@@ -0,0 +1,88 @@
+// A single PTY-backed `claude` session.
+//
+// Wraps `node-pty`'s spawn surface in a small EventEmitter so the driver can
+// subscribe to data and exit events without depending on node-pty's typings
+// directly. The class is intentionally dumb — it knows nothing about parsers,
+// sentinels, or output formats. Higher layers compose those on top.
+//
+// Lifecycle:
+//   new PtySession()  ->  state = 'starting'
+//   .spawn({...})     ->  state = 'idle' once node-pty returns the child
+//   .write(s)         ->  send raw bytes
+//   .kill()           ->  state = 'dead'; resolves when the child exits
+//
+// State values used so far ('busy', 'resetting') are reserved for the pool
+// integration that lands in a later phase.
+
+import { spawn as ptySpawn } from 'node-pty';
+import { EventEmitter } from 'node:events';
+
+export class PtySession extends EventEmitter {
+  constructor() {
+    super();
+    this.state = 'starting';
+    this.proc = null;
+    this.exitInfo = null;
+  }
+
+  /**
+   * Spawn the upstream binary under node-pty.
+   *
+   * @param {object} opts
+   * @param {string} opts.bin            Path or PATH-resolvable name.
+   * @param {string[]} [opts.args]
+   * @param {string} [opts.cwd]
+   * @param {NodeJS.ProcessEnv} [opts.env]
+   * @param {number} [opts.cols]
+   * @param {number} [opts.rows]
+   */
+  async spawn({ bin, args = [], cwd, env, cols = 220, rows = 500 }) {
+    if (this.proc) throw new Error('PtySession.spawn: already spawned');
+    this.proc = ptySpawn(bin, args, {
+      name: 'xterm-256color',
+      cols,
+      rows,
+      cwd: cwd ?? process.cwd(),
+      env: env ?? process.env,
+    });
+    this.proc.onData((chunk) => this.emit('data', chunk));
+    this.proc.onExit((info) => {
+      this.exitInfo = info;
+      this.state = 'dead';
+      this.emit('exit', info);
+    });
+    this.state = 'idle';
+  }
+
+  /** Send raw bytes to the PTY. Throws if not spawned or already dead. */
+  write(data) {
+    if (!this.proc) throw new Error('PtySession.write: not spawned');
+    if (this.state === 'dead') throw new Error('PtySession.write: session is dead');
+    this.proc.write(data);
+  }
+
+  /** Resize the PTY. Safe to call repeatedly. */
+  resize(cols, rows) {
+    if (!this.proc || this.state === 'dead') return;
+    try { this.proc.resize(cols, rows); } catch {}
+  }
+
+  /**
+   * Kill the underlying process. Resolves when it has exited (or after 1 s
+   * if the OS does not deliver the exit event quickly enough).
+   */
+  async kill() {
+    if (!this.proc || this.state === 'dead') return;
+    try { this.proc.kill(); } catch {}
+    if (this.state !== 'dead') {
+      await new Promise((resolve) => {
+        const onExit = () => resolve();
+        this.once('exit', onExit);
+        setTimeout(() => {
+          this.off('exit', onExit);
+          resolve();
+        }, 1000);
+      });
+    }
+  }
+}