talon-agent 5.18.2 → 5.19.1

package/README.md

@@ -203,7 +203,7 @@ The WhatsApp frontend drives a real WhatsApp account over Baileys multi-device
     // The bot account's own number, E.164 digits, no "+". Omit for QR pairing.
     "pairingNumber": "353871234567",
     // Who may DM it — bare numbers or full JIDs. Empty disables DMs.
-    "allowedJids": ["353834733284"],
+    "allowedJids": ["447700900102"],
     // Which groups it serves: "listed" | "with-allowed-user" | "all"
     "groupPolicy": "with-allowed-user",
     // In groups: reply only when mentioned/quoted, or to everything
@@ -487,6 +487,7 @@ Config file: `~/.talon/config.json`
 | `heartbeatIntervalMinutes` | `60`         | Heartbeat interval                                                                                                      |
 | `heartbeatModel`           | ---          | Model for the heartbeat agent (falls back to `model`)                                                                   |
 | `heartbeatEffort`          | ---          | Reasoning effort for the heartbeat agent: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Unset = the model's own default |
+| `alerts`                   | on           | Operator alerts to the admin chat — full disk, crash, error spike, dead frontend — once per fault per cooldown, plus a recovery notice: `{ "enabled": true, "cooldownMinutes": 30 }`. Active alerts also show in `talon status` |
 | `router`                   | ---          | Plan-aware routing for background work: `{ "enabled": true, "ceilingPercent": 85 }`. Unpinned sub-agents, cron `query` jobs and heartbeats run on whichever backend has the most plan headroom, skipping any whose tightest window is at or above the ceiling. `enabled: false` restores inherit-the-caller's-backend ([Backends](docs/backends.md)) |
 | `backendBudgets`           | ---          | Soft token budgets for backends with no usage API, e.g. `{ "openai-agents": { "tokensPer5h": 2000000, "tokensPerDay": 8000000 } }`. Talon's own rolling ledger is measured against these so such a backend still has a headroom signal — and it is what opts an idle backend into routing. `agy` reports its real quota windows (via `agy -p /usage`); a budget there is only a fallback for when that read fails |
 | `dreamModel`               | ---          | Model for dream / memory consolidation (falls back to `model`)                                                          |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.18.2",
+  "version": "5.19.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",
@@ -101,7 +101,7 @@
     "build:fusefs": "node native/talon-fusefs/build.mjs"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.277",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.283",
     "@anthropic-ai/sdk": "^0.104.1",
     "@brave/brave-search-mcp-server": "^2.0.75",
     "@clack/prompts": "^1.2.0",

package/prompts/system/agent-brief.md

@@ -19,14 +19,31 @@ a useful result; silence is not.
 
 ## Talking to your parent
 
-- `check_inbox()` drains any instructions your parent has sent you. Check it
-  at natural milestones — after a phase of work, before a long operation, and
-  before you report. Messages are not delivered to you any other way.
+- `check_inbox()` drains anything sent to you — instructions from your parent
+  and notes from peers. Each message names its sender. Check it at natural
+  milestones: after a phase of work, before a long operation, and before you
+  report. Messages are not delivered to you any other way.
 - `message_parent(text)` sends an interim note (a finding worth acting on now,
   a question, a heads-up that this will take a while). Use it sparingly: each
   one wakes your parent. It does **not** end your run and does **not** count
   as your result.
 
+## Talking to your peers
+
+Your parent may have spawned others alongside you. `list_peers()` shows them —
+id, label, and what each was asked to do — and `message_peer(agent_id, text)`
+sends one of them a note directly, without going through your parent.
+
+Use it when something you found changes _their_ work and waiting would waste
+it: a fact you both need, a dead end worth not repeating, a correction to
+something you told them earlier. Don't narrate your progress at them — a peer
+pays for every message with context it could have spent on its own job.
+
+You can only address peers, and they see your note at their next
+`check_inbox`, so it is not an interrupt. Your report still goes to your
+parent: peer messages are for coordination, never a substitute for
+`report_result`.
+
 ## Delegating further
 
 {% if canSpawn %}You may spawn your own sub-agents with `spawn_agent` (current depth {{depth}}, cap {{maxDepth}}) when the work genuinely splits into independent pieces. You are then responsible for them: `wait_for_agent`, `send_to_agent`, `kill_agent`, and folding their reports into yours.{% else %}You are at the maximum sub-agent depth ({{maxDepth}}) — `spawn_agent` will be refused. Do this work yourself.{% endif %}

package/src/app.ts

@@ -42,6 +42,12 @@ import {
   handleUncaughtException,
   handleUnhandledRejection,
 } from "./core/daemon/crash.js";
+import { writeCrashMarker } from "./core/daemon/crash-marker.js";
+import {
+  announceLastCrash,
+  startHealthAlerts,
+  stopHealthAlerts,
+} from "./core/daemon/health-alerts.js";
 import { log, logError, logWarn } from "./util/log.js";
 import { bootPhase, bootReport } from "./core/daemon/boot-timer.js";
 import {
@@ -352,6 +358,7 @@ async function gracefulShutdown(signal: string): Promise<void> {
   await shutdownStep("sub-agents", shutdownAgents);
   await shutdownStep("watchdog", stopWatchdog);
   await shutdownStep("resource sampler", stopResourceSampler);
+  await shutdownStep("health alerts", stopHealthAlerts);
   await shutdownStep("upload cleanup", stopUploadCleanup);
   await shutdownStep("mcp hub", async () => {
     const { shutdownHub } = await import("./core/mcp-hub/index.js");
@@ -452,6 +459,11 @@ async function main(): Promise<void> {
       await import("./core/frontend-runtime/admin-notify.js");
     await notifyAdmin(restoreReport);
   }
+  // Same reasoning for a crash: the process that died couldn't say so,
+  // so the marker it left is announced now. The probes start here too —
+  // an alert raised before a frontend can carry it is wasted.
+  announceLastCrash();
+  startHealthAlerts();
 
   const bootMs = Math.round(process.uptime() * 1000);
   recordBootMetrics(bootMs);
@@ -465,6 +477,7 @@ async function main(): Promise<void> {
 
 main().catch((err) => {
   crashCleanup(crashHooks);
+  crashStep("crash marker", () => writeCrashMarker("startup", err));
   crashStep("startup report", () =>
     logError("bot", "Fatal startup error", err),
   );

package/src/backend/claude-sdk/handler.ts

@@ -83,10 +83,10 @@ import {
 // The SDK's PostToolBatch hook is the canonical loop-terminator — it returns
 // `{ continue: false }` after `end_turn`/`send`, and the SDK is supposed to
 // emit a `result` SDKMessage and close the async iterator immediately after.
-// In practice (observed 2026-05-19 14:52Z, chat 352042062, contextTokens=251464,
-// numApiCalls=50) the SDK can emit `result` and then ghost — the for-await loop
-// stays parked forever, holding the dispatcher context and the typing-indicator
-// pulse for hours until someone manually `/restart`s.
+// In practice (observed 2026-05-19 on a ~250k-token, 50-API-call turn) the
+// SDK can emit `result` and then ghost — the for-await loop stays parked
+// forever, holding the dispatcher context and the typing-indicator pulse for
+// hours until someone manually `/restart`s.
 //
 // Workaround: arm a short timer the moment `result` is processed. If the
 // iterator hasn't closed by the grace deadline, abort the controller and

package/src/backend/claude-sdk/mcp-ready.ts

@@ -35,9 +35,11 @@ export async function waitForMcpServersReady(
   while (Date.now() < deadline) {
     let statuses;
     try {
-      statuses = await qi.mcpServerStatus();
+      // Bound the call itself: a CLI that never answers the control
+      // request would otherwise park here past the deadline.
+      statuses = await beforeDeadline(qi.mcpServerStatus(), deadline);
     } catch {
-      return; // status query unsupported/failed — don't block the turn
+      return; // status query unsupported/failed/timed out — don't block the turn
     }
     // Best-effort: a backend (or stub) may report status in an unexpected
     // shape (undefined / non-array). Treat anything non-iterable as
@@ -52,3 +54,15 @@ export async function waitForMcpServersReady(
     await new Promise((resolve) => setTimeout(resolve, pollMs));
   }
 }
+
+/** `promise`, or a rejection once `deadline` (epoch ms) passes first. */
+function beforeDeadline<T>(promise: Promise<T>, deadline: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error("mcpServerStatus timed out")),
+      Math.max(0, deadline - Date.now()),
+    );
+  });
+  return Promise.race([promise, expired]).finally(() => clearTimeout(timer));
+}

package/src/backend/claude-sdk/one-shot.ts

@@ -279,6 +279,34 @@ async function formatAndAppendMessage(
  * spawner (us) and contains the env vars Talon set when launching the SDK
  * subprocess via MCP launcher. SIGTERM with a short grace, then SIGKILL.
  */
+/**
+ * Decide whether a `/proc` entry is a run orphan this sweep may kill.
+ *
+ * Carrying the chat id is necessary but NOT sufficient. Every chat-scoped
+ * child Talon spawns inherits `TALON_CHAT_ID` — including trigger watchers
+ * (`core/background/triggers/spawn.ts` sets it alongside `TALON_TRIGGER_ID`)
+ * and their descendants, which are long-lived by design and belong to no run.
+ * Matching on the chat id alone made every orphan sweep kill that chat's
+ * triggers: the warden respawned them, the next sweep killed them again, and
+ * the only visible symptom was a trigger stuck in "errored" with no output.
+ *
+ * Two independent guards, because this function issues SIGKILL:
+ *  - refuse anything tagged `TALON_TRIGGER_ID` (a trigger, or its child);
+ *  - require the argv to actually be the `claude` SDK binary, which is the
+ *    only thing this sweep was ever meant to reap.
+ */
+export function isEvictableOrphan(
+  envEntries: string[],
+  argv: string[],
+  target: string,
+): boolean {
+  if (!envEntries.includes(target)) return false;
+  if (envEntries.some((entry) => entry.startsWith("TALON_TRIGGER_ID="))) {
+    return false;
+  }
+  return argv.some((arg) => arg === "claude" || arg.endsWith("/claude"));
+}
+
 export async function evictOrphanSubprocesses(contextLabel: string): Promise<{
   found: number;
   termed: number;
@@ -306,12 +334,14 @@ export async function evictOrphanSubprocesses(contextLabel: string): Promise<{
     if (!Number.isInteger(pid) || pid === myPid) continue;
     try {
       const environRaw = await readFile(`/proc/${pid}/environ`, "utf-8");
+      const argvRaw = await readFile(`/proc/${pid}/cmdline`, "utf-8");
       // /proc/<pid>/environ is NUL-delimited. Split on \0 and match exact
       // entries — a raw .includes() can false-positive on other vars whose
       // value happens to contain the substring. Since this code can SIGKILL,
       // err on the side of strict matching. (Copilot review on #144.)
-      const envEntries = environRaw.split("\0");
-      if (envEntries.includes(target)) {
+      if (
+        isEvictableOrphan(environRaw.split("\0"), argvRaw.split("\0"), target)
+      ) {
         matched.push(pid);
       }
     } catch {

package/src/backend/claude-sdk/stream.ts

@@ -2,8 +2,8 @@
  * Typed stream processing helpers for SDK messages.
  *
  * Each function operates on a properly narrowed SDK message type —
- * no Record<string, unknown> casts. The StreamState accumulator
- * replaces the scattered local variables from the original handler.
+ * no Record<string, unknown> casts. StreamState is the turn's single
+ * accumulator.
  */
 
 import type {

package/src/backend/codex/auth.ts

@@ -302,7 +302,7 @@ export function isChatGptModelMismatchError(message: string): boolean {
 
 /**
  * Detect the *silent* OAuth-incompat exit shape — the one that hit
- * Pandario on 2026-05-20 at 23:13Z.
+ * a group chat on 2026-05-20 at 23:13Z.
  *
  * On a free ChatGPT-OAuth credential the Codex CLI silently rejects
  * most model strings (only `gpt-5.5` is verified working). Crucially,

package/src/backend/codex/handler/message.ts

@@ -205,17 +205,6 @@ async function maybeFallbackForChatGptMismatch(
   return await handleMessage({ ...params, model: fallbackModel }, true);
 }
 
-// ── Model resolution ────────────────────────────────────────────────────────
-
-/**
- * Codex accepts arbitrary model strings; we pass through whatever the
- * caller resolved (chat-settings → config) and fall back to the auth-aware
- * default: `gpt-5-codex` when an API key is present, `gpt-5.5` when only
- * ChatGPT OAuth is configured (because `gpt-5-codex` is rejected with a
- * 400 on ChatGPT-mode accounts). A model known to be OAuth-incompat on a
- * ChatGPT-OAuth account is swapped pre-emptively rather than letting the
- * first turn fail.
- */
 /**
  * The turn's user prompt: the shared framing every backend emits, plus
  * whatever this turn's memory retrieval produced. `formatUserPrompt` is
@@ -233,6 +222,17 @@ function buildTurnPrompt(params: QueryParams): string {
   });
 }
 
+// ── Model resolution ────────────────────────────────────────────────────────
+
+/**
+ * Codex accepts arbitrary model strings; we pass through whatever the
+ * caller resolved (chat-settings → config) and fall back to the auth-aware
+ * default: `gpt-5-codex` when an API key is present, `gpt-5.5` when only
+ * ChatGPT OAuth is configured (because `gpt-5-codex` is rejected with a
+ * 400 on ChatGPT-mode accounts). A model known to be OAuth-incompat on a
+ * ChatGPT-OAuth account is swapped pre-emptively rather than letting the
+ * first turn fail.
+ */
 function resolveCodexModel(chatId: string, requested: string | undefined) {
   const authInfo = getCodexAuthInfo();
   const authAwareDefault =

package/src/backend/codex/init.ts

@@ -85,15 +85,10 @@ export function initCodexAgent(
   // credential fingerprint has changed since last load). The store is
   // a no-op for non-OAuth credentials but the loader is cheap, so we
   // call it for all modes uniformly.
-  // Fire-and-forget: the loader keeps its async signature (historical;
-  // kv reads are sync now) but `initCodexAgent` is sync and changing it
-  // to async would ripple through every caller in bootstrap.ts.
-  // The store is best-effort anyway — if a turn races with the
-  // first load, `isKnownOAuthIncompat` defaults to false and the
-  // turn proceeds without the runtime-learned filter (the curated
-  // list still applies). Errors are already swallowed inside
-  // `loadOAuthIncompatStore`, so the .catch() here is purely
-  // defensive against a synchronous throw in the function body.
+  // Fire-and-forget: `initCodexAgent` is sync. The store is best-effort —
+  // a turn that races the first load runs without the runtime-learned
+  // filter (the curated list still applies). The loader swallows its own
+  // errors; the .catch() only guards a throw in its body.
   loadOAuthIncompatStore(computeAuthFingerprint(authInfo)).catch(() => {
     /* logged inside loadOAuthIncompatStore */
   });

package/src/backend/codex/mcp-config.ts

@@ -12,8 +12,7 @@
  * hub (`core/mcp-hub`) — Codex connects with `mcp_servers.<name>.url`
  * (the same transport `codex mcp add --url` configures). The hub hosts
  * Talon's tools in-process and shares plugin/brave children across
- * chats, so Codex no longer spawns a subprocess pair per server per
- * turn:
+ * chats, so Codex spawns no MCP subprocesses of its own:
  *
  *   {
  *     mcp_servers: {

package/src/backend/codex/oauth-incompat.ts

@@ -75,6 +75,7 @@
  *     stay synchronous (they only touch the in-memory set).
  */
 
+import { scryptSync } from "node:crypto";
 import { logDebug } from "../../util/log.js";
 import { files } from "../../util/paths.js";
 import { kvGet, kvSet } from "../../storage/kv.js";
@@ -118,7 +119,7 @@ let memoryStore: InMemoryStore | null = null;
  *
  * Fingerprint shape:
  *   - `mode:source` for ChatGPT OAuth (no token to hash)
- *   - `mode:source:<first 16 chars of key>` for api-key billing
+ *   - `mode:source:<scrypt(key), 16 hex>` for api-key billing
  *   - `mode:source` for missing/empty
  *
  * Constant-folded by `mode === "none"` — no learning happens without
@@ -127,9 +128,12 @@ let memoryStore: InMemoryStore | null = null;
 export function computeAuthFingerprint(info: CodexAuthInfo): string {
   const base = `${info.mode}:${info.source}`;
   if (info.mode === "api-key" && info.apiKey) {
-    // First 16 chars is enough to distinguish keys for fingerprint
-    // purposes without storing the full secret on disk.
-    return `${base}:${info.apiKey.slice(0, 16)}`;
+    // A digest, never key material: the fingerprint is persisted in kv
+    // and appears in debug logs.
+    // scrypt, not a bare hash: the input is a credential. Computed once
+    // per codex init.
+    const digest = scryptSync(info.apiKey, "talon.codex.fingerprint", 8);
+    return `${base}:${digest.toString("hex")}`;
   }
   return base;
 }

package/src/backend/codex/one-shot.ts

@@ -40,7 +40,7 @@ import { toCodexReasoningEffort } from "./effort.js";
  * `config.heartbeatModel ?? config.model`. If that's an OAuth-incompat
  * id (curated `apiKeyOnly: true` or runtime-learned) AND the active
  * Codex credential is ChatGPT OAuth, swap to `gpt-5.5` to avoid the
- * silent exit-1 failure mode that hit Pandario on 2026-05-20 23:13Z.
+ * silent exit-1 failure mode that hit a group chat on 2026-05-20 23:13Z.
  *
  * Returns the resolved model id, whether a swap occurred, and an
  * optional reason string for the run log.

package/src/backend/openai-agents/builtins.ts

@@ -31,9 +31,10 @@
  * shared prompt vocabulary applies uniformly.
  */
 import { tool } from "@openai/agents";
-import { spawn } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
 import { readFile, writeFile, mkdir, glob } from "node:fs/promises";
 import { dirname, resolve as resolvePath } from "node:path";
+import { createOutputCapture } from "../../util/exec-output.js";
 import { expandFsPath as expandPath } from "../../util/fs-path.js";
 
 // ── Read ────────────────────────────────────────────────────────────────────
@@ -204,6 +205,12 @@ const editTool = tool({
 
 const BASH_DEFAULT_TIMEOUT_MS = 30_000;
 const BASH_MAX_TIMEOUT_MS = 600_000;
+/**
+ * After a timeout kill, how long to wait for `close` before settling with
+ * what was captured. `close` waits for the stdio pipes to drain, which a
+ * descendant that escaped the kill can hold open indefinitely.
+ */
+const BASH_CLOSE_GRACE_MS = 2_000;
 
 interface BashInput {
   command: string;
@@ -235,43 +242,64 @@ function runShell(
             ],
           }
         : { cmd: "bash", args: ["-lc", command] };
+    // detached → own process group on POSIX, so the timeout kill reaches
+    // the shell's children too. A surviving child (the `sleep` in
+    // `sleep 30; echo`) holds stdout open, and `close` waits for it.
+    const detached = process.platform !== "win32";
     const child = spawn(shell.cmd, shell.args, {
       cwd: process.cwd(),
       env: process.env,
       stdio: ["ignore", "pipe", "pipe"],
+      detached,
     });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (b: Buffer) => {
-      stdout += b.toString("utf8");
-    });
-    child.stderr.on("data", (b: Buffer) => {
-      stderr += b.toString("utf8");
-    });
+    // Bounded: an unbounded stream (`yes`, a verbose build) otherwise grows
+    // until V8's string limit throws inside the data listener.
+    const out = createOutputCapture();
+    const err = createOutputCapture();
+    child.stdout.on("data", out.push);
+    child.stderr.on("data", err.push);
+    let settled = false;
+    let timedOut = false;
+    let closeGrace: NodeJS.Timeout | undefined;
+    const finish = (code: number, stderr = err.value()): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(killer);
+      if (closeGrace) clearTimeout(closeGrace);
+      resolveResult({ stdout: out.value(), stderr, code, timedOut });
+    };
     const killer = setTimeout(() => {
       timedOut = true;
-      child.kill("SIGKILL");
+      killGroup(child, detached);
+      // A descendant that left the group can still hold the pipes open;
+      // don't let it pin the tool call past the timeout.
+      closeGrace = setTimeout(() => finish(-1), BASH_CLOSE_GRACE_MS);
     }, timeoutMs);
-    let timedOut = false;
-    child.on("error", (err) => {
-      // spawn failed (e.g. bash not in PATH on Windows). Resolve instead
-      // of letting Node emit an uncaught error — the tool returns the
-      // diagnostic so callers can surface it rather than crashing.
-      clearTimeout(killer);
-      resolveResult({
-        stdout,
-        stderr: err.message,
-        code: -1,
-        timedOut: false,
-      });
-    });
-    child.on("close", (code) => {
-      clearTimeout(killer);
-      resolveResult({ stdout, stderr, code: code ?? -1, timedOut });
-    });
+    // spawn failed (e.g. bash not in PATH on Windows). Resolve instead
+    // of letting Node emit an uncaught error — the tool returns the
+    // diagnostic so callers can surface it rather than crashing.
+    child.on("error", (spawnErr) => finish(-1, spawnErr.message));
+    child.on("close", (code) => finish(code ?? -1));
   });
 }
 
+/** SIGKILL the child's whole process group, falling back to the child. */
+function killGroup(child: ChildProcess, detached: boolean): void {
+  if (detached && child.pid) {
+    try {
+      process.kill(-child.pid, "SIGKILL");
+      return;
+    } catch {
+      // group already gone — fall through to the direct kill
+    }
+  }
+  try {
+    child.kill("SIGKILL");
+  } catch {
+    // already dead
+  }
+}
+
 const bashTool = tool({
   name: "Bash",
   description:

package/src/backend/openai-agents/factory.ts

@@ -93,9 +93,9 @@ const openAIAgentsFactory: BackendFactory = {
 
     return {
       backend,
-      // Cleanup: close every per-chat MCP bundle in the pool so the
-      // ~15 plugin subprocesses per active chat don't outlive the
-      // backend itself, then drop the cached state.
+      // Cleanup: close every per-chat MCP bundle in the pool so its hub
+      // sessions don't outlive the backend itself, then drop the cached
+      // state.
       cleanup: async () => {
         await releaseAllBundles();
         resetState();

package/src/backend/openai-agents/handler/message.ts

@@ -118,8 +118,7 @@ function buildTurnPrompt(
 
 /**
  * Acquire the per-chat MCP bundle. Persistent across turns — built on
- * first use, kept alive until `releaseBundle(chatId)`. Avoids the
- * ~15-subprocess re-spawn the original per-turn build caused.
+ * first use, kept until the backend's cleanup releases the pool.
  */
 async function acquireMcpBundle(
   chatId: string,
@@ -366,7 +365,7 @@ export async function handleMessage(
   } catch (err) {
     // Swallow the terminator abort — the turn completed via a delivery tool.
     if (!isTerminatorAbort(streamState, err)) {
-      // MCP bundle is retained across a retry — subprocesses are
+      // MCP bundle is retained across a retry — its servers are
       // stateless wrt the model conversation. See `mcp-pool.ts`.
       const outcome = await applyRetryDecision({
         err,
@@ -400,8 +399,7 @@ export async function handleMessage(
       activeAborts.delete(chatId);
     }
     // MCP bundle is NOT closed here — it persists across turns via the
-    // pool in `mcp-pool.ts`. Release happens on chat rebind, `/reset`, and
-    // at backend cleanup.
+    // pool in `mcp-pool.ts` and is released at backend cleanup.
   }
 
   // ── Post-loop accounting ──────────────────────────────────────────────────

package/src/backend/openai-agents/mcp-pool.ts

@@ -4,17 +4,11 @@
  * Every server is a lightweight `MCPServerStreamableHttp` client
  * pointing at the daemon's MCP hub (`core/mcp-hub`): Talon's own tools
  * run in-process there, and plugin/brave servers are hub-managed
- * children shared across chats and reaped when idle.
+ * children shared across chats and reaped when idle. A bundle is just
+ * HTTP client objects; the process count is owned and bounded by the hub.
  *
- * Historical note: this pool used to hold one **subprocess set** per
- * chat (every plugin × every chat, held until release) — the daemon's
- * memory grew linearly with the number of chats. With the hub, a
- * bundle is just HTTP client objects; the process count is owned and
- * bounded by the hub.
- *
- * The bundle is still cached per chat (and released on reset/rebind)
- * so `cacheToolsList` survives across turns and each turn skips the
- * connect handshake.
+ * The bundle is cached per chat so `cacheToolsList` survives across
+ * turns and each turn skips the connect handshake.
  *
  * Concurrency: `getOrCreateBundle` serialises the build-or-return
  * decision on a per-chat in-flight Promise so two concurrent turns from
@@ -36,18 +30,13 @@ import { frontendsForChat } from "../runtime/frontends.js";
 import { log, logWarn } from "../../util/log.js";
 
 /**
- * One per-chat bundle. Subprocesses stay alive until `close()` is
+ * One per-chat bundle. Its hub sessions stay open until `close()` is
  * called via `releaseBundle()` / `releaseAllBundles()`.
  */
 export interface OpenAIAgentsMcpBundle {
-  /**
-   * Connected MCP servers ready to pass to `new Agent({ mcpServers })`.
-   * `connectMcpServers` returns the structural `MCPServer` type — the
-   * underlying instances are `MCPServerStdio` but the Agent constructor
-   * only needs the interface.
-   */
+  /** Connected MCP servers ready to pass to `new Agent({ mcpServers })`. */
   servers: MCPServer[];
-  /** Close every spawned subprocess. Safe to call multiple times. */
+  /** Close every server's hub session. Safe to call multiple times. */
   close: () => Promise<void>;
   /** Servers that failed to connect — exposed for diagnostics. */
   failed: ReadonlyArray<{ name: string; error: string }>;
@@ -115,14 +104,8 @@ export async function getOrCreateBundle(
  * Close the bundle for `chatId` and drop it from the pool. No-op when
  * the chat has no live bundle.
  *
- * Call when:
- *   - The chat rebinds to a non-openai-agents backend.
- *   - The user runs `/reset`.
- *   - The chat is destroyed.
- *
  * If `getOrCreateBundle` is in flight when called, releases the bundle
- * once the in-flight build resolves to avoid leaving an unreleased
- * subprocess set.
+ * once the in-flight build resolves so it is not left open.
  */
 export async function releaseBundle(chatId: string): Promise<void> {
   // If a build is in flight, wait for it then close the result.
@@ -152,8 +135,8 @@ export async function releaseBundle(chatId: string): Promise<void> {
 
 /**
  * Close every live bundle. Used by the backend factory's `cleanup`
- * hook so unbinding the openai-agents backend leaves no orphan MCP
- * subprocesses.
+ * hook so unbinding the openai-agents backend leaves no hub sessions
+ * behind.
  */
 export async function releaseAllBundles(): Promise<void> {
   const ids = [...bundles.keys()];

package/src/backend/remote-server/chat-turn.ts

@@ -253,12 +253,6 @@ export async function runRemoteChatTurn<TClient extends RemoteAgentClient>(
   });
 }
 
-/**
- * If the SSE loop missed the usage info, fall back to the session summary
- * endpoint (which always reflects the final server state). Best-effort:
- * session summaries can race on cancellation, so a failure leaves the
- * counts at zero.
- */
 /**
  * The turn's user prompt: the shared framing every backend emits, plus
  * whatever this turn's memory retrieval produced. `formatUserPrompt` is
@@ -276,6 +270,12 @@ function buildTurnPrompt(params: QueryParams): string {
   });
 }
 
+/**
+ * If the SSE loop missed the usage info, fall back to the session summary
+ * endpoint (which always reflects the final server state). Best-effort:
+ * session summaries can race on cancellation, so a failure leaves the
+ * counts at zero.
+ */
 async function fillUsageFromSummary(
   oc: RemoteSessionClient,
   sessionId: string,

package/src/backend/remote-server/events.ts

@@ -39,11 +39,7 @@ import {
   type RemoteAssistantInfo,
 } from "./session-helpers.js";
 import { log, logDebug } from "../../util/log.js";
-
-/** Format an error for a debug log line. */
-function errMsg(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}
+import { errMsg } from "./state.js";
 
 // ── Streaming timing ───────────────────────────────────────────────────────
 

package/src/backend/remote-server/index.ts

@@ -19,7 +19,6 @@
  *   - Bindings (server-bindings.ts, chat-turn.ts, turn.ts, factory.ts) —
  *     the helpers closed over one backend's state, the SSE-driven turn,
  *     the chat-turn orchestration, and the registry factory composition.
- *     This is where the code that used to be copied per backend lives.
  *
  *   - Profiles (`profiles/bind.ts` + `profiles/{kilo,opencode}.ts`) —
  *     `bindRemoteProfile` closes all of the above over one driver's