local-operator-ui 0.29.11 → 0.29.12

package/out/main/index.js

@@ -15,6 +15,8 @@ const dotenv = require("dotenv");
 const electronLog = require("electron-log");
 const promises = require("node:fs/promises");
 const node_net = require("node:net");
+const headless = require("@xterm/headless");
+const node_module = require("node:module");
 const node_http = require("node:http");
 const https = require("node:https");
 const electronUpdater = require("electron-updater");
@@ -4572,7 +4574,7 @@ class DesktopFeedRelay {
     }
   }
   pause() {
-    const delay = Math.min(
+    const delay2 = Math.min(
       RECONNECT_MAX_MS,
       RECONNECT_MIN_MS * 2 ** Math.min(this.attempt, 5)
     );
@@ -4583,7 +4585,7 @@ class DesktopFeedRelay {
         this.reconnectTimer = null;
         this.reconnectResolve = null;
         resolve();
-      }, delay);
+      }, delay2);
       this.reconnectTimer.unref?.();
     });
   }
@@ -10168,6 +10170,2697 @@ class BackendInstaller {
     }
   }
 }
+const CONSOLE_METHODS = [
+  "console_list",
+  "console_create",
+  "console_status",
+  "console_read",
+  "console_screenshot",
+  "console_input",
+  "console_keys",
+  "console_resize",
+  "console_secure",
+  "console_close"
+];
+new Set(
+  CONSOLE_METHODS
+);
+const CONSOLE_ERROR_CODES = [
+  "unsupported_method",
+  "surface_unavailable",
+  "surface_not_owned",
+  "process_exited",
+  "input_queue_full",
+  "unknown_key",
+  "secure_input_active",
+  "console_unavailable",
+  "invalid_grid",
+  "capture_unavailable"
+];
+const PROTO_VERSION = 1;
+const METHODS$1 = [
+  "open",
+  "goto",
+  "read",
+  "snapshot",
+  "screenshot",
+  "click",
+  "type",
+  "close",
+  "status",
+  "tabs",
+  "scroll",
+  "logs",
+  "request_access",
+  "await_access",
+  "cancel_access",
+  "retitle",
+  "owner_recover",
+  "owner_finish",
+  "owner_retain",
+  "owner_release",
+  ...CONSOLE_METHODS
+];
+const METHOD_SET = new Set(METHODS$1);
+function isMethod(value) {
+  return typeof value === "string" && METHOD_SET.has(value);
+}
+const ERROR_CODES = [
+  "extension_disconnected",
+  "not_paired",
+  "tab_closed",
+  "nav_failed",
+  "nav_timeout",
+  "element_not_found",
+  "origin_denied",
+  "origin_prompt_pending",
+  "origin_not_allowed",
+  "debugger_conflict",
+  "access_queue_full",
+  "tab_limit",
+  "tab_ambiguous",
+  "busy",
+  "proto_mismatch",
+  "owner_refused",
+  "extension_unresponsive",
+  "internal",
+  // The console namespace's own additions (design 10.6). Spread rather than copied
+  // for the same reason METHODS is: this list is what `rpc.ts` narrows a raised
+  // code against, and an unknown code is silently dropped by the session's model —
+  // a command that hangs rather than one that fails.
+  ...CONSOLE_ERROR_CODES
+];
+const RUN_DIRNAME = path$1.join("run", "ui-browser");
+const STATE_FILENAME = "host.json";
+const STATE_DIR_MODE = 448;
+const STATE_FILE_MODE = 384;
+const HEARTBEAT_INTERVAL_MS = 15e3;
+function localOperatorConfigDir() {
+  const configured = process.env.LOCAL_OPERATOR_CONFIG_DIR?.trim();
+  if (configured) return configured;
+  return path$1.join(os.homedir(), ".local-operator");
+}
+function stateFilePath(root = localOperatorConfigDir()) {
+  return path$1.join(root, RUN_DIRNAME, STATE_FILENAME);
+}
+function mintSessionKey() {
+  return node_crypto.randomBytes(32).toString("base64url");
+}
+function keysMatch(presented, expected) {
+  if (typeof presented !== "string") return false;
+  const a = Buffer.from(presented, "utf8");
+  const b = Buffer.from(expected, "utf8");
+  if (a.length !== b.length) return false;
+  return node_crypto.timingSafeEqual(a, b);
+}
+class BrowserStateWriter {
+  constructor(path2, facts, options) {
+    this.path = path2;
+    this.facts = facts;
+    this.now = options.now ?? Date.now;
+    this.onError = options.onError ?? (() => {
+    });
+    this.appVersion = options.appVersion;
+  }
+  now;
+  onError;
+  timer = null;
+  written = false;
+  appVersion;
+  /** Publish the record and start the heartbeat. The heartbeat is the
+   * difference between "the app is running and can open a tab on demand" and a
+   * record that names a process that died without cleaning up. */
+  start(port, sessionKey) {
+    const startedAt = this.now() / 1e3;
+    this.startedAt = startedAt;
+    this.port = port;
+    this.sessionKey = sessionKey;
+    this.write();
+    this.timer = setInterval(() => this.write(), HEARTBEAT_INTERVAL_MS);
+    this.timer.unref?.();
+  }
+  startedAt = 0;
+  port = 0;
+  sessionKey = "";
+  /** Re-publish immediately, without waiting for the next heartbeat. Called
+   * when something the record reports has changed (a tab opened or closed). */
+  publishNow() {
+    if (this.port === 0) return;
+    this.write();
+  }
+  write() {
+    try {
+      const facts = this.facts();
+      const state = {
+        pid: process.pid,
+        port: this.port,
+        session_key: this.sessionKey,
+        proto: PROTO_VERSION,
+        host: "ui",
+        app_version: this.appVersion,
+        profile_dir: facts.profileDir,
+        tabs: facts.tabs,
+        agent_tabs: facts.agentTabs,
+        console: facts.console ?? false,
+        console_surfaces: facts.consoleSurfaces ?? 0,
+        console_agent_surfaces: facts.consoleAgentSurfaces ?? 0,
+        heartbeat_at: this.now() / 1e3,
+        started_at: this.startedAt || this.now() / 1e3
+      };
+      fs.mkdirSync(path$1.dirname(this.path), {
+        recursive: true,
+        mode: STATE_DIR_MODE
+      });
+      const staged = `${this.path}.${process.pid}.tmp`;
+      fs.writeFileSync(staged, `${JSON.stringify(state, null, 2)}
+`, {
+        mode: STATE_FILE_MODE
+      });
+      fs.renameSync(staged, this.path);
+      enforceStateFileModes(this.path);
+      this.written = true;
+    } catch (error) {
+      this.onError(error);
+    }
+  }
+  /** Remove the record, so discovery is honest when the host is gone. Called on
+   * host stop, on quit, and by the Settings toggle that turns the host off. */
+  clear() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (!this.written) return;
+    try {
+      fs.unlinkSync(this.path);
+    } catch (error) {
+      this.onError(error);
+    }
+    this.written = false;
+  }
+}
+function enforceStateFileModes(path2) {
+  try {
+    fs.chmodSync(path$1.dirname(path2), STATE_DIR_MODE);
+    fs.chmodSync(path2, STATE_FILE_MODE);
+  } catch {
+  }
+}
+class BridgeCommandError extends Error {
+  constructor(code, message, data = {}) {
+    super(message);
+    this.code = code;
+    this.data = data;
+  }
+}
+class ConsoleError extends BridgeCommandError {
+  constructor(code, message, data = {}) {
+    super(code, message, data);
+  }
+}
+const RETAIN_BYTES = 4 * 1024 * 1024;
+const CEILING_BYTES = 16 * 1024 * 1024;
+class ByteLog {
+  retainBytes;
+  ceilingBytes;
+  /** Oldest first. Chunks are the pty's own reads, so a trim drops many bytes at
+   * once without copying the ones it keeps. */
+  chunks = [];
+  retained = 0;
+  /** Absolute offset just past the last byte ever appended. */
+  end = 0;
+  /** Absolute offset of the oldest retained byte. */
+  start = 0;
+  dropped = 0;
+  constructor(options = {}) {
+    this.retainBytes = options.retainBytes ?? RETAIN_BYTES;
+    this.ceilingBytes = options.ceilingBytes ?? CEILING_BYTES;
+    if (this.ceilingBytes < this.retainBytes) {
+      throw new Error(
+        "a byte log's ceiling must not be below its retained window"
+      );
+    }
+  }
+  /** Absolute offset of the oldest retained byte. */
+  get startOffset() {
+    return this.start;
+  }
+  /** Absolute offset just past the newest byte. */
+  get endOffset() {
+    return this.end;
+  }
+  /** How many bytes are held right now. */
+  get retainedBytes() {
+    return this.retained;
+  }
+  /** Whether any byte has ever been dropped, i.e. the log is not complete. */
+  get truncated() {
+    return this.dropped > 0;
+  }
+  /** How many bytes have been dropped since the surface was created. */
+  get droppedBytes() {
+    return this.dropped;
+  }
+  append(bytes) {
+    if (bytes.length === 0) return;
+    const copy = Uint8Array.from(bytes);
+    this.chunks.push({ offset: this.end, bytes: copy });
+    this.retained += copy.length;
+    this.end += copy.length;
+    this.trim(copy.length);
+  }
+  /**
+   * Read the retained bytes from `from` onward.
+   *
+   * A `from` below `startOffset` is answered with the retained window and
+   * `truncated: true` rather than an error: the caller asked "everything since
+   * N", and the honest answer is "everything since N is gone; here is the rest".
+   */
+  read(from = 0) {
+    const wanted = Math.max(Math.trunc(from) || 0, 0);
+    const first = Math.max(wanted, this.start);
+    const startIndex = Math.min(first, this.end);
+    const length = Math.max(this.end - startIndex, 0);
+    const out = new Uint8Array(length);
+    let written = 0;
+    for (const chunk of this.chunks) {
+      const chunkEnd = chunk.offset + chunk.bytes.length;
+      if (chunkEnd <= startIndex) continue;
+      const skip = Math.max(startIndex - chunk.offset, 0);
+      const slice = chunk.bytes.subarray(skip);
+      out.set(slice, written);
+      written += slice.length;
+    }
+    return {
+      bytes: out,
+      from: startIndex,
+      to: this.end,
+      truncated: wanted < this.start
+    };
+  }
+  /**
+   * Drop the oldest bytes so the next append cannot cross the ceiling.
+   *
+   * Called with the size of the append that just landed, so a single append
+   * larger than the whole ceiling is handled by the same rule: whatever the size
+   * of the newest bytes, at least the newest `retainBytes` survive, so a reader
+   * always has a window rather than an empty log.
+   */
+  trim(newestChunkBytes) {
+    if (this.retained <= this.ceilingBytes) return;
+    const keep = Math.max(this.retainBytes, newestChunkBytes);
+    while (this.chunks.length > 1 && this.retained > keep) {
+      const oldest = this.chunks[0];
+      if (this.retained - oldest.bytes.length < keep) break;
+      this.chunks.shift();
+      this.retained -= oldest.bytes.length;
+      this.start = oldest.offset + oldest.bytes.length;
+      this.dropped += oldest.bytes.length;
+    }
+    if (this.chunks.length === 1 && this.retained > this.ceilingBytes) {
+      const only = this.chunks[0];
+      const kept = only.bytes.subarray(only.bytes.length - keep);
+      this.dropped += only.bytes.length - kept.length;
+      this.start = only.offset + (only.bytes.length - kept.length);
+      this.chunks = [{ offset: this.start, bytes: Uint8Array.from(kept) }];
+      this.retained = kept.length;
+    }
+  }
+}
+function createXtermEmulator(options) {
+  const terminal = new headless.Terminal({
+    cols: options.cols,
+    rows: options.rows,
+    scrollback: options.scrollback,
+    allowProposedApi: true
+  });
+  let pending = 0;
+  let idle = null;
+  const settleIfIdle = () => {
+    if (pending > 0) return;
+    const resolve = idle;
+    idle = null;
+    resolve?.();
+  };
+  const lineText = (index) => {
+    const line = terminal.buffer.active.getLine(index);
+    return line ? line.translateToString(true) : "";
+  };
+  const bufferLineCount = () => {
+    return terminal.buffer.active.length;
+  };
+  return {
+    write(bytes) {
+      pending += 1;
+      terminal.write(bytes, () => {
+        pending -= 1;
+        settleIfIdle();
+      });
+    },
+    resize(cols, rows) {
+      terminal.resize(cols, rows);
+    },
+    text(mode, window) {
+      const buffer = terminal.buffer.active;
+      const last = bufferLineCount();
+      const first = mode === "viewport" ? Math.min(buffer.viewportY, last) : truncateToInt(window?.start ?? 0, 0, last);
+      const wanted = mode === "viewport" ? terminal.rows : window?.count === void 0 ? Math.max(buffer.viewportY - first, 0) : truncateToInt(window.count, 0, last - first);
+      const end = Math.min(first + wanted, last);
+      const lines = [];
+      for (let index = first; index < end; index += 1) {
+        lines.push(lineText(index));
+      }
+      return lines.join("\n");
+    },
+    get grid() {
+      const buffer = terminal.buffer.active;
+      return {
+        cols: terminal.cols,
+        rows: terminal.rows,
+        viewportTop: buffer.viewportY,
+        lineCount: bufferLineCount(),
+        cursor: { x: buffer.cursorX, y: buffer.cursorY },
+        modes: {
+          bracketedPaste: terminal.modes.bracketedPasteMode,
+          applicationCursorKeys: terminal.modes.applicationCursorKeysMode,
+          mouseTracking: terminal.modes.mouseTrackingMode
+        }
+      };
+    },
+    whenIdle() {
+      if (pending === 0) return Promise.resolve();
+      return new Promise((resolve) => {
+        idle = resolve;
+      });
+    },
+    dispose() {
+      terminal.dispose();
+    }
+  };
+}
+function truncateToInt(value, min, max) {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(Math.max(Math.trunc(value), min), max);
+}
+const NAMED_KEYS = [
+  "enter",
+  "return",
+  "tab",
+  "shift+tab",
+  "backspace",
+  "escape",
+  "space",
+  "up",
+  "down",
+  "left",
+  "right",
+  "home",
+  "end",
+  "pageup",
+  "pagedown",
+  "insert",
+  "delete",
+  "f1",
+  "f2",
+  "f3",
+  "f4",
+  "f5",
+  "f6",
+  "f7",
+  "f8",
+  "f9",
+  "f10",
+  "f11",
+  "f12",
+  "ctrl+a",
+  "ctrl+b",
+  "ctrl+c",
+  "ctrl+d",
+  "ctrl+e",
+  "ctrl+f",
+  "ctrl+g",
+  "ctrl+h",
+  "ctrl+i",
+  "ctrl+j",
+  "ctrl+k",
+  "ctrl+l",
+  "ctrl+m",
+  "ctrl+n",
+  "ctrl+o",
+  "ctrl+p",
+  "ctrl+q",
+  "ctrl+r",
+  "ctrl+s",
+  "ctrl+t",
+  "ctrl+u",
+  "ctrl+v",
+  "ctrl+w",
+  "ctrl+x",
+  "ctrl+y",
+  "ctrl+z",
+  "ctrl+space",
+  "ctrl+[",
+  "ctrl+\\",
+  "ctrl+]",
+  "ctrl+^",
+  "ctrl+_"
+];
+const FIXED = /* @__PURE__ */ new Map([
+  ["enter", "\r"],
+  ["return", "\r"],
+  ["tab", "	"],
+  ["shift+tab", "\x1B[Z"],
+  ["backspace", ""],
+  ["escape", "\x1B"],
+  ["space", " "],
+  ["pageup", "\x1B[5~"],
+  ["pagedown", "\x1B[6~"],
+  ["insert", "\x1B[2~"],
+  ["delete", "\x1B[3~"],
+  // F1-F4 are SS3 (their own code, no bracket); F5 onward are CSI with a number.
+  ["f1", "\x1BOP"],
+  ["f2", "\x1BOQ"],
+  ["f3", "\x1BOR"],
+  ["f4", "\x1BOS"],
+  ["f5", "\x1B[15~"],
+  ["f6", "\x1B[17~"],
+  ["f7", "\x1B[18~"],
+  ["f8", "\x1B[19~"],
+  ["f9", "\x1B[20~"],
+  ["f10", "\x1B[21~"],
+  ["f11", "\x1B[23~"],
+  ["f12", "\x1B[24~"]
+]);
+const CONTROL = /* @__PURE__ */ new Map([
+  ["ctrl+space", 0],
+  ["ctrl+[", 27],
+  ["ctrl+\\", 28],
+  ["ctrl+]", 29],
+  ["ctrl+^", 30],
+  ["ctrl+_", 31]
+]);
+for (const letter of "abcdefghijklmnopqrstuvwxyz") {
+  CONTROL.set(`ctrl+${letter}`, letter.charCodeAt(0) - 96);
+}
+const CURSOR = /* @__PURE__ */ new Map([
+  ["up", { normal: "\x1B[A", application: "\x1BOA" }],
+  ["down", { normal: "\x1B[B", application: "\x1BOB" }],
+  ["right", { normal: "\x1B[C", application: "\x1BOC" }],
+  ["left", { normal: "\x1B[D", application: "\x1BOD" }],
+  ["home", { normal: "\x1B[H", application: "\x1BOH" }],
+  ["end", { normal: "\x1B[F", application: "\x1BOF" }]
+]);
+const ENCODER$1 = new TextEncoder();
+const encodeText = (text) => ENCODER$1.encode(text);
+function encodeNamedKey(name, modes) {
+  const fixed = FIXED.get(name);
+  if (fixed !== void 0) return encodeText(fixed);
+  const control = CONTROL.get(name);
+  if (control !== void 0) return Uint8Array.from([control]);
+  const cursor = CURSOR.get(name);
+  if (cursor !== void 0) {
+    return encodeText(
+      modes.applicationCursorKeys ? cursor.application : cursor.normal
+    );
+  }
+  return null;
+}
+const OSC_133_PREFIX = [27, 93, 49, 51, 51, 59];
+const ESC = 27;
+const BEL = 7;
+const BACKSLASH = 92;
+const MAX_BODY_BYTES$1 = 64;
+const KINDS = {
+  A: "prompt-start",
+  B: "command-start",
+  C: "output-start",
+  D: "command-finished"
+};
+class Osc133Scanner {
+  maxBodyBytes;
+  /** How much of `OSC_133_PREFIX` has matched, 0 when not inside one. */
+  matched = 0;
+  /** The body accumulated since the prefix matched, or null when not inside a
+   * sequence. Kept as a number array because a body is a handful of ASCII bytes. */
+  body = null;
+  /** Whether the previous byte was an ESC that may terminate the body. */
+  escaped = false;
+  /** Whether the retained body already exceeded `maxBodyBytes`. Such a sequence
+   * is abandoned rather than truncated, so a long non-133 OSC cannot produce a
+   * mark from its tail. */
+  overflowed = false;
+  /** Bytes fed so far, i.e. the offset of the next byte. */
+  consumed = 0;
+  /** Absolute offset of the sequence currently being read, or null. */
+  sequenceStart = null;
+  constructor(options = {}) {
+    this.maxBodyBytes = options.maxBodyBytes ?? MAX_BODY_BYTES$1;
+  }
+  /** Absolute offset of the next byte this scanner will be given. */
+  get offset() {
+    return this.consumed;
+  }
+  feed(bytes) {
+    const marks = [];
+    for (const byte of bytes) {
+      const mark = this.step(byte);
+      if (mark) marks.push(mark);
+      this.consumed += 1;
+    }
+    return marks;
+  }
+  /** Forget a partial sequence (called when a surface is reset). The offset is
+   * not rewound: offsets are absolute for the surface's life. */
+  reset() {
+    this.matched = 0;
+    this.body = null;
+    this.escaped = false;
+    this.overflowed = false;
+    this.sequenceStart = null;
+  }
+  step(byte) {
+    if (this.body !== null) return this.stepBody(byte);
+    if (byte === OSC_133_PREFIX[this.matched]) {
+      this.matched += 1;
+      if (this.matched === OSC_133_PREFIX.length) {
+        this.body = [];
+        this.sequenceStart = this.consumed - (OSC_133_PREFIX.length - 1);
+        this.matched = 0;
+        this.escaped = false;
+        this.overflowed = false;
+      }
+      return null;
+    }
+    this.matched = byte === OSC_133_PREFIX[0] ? 1 : 0;
+    return null;
+  }
+  stepBody(byte) {
+    if (this.escaped) {
+      this.escaped = false;
+      if (byte === BACKSLASH) return this.finish();
+      this.abandon();
+      this.step(ESC);
+      return this.step(byte);
+    }
+    if (byte === BEL) return this.finish();
+    if (byte === ESC) {
+      this.escaped = true;
+      return null;
+    }
+    if (this.body === null) return null;
+    if (this.body.length >= this.maxBodyBytes) {
+      this.overflowed = true;
+      this.body = null;
+      return null;
+    }
+    this.body.push(byte);
+    return null;
+  }
+  finish() {
+    const body = this.body;
+    const offset = this.sequenceStart ?? 0;
+    this.body = null;
+    this.escaped = false;
+    this.sequenceStart = null;
+    if (body === null || this.overflowed) {
+      this.overflowed = false;
+      return null;
+    }
+    return parseBody(body, offset);
+  }
+  abandon() {
+    this.body = null;
+    this.overflowed = false;
+    this.sequenceStart = null;
+  }
+}
+function parseBody(body, offset) {
+  const text = String.fromCharCode(...body);
+  const [kind, status2] = text.split(";");
+  const mapped = KINDS[kind];
+  if (!mapped) return null;
+  if (status2 === void 0 || status2 === "") {
+    return { kind: mapped, exitCode: null, offset };
+  }
+  const parsed = Number.parseInt(status2, 10);
+  const exitCode = Number.isInteger(parsed) && parsed >= 0 && parsed <= 255 ? parsed : null;
+  return { kind: mapped, exitCode, offset };
+}
+const SURFACE_PREFIX$1 = "con";
+const MAX_AGENT_SURFACES_PER_SESSION = 8;
+const MAX_SURFACES_PER_APP = 32;
+const REDACTED_NONCE_CHARS$1 = 6;
+const SURFACE_TOKEN$1 = /^con:(\d+):([A-Za-z0-9_-]+)$/;
+const NONCE_BYTES = 16;
+class ConsoleRegistry {
+  entries = /* @__PURE__ */ new Map();
+  now;
+  nonce;
+  /** Monotonic slot number: the `<n>` in `con:<n>:<nonce>`. A counter rather
+   * than a reuse of the current size, so a handle never names a surface that was
+   * closed and a later one that took its place. */
+  nextSlot = 1;
+  constructor(options = {}) {
+    this.now = options.now ?? (() => Date.now() / 1e3);
+    this.nonce = options.nonce ?? (() => node_crypto.randomBytes(NONCE_BYTES).toString("base64url"));
+  }
+  /** Every entry, oldest first, optionally filtered to one session. */
+  list(sessionId2) {
+    const all = [...this.entries.values()];
+    return sessionId2 === void 0 ? all : all.filter((entry) => entry.record.sessionId === sessionId2);
+  }
+  /** How many surfaces exist, app-wide. */
+  count() {
+    return this.entries.size;
+  }
+  /** How many were created by that session's agent. */
+  agentCount(sessionId2) {
+    return this.list(sessionId2).filter(
+      (entry) => entry.record.origin === "agent"
+    ).length;
+  }
+  /**
+   * Create an entry, enforcing the caps in the order §6.3 states them.
+   *
+   * The refusals are the browser's own code for the same fact (`tab_limit`) with
+   * `data.limit` and the scope that bound, rather than a console-specific
+   * vocabulary for a generic condition — the same choice the design makes
+   * everywhere the existing taxonomy fits (§10.6).
+   */
+  create(input) {
+    if (this.count() >= MAX_SURFACES_PER_APP) {
+      throw new ConsoleError(
+        "tab_limit",
+        `this app is already holding ${MAX_SURFACES_PER_APP} console surfaces; close one first`,
+        { limit: MAX_SURFACES_PER_APP, scope: "app" }
+      );
+    }
+    if (input.origin === "agent" && this.agentCount(input.sessionId) >= MAX_AGENT_SURFACES_PER_SESSION) {
+      throw new ConsoleError(
+        "tab_limit",
+        `this session's agent is already running ${MAX_AGENT_SURFACES_PER_SESSION} console surfaces; close one first`,
+        { limit: MAX_AGENT_SURFACES_PER_SESSION, scope: "session" }
+      );
+    }
+    const adopted = input.surface ? parseSurface$1(input.surface) : null;
+    const slot = adopted ? adopted.slot : this.nextSlot;
+    this.nextSlot = Math.max(this.nextSlot, slot + 1);
+    const record = {
+      surface: input.surface ?? `${SURFACE_PREFIX$1}:${slot}:${this.nonce()}`,
+      sessionId: input.sessionId,
+      origin: input.origin,
+      command: input.command,
+      argvTail: input.argvTail,
+      cwd: input.cwd,
+      cols: input.cols,
+      rows: input.rows,
+      running: true,
+      exitCode: null,
+      lastActivity: this.now(),
+      live: true,
+      retain: input.retain,
+      secure: false,
+      sizing: input.sizing
+    };
+    const entry = { record, runtime: null };
+    this.entries.set(record.surface, entry);
+    return entry;
+  }
+  /** Attach the host's runtime to an entry it just created. */
+  attach(surface, runtime) {
+    this.require(surface).runtime = runtime;
+  }
+  /**
+   * Look up an entry, or refuse with the typed `surface_unavailable`.
+   *
+   * The message names the handle and how many exist, per §15: a caller that
+   * mis-typed a handle can tell "nothing like this" from "not this one".
+   */
+  require(surface) {
+    const entry = this.entries.get(surface);
+    if (!entry) {
+      throw new ConsoleError(
+        "surface_unavailable",
+        `no console surface named ${redactSurface(surface)}; ${this.entries.size} exist`,
+        { surface: redactSurface(surface), count: this.entries.size }
+      );
+    }
+    return entry;
+  }
+  /**
+   * Look up an entry without raising, for the asynchronous paths.
+   *
+   * A pty's data and exit callbacks fire after a surface may already have been
+   * closed, and a throw inside an event handler is an unhandled exception rather
+   * than a typed refusal a caller can read. Those paths use this and treat "gone"
+   * as "nothing left to do".
+   */
+  find(surface) {
+    return this.entries.get(surface) ?? null;
+  }
+  /**
+   * Require an entry AND that a session owns it.
+   *
+   * Ownership is a fence, not a filter: §15 has the pane show only a session's
+   * own surfaces, and an agent that names another session's handle gets a typed
+   * refusal rather than a read of somebody else's terminal — the browser's
+   * `owner_refused` precedent, spelled the console's way so a caller need not
+   * substring-match a message.
+   *
+   * WHO CALLS IT, stated because a fence nobody stands at is theatre: the
+   * session-scoped callers are the pane's own ops and the harness tool, and neither
+   * is in this PR — the RPC call carries no session identity (the key is per-host,
+   * §10.1), so there is nothing for THIS process to compare a handle against. What
+   * PR A does enforce is the filter half of §15: `console-state`/`console_list`
+   * answer one session's surfaces, which is what the pane renders and what the tool
+   * reads. The refusal is defined and tested here so the seam exists when a caller
+   * has an identity to check.
+   */
+  requireOwned(surface, sessionId2) {
+    const entry = this.require(surface);
+    if (sessionId2 !== void 0 && entry.record.sessionId !== sessionId2) {
+      throw new ConsoleError(
+        "surface_not_owned",
+        `${redactSurface(surface)} belongs to another session`,
+        { surface: redactSurface(surface) }
+      );
+    }
+    return entry;
+  }
+  /** Patch the mutable facts. The handle, the session and the origin never move. */
+  update(surface, patch) {
+    const entry = this.require(surface);
+    entry.record = { ...entry.record, ...patch, surface: entry.record.surface };
+  }
+  /**
+   * Drop an entry.
+   *
+   * Returns the entry it removed, or null when it was already gone — the same
+   * "already gone is the finished state" contract the browser's ownership ledger
+   * uses, so a close is idempotent without a second lookup.
+   */
+  remove(surface) {
+    const entry = this.entries.get(surface);
+    if (!entry) return null;
+    this.entries.delete(surface);
+    return entry;
+  }
+  /** Drop every entry and every runtime. The host's stop path, and the one place
+   * a caller may assume the map is empty afterwards. */
+  clear() {
+    const all = [...this.entries.values()];
+    this.entries.clear();
+    return all;
+  }
+}
+function parseSurface$1(token) {
+  const match = SURFACE_TOKEN$1.exec(token);
+  if (!match) return null;
+  return { slot: Number.parseInt(match[1], 10), nonce: match[2] };
+}
+function redactSurface(surface) {
+  const parsed = parseSurface$1(surface);
+  if (!parsed) return "(malformed handle)";
+  return `${SURFACE_PREFIX$1}:${parsed.slot}:${parsed.nonce.slice(0, REDACTED_NONCE_CHARS$1)}…`;
+}
+const DEFAULT_COLS = 100;
+const DEFAULT_ROWS = 30;
+const MIN_COLS = 40;
+const MIN_ROWS = 10;
+const MAX_COLS = 500;
+const MAX_ROWS = 200;
+const SCROLLBACK_LINES = 5e3;
+const MAX_INPUT_BYTES = 1 << 18;
+const OUTPUT_COALESCE_MS = 16;
+const PERSIST_FLUSH_MS = 250;
+const PERSIST_FLUSH_BYTES = 256 * 1024;
+const MIN_FRAME_BYTES = 2e3;
+const FRAME_RETRY_DELAY_MS = 120;
+const CLOSE_GRACE_MS = 1500;
+const SURFACE_ENV_MARKER = "LOCAL_OPERATOR_CONSOLE_SURFACE";
+const SESSION_ENV_MARKER = "LOCAL_OPERATOR_CONSOLE_SESSION";
+const SURFACE_TERM = "xterm-256color";
+const SURFACE_COLORTERM = "truecolor";
+const STRIPPED_ENV_PREFIXES = ["CMUX_", "LOP_"];
+class ConsoleHost {
+  registry;
+  options;
+  now;
+  env;
+  constructor(registry, options) {
+    this.registry = registry;
+    this.options = options;
+    this.now = options.now ?? (() => Date.now() / 1e3);
+    this.env = options.env ?? process.env;
+  }
+  /** How many surfaces exist, and how many of them an agent made. The record's
+   * own two numbers (§10.1). */
+  counts() {
+    const all = this.registry.list();
+    return {
+      total: all.length,
+      agent: all.filter((entry) => entry.record.origin === "agent").length
+    };
+  }
+  /**
+   * Create a surface.
+   *
+   * THE ORDER OF THE FIVE STEPS MATTERS and is why this is one method: the record
+   * exists before the spawn (so a failed spawn still has a handle to report), the
+   * runtime is attached only after the spawn succeeded, and a spawn failure
+   * removes the record rather than leaving a surface that lists as running.
+   */
+  create(options) {
+    const cols = options.cols ?? DEFAULT_COLS;
+    const rows = options.rows ?? DEFAULT_ROWS;
+    const grid = clampGrid(cols, rows);
+    const command = options.command?.trim() || defaultShell(this.env);
+    const args = options.args ?? [];
+    const cwd = resolveCwd(options.cwd);
+    const entry = this.registry.create({
+      sessionId: options.sessionId,
+      origin: options.origin,
+      command: path$1.basename(command),
+      argvTail: args.join(" "),
+      cwd,
+      cols: grid.cols,
+      rows: grid.rows,
+      // The design's default (§7.2): a user's surface is retained, an agent's is
+      // not — an agent that floods a surface should not fill the disk by default,
+      // and a user who opened one wants it next launch.
+      retain: options.retain ?? options.origin === "user",
+      sizing: options.sizing ?? "auto"
+    });
+    const surface = entry.record.surface;
+    const env = surfaceEnvironment({
+      base: this.env,
+      sessionId: options.sessionId,
+      surface,
+      overrides: options.env
+    });
+    const startProcess = () => {
+      try {
+        return this.options.spawn({
+          file: command,
+          args,
+          cwd,
+          env,
+          cols: grid.cols,
+          rows: grid.rows
+        });
+      } catch (error) {
+        this.registry.remove(surface);
+        throw new ConsoleError(
+          "console_unavailable",
+          `the surface's process could not start: ${error instanceof Error ? error.message : String(error)}`,
+          { reason: "spawn_failed" }
+        );
+      }
+    };
+    const pty = startProcess();
+    const runtime = {
+      pty,
+      log: new ByteLog(),
+      emulator: createXtermEmulator({
+        cols: grid.cols,
+        rows: grid.rows,
+        scrollback: SCROLLBACK_LINES
+      }),
+      scanner: new Osc133Scanner(),
+      subscribers: /* @__PURE__ */ new Set(),
+      pending: [],
+      pendingTimer: null,
+      persistTimer: null,
+      seq: 0,
+      rect: null,
+      theme: null,
+      lastMark: null,
+      exitDelivered: false,
+      exitWaiters: []
+    };
+    this.registry.attach(surface, runtime);
+    pty.onData((data) => this.consume(surface, data));
+    pty.onExit((event) => this.exited(surface, event.exitCode));
+    if (options.input) pty.write(options.input);
+    if (entry.record.retain) this.flush(surface);
+    this.options.log(
+      `[console] surface ${redactSurface(surface)} started: ${path$1.basename(command)} in ${cwd} at ${grid.cols}x${grid.rows} (${options.origin})`
+    );
+    this.options.onChanged?.();
+    const reveal = this.resolveReveal(options.reveal ?? "none");
+    if (reveal !== "none") {
+      this.options.onReveal?.({
+        surface,
+        sessionId: options.sessionId,
+        mode: reveal
+      });
+    }
+    return {
+      surface,
+      cols: grid.cols,
+      rows: grid.rows,
+      pid: pty.pid,
+      live: true,
+      // `reveal` is the intent after the focus rule; `revealed` says whether a
+      // pane was asked for at all. They differ exactly when `reveal: "open"` was
+      // downgraded because raising the window is not something this app does
+      // (design 10.4), and a caller that cannot tell the two apart would believe
+      // the user was shown something they were not.
+      reveal,
+      revealed: reveal !== "none"
+    };
+  }
+  /**
+   * The half of `reveal` this process owns: whether the app's window is already
+   * focused (design 10.4).
+   *
+   * `show`/`showInactive`/`focus` live in `window-raise.ts` alone, and
+   * `scripts/window-mode.test.mjs` asserts it — so a `reveal: "open"` that would
+   * have to raise the window is downgraded here rather than at the renderer. The
+   * renderer's half (is the wanted session the one on screen?) is not a question
+   * main can answer, and it is exactly why `reveal: "session"` is forwarded rather
+   * than resolved.
+   */
+  resolveReveal(mode) {
+    if (mode !== "open") return mode;
+    const window = this.options.window();
+    if (window && !window.isDestroyed() && window.isFocused()) return "open";
+    return "none";
+  }
+  /**
+   * Adopt a surface reconstructed from persisted history (§7.3).
+   *
+   * It is `live: false` from birth, has no pty and never gets one, and its bytes
+   * are replayed into a fresh record so `console_read` and the pane both show what
+   * the surface printed. The listing says so, which is the whole honesty
+   * requirement: nothing here pretends a process is running.
+   */
+  restore(meta, bytes) {
+    const existing = this.registry.list(meta.session_id);
+    if (existing.some((entry2) => entry2.record.surface === meta.surface)) return;
+    const grid = clampGrid(meta.cols, meta.rows);
+    const entry = this.registry.create({
+      // The handle the history recorded, so a caller holding one across a relaunch
+      // finds the same surface rather than a lookalike with a new nonce.
+      surface: meta.surface,
+      sessionId: meta.session_id,
+      origin: meta.origin,
+      command: meta.command,
+      argvTail: meta.argv.join(" "),
+      cwd: meta.cwd,
+      cols: grid.cols,
+      rows: grid.rows,
+      retain: true,
+      sizing: "auto"
+    });
+    this.createdAt.set(
+      meta.surface,
+      Number.isFinite(meta.created_at) ? meta.created_at : this.now()
+    );
+    this.exitEpoch.set(
+      meta.surface,
+      Number.isFinite(meta.exit_epoch) ? meta.exit_epoch : 0
+    );
+    const emulator = createXtermEmulator({
+      cols: grid.cols,
+      rows: grid.rows,
+      scrollback: SCROLLBACK_LINES
+    });
+    emulator.write(bytes);
+    const runtime = {
+      // A reconstructed surface has no pty. `null` rather than a fake process:
+      // every path that would signal one checks `running` first, and the record
+      // says `running: false` for this surface forever.
+      pty: null,
+      log: new ByteLog(),
+      emulator,
+      scanner: new Osc133Scanner(),
+      subscribers: /* @__PURE__ */ new Set(),
+      pending: [],
+      pendingTimer: null,
+      persistTimer: null,
+      seq: 0,
+      rect: null,
+      theme: null,
+      lastMark: null,
+      exitDelivered: true,
+      exitWaiters: []
+    };
+    runtime.log.append(bytes);
+    this.registry.attach(entry.record.surface, runtime);
+    this.registry.update(entry.record.surface, {
+      running: false,
+      exitCode: meta.exit_code,
+      live: false,
+      lastActivity: meta.last_seen_at
+    });
+  }
+  /** Every surface, optionally one session's, as the wire reports it. */
+  list(sessionId2) {
+    return this.registry.list(sessionId2).map((entry) => this.listing(entry));
+  }
+  listing(entry) {
+    const record = entry.record;
+    return {
+      surface: record.surface,
+      session_id: record.sessionId,
+      origin: record.origin,
+      command: record.command,
+      argv_tail: record.argvTail,
+      cwd: record.cwd,
+      cols: record.cols,
+      rows: record.rows,
+      running: record.running,
+      exit_code: record.exitCode,
+      last_activity: record.lastActivity,
+      live: record.live,
+      agent_owned: record.origin === "agent"
+    };
+  }
+  /** `console_status`. */
+  status(surface) {
+    const entry = this.registry.require(surface);
+    const runtime = entry.runtime;
+    const grid = runtime?.emulator.grid;
+    return {
+      running: entry.record.running,
+      exit_code: entry.record.exitCode,
+      // The retention layer's counter, bumped once per `process_exited` (§7.3,
+      // §10.2). Read from the host's live view of it: the sidecar is what makes
+      // it survive a relaunch, and this is what the running process reports.
+      exit_epoch: this.exitEpoch.get(surface) ?? 0,
+      cols: entry.record.cols,
+      rows: entry.record.rows,
+      live: entry.record.live,
+      truncated: runtime?.log.truncated ?? false,
+      modes: grid?.modes ?? null,
+      cursor: grid?.cursor ?? null,
+      last_activity: entry.record.lastActivity,
+      retain: entry.record.retain,
+      secure: entry.record.secure,
+      // §6.6 asks `console_status` to report "the marker it set and the glyph
+      // decision, so the behaviour is observable rather than inferred". The
+      // marker is this process's own (§6.6's env table, set in
+      // `surfaceEnvironment`); the glyph DECISION is the Python side's predicate
+      // (`is_local_operator_console` → `_nerd_capable_terminal`, §6.6), which
+      // runs in the session that reads this record rather than here, so it is
+      // reported by PR C's side and named there.
+      env_marker: { name: SURFACE_ENV_MARKER, value: surface }
+    };
+  }
+  /**
+   * `console_read`: text from the record, with no view present (R7).
+   *
+   * `whenIdle` first, because the pinned emulator parses asynchronously: a read
+   * answered from a grid one chunk behind is exactly the staleness an agent-driven
+   * read cannot detect (see `emulator.ts`).
+   */
+  async read(surface, mode, window) {
+    const entry = this.registry.require(surface);
+    const runtime = this.requireRuntime(entry);
+    this.refuseWhenSecure(entry);
+    await runtime.emulator.whenIdle();
+    const grid = runtime.emulator.grid;
+    return {
+      text: runtime.emulator.text(mode, window),
+      cols: grid.cols,
+      rows: grid.rows,
+      cursor: grid.cursor,
+      truncated: runtime.log.truncated,
+      live: entry.record.live,
+      mode
+    };
+  }
+  /**
+   * `console_screenshot`: the app's own window, cropped to the pane's reported
+   * rect, photographed with `capturePage` (design 13.2's first row).
+   *
+   * WHAT THIS DOES NOT DO, and it is the design's own first cut item (§17.3): the
+   * offscreen capture view — a hidden renderer replaying the record — is PR B's
+   * (§17.1), so a surface with no displayed pane is refused with
+   * `capture_unavailable` rather than answered with a frame that would not be of
+   * that surface. The `rendered` field is kept so the gap is visible instead of
+   * implied.
+   *
+   * The assert-and-retry is the spike's measured trap and not a hopeful
+   * `setTimeout`: on a hidden window the FIRST `capturePage` came back blank
+   * (9,866 B against 27,869 B for the settled frame), and a headless rig — which
+   * is what every capture in this repo runs in — is exactly that case.
+   */
+  async screenshot(surface) {
+    const entry = this.registry.require(surface);
+    const runtime = this.requireRuntime(entry);
+    this.refuseWhenSecure(entry);
+    const report = runtime.rect;
+    if (this.displayed !== surface || !report || !report.visible) {
+      throw new ConsoleError(
+        "capture_unavailable",
+        "no pane is displaying this surface, and this app version cannot reconstruct a frame offscreen",
+        { rendered: null }
+      );
+    }
+    const window = this.options.window();
+    if (!window || window.isDestroyed()) {
+      throw new ConsoleError(
+        "capture_unavailable",
+        "this app's window is not available to photograph",
+        { rendered: null }
+      );
+    }
+    const rect = cropToWindow(report.contentRect, window.getContentBounds());
+    const png = await this.captureWithRetry(window, rect);
+    const grid = runtime.emulator.grid;
+    return {
+      image_base64: png.toString("base64"),
+      cols: grid.cols,
+      rows: grid.rows,
+      // Named, not implied (13.2): this frame is a photograph of the app's own
+      // window, so it is what a person is looking at rather than a
+      // reconstruction of the record.
+      rendered: "displayed",
+      theme: runtime.theme,
+      live: entry.record.live
+    };
+  }
+  async captureWithRetry(window, rect) {
+    const first = framePng(await window.webContents.capturePage(rect));
+    if (first.length >= MIN_FRAME_BYTES) return first;
+    await delay(FRAME_RETRY_DELAY_MS);
+    return framePng(await window.webContents.capturePage(rect));
+  }
+  /**
+   * `console_input`: bytes into the pty.
+   *
+   * `paste` wraps the payload in the bracketed-paste guards **only when the
+   * record's LIVE mode says so** (§10.5), which is why this is a main-side
+   * decision: the mode is read at the moment of the call, from the record.
+   */
+  async input(surface, payload) {
+    const entry = this.registry.require(surface);
+    const runtime = this.requireRuntime(entry);
+    this.requireRunning(entry);
+    const raw = payload.bytes ?? ENCODER.encode(payload.text ?? "");
+    if (raw.length > MAX_INPUT_BYTES) {
+      throw new ConsoleError(
+        "input_queue_full",
+        `that payload is ${raw.length} bytes and this surface accepts ${MAX_INPUT_BYTES} at a time`,
+        { accepted: 0, limit: MAX_INPUT_BYTES }
+      );
+    }
+    const bracketed = payload.paste === true && runtime.emulator.grid.modes.bracketedPaste;
+    const bytes = bracketed ? wrapBracketedPaste(raw) : raw;
+    this.writeToPty(entry, runtime, bytes);
+    return { accepted: true, bytes: bytes.length };
+  }
+  /** `console_keys`: named keys through the one encoder (§10.5). */
+  async keys(surface, names) {
+    const entry = this.registry.require(surface);
+    const runtime = this.requireRuntime(entry);
+    this.requireRunning(entry);
+    await runtime.emulator.whenIdle();
+    const modes = runtime.emulator.grid.modes;
+    const encoded = names.map(
+      (name) => encodeNamedKey(name, {
+        applicationCursorKeys: modes.applicationCursorKeys
+      })
+    );
+    const unknown = names.find((_name, index) => encoded[index] === null);
+    if (unknown !== void 0) {
+      throw new ConsoleError(
+        "unknown_key",
+        `unknown key ${JSON.stringify(unknown)}; accepted: ${NAMED_KEYS.join(", ")}`,
+        { accepted: [...NAMED_KEYS], key: unknown }
+      );
+    }
+    const sequences = [];
+    for (const bytes of encoded) {
+      if (!bytes) continue;
+      this.writeToPty(entry, runtime, bytes);
+      sequences.push(Buffer.from(bytes).toString("latin1"));
+    }
+    return { accepted: true, encoded: sequences };
+  }
+  /**
+   * `console_resize`: the explicit writer, and the only one besides a displayed
+   * pane's rect (§8.4).
+   */
+  resize(surface, cols, rows) {
+    const entry = this.registry.require(surface);
+    if (entry.record.sizing === "fixed") {
+      throw new ConsoleError(
+        "invalid_grid",
+        "this surface was created with a fixed grid; create another one to resize",
+        // §10.6 reads `reason: "fixed"` here and no clamp: there is no clamp
+        // to carry for a surface that cannot be resized at all.
+        { reason: "fixed" }
+      );
+    }
+    this.applyGrid(entry, cols, rows);
+    return { cols: entry.record.cols, rows: entry.record.rows };
+  }
+  /** The pane's report: measurement in, grid decision out (§8.2). */
+  setContentRect(surface, report) {
+    const entry = this.registry.require(surface);
+    const runtime = this.requireRuntime(entry);
+    runtime.rect = report;
+    runtime.theme = report.theme ?? null;
+    if (!report.visible) return;
+    if (this.displayed !== surface) return;
+    if (entry.record.sizing === "fixed") return;
+    if (!(report.cellWidth > 0) || !(report.cellHeight > 0)) return;
+    const cols = Math.floor(report.contentRect.width / report.cellWidth);
+    const rows = Math.floor(report.contentRect.height / report.cellHeight);
+    if (!Number.isFinite(cols) || !Number.isFinite(rows)) return;
+    this.applyGrid(entry, cols, rows);
+  }
+  /** The pane unmounted or switched surface: forget the rect, and send no resize
+   * and no signal (§6.4, §8.3). */
+  forgetContentRect(surface) {
+    const entry = this.registry.require(surface);
+    if (entry.runtime) entry.runtime.rect = null;
+  }
+  /** `console_secure`: the explicit "do not capture this" switch (§11.4.4). */
+  setSecure(surface, on) {
+    const entry = this.registry.require(surface);
+    this.registry.update(surface, { secure: on });
+    if (on && entry.runtime) {
+      this.options.log(
+        `[console] secure input on for ${redactSurface(surface)}: new bytes are not retained until it is off`
+      );
+    }
+    this.flush(surface);
+    this.options.onChanged?.();
+    return { secure: on };
+  }
+  /**
+   * `console_close`. `kill` signals; without it the surface is only forgotten,
+   * which is what closing a surface whose process already exited means.
+   *
+   * `retain` overrides the record's own default in both directions: a user may
+   * close a surface and keep its history, an agent may close one and drop it.
+   */
+  async close(surface, options = {}) {
+    const entry = this.registry.require(surface);
+    const runtime = entry.runtime;
+    if (options.retain !== void 0) {
+      this.registry.update(surface, { retain: options.retain });
+    }
+    let exitCode = entry.record.exitCode;
+    if (runtime && entry.record.running) {
+      if (options.kill === false) {
+        throw new ConsoleError(
+          "busy",
+          `${redactSurface(surface)} is still running; close it with kill: true, or wait for its process to exit`,
+          { running: true }
+        );
+      }
+      exitCode = await this.terminate(entry) ?? exitCode;
+    }
+    if (!entry.record.retain) {
+      this.options.history?.remove(entry.record.sessionId, surface);
+    } else {
+      this.flush(surface);
+    }
+    this.drop(surface);
+    this.options.log(
+      `[console] surface ${redactSurface(surface)} closed${exitCode === null ? "" : ` with exit ${exitCode}`}${entry.record.retain ? " (history retained)" : ""}`
+    );
+    return exitCode === null ? { closed: true } : { closed: true, exit_code: exitCode };
+  }
+  /**
+   * Signal a surface and wait for its exit, with the design's bounded grace and a
+   * SIGKILL after it (§6.7, the session-deleted row).
+   *
+   * WHY IT WAITS AT ALL: an exit code is the whole evidence that a close did
+   * something, and a close that returned before the process was gone would report
+   * "closed" while the program was still writing into a pty whose surface had
+   * already been dropped. The bound matters for the same reason — a process that
+   * ignores SIGTERM must not hold the RPC call open, so it is escalated rather
+   * than waited on.
+   */
+  async terminate(entry) {
+    const pty = entry.runtime?.pty ?? null;
+    if (!pty) return null;
+    const exit = new Promise((resolve) => {
+      entry.runtime?.exitWaiters.push(resolve);
+    });
+    pty.kill();
+    const code = await Promise.race([
+      exit,
+      delay(CLOSE_GRACE_MS).then(() => null)
+    ]);
+    if (code === null) pty.kill("SIGKILL");
+    return code;
+  }
+  /** Subscribe a pane to one surface's stream, replaying from `fromByte` (§10.3).
+   *
+   * Returns the bytes the subscriber must replay first, and the offset to resume
+   * streaming from, so the two-step is one call rather than a race between a read
+   * and a subscribe. */
+  subscribe(surface, fromByte, subscriber) {
+    const entry = this.registry.require(surface);
+    const runtime = this.requireRuntime(entry);
+    const replay = runtime.log.read(fromByte);
+    runtime.subscribers.add(subscriber);
+    return replay;
+  }
+  /** Stop delivering to one subscriber. Idempotent. */
+  unsubscribe(surface, subscriber) {
+    this.registry.find(surface)?.runtime?.subscribers.delete(subscriber);
+  }
+  /** Drop every subscriber of one surface: the pane unmounted or switched away.
+   * `find`, because a pane can unsubscribe while the surface is being closed. */
+  unsubscribeAll(surface) {
+    this.registry.find(surface)?.runtime?.subscribers.clear();
+  }
+  /**
+   * Which surface a pane is displaying, or null for none (§10.2's pane ops).
+   *
+   * This is a FACT the app reports, not a lever: it never resizes a surface, and
+   * the pane's own measurements arrive separately. What it buys is the honest
+   * `rendered: "displayed"` value on a capture and the answer to "is anybody
+   * looking at this surface", which is the blip's clearing rule (§12.2).
+   */
+  setDisplayed(surface) {
+    if (surface !== null) this.registry.require(surface);
+    this.displayed = surface;
+    if (surface === null) {
+      for (const entry of this.registry.list()) {
+        if (entry.runtime) entry.runtime.rect = null;
+      }
+    }
+    this.options.onChanged?.();
+  }
+  /** The surface a pane is displaying, or null. */
+  get displayedSurface() {
+    return this.displayed;
+  }
+  displayed = null;
+  /** The renderer-facing state: what a pane, a blip or a Settings surface reads. */
+  state(sessionId2) {
+    const counts = this.counts();
+    return {
+      available: true,
+      total: counts.total,
+      agent: counts.agent,
+      displayed_surface: this.displayed,
+      surfaces: this.registry.list(sessionId2).map((entry) => ({
+        ...this.listing(entry),
+        secure: entry.record.secure,
+        retain: entry.record.retain,
+        sizing: entry.record.sizing,
+        displayed: entry.record.surface === this.displayed,
+        last_mark: entry.runtime?.lastMark ?? null
+      }))
+    };
+  }
+  /** Producer of the surface's own output: the pty's data, in order. This is the
+   * ONE place bytes enter the surface, which is why the log, the record, the
+   * scanner and the subscribers cannot disagree about the stream. */
+  consume(surface, data) {
+    const entry = this.registry.find(surface);
+    const runtime = entry?.runtime;
+    if (!entry || !runtime) return;
+    const bytes = Buffer.from(data, "utf8");
+    runtime.emulator.write(new Uint8Array(bytes));
+    if (!entry.record.secure) runtime.log.append(new Uint8Array(bytes));
+    for (const mark of runtime.scanner.feed(new Uint8Array(bytes))) {
+      runtime.lastMark = mark;
+      this.options.onMark?.(surface, mark);
+    }
+    this.registry.update(surface, { lastActivity: this.now() });
+    if (entry.record.retain) this.schedulePersist(entry, runtime);
+    this.broadcast(entry, runtime, new Uint8Array(bytes));
+  }
+  /** Coalesce output for one event-loop tick, then deliver one frame per
+   * subscriber (§10.3: batching is a delivery concern, never the log's). */
+  broadcast(entry, runtime, bytes) {
+    if (runtime.subscribers.size === 0) return;
+    runtime.pending.push(bytes);
+    if (runtime.pendingTimer) return;
+    runtime.pendingTimer = setTimeout(() => {
+      runtime.pendingTimer = null;
+      const pending = runtime.pending;
+      runtime.pending = [];
+      if (pending.length === 0) return;
+      const joined = concat(pending);
+      runtime.seq += 1;
+      const frame = {
+        surface: entry.record.surface,
+        seq: runtime.seq,
+        bytes: joined
+      };
+      for (const subscriber of runtime.subscribers) subscriber.output(frame);
+    }, OUTPUT_COALESCE_MS);
+    runtime.pendingTimer.unref?.();
+  }
+  exited(surface, exitCode) {
+    const entry = this.registry.find(surface);
+    if (!entry || !entry.runtime) return;
+    this.registry.update(surface, {
+      running: false,
+      exitCode,
+      lastActivity: this.now()
+    });
+    this.bumpExitEpoch(entry);
+    if (entry.record.retain) this.flush(surface);
+    const runtime = entry.runtime;
+    for (const waiter of runtime.exitWaiters.splice(0)) waiter(exitCode);
+    if (!runtime.exitDelivered) {
+      runtime.exitDelivered = true;
+      for (const subscriber of runtime.subscribers) {
+        subscriber.exit({ surface, exitCode });
+      }
+    }
+    this.options.log(
+      `[console] surface ${redactSurface(surface)} exited ${exitCode}`
+    );
+    this.options.onChanged?.();
+  }
+  /** Apply a grid change: clamp, compare, and only then touch the record and the
+   * pty — so one clamp-crossing is one `TIOCSWINSZ` and one `SIGWINCH` (§8.2). */
+  applyGrid(entry, cols, rows) {
+    const grid = clampGrid(cols, rows);
+    if (grid.cols === entry.record.cols && grid.rows === entry.record.rows)
+      return;
+    this.registry.update(entry.record.surface, {
+      cols: grid.cols,
+      rows: grid.rows
+    });
+    entry.runtime?.emulator.resize(grid.cols, grid.rows);
+    if (entry.record.running) entry.runtime?.pty?.resize(grid.cols, grid.rows);
+    this.options.log(
+      `[console] surface ${redactSurface(entry.record.surface)} resized ${grid.cols}x${grid.rows}`
+    );
+    this.options.onChanged?.();
+  }
+  writeToPty(entry, runtime, bytes) {
+    runtime.pty?.write(bytes);
+    this.registry.update(entry.record.surface, { lastActivity: this.now() });
+  }
+  requireRuntime(entry) {
+    if (!entry.runtime) {
+      throw new ConsoleError(
+        "console_unavailable",
+        `${redactSurface(entry.record.surface)} has no runtime in this app run`,
+        { reason: "no_runtime" }
+      );
+    }
+    return entry.runtime;
+  }
+  requireRunning(entry) {
+    if (!entry.record.running) {
+      throw new ConsoleError(
+        "process_exited",
+        `${redactSurface(entry.record.surface)} has exited${entry.record.exitCode === null ? "" : ` with code ${entry.record.exitCode}`}; its output is still readable`,
+        // `retain`, not `live`, is §10.6's key for this code: the consumer's
+        // sentence says whether the log is retained, and a caller looking for
+        // `retain` would find nothing if this carried `live` instead.
+        { exit_code: entry.record.exitCode, retain: entry.record.retain }
+      );
+    }
+  }
+  refuseWhenSecure(entry) {
+    if (entry.record.secure) {
+      throw new ConsoleError(
+        "secure_input_active",
+        `${redactSurface(entry.record.surface)} is in secure input; reads and captures are refused until it is turned off`,
+        { secure: true }
+      );
+    }
+  }
+  /**
+   * Write one retained surface's pending bytes and, when it moved, its sidecar.
+   *
+   * THE BYTES ARE THE SPINE and the sidecar is the exception. Every call appends
+   * whatever the log has that disk does not — one `appendFileSync` for the whole
+   * pending window rather than one per chunk — and the sidecar is rewritten only
+   * when one of its own fields actually changed. It used to be rewritten on every
+   * chunk, which is a staged write, a rename and two `chmod`s per pty read for a
+   * document whose fields move about once a second; the signature below is what
+   * keeps a durable `last_seen_at` without paying that.
+   */
+  persist(entry, runtime) {
+    const history = this.options.history;
+    if (!history) return;
+    const surface = entry.record.surface;
+    const record = entry.record;
+    const meta = {
+      surface,
+      session_id: record.sessionId,
+      origin: record.origin,
+      command: record.command,
+      argv: record.argvTail ? record.argvTail.split(" ") : [],
+      cwd: record.cwd,
+      cols: record.cols,
+      rows: record.rows,
+      // The creation time is the record's own first `last_activity`; a sidecar is
+      // rewritten rather than appended, so it carries what is true now. A surface
+      // restored from history seeded this from the sidecar it came from, so a
+      // relaunch cannot rewrite its own creation time (§7.3).
+      created_at: this.createdAt.get(surface) ?? this.now(),
+      last_seen_at: record.lastActivity,
+      exit_code: record.exitCode,
+      truncated: runtime.log.truncated,
+      exit_epoch: this.exitEpoch.get(surface) ?? 0
+    };
+    if (!this.createdAt.has(surface))
+      this.createdAt.set(surface, meta.created_at);
+    if (!this.persistedBytes.has(surface)) this.persistedBytes.set(surface, 0);
+    const already = this.persistedBytes.get(surface) ?? 0;
+    const end = runtime.log.endOffset;
+    if (end > already) {
+      const slice = runtime.log.read(already);
+      history.append(record.sessionId, surface, slice.bytes, meta);
+      this.persistedBytes.set(surface, slice.to);
+    }
+    const signature = metaSignature(meta);
+    if (this.metaSignatures.get(surface) === signature) return;
+    history.writeMeta(meta);
+    this.metaSignatures.set(surface, signature);
+  }
+  /**
+   * Flush a surface's pending bytes and sidecar NOW.
+   *
+   * Called at every point the coalescing must not be observable: `close`,
+   * `dispose`, a process exit, a secure toggle, and the create that writes the
+   * first sidecar. Also the seam a test drives the durable state through without
+   * waiting a quarter of a second.
+   */
+  flush(surface) {
+    const entry = this.registry.find(surface);
+    const runtime = entry?.runtime;
+    if (!entry || !runtime) return;
+    if (runtime.persistTimer) {
+      clearTimeout(runtime.persistTimer);
+      runtime.persistTimer = null;
+    }
+    if (!entry.record.retain) return;
+    this.persist(entry, runtime);
+  }
+  /**
+   * Hand the newest bytes to the bounded flush (§7.2's cap, §18.3's starvation).
+   *
+   * A threshold crossing flushes immediately and a trickle waits for the timer,
+   * which is the two cases this has to get right: a flood must not hold megabytes
+   * in memory, and a single prompt line must be on disk without waiting for the
+   * next byte to arrive. Neither path writes per chunk, which is the defect this
+   * exists to close.
+   */
+  schedulePersist(entry, runtime) {
+    const surface = entry.record.surface;
+    const pending = runtime.log.endOffset - (this.persistedBytes.get(surface) ?? 0);
+    if (pending >= PERSIST_FLUSH_BYTES) {
+      this.flush(surface);
+      return;
+    }
+    if (runtime.persistTimer) return;
+    runtime.persistTimer = setTimeout(() => {
+      runtime.persistTimer = null;
+      this.flush(surface);
+    }, PERSIST_FLUSH_MS);
+  }
+  /**
+   * The surface's next exit generation (§7.3).
+   *
+   * The arithmetic lives in the retention layer (`ConsoleHistory.nextExitEpoch`)
+   * because the sidecar is the only place a generation SURVIVES a relaunch: a
+   * surface replayed under its own handle and run again must report generation 2
+   * on its second exit, and a counter kept here alone would start at 1 again. This
+   * method is the in-process half — the value the running host reports through
+   * `console_status` — and the max() in the history is what keeps the two from
+   * disagreeing when a write was lost.
+   */
+  bumpExitEpoch(entry) {
+    const surface = entry.record.surface;
+    const live = this.exitEpoch.get(surface) ?? 0;
+    const next = this.options.history?.nextExitEpoch(
+      entry.record.sessionId,
+      surface,
+      live
+    ) ?? live + 1;
+    this.exitEpoch.set(surface, next);
+    return next;
+  }
+  /** Forget a surface: its runtime, its record and its subscribers. The ONE
+   * removal path, so the registry and the runtime map cannot drift. */
+  drop(surface) {
+    const entry = this.registry.require(surface);
+    const runtime = entry.runtime;
+    if (runtime) {
+      if (runtime.pendingTimer) clearTimeout(runtime.pendingTimer);
+      if (runtime.persistTimer) clearTimeout(runtime.persistTimer);
+      runtime.subscribers.clear();
+      runtime.emulator.dispose();
+    }
+    this.registry.remove(surface);
+    this.createdAt.delete(surface);
+    this.persistedBytes.delete(surface);
+    this.metaSignatures.delete(surface);
+    this.exitEpoch.delete(surface);
+    this.options.onChanged?.();
+  }
+  /** Stop everything: every pty, every record, every subscriber. */
+  dispose() {
+    for (const entry of this.registry.clear()) {
+      const runtime = entry.runtime;
+      if (!runtime) continue;
+      if (runtime.pendingTimer) clearTimeout(runtime.pendingTimer);
+      if (runtime.persistTimer) clearTimeout(runtime.persistTimer);
+      runtime.subscribers.clear();
+      if (entry.record.retain) this.persist(entry, runtime);
+      if (entry.record.running) runtime.pty?.kill();
+      runtime.emulator.dispose();
+    }
+    this.createdAt.clear();
+    this.persistedBytes.clear();
+    this.metaSignatures.clear();
+    this.exitEpoch.clear();
+  }
+  /** Creation times, kept here rather than on the wire record: nothing outside
+   * this class reads them, and the record is what a listing serialises. */
+  createdAt = /* @__PURE__ */ new Map();
+  /** How many bytes of each surface's log have been written to disk, so an append
+   * never re-writes what is already there. */
+  persistedBytes = /* @__PURE__ */ new Map();
+  /** The last sidecar content written per surface, so an unchanged document is
+   * not rewritten on every flush. */
+  metaSignatures = /* @__PURE__ */ new Map();
+  /** Each surface's exit generation, seeded from the sidecar on restore (§7.3). */
+  exitEpoch = /* @__PURE__ */ new Map();
+}
+function metaSignature(meta) {
+  return [
+    meta.exit_code,
+    meta.truncated,
+    meta.cols,
+    meta.rows,
+    meta.exit_epoch,
+    Math.floor(meta.last_seen_at)
+  ].join("|");
+}
+function clampGrid(cols, rows) {
+  return {
+    cols: clamp(
+      Number.isFinite(cols) ? Math.floor(cols) : DEFAULT_COLS,
+      MIN_COLS,
+      MAX_COLS
+    ),
+    rows: clamp(
+      Number.isFinite(rows) ? Math.floor(rows) : DEFAULT_ROWS,
+      MIN_ROWS,
+      MAX_ROWS
+    )
+  };
+}
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+function surfaceEnvironment(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.base)) {
+    if (value === void 0) continue;
+    if (STRIPPED_ENV_PREFIXES.some((prefix) => key.startsWith(prefix)))
+      continue;
+    env[key] = value;
+  }
+  env.TERM = SURFACE_TERM;
+  env.COLORTERM = SURFACE_COLORTERM;
+  env[SURFACE_ENV_MARKER] = input.surface;
+  env[SESSION_ENV_MARKER] = input.sessionId;
+  for (const [key, value] of Object.entries(input.overrides ?? {})) {
+    env[key] = value;
+  }
+  return env;
+}
+function defaultShell(env) {
+  const shell = env.SHELL?.trim();
+  if (shell && path$1.isAbsolute(shell)) return shell;
+  return "/bin/zsh";
+}
+function resolveCwd(cwd) {
+  const wanted = cwd?.trim();
+  if (wanted && path$1.isAbsolute(wanted)) return wanted;
+  return os.homedir();
+}
+function wrapBracketedPaste(bytes) {
+  const start = new TextEncoder().encode("\x1B[200~");
+  const end = new TextEncoder().encode("\x1B[201~");
+  const out = new Uint8Array(start.length + bytes.length + end.length);
+  out.set(start, 0);
+  out.set(bytes, start.length);
+  out.set(end, start.length + bytes.length);
+  return out;
+}
+function cropToWindow(rect, bounds) {
+  const x = Math.max(Math.floor(rect.x), 0);
+  const y = Math.max(Math.floor(rect.y), 0);
+  return {
+    x,
+    y,
+    width: Math.max(Math.min(Math.floor(rect.width), bounds.width - x), 1),
+    height: Math.max(Math.min(Math.floor(rect.height), bounds.height - y), 1)
+  };
+}
+function framePng(image2) {
+  return image2.isEmpty() ? Buffer.alloc(0) : image2.toPNG();
+}
+const ENCODER = new TextEncoder();
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function concat(chunks) {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
+const METHODS = [
+  "console_list",
+  "console_create",
+  "console_status",
+  "console_read",
+  "console_screenshot",
+  "console_input",
+  "console_keys",
+  "console_resize",
+  "console_secure",
+  "console_close"
+];
+function isConsoleDispatchMethod(method) {
+  return METHODS.includes(method);
+}
+async function dispatchConsole(host, method, params) {
+  switch (method) {
+    case "console_list": {
+      const sessionId2 = optionalString$1(params.session_id, "session_id");
+      const surfaces = host.list(sessionId2);
+      return { surfaces, count: surfaces.length };
+    }
+    case "console_create": {
+      const cols = optionalGrid(params.cols, "cols", DEFAULT_COLS);
+      const rows = optionalGrid(params.rows, "rows", DEFAULT_ROWS);
+      const clamped = clampGrid(cols, rows);
+      if (clamped.cols !== cols || clamped.rows !== rows) {
+        throw new ConsoleError(
+          "invalid_grid",
+          `${cols}x${rows} is outside the supported grid; the clamp would be ${clamped.cols}x${clamped.rows}`,
+          // §10.6's key for this code is the nested `clamp`, which is what a
+          // consumer's sentence names — the requested grid is already in the
+          // message above it.
+          { clamp: clamped }
+        );
+      }
+      return {
+        ...host.create({
+          sessionId: requiredString(params.session_id, "session_id"),
+          origin: "agent",
+          cwd: optionalString$1(params.cwd, "cwd"),
+          command: optionalString$1(params.command, "command"),
+          args: optionalStringList(params.args, "args"),
+          input: optionalString$1(params.input, "input"),
+          env: optionalEnv(params.env),
+          cols,
+          rows,
+          reveal: optionalReveal(params.reveal),
+          retain: optionalBoolean(params.retain, "retain"),
+          sizing: optionalSizing(params.sizing)
+        })
+      };
+    }
+    case "console_status": {
+      return host.status(requiredSurface(params.surface));
+    }
+    case "console_read": {
+      return host.read(
+        requiredSurface(params.surface),
+        requiredMode(params.mode),
+        {
+          start: optionalCount(params.start, "start"),
+          count: optionalCount(params.count, "count")
+        }
+      );
+    }
+    case "console_screenshot": {
+      const format = optionalString$1(params.format, "format");
+      if (format !== void 0 && format !== "png") {
+        throw new ConsoleError(
+          "unsupported_method",
+          `this app version captures png only, not ${JSON.stringify(format)}`,
+          { format }
+        );
+      }
+      return host.screenshot(requiredSurface(params.surface));
+    }
+    case "console_input": {
+      const surface = requiredSurface(params.surface);
+      const text = optionalString$1(params.text, "text");
+      const bytes = optionalBytes(params.bytes);
+      if (text === void 0 && bytes === void 0) {
+        throw new ConsoleError(
+          "internal",
+          "console_input needs text or bytes; a secret_ref is resolved by the tool before the call",
+          { surface }
+        );
+      }
+      return host.input(surface, {
+        text,
+        bytes,
+        paste: optionalBoolean(params.paste, "paste")
+      });
+    }
+    case "console_keys": {
+      const surface = requiredSurface(params.surface);
+      const keys = params.keys;
+      if (!Array.isArray(keys) || keys.length === 0 || keys.some((key) => typeof key !== "string")) {
+        throw new ConsoleError(
+          "unknown_key",
+          "console_keys needs a non-empty list of key names",
+          {}
+        );
+      }
+      return host.keys(surface, keys);
+    }
+    case "console_resize": {
+      const surface = requiredSurface(params.surface);
+      const cols = requiredInteger(params.cols, "cols");
+      const rows = requiredInteger(params.rows, "rows");
+      const clamped = clampGrid(cols, rows);
+      if (clamped.cols !== cols || clamped.rows !== rows) {
+        throw new ConsoleError(
+          "invalid_grid",
+          `${cols}x${rows} is outside the supported grid; the clamp would be ${clamped.cols}x${clamped.rows}`,
+          { clamp: clamped }
+        );
+      }
+      return host.resize(surface, cols, rows);
+    }
+    case "console_secure": {
+      const surface = requiredSurface(params.surface);
+      const on = params.on;
+      if (typeof on !== "boolean") {
+        throw new ConsoleError(
+          "internal",
+          "console_secure needs `on` to be true or false",
+          { surface }
+        );
+      }
+      return host.setSecure(surface, on);
+    }
+    case "console_close": {
+      const surface = requiredSurface(params.surface);
+      return host.close(surface, {
+        kill: optionalBoolean(params.kill, "kill"),
+        retain: optionalBoolean(params.retain, "retain")
+      });
+    }
+  }
+}
+function requiredSurface(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new ConsoleError(
+      "surface_unavailable",
+      "a console command needs a surface handle",
+      { param: "surface" }
+    );
+  }
+  return value;
+}
+function requiredString(value, name) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new ConsoleError("internal", `${name} must be a non-empty string`, {
+      param: name
+    });
+  }
+  return value;
+}
+function optionalString$1(value, name) {
+  if (value === void 0 || value === null) return void 0;
+  return requiredString(value, name);
+}
+function optionalStringList(value, name) {
+  if (value === void 0 || value === null) return void 0;
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new ConsoleError("internal", `${name} must be a list of strings`, {
+      param: name
+    });
+  }
+  return value;
+}
+function optionalBoolean(value, name) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "boolean") {
+    throw new ConsoleError("internal", `${name} must be true or false`, {
+      param: name
+    });
+  }
+  return value;
+}
+function optionalGrid(value, name, fallback) {
+  if (value === void 0 || value === null) {
+    return fallback;
+  }
+  return requiredInteger(value, name);
+}
+function requiredInteger(value, name) {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new ConsoleError("invalid_grid", `${name} must be a whole number`, {
+      param: name
+    });
+  }
+  return value;
+}
+function optionalCount(value, name) {
+  if (value === void 0 || value === null) return void 0;
+  const parsed = requiredInteger(value, name);
+  if (parsed < 0) {
+    throw new ConsoleError("internal", `${name} must not be negative`, {
+      param: name
+    });
+  }
+  return parsed;
+}
+function requiredMode(value) {
+  if (value === "viewport" || value === "scrollback") return value;
+  throw new ConsoleError(
+    "internal",
+    'mode must be "viewport" or "scrollback"',
+    {
+      param: "mode"
+    }
+  );
+}
+function optionalReveal(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (value === "none" || value === "session" || value === "open") return value;
+  throw new ConsoleError(
+    "internal",
+    'reveal must be "none", "session" or "open"',
+    {
+      param: "reveal"
+    }
+  );
+}
+function optionalSizing(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (value === "auto" || value === "fixed") return value;
+  throw new ConsoleError("internal", 'sizing must be "auto" or "fixed"', {
+    param: "sizing"
+  });
+}
+function optionalEnv(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ConsoleError("internal", "env must be an object of strings", {
+      param: "env"
+    });
+  }
+  const out = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (typeof raw !== "string") {
+      throw new ConsoleError("internal", `env.${key} must be a string`, {
+        param: "env",
+        key
+      });
+    }
+    out[key] = raw;
+  }
+  return out;
+}
+function optionalBytes(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (!Array.isArray(value) || value.some(
+    (byte) => typeof byte !== "number" || !Number.isInteger(byte) || byte < 0 || byte > 255
+  )) {
+    throw new ConsoleError(
+      "internal",
+      "bytes must be a list of integers between 0 and 255",
+      { param: "bytes" }
+    );
+  }
+  return Uint8Array.from(value);
+}
+path$1.join("run", "ui-console", "history");
+const HISTORY_DIR_MODE = 448;
+const HISTORY_FILE_MODE = 384;
+const DEFAULT_HISTORY_DAYS = 30;
+const HISTORY_ROTATE_BYTES = RETAIN_BYTES * 2;
+function fileStem(surface) {
+  return surface.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+function sessionDir(root, sessionId2) {
+  return path$1.join(root, fileStem(sessionId2));
+}
+function logPath(root, sessionId2, surface) {
+  return path$1.join(sessionDir(root, sessionId2), `${fileStem(surface)}.log`);
+}
+function sidecarPath(root, sessionId2, surface) {
+  return path$1.join(sessionDir(root, sessionId2), `${fileStem(surface)}.json`);
+}
+class ConsoleHistory {
+  constructor(root, options = {}) {
+    this.root = root;
+    this.now = options.now ?? (() => Date.now() / 1e3);
+  }
+  now;
+  /** Write the sidecar. Staged and renamed, so a reader sees a whole document
+   * or the previous one — never half a JSON file that would read as absent. */
+  writeMeta(meta) {
+    const path2 = sidecarPath(this.root, meta.session_id, meta.surface);
+    fs.mkdirSync(path$1.dirname(path2), { recursive: true, mode: HISTORY_DIR_MODE });
+    const staged = `${path2}.${process.pid}.tmp`;
+    fs.writeFileSync(staged, `${JSON.stringify(meta, null, 2)}
+`, {
+      mode: HISTORY_FILE_MODE
+    });
+    fs.renameSync(staged, path2);
+    enforceModes(path2);
+  }
+  /**
+   * Append bytes, rotating when the file passes the rotate bound.
+   *
+   * Rotation is what keeps a long-lived surface's history bounded: appending
+   * forever is the one shape that turns "retained history" into an unbounded
+   * directory. `truncated` is the caller's to carry — this method reports whether
+   * it rotated, and the host sets the flag on the sidecar, because the sidecar is
+   * the only place the flag is durable.
+   */
+  append(sessionId2, surface, bytes, meta) {
+    const path2 = logPath(this.root, sessionId2, surface);
+    try {
+      fs.mkdirSync(path$1.dirname(path2), { recursive: true, mode: HISTORY_DIR_MODE });
+      fs.appendFileSync(path2, bytes, { mode: HISTORY_FILE_MODE });
+      enforceModes(path2);
+      let size = 0;
+      try {
+        size = fs.statSync(path2).size;
+      } catch {
+        size = 0;
+      }
+      if (size <= HISTORY_ROTATE_BYTES) return { rotated: false };
+      const all = fs.readFileSync(path2);
+      const kept = all.subarray(Math.max(all.length - RETAIN_BYTES, 0));
+      const staged = `${path2}.${process.pid}.tmp`;
+      fs.writeFileSync(staged, kept, { mode: HISTORY_FILE_MODE });
+      fs.renameSync(staged, path2);
+      enforceModes(path2);
+      meta.truncated = true;
+      meta.last_seen_at = this.now();
+      this.writeMeta(meta);
+      return { rotated: true };
+    } catch {
+      return { rotated: false };
+    }
+  }
+  /** Load one surface's history, or null. Never creates anything. */
+  load(sessionId2, surface) {
+    const metaPath = sidecarPath(this.root, sessionId2, surface);
+    if (!fs.existsSync(metaPath)) return null;
+    try {
+      const meta = parseMeta(fs.readFileSync(metaPath, "utf8"));
+      const logFile = logPath(this.root, sessionId2, surface);
+      const bytes = fs.existsSync(logFile) ? fs.readFileSync(logFile) : Buffer.alloc(0);
+      return { meta, bytes: new Uint8Array(bytes) };
+    } catch {
+      return null;
+    }
+  }
+  /** One sidecar, or null. Never creates anything, and never throws. */
+  loadSidecar(sessionId2, surface) {
+    const path2 = sidecarPath(this.root, sessionId2, surface);
+    if (!fs.existsSync(path2)) return null;
+    try {
+      return parseMeta(fs.readFileSync(path2, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Every retained surface, optionally for one session.
+   *
+   * A directory listing rather than an index file: an index is a second source
+   * of truth that a crash between the two writes can desynchronise, and the
+   * number of sessions here is small enough that a readdir is not a cost.
+   */
+  list(sessionId2) {
+    const sessions = sessionId2 === void 0 ? this.sessionDirs() : [fileStem(sessionId2)];
+    const loaded = [];
+    for (const stem of sessions) {
+      const dir = path$1.join(this.root, stem);
+      let files;
+      try {
+        files = fs.readdirSync(dir);
+      } catch {
+        continue;
+      }
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        try {
+          const meta = parseMeta(fs.readFileSync(path$1.join(dir, file), "utf8"));
+          const logFile = path$1.join(dir, `${file.slice(0, -".json".length)}.log`);
+          const bytes = fs.existsSync(logFile) ? fs.readFileSync(logFile) : Buffer.alloc(0);
+          loaded.push({ meta, bytes: new Uint8Array(bytes) });
+        } catch {
+        }
+      }
+    }
+    return loaded;
+  }
+  /**
+   * The exit generation this sidecar currently records, or 0 when nothing has
+   * exited yet (§7.3).
+   *
+   * Read from the FILE rather than from a field the caller carries: the durable
+   * record is the only place a generation can outlive the process, and a caller
+   * that has just restored a surface is holding exactly the meta this reads.
+   */
+  exitEpoch(sessionId2, surface) {
+    const loaded = this.loadSidecar(sessionId2, surface);
+    return loaded?.exit_epoch ?? 0;
+  }
+  /**
+   * The generation the surface's NEXT exit will carry (§7.3).
+   *
+   * `live` is what the running host has seen in this process, and it is combined
+   * with the sidecar rather than replacing it: a write that failed, or a surface
+   * replayed from history and run again, must never move the generation
+   * backwards — two exits sharing one generation is exactly the collision the
+   * counter exists to make impossible (§12.3).
+   */
+  nextExitEpoch(sessionId2, surface, live) {
+    return Math.max(this.exitEpoch(sessionId2, surface), live) + 1;
+  }
+  /** Remove one surface's history, log and sidecar. */
+  remove(sessionId2, surface) {
+    for (const path2 of [
+      logPath(this.root, sessionId2, surface),
+      sidecarPath(this.root, sessionId2, surface)
+    ]) {
+      try {
+        fs.rmSync(path2, { force: true });
+      } catch {
+      }
+    }
+  }
+  /**
+   * Remove a session's whole history, for the session-deleted path (§6.7).
+   *
+   * CALLED BY NOTHING YET, and that is the deferred row rather than dead code:
+   * §6.7's session-deleted row is disclosed as unimplemented (there is no
+   * session-lifecycle signal for main to subscribe to in this PR), so this is the
+   * seam the wiring will call from. It lives here rather than in the caller
+   * because the GC and this method are the only two things that remove a
+   * DIRECTORY, and one implementation of that is the point.
+   */
+  removeSession(sessionId2) {
+    try {
+      fs.rmSync(sessionDir(this.root, sessionId2), {
+        recursive: true,
+        force: true
+      });
+    } catch {
+    }
+  }
+  /**
+   * The GC pass (§7.4): drop session directories whose newest file is older than
+   * the window, and report what it removed rather than doing it silently.
+   */
+  collect(days = DEFAULT_HISTORY_DAYS) {
+    const report = { removedSessions: [], removedSurfaces: 0 };
+    const cutoff = this.now() - days * 24 * 60 * 60;
+    for (const stem of this.sessionDirs()) {
+      const dir = path$1.join(this.root, stem);
+      let newest = 0;
+      let files;
+      try {
+        files = fs.readdirSync(dir);
+      } catch {
+        continue;
+      }
+      for (const file of files) {
+        try {
+          newest = Math.max(newest, fs.statSync(path$1.join(dir, file)).mtimeMs / 1e3);
+        } catch {
+        }
+      }
+      if (newest === 0 || newest >= cutoff) continue;
+      report.removedSurfaces += files.filter(
+        (file) => file.endsWith(".json")
+      ).length;
+      try {
+        fs.rmSync(dir, { recursive: true, force: true });
+        report.removedSessions.push(stem);
+      } catch {
+      }
+    }
+    return report;
+  }
+  sessionDirs() {
+    try {
+      return fs.readdirSync(this.root, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    } catch {
+      return [];
+    }
+  }
+}
+function parseMeta(raw) {
+  const meta = JSON.parse(raw);
+  if (typeof meta.exit_epoch !== "number") meta.exit_epoch = 0;
+  return meta;
+}
+function enforceModes(path2) {
+  try {
+    fs.chmodSync(path$1.dirname(path2), HISTORY_DIR_MODE);
+    fs.chmodSync(path2, HISTORY_FILE_MODE);
+  } catch {
+  }
+}
+const CONSOLE_IPC_CHANNELS = [
+  "console-state",
+  "console-create-surface",
+  "console-open-pane",
+  "console-close-pane",
+  "console-select-surface",
+  "console-input",
+  "console-keys",
+  "console-content-rect",
+  "console-secure-toggle",
+  "console-subscribe",
+  "console-unsubscribe"
+];
+function registerConsoleIpc(options) {
+  function authorize(event) {
+    const owner = options.window();
+    if (!owner || owner.isDestroyed() || event.sender !== owner.webContents || event.senderFrame !== owner.webContents.mainFrame || !trustedDesktopFrame(event.senderFrame.url, options.expectedUrl)) {
+      throw new Error("This window cannot use the console.");
+    }
+    const host = options.host();
+    if (!host) throw new Error("The console is not running.");
+    return host;
+  }
+  electron.ipcMain.handle(
+    "console-state",
+    (event, sessionId2) => authorize(event).state(optionalString(sessionId2, "sessionId"))
+  );
+  electron.ipcMain.handle("console-create-surface", (event, request) => {
+    const host = authorize(event);
+    const input = request && typeof request === "object" ? request : {};
+    const fields = input;
+    const surface = host.create({
+      sessionId: stringOrThrow(fields.sessionId, "sessionId"),
+      origin: "user",
+      cwd: typeof fields.cwd === "string" ? fields.cwd : void 0,
+      command: typeof fields.command === "string" && fields.command.trim() ? fields.command.trim() : void 0,
+      cols: typeof fields.cols === "number" ? fields.cols : void 0,
+      rows: typeof fields.rows === "number" ? fields.rows : void 0,
+      // A user's own surface is born displayed: they asked for it from the pane
+      // they are looking at, and the renderer is the one that opens the pane. No
+      // `reveal` is honoured here because a renderer request cannot need to ask
+      // for a pane it is already in.
+      reveal: "none"
+    });
+    return { ...surface };
+  });
+  electron.ipcMain.handle("console-open-pane", (event, surface) => {
+    const host = authorize(event);
+    host.setDisplayed(stringOrThrow(surface, "surface"));
+    return host.state();
+  });
+  electron.ipcMain.handle("console-close-pane", (event) => {
+    const host = authorize(event);
+    host.setDisplayed(null);
+    return host.state();
+  });
+  electron.ipcMain.handle("console-select-surface", (event, surface) => {
+    const host = authorize(event);
+    host.setDisplayed(stringOrThrow(surface, "surface"));
+    return host.state();
+  });
+  electron.ipcMain.handle(
+    "console-input",
+    async (event, surface, text) => {
+      const host = authorize(event);
+      if (typeof text !== "string") {
+        throw new Error("Console input must be a string.");
+      }
+      return host.input(stringOrThrow(surface, "surface"), { text });
+    }
+  );
+  electron.ipcMain.handle(
+    "console-keys",
+    async (event, surface, keys) => {
+      const host = authorize(event);
+      if (!Array.isArray(keys) || keys.some((key) => typeof key !== "string")) {
+        throw new Error("Console keys must be a list of names.");
+      }
+      return host.keys(stringOrThrow(surface, "surface"), keys);
+    }
+  );
+  electron.ipcMain.handle(
+    "console-content-rect",
+    (event, surface, report) => {
+      const host = authorize(event);
+      host.setContentRect(
+        stringOrThrow(surface, "surface"),
+        contentReportOrThrow(report)
+      );
+      return host.state();
+    }
+  );
+  electron.ipcMain.handle(
+    "console-secure-toggle",
+    (event, surface, on) => {
+      const host = authorize(event);
+      if (typeof on !== "boolean") {
+        throw new Error("The secure toggle takes a boolean.");
+      }
+      return host.setSecure(stringOrThrow(surface, "surface"), on);
+    }
+  );
+  electron.ipcMain.handle(
+    "console-subscribe",
+    (event, surface, fromByte) => {
+      const host = authorize(event);
+      const token = stringOrThrow(surface, "surface");
+      const from = typeof fromByte === "number" && Number.isFinite(fromByte) ? Math.max(Math.trunc(fromByte), 0) : 0;
+      const owner = options.window();
+      const subscriber = {
+        output: (frame) => {
+          const target2 = owner && !owner.isDestroyed() ? owner.webContents : null;
+          target2?.send("console-output", {
+            surface: frame.surface,
+            seq: frame.seq,
+            // Base64 rather than an array of numbers: a frame can carry a
+            // megabyte, and the renderer decodes it once into a Uint8Array.
+            bytes_base64: Buffer.from(frame.bytes).toString("base64")
+          });
+        },
+        exit: (frame) => {
+          const target2 = owner && !owner.isDestroyed() ? owner.webContents : null;
+          target2?.send("console-exit", {
+            surface: frame.surface,
+            exit_code: frame.exitCode
+          });
+        }
+      };
+      const replay = host.subscribe(token, from, subscriber);
+      return {
+        surface: token,
+        replay_base64: Buffer.from(replay.bytes).toString("base64"),
+        from_byte: replay.from,
+        to_byte: replay.to,
+        truncated: replay.truncated
+      };
+    }
+  );
+  electron.ipcMain.handle("console-unsubscribe", (event, surface) => {
+    const host = authorize(event);
+    host.unsubscribeAll(stringOrThrow(surface, "surface"));
+    return { unsubscribed: true };
+  });
+}
+function unregisterConsoleIpc() {
+  for (const channel of CONSOLE_IPC_CHANNELS) electron.ipcMain.removeHandler(channel);
+}
+function stringOrThrow(value, name) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${name} must be a non-empty string.`);
+  }
+  return value;
+}
+function optionalString(value, name) {
+  if (value === void 0 || value === null) return void 0;
+  return stringOrThrow(value, name);
+}
+function contentReportOrThrow(value) {
+  if (!value || typeof value !== "object") {
+    throw new Error("A console content report is required.");
+  }
+  const report = value;
+  const rect = report.contentRect;
+  if (!rect || typeof rect !== "object") {
+    throw new Error("A console content report needs a contentRect.");
+  }
+  const numbers = ["x", "y", "width", "height"].map((key) => {
+    const raw = rect[key];
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+      throw new Error(`contentRect.${key} must be a number.`);
+    }
+    return raw;
+  });
+  if (numbers[2] <= 0 || numbers[3] <= 0) {
+    throw new Error("A console content rect needs a positive size.");
+  }
+  const cellWidth = positiveNumber(report.cellWidth, "cellWidth");
+  const cellHeight = positiveNumber(report.cellHeight, "cellHeight");
+  if (typeof report.visible !== "boolean") {
+    throw new Error("A console content report says whether it is visible.");
+  }
+  const theme = typeof report.theme === "string" || report.theme === null ? report.theme : null;
+  return {
+    contentRect: {
+      x: numbers[0],
+      y: numbers[1],
+      width: numbers[2],
+      height: numbers[3]
+    },
+    cellWidth,
+    cellHeight,
+    visible: report.visible,
+    theme
+  };
+}
+function positiveNumber(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a positive number.`);
+  }
+  return value;
+}
+const PTY_PACKAGE = "node-pty";
+const SPAWN_HELPER_NAME = "spawn-helper";
+const SPAWN_HELPER_MODE = 493;
+const OWNER_EXECUTE = 64;
+const ASAR_APP = /([/\\])app\.asar([/\\])/;
+const ASAR_NODE_MODULES = /([/\\])node_modules\.asar([/\\])/;
+function unpackedPath(path2) {
+  return path2.replace(ASAR_APP, "$1app.asar.unpacked$2").replace(ASAR_NODE_MODULES, "$1node_modules.asar.unpacked$2");
+}
+function prebuildDir(root, target2) {
+  return path$1.join(root, "prebuilds", `${target2.platform}-${target2.arch}`);
+}
+function spawnHelperPath(root, target2) {
+  return path$1.join(prebuildDir(root, target2), SPAWN_HELPER_NAME);
+}
+function resolvePtyRoot() {
+  const requireFrom = node_module.createRequire(
+    typeof __filename === "string" ? __filename : require("url").pathToFileURL(__filename).href
+  );
+  return unpackedPath(
+    path$1.dirname(requireFrom.resolve(`${PTY_PACKAGE}/package.json`))
+  );
+}
+function ensureSpawnHelperExecutable(root, target2) {
+  const path2 = spawnHelperPath(root, target2);
+  try {
+    if (!fs.existsSync(path2)) {
+      return { path: null, mode: null, healed: false, reason: "no helper" };
+    }
+    const mode = fs.statSync(path2).mode & 511;
+    if ((mode & OWNER_EXECUTE) !== 0) {
+      return { path: path2, mode, healed: false };
+    }
+    fs.chmodSync(path2, SPAWN_HELPER_MODE);
+    return { path: path2, mode, healed: true };
+  } catch (error) {
+    return {
+      path: path2,
+      mode: null,
+      healed: false,
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+let cached = null;
+function loadNodePty() {
+  if (cached) return cached;
+  try {
+    const root = resolvePtyRoot();
+    const requireFrom = node_module.createRequire(
+      typeof __filename === "string" ? __filename : require("url").pathToFileURL(__filename).href
+    );
+    const namespace = requireFrom(PTY_PACKAGE);
+    const module = "spawn" in namespace ? namespace : namespace.default;
+    if (typeof module?.spawn !== "function") {
+      cached = { ok: false, reason: "node-pty loaded but exports no spawn()" };
+      return cached;
+    }
+    const helper = ensureSpawnHelperExecutable(root, {
+      platform: process.platform,
+      arch: process.arch
+    });
+    cached = { ok: true, root, helper, module };
+    return cached;
+  } catch (error) {
+    cached = {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error)
+    };
+    return cached;
+  }
+}
+function spawnPty(module, options, onHeal) {
+  const load = cached;
+  if (load?.ok) {
+    const report = ensureSpawnHelperExecutable(load.root, {
+      platform: process.platform,
+      arch: process.arch
+    });
+    if (report.healed) onHeal?.(report);
+  }
+  return module.spawn(options.file, options.args, {
+    // The surface's own name, so a program that asks what terminal it is on gets
+    // the pinned answer the window's TERM already declares (design 6.6).
+    name: "xterm-256color",
+    cols: options.cols,
+    rows: options.rows,
+    cwd: options.cwd,
+    env: options.env
+  });
+}
+const CONSOLE_HOST_ENV = "LOCAL_OPERATOR_UI_CONSOLE_HOST";
+const CONSOLE_REQUIRED_OPTIONS = [
+  "window",
+  "expectedUrl",
+  "appVersion",
+  "log"
+];
+function missingConsoleOptions(options) {
+  return CONSOLE_REQUIRED_OPTIONS.filter(
+    (field) => options[field] === void 0
+  );
+}
+function consoleHostEnabled(env = process.env) {
+  const flag = env[CONSOLE_HOST_ENV]?.trim().toLowerCase();
+  return !(flag === "0" || flag === "false" || flag === "off");
+}
+function broadcastConsoleState(window) {
+  if (window.isDestroyed()) return;
+  window.webContents.send("console-state-changed");
+}
+async function startConsoleHost(options) {
+  const missing = missingConsoleOptions(options);
+  if (missing.length > 0) {
+    throw new Error(
+      `startConsoleHost needs ${missing.join(", ")}: without it the host starts into a condition it invented rather than a failure`
+    );
+  }
+  const { log } = options;
+  if (!consoleHostEnabled()) {
+    log(
+      `[console] disabled by ${CONSOLE_HOST_ENV}; no surfaces will be created and the record carries console: false`
+    );
+    return {
+      ok: false,
+      reason: "disabled",
+      detail: `${CONSOLE_HOST_ENV} is off`,
+      stop: async () => {
+      }
+    };
+  }
+  const load = loadNodePty();
+  if (!load.ok) {
+    log(`[console] node-pty is unavailable: ${load.reason}`);
+    return {
+      ok: false,
+      reason: "pty_unavailable",
+      detail: load.reason,
+      stop: async () => {
+      }
+    };
+  }
+  if (load.helper.healed) {
+    log(
+      `[console] restored the exec bit on ${load.helper.path ?? "spawn-helper"}`
+    );
+  }
+  const configDir = options.configDir ?? localOperatorConfigDir();
+  const history = new ConsoleHistory(
+    path$1.join(configDir, "run", "ui-console", "history")
+  );
+  const registry = new ConsoleRegistry();
+  const host = new ConsoleHost(registry, {
+    window: () => options.window,
+    log,
+    history,
+    now: options.now,
+    spawn: options.spawn ?? ((spawnOptions) => spawnPty(load.module, spawnOptions, (report) => {
+      log(
+        `[console] restored the exec bit on ${report.path ?? "spawn-helper"}`
+      );
+    })),
+    onChanged: () => {
+      broadcastConsoleState(options.window);
+    },
+    onReveal: (request) => {
+      const window = options.window;
+      if (window.isDestroyed()) return;
+      window.webContents.send("console-reveal", {
+        surface: request.surface,
+        session_id: request.sessionId,
+        mode: request.mode
+      });
+    }
+  });
+  if (options.restoreHistory !== false) {
+    const retained = history.list().sort((a, b) => b.meta.last_seen_at - a.meta.last_seen_at).slice(0, MAX_SURFACES_PER_APP);
+    for (const surface of retained) {
+      host.restore(surface.meta, surface.bytes);
+    }
+    if (retained.length > 0) {
+      log(
+        `[console] restored ${retained.length} retained surface(s) from history; none of them is running`
+      );
+    }
+  }
+  const collected = history.collect();
+  if (collected.removedSessions.length > 0) {
+    log(
+      `[console] history GC removed ${collected.removedSurfaces} surface(s) from ${collected.removedSessions.length} session(s) older than the window`
+    );
+  }
+  registerConsoleIpc({
+    window: () => options.window,
+    expectedUrl: options.expectedUrl,
+    host: () => host,
+    log
+  });
+  log(
+    `[console] host ready on the existing endpoint: ${registry.count()} surface(s) (node-pty ${load.helper.mode === null ? "without a helper" : "ready"})`
+  );
+  return {
+    ok: true,
+    host,
+    registry,
+    counts: () => host.counts(),
+    dispatch: async (method, params) => {
+      if (!isConsoleDispatchMethod(method)) {
+        throw new Error(`not a console method: ${method}`);
+      }
+      return dispatchConsole(host, method, params);
+    },
+    stop: async () => {
+      unregisterConsoleIpc();
+      host.dispose();
+      log("[console] host stopped");
+    }
+  };
+}
 const WEBAUTHN_GROUP_SUFFIX = ".webauthn";
 const WEBAUTHN_PROMPT_REASON = "use a passkey for $1";
 const WEBAUTHN_CHOOSER_TIMEOUT_MS = 6e4;
@@ -10613,13 +13306,6 @@ function readJson(path2) {
     return null;
   }
 }
-class BridgeCommandError extends Error {
-  constructor(code, message, data = {}) {
-    super(message);
-    this.code = code;
-    this.data = data;
-  }
-}
 function errorData(error) {
   return error instanceof BridgeCommandError ? error.data : {};
 }
@@ -13278,53 +15964,6 @@ function retitle() {
     reason: "the browser tab is labelled with the page title"
   };
 }
-const PROTO_VERSION = 1;
-const METHODS = [
-  "open",
-  "goto",
-  "read",
-  "snapshot",
-  "screenshot",
-  "click",
-  "type",
-  "close",
-  "status",
-  "tabs",
-  "scroll",
-  "logs",
-  "request_access",
-  "await_access",
-  "cancel_access",
-  "retitle",
-  "owner_recover",
-  "owner_finish",
-  "owner_retain",
-  "owner_release"
-];
-const METHOD_SET = new Set(METHODS);
-function isMethod(value) {
-  return typeof value === "string" && METHOD_SET.has(value);
-}
-const ERROR_CODES = [
-  "extension_disconnected",
-  "not_paired",
-  "tab_closed",
-  "nav_failed",
-  "nav_timeout",
-  "element_not_found",
-  "origin_denied",
-  "origin_prompt_pending",
-  "origin_not_allowed",
-  "debugger_conflict",
-  "access_queue_full",
-  "tab_limit",
-  "tab_ambiguous",
-  "busy",
-  "proto_mismatch",
-  "owner_refused",
-  "extension_unresponsive",
-  "internal"
-];
 const DOCUMENT_SCOPED = /* @__PURE__ */ new Set([
   "read",
   "snapshot",
@@ -14668,119 +17307,6 @@ function flushBrowserStorage(browserSession) {
   } catch {
   }
 }
-const RUN_DIRNAME = path$1.join("run", "ui-browser");
-const STATE_FILENAME = "host.json";
-const STATE_DIR_MODE = 448;
-const STATE_FILE_MODE = 384;
-const HEARTBEAT_INTERVAL_MS = 15e3;
-function localOperatorConfigDir() {
-  const configured = process.env.LOCAL_OPERATOR_CONFIG_DIR?.trim();
-  if (configured) return configured;
-  return path$1.join(os.homedir(), ".local-operator");
-}
-function stateFilePath(root = localOperatorConfigDir()) {
-  return path$1.join(root, RUN_DIRNAME, STATE_FILENAME);
-}
-function mintSessionKey() {
-  return node_crypto.randomBytes(32).toString("base64url");
-}
-function keysMatch(presented, expected) {
-  if (typeof presented !== "string") return false;
-  const a = Buffer.from(presented, "utf8");
-  const b = Buffer.from(expected, "utf8");
-  if (a.length !== b.length) return false;
-  return node_crypto.timingSafeEqual(a, b);
-}
-class BrowserStateWriter {
-  constructor(path2, facts, options) {
-    this.path = path2;
-    this.facts = facts;
-    this.now = options.now ?? Date.now;
-    this.onError = options.onError ?? (() => {
-    });
-    this.appVersion = options.appVersion;
-  }
-  now;
-  onError;
-  timer = null;
-  written = false;
-  appVersion;
-  /** Publish the record and start the heartbeat. The heartbeat is the
-   * difference between "the app is running and can open a tab on demand" and a
-   * record that names a process that died without cleaning up. */
-  start(port, sessionKey) {
-    const startedAt = this.now() / 1e3;
-    this.startedAt = startedAt;
-    this.port = port;
-    this.sessionKey = sessionKey;
-    this.write();
-    this.timer = setInterval(() => this.write(), HEARTBEAT_INTERVAL_MS);
-    this.timer.unref?.();
-  }
-  startedAt = 0;
-  port = 0;
-  sessionKey = "";
-  /** Re-publish immediately, without waiting for the next heartbeat. Called
-   * when something the record reports has changed (a tab opened or closed). */
-  publishNow() {
-    if (this.port === 0) return;
-    this.write();
-  }
-  write() {
-    try {
-      const facts = this.facts();
-      const state = {
-        pid: process.pid,
-        port: this.port,
-        session_key: this.sessionKey,
-        proto: PROTO_VERSION,
-        host: "ui",
-        app_version: this.appVersion,
-        profile_dir: facts.profileDir,
-        tabs: facts.tabs,
-        agent_tabs: facts.agentTabs,
-        heartbeat_at: this.now() / 1e3,
-        started_at: this.startedAt || this.now() / 1e3
-      };
-      fs.mkdirSync(path$1.dirname(this.path), {
-        recursive: true,
-        mode: STATE_DIR_MODE
-      });
-      const staged = `${this.path}.${process.pid}.tmp`;
-      fs.writeFileSync(staged, `${JSON.stringify(state, null, 2)}
-`, {
-        mode: STATE_FILE_MODE
-      });
-      fs.renameSync(staged, this.path);
-      enforceStateFileModes(this.path);
-      this.written = true;
-    } catch (error) {
-      this.onError(error);
-    }
-  }
-  /** Remove the record, so discovery is honest when the host is gone. Called on
-   * host stop, on quit, and by the Settings toggle that turns the host off. */
-  clear() {
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
-    }
-    if (!this.written) return;
-    try {
-      fs.unlinkSync(this.path);
-    } catch (error) {
-      this.onError(error);
-    }
-    this.written = false;
-  }
-}
-function enforceStateFileModes(path2) {
-  try {
-    fs.chmodSync(path$1.dirname(path2), STATE_DIR_MODE);
-    fs.chmodSync(path2, STATE_FILE_MODE);
-  } catch {
-  }
-}
 const RPC_PATH = "/rpc";
 const HEALTH_PATH = "/health";
 const KEY_HEADER = "x-bridge-key";
@@ -14810,6 +17336,16 @@ function readBody(req) {
     req.on("error", reject);
   });
 }
+const CONSOLE_NAME = /^console_[a-z0-9_]+$/;
+function unknownConsoleMethod(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const envelope = raw;
+  if (typeof envelope.id !== "string" || !envelope.id) return null;
+  const method = envelope.method;
+  if (typeof method !== "string" || !CONSOLE_NAME.test(method)) return null;
+  if (isMethod(method)) return null;
+  return { id: envelope.id, method };
+}
 function errorResponse(id2, error) {
   if (error instanceof BridgeCommandError) {
     const known = ERROR_CODES.includes(error.code);
@@ -14899,7 +17435,12 @@ async function handle(req, res, options) {
       const body = {
         host: "ui",
         proto: PROTO_VERSION,
-        pid: process.pid
+        pid: process.pid,
+        // Additive: an older reader requires `host` and `pid` and ignores the
+        // rest, and a newer one learns whether the console is up without a
+        // second probe (design 10.1). `false` when nobody reported a
+        // capability, which is the honest answer for a host that has none.
+        console: options.capabilities?.().console ?? false
       };
       send(res, 200, body);
       return;
@@ -14927,6 +17468,22 @@ async function handle(req, res, options) {
     try {
       request = validateRequest(raw);
     } catch (error) {
+      const skew = unknownConsoleMethod(raw);
+      if (skew) {
+        send(
+          res,
+          200,
+          errorResponse(
+            skew.id,
+            new BridgeCommandError(
+              "unsupported_method",
+              `this app version has no console method ${JSON.stringify(skew.method)}; update Local Operator`,
+              { method: skew.method }
+            )
+          )
+        );
+        return;
+      }
       send(res, 422, {
         detail: error instanceof Error ? error.message : "invalid envelope"
       });
@@ -16175,19 +18732,44 @@ async function startBrowserHost(options) {
       `[browser] restored ${recorded.length} tab(s) from ${SESSION_FILENAME}; every restored tab is user-owned and holds no handle (design 7.3)`
     );
   }
+  const consoleStartup = await startConsoleHost({
+    window: options.window,
+    expectedUrl: options.expectedUrl,
+    appVersion: options.appVersion,
+    log
+  });
   const sessionKey = mintSessionKey();
   const server = await startRpcServer({
     key: sessionKey,
-    dispatch: (method, params, requestId2) => host.dispatch(method, params, requestId2),
-    log
+    dispatch: async (method, params, requestId2) => {
+      if (!isConsoleDispatchMethod(method)) {
+        return host.dispatch(method, params, requestId2);
+      }
+      if (!consoleStartup.ok) {
+        throw new ConsoleError(
+          "console_unavailable",
+          `this app's console is not available (${consoleStartup.reason}): ${consoleStartup.detail}`,
+          { reason: consoleStartup.reason }
+        );
+      }
+      return consoleStartup.dispatch(method, params);
+    },
+    log,
+    capabilities: () => ({ console: consoleStartup.ok })
   });
   stateWriter = new BrowserStateWriter(
     stateFilePath(),
-    () => ({
-      tabs: registry.count(),
-      agentTabs: registry.agentTabCount(),
-      profileDir
-    }),
+    () => {
+      const consoleCounts = consoleStartup.ok ? consoleStartup.counts() : { total: 0, agent: 0 };
+      return {
+        tabs: registry.count(),
+        agentTabs: registry.agentTabCount(),
+        profileDir,
+        console: consoleStartup.ok,
+        consoleSurfaces: consoleCounts.total,
+        consoleAgentSurfaces: consoleCounts.agent
+      };
+    },
     {
       appVersion: options.appVersion,
       onError: (error) => log(`[browser] state file: ${String(error)}`)
@@ -16203,7 +18785,7 @@ async function startBrowserHost(options) {
     log
   });
   log(
-    `[browser] host on ${server.address}:${server.port} (proto ${facts.proto}), profile ${profileDir || "(in-memory)"}, agent tabs ${registry.agentTabCount()}/${8}`
+    `[browser] host on ${server.address}:${server.port} (proto ${facts.proto}), profile ${profileDir || "(in-memory)"}, agent tabs ${registry.agentTabCount()}/${8}, console ${consoleStartup.ok ? `on (${consoleStartup.counts().total} surface(s))` : `off (${consoleStartup.reason})`}`
   );
   const handle2 = {
     host,
@@ -16226,6 +18808,7 @@ async function startBrowserHost(options) {
       registry.destroyAll();
       await cdp.close();
       await server.close();
+      await consoleStartup.stop();
       unregisterBrowserIpc();
       detachWebauthn();
       webauthn.dispose();
@@ -20204,15 +22787,15 @@ ${heal.removed.join("\n")}`,
       );
     }
     const label = shipItJobLabel(bundleId);
-    const logPath = installerLogPath(
+    const logPath2 = installerLogPath(
       shipItCacheDir(path$1.join(os.homedir(), "Library", "Caches"), bundleId)
     );
     try {
-      fs.mkdirSync(path$1.dirname(logPath), { recursive: true });
-      fs.closeSync(fs.openSync(logPath, "a"));
+      fs.mkdirSync(path$1.dirname(logPath2), { recursive: true });
+      fs.closeSync(fs.openSync(logPath2, "a"));
     } catch (error) {
       return refuse(
-        `the installer's log ${logPath} could not be opened for appending: ${String(error)}`
+        `the installer's log ${logPath2} could not be opened for appending: ${String(error)}`
       );
     }
     return {
@@ -20227,7 +22810,7 @@ ${heal.removed.join("\n")}`,
         // install: the failure panel's detail line and
         // scripts/update-window-report.mjs both read that path (see
         // installerLogPath).
-        logPath
+        logPath: logPath2
       }
     };
   }
@@ -20460,12 +23043,12 @@ ${heal.removed.join("\n")}`,
         } catch (error) {
           const code = transientTransportCode(error);
           if (code === null || attempt >= delays.length) throw error;
-          const delay = delays[attempt];
+          const delay2 = delays[attempt];
           logger.warn(
-            `Transient transport failure during the update check (${code}); retrying in ${delay}ms (attempt ${attempt + 2} of ${delays.length + 1})`,
+            `Transient transport failure during the update check (${code}); retrying in ${delay2}ms (attempt ${attempt + 2} of ${delays.length + 1})`,
             LogFileType.UPDATE_SERVICE
           );
-          await new Promise((resolve) => setTimeout(resolve, delay));
+          await new Promise((resolve) => setTimeout(resolve, delay2));
         }
       }
     } finally {