cookbook-bridge 0.1.0 → 0.1.2

package/README.md

@@ -75,6 +75,7 @@ you exactly which parts are ready and how to fix the rest.
 | `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. |
 
 ## Self-updating
 
@@ -147,6 +148,47 @@ volunteered goals, verifies completion, and reports usage. If an agent runs but
 finish, the Bridge retries up to `maxAttempts`, then leaves the task open — with the
 likely cause in the log (login missing, MCP not connected, tool blocked).
 
+## Letting someone else's agent help (grants)
+
+Setting up agents is the one thing you can't ask your agents to do, because they're
+what's broken. So a **hardware grant** lets someone else's agent do it:
+
+```bash
+npx cookbook-bridge host       # open the door (Node + one browser approval; no agents needed)
+```
+
+Then invite one from Cookbook. What that actually means:
+
+- **Their brain stays on their machine.** The visiting agent keeps running on its
+  owner's computer and subscription. Only its *hands* travel, and **your** Bridge is
+  what executes them.
+- **There is no shell.** It can only invoke named verbs from a fixed table — read a
+  setup file, list a folder, run the doctor, run one of a few fixed commands. It
+  cannot compose a command line.
+- **Credential files are never readable.** `.credentials.json`, `auth.json`,
+  `oauth_creds.json`, `~/.ssh`, anything `.env`, any `.pem`. That list wins over
+  every grant, including one where you shared your whole home folder.
+- **Secrets are stripped before anything leaves.** Tokens, keys and your real paths
+  are redacted here, on your machine, and again on the server.
+- **This machine decides.** Every rule is re-checked locally against the grant. An
+  action that needs your approval runs only after you approved it — a server that
+  said otherwise would be refused right here.
+- **You watch, and it's on the record.** Every call shows up before it runs and
+  settles into a permanent receipt. `--off`, or End in the browser, closes the door
+  immediately.
+
+Two kinds of grant, and you pick when you invite:
+
+- **Look only** — the visitor can diagnose and cannot change one byte.
+- **Look and fix** — it can also repair things, and *every change waits for your
+  click*. It proposes (`write_file`, `clear_needs_auth_cache`, `bridge_connect_agents`,
+  a Bridge restart, installing `cookbook-bridge`), you approve or refuse. Files are
+  backed up before they change, and a config that wouldn't parse is refused rather
+  than written.
+
+The Bridge caps write/install/login at "ask" in its own local ceiling, so no grant
+and no server can promote one to automatic. The click is a property of your machine.
+
 ## Honest limits
 
 - **Local only** — tasks run while your machine and the Bridge are up.

package/bridge.mjs

@@ -26,6 +26,7 @@
  * Node built-ins only. No dependencies.
  */
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
@@ -45,11 +46,14 @@ let hasCodexThread, reapCodexServer, killCodexServer;
 let checkForUpdate, applyUpdate;
 let createLocalServer, toolsForMode, modeForTools, vendorOf;
 let connectAgentsProgrammatic, detectClis;
+let serveCalls, describeCall;
+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 } = await import("./cookbook.mjs"));
+  ({ listWorkspaces, listTasks, listOpenWork, getTask, threadResumeContext, completeTaskApi, resolveDelegation, reportTaskUsage, reportTaskProgress, volunteerClaim, dispatchClaim, abandonTask, recallMemories, recallAcrossWorkspaces, creditRecall, getVolunteerSettings, fetchHands, claimHandsCall, reportHandsResult } = await import("./cookbook.mjs"));
+  ({ serveCalls, describeCall } = await import("./hands.mjs"));
   ({ agentEnv, checkGeminiVersion, isGeminiCommand, GEMINI_MIN_VERSION, checkAgyVersion, isAgyCommand, AGY_MIN_VERSION } = await import("./harden.mjs"));
   ({ extractUsage, displayText } = await import("./usage.mjs"));
   ({ volunteeringEnabled, volunteerCandidates, decisionPrompt, parseDecision, MAX_DECISIONS_PER_POLL, mergeVolunteerSettings, effectiveCapabilities } = await import("./volunteer.mjs"));
@@ -63,7 +67,16 @@ const HERE = path.dirname(fileURLToPath(import.meta.url));
 
 function log(msg) {
   const ts = new Date().toISOString().slice(11, 19);
-  console.log(`[${ts}] ${msg}`);
+  // NEVER let logging kill the Bridge. If stdout is gone (a re-exec that inherited a
+  // dying socket, a closed pipe, a parent that exited) console.log THROWS, and a throw
+  // in here propagates out of the poll loop's own catch handler — which killed the loop
+  // while leaving the process alive and Bridge Local still answering "connected".
+  // Diagnosed live 2026-08-24: a wedged Bridge with no fd 1 or 2, 14 minutes silent.
+  try {
+    console.log(`[${ts}] ${msg}`);
+  } catch {
+    /* stdout is unusable; a Bridge with no voice must still do its job */
+  }
 }
 
 /**
@@ -147,6 +160,11 @@ function loadConfig() {
   // terminal, because they asked. Teammate-assigned tasks NEVER get local access;
   // they stay jailed to workspace tools. This is the terminal-parity wall.
   cfg.localWorkspaces = cfg.localWorkspaces ?? {};
+  // HOSTING (hardware grants, 0069): may a teammate's agent, invited by YOU in the
+  // browser, run granted verbs on this machine? Off unless explicitly enabled —
+  // `cookbook-bridge host` sets it. A Bridge that never hosts never even asks the
+  // server for calls, so this costs nothing when unused.
+  cfg.hosting = cfg.hosting ?? { enabled: false };
   cfg.maxAttempts = cfg.maxAttempts ?? 2;
   // Phase 1 semantics: taskTimeoutSeconds is the ABSOLUTE CEILING (cost backstop),
   // livenessTimeoutSeconds is the stall detector (no output for this long = dead).
@@ -441,6 +459,16 @@ async function runAgent(cfg, agent, prompt, onProgress, retry = null, taskCtx =
     const threadKey = taskCtx.task ? taskCtx.task.thread_root_id ?? taskCtx.task.id : undefined;
     return runCodexTask(agent, prompt, cfg.taskTimeoutSeconds, agent.token || cfg.codexToken, env, onProgress, { threadKey, log });
   }
+  if (agent.runner === "openclaw") {
+    // The visiting-agent lane: one Gateway-backed turn, resumed by session id so a
+    // thread stays a conversation. Its own token (agent.token) is what reaches
+    // Cookbook — for Chef that is the scoped VISITOR credential, never the owner's.
+    const { runOpenclawTask } = await import("./openclaw-runner.mjs");
+    return runOpenclawTask(agent, prompt, cfg.taskTimeoutSeconds, env, onProgress, {
+      sessionId: retry?.sessionId ?? taskCtx.sessionRef ?? null,
+      log,
+    });
+  }
   if (agent.runner === "robot") {
     // Embodied runner (sim-first): structured task env, not a prompt — the robot's
     // "brain" is a skill program. Same verify-via-getTask contract as every runner.
@@ -563,6 +591,11 @@ let lastRunError = null;
 /** Whether the Cookbook token has ever verified this run (gates /status.connected and
  *  keeps a token-rejected desktop Bridge alive instead of exiting). */
 let tokenOk = false;
+/** When this Bridge last actually REACHED Cookbook. `tokenOk` only records that the
+ *  token verified once, at startup — so a Bridge whose poll loop has died still
+ *  reported "connected" forever (diagnosed live 2026-08-24: 14 minutes mute, process
+ *  alive, Bridge Local cheerfully green). Liveness has to be a timestamp, not a flag. */
+let lastContactAt = 0;
 /** The desktop app sets COOKBOOK_DESKTOP=1 when it spawns the Bridge. Only then do we
  *  stay alive on a revoked token (so the user can fix it from the app's Connect UI). A
  *  headless/terminal Bridge still exits loudly with the fix — never a silent zombie. */
@@ -595,6 +628,7 @@ function applyConfigFromDisk(cfg) {
   if (raw.cookbookUrl) cfg.cookbookUrl = String(raw.cookbookUrl).replace(/\/$/, "");
   cfg.default = raw.default;
   cfg.localWorkspaces = raw.localWorkspaces ?? {};
+  cfg.hosting = raw.hosting ?? { enabled: false };
   const agents = (raw.agents ?? []).filter((a) => a.enabled !== false);
   cfg.agents.splice(0, cfg.agents.length, ...agents);
   // A reload usually follows connect-agents fixing the token — let the next poll
@@ -606,7 +640,29 @@ function applyConfigFromDisk(cfg) {
 /** Re-exec this Bridge on the same argv (the self-update restart path). */
 function reexecSelf() {
   log("↻ restarting…");
-  const child = spawn(process.execPath, process.argv.slice(1), { detached: true, stdio: "inherit" });
+  // NEVER inherit stdio here. This is called from Bridge Local's POST /restart — i.e.
+  // from inside an HTTP request handler — so "inherit" hands the child the dying
+  // response socket as its stdout. Once that socket closes the child has no fd 1 or 2,
+  // every log() throws, and the poll loop dies while the process stays alive and
+  // Bridge Local keeps reporting "connected". That is the desktop app's Restart button
+  // silently wedging the Bridge, and it is exactly the failure that looks like health.
+  // Diagnosed live 2026-08-24 on a Bridge that had been mute for 14 minutes.
+  //
+  // Append to the log file instead, so a restarted Bridge keeps a voice.
+  let out = "ignore";
+  let err = "ignore";
+  try {
+    const logPath = path.join(path.dirname(CONFIG_PATH || HERE), "bridge.log");
+    const fd = fs.openSync(logPath, "a");
+    out = fd;
+    err = fd;
+  } catch {
+    /* no writable log — silence beats a wedged child */
+  }
+  const child = spawn(process.execPath, process.argv.slice(1), {
+    detached: true,
+    stdio: ["ignore", out, err],
+  });
   child.unref();
   process.exit(0);
 }
@@ -1092,6 +1148,110 @@ async function quickScan(cfg) {
   return true;
 }
 
+// ── HOSTING: a visiting agent's hands on THIS machine (hardware grants, 0069) ─
+//
+// Someone the host invited — in a grant the host approved, with a scope the host
+// set — queues calls; this Bridge executes them locally and posts back what
+// happened. Every rule is re-checked here (bridge/hands.mjs authorizeCall), because
+// the machine that runs a thing is the only honest place to decide whether it may.
+// Serialized: one visiting agent, one pair of hands, one thing at a time — which is
+// also what keeps the live log readable to the human watching it.
+let handsBusy = false;
+const hands = { supported: true, activeGrants: [] };
+// Module-scoped ON PURPOSE. It used to be `let stopped` inside main(), and the
+// hands path above referenced it from here — a ReferenceError on EVERY hands poll,
+// so a host Bridge with hosting on accepted grants and executed nothing. Found in
+// the first real rehearsal (2026-08-25); every hermetic test simulated the host
+// loop with library code and never ran this file.
+let stopped = false;
+
+/** Run lifecycle → Bridge Local subscribers (the desktop tray + notifications). */
+function emitHands(state, call, result) {
+  if (!localServer) return;
+  try {
+    localServer.emit("hands", {
+      state,
+      callId: call?.id ?? null,
+      grantId: call?.grant_id ?? null,
+      workspaceId: call?.workspace_id ?? null,
+      visitor: call?.visitor ?? null,
+      verb: call?.verb ?? null,
+      summary: describeCall ? describeCall(call) : (call?.verb ?? null),
+      risk: call?.risk ?? null,
+      ...(result ? { error: result.error ?? null } : {}),
+      at: new Date().toISOString(),
+    });
+  } catch { /* notifications are best-effort */ }
+}
+
+/**
+ * Something a visiting agent proposed is waiting on the HOST. It is not runnable
+ * here — the whole point is that it waits — but this machine is the right place to
+ * TELL them, so the desktop app can raise a notification instead of the host having
+ * to be watching the browser tab. Announced once per call.
+ */
+const announcedAwaiting = new Set();
+function noteAwaiting(awaiting) {
+  for (const call of awaiting ?? []) {
+    if (announcedAwaiting.has(call.id)) continue;
+    announcedAwaiting.add(call.id);
+    const what = describeCall ? describeCall(call) : call.verb;
+    log(`⏳ ${call.visitor ?? "A visiting agent"} wants to ${what} — approve or refuse it in Cookbook.`);
+    emitHands("needs-approval", call);
+  }
+  if (announcedAwaiting.size > 500) announcedAwaiting.clear();
+}
+
+async function serveHands(cfg, calls) {
+  if (!cfg.hosting?.enabled || 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,
+    });
+  } catch (e) {
+    log(`! hands error: ${e.message}`);
+  } 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) {
+  if (!cfg.hosting?.enabled || !hands.supported || handsBusy) return;
+  try {
+    const r = await fetchHands(cfg);
+    if (!r.supported) {
+      hands.supported = false;
+      log("· this Cookbook has no hardware-grant channel — hosting is unavailable");
+      return;
+    }
+    hands.activeGrants = r.grants ?? [];
+    noteAwaiting(r.awaiting ?? []);
+    await serveHands(cfg, r.calls);
+  } catch (e) {
+    if (!/40[13]/.test(e.message)) log(`! couldn't check for granted work: ${e.message}`);
+  }
+}
+
 // ── THE PUSH CHANNEL (SSE) ────────────────────────────────────────────────────
 // One outbound connection; the server pushes open work + warm hints the moment
 // they change (~sub-second dispatch). Connections are short-lived by design
@@ -1149,6 +1309,16 @@ async function socketLoop(cfg) {
               void dispatchWork(cfg, j.work ?? [], j.warm_hints ?? []);
             } catch { /* malformed frame — next snapshot covers */ }
           }
+          // A visiting agent queued a call on a grant this machine hosts. Push is
+          // what makes "watch an agent work on your laptop" feel live.
+          if (ev.event === "hands" && ev.data) {
+            try {
+              const j = JSON.parse(ev.data);
+              hands.activeGrants = j.grants ?? hands.activeGrants;
+              noteAwaiting(j.awaiting ?? []);
+              void serveHands(cfg, j.calls ?? []);
+            } catch { /* malformed frame — the poll covers it */ }
+          }
         }
       }
     } catch { /* transient — reconnect below */ }
@@ -1436,12 +1606,20 @@ async function main() {
     if (cfg.default && dflt.name !== cfg.default) {
       log(`! config "default" is "${cfg.default}" but no enabled agent has that name — "any"-assigned tasks route to ${dflt.name}.`);
     }
-    if (!resolveBin(Array.isArray(dflt.command) ? dflt.command[0] : null)) {
+    // Same binary derivation as the doctor: an openclaw agent has no `command` on
+    // purpose (the runner builds its argv), so check the binary it will actually use
+    // instead of warning "isn't installed" about a perfectly healthy agent.
+    const dfltBin = Array.isArray(dflt.command) && dflt.command.length
+      ? dflt.command[0]
+      : dflt.runner === "openclaw"
+        ? (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\`.`);
     }
   }
 
-  let stopped = false;
+  stopped = false; // module-scoped; see the hands section
   process.on("SIGINT", () => {
     stopped = true;
     log("Stopping…");
@@ -1512,8 +1690,19 @@ async function main() {
       applyConfig: () => applyConfigFromDisk(cfg),
       restart: () => reexecSelf(),
       hotWorkspaceIds: () => hotWorkspaceIds(),
-      connected: () => tokenOk && consecutive401s === 0,
-      lastError: () => lastRunError,
+      activeGrants: () => hands.activeGrants,
+      // HONEST LIVENESS: a Bridge that has not reached Cookbook in two minutes is not
+      // connected, whatever a startup flag says. The poll loop runs at most every
+      // pollSeconds (default 15) and the push channel reconnects each minute, so two
+      // minutes of silence means something is wrong — and saying so is the whole
+      // point of a status endpoint.
+      connected: () => tokenOk && consecutive401s === 0 && Date.now() - lastContactAt < 120_000,
+      lastError: () => {
+        if (tokenOk && Date.now() - lastContactAt > 120_000) {
+          return `no contact with Cookbook for ${Math.round((Date.now() - lastContactAt) / 1000)}s — the Bridge may be stuck; restart it`;
+        }
+        return lastRunError;
+      },
     });
     await localServer.start();
     for (const sig of ["SIGINT", "SIGTERM"]) process.on(sig, () => { try { localServer.stop(); } catch { /* exiting */ } });
@@ -1530,7 +1719,12 @@ async function main() {
   try {
     const ws = await listWorkspaces(cfg);
     tokenOk = true;
+    lastContactAt = Date.now();
     log(`Connected — watching ${ws.length} workspace(s).`);
+    if (cfg.hosting?.enabled) {
+      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.");
+      await pollHands(cfg);
+    }
     if (cfg.persistentThreads) {
       for (const sig of ["SIGINT", "SIGTERM"]) process.on(sig, () => { killAllRunners(); killCodexServer(); process.exit(0); });
       process.on("exit", () => { killAllRunners(); killCodexServer(); });
@@ -1577,8 +1771,12 @@ async function main() {
           await pollOnce(cfg);
         }
       }
+      // HOSTING: granted calls ride the same cadence as work. When the push channel
+      // is healthy it has already delivered them; this is the net.
+      if (cfg.hosting?.enabled && !pushHealthy) await pollHands(cfg);
       // A clean poll means the token is good — clear any prior rejection so the app's
       // /status flips back to connected once the user fixes it.
+      lastContactAt = Date.now();
       if (consecutive401s || !tokenOk) { consecutive401s = 0; tokenOk = true; lastRunError = null; }
     } catch (e) {
       log(`! poll error: ${e.message}`);
@@ -1646,6 +1844,35 @@ async function runDoctor(args) {
   process.exit(fails === 0 ? 0 : 1);
 }
 
+/**
+ * What the doctor can say about a visiting (openclaw) agent WITHOUT starting a turn
+ * on its owner's subscription: is the profile configured, and does the agent id the
+ * Bridge will pass actually exist. Both are local and free.
+ */
+async function doctorOpenclaw(agent, { ok, warn, bad }) {
+  const { inspectOpenclawProfile, listOpenclawAgents } = await import("./openclaw-runner.mjs");
+  for (const f of inspectOpenclawProfile(agent)) {
+    if (f.level === "bad") bad(f.message, f.fix);
+    else if (f.level === "warn") warn(f.message, f.fix);
+    else ok(f.message);
+  }
+  const wanted = agent.openclawAgent || null;
+  const listed = await listOpenclawAgents(agent);
+  if (!listed.ok) {
+    warn(`${agent.name}: couldn't list OpenClaw agents`, listed.error || "is `openclaw` on PATH?");
+    return;
+  }
+  if (!wanted) {
+    warn(`${agent.name}: no openclawAgent set — the run has no --agent and openclaw will refuse to pick one`,
+      `set "openclawAgent" to one of: ${listed.ids.join(", ") || "(none listed)"}`);
+  } else if (!listed.ids.includes(String(wanted))) {
+    bad(`${agent.name}: openclawAgent "${wanted}" doesn't exist in profile "${agent.profile || "default"}"`,
+      `known agents: ${listed.ids.join(", ") || "(none)"}`);
+  } else {
+    ok(`${agent.name}: agent "${wanted}" exists in profile "${agent.profile || "default"}" (no turn spent)`);
+  }
+}
+
 /** The doctor's checks as data: { cfgPath, rows: [{ level, label, fix }], fails, warns }.
  *  Shared by the CLI (`doctor`, `doctor --json`) and Bridge Local's POST /doctor. */
 async function doctorReport(args) {
@@ -1705,7 +1932,15 @@ async function doctorReport(args) {
 
     // 5. Per agent: binary, allowedTools sanity, and a real login probe
     for (const agent of cfg.agents) {
-      const cmd = Array.isArray(agent.command) ? agent.command[0] : null;
+      // An openclaw agent has no `command`: its argv is assembled by the runner from
+      // profile + openclawAgent, precisely so a hand-written command can't drop
+      // --agent. Derive its binary the same way the runner does, or the doctor
+      // reports `binary \`null\` not found` for a perfectly good config.
+      const cmd = Array.isArray(agent.command) && agent.command.length
+        ? agent.command[0]
+        : agent.runner === "openclaw"
+          ? (agent.bin || "openclaw")
+          : null;
       const bin = resolveBin(cmd);
       if (!bin) {
         bad(`${agent.name}: binary \`${cmd}\` not found on PATH`,
@@ -1769,6 +2004,16 @@ async function doctorReport(args) {
       }
 
       if (agent.runner === "app-server") { warn(`${agent.name}: app-server runner — start it to verify login/MCP (probe skipped)`); continue; }
+      // A visiting agent (openclaw) is driven through the Gateway with its own
+      // token, so we will not spend a turn on someone's subscription to probe it.
+      // But "probe skipped" used to mean NOTHING was checked, and a Chef whose
+      // profile had no gateway credentials, no model and no such agent id sat here
+      // reported as fine until the first real question hit it (2026-08-24). Every
+      // check below is local and free, and each one is a failure seen for real.
+      if (agent.runner === "openclaw") {
+        await doctorOpenclaw(agent, { ok, warn, bad });
+        continue;
+      }
       if (agent.runner === "robot") {
         const r = await spawnAgent(agent, "", 15, agentEnv(cfg).env);
         if (r.code === 0 && String(r.out).trim().endsWith("ok")) ok(`${agent.name}: robot agent responds (probe ok)`);
@@ -1863,6 +2108,17 @@ if (!IS_MAIN) {
       console.error(e.message);
       process.exit(1);
     });
+} else if (sub === "chat") {
+  // Talk to your workspace's agents without leaving the terminal. chat.mjs is a
+  // standalone script that reads its config from argv[2], so reshape argv to make
+  // `cookbook-bridge chat [config.json]` behave like `node chat.mjs [config.json]`.
+  // Without this subcommand the file shipped in every install but was unreachable
+  // by any obvious command.
+  process.argv = [process.argv[0], path.join(HERE, "chat.mjs"), ...process.argv.slice(3)];
+  import("./chat.mjs").catch((e) => {
+    console.error(e.message);
+    process.exit(1);
+  });
 } else if (sub === "connect" || sub === "connect-agents") {
   // `connect` is the documented first command (the connect page and the npm bin both
   // say it); `connect-agents` is the original name, kept working forever.
@@ -1872,6 +2128,21 @@ if (!IS_MAIN) {
       console.error(e.message);
       process.exit(1);
     });
+} else if (sub === "host") {
+  // Open the door for a visiting agent (hardware grants). Ends with a RUNNING
+  // Bridge, because a door nobody is standing behind isn't open.
+  import("./device.mjs")
+    .then(async (m) => {
+      const r = await m.host(process.argv.slice(3));
+      if (r && r.startBridge) {
+        process.argv = [process.argv[0], process.argv[1]];
+        await main();
+      }
+    })
+    .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/config.example.json

@@ -4,18 +4,18 @@
   "pollSeconds": 15,
   "maxAttempts": 2,
   "taskTimeoutSeconds": 3600,
-  "_timeouts": "taskTimeoutSeconds is the ABSOLUTE ceiling per run (cost backstop). livenessTimeoutSeconds kills a STALLED run \u2014 no output for this many seconds (streaming runs only). Healthy long work runs to the ceiling; silence dies fast.",
+  "_timeouts": "taskTimeoutSeconds is the ABSOLUTE ceiling per run (cost backstop). livenessTimeoutSeconds kills a STALLED run — no output for this many seconds (streaming runs only). Healthy long work runs to the ceiling; silence dies fast.",
   "livenessTimeoutSeconds": 300,
   "_concurrency": "How many task runs may be in flight at once. Runs launch in parallel up to this cap; the atomic pre-claim keeps every task single-runner.",
   "maxConcurrentRuns": 2,
   "_billing": "Agents run on the CLI subscriptions you already pay for. The Bridge hides ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY from agent processes so a task can never silently bill your API account instead. Set allowApiKeyBilling to true ONLY if you explicitly want API-key billing.",
   "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 \u2014 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": "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": 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 \u2014 consent never guesses).",
+  "_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).",
   "acceptFrom": "anyone",
   "agents": [
     {
@@ -34,8 +34,8 @@
         "--print-timeout",
         "3600s"
       ],
-      "_setup": "Gemini runs via the Antigravity CLI (agy) \u2014 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 \u2014 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 \u2014 the board shows wall-clock duration for its runs (no token count)."
+      "_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.",
+      "_usage": "agy emits no token/usage JSON — the board shows wall-clock duration for its runs (no token count)."
     },
     {
       "name": "Claude",
@@ -54,8 +54,8 @@
         "--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 \u2014 `node bridge.mjs doctor` checks it.",
-      "_output": "json output lets the Bridge report what each task cost (tokens/$) back to the board \u2014 text works too, you just lose the usage report"
+      "_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.",
+      "_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"
     },
     {
       "name": "Codex",
@@ -68,9 +68,24 @@
       "command": [
         "/Applications/ChatGPT.app/Contents/Resources/codex"
       ],
-      "_binary": "Codex merged into the ChatGPT desktop app (July 2026) \u2014 older installs had /Applications/Codex.app/Contents/Resources/codex. If doctor says 'binary not found', check both paths.",
+      "_binary": "Codex merged into the ChatGPT desktop app (July 2026) — older installs had /Applications/Codex.app/Contents/Resources/codex. If doctor says 'binary not found', check both paths.",
       "sandbox": "workspace-write",
-      "_setup": "Codex (ChatGPT) via codex app-server \u2014 its headless `exec` can't call MCP tools (OpenAI #16685), so the Bridge drives the app-server protocol and auto-approves tool elicitations (bridge/codex-runner.mjs). To enable: (1) make a clean CODEX_HOME at ~/.codex-bridge with config.toml [mcp_servers.cookbook] (url=<cookbookUrl>/api/mcp, bearer_token_env_var=COOKBOOK_CODEX_TOKEN) and a copy of ~/.codex/auth.json so it uses your ChatGPT login; (2) add a Cookbook token here as \"token\" (separate from the Bridge token, so Codex's work is attributed to Codex); (3) optionally set \"codexHome\" if not ~/.codex-bridge; (4) set enabled:true."
+      "_setup": "Codex (ChatGPT) via codex app-server — its headless `exec` can't call MCP tools (OpenAI #16685), so the Bridge drives the app-server protocol and auto-approves tool elicitations (bridge/codex-runner.mjs). To enable: (1) make a clean CODEX_HOME at ~/.codex-bridge with config.toml [mcp_servers.cookbook] (url=<cookbookUrl>/api/mcp, bearer_token_env_var=COOKBOOK_CODEX_TOKEN) and a copy of ~/.codex/auth.json so it uses your ChatGPT login; (2) add a Cookbook token here as \"token\" (separate from the Bridge token, so Codex's work is attributed to Codex); (3) optionally set \"codexHome\" if not ~/.codex-bridge; (4) set enabled:true."
+    },
+    {
+      "name": "Chef",
+      "match": [
+        "chef",
+        "openclaw"
+      ],
+      "enabled": false,
+      "runner": "openclaw",
+      "_setup": "A VISITING agent: it works on other people's machines through hardware grants. Its Cookbook credential does NOT go here — OpenClaw's MCP servers are global to a config file, so a token in this entry would look like isolation without being it. Instead give Chef its own PROFILE: `openclaw --profile chef mcp add cookbook --url <site>/api/mcp --transport streamable-http --header \"Authorization=Bearer <VISITOR token>\"`. That profile has its own config and state under ~/.openclaw-chef, so this Chef carries the scoped visitor credential while your own OpenClaw keeps your personal one. Mint the visitor token with `npm run setup:chef`; the tokens page can't make one.",
+      "_profile_needs": "The profile must also have gateway.auth (its own token AND its own gateway.port) and agents.defaults.model.primary — without them every run dies with GatewayCredentialsRequiredError. `bridge doctor` checks all of this for free.",
+      "_no_command": "Deliberately no \"command\": the runner builds the argv from profile + openclawAgent. A hand-written command that omits --agent loses the session selector and openclaw exits with 'No target session selected' — which is exactly how this shipped broken once.",
+      "_usage": "OpenClaw's --json envelope carries usage + sessionId, so runs get a real receipt and threads resume.",
+      "profile": "chef",
+      "openclawAgent": "main"
     }
   ],
   "persistentThreads": true,
@@ -79,5 +94,9 @@
       "cwd": "/absolute/path/to/project",
       "allowedTools": null
     }
+  },
+  "_hosting": "HARDWARE GRANTS: may an agent someone else runs act on THIS machine? Off by default. `cookbook-bridge host` turns it on; the desktop app has a switch. Even ON, nothing happens until YOU approve a grant in the browser: you set the scope, you watch every call in the log, and `cookbook-bridge host --off` (or End in the UI) closes the door immediately.",
+  "hosting": {
+    "enabled": false
   }
-}
+}

package/cookbook.mjs

@@ -232,3 +232,40 @@ export async function recallAcrossWorkspaces(cfg, query, excludeWorkspaceId, lim
     return [];
   }
 }
+
+// ── HARDWARE GRANTS (0069) — the host side ───────────────────────────────────
+// These are plain REST, not MCP tools: they are the HOST's channel, and the host
+// is not an agent here — it is a machine executing calls its owner invited in. A
+// server that predates grants 404s, which every caller treats as "not hosting".
+
+/** Pending calls (and the live grants they belong to) for THIS Bridge's token. */
+export async function fetchHands(cfg) {
+  const res = await fetch(`${cfg.cookbookUrl}/api/bridge/hands`, {
+    headers: { Authorization: `Bearer ${cfg.token}` },
+  });
+  if (res.status === 404) return { supported: false, calls: [], grants: [] };
+  if (!res.ok) throw new Error(`hands ${res.status}`);
+  const j = await res.json().catch(() => ({}));
+  return { supported: true, calls: j.calls ?? [], grants: j.grants ?? [] };
+}
+
+/** Claim one call before running it. The server CASes on status, so two Bridges on
+ *  the same token (or a re-delivered push frame) can never double-execute. */
+export async function claimHandsCall(cfg, callId) {
+  const res = await fetch(`${cfg.cookbookUrl}/api/bridge/hands`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${cfg.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ call_id: callId }),
+  });
+  return res.ok;
+}
+
+/** Post the (already-redacted) outcome. The server redacts again before storing. */
+export async function reportHandsResult(cfg, callId, result) {
+  const res = await fetch(`${cfg.cookbookUrl}/api/bridge/hands/${encodeURIComponent(callId)}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${cfg.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ status: result.status, output: result.output, error: result.error }),
+  });
+  return res.ok;
+}