@volter/supercode-terminal 0.2.30

package/index.mjs

@@ -0,0 +1,981 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { createServer as defaultCreateServer } from 'node:http';
+
+import { NativeTerminalSessionHost } from './substrate/native-host.js';
+import * as defaultTmux from './substrate/tmux.js';
+import { openLocalTerminal as defaultOpenLocalTerminal } from './substrate/local-terminal.js';
+
+const DEFAULT_ATTACHMENT_TTL_MS = 30_000;
+const DEFAULT_CONTEXT_OPTION = '@supercode-context';
+const DEFAULT_OWNER_OPTION = '@supercode-owner';
+const SESSION_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+// A pane should feel like the terminal it is shown in, not like tmux: no status
+// bar, no prefix key taking keystrokes from the program, and no mouse capture,
+// so the viewer's own terminal selects, copies and scrolls. (Native scrollback
+// for attached viewers comes from the server option the substrate sets for its
+// relay clients.) Session-scoped, so other sessions on the same tmux server
+// keep their own settings.
+const TERMINAL_LIKE_SESSION = Object.freeze({ status: 'off', mouse: 'off', prefix: 'None', prefix2: 'None', 'remain-on-exit': 'failed' });
+
+// The four native harness kinds this package can host interactively, mapped to
+// the vendor CLI a tmux pane runs. These are the plain interactive TUIs, not the
+// registry's stdio/ACP launches (crates/harness/src/support.rs), whose protocol
+// flags (`--experimental-acp`, `agent … stdio`) drive a headless runtime instead
+// of a pane. A kind whose binary is absent from PATH dies at startup and surfaces
+// as the host's existing `session_not_found` TerminalHostError, naming the tmux
+// session that could not be attached.
+const TERMINAL_HARNESS_PROGRAMS = Object.freeze({
+  'claude-code': 'claude',
+  codex: 'codex',
+  gemini: 'gemini',
+  grok: 'grok',
+});
+
+// The native agent-session prefix each kind's pane id carries. substrate/
+// session-lifecycle.js mints `<agent>:<id>` from KNOWN_AGENT_IDS, and the
+// interchange catalog discovers the same four stores under HarnessId::
+// {CLAUDE_CODE, CODEX, GEMINI, GROK}; only claude-code's product id differs from
+// its agent id, so a launched pane binds to the session interchange discovered.
+const NATIVE_AGENT_PREFIXES = Object.freeze({
+  'claude-code': 'claude',
+  codex: 'codex',
+  gemini: 'gemini',
+  grok: 'grok',
+});
+
+function assertContextKey(value) {
+  if (!value || value.length > 256 || /\0|\t|\r|\n/.test(value)) {
+    throw new TerminalHostError('invalid_context_key', 'A terminal context key must be a non-empty opaque value of at most 256 characters.');
+  }
+}
+
+function allowedOrigin(value) {
+  const origin = typeof value === 'string' ? value.trim().replace(/\/$/, '') : '';
+  if (!/^[a-z][a-z0-9+.-]*:\/\/[^/?#]+$/i.test(origin)) {
+    throw new TypeError('TerminalWebSocketBridge requires an exact allowed origin');
+  }
+  return origin;
+}
+
+/** Exact-origin loopback transport for browser and extension terminal viewers. */
+export class TerminalWebSocketBridge {
+  #allowedOrigins;
+  #baseUrl = '';
+  #createServer;
+  #host;
+  #server = null;
+  #sockets = null;
+  #WebSocketServer;
+
+  constructor(options = {}) {
+    if (!options.host?.issueAttachment || !options.host?.attachSocket) {
+      throw new TypeError('TerminalWebSocketBridge requires a TmuxTerminalHost-compatible host');
+    }
+    const origins = Array.isArray(options.allowedOrigins) ? options.allowedOrigins : [options.allowedOrigins];
+    this.#allowedOrigins = new Set(origins.map(allowedOrigin));
+    this.#createServer = options.createServer ?? defaultCreateServer;
+    this.#host = options.host;
+    this.#WebSocketServer = options.WebSocketServer;
+  }
+
+  get baseUrl() {
+    return this.#baseUrl;
+  }
+
+  async start() {
+    if (this.#server) return this.#baseUrl;
+    const WebSocketServer = this.#WebSocketServer ?? (await import('ws')).WebSocketServer;
+    const sockets = new WebSocketServer({ noServer: true });
+    const server = this.#createServer((_request, response) => response.writeHead(404).end());
+    server.on('upgrade', (request, socket, head) => this.#upgrade(request, socket, head));
+    this.#server = server;
+    this.#sockets = sockets;
+    try {
+      await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+          server.off('error', reject);
+          resolve();
+        });
+      });
+      const address = server.address();
+      if (!address || typeof address === 'string') throw new Error('Terminal bridge did not bind a local port');
+      this.#baseUrl = `http://127.0.0.1:${address.port}`;
+      return this.#baseUrl;
+    } catch (error) {
+      this.#server = null;
+      this.#sockets = null;
+      sockets.close();
+      throw error;
+    }
+  }
+
+  issueAttachment(sessionId, options = {}) {
+    if (!this.#baseUrl) throw new TerminalHostError('bridge_not_started', 'The terminal bridge is not started.');
+    return Object.freeze({ ...this.#host.issueAttachment(sessionId, options), baseUrl: this.#baseUrl });
+  }
+
+  async stop() {
+    const server = this.#server;
+    const sockets = this.#sockets;
+    this.#server = null;
+    this.#sockets = null;
+    this.#baseUrl = '';
+    if (!server || !sockets) return;
+    for (const socket of sockets.clients) socket.terminate();
+    sockets.close();
+    await new Promise((resolve) => server.close(() => resolve()));
+  }
+
+  #upgrade(request, socket, head) {
+    const origin = String(request.headers.origin ?? '').replace(/\/$/, '');
+    const url = new URL(request.url ?? '/', this.#baseUrl || 'http://127.0.0.1');
+    const attachmentId = url.searchParams.get('terminalId');
+    const cols = positiveOptionalInteger(url.searchParams.get('cols'));
+    const rows = positiveOptionalInteger(url.searchParams.get('rows'));
+    if (url.pathname !== '/ws' || !attachmentId || !this.#allowedOrigins.has(origin)) {
+      socket.destroy();
+      return;
+    }
+    this.#sockets.handleUpgrade(request, socket, head, (webSocket) => {
+      void this.#host.attachSocket(attachmentId, webSocket, { cols, rows }).catch((error) => {
+        if (webSocket.readyState === webSocket.OPEN) {
+          webSocket.send(JSON.stringify({ message: errorMessage(error), type: 'error' }));
+          webSocket.close(1008, 'terminal attachment rejected');
+        }
+      });
+    });
+  }
+}
+
+export class TmuxTerminalHost {
+  #allowUnownedControl;
+  #attachments = new Map();
+  #attachSocket;
+  #catalog = new Map();
+  #contextOption;
+  #idByName = new Map();
+  #liveAttachments = new Set();
+  #now;
+  #openLocalTerminal;
+  #ownerId;
+  #ownerOption;
+  #randomToken;
+  #socket;
+  #tmux;
+  #ttlMs;
+
+  constructor(options = {}) {
+    this.#allowUnownedControl = options.allowUnownedControl === true;
+    this.#attachSocket = options.attachSocket;
+    this.#contextOption = options.contextOption ?? DEFAULT_CONTEXT_OPTION;
+    this.#now = options.now ?? Date.now;
+    this.#openLocalTerminal = options.openLocalTerminal ?? defaultOpenLocalTerminal;
+    this.#ownerId = options.ownerId ?? `supercode-${process.pid}-${randomToken()}`;
+    this.#ownerOption = options.ownerOption ?? DEFAULT_OWNER_OPTION;
+    this.#randomToken = options.randomToken ?? randomToken;
+    this.#socket = options.socket;
+    this.#tmux = options.tmux ?? defaultTmux;
+    this.#ttlMs = positiveInteger(options.attachmentTtlMs ?? DEFAULT_ATTACHMENT_TTL_MS, 'attachmentTtlMs');
+  }
+
+  async listSessions() {
+    this.#pruneAttachments();
+    const names = this.#sessionNames();
+    const liveNames = new Set(names);
+    for (const [name, id] of this.#idByName) {
+      if (!liveNames.has(name)) {
+        this.#idByName.delete(name);
+        this.#catalog.delete(id);
+      }
+    }
+    const panes = this.#panes();
+    const [contextKeys, sizes] = await Promise.all([
+      this.#tmux.sessionOptionValuesAsync(this.#contextOption, this.#socket),
+      this.#tmux.listWindowSizesAsync(this.#socket),
+    ]);
+    const ownedNames = new Set(this.#tmux.sessionsOwnedBy(this.#ownerId, this.#socket, this.#ownerOption));
+    return names.map((name) => {
+      const id = this.#catalogId(name);
+      const pane = panes.find((candidate) => candidate.session === name && candidate.window === 0 && candidate.pane === 0);
+      const size = sizes.get(name);
+      return Object.freeze({
+        activeCommand: pane?.currentCommand ?? null,
+        rootPid: pane?.rootPid ?? null,
+        contextKey: contextKeys.get(name) ?? null,
+        cwd: pane?.cwd ?? null,
+        id,
+        label: name,
+        owned: ownedNames.has(name),
+        size: size ? Object.freeze({ columns: size.width, rows: size.height }) : null,
+      });
+    });
+  }
+
+  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 tmux session 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.#sessionNames().includes(name)) {
+      throw new TerminalHostError('session_exists', `A tmux session named ${name} already exists.`);
+    }
+    await this.#tmux.createSession({
+      command: {
+        arguments: input.command.arguments ?? [],
+        program: input.command.program,
+      },
+      cwd: input.cwd,
+      env: input.env,
+      name,
+      owner: this.#ownerId,
+      ownerOption: this.#ownerOption,
+      panes: 1,
+      sessionOptions: input.contextKey ? { [this.#contextOption]: input.contextKey } : {},
+      settings: TERMINAL_LIKE_SESSION,
+      socket: this.#socket,
+    });
+    const id = this.#catalogId(name);
+    const created = (await this.listSessions()).find((session) => session.id === id);
+    if (!created) {
+      throw new TerminalHostError('session_not_found', 'The tmux session exited before it could be attached.');
+    }
+    return created;
+  }
+
+  capture(sessionId, options = {}) {
+    const entry = this.#entry(sessionId);
+    return this.#tmux.capturePane({
+      lines: options.lines,
+      preserveEscapes: options.preserveEscapes === true,
+      socket: this.#socket,
+      target: `${entry.name}:0.0`,
+    });
+  }
+
+  async sendInput(sessionId, data, options = {}) {
+    const entry = this.#entry(sessionId);
+    if (!this.#canControl(entry.name)) {
+      throw new TerminalHostError('input_not_allowed', 'This host does not own that tmux session.');
+    }
+    return await this.#tmux.sendInputAsync({
+      data,
+      deadlineMs: options.deadlineMs,
+      socket: this.#socket,
+      submitMode: options.submitMode,
+      target: `${entry.name}:0.0`,
+    });
+  }
+
+  async bindContext(sessionId, contextKey) {
+    assertContextKey(contextKey);
+    const entry = this.#entry(sessionId);
+    if (!this.#canControl(entry.name)) {
+      throw new TerminalHostError('bind_not_allowed', 'This host does not own that tmux session.');
+    }
+    await this.#tmux.setSessionOptionAsync(entry.name, this.#contextOption, contextKey, this.#socket);
+    const bound = (await this.listSessions()).find((session) => session.id === sessionId);
+    if (!bound) {
+      throw new TerminalHostError('session_not_found', 'The tmux session exited before it could be bound.');
+    }
+    return bound;
+  }
+
+  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.');
+    }
+    if (mode === 'control' && !this.#canControl(entry.name)) {
+      throw new TerminalHostError('control_not_allowed', 'This host does not own that tmux session.');
+    }
+    const id = `sct_${this.#randomToken()}`;
+    const expiresAt = this.#now() + this.#ttlMs;
+    this.#attachments.set(id, { expiresAt, mode, name: entry.name });
+    return Object.freeze({ expiresAt, id, mode });
+  }
+
+  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.');
+    }
+    if (!this.#sessionNames().includes(grant.name)) {
+      throw new TerminalHostError('session_not_found', 'The tmux session no longer exists.');
+    }
+    const attach = this.#attachSocket ?? (await import('./substrate/tmux-stream.js')).attachTmuxTerminalSocket;
+    const attachment = await attach({
+      authorizeInput: grant.mode === 'control'
+        ? undefined
+        : () => {
+            throw new TerminalHostError('input_not_allowed', 'This is a read-only terminal attachment.');
+          },
+      errorLabel: 'supercode',
+      readOnly: grant.mode === 'observe',
+      ...(grant.mode === 'control' && size.cols ? { cols: size.cols } : {}),
+      ...(grant.mode === 'control' && size.rows ? { rows: size.rows } : {}),
+      socket,
+      terminalId: grant.name,
+      tmuxSocket: this.#socket,
+      window: 0,
+    });
+    let disposed = false;
+    const onClose = () => wrapped.dispose();
+    const wrapped = {
+      dispose: () => {
+        if (disposed) return;
+        disposed = true;
+        socket?.off?.('close', onClose);
+        this.#liveAttachments.delete(wrapped);
+        attachment.dispose();
+      },
+    };
+    this.#liveAttachments.add(wrapped);
+    socket?.once?.('close', onClose);
+    return wrapped;
+  }
+
+  localAttachLaunch(sessionId) {
+    const entry = this.#entry(sessionId);
+    if (!this.#canControl(entry.name)) {
+      throw new TerminalHostError('control_not_allowed', 'This host does not own that tmux session.');
+    }
+    return Object.freeze({
+      arguments: [...(this.#socket ? ['-L', this.#socket] : []), 'attach-session', '-t', entry.name],
+      env: Object.freeze({}),
+      program: 'tmux',
+    });
+  }
+
+  async openLocalTerminal(sessionId) {
+    await this.#openLocalTerminal(this.localAttachLaunch(sessionId));
+  }
+
+  closeSession(sessionId) {
+    const entry = this.#entry(sessionId);
+    if (!this.#canControl(entry.name)) {
+      throw new TerminalHostError('close_not_allowed', 'This host does not own that tmux session.');
+    }
+    this.#tmux.killSessionProcessTree({ session: entry.name, socket: this.#socket });
+    this.#catalog.delete(sessionId);
+    this.#idByName.delete(entry.name);
+    for (const [id, grant] of this.#attachments) {
+      if (grant.name === entry.name) this.#attachments.delete(id);
+    }
+  }
+
+  dispose() {
+    for (const attachment of [...this.#liveAttachments]) attachment.dispose();
+    this.#attachments.clear();
+    this.#catalog.clear();
+    this.#idByName.clear();
+  }
+
+  #canControl(name) {
+    if (this.#allowUnownedControl) return true;
+    return this.#tmux.sessionOwner(name, this.#socket, this.#ownerOption) === this.#ownerId;
+  }
+
+  #catalogId(name) {
+    const existing = this.#idByName.get(name);
+    if (existing) return existing;
+    const id = `scts_${this.#randomToken()}`;
+    this.#idByName.set(name, id);
+    this.#catalog.set(id, { name });
+    return id;
+  }
+
+  #entry(id) {
+    const entry = this.#catalog.get(id);
+    if (!entry || !this.#sessionNames().includes(entry.name)) {
+      if (entry) {
+        this.#catalog.delete(id);
+        this.#idByName.delete(entry.name);
+      }
+      throw new TerminalHostError('session_not_found', 'The tmux session no longer exists.');
+    }
+    return entry;
+  }
+
+  #panes() {
+    try {
+      return this.#tmux.listPanes(this.#socket);
+    } catch (error) {
+      if (isEmptyServerError(error)) return [];
+      throw error;
+    }
+  }
+
+  #pruneAttachments() {
+    const now = this.#now();
+    for (const [id, grant] of this.#attachments) {
+      if (grant.expiresAt <= now) this.#attachments.delete(id);
+    }
+  }
+
+  #sessionNames() {
+    try {
+      return this.#tmux.listTmuxSessionNames(this.#socket);
+    } catch (error) {
+      if (isEmptyServerError(error)) return [];
+      throw error;
+    }
+  }
+}
+
+/**
+ * Complete reusable terminal companion for Supercode frontends.
+ *
+ * This controller composes durable tmux hosting, leak-safe browser grants, native-session handoff,
+ * and harness-aware initial input delivery. Products supply origins and display policy; they do not
+ * need to rebuild recovery registries or scrape agent TUIs themselves.
+ */
+export class SupercodeTerminalController {
+  #attachment = null;
+  #bridge;
+  #conversationBindingInFlight = null;
+  #contextBySession = new Map();
+  #error = null;
+  #formatCwd;
+  #host;
+  #nativeHost;
+  #nativeSessionIds = new Set();
+  #pendingConversationBindings = new Map();
+  #pendingInitialInputs = new Map();
+  #sessionNamePrefix;
+
+  constructor(options = {}) {
+    if (!options.allowedOrigins) {
+      throw new TypeError('SupercodeTerminalController requires at least one exact browser origin');
+    }
+    this.#formatCwd = options.formatCwd ?? ((cwd) => cwd);
+    this.#host = new TmuxTerminalHost({
+      ...(options.host ?? {}),
+      ownerId: options.host?.ownerId ?? 'supercode-native',
+    });
+    this.#bridge = new TerminalWebSocketBridge({
+      allowedOrigins: options.allowedOrigins,
+      host: this.#host,
+    });
+    this.#nativeHost = new NativeTerminalSessionHost(options.nativeHost);
+    this.#sessionNamePrefix = validSessionPrefix(options.sessionNamePrefix ?? 'supercode');
+  }
+
+  async start() {
+    await this.#bridge.start();
+  }
+
+  async snapshot() {
+    try {
+      const nativeSessions = await this.#host.listSessions();
+      const sessions = nativeSessions.map((session) => Object.freeze({
+        ...session,
+        cwd: session.cwd ? (this.#formatCwd(session.cwd) ?? null) : null,
+      }));
+      this.#contextBySession.clear();
+      for (const session of sessions) {
+        if (session.contextKey) this.#contextBySession.set(session.id, session.contextKey);
+      }
+      return Object.freeze({
+        attachment: this.#attachment,
+        available: true,
+        bindings: Object.freeze([...this.#contextBySession].map(([sessionId, conversationKey]) =>
+          Object.freeze({ conversationKey, sessionId }),
+        )),
+        canOpenLocal: process.platform === 'darwin',
+        error: this.#error,
+        sessions: Object.freeze(sessions),
+      });
+    } catch (error) {
+      this.#error = errorMessage(error);
+      return Object.freeze({
+        attachment: null,
+        available: false,
+        bindings: Object.freeze([]),
+        canOpenLocal: process.platform === 'darwin',
+        error: this.#error,
+        sessions: Object.freeze([]),
+      });
+    }
+  }
+
+  async create(harness, cwd) {
+    assertTerminalHarness(harness);
+    const program = TERMINAL_HARNESS_PROGRAMS[harness];
+    const session = await this.#host.createSession({
+      command: { program },
+      cwd,
+      name: this.#sessionName(harness),
+    });
+    this.#attachment = this.#attachmentFor(session.id, 'control');
+    return await this.snapshot();
+  }
+
+  async launchSession(harness, launch, conversationKey = null, initialInput, options = {}) {
+    const harnessLabel = validHarnessLabel(harness);
+    if (initialInput !== undefined) assertTerminalHarness(harness);
+    let pendingConversationBinding = null;
+    if (!conversationKey && options?.conversationDiscovery) {
+      assertTerminalHarness(harness);
+      const discovery = options.conversationDiscovery;
+      if (
+        !Array.isArray(discovery.knownConversationKeys) ||
+        typeof discovery.prompt !== 'string' ||
+        !discovery.prompt.trim()
+      ) {
+        throw new TypeError('conversationDiscovery requires knownConversationKeys and a prompt.');
+      }
+      pendingConversationBinding = {
+        cwd: launch.cwd,
+        harness: harnessLabel,
+        knownConversationKeys: new Set(discovery.knownConversationKeys.slice(0, 500).filter(
+          (key) => typeof key === 'string' && key && key.length <= 200,
+        )),
+        prompt: discovery.prompt.trim().slice(0, 50_000),
+        startedAtMs: Number.isFinite(discovery.startedAtMs) ? discovery.startedAtMs : Date.now(),
+      };
+    }
+    this.#error = null;
+    const session = await this.#host.createSession({
+      command: { arguments: launch.arguments ?? [], program: launch.program },
+      ...(conversationKey ? { contextKey: conversationKey } : {}),
+      cwd: launch.cwd,
+      env: launch.env,
+      name: this.#sessionName(harnessLabel),
+    });
+    if (session.contextKey) this.#contextBySession.set(session.id, session.contextKey);
+    if (pendingConversationBinding) {
+      this.#pendingConversationBindings.set(session.id, pendingConversationBinding);
+    }
+    this.#attachment = this.#attachmentFor(session.id, 'control');
+    if (initialInput !== undefined) this.#queueInitialInput(session.id, harness, initialInput);
+    return await this.snapshot();
+  }
+
+  async attach(sessionId, mode) {
+    this.#attachment = this.#attachmentFor(sessionId, mode);
+    return await this.snapshot();
+  }
+
+  async bindContext(sessionId, conversationKey) {
+    await this.#host.bindContext(sessionId, conversationKey);
+    this.#contextBySession.set(sessionId, conversationKey);
+    if (this.#attachment?.sessionId === sessionId) {
+      this.#attachment = Object.freeze({ ...this.#attachment, conversationKey });
+    }
+    return await this.snapshot();
+  }
+
+  async reconcileConversationBindings(descriptors, keyForDescriptor, options = {}) {
+    if (!Array.isArray(descriptors) || typeof keyForDescriptor !== 'function') {
+      throw new TypeError('reconcileConversationBindings requires descriptors and keyForDescriptor.');
+    }
+    if (this.#conversationBindingInFlight) {
+      await this.#conversationBindingInFlight.catch(() => undefined);
+      return await this.reconcileConversationBindings(descriptors, keyForDescriptor, options);
+    }
+    const task = this.#reconcileConversationBindings(descriptors, keyForDescriptor, options);
+    this.#conversationBindingInFlight = task;
+    try {
+      return await task;
+    } finally {
+      if (this.#conversationBindingInFlight === task) this.#conversationBindingInFlight = null;
+    }
+  }
+
+  async #reconcileConversationBindings(descriptors, keyForDescriptor, options) {
+    const now = Number.isFinite(options.now) ? options.now : Date.now();
+    const bound = [];
+    for (const [terminalSessionId, pending] of this.#pendingConversationBindings) {
+      if (now - pending.startedAtMs > 10 * 60_000) {
+        this.#pendingConversationBindings.delete(terminalSessionId);
+        continue;
+      }
+      const matches = descriptors.slice(0, 500).filter((descriptor) => {
+        const key = keyForDescriptor(descriptor);
+        if (
+          pending.knownConversationKeys.has(key) ||
+          descriptor?.locator?.harness !== pending.harness ||
+          descriptor.cwd !== pending.cwd
+        ) return false;
+        return [
+          ...(descriptor.preview_candidates ?? []),
+          ...(descriptor.latest_message_candidates ?? []),
+        ].some((candidate) =>
+          candidate?.role === 'user' &&
+          typeof candidate.content === 'string' &&
+          candidate.content.trim() === pending.prompt);
+      });
+      const [match] = matches;
+      if (matches.length !== 1 || !match) continue;
+      const conversationKey = keyForDescriptor(match);
+      await this.bindContext(terminalSessionId, conversationKey);
+      this.#pendingConversationBindings.delete(terminalSessionId);
+      bound.push(Object.freeze({ conversationKey, sessionId: terminalSessionId }));
+    }
+    return Object.freeze({
+      bindings: Object.freeze(bound),
+      snapshot: await this.snapshot(),
+    });
+  }
+
+  async close(sessionId) {
+    this.#pendingInitialInputs.get(sessionId)?.abort.abort();
+    this.#pendingInitialInputs.delete(sessionId);
+    this.#pendingConversationBindings.delete(sessionId);
+    const live = await this.#host.listSessions();
+    if (live.some((session) => session.id === sessionId)) {
+      try {
+        this.#host.closeSession(sessionId);
+      } catch (error) {
+        if (!(error instanceof TerminalHostError) || error.code !== 'session_not_found') throw error;
+      }
+    }
+    this.#contextBySession.delete(sessionId);
+    if (this.#attachment?.sessionId === sessionId) this.#attachment = null;
+    return await this.snapshot();
+  }
+
+  async openLocal(sessionId) {
+    await this.#host.openLocalTerminal(sessionId);
+    return await this.snapshot();
+  }
+
+  async dismiss() {
+    this.#attachment = null;
+    return await this.snapshot();
+  }
+
+  async refreshNativeSessions() {
+    const sessions = await this.#nativeHost.listSessions();
+    this.#nativeSessionIds.clear();
+    for (const session of sessions) this.#nativeSessionIds.add(session.agentSessionId);
+  }
+
+  canMoveSession(harness, sessionId, cwd) {
+    if (!isInteractiveTerminalHarness(harness)) return false;
+    const agentSessionId = nativeAgentSessionId(harness, sessionId);
+    return this.#nativeSessionIds.has(agentSessionId)
+      || this.#nativeHost.hasSessionCandidate(agentSessionId, { cwd });
+  }
+
+  async prepareMoveSession(harness, sessionId, cwd, proof) {
+    const agentSessionId = nativeAgentSessionId(harness, sessionId);
+    if (proof && this.#nativeSessionIds.has(agentSessionId)) return proof;
+    const resolution = await this.#nativeHost.resolveSession(agentSessionId, { cwd });
+    if (!resolution) return null;
+    this.#nativeSessionIds.add(resolution.session.agentSessionId);
+    return resolution.proof;
+  }
+
+  async moveSession(harness, sessionId, launch, conversationKey, proof) {
+    const agentSessionId = nativeAgentSessionId(harness, sessionId);
+    if (!this.#nativeSessionIds.has(agentSessionId)) {
+      throw new TerminalHostError(
+        'native_session_not_found',
+        'This conversation is not running in a visible local terminal.',
+      );
+    }
+    await this.#nativeHost.relinquishSession(agentSessionId, proof);
+    this.#nativeSessionIds.delete(agentSessionId);
+    return await this.launchSession(harness, launch, conversationKey);
+  }
+
+  async stop() {
+    this.#attachment = null;
+    await this.#conversationBindingInFlight?.catch(() => undefined);
+    for (const pending of this.#pendingInitialInputs.values()) pending.abort.abort();
+    await Promise.allSettled([...this.#pendingInitialInputs.values()].map(({ task }) => task));
+    this.#pendingInitialInputs.clear();
+    this.#pendingConversationBindings.clear();
+    this.#host.dispose();
+    await this.#bridge.stop();
+  }
+
+  #attachmentFor(sessionId, mode) {
+    return Object.freeze({
+      ...this.#bridge.issueAttachment(sessionId, { mode }),
+      conversationKey: this.#contextBySession.get(sessionId) ?? null,
+      sessionId,
+    });
+  }
+
+  #queueInitialInput(sessionId, harness, input) {
+    const abort = new AbortController();
+    const task = (async () => {
+      const deadline = Date.now() + 5 * 60_000;
+      while (!abort.signal.aborted && Date.now() < deadline) {
+        const content = this.#host.capture(sessionId, { lines: 80 });
+        if (composerReadyForInput(harness, content) === true) {
+          if (harness === 'codex') {
+            await this.#submitCodexInitialInput(sessionId, input, abort.signal);
+          } else {
+            await this.#host.sendInput(sessionId, input, {
+              deadlineMs: Date.now() + 15_000,
+              submitMode: 'retry',
+            });
+          }
+          return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+      if (!abort.signal.aborted) throw new Error(`${harness} did not reach its input prompt`);
+    })().catch((error) => {
+      if (!abort.signal.aborted) {
+        this.#error = `initial terminal message was not delivered: ${errorMessage(error)}`;
+      }
+    }).finally(() => {
+      if (this.#pendingInitialInputs.get(sessionId)?.task === task) {
+        this.#pendingInitialInputs.delete(sessionId);
+      }
+    });
+    this.#pendingInitialInputs.set(sessionId, { abort, task });
+  }
+
+  async #submitCodexInitialInput(sessionId, input, signal) {
+    await this.#host.sendInput(sessionId, input, {
+      deadlineMs: Date.now() + 15_000,
+      submitMode: 'single',
+    });
+    const deadline = Date.now() + 60_000;
+    let sawPrompt = false;
+    while (!signal.aborted && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      const state = codexInitialInputState(this.#host.capture(sessionId, { lines: 100 }), input);
+      sawPrompt ||= state.promptVisible;
+      if (state.turnStarted || (sawPrompt && state.emptyComposerVisible)) return;
+      await this.#host.sendInput(sessionId, '\n', {
+        deadlineMs: Date.now() + 15_000,
+        submitMode: 'retry',
+      });
+    }
+    if (!signal.aborted) {
+      throw new Error('codex accepted the initial terminal text but did not start the turn');
+    }
+  }
+
+  #sessionName(harness) {
+    const label = harness === 'claude-code' ? 'claude' : harness;
+    return `${this.#sessionNamePrefix}-${label}-${randomUUID().slice(0, 8)}`;
+  }
+}
+
+export class TerminalHostError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = 'TerminalHostError';
+  }
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function positiveOptionalInteger(value) {
+  if (value === null || value === '') return undefined;
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function isEmptyServerError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes('no server running') || message.includes('error connecting to');
+}
+
+function positiveInteger(value, name) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new TerminalHostError('invalid_option', `${name} must be a positive integer.`);
+  }
+  return value;
+}
+
+function assertTerminalHarness(harness) {
+  if (!isInteractiveTerminalHarness(harness)) {
+    throw new TerminalHostError(
+      'unsupported_harness',
+      `${String(harness)} native terminal handoff is not supported`,
+    );
+  }
+}
+
+function isInteractiveTerminalHarness(harness) {
+  return typeof harness === 'string' && Object.hasOwn(TERMINAL_HARNESS_PROGRAMS, harness);
+}
+
+function validHarnessLabel(harness) {
+  if (typeof harness !== 'string' || !/^[A-Za-z0-9_-]{1,32}$/.test(harness)) {
+    throw new TerminalHostError('invalid_harness', 'A terminal harness id must be a safe name.');
+  }
+  return harness;
+}
+
+function nativeAgentSessionId(harness, sessionId) {
+  assertTerminalHarness(harness);
+  return `${NATIVE_AGENT_PREFIXES[harness]}:${sessionId}`;
+}
+
+/**
+ * What each interactive kind's IDLE COMPOSER looks like on a captured screen:
+ * the program has finished booting its TUI and is waiting for a first message.
+ * A table rather than a branch chain so the set of kinds that HAVE a pattern is
+ * the table's own keys — no second list to drift out of step with it.
+ */
+const COMPOSER_READY = Object.freeze({
+  // codex's placeholder text IS the empty-composer state, which is exactly the
+  // question here: not "is there a caret" but "is it waiting for a first
+  // message". A composer already holding a draft does not show it.
+  codex: (screen) => screen.includes('› Ask Codex to do anything'),
+  'claude-code': (screen) => composerLine(screen, /^❯(?:\s|$)/u),
+  // gemini draws its idle input caret as a bare ASCII `>` opening a line. The
+  // pattern is transcribed from substrate/session-lifecycle.js's isGeminiIdle,
+  // which derived it from real `gemini` captures, rather than invented here.
+  gemini: (screen) => composerLine(screen, /^>(?:\s|$)/u),
+  // grok v1.0.13, captured live from a tmux pane: the banner is followed by a
+  // `minimal · /help` hint, a lone `❯` composer line, and a status row
+  // (`Grok 4.6 (high) · always-approve · … · ctrl+o transcript`). The caret glyph is
+  // the same one claude uses; this check is per-kind, so they cannot collide.
+  grok: (screen) => composerLine(screen, /^❯(?:\s|$)/u),
+});
+
+/**
+ * Does any line of the screen open with this caret? Lines are trimmed first,
+ * exactly as substrate/session-lifecycle.js's `visibleLines` does for the same
+ * carets: a composer indented by a box or a left gutter is still a composer,
+ * and anchoring on column 0 instead would read a drawn-in prompt as absent.
+ */
+function composerLine(screen, caret) {
+  return screen.split('\n').some((line) => caret.test(line.trim()));
+}
+
+/**
+ * Is the program of this kind showing its idle composer — ready to be given a
+ * first message — on this captured screen?
+ *
+ * Three answers, not two: `true` and `false` are readings of a kind whose
+ * composer this package knows, and `null` is "no pattern for that kind", which
+ * a caller must not read as "not ready yet". Anyone driving a pane it cannot
+ * recognize needs to fall back to its own evidence rather than wait forever on
+ * a pattern that will never match.
+ *
+ * Exported because the same question is asked wherever a pane is given text it
+ * did not ask for — this controller's own initial message and the teams node's
+ * `launch --input` — and one set of patterns with one precision beats a copy
+ * per surface.
+ */
+export function composerReadyForInput(kind, screen) {
+  if (!Object.hasOwn(COMPOSER_READY, kind)) return null;
+  return COMPOSER_READY[kind](String(screen ?? ''));
+}
+
+/**
+ * Does the composer on this screen hold text the person typed (a draft)?
+ * `screen` is a capture WITH escapes, because an empty composer may show a
+ * placeholder, and only its styling (dim or grey) tells it from a draft.
+ *
+ *   true    the last composer line holds typed text
+ *   false   the composer is on screen and empty (or shows only a placeholder)
+ *   null    no composer is on screen (a menu, a dialog, a program still
+ *           booting), or the kind has no composer pattern
+ *
+ * The caret is the kind's own, the one `composerReadyForInput` reads.
+ */
+export function composerHoldsDraft(kind, screen) {
+  const caret = COMPOSER_CARETS[kind];
+  if (!caret) return null;
+  const lines = String(screen ?? '').split('\n');
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const cells = styledCells(lines[index]);
+    const text = cells.map((cell) => cell.char).join('');
+    const start = text.length - text.trimStart().length;
+    if (!text.trimStart().startsWith(caret)) continue;
+    const typed = cells
+      .slice(start + caret.length)
+      .filter((cell) => !cell.placeholder)
+      .map((cell) => cell.char)
+      .join('')
+      .trim();
+    if (kind === 'codex' && typed.startsWith('Ask Codex to do anything')) return false;
+    return typed.length > 0;
+  }
+  return null;
+}
+
+/** The caret each kind draws at the start of its composer line. */
+const COMPOSER_CARETS = Object.freeze({ 'claude-code': '❯', codex: '›', gemini: '>', grok: '❯' });
+
+/**
+ * The visible characters of one captured line, each marked as placeholder
+ * styling (dim, bright black, or a grey foreground) or not. Only SGR
+ * sequences carry meaning here; any other escape is skipped.
+ */
+function styledCells(line) {
+  const cells = [];
+  let dim = false;
+  let grey = false;
+  const pattern = /\u001b\[([0-9;:]*)([A-Za-z])|\u001b[^[]|([^\u001b])/gu;
+  for (const match of line.matchAll(pattern)) {
+    if (match[3] !== undefined) {
+      cells.push({ char: match[3], placeholder: dim || grey });
+      continue;
+    }
+    if (match[2] !== 'm') continue;
+    const codes = (match[1] || '0').split(/[;:]/u).map(Number);
+    for (let at = 0; at < codes.length; at += 1) {
+      const code = codes[at];
+      if (code === 0) { dim = false; grey = false; }
+      else if (code === 2) dim = true;
+      else if (code === 22) dim = false;
+      else if (code === 90) grey = true;
+      else if (code === 39 || (code >= 30 && code <= 37) || (code >= 91 && code <= 97)) grey = false;
+      else if (code === 38 && codes[at + 1] === 5) { const shade = codes[at + 2]; grey = shade === 8 || (shade >= 232 && shade <= 250); at += 2; }
+      else if (code === 38 && codes[at + 1] === 2) { const [r, g, b] = codes.slice(at + 2, at + 5); grey = r === g && g === b && r < 200; at += 4; }
+      else if (code === 48) at += codes[at + 1] === 5 ? 2 : codes[at + 1] === 2 ? 4 : 0;
+    }
+  }
+  return cells;
+}
+
+function codexInitialInputState(content, input) {
+  const firstLine = input.replace(/(?:\r\n|\n|\r)$/u, '').split(/\r?\n/u, 1)[0] ?? '';
+  const marker = `› ${firstLine.slice(0, 24)}`;
+  const promptAt = marker.length > 2 ? content.lastIndexOf(marker) : -1;
+  const emptyComposerAt = content.lastIndexOf('› Ask Codex to do anything');
+  const tail = promptAt >= 0 ? content.slice(promptAt + marker.length) : '';
+  return {
+    emptyComposerVisible: emptyComposerAt > promptAt,
+    promptVisible: promptAt >= 0,
+    turnStarted: promptAt >= 0 && /(?:^|\n)\s*[•◦✦⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]\s/u.test(tail),
+  };
+}
+
+function validSessionPrefix(value) {
+  if (!/^[A-Za-z0-9_-]{1,32}$/.test(value)) {
+    throw new TerminalHostError(
+      'invalid_session_prefix',
+      'A terminal session prefix must contain 1–32 letters, numbers, underscores, or hyphens.',
+    );
+  }
+  return value;
+}
+
+function randomToken() {
+  return randomBytes(24).toString('base64url');
+}
+
+// The lifecycle observation the substrate already performs, re-exported from the
+// package's main entry so a consumer of this SDK can read a pane's evidence
+// without reaching into `substrate/` by path. `classifyAttentionSignal` is the
+// one classifier for the finer screen read (a crash, a pending choice): it is
+// deliberately conservative and returns undefined on anything ambiguous, so
+// every surface that triages panes shares one precision rather than each
+// inventing its own patterns.
+export { classifyAttentionSignal, observeLifecycle, gatherLifecycleObservation, createLifecycleStore, snapshotProcessTree, snapshotProcessTreeAsync } from './substrate/session-lifecycle.js';