cookbook-bridge 0.1.12 → 0.1.13

package/README.md

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

package/bridge.mjs

@@ -68,14 +68,14 @@ let hasCodexThread, reapCodexServer, killCodexServer;
 let checkForUpdate, applyUpdate;
 let createLocalServer, toolsForMode, modeForTools, vendorOf;
 let connectAgentsProgrammatic, detectClis;
-let serveCalls, describeCall, hostingMode, whichExec, argvForSpawn, redactText, resolveCmdShim, killTree;
+let serveCalls, describeCall, hostingMode, whichExec, argvForSpawn, redactText, resolveCmdShim, killTree, runPreflight, grantsNeedingPreflight;
 let fetchHands, claimHandsCall, reportHandsResult;
 
 async function loadRuntime() {
   ({ createLocalServer, toolsForMode, modeForTools, vendorOf } = await import("./local.mjs"));
   ({ connectAgentsProgrammatic, detectClis } = await import("./device.mjs"));
   ({ listWorkspaces, listTasks, listOpenWork, getTask, threadResumeContext, completeTaskApi, resolveDelegation, reportTaskUsage, reportTaskProgress, volunteerClaim, dispatchClaim, abandonTask, recallMemories, recallAcrossWorkspaces, creditRecall, getVolunteerSettings, fetchHands, claimHandsCall, reportHandsResult, agentsQuery } = await import("./cookbook.mjs"));
-  ({ serveCalls, describeCall, hostingMode, which: whichExec, argvForSpawn, redact: redactText, resolveCmdShim, killTree } = await import("./hands.mjs"));
+  ({ serveCalls, describeCall, hostingMode, which: whichExec, argvForSpawn, redact: redactText, resolveCmdShim, killTree, runPreflight, grantsNeedingPreflight } = await import("./hands.mjs"));
   ({ agentEnv, checkGeminiVersion, isGeminiCommand, GEMINI_MIN_VERSION, checkAgyVersion, isAgyCommand, AGY_MIN_VERSION, withCookbookMcp, isClaudeCommand, withApprovalRelay, materializeMcpConfig,
     isKimiCommand, kimiFromLine, kimiResultEnvelope, kimiCommand, kimiLoginState, kimiMcpState, checkKimiVersion } = await import("./harden.mjs"));
   ({ extractUsage, displayText } = await import("./usage.mjs"));
@@ -815,6 +815,7 @@ function loadRunState() {
     for (const [id, n] of Object.entries(raw.attempts ?? {})) attempts.set(id, Number(n) || 0);
     for (const id of raw.givenUp ?? []) givenUp.add(id);
     for (const [id, ctx] of Object.entries(raw.retryCtx ?? {})) retryCtx.set(id, ctx);
+    for (const id of raw.preflighted ?? []) if (typeof id === "string") preflighted.add(id);
   } catch { /* first run / unreadable — start clean */ }
 }
 function saveRunState() {
@@ -823,11 +824,15 @@ function saveRunState() {
     const attEntries = [...attempts.entries()].slice(-500);
     const given = [...givenUp].slice(-500);
     const retries = [...retryCtx.entries()].slice(-200);
-    fs.writeFileSync(statePath(), JSON.stringify({ attempts: Object.fromEntries(attEntries), givenUp: given, retryCtx: Object.fromEntries(retries) }));
+    const flown = [...preflighted].slice(-500);
+    fs.writeFileSync(statePath(), JSON.stringify({ attempts: Object.fromEntries(attEntries), givenUp: given, retryCtx: Object.fromEntries(retries), preflighted: flown }));
   } catch { /* best-effort — never let state persistence break a run */ }
 }
 
 const attempts = new Map(); // taskId -> count
+// Grants this host has already pre-flighted (hands section). Persisted: a restart
+// must not post a second pre-flight for a grant the visitor already read.
+const preflighted = new Set();
 // Retry context (Phase 1): what the LAST failed attempt knew — the claude session
 // to resume and the failure to feed back — so a retry continues instead of redoing.
 const retryCtx = new Map(); // taskId -> { sessionId, reason }
@@ -1607,30 +1612,36 @@ function noteAwaiting(awaiting) {
   if (announcedAwaiting.size > 500) announcedAwaiting.clear();
 }
 
+/** The host context every hands path shares: serveCalls (visitor calls, plans) and
+ *  runPreflight (the host's own first call on a new grant). */
+function handsContext(cfg) {
+  return {
+    cfg,
+    cfgPath: CONFIG_PATH,
+    home: os.homedir(),
+    // The host's OWN folder list. A granted folder is honoured only if it is here
+    // (or inside one), so the server can never hand a visitor a directory.
+    hostFolders: cfg.hosting?.folders ?? [],
+    doctor: () => doctorReport(["--config", CONFIG_PATH]),
+    claim: (id) => claimHandsCall(cfg, id),
+    report: (id, r) => reportHandsResult(cfg, id, r),
+    // Repair templates reach the same machinery the desktop app's buttons use, so
+    // a fix an agent performs is exactly the fix the host could have clicked.
+    restart: () => reexecSelf(),
+    startConnect: () => connectAgentsProgrammatic({ cfgPath: CONFIG_PATH, baseUrl: cfg.cookbookUrl }),
+    applyConfig: () => applyConfigFromDisk(cfg),
+    log,
+    stopped: () => stopped,
+    visitorLabel: (c) => c.visitor ?? "a visiting agent",
+    onCall: emitHands,
+  };
+}
+
 async function serveHands(cfg, calls) {
   if (hostingMode(cfg) === "off" || handsBusy || !calls || calls.length === 0) return;
   handsBusy = true;
   try {
-    await serveCalls(calls, {
-      cfg,
-      cfgPath: CONFIG_PATH,
-      home: os.homedir(),
-      // The host's OWN folder list. A granted folder is honoured only if it is here
-      // (or inside one), so the server can never hand a visitor a directory.
-      hostFolders: cfg.hosting?.folders ?? [],
-      doctor: () => doctorReport(["--config", CONFIG_PATH]),
-      claim: (id) => claimHandsCall(cfg, id),
-      report: (id, r) => reportHandsResult(cfg, id, r),
-      // Repair templates reach the same machinery the desktop app's buttons use, so
-      // a fix an agent performs is exactly the fix the host could have clicked.
-      restart: () => reexecSelf(),
-      startConnect: () => connectAgentsProgrammatic({ cfgPath: CONFIG_PATH, baseUrl: cfg.cookbookUrl }),
-      applyConfig: () => applyConfigFromDisk(cfg),
-      log,
-      stopped: () => stopped,
-      visitorLabel: (c) => c.visitor ?? "a visiting agent",
-      onCall: emitHands,
-    });
+    await serveCalls(calls, handsContext(cfg));
   } catch (e) {
     log(`! hands error: ${e.message}`);
   } finally {
@@ -1638,6 +1649,51 @@ async function serveHands(cfg, calls) {
   }
 }
 
+/** Open a HOST-initiated call row on a grant (the pre-flight). Same bearer, same
+ *  route the claim uses; the server answers { call_id }. */
+async function createHostCall(cfg, grantId, verb) {
+  const res = await fetch(`${cfg.cookbookUrl}/api/bridge/hands`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${cfg.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ grant_id: grantId, verb, host_initiated: true }),
+  });
+  if (!res.ok) throw new Error(`hands ${res.status}`);
+  const j = await res.json().catch(() => ({}));
+  return typeof j.call_id === "string" ? j.call_id : typeof j.call?.id === "string" ? j.call.id : null;
+}
+
+// ── PRE-FLIGHT: the first thing a new grant gets is what the machine already knows.
+// When a grant this Bridge hosts becomes active, the host runs env + doctor +
+// cli_versions + its own config's shape (tokens stripped) once, locally, read-only,
+// and posts it as a host-initiated `preflight` call. The visitor reads it from
+// grant_get before asking anything the machine already answered. Persisted per
+// grant (bridge.state.json); at most two tries per grant per process.
+const preflightTries = new Map(); // grantId -> attempts this process
+async function preflightNewGrants(cfg) {
+  if (hostingMode(cfg) === "off" || handsBusy || !runPreflight) return;
+  const fresh = grantsNeedingPreflight(hands.activeGrants, { preflighted, tried: preflightTries });
+  if (fresh.length === 0) return;
+  handsBusy = true; // never alongside a visitor's call
+  try {
+    for (const grantId of fresh) {
+      if (stopped) break;
+      const n = (preflightTries.get(grantId) ?? 0) + 1;
+      preflightTries.set(grantId, n);
+      log(`◇ pre-flight for grant ${grantId.slice(0, 8)}: env, doctor, CLI versions, config shape`);
+      try {
+        const { callId } = await runPreflight(grantId, { ...handsContext(cfg), create: (gid) => createHostCall(cfg, gid, "preflight") });
+        preflighted.add(grantId);
+        saveRunState();
+        log(`  ↳ pre-flight posted (call ${String(callId).slice(0, 8)})`);
+      } catch (e) {
+        log(`! pre-flight for grant ${grantId.slice(0, 8)} failed: ${e.message}${n >= 2 ? " (not retrying until the Bridge restarts)" : " (will retry once)"}`);
+      }
+    }
+  } finally {
+    handsBusy = false;
+  }
+}
+
 /** Poll for granted calls (the net under the push channel, and the whole story on a
  *  server or network without SSE). No-ops entirely when not hosting. */
 async function pollHands(cfg) {
@@ -1651,6 +1707,7 @@ async function pollHands(cfg) {
     }
     hands.activeGrants = r.grants ?? [];
     noteAwaiting(r.awaiting ?? []);
+    await preflightNewGrants(cfg);
     await serveHands(cfg, r.calls);
   } catch (e) {
     if (!/40[13]/.test(e.message)) log(`! couldn't check for granted work: ${e.message}`);
@@ -1688,7 +1745,7 @@ async function pullOnce(cfg, { boot = false } = {}) {
   if (j.hands && typeof j.hands === "object") {
     hands.activeGrants = j.hands.grants ?? hands.activeGrants;
     noteAwaiting(j.hands.awaiting ?? []);
-    if (hostingMode(cfg) !== "off") void serveHands(cfg, j.hands.calls ?? []);
+    if (hostingMode(cfg) !== "off") void preflightNewGrants(cfg).then(() => serveHands(cfg, j.hands.calls ?? []));
   }
   // 0092: synthesis (summary, caption, vision, answer) thinks HERE, on this
   // member's subscription. Each job carries kind, model and image straight
@@ -1815,7 +1872,7 @@ async function socketLoop(cfg) {
               const j = JSON.parse(ev.data);
               hands.activeGrants = j.grants ?? hands.activeGrants;
               noteAwaiting(j.awaiting ?? []);
-              void serveHands(cfg, j.calls ?? []);
+              void preflightNewGrants(cfg).then(() => serveHands(cfg, j.calls ?? []));
             } catch { /* malformed frame — the poll covers it */ }
           }
         }

package/chef-persona.md

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

package/hands.mjs

@@ -31,6 +31,7 @@ import os from "node:os";
 import { kimiLoginState } from "./harden.mjs";
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // REDACTION
@@ -314,6 +315,17 @@ const PROJECTIONS = Object.freeze({
 const MAX_FILE_BYTES = 256 * 1024;
 const MAX_OUTPUT_CHARS = 40_000;
 const MAX_DIR_ENTRIES = 400;
+/** The most a single call result may weigh when it leaves this machine. The server
+ *  applies the same cap (src/lib/workspaces/grants.ts MAX_OUTPUT_BYTES); doing it
+ *  here too means a plan of twenty steps or a pre-flight cannot outgrow a receipt. */
+export const MAX_UPLOAD_BYTES = 64 * 1024;
+/** Trim an output to MAX_UPLOAD_BYTES the same way the server does. Pure. */
+export function capOutput(output) {
+  if (output === null || output === undefined) return output;
+  const json = JSON.stringify(output);
+  if (typeof json !== "string" || json.length <= MAX_UPLOAD_BYTES) return output;
+  return { truncated: true, bytes: json.length, preview: json.slice(0, MAX_UPLOAD_BYTES) };
+}
 
 // ─────────────────────────────────────────────────────────────────────────────
 // THE LOCAL CEILING — what this machine will EVER do, regardless of what it is told
@@ -329,7 +341,10 @@ const MAX_DIR_ENTRIES = 400;
  * hand a visitor a directory — only the host's OWN config can (cfg.hosting.folders).
  */
 export const LOCAL_CEILING = Object.freeze({
-  verbs: Object.freeze(["doctor", "env", "read_file", "list_dir", "run", "write_file", "restore_backup", "open_url"]),
+  // `plan` is a container, not a capability: its steps are each checked on their own
+  // (executePlan), so listing it here widens nothing. `preflight` is deliberately
+  // absent: the host runs it on its own initiative and never accepts it as a call.
+  verbs: Object.freeze(["doctor", "env", "read_file", "list_dir", "run", "write_file", "restore_backup", "open_url", "plan"]),
   run_allow: Object.freeze([
     // read
     "node_version", "claude_mcp_list", "cli_versions", "tail_log",
@@ -401,6 +416,11 @@ export const VERB_RISK = Object.freeze({
   write_file: "write",
   restore_backup: "write",
   open_url: "login",
+  // A plan always waits for the host's single click, whatever its steps: "write"
+  // is the label that makes the generic wall say so. Pre-flight is read-only by
+  // construction (env, doctor, CLI versions, the config's shape).
+  plan: "write",
+  preflight: "read",
 });
 
 export const RUN_TEMPLATE_RISK = Object.freeze({
@@ -954,9 +974,27 @@ const VERBS = {
       stderr: String(res.stderr).slice(0, 4000),
     };
   },
+
+  /**
+   * PRE-FLIGHT: everything a visiting agent would otherwise spend its first four
+   * calls asking. Read-only by construction. The host runs it on its own initiative
+   * the moment a grant becomes active (runPreflight) and posts it as a
+   * host-initiated call; a queued `preflight` from the server is refused by the wall.
+   */
+  async preflight(_args, ctx) {
+    return collectPreflight(ctx);
+  },
+
+  /** A plan is executed by executePlan, never as a bare verb: executeCall routes
+   *  it there before this is reached. Kept in the table so the wall knows the name. */
+  async plan() {
+    return { error: "A plan runs through executePlan, one step at a time." };
+  },
 };
 
 export const VERB_NAMES = Object.freeze(Object.keys(VERBS));
+/** Verbs that contain or replace other calls. Never allowed inside a plan. */
+export const META_VERBS = Object.freeze(["plan", "preflight"]);
 
 // ─────────────────────────────────────────────────────────────────────────────
 // EXECUTION
@@ -967,11 +1005,21 @@ export const VERB_NAMES = Object.freeze(Object.keys(VERBS));
  * whole authorization decision is unit-testable without a machine to break.
  * Returns { ok: true, risk } or { ok: false, error }.
  */
-export function authorizeCall(call, scope) {
+export function authorizeCall(call, scope, opts = {}) {
   if (!call || typeof call.verb !== "string") return { ok: false, error: "Malformed call." };
   if (!scope || typeof scope !== "object") return { ok: false, error: "No grant scope." };
   const verb = call.verb;
   if (!VERBS[verb]) return { ok: false, error: `This Bridge has no verb '${verb}'.` };
+  // The host runs its own pre-flight; it is never something a visitor queues.
+  if (verb === "preflight") return { ok: false, error: "Pre-flight runs on the host's own initiative, never as a queued call." };
+  // A PLAN is a container. Its permission is exactly the permission of its steps,
+  // each of which is checked on its own inside executePlan, so the plan row itself
+  // needs only the one thing a container can carry: the host's click.
+  if (verb === "plan") {
+    if (opts.approvedByPlan) return { ok: false, error: "A plan can't contain another plan." };
+    if (call.status !== "approved") return { ok: false, error: "A plan needs the host's approval before it can run here." };
+    return { ok: true, risk: VERB_RISK.plan };
+  }
   if (!Array.isArray(scope.verbs) || !scope.verbs.includes(verb)) {
     return { ok: false, error: `The grant doesn't allow '${verb}'.` };
   }
@@ -991,8 +1039,10 @@ export function authorizeCall(call, scope) {
   }
   // THE CONSENT WALL: when the grant says a class needs a human, this machine runs
   // it only if the host has already flipped the row to `approved`. A UI bug, or a
-  // server that sends it as `queued`, is refused here.
-  if (policy === "ask" && call.status !== "approved") {
+  // server that sends it as `queued`, is refused here. Inside a plan the host's one
+  // click on the plan row is the click for every step (`approvedByPlan`), and
+  // executePlan sets that flag only when the plan row itself said `approved`.
+  if (policy === "ask" && call.status !== "approved" && opts.approvedByPlan !== true) {
     return { ok: false, error: `That needs the host's approval before it can run here.` };
   }
   return { ok: true, risk };
@@ -1003,12 +1053,13 @@ export function authorizeCall(call, scope) {
  * ALWAYS resolves — a thrown verb becomes a failed call, never a crashed Bridge.
  */
 export async function executeCall(call, ctx) {
+  if (call?.verb === "plan") return executePlan(call, ctx);
   const home = ctx.home ?? os.homedir();
   // NEVER the server's scope as sent — always its intersection with what this
   // machine will do at all. This is the line that makes "a lying server cannot make
   // your laptop run something you didn't grant" a true statement instead of a hope.
   const scope = effectiveScope(call.scope ?? ctx.scope, { hostFolders: ctx.hostFolders ?? [], home });
-  const auth = authorizeCall(call, scope);
+  const auth = authorizeCall(call, scope, { approvedByPlan: ctx.approvedByPlan === true });
   if (!auth.ok) return { status: "denied", output: null, error: auth.error };
 
   const args = call.args && typeof call.args === "object" ? call.args : {};
@@ -1020,12 +1071,204 @@ export async function executeCall(call, ctx) {
       // the visitor should see it as such and try something else.
       return { status: "failed", output: null, error: clean.error };
     }
-    return { status: "done", output: clean, error: null };
+    return { status: "done", output: capOutput(clean), error: null };
   } catch (e) {
     return { status: "failed", output: null, error: redact(String(e?.message ?? e), { home }).slice(0, 500) };
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// PLANS — one click, several steps, the same wall for each
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The most steps one click may cover. A fix needs three or four; twenty is a script. */
+export const PLAN_MAX_STEPS = 20;
+
+/** The hash the server stamps on a plan row: sha256 of the steps EXACTLY as sent.
+ *  Recomputed here before a plan runs, so nothing can be appended after the click. Pure. */
+export function planHash(steps) {
+  return createHash("sha256").update(JSON.stringify(steps)).digest("hex");
+}
+
+/**
+ * Is this plan the plan the host clicked? Structure, size, no nested containers, and
+ * the hash. Returns { ok: true, steps, why } or { ok: false, error }. Pure.
+ */
+export function validatePlan(call) {
+  const args = call?.args && typeof call.args === "object" ? call.args : {};
+  const steps = args.steps;
+  if (!Array.isArray(steps) || steps.length === 0) return { ok: false, error: "A plan needs at least one step." };
+  if (steps.length > PLAN_MAX_STEPS) return { ok: false, error: `A plan may have at most ${PLAN_MAX_STEPS} steps; this one has ${steps.length}.` };
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    if (!step || typeof step !== "object" || typeof step.verb !== "string") return { ok: false, error: `Step ${i + 1} is malformed (needs a verb).` };
+    if (META_VERBS.includes(step.verb)) return { ok: false, error: `Step ${i + 1} is '${step.verb}', which can't be inside a plan.` };
+    if (step.args !== undefined && (step.args === null || typeof step.args !== "object" || Array.isArray(step.args))) {
+      return { ok: false, error: `Step ${i + 1} has malformed args.` };
+    }
+  }
+  // THE HASH: the server cannot append a step after the host clicked, because the
+  // click was on this exact list. A missing hash is a mismatch too.
+  if (typeof call.plan_hash !== "string" || planHash(steps) !== call.plan_hash) return { ok: false, error: "plan hash mismatch" };
+  return { ok: true, steps, why: typeof args.why === "string" ? args.why : "" };
+}
+
+/** The word for a step in the log: the template for a run, the verb otherwise. */
+function stepLabel(step) {
+  if (step?.verb === "run") return String(step.args?.template ?? "run");
+  return String(step?.verb ?? "?");
+}
+
+/**
+ * Run an approved plan step by step, through the SAME authorizeCall + executeCall
+ * path a single call takes. The one difference is `approvedByPlan`: the host's click
+ * on the plan row is the click for every write-class step inside it, and it is set
+ * only when the plan row itself is `approved`. Every step is still measured against
+ * effectiveScope and LOCAL_CEILING on its own, so a step the ceiling forbids fails
+ * the plan at that index. Stops at the first failure. ALWAYS resolves.
+ * `ctx.executeStep` (tests) replaces executeCall for the steps.
+ */
+export async function executePlan(call, ctx) {
+  const home = ctx.home ?? os.homedir();
+  const scope = effectiveScope(call.scope ?? ctx.scope, { hostFolders: ctx.hostFolders ?? [], home });
+  const auth = authorizeCall(call, scope, { approvedByPlan: ctx.approvedByPlan === true });
+  if (!auth.ok) return { status: "denied", output: null, error: auth.error };
+  const v = validatePlan(call);
+  if (!v.ok) return { status: "denied", output: null, error: v.error };
+
+  const runStep = typeof ctx.executeStep === "function" ? ctx.executeStep : executeCall;
+  const total = v.steps.length;
+  const steps = [];
+  let stoppedAt;
+  for (let i = 0; i < total; i++) {
+    if (ctx.stopped?.()) { stoppedAt = i; steps.push({ verb: v.steps[i].verb, ok: false, error: "The Bridge is stopping.", duration_ms: 0 }); break; }
+    const step = v.steps[i];
+    // A step never inherits the row's status: the plan's click reaches it ONLY as
+    // approvedByPlan, which is what the wall is written to look at.
+    const stepCall = {
+      id: `${call.id ?? "plan"}#${i + 1}`,
+      grant_id: call.grant_id,
+      workspace_id: call.workspace_id,
+      visitor: call.visitor,
+      verb: step.verb,
+      args: step.args && typeof step.args === "object" ? step.args : {},
+      status: "queued",
+      scope: call.scope ?? ctx.scope,
+    };
+    const t0 = Date.now();
+    let r;
+    try {
+      r = await runStep(stepCall, { ...ctx, approvedByPlan: call.status === "approved" });
+    } catch (e) {
+      r = { status: "failed", output: null, error: String(e?.message ?? e).slice(0, 500) };
+    }
+    const duration_ms = Date.now() - t0;
+    const ok = r?.status === "done";
+    const row = { verb: step.verb, ...(step.verb === "run" ? { template: stepLabel(step) } : {}), ok, duration_ms };
+    if (ok) row.output = r.output ?? null;
+    else row.error = String(r?.error ?? `step ${r?.status ?? "failed"}`);
+    steps.push(row);
+    ctx.log?.(`◇ plan step ${i + 1}/${total}: ${stepLabel(step)} ... ${ok ? "ok" : `failed: ${row.error}`} (${(duration_ms / 1000).toFixed(1)}s)`);
+    if (!ok) { stoppedAt = i; break; }
+  }
+  const output = capOutput(redactDeep({ steps, ...(stoppedAt !== undefined ? { stopped_at: stoppedAt } : {}) }, { home }));
+  if (stoppedAt !== undefined) {
+    const failed = steps[stoppedAt];
+    return { status: "failed", output, error: redact(`Stopped at step ${stoppedAt + 1} of ${total} (${stepLabel(v.steps[stoppedAt])}): ${failed?.error ?? "failed"}`, { home }).slice(0, 500) };
+  }
+  return { status: "done", output, error: null };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PRE-FLIGHT — what the host tells a visitor before it asks
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The four read-only pieces of a pre-flight. Each is a function of the host ctx so a
+ * test can swap one (cli_versions spawns every vendor CLI, which is slow and machine
+ * dependent). Every piece fails on its own: a doctor that throws still leaves env.
+ */
+export const PREFLIGHT_PARTS = Object.freeze({
+  env: (ctx) => VERBS.env({}, ctx),
+  doctor: async (ctx) => {
+    if (typeof ctx.doctor !== "function") return { error: "This Bridge can't run its doctor." };
+    const report = await ctx.doctor();
+    const rows = Array.isArray(report?.rows) ? report.rows : [];
+    return {
+      rows: rows.map((r) => ({ label: String(r?.label ?? ""), ok: r?.level === "ok", detail: typeof r?.fix === "string" ? r.fix : null })),
+      fails: Number(report?.fails ?? rows.filter((r) => r?.level === "bad").length),
+      warns: Number(report?.warns ?? rows.filter((r) => r?.level === "warn").length),
+    };
+  },
+  cli_versions: async (ctx) => {
+    const spec = RUN_TEMPLATES.cli_versions({}, ctx);
+    return spec.local ? spec.local() : { error: spec.error ?? "cli_versions is unavailable" };
+  },
+  bridge_config: (ctx) => {
+    if (!ctx.cfgPath) return { error: "This Bridge has no config path." };
+    let text;
+    try { text = fs.readFileSync(ctx.cfgPath, "utf8"); } catch (e) { return { error: `can't read the config: ${e.code || e.message}` }; }
+    return projectedConfig(text);
+  },
+});
+
+/**
+ * Gather the pre-flight: env, doctor rows, CLI versions and this Bridge's own config
+ * with every token stripped, then redacted and capped exactly like any other result.
+ * Read-only. ALWAYS resolves.
+ */
+export async function collectPreflight(ctx, parts = PREFLIGHT_PARTS) {
+  const home = ctx.home ?? os.homedir();
+  const out = {};
+  for (const key of ["env", "doctor", "cli_versions", "bridge_config"]) {
+    try {
+      out[key] = await parts[key]({ ...ctx, home });
+    } catch (e) {
+      out[key] = { error: String(e?.message ?? e).slice(0, 300) };
+    }
+  }
+  out.at = new Date().toISOString();
+  return capOutput(redactDeep(out, { home }));
+}
+
+/**
+ * Which active grants still owe a pre-flight from this host. A grant counts once it
+ * is `active`, has verbs (a conversation-only grant has no machine), and is neither
+ * already pre-flighted (persisted) nor out of attempts for this process. Pure.
+ */
+export function grantsNeedingPreflight(grants, { preflighted, tried, maxAttempts = 2 } = {}) {
+  const done = preflighted ?? new Set();
+  const attempts = tried ?? new Map();
+  const out = [];
+  for (const g of Array.isArray(grants) ? grants : []) {
+    const id = g?.id;
+    if (typeof id !== "string" || !id) continue;
+    if (g.status && g.status !== "active") continue;
+    if (g.conversation_only === true) continue;
+    if (Array.isArray(g.scope?.verbs) && g.scope.verbs.length === 0) continue;
+    if (done.has(id)) continue;
+    if ((attempts.get(id) ?? 0) >= maxAttempts) continue;
+    out.push(id);
+  }
+  return out;
+}
+
+/**
+ * Run the pre-flight for one grant and post it as a host-initiated call:
+ * `ctx.create(grantId)` asks the server for a call row (POST /api/bridge/hands with
+ * { grant_id, verb: "preflight", host_initiated: true }) and returns its id;
+ * `ctx.report(callId, result)` posts the output through the same route every other
+ * call uses. Throws when the server refuses, so the caller can count the attempt.
+ */
+export async function runPreflight(grantId, ctx) {
+  const output = await collectPreflight(ctx, ctx.preflightParts ?? PREFLIGHT_PARTS);
+  const callId = await ctx.create(grantId);
+  if (typeof callId !== "string" || !callId) throw new Error("the server didn't open a pre-flight call");
+  const posted = await ctx.report(callId, { status: "done", output, error: null });
+  if (posted === false) throw new Error("the server refused the pre-flight result");
+  return { callId, output };
+}
+
 /**
  * The host loop: claim each pending call (CAS server-side), run it, post the result.
  * Serialized per grant — one visiting agent, one pair of hands, one thing at a time,
@@ -1057,6 +1300,12 @@ export function describeCall(call) {
     case "run": return `run ${a.template}`;
     case "doctor": return "run the setup doctor";
     case "env": return "look at what's installed";
+    case "preflight": return "pre-flight: what's installed, the doctor, CLI versions, the config's shape";
+    case "plan": {
+      const steps = Array.isArray(a.steps) ? a.steps : [];
+      const why = typeof a.why === "string" && a.why.trim() ? a.why.trim().slice(0, 120) : "a plan";
+      return `plan: ${why} (${steps.length} step${steps.length === 1 ? "" : "s"}: ${steps.map(stepLabel).join(", ").slice(0, 200)})`;
+    }
     // The three verbs a host must approve are the three that used to render as a
     // bare verb name (ultrareview #123, bug_007). Say WHAT, not just which.
     case "write_file": return `write ${a.path}${typeof a.content === "string" ? ` (${a.content.length} chars)` : ""}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cookbook-bridge",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "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": {
@@ -40,7 +40,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test test/local.test.mjs test/review.test.mjs test/home.test.mjs test/kimi.test.mjs"
+    "test": "node --test test/local.test.mjs test/review.test.mjs test/home.test.mjs test/kimi.test.mjs test/hands.test.mjs"
   },
   "keywords": [
     "cookbook",