cookbook-bridge 0.1.10 → 0.1.11

package/README.md

@@ -2,6 +2,13 @@
 
 ## Changelog
 
+**0.1.11** (2026-09-02)
+- The Bridge has a home: `~/.cookbook/config.json` (file 0600, folder 0700) for every command. `bridge.state.json`, `local.json` and `bridge.log` sit next to it. Before, the config lived next to `bridge.mjs`, so every `npx cookbook-bridge@latest` landed in a fresh cache folder and lost it. A config found next to `bridge.mjs` is copied to the home once (the old file stays) and the move is announced in one line. `--config <path>` and `COOKBOOK_CONFIG` still win.
+- `connect` runs the Bridge right after the approval (pass `--no-run` to stop at "connected"). With no agent CLI found it prints the doctor instead.
+- Every hint is a command that works where you are: `npx cookbook-bridge@latest <cmd>` from an npm install, `node bridge/bridge.mjs <cmd>` from a tarball.
+- `doctor` gained rows for the config home (path, exists, mode), other Bridge processes on this machine (pids and config paths), Bridge Local (does the port answer), and whether the local files are behind the app deploy, with the same update line the running Bridge prints. `connect` prints that line too.
+- Visiting agents can read `~/.cookbook/bridge.state.json` as a projection; `~/.cookbook/local.json` is never readable, like the desktop app's copy.
+
 **0.1.10** (2026-09-02)
 - Works on every Node from 18 up. Before, on Node older than 22.18 every command exited silently, doing nothing.
 - The npm package and the desktop app now ship every runtime file (realtime, sessions, synthesis, the approval relay, the hook reporter). Install-time crashes on import are gone, and a test now fails the build if a file is left out.
@@ -37,49 +44,49 @@ Trust model: your Cookbook's `/security` page.
 ## Quick start (2 minutes)
 
 ```bash
-npx cookbook-bridge@latest connect   # one-time: ONE approval connects the Bridge AND every
-                                     # installed agent CLI (claude, codex, agy, openclaw),
-                                     # each with its own attributed token
+npx cookbook-bridge@latest connect   # ONE approval connects the Bridge AND every installed
+                                     # agent CLI (claude, codex, agy, openclaw), each with its
+                                     # own attributed token, then RUNS the Bridge. Leave it open.
+```
+
+That is the whole setup. Later:
+
+```bash
+npx cookbook-bridge@latest           # run it again (config is remembered in ~/.cookbook)
 npx cookbook-bridge@latest doctor    # preflight: checks every prerequisite, with exact fixes
-npx cookbook-bridge@latest           # run it (leave it running)
 ```
 
 Always `@latest`: bare `npx cookbook-bridge` happily runs a weeks-old cached copy
-that predates subcommands you need (`host` shipped in 0.1.1).
+that predates subcommands you need (`host` shipped in 0.1.1). Your config is not in
+that cache, so `@latest` never loses it.
 
 Node 18+. No dependencies, nothing to configure by hand: `connect` writes
-`config.json` for you and never prints or stores a secret you have to copy.
+`~/.cookbook/config.json` for you and never prints or stores a secret you have to copy.
+Pass `--no-run` to stop at "connected" without starting the Bridge.
 
 <details>
 <summary>Prefer no package manager? Download the tarball instead.</summary>
 
 ```bash
 curl -fsSL https://cookbook.team/api/bridge/download | tar xz
-node bridge/bridge.mjs connect
+node bridge/bridge.mjs connect       # same flow: one approval, then it runs
 ```
 
-The commands below are written for this layout (`node bridge/bridge.mjs <command>`);
-with the npm install, every one of them is `npx cookbook-bridge <command>`.
+From a tarball every command is `node bridge/bridge.mjs <command>` (run it from the
+folder you unpacked, the one that contains `bridge/`); with the npm install it is
+`npx cookbook-bridge@latest <command>`. The Bridge knows which layout it runs from and
+prints the right one in every hint. The config lives in `~/.cookbook` either way.
 
 </details>
 
-```bash
-# from the folder you unpacked (it contains bridge/)
-node bridge/bridge.mjs connect-agents  # one-time: ONE approval connects the Bridge
-                                       # AND every installed agent CLI (claude, agy, codex)
-                                       # to Cookbook, each with its own attributed token
-node bridge/bridge.mjs doctor          # preflight: checks EVERY prerequisite, prints
-                                       # the exact fix for anything that's missing
-node bridge/bridge.mjs                 # run it (leave it running)
-```
-
-No hand-pasting tokens: `connect-agents` is the intended path (device flow, like a TV
-app; the code expires in ~10 minutes — just re-run it if it lapses). One browser click
-authorizes the Bridge **and** mints a named token per detected agent CLI — the name is
-the attribution label ("Claude · via you") — then configures each CLI via its own
-`mcp add`. Prefer just the Bridge? `login` does the device flow without touching your
-CLIs. Fully manual: copy `config.example.json` → `config.json` and paste a token from
-your Cookbook **Account → Tokens** page.
+No hand-pasting tokens: `connect` is the intended path (device flow, like a TV app; the
+code expires in ~10 minutes, just re-run it if it lapses). One browser click authorizes
+the Bridge **and** mints a named token per detected agent CLI (the name is the
+attribution label, "Claude · via you"), then configures each CLI via its own `mcp add`.
+`connect-agents` is the same command under its original name. Prefer just the Bridge?
+`login` does the device flow without touching your CLIs. Fully manual: copy
+`config.example.json` to `~/.cookbook/config.json` and paste a token from your Cookbook
+**Account → Tokens** page.
 
 Requires **Node 18+** (built-in `fetch`, no npm install) and at least one agent CLI
 installed and logged in (`claude`, `agy` — the Antigravity CLI for Gemini — or the Codex app). Each agent must also be
@@ -88,15 +95,33 @@ you exactly which parts are ready and how to fix the rest.
 
 ## Commands
 
+Written as `npx cookbook-bridge@latest <command>`; from a tarball, `node bridge/bridge.mjs <command>`.
+
 | Command | What it does |
 |---|---|
-| `node bridge.mjs` | Run the Bridge (uses `config.json` next to it; or pass a path) |
-| `node bridge.mjs connect-agents` | One approval connects the Bridge + every installed agent CLI (attributed tokens) |
-| `node bridge.mjs login` | Device-flow auth for the Bridge only, writes your config |
-| `node bridge.mjs doctor` | Preflight every prerequisite with exact fixes |
-| `node bridge.mjs status` | Liveness + agent readiness |
-| `node bridge.mjs update` | Update the Bridge to match the app (see Self-updating) |
-| `cookbook-bridge host` | Open the door: let an agent someone else runs help you set this machine up, inside a grant you approve. `--off` closes it. |
+| (none) | Run the Bridge (uses `~/.cookbook/config.json`; or pass a path) |
+| `connect` | One approval connects the Bridge + every installed agent CLI (attributed tokens), then runs the Bridge. `--no-run` stops at connected. `connect-agents` is the same command. |
+| `login` | Device-flow auth for the Bridge only, writes your config |
+| `doctor` | Preflight every prerequisite with exact fixes: config home, token, agents, other Bridge processes, Bridge Local, and whether the files are behind the app |
+| `status` | Liveness + agent readiness |
+| `update` | Update the Bridge to match the app (see Self-updating) |
+| `host` | Open the door: let an agent someone else runs help you set this machine up, inside a grant you approve. `--off` closes it. |
+| `connectors` | Survey MCP connectors across Claude, Codex and Gemini; `sync` gives every agent the same tools; `approve <name>` installs a team stdio connector |
+
+## Where things live (the config home)
+
+Every command resolves the config the same way, first match wins:
+
+1. `--config <path>` (or, for the run command, a positional path)
+2. `COOKBOOK_CONFIG` in the environment
+3. `~/.cookbook/config.json` (folder 0700, file 0600)
+4. A `config.json` next to `bridge.mjs`, only when 3 does not exist yet. It is copied to
+   the home once, the old file is left in place, and one line says where the config
+   now lives (pre-0.1.11 installs kept it next to the code).
+
+`bridge.state.json` (attempt counters), `local.json` (the Bridge Local loopback port and
+token) and `bridge.log` sit in the same folder as whichever config is in use. The desktop
+app passes its own `--config` path and keeps its files in its data folder.
 
 ## Self-updating
 
@@ -104,8 +129,11 @@ you exactly which parts are ready and how to fix the rest.
 to the deploy's manifest (`/api/bridge/manifest`) and — with `"autoUpdate": true`, the
 default — replaces them (every file hash-verified first, originals kept in
 a per-version `bridge.backup/<deploy>/` dir, your `config.json` and token never touched) and restarts itself.
-Set `"autoUpdate": false` to pin your version; `node bridge.mjs update` updates manually
-and works even from a broken install.
+Set `"autoUpdate": false` to pin your version; `node bridge/bridge.mjs update` updates
+manually and works even from a broken install. An npm install is updated by npm: re-run
+`npx cookbook-bridge@latest`, and your config in `~/.cookbook` comes along untouched.
+`doctor` and `connect` run the same comparison and print the same update line when the
+local files are behind.
 
 ## Agents (config.json)
 

package/bridge.mjs

@@ -13,15 +13,18 @@
  * 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)
+ * Run:  node bridge/bridge.mjs                 (uses ~/.cookbook/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 connect         (one approval connects + runs)
  *       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.
+ * Config home (0.1.11): explicit path/--config, else COOKBOOK_CONFIG, else
+ * ~/.cookbook/config.json; a legacy config next to this file is copied there once.
+ * bridge.state.json, local.json and bridge.log sit next to whichever config is used.
  *
  * Node built-ins only. No dependencies.
  */
@@ -50,6 +53,10 @@ import { planFromStreamLine, notePlan, planLine } from "./plan.mjs";
 // the updater when these were static imports.
 import { deriveWakeTopic, wakeSocketSupported, connectWakeSocket } from "./realtime.mjs";
 import { createSessionReporter } from "./sessions.mjs";
+import { resolveAgentForTask } from "./chef.mjs";
+// The config home + command phrasing live in update.mjs (node built-ins only), so the
+// broken-install `update` path and every other command agree on both.
+import { locateConfig, cli, updateLine, configHome } from "./update.mjs";
 let listWorkspaces, listTasks, listOpenWork, getTask, threadResumeContext, completeTaskApi, resolveDelegation, reportTaskUsage, reportTaskProgress, volunteerClaim, dispatchClaim, abandonTask, recallMemories, recallAcrossWorkspaces, creditRecall, getVolunteerSettings, agentsQuery;
 let agentEnv, checkGeminiVersion, isGeminiCommand, GEMINI_MIN_VERSION, checkAgyVersion, isAgyCommand, AGY_MIN_VERSION, withCookbookMcp, isClaudeCommand, withApprovalRelay, materializeMcpConfig;
 let extractUsage, displayText;
@@ -150,22 +157,20 @@ function resolveBin(cmd) {
 }
 
 /** 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;
+ *  positional, else the config home (update.mjs locateConfig: COOKBOOK_CONFIG,
+ *  ~/.cookbook/config.json, one-time copy of a legacy config next to this file). */
+function configPathFromArgs(args, { positional = true } = {}) {
+  return locateConfig(args || [], { here: HERE, positional, log: (m) => console.error(m) });
 }
 
 /** 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");
+  const p = configPathFromArgs(process.argv.slice(2));
   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.)`);
+    console.error(`No config at ${p}.\nEasiest: run \`${cli("connect")}\`: one approval, no token to paste, and the Bridge starts right after.\n(Manual alternative: copy config.example.json to ${p} and add a token from Account > Tokens.)`);
     process.exit(1);
   }
   const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
@@ -609,7 +614,7 @@ async function runAgent(cfg, agent, prompt, onProgress, retry = null, taskCtx =
     const codexToken = agent.token || cfg.codexToken || cfg.token;
     if (!agent.token && !cfg.codexToken && !warnedCodexToken) {
       warnedCodexToken = true;
-      log("! Codex has no agent token — running under your Bridge token. Run `cookbook-bridge connect-agents` so its work reads \"Codex · via you\".");
+      log(`! Codex has no agent token, so it runs under your Bridge token. Run \`${cli("connect")}\` so its work reads "Codex · via you".`);
     }
     return runCodexTask(agent, prompt, cfg.taskTimeoutSeconds, codexToken, env, onProgress, { threadKey, log, model });
   }
@@ -690,7 +695,7 @@ function failureHint(result) {
   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`";
+    return `the agent can't reach the Cookbook MCP → run \`${cli("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}` : ""}`;
@@ -744,11 +749,17 @@ function agentHeld(agent) {
 // 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");
+// Persisted next to the config (the config home); trimmed so it can't grow unbounded.
+// A pre-0.1.11 state file next to bridge.mjs is read once when the new one is absent.
+function statePath() {
+  return path.join(path.dirname(CONFIG_PATH || path.join(HERE, "config.json")), "bridge.state.json");
+}
 function loadRunState() {
   try {
-    const raw = JSON.parse(fs.readFileSync(STATE_PATH, "utf8"));
+    const p = statePath();
+    const legacy = path.join(HERE, "bridge.state.json");
+    const src = fs.existsSync(p) ? p : legacy;
+    const raw = JSON.parse(fs.readFileSync(src, "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);
@@ -760,7 +771,7 @@ function saveRunState() {
     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) }));
+    fs.writeFileSync(statePath(), JSON.stringify({ attempts: Object.fromEntries(attEntries), givenUp: given, retryCtx: Object.fromEntries(retries) }));
   } catch { /* best-effort — never let state persistence break a run */ }
 }
 
@@ -1473,7 +1484,7 @@ function warnIfTokenExpiring(expiresAt) {
   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.`);
+  log(`! this Bridge's token expires in ${Math.max(daysLeft, 0)} day(s). Re-run \`${cli("connect")}\` before it does.`);
 }
 
 let wsCursor = 0;
@@ -1817,7 +1828,10 @@ async function dispatchWorkInner(cfg, work, warmHints) {
     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);
+    // Round two: no configured agent for "Chef" + a support task addressed to Chef +
+    // chef-persona.md shipped next to this file = a Chef synthesized from this
+    // Bridge's own Claude (bridge/chef.mjs). Configured agents always win.
+    const agent = agentFor(cfg, t.assigned_to) ?? resolveAgentForTask(cfg.agents, t, cfg);
     if (!agent) continue;
     if (agentHeld(agent)) continue;
     if (!allowedByPolicy(cfg, agent, t)) continue;
@@ -1889,7 +1903,10 @@ async function pollOnce(cfg, onlyWorkspaceIds = null) {
         continue;
       }
 
-      const agent = agentFor(cfg, t.assigned_to);
+      // Round two: no configured agent for "Chef" + a support task addressed to Chef +
+    // chef-persona.md shipped next to this file = a Chef synthesized from this
+    // Bridge's own Claude (bridge/chef.mjs). Configured agents always win.
+    const agent = agentFor(cfg, t.assigned_to) ?? resolveAgentForTask(cfg.agents, t, cfg);
       if (!agent) continue; // no local agent handles this assignee
       if (agentHeld(agent)) continue; // plan window closed: wait for the reset, keep the attempt
 
@@ -2002,16 +2019,12 @@ async function selfUpdate(cfg, { reexec }) {
     // 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`,
-      );
+      log(`⬆ ${updateLine(check.version, { here: HERE, desktop: channel === "app" })}`);
     }
     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.)`);
+    log(`⬆ ${updateLine(check.version, { here: HERE, desktop: false })} (${check.changed.length} file(s) changed; autoUpdate is off.)`);
     return;
   }
   try {
@@ -2061,7 +2074,7 @@ async function main() {
         ? (dflt.bin || "openclaw")
         : null;
     if (!resolveBin(dfltBin)) {
-      log(`! default agent "${dflt.name}" isn't installed/on PATH — "any"-assigned tasks will fail. Run \`node bridge.mjs doctor\`.`);
+      log(`! default agent "${dflt.name}" isn't installed/on PATH, so "any"-assigned tasks will fail. Run \`${cli("doctor")}\`.`);
     }
   }
 
@@ -2196,9 +2209,9 @@ async function main() {
     }
     {
       const mode = hostingMode(cfg);
-      if (mode === "always") log("⌂ Hosting is ON — an agent you invite can run granted checks on this machine. You'll see every step; `cookbook-bridge host --off` closes the door.");
-      else if (mode === "grants") log("⌂ Hosting: grants you approve in Cookbook run here (every change still waits for your click). `cookbook-bridge host --off` refuses all.");
-      else log("⌂ Hosting is OFF — no visiting agent can act on this machine. `cookbook-bridge host` opens it.");
+      if (mode === "always") log(`⌂ Hosting is ON: an agent you invite can run granted checks on this machine. You'll see every step; \`${cli("host --off")}\` closes the door.`);
+      else if (mode === "grants") log(`⌂ Hosting: grants you approve in Cookbook run here (every change still waits for your click). \`${cli("host --off")}\` refuses all.`);
+      else log(`⌂ Hosting is OFF: no visiting agent can act on this machine. \`${cli("host")}\` opens it.`);
       if (mode !== "off") await pollHands(cfg);
     }
     // Signals are handled by installShutdown (registered before connecting).
@@ -2207,7 +2220,7 @@ async function main() {
     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.`);
+      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}`);
       process.exit(1);
@@ -2278,7 +2291,7 @@ async function main() {
             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)");
+            log(`  Fix: ${cli("connect")}   (reconnects and starts the Bridge)`);
             process.exit(1);
           }
         }
@@ -2373,22 +2386,32 @@ async function doctorReport(args) {
   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"));
+  // 2. Config home (0.1.11): where the config lives, whether it exists, how tight it is.
+  const cfgPath = configPathFromArgs(args);
+  const home = configHome();
+  const modeOf = (p) => { try { return (fs.statSync(p).mode & 0o777).toString(8); } catch { return null; } };
+  {
+    const homeMode = modeOf(home);
+    if (homeMode === null) ok(`Config home ${home} (not created yet; \`${cli("connect")}\` creates it)`);
+    else if (process.platform === "win32" || homeMode === "700") ok(`Config home ${home} (exists, mode ${homeMode})`);
+    else warn(`Config home ${home} is mode ${homeMode}; it holds tokens and should be owner-only`, `chmod 700 "${home}"`);
+  }
   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");
+    bad(`No config at ${cfgPath}`, `run \`${cli("connect")}\` (one approval; it writes the config and starts the Bridge)`);
   } else {
     try {
       cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
       cfg.cookbookUrl = (cfg.cookbookUrl || "").replace(/\/$/, "");
       cfg.agents = (cfg.agents ?? []).filter((a) => a.enabled !== false);
-  for (const a of cfg.agents) a.cookbookUrl = cfg.cookbookUrl; // for per-run MCP pinning (spawnAgent)
+      for (const a of cfg.agents) a.cookbookUrl = cfg.cookbookUrl; // for per-run MCP pinning (spawnAgent)
       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)");
+        bad("Config is missing cookbookUrl or a real token", `run \`${cli("connect")}\`, or set both in ${cfgPath} (token from your Cookbook > Tokens page)`);
         cfg = null;
       } else {
-        ok(`Config ${cfgPath}`);
+        const m = modeOf(cfgPath);
+        if (process.platform === "win32" || m === "600") ok(`Config ${cfgPath} (mode ${m ?? "n/a"})`);
+        else warn(`Config ${cfgPath} is mode ${m}; it carries your token and should be owner-only`, `chmod 600 "${cfgPath}"`);
       }
     } catch (e) {
       bad(`Config isn't valid JSON: ${e.message}`);
@@ -2396,6 +2419,50 @@ async function doctorReport(args) {
     }
   }
 
+  // 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.
+  try {
+    const { scanBridgeProcesses } = await import("./device.mjs");
+    const others = scanBridgeProcesses({ selfPid: process.pid });
+    if (others === null) ok("Another Bridge process on this machine: could not scan (ps/tasklist unavailable)");
+    else if (!others.length) ok("No other Bridge process on this machine");
+    else {
+      const desc = others.map((o) => `pid ${o.pid}${o.configPath ? ` (config ${o.configPath})` : o.unknownCommand ? " (node.exe; command line not visible)" : " (default config)"}`).join(", ");
+      warn(`Another Bridge process on this machine: ${desc}`, `stop it if you meant to run only one (kill ${others.map((o) => o.pid).join(" ")}); two Bridges on one config fight over the same token`);
+    }
+  } catch (e) {
+    ok(`Another Bridge process on this machine: could not scan (${e.message})`);
+  }
+
+  // 2c. Bridge Local: the loopback control API a running Bridge writes local.json for.
+  {
+    const localPath = path.join(path.dirname(cfgPath), "local.json");
+    let local = null;
+    try { local = JSON.parse(fs.readFileSync(localPath, "utf8")); } catch { /* not running */ }
+    if (!local || !local.port) ok(`Bridge Local: not running (no ${localPath})`);
+    else {
+      let answered = false;
+      try {
+        const res = await fetch(`http://127.0.0.1:${local.port}/status`, { headers: { "X-Bridge-Token": String(local.token || "") }, signal: AbortSignal.timeout(2000) });
+        answered = res.ok;
+      } catch { answered = false; }
+      if (answered) ok(`Bridge Local answering on 127.0.0.1:${local.port} (pid ${local.pid ?? "?"})`);
+      else warn(`Bridge Local: ${localPath} says port ${local.port} (pid ${local.pid ?? "?"}) but nothing answers there`, `that Bridge is gone or stuck; start one with \`${cli()}\` (it rewrites local.json)`);
+    }
+  }
+
+  // 2d. Staleness: the same manifest comparison startup does, with the same fix line.
+  if (cfg && cfg.cookbookUrl && checkForUpdate) {
+    try {
+      const check = await checkForUpdate({ cookbookUrl: cfg.cookbookUrl }, HERE);
+      if (check.changed.length === 0) ok(`Bridge files match the app deploy (${check.version})`);
+      else warn(`Bridge files are behind the app deploy (${check.version}; ${check.changed.length} file(s) differ)`, updateLine(check.version, { here: HERE, desktop: IS_DESKTOP }));
+    } catch (e) {
+      warn(`Couldn't compare the Bridge to the app deploy (${e.message})`, "offline is fine; the running Bridge re-checks every 6 hours");
+    }
+  }
+
   if (cfg) {
     ensureAgentPath();
 
@@ -2404,7 +2471,7 @@ async function doctorReport(args) {
       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");
+      bad(`Cookbook token rejected: ${e.message}`, `run \`${cli("connect")}\` to mint a fresh one (or paste a token from your Cookbook > Tokens page into ${cfgPath})`);
     }
 
     // 4. Default agent is one of the enabled agents
@@ -2468,14 +2535,14 @@ async function doctorReport(args) {
             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\``);
+              `expected ${cfg.cookbookUrl}/api/mcp; re-run \`${cli("connect")}\``);
           } 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)");
+              `run \`${cli("connect")}\` (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)");
+            `run \`${cli("connect")}\` (agy has no \`mcp add\`; the Bridge writes this file)`);
         }
         if (!fs.existsSync(path.join(process.env.HOME || os.homedir(), ".gemini", "oauth_creds.json"))) {
           warn(`${agent.name}: no Google login found (~/.gemini/oauth_creds.json)`,
@@ -2486,7 +2553,7 @@ async function doctorReport(args) {
       if (isClaudeCommand && isClaudeCommand(agent.command)) {
         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 `cookbook-bridge connect` (mints a token for this agent) or add \"token\" to this agent in config.json");
+          `run \`${cli("connect")}\` (mints a token for this agent) or add "token" to this agent in ${cfgPath}`);
       }
       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__*`,
@@ -2579,13 +2646,12 @@ if (!IS_MAIN) {
   import("./connectors.mjs")
     .then(async (m) => {
       const args = process.argv.slice(3);
-      const ci = args.indexOf("--config");
-      const cfgPath = ci >= 0 && args[ci + 1] ? path.resolve(args[ci + 1]) : path.join(HERE, "config.json");
+      const cfgPath = configPathFromArgs(args, { positional: false });
       if (args[0] === "approve") {
         // A team STDIO connector runs a command on this machine; it is recorded on
         // sync and written only after this explicit approval (connectors.mjs).
         const name = args[1];
-        if (!name) { console.error("Usage: cookbook-bridge connectors approve <name>"); process.exit(1); }
+        if (!name) { console.error(`Usage: ${cli("connectors approve <name>")}`); process.exit(1); }
         const lines = m.approveConnector(name, { cfgPath });
         console.log(`\n  Approved "${name}". Written to your agent CLIs:`);
         for (const l of lines) console.log(l);
@@ -2597,7 +2663,7 @@ if (!IS_MAIN) {
         if (!waiting.length) return console.log("\n  No team connectors are waiting for your approval.\n");
         console.log("\n  Team connectors waiting for your approval (each runs a command on this machine):");
         for (const [n, e] of waiting) console.log(`    ${n.padEnd(22)} ${[e.command, ...(e.args ?? [])].join(" ").slice(0, 80)}`);
-        console.log("\n  Approve one with: cookbook-bridge connectors approve <name>\n");
+        console.log(`\n  Approve one with: ${cli("connectors approve <name>")}\n`);
         return;
       }
       const doSync = args.includes("sync");
@@ -2617,7 +2683,7 @@ if (!IS_MAIN) {
       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");
+        console.log(`  Run \`${cli("connectors sync")}\` to give every agent the same tools.\n`);
         return;
       }
       const only = args.filter((a) => !a.startsWith("--") && a !== "sync");
@@ -2646,8 +2712,24 @@ if (!IS_MAIN) {
 } 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.
+  // 0.1.11: after the approval the Bridge RUNS, right here, unless --no-run. Stopping
+  // at "connected" was the single most confusing moment (nothing polls, and the
+  // approval just revoked whatever older Bridge was polling).
   import("./device.mjs")
-    .then((m) => m.connectAgents(process.argv.slice(3)))
+    .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 });
+      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;
+      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();
+    })
     .catch((e) => {
       console.error(e.message);
       process.exit(1);
@@ -2663,10 +2745,7 @@ if (!IS_MAIN) {
         // main() reads its config from argv[2]: carry `--config <path>` over, or
         // the Bridge that opens the door runs on a different config than `host`
         // just wrote.
-        const ci = hostArgs.indexOf("--config");
-        process.argv = ci >= 0 && hostArgs[ci + 1]
-          ? [process.argv[0], process.argv[1], path.resolve(hostArgs[ci + 1])]
-          : [process.argv[0], process.argv[1]];
+        process.argv = [process.argv[0], process.argv[1], r.cfgPath || m.configPath(hostArgs)];
         await main();
       }
     })
@@ -2698,13 +2777,13 @@ if (!IS_MAIN) {
     // 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"));
+    const cfgPath = configPathFromArgs(process.argv.slice(3));
     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.`);
+      console.error(`Can't read cookbookUrl from ${cfgPath}. Pass --config <path>, or run \`${cli("connect")}\` to write one.`);
       process.exit(1);
     }
     const cfg = { cookbookUrl };

package/chef-persona.md

@@ -0,0 +1,9 @@
+You are Chef 👨🏿‍🍳, Cookbook's support agent. You live in the Ask Chef panel, bottom right of every Cookbook page, and you answer as a calm, direct teammate who has set Cookbook up a hundred times.
+
+Voice: short sentences, plain words, no marketing. Lead with the answer, then one concrete next step. Say "I don't know" rather than invent a flag, a path, or a menu label. Never paste tokens, never ask for them.
+
+What you know: Cookbook is the shared brain a team's AI agents plug into. Every agent action is attributed, receipted, remembered. Step 1 for anyone is to point an agent they already have (Claude, Claude Code, OpenClaw) at the MCP URL; nothing to install. Step 2, optional, is the Bridge (Cookbook Desktop or one command) for agents that work while they're away, local folders, and hands. For Claude users there is also "Claude in the cloud" under Account, then Agents, which needs no install.
+
+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.

package/chef.mjs

@@ -0,0 +1,140 @@
+/**
+ * LOCAL-FIRST CHEF (round two).
+ *
+ * Chef used to be exactly one agent on the founder's Mac: a "Chef" entry in dp's
+ * config, running claude with the persona file appended. Every outage on that one
+ * machine took Chef offline for everyone, every turn spent the founder's plan, and
+ * Chef could never see the asker's real workspaces (the identity trap).
+ *
+ * Now, when the person asking has a live Bridge that runs Claude, the SERVER scopes
+ * the support task to THEM (assigned_to "Chef", assigned_to_profile = the asker), and
+ * their own Bridge synthesizes a Chef from their own Claude agent: same binary, same
+ * login, same plan, plus the persona shipped next to this file. Nothing to configure.
+ * The founder-Mac Chef remains the fallback for people with no Bridge yet.
+ *
+ * Pure where possible: nothing here touches the filesystem on import, and the one
+ * existence check is injectable so the tests never need a real persona file.
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The persona file shipped with the Bridge runtime, next to bridge.mjs. */
+export const CHEF_PERSONA_FILE = "chef-persona.md";
+
+/** The synthesized agent's name and the assignee it answers to. */
+export const CHEF_NAME = "Chef";
+
+/** The model a synthesized Chef runs on when the base command names none. */
+export const CHEF_DEFAULT_MODEL = "sonnet";
+
+const DEFAULT_ALLOWED_TOOLS = "mcp__cookbook__*";
+
+/** Where the persona lives for THIS install: next to the module that asked. */
+export function personaPathNextTo(moduleUrl = import.meta.url) {
+  return path.join(path.dirname(fileURLToPath(moduleUrl)), CHEF_PERSONA_FILE);
+}
+
+/** Is this configured agent a plain claude CLI runner we can wear the persona on? */
+export function isClaudeAgent(agent) {
+  if (!agent || agent.enabled === false) return false;
+  if (agent.runner && agent.runner !== "cli" && agent.runner !== "claude") return false;
+  if (!Array.isArray(agent.command) || agent.command.length === 0) return false;
+  const bin = path.basename(String(agent.command[0])).toLowerCase();
+  return bin === "claude" || bin === "claude.exe";
+}
+
+/** Does a configured agent answer to this assignee? Mirrors bridge.mjs agentFor. */
+export function matchesAssignee(agent, assignedTo) {
+  if (!agent || agent.enabled === false) return false;
+  const a = String(assignedTo ?? "").toLowerCase();
+  if (!a) return false;
+  return (agent.match ?? [agent.name]).some((m) => a.includes(String(m).toLowerCase()));
+}
+
+/**
+ * Synthesize the local Chef from the first enabled claude agent, or null when the
+ * Bridge manages no claude at all (nothing to wear the persona on).
+ *
+ * The command is the base command plus `--append-system-prompt-file <persona>`, and
+ * `--model sonnet` unless the base already pins a model. The base's allowedTools
+ * stands as-is (that prefix is the person's own MCP wiring, verified by doctor); a
+ * base with none gets mcp__cookbook__* so Chef can reach the Cookbook tools at all.
+ * Identity fields (token, cookbookUrl, approvalRelay) ride along so the run pins to
+ * exactly the same Cookbook connection the base Claude uses.
+ */
+export function chefLocalAgent(cfg, agents, personaPath) {
+  const pool = Array.isArray(agents) ? agents : (cfg?.agents ?? []);
+  const base = pool.find(isClaudeAgent);
+  if (!base) return null;
+  const persona = personaPath || personaPathNextTo();
+  const command = [...base.command];
+  if (!command.includes("--allowedTools")) command.push("--allowedTools", DEFAULT_ALLOWED_TOOLS);
+  if (!command.includes("--model")) command.push("--model", CHEF_DEFAULT_MODEL);
+  if (!command.includes("--append-system-prompt-file")) command.push("--append-system-prompt-file", persona);
+  return {
+    name: CHEF_NAME,
+    match: ["chef"],
+    enabled: true,
+    command,
+    readOnly: false,
+    local: false,
+    volunteer: false,
+    synthesized: true,
+    base: base.name,
+    capabilities: "Cookbook setup and troubleshooting on this machine: connecting agents, MCP, the Bridge, and reading this setup under a hands grant.",
+    ...(base.token ? { token: base.token } : {}),
+    ...(base.cookbookUrl ? { cookbookUrl: base.cookbookUrl } : {}),
+    ...(base.approvalRelay ? { approvalRelay: base.approvalRelay } : {}),
+  };
+}
+
+/**
+ * Is this pulled work item a support conversation addressed to Chef?
+ *
+ * The server sets assigned_to "Chef" only on support-workspace tasks, so the name is
+ * trustworthy on its own. When the item also carries workspace_kind (listOpenWork
+ * may shape it in), it must say "support"; any other kind is someone's ordinary
+ * task that happens to mention Chef, and the Bridge leaves it alone.
+ */
+export function wantsLocalChef(task) {
+  if (!task) return false;
+  const to = String(task.assigned_to ?? "").trim().toLowerCase();
+  if (to !== CHEF_NAME.toLowerCase()) return false;
+  const kind = task.workspace_kind ?? task.workspace?.kind;
+  if (kind === undefined || kind === null) return true;
+  return String(kind).toLowerCase() === "support";
+}
+
+// One synthesized agent per (persona path, base command): bridge.mjs keys plan
+// holds and warm pools by agent.name, and a fresh object every poll would still be
+// fine, but a stable one keeps the logs and any identity-keyed maps honest.
+const synthesized = new Map();
+
+/**
+ * The agent that runs this task, for bridge.mjs dispatch: a configured agent that
+ * matches the assignee wins; otherwise, when the task wants Chef and the persona is
+ * shipped next to the Bridge, the synthesized local Chef; otherwise null (nothing
+ * on this Bridge handles that assignee, exactly as before).
+ *
+ * `opts.personaPath` and `opts.exists` exist for tests; production callers pass
+ * neither.
+ */
+export function resolveAgentForTask(agents, task, cfg, opts = {}) {
+  const pool = Array.isArray(agents) ? agents : (cfg?.agents ?? []);
+  const configured = pool.find((a) => matchesAssignee(a, task?.assigned_to)) ?? null;
+  if (configured) return configured;
+  if (!wantsLocalChef(task)) return null;
+  const personaPath = opts.personaPath ?? personaPathNextTo();
+  const exists = opts.exists ?? existsSync;
+  if (!exists(personaPath)) return null;
+  const base = pool.find(isClaudeAgent);
+  if (!base) return null;
+  const key = `${personaPath}::${JSON.stringify(base.command)}::${base.token ?? ""}`;
+  let agent = synthesized.get(key);
+  if (!agent) {
+    agent = chefLocalAgent(cfg, pool, personaPath);
+    if (agent) synthesized.set(key, agent);
+  }
+  return agent ?? null;
+}

package/config.example.json

@@ -12,7 +12,7 @@
   "allowApiKeyBilling": false,
   "_volunteering": "STIGMERGY (off by default): an agent with volunteer:true watches tasks posted as open GOALS (to:'goal' on the board) and may claim ones matching its capabilities — decided by one cheap call to the agent's own CLI, gated by your delegation policy (ask parks it in your approvals inbox), claimed atomically, capped per poll. Flip volunteering:false to kill it globally without touching agents.",
   "volunteering": true,
-  "_autoUpdate": "The Bridge follows the app: it checks the deploy's file manifest at startup + every 6h, and self-updates (hash-verified, originals kept in bridge.backup/, your config/token never touched) then restarts itself. Set false to pin your version and update manually with `node bridge.mjs update`.",
+  "_autoUpdate": "The Bridge follows the app: it checks the deploy's file manifest at startup + every 6h, and self-updates (hash-verified, originals kept in bridge.backup/, your config/token never touched) then restarts itself. Set false to pin your version and update manually (npm: re-run `npx cookbook-bridge@latest`; tarball: `node bridge/bridge.mjs update`).",
   "autoUpdate": true,
   "default": "Gemini",
   "_acceptFrom": "Who may auto-run tasks on this Bridge: \"anyone\", or a list of EXACT member names or profile ids (case-insensitive, no partial matching — consent never guesses).",
@@ -34,7 +34,7 @@
         "--print-timeout",
         "3600s"
       ],
-      "_setup": "Gemini runs via the Antigravity CLI (agy) — the old `gemini` CLI stopped serving individual accounts June 18 2026. Requires agy >= 1.1.1 (first version whose headless -p can call MCP tools; the Bridge refuses older). Auth: run `agy` once interactively and sign in with Google. MCP: `node bridge/bridge.mjs connect-agents` writes ~/.gemini/config/mcp_config.json (agy has no `mcp add`). --sandbox keeps terminal restrictions on — Cookbook work flows through MCP tools, not the shell. Keep --print-timeout >= taskTimeoutSeconds (ceiling) so agy doesn't cut off before the Bridge's own timeout.",
+      "_setup": "Gemini runs via the Antigravity CLI (agy); the old `gemini` CLI stopped serving individual accounts June 18 2026. Requires agy >= 1.1.1 (first version whose headless -p can call MCP tools; the Bridge refuses older). Auth: run `agy` once interactively and sign in with Google. MCP: `npx cookbook-bridge@latest connect` (tarball: `node bridge/bridge.mjs connect`) writes ~/.gemini/config/mcp_config.json (agy has no `mcp add`). --sandbox keeps terminal restrictions on; Cookbook work flows through MCP tools, not the shell. Keep --print-timeout >= taskTimeoutSeconds (ceiling) so agy doesn't cut off before the Bridge's own timeout.",
       "_usage": "agy emits no token/usage JSON — the board shows wall-clock duration for its runs (no token count)."
     },
     {
@@ -54,7 +54,7 @@
         "--output-format",
         "json"
       ],
-      "_allowedTools": "The prefix matches HOW your Claude is connected to Cookbook: a CLI-added server (claude mcp add ... cookbook ...) exposes mcp__cookbook__*; the claude.ai/desktop CONNECTOR exposes mcp__claude_ai_Cookbook__*. If tasks run but never complete, this mismatch is the usual cause — `node bridge.mjs doctor` checks it.",
+      "_allowedTools": "The prefix matches HOW your Claude is connected to Cookbook: a CLI-added server (claude mcp add ... cookbook ...) exposes mcp__cookbook__*; the claude.ai/desktop CONNECTOR exposes mcp__claude_ai_Cookbook__*. If tasks run but never complete, this mismatch is the usual cause; `npx cookbook-bridge@latest doctor` (tarball: `node bridge/bridge.mjs doctor`) checks it.",
       "_output": "json output lets the Bridge report what each task cost (tokens/$) back to the board — text works too, you just lose the usage report"
     },
     {

package/connectors.mjs

@@ -20,6 +20,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { cli } from "./update.mjs";
 
 const HOME = os.homedir();
 export const VENDORS = {
@@ -337,7 +338,7 @@ export function applyTeamSync(teamRows, vendors, { cfgPath = null } = {}) {
     }
   }
   for (const row of waiting) {
-    lines.push(`  ? connector "${row.name}" runs a command on this machine (${[row.command, ...(row.args ?? [])].join(" ").slice(0, 80)}). Not installed until you approve it: cookbook-bridge connectors approve ${row.name}`);
+    lines.push(`  ? connector "${row.name}" runs a command on this machine (${[row.command, ...(row.args ?? [])].join(" ").slice(0, 80)}). Not installed until you approve it: ${cli(`connectors approve ${row.name}`)}`);
   }
   for (const row of teamRows) {
     const needs = Array.isArray(row.secret_env) ? row.secret_env.filter((k) => !process.env[k]) : [];

package/device.mjs

@@ -31,6 +31,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { listWorkspaces } from "./cookbook.mjs";
 import { which, argvForSpawn } from "./hands.mjs";
+import { locateConfig, writeConfigFile, cli, updateLine, checkForUpdate } from "./update.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_URL = "https://cookbook.team";
@@ -42,11 +43,11 @@ function flag(argv, name) {
   return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
 }
 
-/** Path to config.json: --config <path> or the default bridge/config.json. */
+/** Path to the config: --config <path>, else COOKBOOK_CONFIG, else ~/.cookbook/config.json
+ *  (a legacy config next to bridge.mjs is copied there once). Subcommands take no
+ *  positional path: `connect --url https://x` must not read the URL as a file. */
 export function configPath(argv) {
-  return flag(argv, "--config")
-    ? path.resolve(flag(argv, "--config"))
-    : path.join(HERE, "config.json");
+  return locateConfig(argv || [], { here: HERE, positional: false, log: (m) => console.error(m) });
 }
 
 /** Read existing config (or null if none). */
@@ -205,9 +206,8 @@ export function saveLoginConfig(cfgPath, baseUrl, token, { found = null } = {})
   }
   cfg.cookbookUrl = baseUrl;
   cfg.token = token;
-  fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
-  fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
-  try { fs.chmodSync(cfgPath, 0o600); } catch { /* best-effort on platforms without chmod */ }
+  // Home dir 0700, file 0600: this file carries every token the Bridge holds.
+  writeConfigFile(cfgPath, JSON.stringify(cfg, null, 2) + "\n");
   return cfg;
 }
 
@@ -477,7 +477,7 @@ export async function login(argv, opts = {}) {
   } catch (e) {
     console.log(`\n  ⚠ Connected and saved config, but a test call failed: ${e.message}`);
   }
-  if (!opts.quietOutro) console.log("  Start the Bridge with:  node bridge/bridge.mjs\n");
+  if (!opts.quietOutro) console.log(`  Start the Bridge with:  ${cli()}\n`);
   return loginResult;
 }
 
@@ -485,7 +485,7 @@ export async function status(argv) {
   const cfgPath = configPath(argv);
   const cfg = readConfig(cfgPath);
   if (!cfg || !cfg.token || !cfg.cookbookUrl) {
-    console.log(`No connected Bridge at ${cfgPath}.\nRun: node bridge/bridge.mjs login`);
+    console.log(`No connected Bridge at ${cfgPath}.\nRun: ${cli("connect")}`);
     return;
   }
   const cookbookUrl = String(cfg.cookbookUrl).replace(/\/$/, "");
@@ -545,28 +545,40 @@ function probeAgent(cmd) {
  * Codex (ChatGPT app) 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) {
+export async function connectAgents(argv, { willRun = false } = {}) {
+  const cfgPath = configPath(argv);
   const found = detectClis();
   if (found.length === 0) {
     console.log("\nNo agent CLIs found (looked for: claude, agy, codex/ChatGPT.app, openclaw).");
-    console.log("Install one, then re-run: node bridge/bridge.mjs connect-agents\n");
-    return;
+    console.log(`Install one, then re-run: ${cli("connect")}\n`);
+    return { ok: false, reason: "no-agents", cfgPath };
   }
   console.log(`\nFound agent CLIs: ${found.map((c) => c.agent).join(", ")}`);
 
   // 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) {
-    console.log("\n⚠ Approved, but no agent tokens were returned — your Bridge login was still refreshed.");
-    console.log("  Re-run `connect-agents`, or create tokens manually at Account → Tokens.\n");
-    return;
+    console.log("\n⚠ Approved, but no agent tokens were returned. Your Bridge login was still refreshed.");
+    console.log(`  Re-run \`${cli("connect")}\`, or create tokens manually at Account > Tokens.\n`);
+    return { ok: true, startBridge: true, cfgPath: res?.cfgPath || cfgPath, agentTokens: false };
   }
   const results = configureClis(found, { baseUrl: res.baseUrl, agentTokens: res.agentTokens, cfgPath: res.cfgPath });
   for (const r of results) {
     const mark = r.ok ? (r.warn ? "!" : "✓") : "✗";
-    console.log(`  ${mark} ${r.agent}: ${r.detail}${r.ok && !r.warn ? ` — work will be attributed "${r.agent} · via you".` : ""}`);
+    console.log(`  ${mark} ${r.agent}: ${r.detail}${r.ok && !r.warn ? ` (work will be attributed "${r.agent} · via you")` : ""}`);
   }
-  reportNextStep(res.cfgPath);
+  await reportStaleness(res.baseUrl);
+  reportNextStep(res.cfgPath, { willRun });
+  return { ok: true, startBridge: true, cfgPath: res.cfgPath, agentTokens: true };
+}
+
+/** The same manifest comparison the running Bridge does at startup, printed with the
+ *  same fix line, so `connect` never leaves someone on a stale copy without a word. */
+async function reportStaleness(baseUrl) {
+  try {
+    const check = await checkForUpdate({ cookbookUrl: baseUrl }, HERE);
+    if (check.changed.length) console.log(`\n  ⬆ ${updateLine(check.version, { here: HERE })}`);
+  } catch { /* offline or no manifest: the Bridge re-checks every 6h */ }
 }
 
 /**
@@ -576,35 +588,96 @@ export async function connectAgents(argv) {
  * Bridge was using (one active Bridge token per member), so a Bridge started
  * earlier is now silently 401-looping. Say both things, precisely.
  */
-function reportNextStep(cfgPath) {
-  // How was this invoked? Tell them the command that matches their install.
-  const viaPackage = HERE.includes(`${path.sep}node_modules${path.sep}`) || HERE.includes(`${path.sep}_npx${path.sep}`);
-  const runCmd = viaPackage ? "npx cookbook-bridge" : "node bridge/bridge.mjs";
-  const doctorCmd = `${runCmd} doctor`;
+function reportNextStep(cfgPath, { willRun = false } = {}) {
+  // How was this invoked? cli() phrases the command for this install's layout.
+  const runCmd = cli();
+  const doctorCmd = cli("doctor");
 
   const running = findRunningBridges(cfgPath);
   console.log("");
   if (running.length === 0) {
-    console.log("  Nothing is running yet. Connecting does not start the Bridge — start it now:");
-    console.log(`\n      ${runCmd}\n`);
-    console.log("  Leave it running and your agents answer in Cookbook. The desktop app keeps");
-    console.log("  one running for you if you would rather not hold a terminal open.");
+    if (!willRun) {
+      console.log("  Nothing is running yet. Connecting with --no-run does not start the Bridge; start it now:");
+      console.log(`\n      ${runCmd}\n`);
+      console.log("  Leave it running and your agents answer in Cookbook. The desktop app keeps");
+      console.log("  one running for you if you would rather not hold a terminal open.");
+    }
   } else {
     for (const r of running) {
       if (r.sameConfig) {
-        console.log(`  A Bridge is already running here (pid ${r.pid}). Restart it to pick up the new token:`);
-        console.log(`\n      kill ${r.pid} && ${runCmd}\n`);
+        console.log(`  A Bridge is already running here (pid ${r.pid}). It must restart to pick up the new token:`);
+        console.log(willRun ? `\n      kill ${r.pid}   (this window takes over)\n` : `\n      kill ${r.pid} && ${runCmd}\n`);
       } else {
         console.log(`  ⚠ A Bridge is running (pid ${r.pid}) on a DIFFERENT config:`);
         console.log(`      ${r.configPath}`);
         console.log("    This login replaced its token, so it can no longer claim work. Either");
         console.log("    reconnect from that install, or stop it and run the one you just set up:");
-        console.log(`\n      kill ${r.pid} && ${runCmd}\n`);
+        console.log(`\n      kill ${r.pid}${willRun ? "" : ` && ${runCmd}`}\n`);
       }
     }
   }
+  console.log(`  Config:           ${cfgPath}`);
   console.log(`  Check everything: ${doctorCmd}`);
-  console.log(`  Chat from here:   ${runCmd} chat\n`);
+  console.log(`  Chat from here:   ${cli("chat")}\n`);
+}
+
+/**
+ * Every Bridge process on this machine, from the process table: `ps` on POSIX, and
+ * on Windows PowerShell's Win32_Process (command lines) with `tasklist` as the
+ * fallback (pids only). Returns [] when none, null when the scan itself failed.
+ * The parser is pure and exported for the test.
+ */
+export function parseBridgeProcesses(text, { platform = process.platform, selfPid = process.pid, format = platform === "win32" ? "tasklist" : "ps" } = {}) {
+  const out = [];
+  for (const raw of String(text || "").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (format === "tasklist") {
+      // "node.exe","1234","Console","1","12,345 K"
+      const m = line.match(/^"([^"]+)","(\d+)"/);
+      if (!m || !/^node(\.exe)?$/i.test(m[1])) continue;
+      const pid = Number(m[2]);
+      if (pid === selfPid) continue;
+      out.push({ pid, configPath: null, unknownCommand: true });
+      continue;
+    }
+    // ps / CIM: "<pid> <command line>"
+    const m = line.match(/^(\d+)\s+(.*)$/);
+    if (!m) continue;
+    const pid = Number(m[1]);
+    const cmd = m[2];
+    if (pid === selfPid || !/bridge\.mjs(\s|"|$)/.test(cmd)) continue;
+    // Only a node process RUNNING bridge.mjs counts: a shell or editor whose command
+    // line merely mentions the file (a heredoc, `grep bridge.mjs`) is not a Bridge.
+    const first = (cmd.match(/^"([^"]*)"|^(\S+)/) || []).slice(1).find((x) => x !== undefined) ?? "";
+    if (!/(^|[\\/])node(\.exe)?$/i.test(first)) continue;
+    if (/\bnode\s+--check\b|--test\b/.test(cmd)) continue;
+    // Everything after bridge.mjs, kept whole: the desktop's config path has a space
+    // in it ("Application Support"), so a whitespace split would lose it.
+    const rest = (cmd.match(/bridge\.mjs"?\s*(.*)$/) || [, ""])[1].trim();
+    let configPath = null;
+    const cm = rest.match(/--config\s+"?(.+?)"?\s*$/);
+    if (cm) configPath = cm[1];
+    else if (/\.json"?$/i.test(rest)) configPath = rest.replace(/^"|"$/g, "");
+    out.push({ pid, configPath, unknownCommand: false });
+  }
+  return out;
+}
+
+export function scanBridgeProcesses({ selfPid = process.pid } = {}) {
+  const run = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 5000, windowsHide: true });
+    if (r.error || r.status !== 0) return null;
+    return r.stdout || "";
+  };
+  if (process.platform === "win32") {
+    const cim = run("powershell", ["-NoProfile", "-Command", "Get-CimInstance Win32_Process -Filter \"Name='node.exe'\" | ForEach-Object { \"$($_.ProcessId) $($_.CommandLine)\" }"]);
+    if (cim !== null) return parseBridgeProcesses(cim, { selfPid, format: "ps" });
+    const tl = run("tasklist", ["/FI", "IMAGENAME eq node.exe", "/FO", "CSV", "/NH"]);
+    return tl === null ? null : parseBridgeProcesses(tl, { selfPid, format: "tasklist" });
+  }
+  const ps = run("ps", ["-axo", "pid=,command="]) ?? run("ps", ["-eo", "pid=,args="]);
+  return ps === null ? null : parseBridgeProcesses(ps, { selfPid, format: "ps" });
 }
 
 /**
@@ -615,7 +688,8 @@ function reportNextStep(cfgPath) {
  * confusion.
  */
 function findRunningBridges(cfgPath) {
-  const candidates = [cfgPath];
+  // The config we just wrote, a pre-0.1.11 install's folder, and the desktop app's data dir.
+  const candidates = [cfgPath, path.join(HERE, "config.json")];
   if (process.platform === "darwin") {
     candidates.push(path.join(os.homedir(), "Library", "Application Support", "ai.cookbook.desktop", "config.json"));
   }
@@ -695,8 +769,8 @@ export async function host(argv) {
   }
   writeHosting(cfgPath, true);
   console.log("\n  ✓ This machine can now host a visiting agent, inside a grant you approve.");
-  console.log("    Leave this running and invite one from Cookbook — you'll see every step as it happens.\n");
-  return { ok: true, startBridge: true };
+  console.log("    Leave this running and invite one from Cookbook; you'll see every step as it happens.\n");
+  return { ok: true, startBridge: true, cfgPath };
 }
 
 /** Is that pid still alive? (signal 0 = existence check, no signal delivered) */
@@ -709,5 +783,5 @@ function pidAlive(pid) {
 function writeHosting(cfgPath, enabled) {
   const raw = readConfig(cfgPath) ?? {};
   raw.hosting = { ...(raw.hosting ?? {}), enabled };
-  fs.writeFileSync(cfgPath, JSON.stringify(raw, null, 2) + "\n", { mode: 0o600 });
+  writeConfigFile(cfgPath, JSON.stringify(raw, null, 2) + "\n");
 }

package/hands.mjs

@@ -140,6 +140,8 @@ export const SETUP_FILES = Object.freeze([
   ".gemini/antigravity-cli/settings.json",
   ".openclaw/openclaw.json",
   ".cookbook/config.json",                          // Bridge config (projected: tokens stripped)
+  ".cookbook/bridge.state.json",                    // attempt counters (projected)
+  ".cookbook/local.json",                           // also on NEVER_READ (the loopback token); deny wins
   // The desktop app's own files (macOS). All projected: a Bridge config carries the
   // Bridge token and per-agent tokens, and a visitor only needs its SHAPE.
   "Library/Application Support/ai.cookbook.desktop/config.json",
@@ -188,6 +190,7 @@ const NEVER_READ = Object.freeze([
   /\.(pem|key|p12|pfx|keystore|jks|asc)$/i,
   /(^|\/)id_(rsa|ed25519|ecdsa|dsa)(\.pub)?$/i,
   /(^|\/)local\.json$/i,        // the Bridge Local loopback token
+  /(^|\/)\.cookbook\/local\.json$/i, // the config home's copy, named explicitly like the Library one
   /(^|\/)\.git\/config$/i,      // can carry credentials in a remote URL
   // `credentials.json` AND its dotfile spelling `.credentials.json` — the anchor
   // used to accept only `/` before the word, so a dotfile in a granted project
@@ -274,6 +277,8 @@ export function projectedConfig(text) {
 
 const PROJECTIONS = Object.freeze({
   ".cookbook/config.json": projectedConfig,
+  ".cookbook/bridge.state.json": projectedConfig,
+  ".cookbook/local.json": projectedConfig,
   "Library/Application Support/ai.cookbook.desktop/config.json": projectedConfig,
   "Library/CookbookBridge/config.json": projectedConfig,
   "Library/CookbookBridge/local.json": projectedConfig,
@@ -658,7 +663,7 @@ export const RUN_TEMPLATES = Object.freeze({
     const bin = which("claude");
     if (!bin) return { error: "The claude CLI isn't installed on this machine (not on PATH)." };
     const raw = ctx?.cfg?.cookbookUrl;
-    if (!raw) return { error: "This Bridge has no cookbookUrl in its config, so there is nothing to point Claude at. Run `cookbook-bridge connect` first." };
+    if (!raw) return { error: "This Bridge has no cookbookUrl in its config, so there is nothing to point Claude at. Run `npx cookbook-bridge@latest connect` first." };
     let origin;
     try { origin = new URL(String(raw)).origin; } catch { return { error: `cookbookUrl in this Bridge's config is not a valid URL (${String(raw).slice(0, 80)}).` }; }
     return { argv: [bin, "mcp", "add", "--transport", "http", "--scope", "user", "cookbook", `${origin}/api/mcp`], timeoutMs: 45_000 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cookbook-bridge",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Run your own Claude, Codex and Gemini subscriptions against your Cookbook workspaces. One approval connects every agent CLI on your machine, with a receipt for every run.",
   "type": "module",
   "bin": {
@@ -12,6 +12,8 @@
     "approve-mcp.mjs",
     "bridge.mjs",
     "chat.mjs",
+    "chef-persona.md",
+    "chef.mjs",
     "codex-runner.mjs",
     "config.example.json",
     "connectors.mjs",
@@ -38,7 +40,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test test/local.test.mjs test/review.test.mjs"
+    "test": "node --test test/local.test.mjs test/review.test.mjs test/home.test.mjs"
   },
   "keywords": [
     "cookbook",

package/update.mjs

@@ -17,10 +17,124 @@
  * scripts/test-bridge-update.ts; I/O lives in checkForUpdate/applyUpdate.
  */
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { gunzipSync } from "node:zlib";
 
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+// ── The Bridge's home + how to phrase a command ─────────────────────────────
+// These live HERE (node built-ins only, imported by every command including the
+// broken-install `update` path) so that connecting, running and updating all
+// agree on where the config is and on what command to print. Before 0.1.11 the
+// config sat next to bridge.mjs, which meant an npx cache: every `@latest` moved
+// the Bridge to a new folder and lost its config, and every hint said
+// `node bridge/bridge.mjs` to people who had never unpacked a tarball.
+
+/** `~/.cookbook`: config.json, bridge.state.json, local.json and bridge.log live here. */
+export function configHome(home = os.homedir()) {
+  return path.join(home, ".cookbook");
+}
+
+export function defaultConfigPath(home = os.homedir()) {
+  return path.join(configHome(home), "config.json");
+}
+
+/**
+ * Where the config is, as data (no writes). Order:
+ *   1. `--config <path>`, or (when `positional` is on) the first bare argument
+ *   2. COOKBOOK_CONFIG
+ *   3. ~/.cookbook/config.json when it exists
+ *   4. legacy <here>/config.json when it exists and 3 does not: the answer is still
+ *      the home path, with `migrateFrom` set so locateConfig can copy it over
+ *   5. ~/.cookbook/config.json (the place a first `connect` will write)
+ * Pure so the order is testable: `exists`, `env`, `home` and `here` are injectable.
+ */
+export function resolveConfigPath(args = [], { env = process.env, home = os.homedir(), here = HERE, exists = fs.existsSync, positional = true } = {}) {
+  const list = Array.isArray(args) ? args : [];
+  const i = list.indexOf("--config");
+  if (i >= 0 && list[i + 1]) return { path: path.resolve(list[i + 1]), source: "flag" };
+  if (positional) {
+    const bare = list.find((a) => a && !String(a).startsWith("-"));
+    if (bare) return { path: path.resolve(bare), source: "arg" };
+  }
+  if (env && env.COOKBOOK_CONFIG) return { path: path.resolve(env.COOKBOOK_CONFIG), source: "env" };
+  const homePath = defaultConfigPath(home);
+  if (exists(homePath)) return { path: homePath, source: "home" };
+  const legacy = here ? path.join(here, "config.json") : null;
+  if (legacy && exists(legacy)) return { path: homePath, source: "legacy", migrateFrom: legacy };
+  return { path: homePath, source: "home" };
+}
+
+/** Create the home dir owner-only (0700). Best effort on platforms without modes. */
+export function ensureConfigHome(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(dir, 0o700); } catch { /* win32 */ }
+  return dir;
+}
+
+/** Owner-only write of a config file (0600), creating its dir (0700) first. */
+export function writeConfigFile(p, text) {
+  ensureConfigHome(path.dirname(p));
+  fs.writeFileSync(p, text, { mode: 0o600 });
+  try { fs.chmodSync(p, 0o600); } catch { /* win32 */ }
+}
+
+/**
+ * resolveConfigPath + the one side effect: a legacy <here>/config.json is COPIED to
+ * the home (the old file stays where it was) and one line says where the config now
+ * lives. Returns the path every command should use. Also carries bridge.state.json
+ * over when it sits next to the legacy config, so attempt counters survive the move.
+ */
+export function locateConfig(args = [], opts = {}) {
+  const { log = (m) => console.error(m) } = opts;
+  const r = resolveConfigPath(args, opts);
+  if (r.source === "legacy" && r.migrateFrom) {
+    try {
+      writeConfigFile(r.path, fs.readFileSync(r.migrateFrom));
+      const oldState = path.join(path.dirname(r.migrateFrom), "bridge.state.json");
+      const newState = path.join(path.dirname(r.path), "bridge.state.json");
+      if (fs.existsSync(oldState) && !fs.existsSync(newState)) {
+        try { fs.copyFileSync(oldState, newState); } catch { /* counters are advisory */ }
+      }
+      log(`Config now lives at ${r.path} (copied from ${r.migrateFrom}; the old file was left in place).`);
+    } catch (e) {
+      // Can't create the home: keep working from the legacy file rather than fail.
+      log(`Could not move the config to ${r.path} (${e.message}); still using ${r.migrateFrom}.`);
+      return r.migrateFrom;
+    }
+  }
+  return r.path;
+}
+
+/**
+ * How was this copy installed? Decides how every hint spells a command.
+ *   "npm"     an npx cache (`_npx`) or an npm install (`node_modules/cookbook-bridge`)
+ *   "tarball" bridge.mjs unpacked from the download (or a source checkout)
+ */
+export function installLayout(here = HERE) {
+  const n = String(here).replace(/\\/g, "/") + "/";
+  if (n.includes("/_npx/") || n.includes("/node_modules/cookbook-bridge/")) return "npm";
+  return "tarball";
+}
+
+/** The ONE way to print a Bridge command: `cli("doctor")` reads `npx cookbook-bridge@latest doctor`
+ *  on an npm install and `node bridge/bridge.mjs doctor` from a tarball. Bare `cli()` is the run command. */
+export function cli(cmd = "", { here = HERE } = {}) {
+  const base = installLayout(here) === "npm" ? "npx cookbook-bridge@latest" : "node bridge/bridge.mjs";
+  return cmd ? `${base} ${cmd}` : base;
+}
+
+/** The exact line printed when the local files are behind the deploy. Shared by the
+ *  running Bridge's startup check, `doctor` and `connect`, so they never disagree. */
+export function updateLine(version, { here = HERE, desktop = process.env.COOKBOOK_DESKTOP === "1" } = {}) {
+  if (desktop) return `A newer Bridge ships with the app (deploy ${version}). The Cookbook app manages this copy; update the app to pick it up.`;
+  if (installLayout(here) === "npm") return `A newer Bridge is available (deploy ${version}). Update it with:  ${cli("", { here })}   (@latest fetches the new copy; your config stays in ~/.cookbook)`;
+  return `A newer Bridge is available (deploy ${version}). Update it with:  ${cli("update", { here })}`;
+}
+
 /** Files the updater manages — must mirror the server's BRIDGE_RUNTIME_FILES. The list
  *  itself comes from the MANIFEST at update time (server-driven), so a future deploy can
  *  add files without this constant; this is only the local-hash candidate set. */