@threadbase-sh/streamer 1.43.0 → 1.44.1

package/dist/index.js

@@ -102,14 +102,14 @@ function createConversationWriter(opts) {
       }
       const file = join(baseDir, `${args.sessionId}.jsonl`);
       await mkdir(dirname(file), { recursive: true });
-      const record = {
+      const record2 = {
         role: "assistant",
         turnId: args.turnId,
         content: args.content,
         timestamp: Date.now(),
         ...args.reviewerOverruled ? { reviewerOverruled: true } : {}
       };
-      const line = `${JSON.stringify(record)}
+      const line = `${JSON.stringify(record2)}
 `;
       await appendFile(file, line, { encoding: "utf8" });
     }
@@ -416,6 +416,9 @@ var baseLogger = pino({
     censor: "[redacted]"
   }
 });
+function defaultDest() {
+  return process.stdout.isTTY ? "console" : "pino";
+}
 function emit(pinoChild, level, msg, fields, dest) {
   if (dest === "pino" || dest === "both") {
     if (fields && Object.keys(fields).length > 0) pinoChild[level](fields, msg);
@@ -428,11 +431,11 @@ function emit(pinoChild, level, msg, fields, dest) {
 }
 function build(pinoChild) {
   return {
-    debug: (m, f, d = "both") => emit(pinoChild, "debug", m, f, d),
-    info: (m, f, d = "both") => emit(pinoChild, "info", m, f, d),
-    warn: (m, f, d = "both") => emit(pinoChild, "warn", m, f, d),
-    error: (m, f, d = "both") => emit(pinoChild, "error", m, f, d),
-    log: (lvl, m, f, d = "both") => emit(pinoChild, lvl, m, f, d),
+    debug: (m, f, d = defaultDest()) => emit(pinoChild, "debug", m, f, d),
+    info: (m, f, d = defaultDest()) => emit(pinoChild, "info", m, f, d),
+    warn: (m, f, d = defaultDest()) => emit(pinoChild, "warn", m, f, d),
+    error: (m, f, d = defaultDest()) => emit(pinoChild, "error", m, f, d),
+    log: (lvl, m, f, d = defaultDest()) => emit(pinoChild, lvl, m, f, d),
     pino: pinoChild
   };
 }
@@ -454,6 +457,12 @@ var FEATURE_FLAGS = [
     description: "Seed the session list at boot with sessions a previous streamer run left behind, so a restart leaves them one tap from resuming instead of silently gone. On by default, with a kill switch: it changes what GET /api/sessions contains.",
     default: true,
     env: "THREADBASE_FEATURE_SESSION_REHYDRATION"
+  },
+  {
+    id: "ptyHost",
+    description: "Keep live PTYs in a separate host process so a streamer restart can reconnect without restarting the agents. Off by default until cross-platform behavior is qualified.",
+    default: false,
+    env: "THREADBASE_FEATURE_PTY_HOST"
   }
 ];
 function findFeatureFlag(id) {
@@ -819,7 +828,16 @@ import { existsSync } from "fs";
 import { homedir as homedir2, platform } from "os";
 import { join as join4 } from "path";
 var isWindows = platform() === "win32";
+var WINDOWS_EXECUTABLE_EXTENSIONS = /* @__PURE__ */ new Set([".exe", ".cmd", ".bat"]);
+function isWindowsExecutablePath(path) {
+  const dot = path.lastIndexOf(".");
+  if (dot < 0) return false;
+  return WINDOWS_EXECUTABLE_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
 var _claudeExe;
+function clearClaudeExeCache() {
+  _claudeExe = void 0;
+}
 function resolveClaudeExe() {
   if (_claudeExe !== void 0) return _claudeExe;
   if (isWindows) {
@@ -828,7 +846,7 @@ function resolveClaudeExe() {
         encoding: "utf-8",
         windowsHide: true,
         timeout: 3e3
-      }).trim().split("\n")[0].trim();
+      }).trim().split("\n").map((line) => line.trim()).find(isWindowsExecutablePath);
       if (found) {
         _claudeExe = found;
         return _claudeExe;
@@ -878,6 +896,9 @@ function resolveClaudeExe() {
   return _claudeExe;
 }
 var _codexExe;
+function clearCodexExeCache() {
+  _codexExe = void 0;
+}
 function resolveCodexExe() {
   if (_codexExe !== void 0) return _codexExe;
   if (isWindows) {
@@ -886,7 +907,7 @@ function resolveCodexExe() {
         encoding: "utf-8",
         windowsHide: true,
         timeout: 3e3
-      }).trim().split("\n")[0].trim();
+      }).trim().split("\n").map((line) => line.trim()).find(isWindowsExecutablePath);
       if (found) {
         _codexExe = found;
         return _codexExe;
@@ -1146,20 +1167,26 @@ var CodexPtyRunner = class {
   async doStart(sessionId, options) {
     const nodePty = await loadPty();
     const projectName = options.projectName ?? basename(options.projectPath);
-    const proc = nodePty.spawn(
-      resolveCodexExe(),
-      // `sessionId` stays the runner's map key — only argv carries the
-      // provider-side id, so a resumed Codex session keeps the placeholder id
-      // its client already navigated to.
-      ["resume", options.resumeId ?? sessionId, "--cd", options.projectPath, "--no-alt-screen"],
-      {
-        name: "xterm-256color",
-        cols: PTY_COLS,
-        rows: PTY_ROWS,
-        cwd: options.projectPath,
-        env: process.env
-      }
-    );
+    let proc;
+    try {
+      proc = nodePty.spawn(
+        resolveCodexExe(),
+        // `sessionId` stays the runner's map key — only argv carries the
+        // provider-side id, so a resumed Codex session keeps the placeholder id
+        // its client already navigated to.
+        ["resume", options.resumeId ?? sessionId, "--cd", options.projectPath, "--no-alt-screen"],
+        {
+          name: "xterm-256color",
+          cols: PTY_COLS,
+          rows: PTY_ROWS,
+          cwd: options.projectPath,
+          env: process.env
+        }
+      );
+    } catch (err) {
+      clearCodexExeCache();
+      throw err;
+    }
     const session = {
       id: sessionId,
       provider: CODEX_CLI_PROVIDER,
@@ -1202,13 +1229,19 @@ var CodexPtyRunner = class {
     if (options.systemPrompt) {
       args.push(options.systemPrompt);
     }
-    const proc = nodePty.spawn(resolveCodexExe(), args, {
-      name: "xterm-256color",
-      cols: PTY_COLS,
-      rows: PTY_ROWS,
-      cwd: options.projectPath,
-      env: process.env
-    });
+    let proc;
+    try {
+      proc = nodePty.spawn(resolveCodexExe(), args, {
+        name: "xterm-256color",
+        cols: PTY_COLS,
+        rows: PTY_ROWS,
+        cwd: options.projectPath,
+        env: process.env
+      });
+    } catch (err) {
+      clearCodexExeCache();
+      throw err;
+    }
     const session = {
       id: sessionId,
       provider: CODEX_CLI_PROVIDER,
@@ -1683,6 +1716,381 @@ function stripAnsi(str) {
   return str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "").replace(/\x1b\][^\x07]*\x07/g, "");
 }
 
+// src/pty-host/protocol.ts
+var PTY_HOST_PROTOCOL_VERSION = 2;
+function isHostEvent(message) {
+  return "type" in message && message.type === "event";
+}
+var SESSION_DATE_FIELDS = [
+  "startedAt",
+  "completedAt",
+  "statusUpdatedAt",
+  "lastActivityAt",
+  "firstMessageAt",
+  "lastMessageAt"
+];
+function reviveSession(raw) {
+  const s = { ...raw };
+  for (const field of SESSION_DATE_FIELDS) {
+    const value = s[field];
+    if (typeof value === "string") s[field] = new Date(value);
+  }
+  return s;
+}
+function encodeMessage(message) {
+  return `${JSON.stringify(message)}
+`;
+}
+var LineDecoder = class {
+  buffer = "";
+  push(chunk) {
+    this.buffer += chunk;
+    const lines = this.buffer.split("\n");
+    this.buffer = lines.pop() ?? "";
+    return lines.filter((line) => line.length > 0);
+  }
+};
+
+// src/pty-host/remote-session-runner.ts
+var PtyHostProtocolMismatchError = class extends Error {
+  constructor(hostVersion, streamerVersion) {
+    super(
+      `pty-host protocol ${hostVersion} is incompatible with streamer protocol ${streamerVersion}`
+    );
+    this.hostVersion = hostVersion;
+    this.streamerVersion = streamerVersion;
+    this.name = "PtyHostProtocolMismatchError";
+  }
+  hostVersion;
+  streamerVersion;
+};
+var HOST_HEARTBEAT_INTERVAL_MS = 1e4;
+var HOST_HEARTBEAT_REQUEST_TIMEOUT_MS = 5e3;
+var HOST_SHUTDOWN_REQUEST_TIMEOUT_MS = 1e3;
+var RemoteSessionRunner = class _RemoteSessionRunner {
+  transport;
+  options;
+  decoder = new LineDecoder();
+  nextRequestId = 1;
+  pending = /* @__PURE__ */ new Map();
+  /** The mirror. Rebuilt wholesale by `status`, patched by events. */
+  sessions = /* @__PURE__ */ new Map();
+  /** Ring buffers, fed by `output` events so `getOutput` stays synchronous. */
+  output = /* @__PURE__ */ new Map();
+  inputHistory = /* @__PURE__ */ new Map();
+  /** Fixed for a session's lifetime, so only spawn and status carry it. */
+  pids = /* @__PURE__ */ new Map();
+  closed = false;
+  heartbeatTimer = null;
+  heartbeatInFlight = false;
+  /**
+   * The only supported way to build one: a runner whose mirror has not been
+   * seeded yet would answer `hasSession` with a confident, wrong `false` for
+   * every session the host is holding — which reads as "the agent is gone" and
+   * routes the user to start a new one.
+   */
+  static async connect(transport, options = {}) {
+    const runner = new _RemoteSessionRunner(transport, options);
+    const status = await runner.readStatus();
+    if (status.protocolVersion !== PTY_HOST_PROTOCOL_VERSION) {
+      try {
+        await runner.request({ type: "shutdown-host" }, HOST_SHUTDOWN_REQUEST_TIMEOUT_MS);
+      } catch (err) {
+        options.logger?.warn("[pty-host] incompatible host did not acknowledge shutdown", {
+          event: "pty_host.shutdown_failed",
+          err
+        });
+      } finally {
+        runner.dispose();
+      }
+      throw new PtyHostProtocolMismatchError(status.protocolVersion, PTY_HOST_PROTOCOL_VERSION);
+    }
+    await runner.request({ type: "subscribe" });
+    runner.refreshMirror(status);
+    return runner;
+  }
+  constructor(transport, options) {
+    this.transport = transport;
+    this.options = options;
+    transport.onLine((line) => this.handleLine(line));
+    transport.onClose(() => this.handleClose());
+  }
+  // ─── Transport plumbing ──────────────────────────────────────────
+  handleLine(line) {
+    for (const complete of this.decoder.push(line)) {
+      let message;
+      try {
+        message = JSON.parse(complete);
+      } catch {
+        this.options.logger?.warn("[pty-host] dropped unparseable message", {
+          event: "pty_host.bad_message"
+        });
+        continue;
+      }
+      if (isHostEvent(message)) {
+        this.handleEvent(message);
+        continue;
+      }
+      const waiter = this.pending.get(message.id);
+      if (!waiter) continue;
+      this.pending.delete(message.id);
+      if (waiter.timeout) clearTimeout(waiter.timeout);
+      if (message.ok) waiter.resolve(message.result);
+      else waiter.reject(new Error(message.error));
+    }
+  }
+  /**
+   * Fail every in-flight request when the socket drops.
+   *
+   * Without this each one stays pending forever and the caller — a session
+   * start, an input write — hangs rather than erroring. PR 9 adds reconnection;
+   * until then a dropped host is a hard failure that says so.
+   */
+  handleClose() {
+    if (this.closed) return;
+    this.closed = true;
+    this.stopHeartbeat();
+    const err = new Error("pty-host connection closed");
+    for (const waiter of this.pending.values()) {
+      if (waiter.timeout) clearTimeout(waiter.timeout);
+      waiter.reject(err);
+    }
+    this.pending.clear();
+  }
+  request(body, timeoutMs) {
+    if (this.closed) return Promise.reject(new Error("pty-host connection closed"));
+    const id = this.nextRequestId++;
+    return new Promise((resolve2, reject) => {
+      const timeout = timeoutMs === void 0 ? null : setTimeout(() => {
+        if (!this.pending.delete(id)) return;
+        reject(new Error(`${body.type} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      timeout?.unref?.();
+      this.pending.set(id, { resolve: resolve2, reject, timeout });
+      this.transport.send(encodeMessage({ ...body, id }));
+    });
+  }
+  /**
+   * Fire-and-forget for the synchronous parts of `SessionRunner`.
+   *
+   * `sendKeys`, `cancel`, `killPid` and `putOnHold` all return void, so there is
+   * no channel to report a failure through even if we waited for one. The
+   * response is still consumed — an unhandled rejection would take the process
+   * down over a keystroke that failed to land.
+   */
+  fireAndForget(body) {
+    this.request(body).catch((err) => {
+      this.options.logger?.warn("[pty-host] request failed", {
+        event: "pty_host.request_failed",
+        type: body.type,
+        err
+      });
+    });
+  }
+  async readStatus() {
+    return await this.request({ type: "status" });
+  }
+  refreshMirror(status) {
+    this.sessions = /* @__PURE__ */ new Map();
+    this.pids = /* @__PURE__ */ new Map();
+    for (const entry of status.sessions) {
+      const session = reviveSession(entry.session);
+      this.sessions.set(session.id, session);
+      this.pids.set(session.id, entry.pid);
+    }
+  }
+  async heartbeat(state, timeoutMs = HOST_HEARTBEAT_REQUEST_TIMEOUT_MS) {
+    await this.request({ type: "heartbeat", ...state }, timeoutMs);
+  }
+  startHeartbeat(getState, intervalMs = HOST_HEARTBEAT_INTERVAL_MS) {
+    this.stopHeartbeat();
+    const send = () => {
+      if (this.closed || this.heartbeatInFlight) return;
+      this.heartbeatInFlight = true;
+      void Promise.resolve().then(() => this.heartbeat(getState())).catch((err) => {
+        if (this.closed) return;
+        this.options.logger?.warn("[pty-host] heartbeat failed", {
+          event: "pty_host.heartbeat_failed",
+          err
+        });
+      }).finally(() => {
+        this.heartbeatInFlight = false;
+      });
+    };
+    send();
+    this.heartbeatTimer = setInterval(send, intervalMs);
+    this.heartbeatTimer.unref?.();
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = null;
+  }
+  // ─── Events ──────────────────────────────────────────────────────
+  handleEvent(event) {
+    switch (event.event) {
+      case "output": {
+        this.output.set(event.sessionId, (this.output.get(event.sessionId) ?? "") + event.data);
+        this.options.onOutput?.(event.sessionId, event.data);
+        break;
+      }
+      case "status-change": {
+        const session = reviveSession(event.session);
+        if (session.status === "idle" && session.completedAt != null) {
+          this.sessions.delete(session.id);
+          this.pids.delete(session.id);
+          this.output.delete(session.id);
+          this.inputHistory.delete(session.id);
+        } else {
+          this.sessions.set(session.id, session);
+        }
+        this.options.onStatusChange?.(session);
+        break;
+      }
+      case "ready": {
+        const session = reviveSession(event.session);
+        this.sessions.set(session.id, session);
+        this.options.onReady?.(session);
+        break;
+      }
+      case "permission-change":
+        this.options.onPermissionChange?.(event.sessionId, event.gate);
+        break;
+      case "live-question":
+        this.options.onLiveQuestion?.(event.sessionId, event.questions);
+        break;
+      case "live-question-gone":
+        this.options.onLiveQuestionGone?.(event.sessionId);
+        break;
+      case "user-message": {
+        const history = this.inputHistory.get(event.sessionId) ?? [];
+        history.push({ text: event.text, ts: event.ts });
+        this.inputHistory.set(event.sessionId, history);
+        this.options.onUserMessage?.(event.sessionId, event.text, event.ts);
+        break;
+      }
+      case "exit": {
+        this.sessions.delete(event.sessionId);
+        this.pids.delete(event.sessionId);
+        this.output.delete(event.sessionId);
+        this.inputHistory.delete(event.sessionId);
+        break;
+      }
+    }
+  }
+  // ─── SessionRunner ───────────────────────────────────────────────
+  async start(sessionId, options) {
+    const provider = options.provider ?? "claude-code";
+    return this.adopt(await this.request({ type: "spawn", provider, sessionId, options }));
+  }
+  async startFresh(options) {
+    const provider = options.provider ?? "claude-code";
+    return this.adopt(await this.request({ type: "spawn", provider, sessionId: null, options }));
+  }
+  /**
+   * Take a spawn answer into the mirror.
+   *
+   * The pid lands here and nowhere else in the live path: `recordSessionSpawn`
+   * reads it immediately after start to write the durable registry row, and a
+   * null there costs the next boot its ability to probe whether the agent
+   * outlived us.
+   */
+  adopt(raw) {
+    const entry = raw;
+    const session = reviveSession(entry.session);
+    this.sessions.set(session.id, session);
+    this.pids.set(session.id, entry.pid);
+    return session;
+  }
+  /**
+   * Returns the mirror's promptCount, optimistically incremented.
+   *
+   * The interface is synchronous, so there is no way to return the host's
+   * authoritative count. The increment matches what an in-process runner does
+   * for the same call, and the next `status-change` event overwrites it — so a
+   * mirror that guessed wrong is corrected within one round trip rather than
+   * drifting.
+   */
+  sendInput(sessionId, input) {
+    const session = this.requireSession(sessionId);
+    this.fireAndForget({ type: "write", sessionId, input });
+    session.promptCount += 1;
+    return session.promptCount;
+  }
+  sendKeys(sessionId, keys) {
+    this.requireSession(sessionId);
+    this.fireAndForget({ type: "keys", sessionId, keys });
+  }
+  cancel(sessionId) {
+    this.fireAndForget({ type: "cancel", sessionId });
+  }
+  killPid(pid) {
+    this.fireAndForget({ type: "kill", pid });
+  }
+  putOnHold(sessionId) {
+    this.fireAndForget({ type: "kill", sessionId, hold: true });
+    this.sessions.delete(sessionId);
+    this.pids.delete(sessionId);
+  }
+  getOutput(sessionId) {
+    this.requireSession(sessionId);
+    return this.output.get(sessionId) ?? "";
+  }
+  async getOutputLines(sessionId, maxLines) {
+    const result = await this.request({ type: "replay", sessionId, maxLines });
+    if (typeof result.output === "string") this.output.set(sessionId, result.output);
+    return result.lines;
+  }
+  /**
+   * Synchronous, so it answers from the mirror rather than the host.
+   *
+   * Seeded lazily: `user-message` events append as they arrive, and a session
+   * this streamer did not start has none until `hydrateInputHistory` fetches
+   * them. Empty is the same answer an in-process runner gives for an unknown
+   * session, so a caller cannot tell "none yet" from "not fetched" — which is
+   * why the fetch is explicit rather than hidden behind this getter.
+   */
+  getInputHistory(sessionId) {
+    return this.inputHistory.get(sessionId) ?? [];
+  }
+  /** Pull a session's recorded messages from the host into the mirror. */
+  async hydrateInputHistory(sessionId) {
+    const result = await this.request({
+      type: "input-history",
+      sessionId
+    });
+    this.inputHistory.set(sessionId, result.history);
+    return result.history;
+  }
+  getPid(sessionId) {
+    return this.pids.get(sessionId) ?? null;
+  }
+  getSession(sessionId) {
+    return this.sessions.get(sessionId) ?? null;
+  }
+  hasSession(sessionId) {
+    return this.sessions.has(sessionId);
+  }
+  listSessions() {
+    return [...this.sessions.values()];
+  }
+  /**
+   * Drops this streamer's connection and nothing else.
+   *
+   * Emphatically NOT the in-process `dispose()`, which signals every child. The
+   * entire point of the host is that its PTYs outlive the streamer, so tearing
+   * them down here would spend the feature to implement a method name.
+   */
+  dispose() {
+    this.handleClose();
+    this.transport.close();
+  }
+  requireSession(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error(`Session not found: ${sessionId}`);
+    return session;
+  }
+};
+
 // src/pty-manager.ts
 import { Terminal as Terminal2 } from "@xterm/headless";
 import { randomUUID as randomUUID2 } from "crypto";
@@ -2054,13 +2462,19 @@ var PTYManager = class {
       sessionId
     ];
     args.push(...buildFlagArgs(options.claudeFlags, options.claudeExtraArgs));
-    const proc = nodePty.spawn(resolveClaudeExe(), args, {
-      name: "xterm-256color",
-      cols: 120,
-      rows: 40,
-      cwd: options.projectPath,
-      env: buildSpawnEnv()
-    });
+    let proc;
+    try {
+      proc = nodePty.spawn(resolveClaudeExe(), args, {
+        name: "xterm-256color",
+        cols: 120,
+        rows: 40,
+        cwd: options.projectPath,
+        env: buildSpawnEnv()
+      });
+    } catch (err) {
+      clearClaudeExeCache();
+      throw err;
+    }
     const session = {
       id: sessionId,
       provider: CLAUDE_CODE_PROVIDER,
@@ -2115,13 +2529,19 @@ var PTYManager = class {
       args.push("--system-prompt", options.systemPrompt);
     }
     args.push(...buildFlagArgs(options.claudeFlags, options.claudeExtraArgs));
-    const proc = nodePty.spawn(resolveClaudeExe(), args, {
-      name: "xterm-256color",
-      cols: 120,
-      rows: 40,
-      cwd: options.projectPath,
-      env: buildSpawnEnv()
-    });
+    let proc;
+    try {
+      proc = nodePty.spawn(resolveClaudeExe(), args, {
+        name: "xterm-256color",
+        cols: 120,
+        rows: 40,
+        cwd: options.projectPath,
+        env: buildSpawnEnv()
+      });
+    } catch (err) {
+      clearClaudeExeCache();
+      throw err;
+    }
     const session = {
       id: sessionId,
       provider: CLAUDE_CODE_PROVIDER,
@@ -2687,12 +3107,30 @@ function stripAnsi2(str) {
 // src/live-session-manager.ts
 var LiveSessionManager = class {
   runners;
+  remoteRunner = null;
+  options;
   constructor(options = {}) {
+    this.options = options;
     this.runners = /* @__PURE__ */ new Map([
       [CLAUDE_CODE_PROVIDER, new PTYManager(options)],
       [CODEX_CLI_PROVIDER, new CodexPtyRunner(options)]
     ]);
   }
+  async useRemoteRunner(transport) {
+    const remote = await RemoteSessionRunner.connect(transport, this.options);
+    await Promise.all(
+      remote.listSessions().map((session) => remote.hydrateInputHistory(session.id))
+    );
+    for (const runner of this.runners.values()) runner.dispose();
+    this.remoteRunner = remote;
+    return remote.listSessions();
+  }
+  isRemote() {
+    return this.remoteRunner !== null;
+  }
+  startRemoteHeartbeat(getState) {
+    this.remoteRunner?.startHeartbeat(getState);
+  }
   async start(sessionId, options) {
     const provider = options.provider ?? CLAUDE_CODE_PROVIDER;
     const runner = this.assertSupportedProvider(provider, options.projectPath);
@@ -2713,7 +3151,7 @@ var LiveSessionManager = class {
     this.runnerFor(sessionId).cancel(sessionId);
   }
   killPid(pid) {
-    for (const runner of this.runners.values()) {
+    for (const runner of this.activeRunners()) {
       runner.killPid(pid);
     }
   }
@@ -2723,13 +3161,13 @@ var LiveSessionManager = class {
   // every runner rather than throwing; this matches the pre-extraction
   // behavior of delegating straight through with no existence check.
   putOnHold(sessionId) {
-    for (const runner of this.runners.values()) {
+    for (const runner of this.activeRunners()) {
       if (runner.hasSession(sessionId) || runner.getSession(sessionId)) {
         runner.putOnHold(sessionId);
         return;
       }
     }
-    for (const runner of this.runners.values()) {
+    for (const runner of this.activeRunners()) {
       runner.putOnHold(sessionId);
     }
   }
@@ -2743,7 +3181,7 @@ var LiveSessionManager = class {
     return this.runnerFor(sessionId).getInputHistory(sessionId);
   }
   getSession(sessionId) {
-    for (const runner of this.runners.values()) {
+    for (const runner of this.activeRunners()) {
       const session = runner.getSession(sessionId);
       if (session) return session;
     }
@@ -2753,23 +3191,23 @@ var LiveSessionManager = class {
   // best-effort basis, so an unknown session must return null rather than
   // throw the way the input-routing methods do.
   getPid(sessionId) {
-    for (const runner of this.runners.values()) {
+    for (const runner of this.activeRunners()) {
       const pid = runner.getPid(sessionId);
       if (pid != null) return pid;
     }
     return null;
   }
   hasSession(sessionId) {
-    for (const runner of this.runners.values()) {
+    for (const runner of this.activeRunners()) {
       if (runner.hasSession(sessionId)) return true;
     }
     return false;
   }
   listSessions() {
-    return Array.from(this.runners.values()).flatMap((runner) => runner.listSessions());
+    return this.activeRunners().flatMap((runner) => runner.listSessions());
   }
   dispose() {
-    for (const runner of this.runners.values()) {
+    for (const runner of this.activeRunners()) {
       runner.dispose();
     }
   }
@@ -2777,12 +3215,13 @@ var LiveSessionManager = class {
   // this is a linear scan across hasSession()/getSession() rather than a
   // separate session→provider index — see task-1-brief.md.
   runnerFor(sessionId) {
-    for (const runner of this.runners.values()) {
+    for (const runner of this.activeRunners()) {
       if (runner.hasSession(sessionId) || runner.getSession(sessionId)) return runner;
     }
     throw new Error(`Session not found: ${sessionId}`);
   }
   assertSupportedProvider(provider, projectPath) {
+    if (this.remoteRunner) return this.remoteRunner;
     const runner = this.runners.get(provider);
     if (runner) return runner;
     const err = new Error(
@@ -2791,6 +3230,9 @@ var LiveSessionManager = class {
     err.statusCode = 501;
     throw err;
   }
+  activeRunners() {
+    return this.remoteRunner ? [this.remoteRunner] : [...this.runners.values()];
+  }
 };
 
 // src/process-discovery.ts
@@ -3080,9 +3522,9 @@ import {
   statSync as statSync9
 } from "fs";
 import { realpath as realpath2 } from "fs/promises";
-import { createServer } from "http";
-import { homedir as homedir9, hostname as hostname3 } from "os";
-import { basename as basename5, dirname as dirname9, join as join18 } from "path";
+import { createServer as createServer2 } from "http";
+import { homedir as homedir10, hostname as hostname3 } from "os";
+import { basename as basename5, dirname as dirname9, join as join19 } from "path";
 import { createInterface } from "readline";
 
 // node_modules/nanoid/index.js
@@ -5205,21 +5647,53 @@ var createWsRoutes = (deps, upgradeWebSocket) => {
 };
 
 // src/api/app.ts
+var ALREADY_HANDLED7 = 597;
+function summarizeQuery(query) {
+  const keys = Object.keys(query).sort();
+  if (keys.length === 0) return void 0;
+  return keys.map((k) => `${k}=${/^-?\d+$/.test(query[k]) ? query[k] : "_"}`).join("&");
+}
+function countResponseBytes(res) {
+  let bytes = 0;
+  const add = (chunk) => {
+    if (typeof chunk === "string") bytes += Buffer.byteLength(chunk);
+    else if (chunk instanceof Uint8Array) bytes += chunk.byteLength;
+  };
+  const write = res.write;
+  const end = res.end;
+  res.write = function(...args) {
+    add(args[0]);
+    return write.apply(this, args);
+  };
+  res.end = function(...args) {
+    add(args[0]);
+    return end.apply(this, args);
+  };
+  return () => bytes;
+}
 var createHonoApp = (deps, upgradeWebSocket) => {
   const app = new Hono18();
   const httpLog = getLogger("http");
   app.use("*", async (c, next) => {
     const start = Date.now();
     const ua = c.req.header("user-agent") ?? "";
+    const outgoing = c.env?.outgoing;
+    const bytesWritten = outgoing && countResponseBytes(outgoing);
     await next();
     if (!deps.logMenubarRequests && c.req.header("x-client") === "menubar") return;
     const ms = Date.now() - start;
-    httpLog.info(`[req] ${c.req.method} ${c.req.path} \u2192 ${c.res.status} ${ms}ms`, {
+    const handled = c.res.status === ALREADY_HANDLED7 && outgoing !== void 0;
+    const status = handled ? outgoing.statusCode : c.res.status;
+    const qs = summarizeQuery(c.req.query());
+    const bytes = handled && bytesWritten ? bytesWritten() : void 0;
+    httpLog.info(`[req] ${c.req.method} ${c.req.path} \u2192 ${status} ${ms}ms`, {
       method: c.req.method,
       path: c.req.path,
-      status: c.res.status,
+      status,
       ms,
       ua,
+      ...qs ? { qs } : {},
+      ...bytes === void 0 ? {} : { bytes },
       event: "http.request"
     });
   });
@@ -5310,6 +5784,74 @@ import { open as openAsync } from "fs/promises";
 import { dirname as dirname7 } from "path";
 import { setImmediate as yieldToEventLoop } from "timers/promises";
 
+// src/db/query-timing.ts
+var log3 = getLogger("db");
+var DEFAULT_SLOW_QUERY_MS = 35;
+var LABEL = /* @__PURE__ */ Symbol("tbQueryLabel");
+function deriveLabel(sql) {
+  const verb = /^\s*(\w+)/.exec(sql)?.[1]?.toLowerCase() ?? "sql";
+  const table = /(?:from|into|update)\s+([A-Za-z_]\w*)/i.exec(sql)?.[1] ?? "?";
+  return `${verb}:${table}`;
+}
+function resolveSlowMs() {
+  const raw = process.env.THREADBASE_DB_SLOW_QUERY_MS;
+  if (raw === void 0 || raw === "") return DEFAULT_SLOW_QUERY_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : DEFAULT_SLOW_QUERY_MS;
+}
+function record(label, ms, rows, slowMs) {
+  if (slowMs > 0 && ms >= slowMs) {
+    log3.warn(
+      `[db] slow query ${label} ${ms.toFixed(1)}ms rows=${rows}`,
+      { event: "db.slow_query", stmt: label, ms: Math.round(ms * 100) / 100, rows },
+      "pino"
+    );
+    return;
+  }
+  if (log3.pino.isLevelEnabled("debug")) {
+    log3.debug(
+      `[db] ${label} ${ms.toFixed(2)}ms rows=${rows}`,
+      { event: "db.query", stmt: label, ms: Math.round(ms * 100) / 100, rows },
+      "pino"
+    );
+  }
+}
+function rowsOf(method, result) {
+  if (method === "all") return Array.isArray(result) ? result.length : 0;
+  if (method === "run") return result?.changes ?? 0;
+  return result === void 0 ? 0 : 1;
+}
+function instrumentDatabase(db, options = {}) {
+  const slowMs = options.slowMs ?? resolveSlowMs();
+  const prepare = db.prepare.bind(db);
+  db.prepare = ((sql) => {
+    const stmt = prepare(sql);
+    const box = { label: deriveLabel(sql) };
+    Object.defineProperty(stmt, LABEL, { value: box, configurable: true });
+    for (const method of ["get", "all", "run"]) {
+      const original = stmt[method].bind(stmt);
+      Object.defineProperty(stmt, method, {
+        configurable: true,
+        writable: true,
+        value: (...args) => {
+          const started = performance.now();
+          const result = original(...args);
+          record(box.label, performance.now() - started, rowsOf(method, result), slowMs);
+          return result;
+        }
+      });
+    }
+    return stmt;
+  });
+  return db;
+}
+function labelStatements(statements) {
+  for (const [name, stmt] of Object.entries(statements)) {
+    const box = stmt?.[LABEL];
+    if (box) box.label = name;
+  }
+}
+
 // src/db/sqlite-migrate.ts
 import { readdirSync as readdirSync2, readFileSync as readFileSync7 } from "fs";
 import { dirname as dirname6, join as join12 } from "path";
@@ -5519,6 +6061,7 @@ CREATE TABLE IF NOT EXISTS session_names (
   updated_at  INTEGER NOT NULL
 );
 `;
+var cacheLog = getLogger("cache");
 var ConversationCache = class _ConversationCache {
   db;
   tailSize;
@@ -5748,6 +6291,7 @@ var ConversationCache = class _ConversationCache {
         "SELECT COUNT(*) as cnt FROM conversation_message_index WHERE conversation_id = ?"
       )
     };
+    labelStatements(this.stmts);
   }
   /**
    * Expose the underlying handle so projects/cache_metadata repositories can
@@ -5911,6 +6455,7 @@ var ConversationCache = class _ConversationCache {
     return walk;
   }
   async runBackfill(filePath) {
+    const startedAt = performance.now();
     const convId = _ConversationCache.conversationIdForFile(filePath);
     this.deleteFileIndex(filePath, convId);
     this.indexParseState.delete(filePath);
@@ -5971,6 +6516,18 @@ var ConversationCache = class _ConversationCache {
       last_message_index: nextIndex - 1
     });
     this.indexParseState.set(filePath, state);
+    const ms = Math.round(performance.now() - startedAt);
+    cacheLog.info(
+      `[cache] offset-index backfilled ${convId} ${ms}ms`,
+      {
+        event: "offset_index.backfill_ok",
+        conversationId: convId,
+        ms,
+        rows: nextIndex,
+        bytes: stat3.size
+      },
+      "pino"
+    );
   }
   /**
    * Windowed detail read straight from the offset index — the hot path.
@@ -6056,7 +6613,7 @@ var ConversationCache = class _ConversationCache {
   }
   static open(dbPath, tailSize = 10, migrationsDir, options) {
     mkdirSync3(dirname7(dbPath), { recursive: true });
-    const db = new Database(dbPath);
+    const db = instrumentDatabase(new Database(dbPath));
     db.pragma("journal_mode = WAL");
     db.pragma("foreign_keys = ON");
     return new _ConversationCache(db, tailSize, migrationsDir, options);
@@ -7068,7 +7625,7 @@ var RuntimeStore = class _RuntimeStore {
   }
   db;
   static open(dbPath, migrationsDir) {
-    const db = new Database2(dbPath);
+    const db = instrumentDatabase(new Database2(dbPath));
     db.pragma("journal_mode = WAL");
     runSqliteMigrations(db, migrationsDir ?? resolveMigrationsDir("runtime-migrations"));
     return new _RuntimeStore(db);
@@ -7200,14 +7757,14 @@ var PairTokenStore = class {
     };
   }
   consume(token) {
-    const record = this.current;
-    if (!record || record.token !== token) return { ok: false, reason: "unknown" };
-    if (Date.now() > record.expiresAt) {
+    const record2 = this.current;
+    if (!record2 || record2.token !== token) return { ok: false, reason: "unknown" };
+    if (Date.now() > record2.expiresAt) {
       this.current = null;
       return { ok: false, reason: "expired" };
     }
-    if (record.used) return { ok: false, reason: "used" };
-    record.used = true;
+    if (record2.used) return { ok: false, reason: "used" };
+    record2.used = true;
     return { ok: true };
   }
   peek() {
@@ -7228,6 +7785,88 @@ var PairTokenStore = class {
   }
 };
 
+// src/pty-host/spawn-host.ts
+import { spawn as spawn2 } from "child_process";
+
+// src/pty-host/socket.ts
+import { createConnection, createServer } from "net";
+import { homedir as homedir7 } from "os";
+import { join as join14 } from "path";
+function hostSocketPath(instanceId) {
+  if (process.platform === "win32") {
+    return `\\\\.\\pipe\\threadbase-pty-host-${instanceId}`;
+  }
+  const dir = process.env.THREADBASE_CONFIG_DIR ?? join14(homedir7(), ".threadbase");
+  return join14(dir, "run", `pty-host-${instanceId}.sock`);
+}
+function socketTransport(socket) {
+  socket.setEncoding("utf8");
+  return {
+    send(line) {
+      socket.write(line);
+    },
+    onLine(handler) {
+      socket.on("data", (chunk) => handler(chunk));
+    },
+    onClose(handler) {
+      let handled = false;
+      const handleClose = () => {
+        if (handled) return;
+        handled = true;
+        handler();
+      };
+      socket.once("close", handleClose);
+      socket.once("error", handleClose);
+    },
+    close() {
+      socket.destroy();
+    }
+  };
+}
+function connectToHost(socketPath) {
+  return new Promise((resolve2, reject) => {
+    const socket = createConnection(socketPath);
+    socket.once("error", reject);
+    socket.once("connect", () => {
+      socket.removeListener("error", reject);
+      resolve2(socketTransport(socket));
+    });
+  });
+}
+
+// src/pty-host/spawn-host.ts
+var HOST_READY_TIMEOUT_MS = 5e3;
+var HOST_POLL_INTERVAL_MS = 50;
+async function connectOrSpawnHost(options) {
+  const socketPath = hostSocketPath(options.instanceId);
+  try {
+    return await connectToHost(socketPath);
+  } catch {
+  }
+  spawnDetachedHost(socketPath, options.entryPoint);
+  const deadline = Date.now() + (options.timeoutMs ?? HOST_READY_TIMEOUT_MS);
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      return await connectToHost(socketPath);
+    } catch (err) {
+      lastError = err;
+      await new Promise((r) => setTimeout(r, HOST_POLL_INTERVAL_MS));
+    }
+  }
+  throw new Error(
+    `pty-host did not accept a connection on ${socketPath} within ${options.timeoutMs ?? HOST_READY_TIMEOUT_MS}ms` + (lastError instanceof Error ? `: ${lastError.message}` : "")
+  );
+}
+function spawnDetachedHost(socketPath, entryPoint) {
+  const child = spawn2(
+    process.execPath,
+    [entryPoint ?? process.argv[1], "pty-host", "--socket", socketPath],
+    { detached: true, stdio: "ignore" }
+  );
+  child.unref();
+}
+
 // src/seal.ts
 import nacl from "tweetnacl";
 import naclUtil from "tweetnacl-util";
@@ -7263,11 +7902,11 @@ import { existsSync as existsSync9 } from "fs";
 
 // src/services/cache-integrity/alertStore.ts
 import { mkdirSync as mkdirSync4, readFileSync as readFileSync8, writeFileSync as writeFileSync3 } from "fs";
-import { homedir as homedir7 } from "os";
-import { dirname as dirname8, join as join14 } from "path";
+import { homedir as homedir8 } from "os";
+import { dirname as dirname8, join as join15 } from "path";
 function alertStatePath() {
-  const dir = process.env.THREADBASE_CONFIG_DIR ?? join14(homedir7(), ".threadbase");
-  return join14(dir, "cache-alert.json");
+  const dir = process.env.THREADBASE_CONFIG_DIR ?? join15(homedir8(), ".threadbase");
+  return join15(dir, "cache-alert.json");
 }
 function loadAlertState() {
   try {
@@ -7286,7 +7925,7 @@ function saveAlertState(state) {
 
 // src/services/cache-integrity/backup.ts
 import { existsSync as existsSync8, mkdirSync as mkdirSync5, readdirSync as readdirSync4, statSync as statSync5, unlinkSync } from "fs";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 var DEFAULT_RETAIN = 3;
 function retainCount() {
   const parsed = Number.parseInt(process.env.THREADBASE_CACHE_BACKUP_RETAIN ?? "", 10);
@@ -7297,13 +7936,13 @@ function timestamp(d) {
   return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
 }
 async function backupCacheDb(db, cacheDir) {
-  const backupsDir = join15(cacheDir, "backups");
+  const backupsDir = join16(cacheDir, "backups");
   mkdirSync5(backupsDir, { recursive: true });
-  const destPath = join15(backupsDir, `cache-${timestamp(/* @__PURE__ */ new Date())}.db`);
+  const destPath = join16(backupsDir, `cache-${timestamp(/* @__PURE__ */ new Date())}.db`);
   await db.backup(destPath);
   const retain = retainCount();
   const backups = readdirSync4(backupsDir).filter((f) => f.startsWith("cache-") && f.endsWith(".db")).map((f) => {
-    const full = join15(backupsDir, f);
+    const full = join16(backupsDir, f);
     return { full, mtime: statSync5(full).mtimeMs };
   }).sort((a, b) => b.mtime - a.mtime);
   for (const stale of backups.slice(retain)) {
@@ -7326,10 +7965,10 @@ function fingerprintOf(ids) {
   return `sha256:${createHash3("sha256").update(sorted.join("\n")).digest("hex")}`;
 }
 var CacheIntegrityMonitor = class {
-  constructor(cache, wsHub, log7, cacheDir, rescan, runDuringReset) {
+  constructor(cache, wsHub, log8, cacheDir, rescan, runDuringReset) {
     this.cache = cache;
     this.wsHub = wsHub;
-    this.log = log7;
+    this.log = log8;
     this.cacheDir = cacheDir;
     this.rescan = rescan;
     this.runDuringReset = runDuringReset;
@@ -7887,9 +8526,9 @@ function refreshConversationCache(deps) {
 
 // src/services/conversations/shouldRefreshProjectsFromHdd.ts
 import { readdirSync as readdirSync5, statSync as statSync7 } from "fs";
-import { homedir as homedir8 } from "os";
-import { join as join16 } from "path";
-var DEFAULT_PROJECTS_DIR = join16(homedir8(), ".claude", "projects");
+import { homedir as homedir9 } from "os";
+import { join as join17 } from "path";
+var DEFAULT_PROJECTS_DIR = join17(homedir9(), ".claude", "projects");
 function maxProjectsTreeMtimeMs(projectsDir) {
   let maxMs;
   try {
@@ -7901,7 +8540,7 @@ function maxProjectsTreeMtimeMs(projectsDir) {
     for (const ent of readdirSync5(projectsDir, { withFileTypes: true })) {
       if (!ent.isDirectory()) continue;
       try {
-        const childMs = statSync7(join16(projectsDir, ent.name)).mtimeMs;
+        const childMs = statSync7(join17(projectsDir, ent.name)).mtimeMs;
         if (childMs > maxMs) maxMs = childMs;
       } catch {
       }
@@ -7945,7 +8584,7 @@ function deriveProjectChatTitle(input) {
 // src/services/push/apnsClient.ts
 import { createSign } from "crypto";
 import { connect, constants } from "http2";
-var log3 = getLogger("apns");
+var log4 = getLogger("apns");
 var APNS_HOST_SANDBOX = "api.sandbox.push.apple.com";
 var APNS_MAX_PAYLOAD_BYTES = 4096;
 var JWT_TTL_SECONDS = 3e3;
@@ -8029,7 +8668,7 @@ var ApnsClient = class {
     }
     const session = connect(`https://${this.creds.host}`);
     session.on("error", (err) => {
-      log3.warn("apns.session_error", { event: "apns.session_error", err: String(err) });
+      log4.warn("apns.session_error", { event: "apns.session_error", err: String(err) });
     });
     this.session = session;
     return session;
@@ -8114,7 +8753,7 @@ function truncateLastOutput(raw) {
 }
 
 // src/services/push/liveActivityNotifier.ts
-var log4 = getLogger("live-activity");
+var log5 = getLogger("live-activity");
 function contentStateForSession(args) {
   const status = toLiveActivityStatus(args.session.status);
   if (!status) return null;
@@ -8174,7 +8813,7 @@ var LiveActivityNotifier = class {
       }
       await this.maybeSendName(session);
     } catch (err) {
-      log4.error("live_activity.notify_failed", {
+      log5.error("live_activity.notify_failed", {
         event: "live_activity.notify_failed",
         sessionId: session.id,
         status: session.status,
@@ -8196,7 +8835,7 @@ var LiveActivityNotifier = class {
     });
     this.openActivity.set(session.id, { sessionNameSent: session.sessionName != null });
     if (outcome.attempted > 0) {
-      log4.info("live_activity.updated", {
+      log5.info("live_activity.updated", {
         event: "live_activity.updated",
         sessionId: session.id,
         status: contentState.status,
@@ -8220,7 +8859,7 @@ var LiveActivityNotifier = class {
     });
     open2.sessionNameSent = true;
     if (outcome.attempted > 0) {
-      log4.info("live_activity.updated", {
+      log5.info("live_activity.updated", {
         event: "live_activity.updated",
         sessionId: session.id,
         status: contentState.status,
@@ -8239,7 +8878,7 @@ var LiveActivityNotifier = class {
     if (!contentState) return;
     const outcome = await this.sender.end({ sessionId: session.id, contentState });
     if (outcome.attempted > 0) {
-      log4.info("live_activity.ended", {
+      log5.info("live_activity.ended", {
         event: "live_activity.ended",
         sessionId: session.id,
         ...outcome
@@ -8253,7 +8892,7 @@ var LiveActivityNotifier = class {
 };
 
 // src/services/push/liveActivitySender.ts
-var log5 = getLogger("live-activity");
+var log6 = getLogger("live-activity");
 var ACTIVITY_MAX_LIFETIME_MS = 8 * 60 * 60 * 1e3;
 function buildActivityKitPayload(args) {
   return {
@@ -8317,7 +8956,7 @@ var LiveActivitySender = class {
     );
     for (const { row, result, error } of results) {
       if (error) {
-        log5.error("live_activity.send_failed", {
+        log6.error("live_activity.send_failed", {
           event: "live_activity.send_failed",
           sessionId: args.sessionId,
           activityId: row.activity_id,
@@ -8338,7 +8977,7 @@ var LiveActivitySender = class {
         this.repo.expire(row.token, now);
         outcome.retired += 1;
       }
-      log5.warn("live_activity.send_rejected", {
+      log6.warn("live_activity.send_rejected", {
         event: "live_activity.send_rejected",
         sessionId: args.sessionId,
         activityId: row.activity_id,
@@ -8383,7 +9022,7 @@ var LiveActivitySender = class {
 };
 
 // src/services/push/liveActivityRenewal.ts
-var log6 = getLogger("live-activity");
+var log7 = getLogger("live-activity");
 var RENEWAL_LEAD_MS = 30 * 60 * 1e3;
 var MAX_TIMER_MS = 60 * 60 * 1e3;
 function renewalDueAt(row) {
@@ -8431,7 +9070,7 @@ var LiveActivityRenewalScheduler = class {
         await this.renew(row, now);
       }
     } catch (err) {
-      log6.error("live_activity.renewal_sweep_failed", {
+      log7.error("live_activity.renewal_sweep_failed", {
         event: "live_activity.renewal_sweep_failed",
         err: String(err)
       });
@@ -8460,7 +9099,7 @@ var LiveActivityRenewalScheduler = class {
     if (!session || !status) {
       this.deps.repo.claimRenewal(row.token, now);
       this.deps.repo.expire(row.token, now);
-      log6.info("live_activity.renewal_skipped", {
+      log7.info("live_activity.renewal_skipped", {
         event: "live_activity.renewal_skipped",
         sessionId: row.session_id,
         activityId: row.activity_id,
@@ -8495,7 +9134,7 @@ var LiveActivityRenewalScheduler = class {
         startedAt,
         now
       });
-      log6.info("live_activity.renewed", {
+      log7.info("live_activity.renewed", {
         event: "live_activity.renewed",
         sessionId: session.id,
         activityId: row.activity_id,
@@ -8505,7 +9144,7 @@ var LiveActivityRenewalScheduler = class {
         replacementRequested: started
       });
     } catch (err) {
-      log6.error("live_activity.renewal_failed", {
+      log7.error("live_activity.renewal_failed", {
         event: "live_activity.renewal_failed",
         sessionId: session.id,
         activityId: row.activity_id,
@@ -8996,6 +9635,12 @@ var SessionStore = class {
   removeManaged(sessionId) {
     return this.managed.delete(sessionId);
   }
+  /**
+   * The **live** stored record — mutating it mutates the store. Paired with
+   * `get()`, which hands back a throwaway response copy. Prefer
+   * `updateManaged()` for writes; this is for readers that need the internal
+   * shape (Date fields, `rehydrated`, …) rather than the wire shape.
+   */
   getManaged(sessionId) {
     return this.managed.get(sessionId) ?? null;
   }
@@ -9005,12 +9650,21 @@ var SessionStore = class {
       this.discovered.set(proc.pid, proc);
     }
   }
+  /**
+   * The **live** stored records — mutating an element mutates the store. Paired
+   * with `list()`, which hands back throwaway response copies.
+   */
   listManaged() {
     return Array.from(this.managed.values());
   }
   // Build the session list: live PTY sessions (managed) merged with externally
   // discovered Claude processes. Managed sessions keyed by JSONL UUID take
   // priority — discovered processes with the same UUID are skipped.
+  //
+  // Returns freshly constructed response objects, NOT references into the
+  // store — hence `Readonly`: writing to one changes nothing, so the compiler
+  // refuses it. Persist state with `updateManaged()`; to decorate a response,
+  // build a new object (`{ ...s, … }`) as `withReconciledLifecycle` does.
   list(ptyAttachedIds) {
     const results = [];
     const seenIds = /* @__PURE__ */ new Set();
@@ -9026,6 +9680,9 @@ var SessionStore = class {
     }
     return results;
   }
+  // A freshly constructed response object, NOT a reference into the store —
+  // hence `Readonly`, for the same reason as `list()` above. Use `getManaged()`
+  // when you want the live record.
   get(sessionId, ptyAttachedIds) {
     const managed = this.managed.get(sessionId);
     if (managed) return managedToResponse(managed, ptyAttachedIds.has(sessionId));
@@ -9117,8 +9774,8 @@ function managedToResponse(s, ptyAttached) {
     // behind it — `resumable`, and `historical` rather than `managed`
     // (docs/plans/live-sessions-persistence-plan.md §4, Phase 1).
     lifecycle: ptyAttached ? "attached" : s.rehydrated ? "resumable" : s.failureReason != null ? "failed" : "completed",
-    lifecycleSource: ptyAttached ? "spawn" : s.rehydrated ? "reconcile" : "exit",
-    // We spawned it, so `status` is the authoritative signal — no inferred
+    lifecycleSource: ptyAttached ? s.reconciled ? "reconcile" : "spawn" : s.rehydrated ? "reconcile" : "exit",
+    // We own its PTY, so `status` is the authoritative signal — no inferred
     // `activity` is attached for managed sessions.
     ownership: s.rehydrated ? "historical" : "managed",
     projectPath: s.projectPath,
@@ -9193,7 +9850,7 @@ function discoveredToResponse(d, conversationId) {
 import { randomBytes as randomBytes4 } from "crypto";
 import { mkdir as mkdir3, writeFile } from "fs/promises";
 import heicConvert from "heic-convert";
-import { join as join17 } from "path";
+import { join as join18 } from "path";
 var UPLOAD_DIR_NAME = ".threadbase-uploads";
 var MAX_BYTES = 25 * 1024 * 1024;
 var HEIC_MIMES = /* @__PURE__ */ new Set(["image/heic", "image/heif"]);
@@ -9226,9 +9883,9 @@ async function saveUploadFile(input) {
   }
   const id = `up_${randomBytes4(8).toString("hex")}`;
   const safeName = sanitizeFilename(originalName) || `file${MIME_TO_EXT[mimeType] ?? ""}`;
-  const dir = join17(input.projectPath, UPLOAD_DIR_NAME, input.sessionId);
+  const dir = join18(input.projectPath, UPLOAD_DIR_NAME, input.sessionId);
   await mkdir3(dir, { recursive: true });
-  const filePath = join17(dir, `${Date.now()}-${id}-${safeName}`);
+  const filePath = join18(dir, `${Date.now()}-${id}-${safeName}`);
   await writeFile(filePath, buffer);
   return {
     id,
@@ -9770,7 +10427,7 @@ var StreamerServer = class {
     this.autoResumeOnBoot = config.autoResumeOnBoot ?? false;
     this.scannerPersistenceDisabled = config.scannerPersistent === false;
     this.scanProfiles = config.scanProfiles;
-    this.codexRoots = config.codexRoots ?? [join18(homedir9(), ".codex", "sessions")];
+    this.codexRoots = config.codexRoots ?? [join19(homedir10(), ".codex", "sessions")];
     this.ptyGracePeriodMs = config.ptyGracePeriodMs ?? DEFAULT_PTY_GRACE_PERIOD_MS;
     this.defaultSystemPrompt = config.defaultSystemPrompt ?? DEFAULT_SYSTEM_PROMPT;
     this.featureFlags = resolveFeatureFlags({ cli: config.featureFlags, yaml: loadFeatureFlags() });
@@ -9784,8 +10441,8 @@ var StreamerServer = class {
     this.claudeFlagsPersistable = config.claudeFlags === void 0;
     this.claudeFlags = config.claudeFlags ?? loadClaudeFlags();
     this.claudeExtraArgs = config.claudeExtraArgs ?? loadClaudeExtraArgs();
-    this.cacheDir = config.cacheDir ?? loadCacheDir() ?? join18(homedir9(), ".threadbase", "cache");
-    this.runtimeDbPath = config.runtimeDbPath ?? process.env.THREADBASE_RUNTIME_DB ?? join18(process.env.THREADBASE_CONFIG_DIR ?? join18(homedir9(), ".threadbase"), "runtime.db");
+    this.cacheDir = config.cacheDir ?? loadCacheDir() ?? join19(homedir10(), ".threadbase", "cache");
+    this.runtimeDbPath = config.runtimeDbPath ?? process.env.THREADBASE_RUNTIME_DB ?? join19(process.env.THREADBASE_CONFIG_DIR ?? join19(homedir10(), ".threadbase"), "runtime.db");
     this.tailSize = config.tailSize ?? loadTailSize() ?? 10;
     this.directoryDebounceMs = parseDirScanDebounceEnv(process.env.THREADBASE_DIR_SCAN_DEBOUNCE_MS) ?? config.directoryScanDebounceMs ?? 1e3;
     this.markScannerStaleDebounced = debounce(() => {
@@ -10041,7 +10698,7 @@ var StreamerServer = class {
         temporalClient,
         taskQueue: agentConfig.temporal.taskQueue
       });
-      const conversationsBaseDir = agentConfig.conversationsDir || join18(dirname9(this.cacheDir), "conversations");
+      const conversationsBaseDir = agentConfig.conversationsDir || join19(dirname9(this.cacheDir), "conversations");
       conversationWriter = createConversationWriter({
         baseDir: conversationsBaseDir
       });
@@ -10194,7 +10851,7 @@ var StreamerServer = class {
       conversationWriter,
       agentConfig
     };
-    this.httpServer = createServer((req, res) => this.handleRequest(req, res));
+    this.httpServer = createServer2((req, res) => this.handleRequest(req, res));
     this.httpServer.on("clientError", (_err, socket) => {
       try {
         socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
@@ -10348,7 +11005,7 @@ var StreamerServer = class {
     if (!this.managedSessionsRepo) return [];
     let verdicts = [];
     try {
-      const rows = this.managedSessionsRepo.listNonTerminal();
+      const rows = this.managedSessionsRepo.listNonTerminal().filter((row) => !this.ptyManager.hasSession(row.session_id));
       if (rows.length === PROBE_SET_MAX) {
         this.log.warn(
           `[reconcile] probe set hit its cap of ${PROBE_SET_MAX} \u2014 older rows skipped`,
@@ -10595,6 +11252,26 @@ var StreamerServer = class {
     if (session.provider !== CODEX_CLI_PROVIDER) return session.id;
     return session.boundConversationId ?? session.projectPath;
   }
+  /** Restore registry-only metadata after the host mirror has been adopted. */
+  refreshHostedSessionsFromRegistry() {
+    for (const session of this.ptyManager.listSessions()) {
+      const row = this.managedSessionsRepo?.get(session.id);
+      const merged = {
+        ...session,
+        reconciled: true,
+        ...row?.project_id != null && { projectId: row.project_id },
+        ...row?.session_name != null && { sessionName: row.session_name },
+        ...row?.bound_conversation_id != null && {
+          boundConversationId: row.bound_conversation_id
+        },
+        ...row?.resumed_from_conversation_id != null && {
+          resumedFromConversationId: row.resumed_from_conversation_id
+        }
+      };
+      this.sessionStore.addManaged(merged);
+      void this.watchConversationFile(session.id, merged.boundConversationId ?? session.id);
+    }
+  }
   /**
    * Mirror a freshly-spawned session into the durable registry (C1 Phase 2).
    *
@@ -10690,6 +11367,7 @@ var StreamerServer = class {
    * of waiting on the interval.
    */
   reapIdleSessions(now = Date.now()) {
+    if (this.ptyManager.isRemote()) return [];
     const reaped = [];
     for (const session of this.ptyManager.listSessions()) {
       if (session.status === "running") continue;
@@ -10791,6 +11469,40 @@ var StreamerServer = class {
     return true;
   }
   async listen(port, opts) {
+    if (this.featureFlags.ptyHost) {
+      try {
+        let sessions = null;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+          const transport = await connectOrSpawnHost({
+            instanceId: process.env.THREADBASE_INSTANCE_ID ?? hostname3()
+          });
+          try {
+            sessions = await this.ptyManager.useRemoteRunner(transport);
+            break;
+          } catch (err) {
+            if (!(err instanceof PtyHostProtocolMismatchError) || attempt > 0) throw err;
+            this.log.info(`[pty-host] replaced incompatible protocol ${err.hostVersion}`, {
+              event: "pty_host.protocol_replaced",
+              hostVersion: err.hostVersion,
+              streamerVersion: err.streamerVersion
+            });
+          }
+        }
+        if (!sessions) throw new Error("pty-host replacement did not produce a compatible host");
+        for (const session of sessions) {
+          this.sessionStore.addManaged({ ...session, reconciled: true });
+        }
+        this.log.info(`[pty-host] re-adopted ${sessions.length} live session(s)`, {
+          event: "pty_host.sessions_adopted",
+          sessions: sessions.length
+        });
+      } catch (err) {
+        this.log.error(
+          "[pty-host] could not attach; falling back to in-process PTYs for this run",
+          { event: "pty_host.attach_failed", err }
+        );
+      }
+    }
     const dbConfig = this.disableDb ? null : getDbConfig();
     if (dbConfig) {
       this.dbPool = await createPool(dbConfig);
@@ -10805,8 +11517,10 @@ var StreamerServer = class {
       this.log.info("Database migrations applied", { event: "db.migrations_applied" });
     }
     await this.bindWithRetry(port);
-    this.idleReaperTimer = setInterval(() => this.reapIdleSessions(), IDLE_REAP_SWEEP_MS);
-    this.idleReaperTimer.unref?.();
+    if (!this.ptyManager.isRemote()) {
+      this.idleReaperTimer = setInterval(() => this.reapIdleSessions(), IDLE_REAP_SWEEP_MS);
+      this.idleReaperTimer.unref?.();
+    }
     const warmUp = new Promise((resolveWarm) => {
       {
         this.log.info(`Streamer server listening on port ${port}`, {
@@ -10824,9 +11538,18 @@ var StreamerServer = class {
             { error: message, abiMismatch, path: this.runtimeDbPath, event: "runtime.open_failed" }
           );
         }
+        if (this.ptyManager.isRemote()) {
+          this.ptyManager.startRemoteHeartbeat(() => {
+            if (!this.managedSessionsRepo) {
+              return { registryState: "unknown", referencedSessionIds: [] };
+            }
+            const referencedSessionIds = this.ptyManager.listSessions().filter((session) => this.managedSessionsRepo?.get(session.id)?.completed_at == null).map((session) => session.id);
+            return { registryState: "known", referencedSessionIds };
+          });
+        }
         try {
           this.cache = ConversationCache.open(
-            join18(this.cacheDir, "cache.db"),
+            join19(this.cacheDir, "cache.db"),
             this.tailSize,
             void 0,
             {
@@ -10900,6 +11623,7 @@ var StreamerServer = class {
           );
           this.scannerPersistenceDisabled = true;
         }
+        if (this.ptyManager.isRemote()) this.refreshHostedSessionsFromRegistry();
         void this.reconcilePreviousSessions().then(async (v) => {
           const recoverableRows = this.rehydratePreviousSessions(v);
           await this.autoResumePreviousSessions(recoverableRows);
@@ -11105,7 +11829,8 @@ var StreamerServer = class {
     }
     this.lastAgentChunkAt.clear();
     this.terminalSeq.clear();
-    this.recordShutdownState();
+    if (this.ptyManager.isRemote()) this.ptyManager.dispose();
+    else this.recordShutdownState();
     this.markScannerStaleDebounced.cancel();
     await Promise.all([...this.inFlightCacheWrites]);
     await Promise.all([...this.allScanners].map((s) => s.close()));
@@ -11113,7 +11838,7 @@ var StreamerServer = class {
     this.scanner = null;
     this.cache?.close();
     this.runtimeStore?.close();
-    this.ptyManager.dispose();
+    if (!this.ptyManager.isRemote()) this.ptyManager.dispose();
     this.fileWatcher.dispose();
     this.externalTails.clear();
     this.wsHub.dispose();
@@ -11339,9 +12064,9 @@ var StreamerServer = class {
   /** Project roots watched for conversation JSONLs (profiles or ~/.claude/projects). */
   projectsDirsForFreshnessCheck() {
     if (this.scanProfiles && this.scanProfiles.length > 0) {
-      return this.scanProfiles.filter((p) => p.enabled).map((p) => join18(p.configDir, "projects"));
+      return this.scanProfiles.filter((p) => p.enabled).map((p) => join19(p.configDir, "projects"));
     }
-    return [join18(homedir9(), ".claude", "projects")];
+    return [join19(homedir10(), ".claude", "projects")];
   }
   /**
    * Full-glob scan + cache upsert/delete reconcile. Used by ?refresh=1 and by
@@ -11742,21 +12467,21 @@ var StreamerServer = class {
    */
   projectsDirs() {
     if (this.scanProfiles && this.scanProfiles.length > 0) {
-      return this.scanProfiles.filter((p) => p.enabled).map((p) => join18(p.configDir, "projects"));
+      return this.scanProfiles.filter((p) => p.enabled).map((p) => join19(p.configDir, "projects"));
     }
-    return [join18(homedir9(), ".claude", "projects")];
+    return [join19(homedir10(), ".claude", "projects")];
   }
   findJsonlPath(uuid) {
     const filename = `${uuid}.jsonl`;
     for (const projectsDir of this.projectsDirs()) {
       if (!existsSync11(projectsDir)) continue;
       for (const dir of readdirSync6(projectsDir)) {
-        const fp = join18(projectsDir, dir, filename);
+        const fp = join19(projectsDir, dir, filename);
         if (existsSync11(fp)) return fp;
-        const projectDir = join18(projectsDir, dir);
+        const projectDir = join19(projectsDir, dir);
         try {
           for (const sub of readdirSync6(projectDir)) {
-            const subagentPath = join18(projectDir, sub, "subagents", filename);
+            const subagentPath = join19(projectDir, sub, "subagents", filename);
             if (existsSync11(subagentPath)) return subagentPath;
           }
         } catch {
@@ -12163,6 +12888,16 @@ var StreamerServer = class {
       const windowStart = Math.max(0, beforeIndex - scanLimit);
       const indexWindow = scanLimit > 0 && !hasAnchor && indexFilePath && this.cache ? this.cache.readMessageWindow(indexFilePath, windowStart, beforeIndex) : null;
       if (!indexWindow && indexFilePath && this.cache && !hasAnchor) {
+        this.log.info(
+          `[server] offset-index miss ${id} \u2192 scanner fallback`,
+          {
+            event: "offset_index.miss",
+            conversationId: id,
+            fromIndex: windowStart,
+            toIndex: beforeIndex
+          },
+          "pino"
+        );
         this.trackCacheWrite(
           this.cache.backfillIndex(indexFilePath).catch((err) => {
             this.log.warn("offset-index.backfill_failed", {
@@ -12437,14 +13172,15 @@ var StreamerServer = class {
   }
   async handleGetSession(sessionId, res) {
     if (this.rejectIfWarmingUp(res)) return;
-    const session = this.sessionStore.get(sessionId, this.ptyAttachedIds());
-    if (session) {
-      if (!existsSync11(session.projectPath)) {
-        session.failureReason = `Project directory not found: ${session.projectPath}`;
-      }
-      const reconciled = this.withReconciledLifecycle([session])[0];
-      session.lifecycle = reconciled.lifecycle;
-      session.lifecycleSource = reconciled.lifecycleSource;
+    const base = this.sessionStore.get(sessionId, this.ptyAttachedIds());
+    if (base) {
+      const reconciled = this.withReconciledLifecycle([base])[0];
+      const session = {
+        ...base,
+        ...existsSync11(base.projectPath) ? {} : { failureReason: `Project directory not found: ${base.projectPath}` },
+        lifecycle: reconciled.lifecycle,
+        lifecycleSource: reconciled.lifecycleSource
+      };
       if (this.ptyManager.hasSession(sessionId)) {
         try {
           const lines = await this.ptyManager.getOutputLines(sessionId, 10);
@@ -12607,31 +13343,37 @@ var StreamerServer = class {
     this.sessionStore.addManaged(session);
     this.recordSessionSpawn(session);
     void this.watchConversationFile(sessionId, historyId);
-    const response = this.sessionStore.get(session.id, this.ptyAttachedIds());
     this.enrichResumedSessionAsync(sessionId, projectPath, conv);
+    const response = this.sessionStore.get(session.id, this.ptyAttachedIds());
     return { ok: true, alreadyRunning: false, session, response };
   }
   enrichResumedSessionAsync(sessionId, projectPath, conv) {
     try {
-      const session = this.sessionStore.get(sessionId, this.ptyAttachedIds());
-      if (!session) return;
+      if (!this.sessionStore.getManaged(sessionId)) return;
       if (conv) {
-        session.sessionName = conv.sessionName ?? void 0;
-        session.messageCount = conv.messageCount ?? 0;
-        session.account = conv.account ?? void 0;
-        session.filePath = conv.filePath ?? void 0;
+        this.sessionStore.updateManaged(sessionId, {
+          sessionName: conv.sessionName ?? void 0,
+          messageCount: conv.messageCount ?? 0,
+          account: conv.account ?? void 0,
+          filePath: conv.filePath ?? void 0
+        });
       }
       if (!this.cache || !this.projectsRepo || !this.conversationsRepo) return;
       const cached3 = this.cache.getMetaById(sessionId);
       if (cached3) {
-        session.model = cached3.model ?? void 0;
-        session.preview = cached3.preview ?? void 0;
         const first = cached3.firstMessage ? JSON.parse(cached3.firstMessage) : null;
         const last = cached3.lastMessage ? JSON.parse(cached3.lastMessage) : null;
-        session.firstMessageText = first?.text ?? void 0;
-        session.firstMessageAt = first?.timestamp ? new Date(first.timestamp).toISOString() : void 0;
-        session.lastMessageText = last?.text ?? void 0;
-        session.lastMessageAt = last?.timestamp ? new Date(last.timestamp).toISOString() : void 0;
+        this.sessionStore.updateManaged(sessionId, {
+          model: cached3.model ?? void 0,
+          preview: cached3.preview ?? void 0,
+          firstMessageText: first?.text ?? void 0,
+          // parseIsoDateOrNull, not `new Date()`: an unparseable cached
+          // timestamp must land as absent, not as an Invalid Date that
+          // managedToResponse would throw on when it calls .toISOString().
+          firstMessageAt: parseIsoDateOrNull(first?.timestamp) ?? void 0,
+          lastMessageText: last?.text ?? void 0,
+          lastMessageAt: parseIsoDateOrNull(last?.timestamp) ?? void 0
+        });
       }
       let resolvedProjectId = cached3?.projectId ?? null;
       if (!resolvedProjectId) {
@@ -12643,8 +13385,10 @@ var StreamerServer = class {
         });
       }
       if (resolvedProjectId) {
-        session.projectId = resolvedProjectId;
-        session.resumedFromConversationId = sessionId;
+        this.sessionStore.updateManaged(sessionId, {
+          projectId: resolvedProjectId,
+          resumedFromConversationId: sessionId
+        });
       }
     } catch (err) {
       console.error(`[enrichResumedSessionAsync] ${sessionId}:`, err);
@@ -13075,7 +13819,7 @@ var StreamerServer = class {
         sessionStore: this.sessionStore,
         // biome-ignore lint/style/noNonNullAssertion: agentClient is set when agentConfig.enabled is true
         agentClient: this.agentClient,
-        conversationsDir: this.cacheDir ? join18(dirname9(this.cacheDir), "conversations") : "",
+        conversationsDir: this.cacheDir ? join19(dirname9(this.cacheDir), "conversations") : "",
         agentConfig: this.agentConfig
       });
       json(res, result.status, result.body);
@@ -13239,9 +13983,9 @@ var StreamerServer = class {
   // was passed to Claude via --session-id so the filename matches from the start.
   watchForJsonl(sessionId, projectPath) {
     const encoded = projectPath.replace(/[/\\:.]/g, "-");
-    const projectsDir = join18(homedir9(), ".claude", "projects", encoded);
+    const projectsDir = join19(homedir10(), ".claude", "projects", encoded);
     const expectedFile = `${sessionId}.jsonl`;
-    const filePath = join18(projectsDir, expectedFile);
+    const filePath = join19(projectsDir, expectedFile);
     const deadline = Date.now() + 12e4;
     let watcher = null;
     const cleanup = () => {
@@ -13263,10 +14007,10 @@ var StreamerServer = class {
       if (!resolvedFilePath && existsSync11(projectsDir)) {
         try {
           const now = Date.now();
-          const match = readdirSync6(projectsDir).filter((f) => f.endsWith(".jsonl")).map((f) => ({ f, mtime: statSync9(join18(projectsDir, f)).mtimeMs })).filter(({ mtime }) => now - mtime < 5e3).filter(
-            ({ f }) => basename5(f, ".jsonl") === sessionId || this.readFirstLineSessionId(join18(projectsDir, f)) === sessionId
+          const match = readdirSync6(projectsDir).filter((f) => f.endsWith(".jsonl")).map((f) => ({ f, mtime: statSync9(join19(projectsDir, f)).mtimeMs })).filter(({ mtime }) => now - mtime < 5e3).filter(
+            ({ f }) => basename5(f, ".jsonl") === sessionId || this.readFirstLineSessionId(join19(projectsDir, f)) === sessionId
           ).sort((a, b) => b.mtime - a.mtime)[0];
-          if (match) resolvedFilePath = join18(projectsDir, match.f);
+          if (match) resolvedFilePath = join19(projectsDir, match.f);
         } catch {
         }
       }
@@ -13314,7 +14058,7 @@ var StreamerServer = class {
   watchForCodexRollout(sessionId, projectPath) {
     const deadline = Date.now() + 12e4;
     const now = /* @__PURE__ */ new Date();
-    const dateDir = join18(
+    const dateDir = join19(
       String(now.getFullYear()),
       String(now.getMonth() + 1).padStart(2, "0"),
       String(now.getDate()).padStart(2, "0")
@@ -13355,7 +14099,7 @@ var StreamerServer = class {
         this.sessionStore.listManaged().filter((s) => s.id !== sessionId && s.boundConversationId != null).map((s) => s.boundConversationId)
       );
       for (const root of this.codexRoots) {
-        const sessionsDir = join18(root, dateDir);
+        const sessionsDir = join19(root, dateDir);
         if (!existsSync11(sessionsDir)) continue;
         let candidateFiles;
         try {
@@ -13364,9 +14108,9 @@ var StreamerServer = class {
           continue;
         }
         const nowMs = Date.now();
-        const recentCandidates = candidateFiles.map((f) => ({ f, mtime: statSync9(join18(sessionsDir, f)).mtimeMs })).filter(({ mtime }) => nowMs - mtime < 1e4).sort((a, b) => b.mtime - a.mtime);
+        const recentCandidates = candidateFiles.map((f) => ({ f, mtime: statSync9(join19(sessionsDir, f)).mtimeMs })).filter(({ mtime }) => nowMs - mtime < 1e4).sort((a, b) => b.mtime - a.mtime);
         for (const { f } of recentCandidates) {
-          const candidatePath = join18(sessionsDir, f);
+          const candidatePath = join19(sessionsDir, f);
           const match = matchesProjectPath(candidatePath);
           if (!match) continue;
           if (boundElsewhere.has(match.id)) continue;