cookbook-bridge 0.1.12 → 0.1.16

package/README.md

@@ -2,6 +2,14 @@
 
 ## Changelog
 
+**0.1.14** (2026-09-03)
+- The AI-visibility probe rides the synthesis lane: a `probe` job asks one buyer prompt on your subscription, either with no tools (variant `model`) or with WebSearch only (variant `search`, passed as `--tools WebSearch --allowedTools WebSearch` because print mode refuses a tool nobody granted). Capped at 120s per prompt, logged as `probe: <group> #<n> (<variant>)`, never with the prompt text.
+
+**0.1.13** (2026-09-02)
+- Pre-flight: the moment a grant this Bridge hosts becomes active, it runs `env`, the doctor, `cli_versions` and the shape of its own config (tokens stripped) once, locally and read-only, and posts the result as a host-initiated `preflight` call, so the visiting agent starts with what the machine already knows. Remembered per grant in `bridge.state.json`; a failed post is retried once per process.
+- One-click plans: a `plan` call carries `why` and an ordered list of steps. The Bridge recomputes the plan hash before running (a step added after the click is refused as `plan hash mismatch`), runs each step through the same authorization wall as a single call, with the plan's approval standing in for each write-class step's click, stops at the first failure, and reports every step with its duration. Plans cannot nest, cannot contain `preflight`, and run one at a time like every other call.
+- Every result leaving the machine is capped at 64 KB, the same cap the server applies.
+
 **0.1.12** (2026-09-02)
 - Kimi Code is the fourth agent: `connect` finds `kimi`, mints a "Kimi" token and writes `~/.kimi-code/mcp.json` (owner-only, other servers kept). Runs use `kimi -p ... --output-format stream-json`; the board gets live text and the work log, resume by session id, and a duration-only receipt (kimi reports no token counts).
 - A headless kimi run approves every tool and has no `--allowedTools` flag, so the Bridge turns the config's `--allowedTools` into a per-run agent file (`--agent-file`, a 0600 temp file) whose tools allowlist is exactly that list. `doctor` fails a Kimi agent that has no `--allowedTools`.

package/bridge.mjs

@@ -34,7 +34,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { callsFromStreamLine, foldCallEvent, wireCalls, shortTool, argFor } from "./live.mjs";
-import { planFromStreamLine, notePlan, planLine } from "./plan.mjs";
+import { planFromStreamLine, notePlan, planLine, noteAuth, isSignedOutError } from "./plan.mjs";
 
 // Node version guard: below 18 there is no global fetch and none of this runs. One
 // plain line beats a stack trace from the first `fetch(` call.
@@ -68,14 +68,14 @@ let hasCodexThread, reapCodexServer, killCodexServer;
 let checkForUpdate, applyUpdate;
 let createLocalServer, toolsForMode, modeForTools, vendorOf;
 let connectAgentsProgrammatic, detectClis;
-let serveCalls, describeCall, hostingMode, whichExec, argvForSpawn, redactText, resolveCmdShim, killTree;
+let serveCalls, describeCall, hostingMode, whichExec, argvForSpawn, redactText, resolveCmdShim, killTree, runPreflight, grantsNeedingPreflight;
 let fetchHands, claimHandsCall, reportHandsResult;
 
 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, fetchHands, claimHandsCall, reportHandsResult, agentsQuery } = await import("./cookbook.mjs"));
-  ({ serveCalls, describeCall, hostingMode, which: whichExec, argvForSpawn, redact: redactText, resolveCmdShim, killTree } = await import("./hands.mjs"));
+  ({ serveCalls, describeCall, hostingMode, which: whichExec, argvForSpawn, redact: redactText, resolveCmdShim, killTree, runPreflight, grantsNeedingPreflight } = await import("./hands.mjs"));
   ({ agentEnv, checkGeminiVersion, isGeminiCommand, GEMINI_MIN_VERSION, checkAgyVersion, isAgyCommand, AGY_MIN_VERSION, withCookbookMcp, isClaudeCommand, withApprovalRelay, materializeMcpConfig,
     isKimiCommand, kimiFromLine, kimiResultEnvelope, kimiCommand, kimiLoginState, kimiMcpState, checkKimiVersion } = await import("./harden.mjs"));
   ({ extractUsage, displayText } = await import("./usage.mjs"));
@@ -739,8 +739,8 @@ function failureHint(result) {
   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 (isSignedOutError(infra))
+    return "Claude on this machine is signed out → open a terminal, run `claude`, and sign in; this Bridge picks it up on its own";
   // Kimi's own error strings (stderr: "error: failed to run prompt: provider.connection_error: …").
   if (infra.includes("provider.connection_error") || infra.includes("connection error"))
     return "the agent CLI can't reach its API (a network or DNS block on the vendor's hosts) → check the connection, then try `kimi -p hi` by hand";
@@ -815,6 +815,7 @@ function loadRunState() {
     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);
+    for (const id of raw.preflighted ?? []) if (typeof id === "string") preflighted.add(id);
   } catch { /* first run / unreadable — start clean */ }
 }
 function saveRunState() {
@@ -823,11 +824,15 @@ function saveRunState() {
     const attEntries = [...attempts.entries()].slice(-500);
     const given = [...givenUp].slice(-500);
     const retries = [...retryCtx.entries()].slice(-200);
-    fs.writeFileSync(statePath(), JSON.stringify({ attempts: Object.fromEntries(attEntries), givenUp: given, retryCtx: Object.fromEntries(retries) }));
+    const flown = [...preflighted].slice(-500);
+    fs.writeFileSync(statePath(), JSON.stringify({ attempts: Object.fromEntries(attEntries), givenUp: given, retryCtx: Object.fromEntries(retries), preflighted: flown }));
   } catch { /* best-effort — never let state persistence break a run */ }
 }
 
 const attempts = new Map(); // taskId -> count
+// Grants this host has already pre-flighted (hands section). Persisted: a restart
+// must not post a second pre-flight for a grant the visitor already read.
+const preflighted = new Set();
 // 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 }
@@ -1434,6 +1439,10 @@ async function processTask(cfg, ws, task, agent) {
       // turns a multi-hour debug into a one-glance fix.
       const hint = failureHint(result);
       const why = hint ? ` — ${hint}` : "";
+      if (/signed out/.test(hint) && isClaudeCommand && isClaudeCommand(agent.command)) {
+        if (noteAuth("claude", false)) log("! Claude is signed out on this machine → run `claude` in a terminal and sign in. Until then Claude work here falls back or waits.");
+        lastAuthCheck = Date.now() - AUTH_CHECK_MS + 60_000; // re-check in a minute
+      }
       if (holdDuringRun()) {
         shelveForHold(hint || "plan limit reached", result?.sessionId ?? null);
       } else if (n >= cfg.maxAttempts) {
@@ -1607,30 +1616,36 @@ function noteAwaiting(awaiting) {
   if (announcedAwaiting.size > 500) announcedAwaiting.clear();
 }
 
+/** The host context every hands path shares: serveCalls (visitor calls, plans) and
+ *  runPreflight (the host's own first call on a new grant). */
+function handsContext(cfg) {
+  return {
+    cfg,
+    cfgPath: CONFIG_PATH,
+    home: os.homedir(),
+    // The host's OWN folder list. A granted folder is honoured only if it is here
+    // (or inside one), so the server can never hand a visitor a directory.
+    hostFolders: cfg.hosting?.folders ?? [],
+    doctor: () => doctorReport(["--config", CONFIG_PATH]),
+    claim: (id) => claimHandsCall(cfg, id),
+    report: (id, r) => reportHandsResult(cfg, id, r),
+    // Repair templates reach the same machinery the desktop app's buttons use, so
+    // a fix an agent performs is exactly the fix the host could have clicked.
+    restart: () => reexecSelf(),
+    startConnect: () => connectAgentsProgrammatic({ cfgPath: CONFIG_PATH, baseUrl: cfg.cookbookUrl }),
+    applyConfig: () => applyConfigFromDisk(cfg),
+    log,
+    stopped: () => stopped,
+    visitorLabel: (c) => c.visitor ?? "a visiting agent",
+    onCall: emitHands,
+  };
+}
+
 async function serveHands(cfg, calls) {
   if (hostingMode(cfg) === "off" || handsBusy || !calls || calls.length === 0) return;
   handsBusy = true;
   try {
-    await serveCalls(calls, {
-      cfg,
-      cfgPath: CONFIG_PATH,
-      home: os.homedir(),
-      // The host's OWN folder list. A granted folder is honoured only if it is here
-      // (or inside one), so the server can never hand a visitor a directory.
-      hostFolders: cfg.hosting?.folders ?? [],
-      doctor: () => doctorReport(["--config", CONFIG_PATH]),
-      claim: (id) => claimHandsCall(cfg, id),
-      report: (id, r) => reportHandsResult(cfg, id, r),
-      // Repair templates reach the same machinery the desktop app's buttons use, so
-      // a fix an agent performs is exactly the fix the host could have clicked.
-      restart: () => reexecSelf(),
-      startConnect: () => connectAgentsProgrammatic({ cfgPath: CONFIG_PATH, baseUrl: cfg.cookbookUrl }),
-      applyConfig: () => applyConfigFromDisk(cfg),
-      log,
-      stopped: () => stopped,
-      visitorLabel: (c) => c.visitor ?? "a visiting agent",
-      onCall: emitHands,
-    });
+    await serveCalls(calls, handsContext(cfg));
   } catch (e) {
     log(`! hands error: ${e.message}`);
   } finally {
@@ -1638,6 +1653,51 @@ async function serveHands(cfg, calls) {
   }
 }
 
+/** Open a HOST-initiated call row on a grant (the pre-flight). Same bearer, same
+ *  route the claim uses; the server answers { call_id }. */
+async function createHostCall(cfg, grantId, verb) {
+  const res = await fetch(`${cfg.cookbookUrl}/api/bridge/hands`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${cfg.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ grant_id: grantId, verb, host_initiated: true }),
+  });
+  if (!res.ok) throw new Error(`hands ${res.status}`);
+  const j = await res.json().catch(() => ({}));
+  return typeof j.call_id === "string" ? j.call_id : typeof j.call?.id === "string" ? j.call.id : null;
+}
+
+// ── PRE-FLIGHT: the first thing a new grant gets is what the machine already knows.
+// When a grant this Bridge hosts becomes active, the host runs env + doctor +
+// cli_versions + its own config's shape (tokens stripped) once, locally, read-only,
+// and posts it as a host-initiated `preflight` call. The visitor reads it from
+// grant_get before asking anything the machine already answered. Persisted per
+// grant (bridge.state.json); at most two tries per grant per process.
+const preflightTries = new Map(); // grantId -> attempts this process
+async function preflightNewGrants(cfg) {
+  if (hostingMode(cfg) === "off" || handsBusy || !runPreflight) return;
+  const fresh = grantsNeedingPreflight(hands.activeGrants, { preflighted, tried: preflightTries });
+  if (fresh.length === 0) return;
+  handsBusy = true; // never alongside a visitor's call
+  try {
+    for (const grantId of fresh) {
+      if (stopped) break;
+      const n = (preflightTries.get(grantId) ?? 0) + 1;
+      preflightTries.set(grantId, n);
+      log(`◇ pre-flight for grant ${grantId.slice(0, 8)}: env, doctor, CLI versions, config shape`);
+      try {
+        const { callId } = await runPreflight(grantId, { ...handsContext(cfg), create: (gid) => createHostCall(cfg, gid, "preflight") });
+        preflighted.add(grantId);
+        saveRunState();
+        log(`  ↳ pre-flight posted (call ${String(callId).slice(0, 8)})`);
+      } catch (e) {
+        log(`! pre-flight for grant ${grantId.slice(0, 8)} failed: ${e.message}${n >= 2 ? " (not retrying until the Bridge restarts)" : " (will retry once)"}`);
+      }
+    }
+  } finally {
+    handsBusy = false;
+  }
+}
+
 /** Poll for granted calls (the net under the push channel, and the whole story on a
  *  server or network without SSE). No-ops entirely when not hosting. */
 async function pollHands(cfg) {
@@ -1651,6 +1711,7 @@ async function pollHands(cfg) {
     }
     hands.activeGrants = r.grants ?? [];
     noteAwaiting(r.awaiting ?? []);
+    await preflightNewGrants(cfg);
     await serveHands(cfg, r.calls);
   } catch (e) {
     if (!/40[13]/.test(e.message)) log(`! couldn't check for granted work: ${e.message}`);
@@ -1688,7 +1749,7 @@ async function pullOnce(cfg, { boot = false } = {}) {
   if (j.hands && typeof j.hands === "object") {
     hands.activeGrants = j.hands.grants ?? hands.activeGrants;
     noteAwaiting(j.hands.awaiting ?? []);
-    if (hostingMode(cfg) !== "off") void serveHands(cfg, j.hands.calls ?? []);
+    if (hostingMode(cfg) !== "off") void preflightNewGrants(cfg).then(() => serveHands(cfg, j.hands.calls ?? []));
   }
   // 0092: synthesis (summary, caption, vision, answer) thinks HERE, on this
   // member's subscription. Each job carries kind, model and image straight
@@ -1815,7 +1876,7 @@ async function socketLoop(cfg) {
               const j = JSON.parse(ev.data);
               hands.activeGrants = j.grants ?? hands.activeGrants;
               noteAwaiting(j.awaiting ?? []);
-              void serveHands(cfg, j.calls ?? []);
+              void preflightNewGrants(cfg).then(() => serveHands(cfg, j.calls ?? []));
             } catch { /* malformed frame — the poll covers it */ }
           }
         }
@@ -2025,6 +2086,45 @@ async function pollOnce(cfg, onlyWorkspaceIds = null) {
 
 /** How often a RUNNING bridge re-checks the deploy manifest ("app updated → I update"). */
 const UPDATE_CHECK_MS = 6 * 60 * 60 * 1000;
+/** How often to ask the CLI whether it is still signed in (0100). */
+const AUTH_CHECK_MS = 10 * 60 * 1000;
+let lastAuthCheck = 0;
+
+/**
+ * Ask claude whether it is signed in (`claude auth status` prints JSON with
+ * `loggedIn`). Only claude has this today; other vendors are learned from their
+ * failures. Records the state (plan.mjs noteAuth) so the heartbeat advertises it,
+ * and logs once per change. Never throws; an unreadable answer changes nothing.
+ */
+async function checkClaudeAuth(cfg) {
+  const agent = (cfg?.agents ?? []).find((a) => a && a.enabled !== false && isClaudeCommand && isClaudeCommand(a.command));
+  if (!agent) return null;
+  const cmd = agent.command[0];
+  const env = typeof agentEnv === "function" ? agentEnv(cfg).env : process.env;
+  const out = await new Promise((resolve) => {
+    let text = "";
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolve(v); } };
+    try {
+      const child = spawn(cmd, ["auth", "status"], { env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+      child.stdout.on("data", (d) => { text += d; });
+      child.stderr.on("data", (d) => { text += d; });
+      child.on("error", () => finish(null));
+      child.on("close", () => finish(text));
+      setTimeout(() => { try { child.kill(); } catch { /* gone */ } finish(null); }, 15_000).unref();
+    } catch { finish(null); }
+  });
+  if (out === null) return null;
+  let loggedIn = null;
+  const brace = out.indexOf("{");
+  if (brace >= 0) { try { const j = JSON.parse(out.slice(brace)); if (typeof j.loggedIn === "boolean") loggedIn = j.loggedIn; } catch { /* not JSON */ } }
+  if (loggedIn === null && isSignedOutError(out)) loggedIn = false;
+  if (loggedIn === null) return null;
+  const changed = noteAuth("claude", loggedIn);
+  if (changed && !loggedIn) log("! Claude is signed out on this machine → open a terminal, run `claude`, and sign in. This Bridge re-checks every 10 minutes.");
+  if (changed && loggedIn && lastAuthCheck > 0) log("✓ Claude is signed in again — Claude work resumes here.");
+  return loggedIn;
+}
 
 /**
  * WHO OWNS THIS INSTALL'S VERSION.
@@ -2059,6 +2159,39 @@ let updateNagged = false;
  * 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/).
  */
+/**
+ * Install the runtime + login service and wait for it to come up. Returns true
+ * when a Bridge is running under the service; false (with the reason printed) so
+ * the caller can fall back to a foreground run.
+ */
+async function installAsService(svc, { cookbookUrl, cfgPath }) {
+  const say = (m) => console.log(`  ${m}`);
+  try {
+    console.log("\nInstalling the Bridge as a background service…");
+    await svc.installRuntime({ cookbookUrl, log: say });
+    svc.installService({ config: cfgPath, log: say });
+    process.stdout.write("  Starting");
+    const pid = await svc.waitForBridge(cfgPath, { timeoutMs: 30_000 });
+    console.log("");
+    const st = svc.serviceState({ config: cfgPath });
+    if (pid) {
+      console.log(`\n  ✓ The Bridge is running in the background (pid ${pid}). It starts with your computer,`);
+      console.log("    updates itself from cookbook.team, and this window can close.");
+    } else {
+      console.log(`\n  ! The service is installed but the Bridge has not reported in yet. Its log: ${st.log}`);
+    }
+    console.log(`\n  Config:   ${cfgPath}`);
+    console.log(`  Log:      ${st.log}`);
+    console.log(`  Check:    ${cli("doctor")}`);
+    console.log(`  Restart:  ${cli("restart")}`);
+    console.log(`  Remove:   ${cli("uninstall")}\n`);
+    return true;
+  } catch (e) {
+    console.log(`\n  ! Could not install the service: ${e.message}`);
+    return false;
+  }
+}
+
 async function selfUpdate(cfg, { reexec }) {
   let check;
   try {
@@ -2083,6 +2216,10 @@ async function selfUpdate(cfg, { reexec }) {
   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 && process.env.COOKBOOK_SERVICE === "1") {
+      log("↻ restarting on the new code (the service brings it back)…");
+      process.exit(0);
+    }
     if (reexec) {
       log("↻ restarting on the new code…");
       const { spawn } = await import("node:child_process");
@@ -2100,6 +2237,9 @@ async function main() {
   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`);
+  // Is the CLI actually able to run? (0100) The answer rides the first heartbeat.
+  await checkClaudeAuth(cfg).catch(() => null);
+  lastAuthCheck = Date.now();
 
   // "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.
@@ -2276,6 +2416,13 @@ async function main() {
       log(`  Fix it in the app (Connect your agents), or run \`${cli("connect")}\`. The control API stays up so you can.`);
     } else {
       console.error(`\nCouldn't connect to Cookbook: ${e.message}`);
+      // Under a login service the supervisor restarts us at once; a dead token
+      // would then hit the server every 15 seconds forever. Say the fix, then
+      // wait before exiting so the loop is gentle (service.mjs, 2026-09-09).
+      if (process.env.COOKBOOK_SERVICE === "1") {
+        console.error(`  Fix: ${cli("connect")}   (reconnects; the service picks the new token up on its own). Retrying in 5 minutes.`);
+        await new Promise((r) => setTimeout(r, 5 * 60 * 1000));
+      }
       process.exit(1);
     }
   }
@@ -2345,11 +2492,19 @@ async function main() {
           } 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: ${cli("connect")}   (reconnects and starts the Bridge)`);
+            if (process.env.COOKBOOK_SERVICE === "1") {
+              log("  Running as a service: retrying in 5 minutes.");
+              await new Promise((r) => setTimeout(r, 5 * 60 * 1000));
+            }
             process.exit(1);
           }
         }
       }
     }
+    if (Date.now() - lastAuthCheck > AUTH_CHECK_MS) {
+      lastAuthCheck = Date.now();
+      void checkClaudeAuth(cfg).catch(() => null);
+    }
     if (Date.now() - lastUpdateCheck > UPDATE_CHECK_MS) {
       lastUpdateCheck = Date.now();
       await selfUpdate(cfg, { reexec: true });
@@ -2472,6 +2627,18 @@ async function doctorReport(args) {
     }
   }
 
+  // 2a½. The login service (2026-09-09): installed? running?
+  try {
+    const svc = await import("./service.mjs");
+    const st = svc.serviceState({ config: cfgPath });
+    if (!st.kind) ok("Login service: not available on this platform (run the Bridge in a terminal)");
+    else if (st.installed && st.pid) ok(`Login service: installed (${st.definition}) and running (pid ${st.pid})`);
+    else if (st.installed) warn(`Login service: installed (${st.definition}) but no Bridge is reporting in`, `look at ${st.log}, or \`${cli("restart")}\``);
+    else if (!IS_DESKTOP) warn("Login service: not installed, so the Bridge stops when this window closes", `\`${cli("install")}\` installs it and starts it now`);
+  } catch (e) {
+    ok(`Login service: could not check (${e.message})`);
+  }
+
   // 2b. Another Bridge on this machine? Two on one config fight over the same token
   // (a `connect` revokes the other's); one on a different config is the classic
   // "I connected but a stale Bridge is still running" trap.
@@ -2628,6 +2795,9 @@ async function doctorReport(args) {
       }
 
       if (isClaudeCommand && isClaudeCommand(agent.command)) {
+        const signedIn = await checkClaudeAuth({ ...cfg, agents: [agent] }).catch(() => null);
+        if (signedIn === false) bad(`${agent.name}: claude is SIGNED OUT on this machine`, "open a terminal, run `claude`, and sign in (or `claude auth login`)");
+        else if (signedIn === true) ok(`${agent.name}: claude is signed in`);
         if (agent.token) ok(`${agent.name}: runs carry their own Cookbook connection (per-agent token) — identity is this Bridge's member`);
         else warn(`${agent.name}: no per-agent token — runs use the claude CLI's OWN Cookbook login, which may be a different account and inherits stale claude.ai connectors`,
           `run \`${cli("connect")}\` (mints a token for this agent) or add "token" to this agent in ${cfgPath}`);
@@ -2796,13 +2966,24 @@ if (!IS_MAIN) {
     .then(async (m) => {
       const args = process.argv.slice(3);
       const noRun = args.includes("--no-run");
-      const r = await m.connectAgents(args.filter((a) => a !== "--no-run"), { willRun: !noRun });
+      // THE SERVICE (2026-09-09): after the approval the Bridge is installed as a
+      // login service and started, so the window can close and it survives reboots.
+      // `--no-service` keeps the foreground run; the desktop app supervises its own.
+      const svc = await import("./service.mjs");
+      const wantService = !noRun && !args.includes("--no-service") && !IS_DESKTOP && !!svc.serviceKind();
+      const passArgs = args.filter((a) => a !== "--no-run" && a !== "--no-service" && a !== "--no-signin").concat(args.includes("--no-signin") ? ["--no-signin"] : []);
+      const r = await m.connectAgents(passArgs, { willRun: !noRun, service: wantService });
       if (!r || !r.ok) {
         // Nothing to run (no agent CLI found): the doctor says what is missing and how to fix it.
         if (r && r.reason === "no-agents") await runDoctor(["--config", r.cfgPath]);
         return;
       }
       if (noRun || !r.startBridge) return;
+      if (wantService) {
+        const done = await installAsService(svc, { cookbookUrl: r.baseUrl, cfgPath: r.cfgPath });
+        if (done) return;
+        console.log("Falling back to running the Bridge here.\n");
+      }
       console.log("Connected. Running the Bridge now; leave this window open. Ctrl-C stops it.\n");
       process.argv = [process.argv[0], process.argv[1], r.cfgPath];
       await main();
@@ -2839,6 +3020,33 @@ if (!IS_MAIN) {
       console.error(e.message);
       process.exit(1);
     });
+} else if (sub === "install") {
+  // Runtime + login service + start, against an existing config (connect does this
+  // for you; `install` is for a machine that already has a config).
+  (async () => {
+    const svc = await import("./service.mjs");
+    const cfgPath = configPathFromArgs(process.argv.slice(3));
+    let cookbookUrl = "";
+    try { cookbookUrl = String(JSON.parse(fs.readFileSync(cfgPath, "utf8")).cookbookUrl || "").replace(/\/$/, ""); } catch { /* below */ }
+    if (!cookbookUrl) { console.error(`No config at ${cfgPath}. Run \`${cli("connect")}\` first.`); process.exit(1); }
+    const ok = await installAsService(svc, { cookbookUrl, cfgPath });
+    process.exit(ok ? 0 : 1);
+  })().catch((e) => { console.error(e.message); process.exit(1); });
+} else if (sub === "uninstall") {
+  (async () => {
+    const svc = await import("./service.mjs");
+    const cfgPath = configPathFromArgs(process.argv.slice(3));
+    const r = svc.uninstallService({ config: cfgPath, log: (m) => console.log(`  ${m}`) });
+    console.log(r.removed.length ? `Service removed (${r.removed.join(", ")}).` : "No service was installed.");
+    console.log(`Your config and token are untouched at ${cfgPath}. To revoke the Bridge's access, remove it under Account > Connected apps.`);
+  })().catch((e) => { console.error(e.message); process.exit(1); });
+} else if (sub === "restart") {
+  (async () => {
+    const svc = await import("./service.mjs");
+    const cfgPath = configPathFromArgs(process.argv.slice(3));
+    const ok = svc.restartService({ config: cfgPath });
+    console.log(ok ? "Restarting the Bridge service." : `No running service found for ${cfgPath}. Start one with \`${cli("install")}\`.`);
+  })().catch((e) => { console.error(e.message); process.exit(1); });
 } else if (sub === "status") {
   import("./device.mjs")
     .then((m) => m.status(process.argv.slice(3)))

package/chef-persona.md

@@ -7,3 +7,5 @@ What you know: Cookbook is the shared brain a team's AI agents plug into. Every
 How you work: the message you receive carries the rules for this conversation (a grant id, whether you may ask for machine access, and Cookbook Help notes that match the question). Follow those rules exactly; they override anything here. Use the Cookbook tools only. When the answer depends on the person's machine, ask for access the way the rules describe. Never send them to a terminal.
 
 You are running on this person's own machine and subscription as their agent. You can see their workspaces. When you need to look at or change their setup, ask for a hands grant in the usual way; every action still waits for their click.
+
+When a fix needs more than one change, do not ask for each one. Submit ONE hands_plan with a plain `why` and the steps in order, then wait for the person's single approval; the Bridge runs the steps one at a time and stops at the first failure. Before you ask about the machine, read the pre-flight the host posted on the grant (grant_get): what is installed, the doctor rows, CLI versions and the shape of the Bridge config are already there. Never ask for something the machine has already answered.

package/cookbook.mjs

@@ -8,7 +8,7 @@
  *
  * Node built-ins only (global fetch, Node 18+). No dependencies.
  */
-import { planParam } from "./plan.mjs";
+import { planParam, signedOutParam } from "./plan.mjs";
 
 /** Call one Cookbook MCP tool. Returns the tool's body (structuredContent). */
 export async function callTool(cfg, name, args = {}) {
@@ -260,6 +260,9 @@ export function agentsQuery(cfg, plan = planParam) {
   // reported them to this Bridge (bridge/plan.mjs). Rides the same heartbeat.
   const p = typeof plan === "function" ? plan() : "";
   if (p) parts.push(p);
+  // `signed_out=…` — which of those agents' CLIs cannot run right now (0100).
+  const so = signedOutParam();
+  if (so) parts.push(so);
   return parts.length ? `?${parts.join("&")}` : "";
 }
 

package/device.mjs

@@ -582,7 +582,7 @@ function probeAgent(cmd) {
  * Codex (ChatGPT app), Kimi and OpenClaw; mints one named token per agent in the same
  * approval as the Bridge token; configures each via its official path.
  */
-export async function connectAgents(argv, { willRun = false } = {}) {
+export async function connectAgents(argv, { willRun = false, service = false } = {}) {
   const cfgPath = configPath(argv);
   const found = detectClis();
   if (found.length === 0) {
@@ -592,6 +592,13 @@ export async function connectAgents(argv, { willRun = false } = {}) {
   }
   console.log(`\nFound agent CLIs: ${found.map((c) => c.agent).join(", ")}`);
 
+  // ONE-CLICK SIGN-IN (2026-09-09). The Bridge can only run a CLI that is signed
+  // in, and "signed out" was the failure behind every dead task Texas Accelerate
+  // and Pierre hit. So before the Cookbook approval, sign the CLIs in right here:
+  // claude opens Anthropic's own login page; codex shows OpenAI's device code.
+  // Each token lands in that CLI's own store on this disk; Cookbook never sees it.
+  if (!argv.includes("--no-signin")) await ensureSignedIn(found);
+
   // One approval mints the bridge token + one named token per agent.
   const res = await login(argv, { agents: found.map((c) => c.agent), quietOutro: true });
   if (!res || !res.agentTokens) {
@@ -605,8 +612,77 @@ export async function connectAgents(argv, { willRun = false } = {}) {
     console.log(`  ${mark} ${r.agent}: ${r.detail}${r.ok && !r.warn ? ` (work will be attributed "${r.agent} · via you")` : ""}`);
   }
   await reportStaleness(res.baseUrl);
-  reportNextStep(res.cfgPath, { willRun });
-  return { ok: true, startBridge: true, cfgPath: res.cfgPath, agentTokens: true };
+  if (!service) reportNextStep(res.cfgPath, { willRun });
+  return { ok: true, startBridge: true, cfgPath: res.cfgPath, agentTokens: true, baseUrl: res.baseUrl, found };
+}
+
+/** `claude auth status` → true / false / null (unknown). Never throws. */
+export function claudeSignedIn(claudePath) {
+  try {
+    const argv = argvForSpawn([claudePath, "auth", "status"]);
+    const r = spawnSync(argv[0], argv.slice(1), { encoding: "utf8", timeout: 15_000, windowsHide: true });
+    const out = `${r.stdout || ""}${r.stderr || ""}`;
+    const brace = out.indexOf("{");
+    if (brace >= 0) { try { const j = JSON.parse(out.slice(brace)); if (typeof j.loggedIn === "boolean") return j.loggedIn; } catch { /* not JSON */ } }
+    if (/not logged in|please log in|expired|not authenticated/i.test(out)) return false;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Does codex have a login on this machine? (`~/.codex/auth.json` is what `codex login` writes.) */
+export function codexSignedIn(home = os.homedir()) {
+  try {
+    const j = JSON.parse(fs.readFileSync(path.join(home, ".codex", "auth.json"), "utf8"));
+    return !!(j && (j.tokens || j.OPENAI_API_KEY || j.access_token));
+  } catch {
+    return false;
+  }
+}
+
+/** Run a CLI's own interactive sign-in in this terminal and wait for it. */
+function runInteractive(bin, args) {
+  return new Promise((resolve) => {
+    try {
+      const argv = argvForSpawn([bin, ...args]);
+      const child = spawn(argv[0], argv.slice(1), { stdio: "inherit" });
+      child.on("error", () => resolve(false));
+      child.on("close", (code) => resolve(code === 0));
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+/**
+ * Sign in every detected CLI that is signed out, in the terminal, before anything
+ * else. Claude: Anthropic's browser login (`claude auth login`). Codex: OpenAI's
+ * device code (`codex login --device-auth`). Skipped for CLIs we cannot check.
+ */
+export async function ensureSignedIn(found, { log = console.log } = {}) {
+  const outcome = [];
+  for (const c of found) {
+    if (c.vendor === "claude") {
+      const state = claudeSignedIn(c.path);
+      if (state === false) {
+        log("\n  Claude Code is signed out on this machine. Sign in with the account you use in the browser:\n");
+        const ok = await runInteractive(c.path, ["auth", "login"]);
+        const after = claudeSignedIn(c.path);
+        log(after ? "\n  ✓ Claude Code is signed in.\n" : "\n  ! Claude Code still looks signed out. Run `claude` in a terminal and sign in, then re-run connect.\n");
+        outcome.push({ agent: "Claude", signedIn: !!after, ran: ok });
+      } else outcome.push({ agent: "Claude", signedIn: state !== false, ran: false });
+    } else if (c.vendor === "codex" && c.kind === "codex" && !/ChatGPT\.app/i.test(String(c.path))) {
+      if (!codexSignedIn()) {
+        log("\n  Codex has no ChatGPT login on this machine. Enter the code OpenAI shows you:\n");
+        const ok = await runInteractive(c.path, ["login", "--device-auth"]);
+        const after = codexSignedIn();
+        log(after ? "\n  ✓ Codex is signed in with your ChatGPT account.\n" : "\n  ! Codex still has no login. Run `codex login` in a terminal, then re-run connect.\n");
+        outcome.push({ agent: "Codex", signedIn: after, ran: ok });
+      } else outcome.push({ agent: "Codex", signedIn: true, ran: false });
+    }
+  }
+  return outcome;
 }
 
 /** The same manifest comparison the running Bridge does at startup, printed with the