cookbook-bridge 0.1.0

package/bridge.mjs

@@ -0,0 +1,1914 @@
+#!/usr/bin/env node
+/**
+ * Cookbook Bridge — wakes your local subscription agents to do their Cookbook
+ * tasks, so they run themselves instead of you shuttling between chat windows.
+ *
+ *   Claude assigns Gemini a task  →  it lands on the Cookbook board (open)
+ *   The Bridge (here) polls, sees it, and wakes Gemini headlessly
+ *   Gemini — already MCP-connected to Cookbook — does the work and calls
+ *     complete_task itself, on YOUR subscription (no API credits)
+ *
+ * The Bridge is just a *waker*: it never does the work, it triggers the right
+ * agent and verifies the task got done. Local, free, distributed (each user
+ * runs their own Bridge for their own agents — this is the seed of the shippable
+ * "Cookbook Bridge" client).
+ *
+ * Run:  node bridge/bridge.mjs                 (uses bridge/config.json)
+ *       node bridge/bridge.mjs ./my.json       (explicit config path)
+ *       node bridge/bridge.mjs login           (one-click connect, RFC 8628)
+ *       node bridge/bridge.mjs status          (liveness + agent readiness)
+ *       node bridge/bridge.mjs doctor          (preflight: check every prerequisite,
+ *                                               print the exact fix for each ✗)
+ *
+ * "login", "status", and "doctor" are reserved first-args; pass a config path to
+ * those subcommands with --config <path>. Plain `node bridge.mjs [path]` is unchanged.
+ *
+ * Node built-ins only. No dependencies.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+// LOCAL modules load LAZILY (loadRuntime below), not statically: a Bridge with a
+// missing/corrupt module file must still be able to run `node bridge.mjs update` and
+// repair itself — the update path depends ONLY on update.mjs (node built-ins only).
+// The e2e that forced this: a stale install missing volunteer.mjs couldn't even reach
+// the updater when these were static imports.
+let listWorkspaces, listTasks, listOpenWork, getTask, threadResumeContext, completeTaskApi, resolveDelegation, reportTaskUsage, reportTaskProgress, volunteerClaim, dispatchClaim, abandonTask, recallMemories, recallAcrossWorkspaces, creditRecall, getVolunteerSettings;
+let agentEnv, checkGeminiVersion, isGeminiCommand, GEMINI_MIN_VERSION, checkAgyVersion, isAgyCommand, AGY_MIN_VERSION;
+let extractUsage, displayText;
+let volunteeringEnabled, volunteerCandidates, decisionPrompt, parseDecision, MAX_DECISIONS_PER_POLL, mergeVolunteerSettings, effectiveCapabilities;
+let buildPrompt, buildThreadFollowUpPrompt;
+let runnerFor, hasRunner, warmUp, adoptRunner, reapIdleRunners, killAllRunners;
+let hasCodexThread, reapCodexServer, killCodexServer;
+let checkForUpdate, applyUpdate;
+let createLocalServer, toolsForMode, modeForTools, vendorOf;
+let connectAgentsProgrammatic, detectClis;
+
+async function loadRuntime() {
+  ({ createLocalServer, toolsForMode, modeForTools, vendorOf } = await import("./local.mjs"));
+  ({ connectAgentsProgrammatic, detectClis } = await import("./device.mjs"));
+  ({ listWorkspaces, listTasks, listOpenWork, getTask, threadResumeContext, completeTaskApi, resolveDelegation, reportTaskUsage, reportTaskProgress, volunteerClaim, dispatchClaim, abandonTask, recallMemories, recallAcrossWorkspaces, creditRecall, getVolunteerSettings } = await import("./cookbook.mjs"));
+  ({ agentEnv, checkGeminiVersion, isGeminiCommand, GEMINI_MIN_VERSION, checkAgyVersion, isAgyCommand, AGY_MIN_VERSION } = await import("./harden.mjs"));
+  ({ extractUsage, displayText } = await import("./usage.mjs"));
+  ({ volunteeringEnabled, volunteerCandidates, decisionPrompt, parseDecision, MAX_DECISIONS_PER_POLL, mergeVolunteerSettings, effectiveCapabilities } = await import("./volunteer.mjs"));
+  ({ buildPrompt, buildThreadFollowUpPrompt } = await import("./prompt.mjs"));
+  ({ runnerFor, hasRunner, warmUp, adoptRunner, reapIdleRunners, killAllRunners } = await import("./thread-runner.mjs"));
+  ({ hasCodexThread, reapCodexServer, killCodexServer } = await import("./codex-runner.mjs"));
+  ({ checkForUpdate, applyUpdate } = await import("./update.mjs"));
+}
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+function log(msg) {
+  const ts = new Date().toISOString().slice(11, 19);
+  console.log(`[${ts}] ${msg}`);
+}
+
+/**
+ * A GUI app (the desktop sidecar) inherits a minimal PATH that misses Homebrew
+ * (`/opt/homebrew/bin`), `/usr/local/bin`, nvm, and Claude's local install — so a
+ * bare agent command like `claude`/`gemini` fails with ENOENT and the task silently
+ * never runs (Codex works only because its config uses an absolute path). Prepend the
+ * known install dirs to PATH so spawned agents resolve their binaries regardless of
+ * how the Bridge was launched. This is the agent-command analog of the Rust
+ * find_node() trap fix (bridge.rs), applied to the binaries the Bridge itself spawns.
+ */
+function ensureAgentPath() {
+  const home = process.env.HOME || "";
+  const dirs = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"];
+  if (home) {
+    dirs.push(path.join(home, ".claude/local")); // claude CLI local install
+    dirs.push(path.join(home, ".bun/bin"), path.join(home, ".local/bin"));
+    try {
+      const base = path.join(home, ".nvm/versions/node");
+      const vers = fs.readdirSync(base).sort();
+      if (vers.length) dirs.push(path.join(base, vers[vers.length - 1], "bin"));
+    } catch {
+      /* no nvm — fine */
+    }
+  }
+  const cur = process.env.PATH || "";
+  const have = new Set(cur.split(path.delimiter).filter(Boolean));
+  const add = dirs.filter((d) => d && !have.has(d));
+  if (add.length) process.env.PATH = [...add, cur].filter(Boolean).join(path.delimiter);
+}
+
+/** Resolve a command to an executable path: an absolute/relative path is checked
+ *  directly; a bare name is searched on PATH (after ensureAgentPath). Returns null if
+ *  not found — used by `doctor` and the default-agent startup warning. */
+function resolveBin(cmd) {
+  if (!cmd) return null;
+  if (cmd.includes("/")) {
+    try { fs.accessSync(cmd, fs.constants.X_OK); return cmd; } catch { return null; }
+  }
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    if (!dir) continue;
+    const p = path.join(dir, cmd);
+    try { fs.accessSync(p, fs.constants.X_OK); return p; } catch { /* keep looking */ }
+  }
+  return null;
+}
+
+/** Pick a config path from a subcommand's args: `--config <path>`, else first
+ *  positional, else the default config.json next to this file. */
+function configPathFromArgs(args, fallback) {
+  const i = args.indexOf("--config");
+  if (i >= 0 && args[i + 1]) return path.resolve(args[i + 1]);
+  const positional = (args || []).find((a) => a && !a.startsWith("-"));
+  return positional ? path.resolve(positional) : fallback;
+}
+
+/** Where the running Bridge's config lives (Bridge Local writes local.json next to it). */
+let CONFIG_PATH = null;
+
+function loadConfig() {
+  const p = process.argv[2] ? path.resolve(process.argv[2]) : path.join(HERE, "config.json");
+  CONFIG_PATH = p;
+  if (!fs.existsSync(p)) {
+    console.error(`No config at ${p}.\nEasiest: run \`node bridge/bridge.mjs login\` — one-click connect, no token to paste.\n(Manual alternative: copy bridge/config.example.json → bridge/config.json and add a token from Account → Tokens.)`);
+    process.exit(1);
+  }
+  const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
+  cfg.cookbookUrl = (cfg.cookbookUrl || "").replace(/\/$/, "");
+  if (!cfg.cookbookUrl || !cfg.token || cfg.token.startsWith("PASTE")) {
+    console.error("Config needs `cookbookUrl` and a real `token` (generate one on your Cookbook account's Tokens page).");
+    process.exit(1);
+  }
+  cfg.pollSeconds = cfg.pollSeconds ?? 15;
+  // Persistent per-thread agent processes (terminal-feel replies). Opt-in while it
+  // proves itself; the one-shot spawn path remains the fallback either way.
+  cfg.persistentThreads = cfg.persistentThreads ?? false;
+  // LOCAL WORKSPACE ACCESS (2026-08-21): map a workspace to a folder on THIS machine.
+  //   localWorkspaces: { "<workspaceId>": { "cwd": "/abs/path", "allowedTools": "…" } }
+  // SELF-ASSIGNED tasks in a mapped workspace run IN that folder with real tools
+  // (files/shell) — the same trust as the member running the CLI in their own
+  // terminal, because they asked. Teammate-assigned tasks NEVER get local access;
+  // they stay jailed to workspace tools. This is the terminal-parity wall.
+  cfg.localWorkspaces = cfg.localWorkspaces ?? {};
+  cfg.maxAttempts = cfg.maxAttempts ?? 2;
+  // Phase 1 semantics: taskTimeoutSeconds is the ABSOLUTE CEILING (cost backstop),
+  // livenessTimeoutSeconds is the stall detector (no output for this long = dead).
+  // History: 300 killed MCP-heavy runs (2026-07-03); 900 killed healthy founding
+  // runs (2026-07-13) — no wall-clock fits both, so silence decides, not duration.
+  cfg.taskTimeoutSeconds = cfg.taskTimeoutSeconds ?? 3600;
+  cfg.livenessTimeoutSeconds = cfg.livenessTimeoutSeconds ?? 300;
+  // Parallel slots: how many task runs may be in flight at once (audit: serial
+  // execution let one long run block every workspace's queue).
+  cfg.maxConcurrentRuns = Math.max(1, cfg.maxConcurrentRuns ?? 2);
+  cfg.agents = (cfg.agents ?? []).filter((a) => a.enabled !== false);
+  ensureAgentPath(); // so bare `claude`/`gemini` commands resolve under the app's minimal PATH
+  loadRunState(); // restore attempts/given-up so a restart can't grant doomed tasks fresh attempts
+  return cfg;
+}
+
+/** Which managed agent (if any) handles a task's `assigned_to`. */
+/** Tools a LOCAL run gets: the member's own terminal toolkit + Cookbook. */
+export const DEFAULT_LOCAL_TOOLS = "Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch,mcp__cookbook__*";
+
+/** Rewrite a claude-shaped command's --allowedTools for a local-access run. Pure. */
+export function localizeCommand(command, allowedTools) {
+  if (!Array.isArray(command)) return command;
+  const i = command.indexOf("--allowedTools");
+  if (i < 0 || i + 1 >= command.length) return command;
+  const out = [...command];
+  out[i + 1] = allowedTools || DEFAULT_LOCAL_TOOLS;
+  return out;
+}
+
+function agentFor(cfg, assignedTo) {
+  const a = (assignedTo || "").toLowerCase();
+  if (a === "any") {
+    return cfg.agents.find((x) => x.name === cfg.default) ?? cfg.agents[0] ?? null;
+  }
+  // Substring match so "Gemini" matches a connection labelled "Gemini CLI MCP Client".
+  return cfg.agents.find((x) => (x.match ?? [x.name]).some((m) => a.includes(String(m).toLowerCase()))) ?? null;
+}
+
+/**
+ * Approval policy: should this agent auto-run a task, given WHO assigned it?
+ *  - "anyone" (default): run every task assigned to this agent.
+ *  - ["dp","erichaneyatx", …]: only run tasks assigned by these people (matched
+ *    on the assigning member, so it's precise even if they used an agent).
+ * Anything not allowed is skipped and left open for you.
+ */
+export function allowedByPolicy(cfg, agent, task) {
+  let policy = agent.acceptFrom ?? cfg.acceptFrom ?? "anyone";
+  if (typeof policy === "string" && policy !== "anyone") policy = [policy];
+  if (policy === "anyone" || !Array.isArray(policy)) return true;
+  // EXACT match only (Phase 0, audit #9): substring matching made consent fuzzy —
+  // acceptFrom:["Ana"] silently accepted tasks from "Ariana"; ["dp"] matched
+  // "dprozzi". A CONSENT decision must never guess. Entries match the assigning
+  // member's exact name (case-insensitive) or their profile id.
+  const whoName = String(task.assigned_by_member || task.assigned_by || "").trim().toLowerCase();
+  const whoId = String(task.assigned_by_profile || "").toLowerCase();
+  return policy.some((n) => {
+    const entry = String(n).trim().toLowerCase();
+    return entry !== "" && (entry === whoName || entry === whoId);
+  });
+}
+
+
+/** Spawn the agent's headless CLI with the prompt substituted into its argv.
+ *  `env` (from agentEnv) strips vendor API-billing keys unless the user opted in —
+ *  a task must never silently bill an API account instead of the owner's subscription. */
+/**
+ * Detect a one-shot claude agent emitting `--output-format json` and rewrite it to
+ * `stream-json` (+ `--verbose`, which claude requires with stream-json). This gives
+ * the LIVE token ticker for free — no config change — while the final `result` line
+ * stream-json emits last is byte-identical to what json mode returns, so
+ * extractUsage/failureHint/displayText keep working unchanged. Returns the (possibly
+ * rewritten) command array + whether streaming is active. Anything else (gemini,
+ * text mode, already-stream-json, no json flag) is returned untouched.
+ */
+export function streamingCommand(command) {
+  if (!Array.isArray(command)) return { command, streaming: false };
+  const i = command.indexOf("--output-format");
+  if (i < 0 || command[i + 1] !== "json") return { command, streaming: command.includes("stream-json") };
+  const rewritten = [...command];
+  rewritten[i + 1] = "stream-json";
+  if (!rewritten.includes("--verbose")) rewritten.push("--verbose");
+  // Live words stream PER COMPLETED TURN (assistant events), deliberately NOT
+  // --include-partial-messages: that flag stores partial-generation artifacts in the
+  // session file, and RESUMING such a session trips the API's reasoning-extraction
+  // safeguard (observed live 2026-08-20: resumed thread runs refused with
+  // `[reasoning_extraction]`). Resume is the flagship; per-turn streaming is plenty.
+  return { command: rewritten, streaming: true };
+}
+
+/** Pull streamed assistant TEXT out of one stream-json line. Returns
+ *  {kind:'delta',text} for a partial chunk (--include-partial-messages),
+ *  {kind:'turn',text} for a completed assistant turn (turn text REPLACES the
+ *  partial accumulation for that turn — never append both), or null when the
+ *  line carries no prose (tool calls, usage ticks, init). */
+export function textFromStreamLine(line) {
+  let j;
+  try { j = JSON.parse(line); } catch { return null; }
+  if (j.type === "stream_event") {
+    const d = j.event?.delta;
+    return d && d.type === "text_delta" && typeof d.text === "string" ? { kind: "delta", text: d.text } : null;
+  }
+  if (j.type === "assistant" && Array.isArray(j.message?.content)) {
+    const text = j.message.content
+      .filter((b) => b && b.type === "text" && typeof b.text === "string")
+      .map((b) => b.text)
+      .join("");
+    return { kind: "turn", text };
+  }
+  return null;
+}
+
+/** Cap for the live-text tail that rides progress reports (server caps at 2000). */
+export const LIVE_TEXT_CAP = 1800;
+
+/** Fold one stream-json line into a running progress total (monotonic-ish: output
+ *  tokens sum across turns; input/cache take the largest seen). Returns the updated
+ *  accumulator, or null when the line carries no usage. Also surfaces the final
+ *  `result` line so the caller can hand extractUsage a single clean envelope. */
+export function foldStreamLine(line, acc) {
+  let j;
+  try { j = JSON.parse(line); } catch { return { acc, resultLine: null }; }
+  if (j.type === "result") return { acc, resultLine: line };
+  const u = (j.message && j.message.usage) || j.usage;
+  if (!u || typeof u !== "object") return { acc, resultLine: null };
+  const n = (v) => (Number.isFinite(Number(v)) ? Number(v) : 0);
+  return {
+    acc: {
+      input_tokens: Math.max(acc.input_tokens, n(u.input_tokens)),
+      output_tokens: acc.output_tokens + n(u.output_tokens),
+      cache_read_input_tokens: Math.max(acc.cache_read_input_tokens, n(u.cache_read_input_tokens)),
+      num_turns: acc.num_turns + 1,
+    },
+    resultLine: null,
+  };
+}
+
+/** Pull the CLI's session identity off any stream line (claude stream-json carries
+ *  `session_id` on the init message AND the final result). Null when absent. */
+export function sessionIdFrom(line) {
+  try {
+    const j = JSON.parse(line);
+    return typeof j.session_id === "string" && j.session_id ? j.session_id : null;
+  } catch { return null; }
+}
+
+/** LIVENESS over wall-clock (Coordination v2 Phase 1): a run producing output is
+ *  healthy at minute 40; a run that's gone silent died at minute 3 — no fixed
+ *  wall-clock can tell them apart (300s killed MCP runs, 900s killed founding
+ *  runs). Kill on SILENCE (no stdout activity for livenessMs — streaming runs
+ *  only; buffered/non-streaming runs emit nothing until the end) and keep a
+ *  generous absolute ceiling purely as a cost backstop. Pure for tests. */
+export function shouldKill({ streaming, startedAt, lastActivityAt, now, livenessMs, ceilingMs }) {
+  if (now - startedAt >= ceilingMs) return { kill: true, why: `hit the ${Math.round(ceilingMs / 60000)}min absolute ceiling` };
+  if (streaming && livenessMs > 0 && now - lastActivityAt >= livenessMs) {
+    return { kill: true, why: `no output for ${Math.round(livenessMs / 1000)}s (stalled — likely a hung prompt or dead CLI)` };
+  }
+  return { kill: false, why: "" };
+}
+
+/** RESUME-FIRST RETRIES (Phase 1): rewrite a claude one-shot command to resume the
+ *  previous attempt's session — the retry CONTINUES the conversation (with the
+ *  failure fed back as the next message) instead of re-paying for a blank-context
+ *  redo. Claude only; other CLIs fall back to a fresh run with the error fed
+ *  forward in the prompt. Pure for tests. */
+export function resumeCommand(command, sessionId) {
+  if (!Array.isArray(command) || !sessionId) return { command, resumed: false };
+  const base = String(command[0] ?? "").split(/[\\/]/).pop().toLowerCase();
+  if (base !== "claude") return { command, resumed: false };
+  if (command.includes("--resume")) return { command, resumed: true };
+  return { command: [command[0], "--resume", sessionId, ...command.slice(1)], resumed: true };
+}
+
+function spawnAgent(agent, prompt, timeoutSeconds, env, onProgress, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const baseCommand = opts.command ?? agent.command;
+    const { command, streaming } = onProgress ? streamingCommand(baseCommand) : { command: baseCommand, streaming: false };
+    const [cmd, ...rawArgs] = command;
+    const args = rawArgs.map((a) => a.replaceAll("{prompt}", prompt));
+    const child = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: env ?? process.env,
+      // Local-access runs execute IN the mapped folder (terminal parity).
+      ...(agent.cwd ? { cwd: agent.cwd } : {}),
+    });
+
+    let out = "";
+    let err = "";
+    // Streaming path: line-buffer stdout, fold per-turn usage, throttle-emit progress,
+    // and keep ONLY the final result line as `out` so downstream parsers are unchanged.
+    let acc = { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, num_turns: 0 };
+    let resultLine = "";
+    let lineBuf = "";
+    let lastEmit = 0;
+    // Live words (Composer chat feel): finished turns + the current turn's partial
+    // deltas. A completed turn REPLACES its partials (same text arrives both ways).
+    let turnsText = "";
+    let partialText = "";
+    const liveText = () => {
+      const full = partialText ? `${turnsText}${turnsText ? "\n\n" : ""}${partialText}` : turnsText;
+      return full.length > LIVE_TEXT_CAP ? "…" + full.slice(-LIVE_TEXT_CAP) : full;
+    };
+    const emit = () => {
+      const text = liveText();
+      if (!onProgress || (acc.input_tokens === 0 && acc.output_tokens === 0 && !text)) return;
+      lastEmit = Date.now();
+      // session_ref rides every tick once known: the server-visible resume handle that
+      // lets a Composer-thread follow-up continue THIS conversation (0064), surviving
+      // Bridge restarts (local retryCtx state is trimmed; the task row isn't).
+      // Progress needs a token field to pass the server's substance check, so a
+      // text-only tick sends output_tokens as-is (0 is fine once input>0 arrives).
+      try { onProgress({ ...acc, runner: agent.name, ...(text ? { live_text: text } : {}), ...(sessionId ? { session_ref: sessionId } : {}) }); } catch { /* progress is best-effort */ }
+    };
+
+    let sessionId = null;
+    const startedAt = Date.now();
+    let lastActivityAt = startedAt;
+    child.stdout.on("data", (d) => {
+      lastActivityAt = Date.now();
+      if (!streaming) { out += d; return; }
+      lineBuf += d;
+      let nl;
+      while ((nl = lineBuf.indexOf("\n")) >= 0) {
+        const line = lineBuf.slice(0, nl).trim();
+        lineBuf = lineBuf.slice(nl + 1);
+        if (!line) continue;
+        if (!sessionId) sessionId = sessionIdFrom(line);
+        const spoke = textFromStreamLine(line);
+        if (spoke) {
+          if (spoke.kind === "delta") partialText += spoke.text;
+          else {
+            turnsText += (turnsText && spoke.text ? "\n\n" : "") + spoke.text;
+            partialText = "";
+          }
+        }
+        const r = foldStreamLine(line, acc);
+        acc = r.acc;
+        if (r.resultLine) resultLine = r.resultLine;
+        else if (Date.now() - lastEmit > (agent.progressThrottleMs ?? 1200)) emit();
+      }
+    });
+    child.stderr.on("data", (d) => { lastActivityAt = Date.now(); err += d; });
+
+    // Liveness watchdog (Phase 1): silence kills fast, healthy work runs long.
+    // timeoutSeconds is now the absolute CEILING; livenessSeconds governs stall
+    // detection on streaming runs (non-streaming CLIs buffer, so ceiling-only).
+    const livenessMs = (opts.livenessSeconds ?? 0) * 1000;
+    const ceilingMs = timeoutSeconds * 1000;
+    const watchdog = setInterval(() => {
+      const verdict = shouldKill({ streaming, startedAt, lastActivityAt, now: Date.now(), livenessMs, ceilingMs });
+      if (!verdict.kill) return;
+      clearInterval(watchdog);
+      child.kill("SIGTERM");
+      setTimeout(() => child.kill("SIGKILL"), 5000);
+      const e = new Error(`killed: ${verdict.why}`);
+      // Carry the partial streaming counts out with the failure: a timed-out run
+      // BURNED real quota, and reporting zero made failed runs invisible to the
+      // chain token budget (2026-07-13 finding: 30 min of burns, budget saw 0).
+      e.partialUsage = acc.input_tokens || acc.output_tokens ? { ...acc } : null;
+      e.elapsedMs = Date.now() - startedAt;
+      e.sessionId = sessionId;
+      reject(e);
+    }, 5000);
+
+    child.on("error", (e) => {
+      clearInterval(watchdog);
+      reject(new Error(`could not launch \`${cmd}\` (is it installed + on PATH?): ${e.message}`));
+    });
+    child.on("close", (code) => {
+      clearInterval(watchdog);
+      // In streaming mode, hand back the final result line (json-mode-identical); fall
+      // back to the raw buffer if the run died before emitting one.
+      resolve({ code, out: streaming ? (resultLine || lineBuf || out) : out, err, sessionId });
+    });
+  });
+}
+
+/**
+ * Run a task on an agent. Two runner shapes:
+ *  - default: a one-shot headless CLI (Claude `-p`, Gemini `-p`) via spawnAgent.
+ *  - "app-server": a persistent `codex app-server` driven over JSON-RPC, because
+ *    Codex's headless `exec` path auto-cancels MCP tool calls (OpenAI #16685).
+ *    See bridge/codex-runner.mjs. Either way the agent calls complete_task
+ *    itself, so verification (getTask) is identical.
+ */
+async function runAgent(cfg, agent, prompt, onProgress, retry = null, taskCtx = {}) {
+  const { env } = agentEnv(cfg); // billing protection (see harden.mjs)
+  if (agent.runner === "app-server") {
+    const { runCodexTask } = await import("./codex-runner.mjs");
+    // Persistent codex server + thread mapping (v2): threadKey gives follow-ups
+    // real conversation continuity; onProgress streams agent-message deltas.
+    const threadKey = taskCtx.task ? taskCtx.task.thread_root_id ?? taskCtx.task.id : undefined;
+    return runCodexTask(agent, prompt, cfg.taskTimeoutSeconds, agent.token || cfg.codexToken, env, onProgress, { threadKey, log });
+  }
+  if (agent.runner === "robot") {
+    // Embodied runner (sim-first): structured task env, not a prompt — the robot's
+    // "brain" is a skill program. Same verify-via-getTask contract as every runner.
+    const { runRobotTask } = await import("./robot-runner.mjs");
+    return runRobotTask(agent, taskCtx.ws, taskCtx.task, cfg.taskTimeoutSeconds, agent.token || cfg.token, cfg.cookbookUrl, env);
+  }
+  // liveTokens defaults ON; a user can opt out per-agent or globally.
+  const live = cfg.liveTokens !== false && agent.liveTokens !== false;
+  // RESUME-FIRST (Phase 1): a retry with a saved claude session CONTINUES that
+  // session — the prompt becomes the next message in the conversation, carrying
+  // the failure back. Other CLIs get the failure fed forward in a fresh prompt.
+  const { command, resumed } = resumeCommand(agent.command, retry?.sessionId ?? null);
+  return spawnAgent(agent, prompt, cfg.taskTimeoutSeconds, env, live ? onProgress : undefined, {
+    command,
+    resumed,
+    livenessSeconds: cfg.livenessTimeoutSeconds,
+  });
+}
+
+/**
+ * Turn a spawn result into a human cause for the "ran but didn't complete" case —
+ * the single most confusing failure in the field (the agent CLI exited fine but the
+ * task isn't done because it isn't logged in / has no MCP / a tool was blocked). Reads
+ * the agent's own exit code + stderr/stdout and names the likely fix. Returns "" when
+ * there's nothing useful (e.g. the persistent app-server runner, whose result differs).
+ */
+/** Human line for a daily-cap hold: "X hit their NN-token daily cap on your subscription". */
+function capHoldLine(who, res) {
+  const cap = Number(res?.cap);
+  const spent = Number(res?.spent);
+  const capStr = Number.isFinite(cap) ? cap.toLocaleString() : "the";
+  const spentStr = Number.isFinite(spent) ? ` (${spent.toLocaleString()} used today)` : "";
+  return `${who} hit their ${capStr}-token daily cap on your subscription${spentStr} — held until it resets (or you raise it in Account → Agents).`;
+}
+
+function failureHint(result) {
+  if (!result || typeof result !== "object") return "";
+  const { code, err, out } = result;
+  // JSON-mode envelopes ALWAYS contain the literal substring "permission_denials",
+  // so judging on raw output misdiagnosed every failed claude+json run as "a tool
+  // was blocked" (live, 2026-07-03). Parse the envelope and judge the REAL fields:
+  // the denials array, and the agent's own final text.
+  let denials = [];
+  let display = "";
+  const rawOut = String(out ?? "");
+  const brace = rawOut.indexOf("{");
+  if (brace >= 0) {
+    try {
+      const j = JSON.parse(rawOut.slice(brace));
+      denials = Array.isArray(j.permission_denials) ? j.permission_denials : [];
+      if (typeof j.result === "string") display = j.result;
+    } catch { /* not a JSON envelope */ }
+  }
+  if (denials.length > 0) {
+    const names = [...new Set(denials.map((d) => d?.tool_name).filter(Boolean))].slice(0, 3).join(", ");
+    return `tool(s) blocked${names ? ` (${names})` : ""} → check \`allowedTools\` matches the agent's MCP server name (CLI-added = mcp__cookbook__*)`;
+  }
+  // Infrastructure patterns are judged on STDERR only — the model's answer text
+  // (`display`) legitimately contains words like "/login" or "MCP server" whenever
+  // the TASK is about those things (misdiagnosis class, audit 2026-07-03 #7).
+  const infra = String(err || "").toLowerCase();
+  const tailSrc = `${err || display || (brace < 0 ? rawOut : "")}`.trim();
+  const tail = tailSrc.split("\n").slice(-2).join(" ").slice(0, 240);
+  if (infra.includes("not logged in") || infra.includes("please log in"))
+    return "the agent CLI isn't logged in → run `claude auth login`";
+  if (infra.includes("no mcp") || infra.includes("requires authentication"))
+    return "the agent can't reach the Cookbook MCP → run `node bridge/bridge.mjs doctor`";
+  if (infra.includes("not allowed") || infra.includes("allowedtools"))
+    return "a tool was blocked → check `allowedTools` matches the agent's MCP server name (CLI-added = mcp__cookbook__*)";
+  if (typeof code === "number" && code !== 0) return `agent exited ${code}${tail ? `: ${tail}` : ""}`;
+  if (tail) return `agent said: ${tail}`;
+  return "";
+}
+
+// ── run-state persistence ────────────────────────────────────────────────────
+// attempts/givenUp were in-memory only, so EVERY restart (crash, self-update
+// re-exec, manual bounce) reset the counters — and the Bridge resumes its own
+// claimed tasks, so a restart granted every stuck task a fresh pair of attempts
+// (2026-07-13: a doomed goal would have re-burned 6x900s across restarts).
+// Persisted next to config; trimmed so it can't grow unbounded.
+const STATE_PATH = path.join(HERE, "bridge.state.json");
+function loadRunState() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(STATE_PATH, "utf8"));
+    for (const [id, n] of Object.entries(raw.attempts ?? {})) attempts.set(id, Number(n) || 0);
+    for (const id of raw.givenUp ?? []) givenUp.add(id);
+    for (const [id, ctx] of Object.entries(raw.retryCtx ?? {})) retryCtx.set(id, ctx);
+  } catch { /* first run / unreadable — start clean */ }
+}
+function saveRunState() {
+  try {
+    // Trim: these only matter for live tasks; cap so years of ids can't accumulate.
+    const attEntries = [...attempts.entries()].slice(-500);
+    const given = [...givenUp].slice(-500);
+    const retries = [...retryCtx.entries()].slice(-200);
+    fs.writeFileSync(STATE_PATH, JSON.stringify({ attempts: Object.fromEntries(attEntries), givenUp: given, retryCtx: Object.fromEntries(retries) }));
+  } catch { /* best-effort — never let state persistence break a run */ }
+}
+
+const attempts = new Map(); // taskId -> count
+// Retry context (Phase 1): what the LAST failed attempt knew — the claude session
+// to resume and the failure to feed back — so a retry continues instead of redoing.
+const retryCtx = new Map(); // taskId -> { sessionId, reason }
+// Volunteered runs that failed with attempts left: the task is already CLAIMED (by
+// this Bridge's volunteer pre-claim), so the open-task scan can't re-find it — it
+// retries from this shelf instead. In-memory: a restart still strands the claim
+// (visible on the board, cancel by hand) — deliberate v1 legibility over churn.
+const volunteeredRetries = [];
+const inFlight = new Set();
+
+// HOT MODE: while a conversation is active, the poll loop runs at 1s AND scopes
+// its sweep to the hot workspace(s) so replies dispatch near-instantly; markHot()
+// stamps activity per workspace, the window decays on its own.
+const HOT_WINDOW_MS = 180_000;
+let lastHotAt = 0;
+const hotWorkspaces = new Map(); // wsId -> last activity ts
+/** Bridge Local (local.mjs) — the loopback control API; null until main() starts it. */
+let localServer = null;
+let lastRunError = null;
+/** Whether the Cookbook token has ever verified this run (gates /status.connected and
+ *  keeps a token-rejected desktop Bridge alive instead of exiting). */
+let tokenOk = false;
+/** The desktop app sets COOKBOOK_DESKTOP=1 when it spawns the Bridge. Only then do we
+ *  stay alive on a revoked token (so the user can fix it from the app's Connect UI). A
+ *  headless/terminal Bridge still exits loudly with the fix — never a silent zombie. */
+const IS_DESKTOP = process.env.COOKBOOK_DESKTOP === "1";
+
+/** Run lifecycle → Bridge Local subscribers (the desktop app's notifications). */
+function emitRun(state, ws, task, agent, localMeta) {
+  if (!localServer) return;
+  try {
+    localServer.emit("run", {
+      state,
+      workspaceId: ws?.id ?? null,
+      workspaceName: ws?.name ?? null,
+      taskId: task?.id ?? null,
+      title: task?.title ?? null,
+      agent: agent?.name ?? null,
+      ...(localMeta ? { cwd: localMeta.local_cwd, mode: localMeta.local_mode } : {}),
+      at: new Date().toISOString(),
+    });
+  } catch { /* notifications are best-effort */ }
+}
+
+/** Re-read config.json into the live cfg (token, agents, folders) without a restart.
+ *  Used after connect-agents (the login refreshed the Bridge token) and by tools
+ *  that edit the file while the Bridge runs. Version gates ran at startup only. */
+function applyConfigFromDisk(cfg) {
+  if (!CONFIG_PATH) return;
+  const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+  if (raw.token && !String(raw.token).startsWith("PASTE")) cfg.token = raw.token;
+  if (raw.cookbookUrl) cfg.cookbookUrl = String(raw.cookbookUrl).replace(/\/$/, "");
+  cfg.default = raw.default;
+  cfg.localWorkspaces = raw.localWorkspaces ?? {};
+  const agents = (raw.agents ?? []).filter((a) => a.enabled !== false);
+  cfg.agents.splice(0, cfg.agents.length, ...agents);
+  // A reload usually follows connect-agents fixing the token — let the next poll
+  // re-verify from scratch instead of staying stuck in the rejected state.
+  consecutive401s = 0;
+  log(`↻ config reloaded — agents: ${agents.map((a) => a.name).join(", ") || "(none)"}`);
+}
+
+/** Re-exec this Bridge on the same argv (the self-update restart path). */
+function reexecSelf() {
+  log("↻ restarting…");
+  const child = spawn(process.execPath, process.argv.slice(1), { detached: true, stdio: "inherit" });
+  child.unref();
+  process.exit(0);
+}
+
+/** Configured agents + CLIs found on this machine, for Bridge Local's /status. */
+function detectAgentsForStatus(cfg) {
+  const rows = cfg.agents.map((a) => {
+    const cmd = Array.isArray(a.command) ? a.command[0] : null;
+    const binary = resolveBin(cmd);
+    return { name: a.name, vendor: vendorOf ? vendorOf(a) : "other", binary, found: !!binary, enabled: true, runner: a.runner ?? "cli", configured: true };
+  });
+  try {
+    for (const cli of detectClis ? detectClis() : []) {
+      if (rows.some((r) => r.vendor === cli.vendor)) continue;
+      rows.push({ name: cli.agent, vendor: cli.vendor, binary: cli.path, found: true, enabled: false, runner: cli.kind === "codex" ? "app-server" : "cli", configured: false });
+    }
+  } catch { /* detection is best-effort */ }
+  return rows;
+}
+
+function markHot(wsId) {
+  lastHotAt = Date.now();
+  if (wsId) hotWorkspaces.set(wsId, lastHotAt);
+}
+function hotWorkspaceIds() {
+  const now = Date.now();
+  const ids = new Set();
+  for (const [id, ts] of hotWorkspaces) {
+    if (now - ts < HOT_WINDOW_MS) ids.add(id);
+    else hotWorkspaces.delete(id);
+  }
+  return ids;
+}
+const givenUp = new Set();
+const skippedLogged = new Set(); // tasks we've already logged as policy-skipped
+
+// Volunteer decisions we've already made, so a PASS isn't re-asked every poll and a
+// VOLUNTEER isn't re-burned after an approval round-trip. Key: `${taskId}:${agentName}`.
+const volunteerDecisions = new Map();
+
+/**
+ * The volunteer path for one open GOAL task (stigmergy v1 — bridge/volunteer.mjs holds
+ * the pure logic; this is the I/O). For each opted-in agent, in config order:
+ * ask its OWN model the one-word capability question → on VOLUNTEER, run the same
+ * delegation-policy gate as any dispatched task (allow / ask-parks-in-inbox / off) →
+ * claim ATOMICALLY with claimed_via='volunteered' (two Bridges race in the DB; the
+ * loser just moves on). Returns {ws, task, agent} for the run queue on a won claim.
+ *
+ * v1 honesty: a volunteered task is claimed BEFORE running, so a failed run leaves it
+ * visibly claimed on the board (cancel/reassign by hand) rather than silently retried —
+ * deliberate: legible failure over invisible churn while the feature earns trust.
+ */
+// The owner's UI settings (Account → Agent delegation → Volunteering), cached one
+// minute so a busy board doesn't hammer the server. CONSENT FAILS CLOSED-ish: a
+// transient fetch failure reuses the last SUCCESSFUL value (a UI "off" must not be
+// overridden by local config during a server hiccup); only a server that genuinely
+// lacks the tool yields null = "config decides". Also where the Bridge learns its
+// own profile id (for member-scoped goal candidacy).
+let volSettingsCache = { at: 0, value: null, everSucceeded: false };
+let myProfileId = null;
+async function cachedVolunteerSettings(cfg) {
+  if (Date.now() - volSettingsCache.at > 60_000) {
+    const r = await getVolunteerSettings(cfg);
+    if (r.ok) {
+      volSettingsCache = { at: Date.now(), value: r.value, everSucceeded: true };
+      if (r.value?.profile_id) myProfileId = r.value.profile_id;
+      warnIfTokenExpiring(r.value?.token_expires_at);
+    } else {
+      volSettingsCache.at = Date.now(); // don't hammer; keep the last-good value
+    }
+  }
+  return volSettingsCache.value;
+}
+
+async function considerVolunteering(cfg, ws, task, budget) {
+  const merged = mergeVolunteerSettings(cfg, await cachedVolunteerSettings(cfg));
+  const enabled = cfg.agents.filter((a) => volunteeringEnabled(cfg, a, merged));
+  if (enabled.length === 0) return null;
+  const candidates = volunteerCandidates([task], {
+    profileId: myProfileId ?? undefined,
+    inFlight, givenUp, attempts, maxAttempts: cfg.maxAttempts,
+    decided: { get: (id) => (enabled.every((a) => volunteerDecisions.get(`${id}:${a.name}`) === "PASS") ? "PASS" : undefined) },
+  });
+  if (candidates.length === 0) return null;
+
+  for (const agent of enabled) {
+    const key = `${task.id}:${agent.name}`;
+    let decision = volunteerDecisions.get(key);
+    if (decision === "PASS") continue;
+    if (!decision) {
+      if (budget.used >= MAX_DECISIONS_PER_POLL) return null; // next poll considers the rest
+      budget.used++;
+      let answered = true;
+      try {
+        const r = await spawnAgent(agent, decisionPrompt(task, effectiveCapabilities(agent, merged) ?? agent.capabilities), cfg.decisionTimeoutSeconds ?? 90, agentEnv(cfg).env);
+        decision = parseDecision(displayText(r.out));
+      } catch {
+        // Conservative THIS poll — but a timeout/hiccup is not the model's answer,
+        // so don't cache it: caching made one cold-start permanently mute a capable
+        // agent (audit 2026-07-03 #4). The next poll re-asks.
+        decision = "PASS";
+        answered = false;
+      }
+      if (answered) volunteerDecisions.set(key, decision);
+      log(`${decision === "VOLUNTEER" ? "🙋" : "🤔"} ${agent.name} ${decision === "VOLUNTEER" ? "volunteers for" : "passed on"} goal "${task.title}"`);
+      if (decision === "PASS") continue;
+    }
+
+    // Same consent gate as a dispatched task: the OWNER's delegation policy decides.
+    // FAILS CLOSED: an unreachable policy check skips this poll (resolveDelegation
+    // itself returns "run" only for genuinely-older servers without the tool).
+    let policy;
+    try {
+      policy = await resolveDelegation(cfg, task.id);
+    } catch {
+      log(`! couldn't check delegation policy for "${task.title}" — skipping this poll (will retry)`);
+      return null;
+    }
+    if (policy.decision === "pending") {
+      if (!skippedLogged.has("volpend:" + task.id)) {
+        skippedLogged.add("volpend:" + task.id);
+        log(`⏳ volunteer claim for "${task.title}" is waiting for your approval → /account/agents`);
+      }
+      return null; // decision is cached; after approval the next poll claims + runs
+    }
+    if (policy.decision === "skip") {
+      // A daily-cap hold is temporary (resets/raises) — don't cache PASS, just wait.
+      if (policy.reason === "daily_cap") {
+        if (!skippedLogged.has("volcap:" + task.id)) {
+          skippedLogged.add("volcap:" + task.id);
+          log(`⛔ ${capHoldLine(task.assigned_by_member || task.assigned_by, policy)}`);
+        }
+        return null;
+      }
+      volunteerDecisions.set(key, "PASS"); // policy said no — stop asking
+      continue;
+    }
+
+    // The atomic claim IS the cross-Bridge race.
+    try {
+      await volunteerClaim(cfg, ws.id, task.id);
+    } catch (e) {
+      log(`… lost the volunteer race for "${task.title}" (${e.message.slice(0, 80)})`);
+      return null; // someone else has it; it's no longer open next poll
+    }
+    // Stamp locally: the queued object predates the claim (listTasks ran before it), and
+    // the run prompt tells a volunteered agent it owns the judgment calls.
+    return { ws, task: { ...task, claimed_via: "volunteered" }, agent };
+  }
+  return null;
+}
+
+async function processTask(cfg, ws, task, agent) {
+  inFlight.add(task.id);
+  // PRE-CLAIM (Phase 0, audit #1): a dispatched task must be OURS before we spend
+  // quota on it. Without this, a to:'any' task — or the same member's Bridge on a
+  // second machine — ran N times and the losers found out at the 409 after paying
+  // for the whole run. The volunteer path already pre-claimed; this makes dispatch
+  // identical. Losing the claim is a normal outcome, not an error.
+  if (task.status === "open") {
+    const claimed = await dispatchClaim(cfg, ws.id, task.id);
+    if (!claimed) {
+      inFlight.delete(task.id);
+      return; // another Bridge won the race — their run, their receipt
+    }
+    task = { ...task, ...claimed };
+  }
+  // ANCESTOR CHECK (Phase 0, audit #6): if this task rides a chain whose root was
+  // cancelled, don't burn an attempt on work the human already stopped. Server-side
+  // cascade cancels open/claimed children; this catches the in-flight-retry window.
+  if (task.chain_id && task.chain_id !== task.id) {
+    const root = await getTask(cfg, ws.id, task.chain_id).catch(() => null);
+    if (root && root.status === "cancelled") {
+      inFlight.delete(task.id);
+      givenUp.add(task.id);
+      saveRunState();
+      await abandonTask(cfg, ws.id, task.id, "parent chain was cancelled");
+      log(`⨯ skipping "${task.title}" — its chain was cancelled`);
+      return;
+    }
+  }
+  markHot(ws.id); // a live conversation — poll this workspace fast until it quiets
+  attempts.set(task.id, (attempts.get(task.id) ?? 0) + 1);
+  saveRunState();
+  const n = attempts.get(task.id);
+  log(`→ waking ${agent.name} for "${task.title}" in ${ws.name} (attempt ${n}/${cfg.maxAttempts})`);
+  let resume = null; // hoisted: the catch path needs to know if the run RESUMED a session
+  try {
+    // Recall-injection: the team's relevant memory rides into the prompt (best-effort;
+    // [] on any failure — memory must never block a run). Query = the task title.
+    // Composer follow-ups (0064) skip recall entirely: a resumed session already
+    // carries what rode into the original run, and crediting notes that never rode
+    // into THIS prompt would corrupt the outcome-weighted signal.
+    const { memories, conventions } = task.thread_root_id
+      ? { memories: [], conventions: [] }
+      : await recallMemories(cfg, ws.id, task.title);
+    // Credit both classes on verified completion — conventions earn helpful_count too
+    // (the outcome signal that ranks proven rules first).
+    const recalledIds = [...memories, ...conventions].map((m) => m && m.id).filter(Boolean);
+    if (memories.length) log(`  ↳ injecting ${memories.length} team-memory note${memories.length === 1 ? "" : "s"}`);
+    if (conventions.length) log(`  ↳ + ${conventions.length} team convention${conventions.length === 1 ? "" : "s"} (verbatim)`);
+    // Proactive cross-workspace recall: proven knowledge from the member's OTHER projects
+    // (a playbook, a gotcha) surfaces here without being pointed at it. Best-effort.
+    const crossWorkspace = task.thread_root_id ? [] : await recallAcrossWorkspaces(cfg, task.title, ws.id, 3);
+    if (crossWorkspace.length) log(`  ↳ + ${crossWorkspace.length} proven note${crossWorkspace.length === 1 ? "" : "s"} from your other projects`);
+    const startedAt = Date.now();
+    // Live ticker: stream in-flight token counts to the board so the assigner watches
+    // the cost accrue. Fire-and-forget + swallow errors — a progress hiccup must never
+    // touch the run. (report_task_progress is a no-op once the task leaves 'claimed'.)
+    let lastProgressPost = 0;
+    let localMeta = null; // { local_cwd, local_mode } once local access is decided below
+    const onProgress = (p) => {
+      if (Date.now() - lastProgressPost < 1000) return;
+      lastProgressPost = Date.now();
+      reportTaskProgress(cfg, ws.id, task.id, localMeta ? { ...p, ...localMeta } : p).catch(() => {});
+    };
+    // Retry attempts CONTINUE, not redo (Phase 1): with a saved claude session the
+    // prompt is just the next message in the resumed conversation; without one, the
+    // fresh prompt carries the failure + a don't-redo-finished-work instruction.
+    const retry = n > 1 ? retryCtx.get(task.id) ?? null : null;
+    // COMPOSER THREAD (0064): a follow-up run continues the thread's conversation.
+    // The freshest session_ref across the thread (server-side, survives restarts) is
+    // the resume handle; resume only works for claude commands (resumeCommand no-ops
+    // otherwise), so the cold-baton prompt is ALWAYS the fallback shape. A retry of
+    // this very task (retryCtx) outranks the thread handle — it's strictly newer.
+    // LOCAL ACCESS (terminal parity): a SELF-assigned task in a locally-mapped
+    // workspace runs IN the mapped folder with real tools. Teammate-assigned
+    // tasks never qualify (assigner ≠ claimer). The agent object is shadowed so
+    // every runner path downstream inherits cwd + widened tools consistently.
+    const localMap = cfg.localWorkspaces[ws.id];
+    const selfAssigned = task.assigned_by_profile && task.claimed_by_profile && task.assigned_by_profile === task.claimed_by_profile;
+    const local = localMap && selfAssigned && localMap.cwd ? localMap : null;
+    if (local) {
+      const mode = local.mode ?? modeForTools?.(local.allowedTools) ?? "run";
+      agent = { ...agent, command: localizeCommand(agent.command, local.allowedTools), cwd: local.cwd };
+      localMeta = { local_cwd: local.cwd, local_mode: mode };
+      log(`  ↳ local access: running in ${local.cwd} (${mode}) with real tools (self-assigned)`);
+      // Tell the thread right away where this run lives (the receipt shows it).
+      reportTaskProgress(cfg, ws.id, task.id, { stage: `local: ${local.cwd}`, ...localMeta }).catch(() => {});
+    }
+    emitRun("started", ws, task, agent, localMeta);
+    // PERSISTENT RUNNER (terminal feel, opt-in): a live process for this thread means
+    // the conversation is already in memory — the prompt is just the next message,
+    // and the server-side session lookup (a full list_tasks) is skippable.
+    // Key includes the AGENT (vendor-switch safety) and the LOCAL flag — a jailed
+    // warm process must never serve a local turn, nor vice versa.
+    const threadKey = `${task.thread_root_id ?? task.id}::${agent.name}${local ? "::local" : ""}`;
+    const runnerEligible = cfg.persistentThreads && !retry && agent.runner !== "app-server" && agent.runner !== "robot";
+    let warmRunner = runnerEligible ? hasRunner(threadKey) : null;
+    // ADOPT a pre-warmed runner (0065) for a NEW conversation: the process booted
+    // while the member was still typing, so their first words hit a live agent.
+    if (!warmRunner && runnerEligible && !task.thread_root_id && !local) {
+      // (Local runs never adopt from the warm pool — pooled processes are jailed
+      // to workspace tools and the wrong cwd.)
+      warmRunner = adoptRunner(`warm::${ws.id}::${agent.name}`, threadKey);
+      if (warmRunner) log(`  ↳ adopted a pre-warmed ${agent.name} — first message hits a live process`);
+    }
+    let thread = null;
+    if (task.thread_root_id && !warmRunner) {
+      thread = await threadResumeContext(cfg, ws.id, task.thread_root_id).catch(() => null);
+      if (thread?.root?.status === "cancelled") {
+        inFlight.delete(task.id);
+        givenUp.add(task.id);
+        saveRunState();
+        await abandonTask(cfg, ws.id, task.id, "thread was cancelled");
+        log(`⨯ skipping "${task.title}" — its thread was cancelled`);
+        return;
+      }
+    }
+    // A RETRY never thread-resumes (retryCtx null-session means the resumed session
+    // itself failed — go cold on the baton; thread.root still feeds it context).
+    const threadSession = !retry ? thread?.sessionRef ?? null : null;
+    const canResumeThread = threadSession && resumeCommand(agent.command, threadSession).resumed;
+    // Codex keeps its own conversation map (persistent app-server threads).
+    const codexWarm = agent.runner === "app-server" && hasCodexThread(task.thread_root_id ?? task.id);
+    const conversationWarm = !!warmRunner || !!canResumeThread || codexWarm;
+    // CHAT LANE (bridgeFiles): the agent's final message IS the result and the
+    // Bridge files it — saves a whole model round-trip (the complete_task tool
+    // call) plus the verify fetch, every single turn. Applies to claude runners
+    // AND the persistent codex server (its final agent message is the answer).
+    const bridgeFiles = cfg.persistentThreads && agent.runner !== "robot";
+    let basePrompt = task.thread_root_id
+      ? buildThreadFollowUpPrompt(ws, task, { resumed: conversationWarm, root: thread?.root ?? null, bridgeFiles })
+      : buildPrompt(ws, task, { memories, conventions, crossWorkspace, volunteered: task.claimed_via === "volunteered", bridgeFiles });
+    if (local) {
+      basePrompt += `\n\nLOCAL ACCESS: you are running ON the member's machine in ${local.cwd} — this folder is the workspace's local project. You have real file and shell tools; use them for the actual work (build artifacts, code, sites live HERE). Mirror durable outcomes into the Cookbook workspace (files / remember) so the team side stays true.`;
+    }
+    const prompt = retry?.sessionId
+      ? `Your previous attempt on this task was interrupted: ${String(retry.reason ?? "unknown failure").slice(0, 300)}. ` +
+        `Continue EXACTLY where you left off — do not redo completed work. If you are close, finish and call complete_task; ` +
+        `if the task is impossible from this environment, call abandon_task with the reason.`
+      : retry
+        ? `${basePrompt}\n\nNOTE: a previous attempt failed (${String(retry.reason ?? "unknown").slice(0, 300)}). ` +
+          `Check the workspace and memory for work already done — continue it, don't redo it.`
+        : basePrompt;
+    if (retry?.sessionId) log(`  ↳ resuming previous session (continue, not redo)`);
+    else if (warmRunner) log(`  ↳ warm thread runner — message goes straight to the live process`);
+    else if (canResumeThread) log(`  ↳ resuming the thread's conversation (Composer follow-up)`);
+    else if (task.thread_root_id) log(`  ↳ thread follow-up, no resumable session — running with the cold baton`);
+    resume = retry ?? (canResumeThread ? { sessionId: threadSession } : null);
+    let result = null;
+    if (cfg.persistentThreads && !retry && agent.runner !== "app-server" && agent.runner !== "robot") {
+      // Runner path: existing warm process, or boot one (resuming the thread's
+      // saved session when there is one). ANY runner failure falls back to the
+      // one-shot spawn below — the runner is an accelerator, never a dependency.
+      try {
+        const live = cfg.liveTokens !== false && agent.liveTokens !== false;
+        const r = warmRunner ?? runnerFor({
+          threadId: threadKey,
+          agent,
+          env: agentEnv(cfg).env,
+          resumeSessionId: canResumeThread ? threadSession : null,
+          helpers: { fold: foldStreamLine, textFrom: textFromStreamLine, sessionFrom: sessionIdFrom },
+          log,
+        });
+        result = await r.send(prompt, {
+          onProgress: live ? onProgress : undefined,
+          timeoutMs: cfg.taskTimeoutSeconds * 1000,
+          livenessMs: (cfg.livenessTimeoutSeconds ?? 0) * 1000,
+        });
+      } catch (e) {
+        if (/busy|not a claude-shaped/.test(e.message)) {
+          log(`  ↳ runner unavailable (${e.message}) — one-shot fallback`);
+          result = null;
+        } else {
+          throw e; // real failure: ride the existing retry/abandon machinery
+        }
+      }
+    }
+    if (!result) result = await runAgent(cfg, agent, prompt, onProgress, resume, { ws, task });
+    if (result && result.sessionId) retryCtx.set(task.id, { sessionId: result.sessionId, reason: retryCtx.get(task.id)?.reason ?? null });
+    let after;
+    if (bridgeFiles) {
+      // File the final message as the result (agent may still have abandoned or
+      // self-completed via tools — any conflict just falls back to reading state).
+      const finalText = displayText(result?.out).trim().slice(0, 20_000);
+      // Success shape differs by runner: claude one-shots exit 0; the codex server
+      // resolves with a turn status (no exit code) — failed statuses fall through.
+      const cleanExit = result?.code === 0 || (result?.code === undefined && !/failed/i.test(String(result?.status ?? "")));
+      if (finalText && cleanExit) {
+        try {
+          await completeTaskApi(cfg, ws.id, task.id, finalText);
+          after = { status: "done" };
+        } catch {
+          after = await getTask(cfg, ws.id, task.id);
+        }
+      } else {
+        after = await getTask(cfg, ws.id, task.id);
+      }
+    } else {
+      after = await getTask(cfg, ws.id, task.id);
+    }
+    if (after?.status === "done") {
+      retryCtx.delete(task.id);
+      log(`✓ ${agent.name} completed "${task.title}"`);
+      emitRun("done", ws, task, agent, localMeta);
+      // Outcome signal: credit the memory notes that rode into this SUCCESSFUL run,
+      // so proven notes surface first next time (outcome-weighted recall). Best-effort.
+      if (recalledIds.length) creditRecall(cfg, ws.id, recalledIds).catch(() => {});
+      // Quota visibility: tell Cookbook what this run cost (tokens/cost from the CLI's
+      // own report when available, wall time always) so the assigner sees the price of
+      // the delegation. Fire-and-forget — a usage hiccup must never fail a done task.
+      try {
+        const usage = extractUsage(result, agent.name, Date.now() - startedAt);
+        if (usage) {
+          await reportTaskUsage(cfg, ws.id, task.id, usage);
+          const tok = (usage.input_tokens ?? 0) + (usage.output_tokens ?? 0);
+          log(`  ↳ usage reported${tok ? `: ${tok.toLocaleString()} tokens` : ""}${usage.cost_usd ? ` · ~$${usage.cost_usd.toFixed(2)}` : ""}`);
+        }
+      } catch (e) {
+        log(`  ↳ usage report skipped (${e.message})`);
+      }
+    } else {
+      // The agent CLI exited but the task isn't done — surface WHY (login/MCP/tools),
+      // instead of the old silent "ran but isn't marked done". This is the line that
+      // turns a multi-hour debug into a one-glance fix.
+      const hint = failureHint(result);
+      const why = hint ? ` — ${hint}` : "";
+      if (n >= cfg.maxAttempts) {
+        givenUp.add(task.id);
+        saveRunState();
+        // Final attempt: account the burn (see catch path). extractUsage reads the
+        // CLI's own final report when the run exited but didn't complete the task.
+        try {
+          const burned = extractUsage(result, agent.name, Date.now() - startedAt);
+          if (burned) reportTaskUsage(cfg, ws.id, task.id, burned).catch(() => {});
+        } catch { /* accounting only — never let it touch the failure path */ }
+        // HAND BACK LOUDLY (Phase 0, audit #2/#8): mark it abandoned with the hint
+        // so the ASSIGNER sees "tried, gave up, here's why" on the board — instead
+        // of a task that silently rots open (or strands claimed, invisible to all).
+        retryCtx.delete(task.id);
+        await abandonTask(cfg, ws.id, task.id, hint || `ran ${n} attempt(s) without completing`);
+        emitRun("failed", ws, task, agent, localMeta);
+        log(`✗ ${agent.name} didn't complete "${task.title}" after ${n} attempts${why} — handed back as abandoned.`);
+      } else {
+        // THREAD SELF-HEAL: if this attempt RESUMED a session and still failed, the
+        // session itself may be the problem (e.g. a safeguard refusing the replayed
+        // transcript) — retry COLD on the baton instead of resuming into the same
+        // wall. The cold run's own session_ref then becomes the thread's freshest
+        // handle, so future replies resume a healthy conversation.
+        const resumedAndFailed = task.thread_root_id && resume?.sessionId;
+        retryCtx.set(task.id, {
+          sessionId: resumedAndFailed ? null : result?.sessionId ?? retryCtx.get(task.id)?.sessionId ?? null,
+          reason: hint || "ran but did not complete the task",
+        });
+        saveRunState();
+        // EVERY failed run is a CLAIMED task now (Phase 0 pre-claims dispatch too),
+        // so every one must ride the retry shelf or it strands invisible to the
+        // open scan. (Pre-fix this was volunteered-only: assigned tasks whose
+        // attempt 1 failed logged "will retry" and never did.)
+        volunteeredRetries.push({ ws, task, agent });
+        log(`… ${agent.name} ran but the task isn't marked done${why} — will retry${retryCtx.get(task.id)?.sessionId ? " (resumable)" : ""}.`);
+      }
+    }
+  } catch (e) {
+    if (n >= cfg.maxAttempts) {
+      givenUp.add(task.id);
+      saveRunState();
+      retryCtx.delete(task.id);
+      await abandonTask(cfg, ws.id, task.id, e.message || "failed after final attempt");
+      emitRun("failed", ws, task, agent, null);
+      // FINAL attempt failed: report what the failed runs actually burned, so the
+      // chain token budget sees it. Only on the LAST attempt — usage is first-
+      // report-wins, and an earlier report would block a successful retry's real
+      // one. Best-effort: the server rejects states it won't account (e.g. open).
+      if (e.partialUsage) {
+        reportTaskUsage(cfg, ws.id, task.id, {
+          ...e.partialUsage,
+          duration_ms: e.elapsedMs ?? 0,
+          runner: agent.name,
+        }).then(() => {
+          const tok = (e.partialUsage.input_tokens ?? 0) + (e.partialUsage.output_tokens ?? 0);
+          log(`  ↳ burned quota reported despite failure: ${tok.toLocaleString()} tokens`);
+        }).catch(() => {});
+      }
+    }
+    // A volunteered task is CLAIMED — invisible to the open scan — so the throw
+    // branch (timeouts are the COMMON failure here) must feed the retry shelf
+    // exactly like the ran-but-not-done branch, or the claim strands.
+    else {
+      // Same thread self-heal as the ran-not-done branch: a failed RESUMED thread
+      // attempt retries cold rather than back into the same session.
+      const resumedAndFailed = task.thread_root_id && resume?.sessionId;
+      retryCtx.set(task.id, { sessionId: resumedAndFailed ? null : e.sessionId ?? retryCtx.get(task.id)?.sessionId ?? null, reason: e.message });
+      saveRunState();
+      volunteeredRetries.push({ ws, task, agent }); // all claimed failures ride the shelf (see above)
+    }
+    const slow = /timed out after (\d+)s/.exec(e.message);
+    lastRunError = `${agent.name}: ${String(e.message).slice(0, 300)}`;
+    log(`✗ ${agent.name} error on "${task.title}": ${e.message}${slow ? ` — the run hit taskTimeoutSeconds (${slow[1]}s); raise it in config.json if this task is just slow` : ""}`);
+  } finally {
+    inFlight.delete(task.id);
+    markHot(ws.id); // the reply usually lands right after a run finishes — stay fast for it
+  }
+}
+
+let consecutive401s = 0;
+
+// Warn (once per day) when the Bridge token is within 14 days of expiry — the
+// alternative is a silent death into 401s weeks later (audit 2026-07-03 #9).
+// Pairs with the 5x401 loud exit above: warned before, clean exit after.
+let lastExpiryWarnDay = "";
+function warnIfTokenExpiring(expiresAt) {
+  if (!expiresAt) return;
+  const daysLeft = Math.floor((new Date(expiresAt).getTime() - Date.now()) / 86_400_000);
+  if (daysLeft > 14) return;
+  const today = new Date().toISOString().slice(0, 10);
+  if (lastExpiryWarnDay === today) return;
+  lastExpiryWarnDay = today;
+  log(`! this Bridge's token expires in ${Math.max(daysLeft, 0)} day(s) — re-run \`node bridge/bridge.mjs login\` before it does.`);
+}
+
+let wsCursor = 0;
+/** ONE-CALL fast dispatch: list_open_work across every workspace in a single HTTP
+ *  round-trip, then the same eligibility pipeline as the sweep (goal/volunteer,
+ *  pending/skip messaging, and stale-claim rescue stay on the full sweep — this is
+ *  the 1s dispatch lane, not the janitor). Returns false when the server predates
+ *  the tool so the caller can fall back to sweeps. */
+async function quickScan(cfg) {
+  const { supported, work, warmHints } = await listOpenWork(cfg);
+  if (!supported) return false;
+  await dispatchWork(cfg, work, warmHints);
+  return true;
+}
+
+// ── THE PUSH CHANNEL (SSE) ────────────────────────────────────────────────────
+// One outbound connection; the server pushes open work + warm hints the moment
+// they change (~sub-second dispatch). Connections are short-lived by design
+// (serverless-honest); this loop reconnects forever. A server without the route
+// marks it unsupported and the 1s poll carries on — push is an accelerator,
+// never a dependency.
+const sse = { connected: false, supported: true, aliveAt: 0 };
+
+function parseSseFrame(frame) {
+  let event = "message";
+  let data = "";
+  for (const line of frame.split("\n")) {
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    else if (line.startsWith("data:")) data += line.slice(5).trim();
+  }
+  return { event, data };
+}
+
+async function socketLoop(cfg) {
+  let announced = false;
+  while (!sseStopped && sse.supported) {
+    try {
+      const res = await fetch(`${cfg.cookbookUrl}/api/bridge/stream`, {
+        headers: { Authorization: `Bearer ${cfg.token}` },
+      });
+      if (res.status === 404 || res.status === 405) {
+        sse.supported = false;
+        log("· server has no push channel — dispatching on the 1s poll");
+        return;
+      }
+      if (!res.ok || !res.body) throw new Error(`stream ${res.status}`);
+      sse.connected = true;
+      sse.aliveAt = Date.now();
+      if (!announced) {
+        announced = true;
+        log("⚡ push channel connected — dispatch is now sub-second");
+      }
+      const reader = res.body.getReader();
+      const dec = new TextDecoder();
+      let buf = "";
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        sse.aliveAt = Date.now();
+        buf += dec.decode(value, { stream: true });
+        let i;
+        while ((i = buf.indexOf("\n\n")) >= 0) {
+          const frame = buf.slice(0, i);
+          buf = buf.slice(i + 2);
+          if (!frame.trim() || frame.startsWith(":")) continue;
+          const ev = parseSseFrame(frame);
+          if (ev.event === "work" && ev.data) {
+            try {
+              const j = JSON.parse(ev.data);
+              void dispatchWork(cfg, j.work ?? [], j.warm_hints ?? []);
+            } catch { /* malformed frame — next snapshot covers */ }
+          }
+        }
+      }
+    } catch { /* transient — reconnect below */ }
+    sse.connected = false;
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+}
+let sseStopped = false;
+
+/** The ONE dispatch pipeline — fed by the push channel (SSE) and the 1s poll alike.
+ *  Re-entrancy-guarded: overlapping snapshots are redundant (each is a full picture),
+ *  and claim CAS + inFlight make any stragglers harmless anyway. */
+let dispatchBusy = false;
+async function dispatchWork(cfg, work, warmHints) {
+  if (dispatchBusy) return;
+  dispatchBusy = true;
+  try {
+    await dispatchWorkInner(cfg, work, warmHints);
+  } finally {
+    dispatchBusy = false;
+  }
+}
+
+async function dispatchWorkInner(cfg, work, warmHints) {
+  // PRE-WARM (0065): the chat surface hinted a conversation is imminent — boot the
+  // runner NOW so the first message hits a live process instead of a cold spawn.
+  if (cfg.persistentThreads) {
+    for (const h of warmHints ?? []) {
+      const agent = agentFor(cfg, h.agent);
+      if (!agent || agent.runner === "app-server" || agent.runner === "robot") continue;
+      warmUp({
+        poolKey: `warm::${h.workspace_id}::${agent.name}`,
+        agent,
+        env: agentEnv(cfg).env,
+        helpers: { fold: foldStreamLine, textFrom: textFromStreamLine, sessionFrom: sessionIdFrom },
+        log,
+      });
+    }
+  }
+  const queue = [];
+  // RETRY SHELF drains here too — the fast lane demoted the full sweep to a 30s
+  // janitor, which silently made every retry wait up to 30s (Diego's SaaS thread,
+  // 2026-08-20: fail at :26, retry at :03). A failed CLAIMED task must re-attempt
+  // on the next second, exactly like fresh work.
+  while (volunteeredRetries.length > 0) {
+    const retry = volunteeredRetries.shift();
+    if (inFlight.has(retry.task.id) || givenUp.has(retry.task.id)) continue;
+    if ((attempts.get(retry.task.id) ?? 0) >= cfg.maxAttempts) continue;
+    try {
+      const fresh = await getTask(cfg, retry.ws.id, retry.task.id);
+      if (fresh && fresh.status === "claimed") queue.push(retry);
+    } catch {
+      volunteeredRetries.push(retry); // transient — try again next scan
+      break;
+    }
+  }
+  for (const t of work) {
+    if ((t.assigned_to || "").toLowerCase() === "goal") continue;
+    if (inFlight.has(t.id) || givenUp.has(t.id)) continue;
+    if ((attempts.get(t.id) ?? 0) >= cfg.maxAttempts) continue;
+    const agent = agentFor(cfg, t.assigned_to);
+    if (!agent) continue;
+    if (!allowedByPolicy(cfg, agent, t)) continue;
+    let policy;
+    try { policy = await resolveDelegation(cfg, t.id); } catch { continue; }
+    if (policy.decision !== "run") continue;
+    queue.push({ ws: { id: t.workspace_id, name: t.workspace_name ?? "workspace" }, task: t, agent });
+  }
+  queue.sort((a, b) => new Date(a.task.created_at ?? 0) - new Date(b.task.created_at ?? 0));
+  const slots = Math.max(0, cfg.maxConcurrentRuns - inFlight.size);
+  for (const item of queue.slice(0, slots)) {
+    void processTask(cfg, item.ws, item.task, item.agent).catch((e) => log(`✗ run error on "${item.task.title}": ${e.message}`));
+  }
+}
+
+async function pollOnce(cfg, onlyWorkspaceIds = null) {
+  let workspaces = await listWorkspaces(cfg);
+  // HOT-SCOPED SWEEP (chat feel): a full sweep across N workspaces costs N HTTP
+  // round-trips — 12 workspaces ≈ 15s, which WAS the reply latency users felt.
+  // While a conversation is hot, in-between sweeps scan only its workspace(s);
+  // the full-fairness sweep still runs on the normal cadence.
+  if (onlyWorkspaceIds) workspaces = workspaces.filter((w) => onlyWorkspaceIds.has(w.id));
+  // FAIRNESS (Phase 1, audit #3): rotate which workspace is scanned first each
+  // poll — scan order used to decide who ate the volunteer budget and the run
+  // slots, starving every workspace after a busy one.
+  if (workspaces.length > 1) {
+    const k = wsCursor++ % workspaces.length;
+    workspaces = [...workspaces.slice(k), ...workspaces.slice(0, k)];
+  }
+  consecutive401s = 0;
+  // Collect eligible (open, managed, not in-flight, not given-up) tasks.
+  const queue = [];
+  // Failed volunteered runs retry first — they're claimed by us, invisible to the
+  // open scan. Verify the task is still live (not completed/cancelled by a human).
+  while (volunteeredRetries.length > 0) {
+    const retry = volunteeredRetries.shift();
+    if (inFlight.has(retry.task.id) || givenUp.has(retry.task.id)) continue;
+    if ((attempts.get(retry.task.id) ?? 0) >= cfg.maxAttempts) continue;
+    try {
+      const fresh = await getTask(cfg, retry.ws.id, retry.task.id);
+      if (fresh && fresh.status === "claimed") queue.push(retry);
+    } catch { volunteeredRetries.push(retry); break; } // server unreachable — retry next poll
+  }
+  // Per-poll budget for volunteer decisions (each is a model call on the owner's quota).
+  const decisionBudget = { used: 0 };
+  for (const ws of workspaces) {
+    let tasks;
+    try {
+      tasks = await listTasks(cfg, ws.id, "open");
+    } catch (e) {
+      log(`! couldn't list tasks for ${ws.name}: ${e.message}`);
+      continue;
+    }
+    for (const t of tasks) {
+      if (inFlight.has(t.id) || givenUp.has(t.id)) continue;
+      if ((attempts.get(t.id) ?? 0) >= cfg.maxAttempts) continue;
+
+      // Open GOAL → the volunteer path (stigmergy), never the dispatch path. OFF unless
+      // an agent opted in (`"volunteer": true`) under the master switch (`volunteering`).
+      if ((t.assigned_to || "").toLowerCase() === "goal") {
+        const claimed = await considerVolunteering(cfg, ws, t, decisionBudget);
+        if (claimed) queue.push(claimed); // {ws, task, agent} — claim already won
+        continue;
+      }
+
+      const agent = agentFor(cfg, t.assigned_to);
+      if (!agent) continue; // no local agent handles this assignee
+
+      // Optional extra LOCAL allowlist (config acceptFrom; default "anyone").
+      if (!allowedByPolicy(cfg, agent, t)) {
+        if (!skippedLogged.has(t.id)) {
+          skippedLogged.add(t.id);
+          log(`⊘ skipping "${t.title}" — assigned by ${t.assigned_by_member || t.assigned_by}, not in ${agent.name}'s local acceptFrom. Left open.`);
+        }
+        continue;
+      }
+
+      // UI-managed delegation policy (allow / ask / off), enforced by Cookbook.
+      // FAILS CLOSED: consent unknown = don't run this poll. resolveDelegation
+      // returns "run" itself for genuinely-older servers (unknown tool), so the
+      // catch here only fires on transient failures — the task stays open and
+      // is re-checked next poll.
+      let policy;
+      try {
+        policy = await resolveDelegation(cfg, t.id);
+      } catch {
+        if (!skippedLogged.has("warn:" + t.id)) {
+          skippedLogged.add("warn:" + t.id);
+          log(`! couldn't check delegation policy for "${t.title}" — holding it until the check succeeds.`);
+        }
+        continue;
+      }
+      if (policy.decision === "pending") {
+        if (!skippedLogged.has("pend:" + t.id)) {
+          skippedLogged.add("pend:" + t.id);
+          log(`⏳ "${t.title}" (from ${t.assigned_by_member || t.assigned_by}) is waiting for your approval → /account/agents`);
+        }
+        continue;
+      }
+      if (policy.decision === "skip") {
+        // A daily-cap hold is temporary — log it distinctly (re-logs if the cap changes).
+        const capMsg = policy.reason === "daily_cap"
+          ? `⛔ ${capHoldLine(t.assigned_by_member || t.assigned_by, policy)}`
+          : `⊘ "${t.title}" blocked by your delegation policy. Left open.`;
+        const key = policy.reason === "daily_cap" ? "cap:" + t.id : t.id;
+        if (!skippedLogged.has(key)) {
+          skippedLogged.add(key);
+          log(capMsg);
+        }
+        continue;
+      }
+      queue.push({ ws, task: t, agent });
+    }
+  }
+  // PARALLEL SLOTS + FAIRNESS (Phase 1). Launch up to maxConcurrentRuns without
+  // blocking the poll loop (inFlight dedupes across polls; the pre-claim makes a
+  // double-launch a no-op even across Bridges). Oldest task first — newest-first
+  // starved old tasks under a steady stream of new ones (audit #3).
+  queue.sort((a, b) => new Date(a.task.created_at ?? 0) - new Date(b.task.created_at ?? 0));
+  const slots = Math.max(0, cfg.maxConcurrentRuns - inFlight.size);
+  for (const item of queue.slice(0, slots)) {
+    void processTask(cfg, item.ws, item.task, item.agent).catch((e) => {
+      inFlight.delete(item.task.id);
+      log(`! run crashed unexpectedly for "${item.task.title}": ${e.message}`);
+    });
+  }
+}
+
+/** How often a RUNNING bridge re-checks the deploy manifest ("app updated → I update"). */
+const UPDATE_CHECK_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * WHO OWNS THIS INSTALL'S VERSION.
+ *
+ * The Bridge shipped with a bespoke self-updater because it was the only channel: an
+ * unpacked tar has no package manager behind it. Where a real channel DOES exist,
+ * rewriting our own files is wrong and has bitten us (2026-08-22: writing inside the
+ * signed .app broke its code seal and voided notarization). So:
+ *
+ *   "app"  — the desktop shell spawned us (COOKBOOK_DESKTOP=1). The app ships, signs
+ *            and notarizes the runtime with itself and re-seeds on upgrade. Never
+ *            self-update: that is what corrupted the bundle.
+ *   "npm"  — installed as a package (node_modules, npx cache, or a package.json next
+ *            to us). npm is the channel; rewriting files under it fights the package
+ *            manager and can poison an npx cache. Nag with the update command.
+ *   "self" — a bare unpacked tar. No other channel exists, so keep the original
+ *            behavior: verify, back up, replace, re-exec.
+ */
+function updateChannel() {
+  if (IS_DESKTOP) return "app";
+  if (HERE.includes(`${path.sep}node_modules${path.sep}`)) return "npm";
+  if (fs.existsSync(path.join(HERE, "package.json"))) return "npm";
+  return "self";
+}
+
+let updateNagged = false;
+
+/**
+ * Self-update pass. Only the "self" channel applies anything (see updateChannel).
+ * autoUpdate !== false (default ON): apply + re-exec so fleets track app deploys.
+ * autoUpdate === false: loud nag only — the version is pinned by the user.
+ * Check failures are non-fatal (offline is fine); a FAILED apply never breaks the
+ * running code (verification happens before any write; originals in bridge.backup/).
+ */
+async function selfUpdate(cfg, { reexec }) {
+  let check;
+  try {
+    check = await checkForUpdate(cfg, HERE);
+  } catch {
+    return; // can't reach the manifest — never block on updates
+  }
+  if (check.changed.length === 0) return;
+  const channel = updateChannel();
+  if (channel !== "self") {
+    // Say it once per process: drift should be visible, not noisy, and never silent.
+    if (!updateNagged) {
+      updateNagged = true;
+      log(
+        channel === "app"
+          ? `⬆ A newer Bridge ships with the app (deploy ${check.version}). The Cookbook app manages this copy — update the app to pick it up.`
+          : `⬆ A newer Bridge is available (deploy ${check.version}). Update it with:  npx cookbook-bridge@latest connect`,
+      );
+    }
+    return;
+  }
+  if (cfg.autoUpdate === false) {
+    log(`⬆ Bridge update available (deploy ${check.version}; ${check.changed.length} file(s) changed) — run \`node bridge.mjs update\`. (autoUpdate is off.)`);
+    return;
+  }
+  try {
+    const replaced = await applyUpdate(cfg, HERE, check);
+    log(`⬆ Bridge self-updated to deploy ${check.version} (${replaced.length} file(s), hash-verified; previous in bridge.backup/${check.version}/).`);
+    if (reexec) {
+      log("↻ restarting on the new code…");
+      const { spawn } = await import("node:child_process");
+      const child = spawn(process.execPath, process.argv.slice(1), { detached: true, stdio: "inherit" });
+      child.unref();
+      process.exit(0);
+    }
+  } catch (e) {
+    log(`! self-update failed safely (${e.message}) — still on the previous version.`);
+  }
+}
+
+async function main() {
+  await loadRuntime();
+  const cfg = loadConfig();
+  log(`Cookbook Bridge started · ${cfg.cookbookUrl}`);
+  log(`Managing: ${cfg.agents.map((a) => a.name).join(", ") || "(no agents enabled!)"} · polling every ${cfg.pollSeconds}s`);
+
+  // "When the app updates, so does the Bridge": check the deploy manifest now, then
+  // every 6h while running. Set "autoUpdate": false in config to pin.
+  await selfUpdate(cfg, { reexec: true });
+  let lastUpdateCheck = Date.now();
+
+  // Loud warning if the default agent (the one that runs "any"-assigned tasks) isn't
+  // actually installed — otherwise those tasks silently route to a missing CLI. Run
+  // `node bridge.mjs doctor` for the full preflight.
+  const dflt = agentFor(cfg, "any");
+  if (!dflt) {
+    log(`! no default agent — "any"-assigned tasks won't run. Set "default" in config to an enabled agent.`);
+  } else {
+    // agentFor falls back to agents[0] when "default" names a missing/disabled
+    // agent — silent rerouting is exactly the surprise class; say it out loud.
+    if (cfg.default && dflt.name !== cfg.default) {
+      log(`! config "default" is "${cfg.default}" but no enabled agent has that name — "any"-assigned tasks route to ${dflt.name}.`);
+    }
+    if (!resolveBin(Array.isArray(dflt.command) ? dflt.command[0] : null)) {
+      log(`! default agent "${dflt.name}" isn't installed/on PATH — "any"-assigned tasks will fail. Run \`node bridge.mjs doctor\`.`);
+    }
+  }
+
+  let stopped = false;
+  process.on("SIGINT", () => {
+    stopped = true;
+    log("Stopping…");
+    process.exit(0);
+  });
+
+  // Billing protection: say what's being stripped from agent processes (once).
+  const { stripped } = agentEnv(cfg);
+  if (stripped.length) {
+    log(`Billing protection: ${stripped.join(", ")} hidden from agent processes so tasks run on your SUBSCRIPTION, never your API account. (Opt out: "allowApiKeyBilling": true in config.)`);
+  }
+
+  // Gemini version gate: refuse to run gemini agents below the RCE-fix version.
+  // cfg.agents is pre-filtered at load and matching never re-checks `enabled`, so a
+  // vulnerable agent must be REMOVED from the list, not just flagged.
+  const vulnerableAgents = new Set();
+  for (const agent of cfg.agents.filter((a) => isGeminiCommand(a.command?.[0]))) {
+    const { version, vulnerable } = await checkGeminiVersion([agent.command[0]]);
+    if (vulnerable) {
+      vulnerableAgents.add(agent);
+      console.error(
+        `!! ${agent.name}: gemini-cli ${version} has a critical (CVSS 10.0) prompt-injection RCE — ` +
+        `agent DISABLED for this run. Update to ≥ ${GEMINI_MIN_VERSION} (npm i -g @google/gemini-cli@latest) and restart.`,
+      );
+    } else if (!version) {
+      log(`! ${agent.name}: couldn't read gemini version — make sure it's ≥ ${GEMINI_MIN_VERSION} (RCE fix).`);
+    }
+  }
+  if (vulnerableAgents.size) cfg.agents = cfg.agents.filter((a) => !vulnerableAgents.has(a));
+
+  // Agy (Antigravity) version gate: below 1.1.1 headless -p can't call MCP tools —
+  // the task "runs" but complete_task never lands, burning every attempt. Same
+  // remove-don't-flag rule as the gemini gate (matching never re-checks enabled).
+  const tooOldAgy = new Set();
+  for (const agent of cfg.agents.filter((a) => isAgyCommand(a.command?.[0]))) {
+    const { version, tooOld } = await checkAgyVersion([agent.command[0]]);
+    if (tooOld) {
+      tooOldAgy.add(agent);
+      console.error(
+        `!! ${agent.name}: agy ${version} can't call MCP tools headlessly (fixed in ${AGY_MIN_VERSION}) — ` +
+        `agent DISABLED for this run. Run \`agy update\` and restart.`,
+      );
+    } else if (!version) {
+      log(`! ${agent.name}: couldn't read agy version — make sure it's >= ${AGY_MIN_VERSION} (headless MCP fix).`);
+    }
+  }
+  if (tooOldAgy.size) cfg.agents = cfg.agents.filter((a) => !tooOldAgy.has(a));
+
+  // BRIDGE LOCAL: the loopback control API (desktop app buttons: connect agents,
+  // connect a folder, doctor, restart). Started BEFORE the token check on purpose:
+  // the whole point of the connect UI is to FIX a broken/missing connection, so its
+  // control plane must be up even when the Cookbook token is bad. Additive — a bind
+  // failure never stops the Bridge from doing its real job.
+  try {
+    let version = "dev";
+    try {
+      const { createHash } = await import("node:crypto");
+      version = createHash("sha256").update(fs.readFileSync(path.join(HERE, "bridge.mjs"))).digest("hex").slice(0, 8);
+    } catch { /* keep dev */ }
+    localServer = createLocalServer({
+      cfg,
+      cfgPath: CONFIG_PATH,
+      version,
+      log,
+      doctor: () => doctorReport(["--config", CONFIG_PATH]),
+      detectAgents: () => detectAgentsForStatus(cfg),
+      startConnect: () => connectAgentsProgrammatic({ cfgPath: CONFIG_PATH, baseUrl: cfg.cookbookUrl }),
+      applyConfig: () => applyConfigFromDisk(cfg),
+      restart: () => reexecSelf(),
+      hotWorkspaceIds: () => hotWorkspaceIds(),
+      connected: () => tokenOk && consecutive401s === 0,
+      lastError: () => lastRunError,
+    });
+    await localServer.start();
+    for (const sig of ["SIGINT", "SIGTERM"]) process.on(sig, () => { try { localServer.stop(); } catch { /* exiting */ } });
+    process.on("exit", () => { try { localServer.stop(); } catch { /* exiting */ } });
+  } catch (e) {
+    localServer = null;
+    log(`! Bridge Local couldn't start (${e.message}) — the desktop app's buttons won't work this session; tasks still run.`);
+  }
+
+  // Confirm the token works before looping. A bad token is fatal for a HEADLESS
+  // (terminal) Bridge — exit with the fix. But when Bridge Local is up (the desktop
+  // app), stay alive in a degraded state so the user can fix the connection from the
+  // app (connect-agents rewrites the token, applyConfig reloads it, the poll recovers).
+  try {
+    const ws = await listWorkspaces(cfg);
+    tokenOk = true;
+    log(`Connected — watching ${ws.length} workspace(s).`);
+    if (cfg.persistentThreads) {
+      for (const sig of ["SIGINT", "SIGTERM"]) process.on(sig, () => { killAllRunners(); killCodexServer(); process.exit(0); });
+      process.on("exit", () => { killAllRunners(); killCodexServer(); });
+    }
+  } catch (e) {
+    lastRunError = e.message;
+    if (IS_DESKTOP && localServer) {
+      log(`! Not connected to Cookbook yet: ${e.message}`);
+      log(`  Fix it in the app (Connect your agents), or run \`node bridge.mjs login\`. The control API stays up so you can.`);
+    } else {
+      console.error(`\nCouldn't connect to Cookbook: ${e.message}`);
+      process.exit(1);
+    }
+  }
+
+  let lastFullSweepAt = 0;
+  let fastPath = true; // one-call dispatch until the server says it can't
+  void socketLoop(cfg); // push channel: sub-second dispatch when the server has it
+  while (!stopped) {
+    try {
+      // FAST PATH: push channel first (sub-second), 1s one-call poll as the net,
+      // full sweep (volunteering, skip/hold messaging, stale-claim rescue) as the
+      // 30s janitor. Falls back gracefully at every layer.
+      const hotIds = hotWorkspaceIds();
+      const pushHealthy = sse.connected && Date.now() - sse.aliveAt < 30_000;
+      if (fastPath) {
+        const dueFullSweep = Date.now() - lastFullSweepAt >= Math.max(cfg.pollSeconds * 1000, 30_000);
+        if (dueFullSweep) {
+          lastFullSweepAt = Date.now();
+          await pollOnce(cfg);
+        } else if (pushHealthy) {
+          // The socket carries dispatch; nothing to poll between janitor sweeps.
+        } else {
+          fastPath = await quickScan(cfg);
+          if (!fastPath) log("· server predates list_open_work — dispatching via workspace sweeps instead");
+        }
+      } else {
+        const fullEvery = hotIds.size > 0 ? Math.max(cfg.pollSeconds * 1000, 30_000) : cfg.pollSeconds * 1000;
+        const dueFullSweep = Date.now() - lastFullSweepAt >= fullEvery;
+        if (hotIds.size > 0 && !dueFullSweep) {
+          await pollOnce(cfg, hotIds);
+        } else {
+          lastFullSweepAt = Date.now();
+          await pollOnce(cfg);
+        }
+      }
+      // A clean poll means the token is good — clear any prior rejection so the app's
+      // /status flips back to connected once the user fixes it.
+      if (consecutive401s || !tokenOk) { consecutive401s = 0; tokenOk = true; lastRunError = null; }
+    } catch (e) {
+      log(`! poll error: ${e.message}`);
+      // A revoked/expired token would otherwise zombie-loop forever (re-running
+      // `login`/`connect-agents` revokes the prior token by design). Exit loudly
+      // with the actual fix instead of logging 401s every poll until the heat
+      // death of the laptop.
+      if (/401/.test(e.message)) {
+        consecutive401s++;
+        if (consecutive401s >= 5) {
+          if (IS_DESKTOP && localServer) {
+            // Desktop: keep the control API up so the user can fix the token from the
+            // app. Back off to the slow cadence and stop spamming; recovers on fix.
+            if (consecutive401s === 5) log("! Cookbook keeps rejecting this token — waiting. Fix it in the app (Connect your agents) or re-run login.");
+            await new Promise((r) => setTimeout(r, Math.max(cfg.pollSeconds * 1000, 15_000)));
+          } else {
+            log("✗ Cookbook has rejected this token 5 polls in a row — it was likely revoked (a new login replaces old tokens) or expired.");
+            log("  Fix: node bridge/bridge.mjs login   (then restart the Bridge)");
+            process.exit(1);
+          }
+        }
+      }
+    }
+    if (Date.now() - lastUpdateCheck > UPDATE_CHECK_MS) {
+      lastUpdateCheck = Date.now();
+      await selfUpdate(cfg, { reexec: true });
+    }
+    // HOT MODE (chat feel): while a conversation is active (a run started or
+    // finished in the last 3 minutes), poll every second so a reply dispatches
+    // near-instantly; decay back to the configured cadence when the room quiets.
+    if (cfg.persistentThreads) { reapIdleRunners(log); reapCodexServer(log); }
+    const hot = Date.now() - lastHotAt < HOT_WINDOW_MS;
+    await new Promise((r) => setTimeout(r, fastPath || hot ? 1000 : cfg.pollSeconds * 1000));
+  }
+}
+
+/**
+ * Preflight check — the fix for the #1 onboarding problem (every prerequisite fails
+ * silently or with a misleading error). Prints a ✓/✗ checklist and, for each ✗, the
+ * EXACT command to fix it: Node version, config + token, token actually works, and per
+ * agent: binary on PATH, CLI logged in (a real 1-token probe), allowedTools naming, and
+ * the default agent installed. One screen instead of a multi-hour debug session.
+ */
+async function runDoctor(args) {
+  const report = await doctorReport(args);
+  const { rows, fails, warns } = report;
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(report));
+    process.exit(fails === 0 ? 0 : 1);
+  }
+  const C = { g: "\x1b[32m", r: "\x1b[31m", y: "\x1b[33m", x: "\x1b[0m" };
+  const lines = rows.map((r) =>
+    r.level === "ok" ? `  ${C.g}✓${C.x} ${r.label}`
+      : r.level === "bad" ? `  ${C.r}✗${C.x} ${r.label}${r.fix ? `\n      ${C.r}↳ fix:${C.x} ${r.fix}` : ""}`
+        : `  ${C.y}!${C.x} ${r.label}${r.fix ? `\n      ↳ ${r.fix}` : ""}`,
+  );
+  console.log(`\nCookbook Bridge — doctor\n`);
+  console.log(lines.join("\n"));
+  const notes = warns ? ` ${C.y}(${warns} warning${warns > 1 ? "s" : ""} above worth a look)${C.x}` : "";
+  console.log(
+    fails === 0
+      ? `\n${C.g}No blockers — the Bridge should run tasks end-to-end.${C.x}${notes}\n`
+      : `\n${C.r}${fails} problem(s) above must be fixed before the Bridge can run tasks.${C.x}${notes}\n`,
+  );
+  process.exit(fails === 0 ? 0 : 1);
+}
+
+/** The doctor's checks as data: { cfgPath, rows: [{ level, label, fix }], fails, warns }.
+ *  Shared by the CLI (`doctor`, `doctor --json`) and Bridge Local's POST /doctor. */
+async function doctorReport(args) {
+  await loadRuntime();
+  const rows = [];
+  let fails = 0;
+  let warns = 0;
+  const ok = (s) => rows.push({ level: "ok", label: s });
+  const bad = (s, fix) => { fails++; rows.push({ level: "bad", label: s, ...(fix ? { fix } : {}) }); };
+  const warn = (s, note) => { warns++; rows.push({ level: "warn", label: s, ...(note ? { fix: note } : {}) }); };
+
+  // 1. Node version
+  const major = Number(process.versions.node.split(".")[0]);
+  if (major >= 18) ok(`Node ${process.version}`);
+  else bad(`Node ${process.version} is too old (need ≥18)`, "install Node 18+ (e.g. `brew install node`)");
+
+  // 2. Config present + filled in
+  const cfgPath = configPathFromArgs(args, path.join(HERE, "config.json"));
+  let cfg = null;
+  if (!fs.existsSync(cfgPath)) {
+    bad(`No config at ${cfgPath}`, "run `node bridge/bridge.mjs login` (one-click connect) — or copy config.example.json → config.json and add a token");
+  } else {
+    try {
+      cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+      cfg.cookbookUrl = (cfg.cookbookUrl || "").replace(/\/$/, "");
+      cfg.agents = (cfg.agents ?? []).filter((a) => a.enabled !== false);
+      if (!cfg.cookbookUrl || !cfg.token || String(cfg.token).startsWith("PASTE")) {
+        bad("Config is missing cookbookUrl or a real token", "set both in config.json (token from your Cookbook → Tokens page)");
+        cfg = null;
+      } else {
+        ok(`Config ${cfgPath}`);
+      }
+    } catch (e) {
+      bad(`Config isn't valid JSON: ${e.message}`);
+      cfg = null;
+    }
+  }
+
+  if (cfg) {
+    ensureAgentPath();
+
+    // 3. Token actually works
+    try {
+      const ws = await listWorkspaces(cfg);
+      ok(`Cookbook token works — ${ws.length} workspace(s) visible`);
+    } catch (e) {
+      bad(`Cookbook token rejected: ${e.message}`, "regenerate a token on your Cookbook → Tokens page and update config.json");
+    }
+
+    // 4. Default agent is one of the enabled agents
+    if (cfg.default && !cfg.agents.some((a) => a.name === cfg.default)) {
+      bad(`default agent "${cfg.default}" isn't in your enabled agents`,
+        `set "default" to one of: ${cfg.agents.map((a) => a.name).join(", ") || "(none enabled)"}`);
+    }
+
+    if (!cfg.agents.length) warn("No agents enabled in config — nothing will run.");
+
+    // 5. Per agent: binary, allowedTools sanity, and a real login probe
+    for (const agent of cfg.agents) {
+      const cmd = Array.isArray(agent.command) ? agent.command[0] : null;
+      const bin = resolveBin(cmd);
+      if (!bin) {
+        bad(`${agent.name}: binary \`${cmd}\` not found on PATH`,
+          `install it, or put an absolute path in config (find it with \`which ${cmd}\`)`);
+        continue;
+      }
+      ok(`${agent.name}: binary at ${bin}`);
+
+      // Gemini RCE gate (CVSS 10.0, fixed in 0.39.1): a confirmed-old version is a
+      // hard failure — the Bridge will refuse to run this agent.
+      if (isGeminiCommand(cmd)) {
+        const { version, vulnerable } = await checkGeminiVersion([bin]);
+        if (vulnerable) {
+          bad(`${agent.name}: gemini-cli ${version} has a critical prompt-injection RCE (CVSS 10.0)`,
+            `update to ≥ ${GEMINI_MIN_VERSION}: npm i -g @google/gemini-cli@latest`);
+        } else if (version) {
+          ok(`${agent.name}: gemini-cli ${version} (≥ ${GEMINI_MIN_VERSION}, RCE-safe)`);
+        } else {
+          warn(`${agent.name}: couldn't read gemini version`, `make sure it's ≥ ${GEMINI_MIN_VERSION} (RCE fix)`);
+        }
+      }
+
+      // Agy (Antigravity) checks: version >= 1.1.1 (headless-MCP fix), the MCP
+      // config file (agy has no `mcp add` — connect-agents writes it), and login.
+      if (isAgyCommand(cmd)) {
+        const { version, tooOld } = await checkAgyVersion([bin]);
+        if (tooOld) {
+          bad(`${agent.name}: agy ${version} can't call MCP tools headlessly (fixed in ${AGY_MIN_VERSION})`,
+            "run `agy update` — below 1.1.1 tasks run but never complete");
+        } else if (version) {
+          ok(`${agent.name}: agy ${version} (>= ${AGY_MIN_VERSION}, headless MCP works)`);
+        } else {
+          warn(`${agent.name}: couldn't read agy version`, `make sure it's >= ${AGY_MIN_VERSION} (headless MCP fix)`);
+        }
+        const agyMcpPath = path.join(process.env.HOME || "", ".gemini", "config", "mcp_config.json");
+        try {
+          const mc = JSON.parse(fs.readFileSync(agyMcpPath, "utf8"));
+          const srv = mc?.mcpServers?.cookbook;
+          if (srv?.serverUrl === `${cfg.cookbookUrl}/api/mcp` && srv?.headers?.Authorization) {
+            ok(`${agent.name}: Cookbook MCP configured (${agyMcpPath})`);
+          } else if (srv) {
+            warn(`${agent.name}: MCP config points at ${srv.serverUrl || "(no url)"}`,
+              `expected ${cfg.cookbookUrl}/api/mcp — re-run \`node bridge/bridge.mjs connect-agents\``);
+          } else {
+            bad(`${agent.name}: no 'cookbook' server in ${agyMcpPath}`,
+              "run `node bridge/bridge.mjs connect-agents` (agy has no `mcp add`; the Bridge writes this file)");
+          }
+        } catch {
+          bad(`${agent.name}: no agy MCP config at ${agyMcpPath}`,
+            "run `node bridge/bridge.mjs connect-agents` (agy has no `mcp add`; the Bridge writes this file)");
+        }
+        if (!fs.existsSync(path.join(process.env.HOME || "", ".gemini", "oauth_creds.json"))) {
+          warn(`${agent.name}: no Google login found (~/.gemini/oauth_creds.json)`,
+            "run `agy` once interactively and sign in with Google");
+        }
+      }
+
+      if ((agent.command || []).join(" ").includes("mcp__claude_ai_Cookbook__")) {
+        warn(`${agent.name}: allowedTools uses mcp__claude_ai_Cookbook__* — a CLI-added server is usually mcp__cookbook__*`,
+          "if tasks 'run but never complete', switch allowedTools to mcp__cookbook__*");
+      }
+
+      if (agent.runner === "app-server") { warn(`${agent.name}: app-server runner — start it to verify login/MCP (probe skipped)`); continue; }
+      if (agent.runner === "robot") {
+        const r = await spawnAgent(agent, "", 15, agentEnv(cfg).env);
+        if (r.code === 0 && String(r.out).trim().endsWith("ok")) ok(`${agent.name}: robot agent responds (probe ok)`);
+        else warn(`${agent.name}: robot agent probe inconclusive`, String(r.err || r.out).slice(0, 160));
+        continue;
+      }
+
+      try {
+        const r = await spawnAgent(agent, "Reply with the single word: ok", 30, agentEnv(cfg).env);
+        const text = `${r.out || ""}\n${r.err || ""}`.toLowerCase();
+        if (text.includes("not logged in") || text.includes("/login") || text.includes("please log in")) {
+          bad(`${agent.name}: CLI is NOT logged in`, `run \`${cmd} auth login\` (persists; setup-token does not)`);
+        } else if (text.includes("no mcp") || text.includes("mcp server")) {
+          bad(`${agent.name}: no Cookbook MCP connected`,
+            `${cmd} mcp add --scope user --transport http cookbook ${cfg.cookbookUrl}/api/mcp --header "Authorization: Bearer <token>"`);
+        } else if (r.code === 0) {
+          ok(`${agent.name}: CLI responds (logged in)`);
+        } else {
+          const probeTail = `${r.err || r.out || ""}`.trim().split("\n").slice(-2).join(" ").slice(0, 200);
+          // Account/tier lockouts (gemini's IneligibleTierError, quota exhaustion,
+          // auth expiry) are REAL blockers, not inconclusive noise — a CLI that
+          // starts but can't serve burns every attempt at runtime (2026-07-03).
+          if (/ineligible|no longer supported|quota exceeded|not authenticated|login required|migrate to/i.test(probeTail)) {
+            bad(`${agent.name}: the CLI refuses this account/tier — ${probeTail}`, "fix the account (or remove the agent from config.json — removal, not enabled:false)");
+          } else {
+            warn(`${agent.name}: probe exited ${r.code} — inconclusive`, probeTail);
+          }
+        }
+      } catch (e) {
+        warn(`${agent.name}: probe couldn't run (${e.message}) — inconclusive`);
+      }
+    }
+  }
+
+  return { cfgPath, rows, fails, warns };
+}
+
+// Dispatch ONLY when bridge.mjs is the entry script. Without this guard, any
+// test/tool that IMPORTS this module (for streamingCommand etc.) fell through
+// to main() and started a REAL polling Bridge on the importer's machine.
+const IS_MAIN = import.meta.main === true;
+const sub = process.argv[2];
+if (!IS_MAIN) {
+  /* library import — export-only, no dispatch */
+} else if (sub === "doctor") {
+  runDoctor(process.argv.slice(3)).catch((e) => {
+    console.error(e.message);
+    process.exit(1);
+  });
+} else if (sub === "login") {
+  import("./device.mjs")
+    .then((m) => m.login(process.argv.slice(3)))
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+} else if (sub === "connectors") {
+  // Connect a tool once, every agent has it: survey/sync MCP connectors across
+  // Claude, Codex, and Gemini (three files, three schemas, silent drift).
+  import("./connectors.mjs")
+    .then(async (m) => {
+      const args = process.argv.slice(3);
+      const doSync = args.includes("sync");
+      const dryRun = args.includes("--dry-run");
+      const rows = m.survey();
+      const vendors = Object.keys(m.VENDORS);
+      if (rows.length === 0) return console.log("No MCP connectors found for Claude, Codex, or Gemini.");
+      console.log("\n  " + "connector".padEnd(22) + vendors.map((v) => m.VENDORS[v].label.padEnd(9)).join(""));
+      for (const r of rows) {
+        const cells = vendors.map((v) => (r.present[v] ? "  ✓      " : "  ·      ")).join("");
+        console.log("  " + r.name.padEnd(22) + cells + (r.drift ? "⚠ drift" : ""));
+      }
+      for (const r of rows.filter((x) => x.drift)) {
+        console.log(`\n  ⚠ "${r.name}" points somewhere different per vendor:`);
+        for (const t of r.targets) console.log(`      ${t}`);
+      }
+      if (!doSync) {
+        const missing = rows.filter((r) => vendors.some((v) => !r.present[v])).length;
+        console.log(`\n  ${missing} connector(s) aren't on every agent.`);
+        console.log("  Run `node bridge/bridge.mjs connectors sync` to give every agent the same tools.\n");
+        return;
+      }
+      const only = args.filter((a) => !a.startsWith("--") && a !== "sync");
+      const actions = m.sync({ only: only.length ? only : null, dryRun });
+      if (actions.length === 0) return console.log("\n  Already in sync — every agent has the same connectors.\n");
+      console.log(`\n  ${dryRun ? "Would apply" : "Applied"} ${actions.length} change(s):`);
+      for (const a of actions) console.log(`    ${a.action === "add" ? "+" : "~"} ${m.VENDORS[a.vendor].label.padEnd(7)} ${a.name}`);
+      if (!dryRun) console.log("\n  Backups written next to each config (.bak-<timestamp>). Restart your agents to pick them up.\n");
+      else console.log("\n  (dry run — nothing written)\n");
+    })
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+} else if (sub === "connect" || sub === "connect-agents") {
+  // `connect` is the documented first command (the connect page and the npm bin both
+  // say it); `connect-agents` is the original name, kept working forever.
+  import("./device.mjs")
+    .then((m) => m.connectAgents(process.argv.slice(3)))
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+} else if (sub === "status") {
+  import("./device.mjs")
+    .then((m) => m.status(process.argv.slice(3)))
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+} else if (sub === "update") {
+  // One-shot: check the deploy manifest, verify + apply, report. Exit 0 either way
+  // unless the apply itself failed.
+  (async () => {
+    // Deliberately import ONLY update.mjs — this path must work from a broken install.
+    // Config is read minimally here (no loadConfig: that treats argv[2] as a path and
+    // demands a token — updates need only the cookbookUrl, both endpoints are public).
+    const upd = await import("./update.mjs");
+    const cfgPath = configPathFromArgs(process.argv.slice(3), path.join(HERE, "config.json"));
+    let cookbookUrl = "";
+    try {
+      cookbookUrl = String(JSON.parse(fs.readFileSync(cfgPath, "utf8")).cookbookUrl || "").replace(/\/$/, "");
+    } catch { /* fall through to the error below */ }
+    if (!cookbookUrl) {
+      console.error(`Can't read cookbookUrl from ${cfgPath} — pass --config <path> or fix config.json.`);
+      process.exit(1);
+    }
+    const cfg = { cookbookUrl };
+    const check = await upd.checkForUpdate(cfg, HERE);
+    if (check.changed.length === 0) {
+      console.log(`Up to date with the app deploy (${check.version}).`);
+      return;
+    }
+    console.log(`Update available (deploy ${check.version}) — ${check.changed.length} file(s): ${check.changed.join(", ")}`);
+    const replaced = await upd.applyUpdate(cfg, HERE, check);
+    console.log(`Updated ${replaced.length} file(s), hash-verified. Previous version in bridge.backup/${check.version}/. Restart the Bridge to run the new code.`);
+  })().catch((e) => {
+    console.error(`Update failed safely (nothing partially applied): ${e.message}`);
+    process.exit(1);
+  });
+} else {
+  main();
+}