@threadbase-sh/streamer 1.43.0 → 1.44.1

package/dist/index.cjs

@@ -154,14 +154,14 @@ function createConversationWriter(opts) {
       }
       const file = (0, import_node_path.join)(baseDir, `${args.sessionId}.jsonl`);
       await (0, import_promises.mkdir)((0, import_node_path.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 (0, import_promises.appendFile)(file, line, { encoding: "utf8" });
     }
@@ -468,6 +468,9 @@ var baseLogger = (0, import_pino.default)({
     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);
@@ -480,11 +483,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
   };
 }
@@ -506,6 +509,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) {
@@ -872,7 +881,16 @@ var import_fs3 = require("fs");
 var import_os2 = require("os");
 var import_path3 = require("path");
 var isWindows = (0, import_os2.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) {
@@ -881,7 +899,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;
@@ -931,6 +949,9 @@ function resolveClaudeExe() {
   return _claudeExe;
 }
 var _codexExe;
+function clearCodexExeCache() {
+  _codexExe = void 0;
+}
 function resolveCodexExe() {
   if (_codexExe !== void 0) return _codexExe;
   if (isWindows) {
@@ -939,7 +960,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;
@@ -1199,20 +1220,26 @@ var CodexPtyRunner = class {
   async doStart(sessionId, options) {
     const nodePty = await loadPty();
     const projectName = options.projectName ?? (0, import_path5.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,
@@ -1255,13 +1282,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,
@@ -1736,6 +1769,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
 var import_headless2 = require("@xterm/headless");
 var import_crypto3 = require("crypto");
@@ -2107,13 +2515,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,
@@ -2168,13 +2582,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,
@@ -2740,12 +3160,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);
@@ -2766,7 +3204,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);
     }
   }
@@ -2776,13 +3214,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);
     }
   }
@@ -2796,7 +3234,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;
     }
@@ -2806,23 +3244,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();
     }
   }
@@ -2830,12 +3268,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(
@@ -2844,6 +3283,9 @@ var LiveSessionManager = class {
     err.statusCode = 501;
     throw err;
   }
+  activeRunners() {
+    return this.remoteRunner ? [this.remoteRunner] : [...this.runners.values()];
+  }
 };
 
 // src/process-discovery.ts
@@ -5244,21 +5686,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 import_hono18.Hono();
   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"
     });
   });
@@ -5346,6 +5820,74 @@ var import_promises3 = require("fs/promises");
 var import_path12 = require("path");
 var import_promises4 = require("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
 var import_fs8 = require("fs");
 var import_path10 = require("path");
@@ -5556,6 +6098,7 @@ CREATE TABLE IF NOT EXISTS session_names (
   updated_at  INTEGER NOT NULL
 );
 `;
+var cacheLog = getLogger("cache");
 var ConversationCache = class _ConversationCache {
   db;
   tailSize;
@@ -5785,6 +6328,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
@@ -5948,6 +6492,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);
@@ -6008,6 +6553,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.
@@ -6093,7 +6650,7 @@ var ConversationCache = class _ConversationCache {
   }
   static open(dbPath, tailSize = 10, migrationsDir, options) {
     (0, import_fs10.mkdirSync)((0, import_path12.dirname)(dbPath), { recursive: true });
-    const db = new import_better_sqlite3.default(dbPath);
+    const db = instrumentDatabase(new import_better_sqlite3.default(dbPath));
     db.pragma("journal_mode = WAL");
     db.pragma("foreign_keys = ON");
     return new _ConversationCache(db, tailSize, migrationsDir, options);
@@ -7105,7 +7662,7 @@ var RuntimeStore = class _RuntimeStore {
   }
   db;
   static open(dbPath, migrationsDir) {
-    const db = new import_better_sqlite32.default(dbPath);
+    const db = instrumentDatabase(new import_better_sqlite32.default(dbPath));
     db.pragma("journal_mode = WAL");
     runSqliteMigrations(db, migrationsDir ?? resolveMigrationsDir("runtime-migrations"));
     return new _RuntimeStore(db);
@@ -7237,14 +7794,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() {
@@ -7265,6 +7822,88 @@ var PairTokenStore = class {
   }
 };
 
+// src/pty-host/spawn-host.ts
+var import_node_child_process2 = require("child_process");
+
+// src/pty-host/socket.ts
+var import_node_net = require("net");
+var import_node_os4 = require("os");
+var import_node_path7 = require("path");
+function hostSocketPath(instanceId) {
+  if (process.platform === "win32") {
+    return `\\\\.\\pipe\\threadbase-pty-host-${instanceId}`;
+  }
+  const dir = process.env.THREADBASE_CONFIG_DIR ?? (0, import_node_path7.join)((0, import_node_os4.homedir)(), ".threadbase");
+  return (0, import_node_path7.join)(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 = (0, import_node_net.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 = (0, import_node_child_process2.spawn)(
+    process.execPath,
+    [entryPoint ?? process.argv[1], "pty-host", "--socket", socketPath],
+    { detached: true, stdio: "ignore" }
+  );
+  child.unref();
+}
+
 // src/seal.ts
 var import_tweetnacl = __toESM(require("tweetnacl"), 1);
 var import_tweetnacl_util = __toESM(require("tweetnacl-util"), 1);
@@ -7363,10 +8002,10 @@ function fingerprintOf(ids) {
   return `sha256:${(0, import_crypto9.createHash)("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;
@@ -7982,7 +8621,7 @@ function deriveProjectChatTitle(input) {
 // src/services/push/apnsClient.ts
 var import_node_crypto3 = require("crypto");
 var import_node_http2 = require("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;
@@ -8066,7 +8705,7 @@ var ApnsClient = class {
     }
     const session = (0, import_node_http2.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;
@@ -8151,7 +8790,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;
@@ -8211,7 +8850,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,
@@ -8233,7 +8872,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,
@@ -8257,7 +8896,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,
@@ -8276,7 +8915,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
@@ -8290,7 +8929,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 {
@@ -8354,7 +8993,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,
@@ -8375,7 +9014,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,
@@ -8420,7 +9059,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) {
@@ -8468,7 +9107,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)
       });
@@ -8497,7 +9136,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,
@@ -8532,7 +9171,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,
@@ -8542,7 +9181,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,
@@ -9033,6 +9672,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;
   }
@@ -9042,12 +9687,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();
@@ -9063,6 +9717,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));
@@ -9154,8 +9811,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,
@@ -10385,7 +11042,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`,
@@ -10632,6 +11289,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).
    *
@@ -10727,6 +11404,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;
@@ -10828,6 +11506,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 ?? (0, import_os10.hostname)()
+          });
+          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);
@@ -10842,8 +11554,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}`, {
@@ -10861,6 +11575,15 @@ 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(
             (0, import_path18.join)(this.cacheDir, "cache.db"),
@@ -10937,6 +11660,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);
@@ -11142,7 +11866,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()));
@@ -11150,7 +11875,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();
@@ -12200,6 +12925,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", {
@@ -12474,14 +13209,15 @@ var StreamerServer = class {
   }
   async handleGetSession(sessionId, res) {
     if (this.rejectIfWarmingUp(res)) return;
-    const session = this.sessionStore.get(sessionId, this.ptyAttachedIds());
-    if (session) {
-      if (!(0, import_fs19.existsSync)(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,
+        ...(0, import_fs19.existsSync)(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);
@@ -12644,31 +13380,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) {
@@ -12680,8 +13422,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);