@botbuddy/cli 1.63.4 → 1.63.6

package/bin/botbuddy.mjs

@@ -4,11 +4,19 @@ import { ensureRunDelivery } from "../src/run-delivery.mjs";
 
 const argv = process.argv.slice(2);
 
-// BOT-2600: any `bb` invocation starts the single per-machine delivery process
+// BOT-2600: normal `bb` invocations start the single per-machine delivery process
 // when finished `bb run` commands still have an unsent terminal update. A stat
 // and two small reads when nothing changed; it never fails the command.
 const deliveryProcessArgs = argv[0] === "run" && (argv[1] === "--worker" || argv[1] === "--deliver");
-const delivery = deliveryProcessArgs ? Promise.resolve() : ensureRunDelivery().catch(() => {});
+// BOT-2766: help and inspection must remain read-only through the launcher,
+// not just inside their handlers. Child help after -- still belongs to work.
+const separator = argv.indexOf("--");
+const flags = separator === -1 ? argv : argv.slice(0, separator);
+const readOnly = flags.some((flag) => flag === "--help" || flag === "-h")
+  || argv[0] === "help"
+  || (argv[0] === "stack" && argv[1] === "help")
+  || (argv[0] === "run" && (argv[1] === "inspect" || argv[1] === "help"));
+const delivery = deliveryProcessArgs || readOnly ? Promise.resolve() : ensureRunDelivery().catch(() => {});
 
 delivery.then(() => run(argv)).then((code) => {
   if (typeof code === "number") process.exitCode = code;

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.63.4",
-  "source_commit": "23deeb29628f9ec5a8d5eeb2e2f7edc0900cbd94",
-  "source_sha256": "2adad1e7c251dc5ef332993dce65fc0c0d253abbc3324822b25ab1253bd47d3f",
+  "release_version": "1.63.6",
+  "source_commit": "5c72f5b01f85d06bd437e50a6d3515bbf9871230",
+  "source_sha256": "f96b0407034852d7a2c255176a4dcce9297fe6aaec8311f4b25bb70ffbfa5fa8",
   "target": "darwin-arm64",
-  "sha256": "c8ac2b3ffcd575fe8e42ee6a054e6e0797ee97fa862cb49e7baa044cd6a86291"
+  "sha256": "f31b5ae401c2b404d0b321f2ed7864afbeadb45080069daf6fd5a4830b1c0546"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.63.4",
-  "source_commit": "23deeb29628f9ec5a8d5eeb2e2f7edc0900cbd94",
-  "source_sha256": "2adad1e7c251dc5ef332993dce65fc0c0d253abbc3324822b25ab1253bd47d3f",
+  "release_version": "1.63.6",
+  "source_commit": "5c72f5b01f85d06bd437e50a6d3515bbf9871230",
+  "source_sha256": "f96b0407034852d7a2c255176a4dcce9297fe6aaec8311f4b25bb70ffbfa5fa8",
   "target": "linux-x64",
-  "sha256": "4144a3b3f9ec96d57f436b5cd4b4b1d581e2e1807d96a721fe45dab11f7fbdb2"
+  "sha256": "ca5a27989617f81c17b84ef2b160a845b7f65017aada19ec032853d826eaf713"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.63.4",
-  "source_commit": "23deeb29628f9ec5a8d5eeb2e2f7edc0900cbd94",
-  "source_sha256": "2adad1e7c251dc5ef332993dce65fc0c0d253abbc3324822b25ab1253bd47d3f",
+  "release_version": "1.63.6",
+  "source_commit": "5c72f5b01f85d06bd437e50a6d3515bbf9871230",
+  "source_sha256": "f96b0407034852d7a2c255176a4dcce9297fe6aaec8311f4b25bb70ffbfa5fa8",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "c8ac2b3ffcd575fe8e42ee6a054e6e0797ee97fa862cb49e7baa044cd6a86291",
+      "sha256": "f31b5ae401c2b404d0b321f2ed7864afbeadb45080069daf6fd5a4830b1c0546",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "4144a3b3f9ec96d57f436b5cd4b4b1d581e2e1807d96a721fe45dab11f7fbdb2",
+      "sha256": "ca5a27989617f81c17b84ef2b160a845b7f65017aada19ec032853d826eaf713",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.63.4",
+  "version": "1.63.6",
   "description": "BotBuddy \u2014 Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/run.mjs

@@ -280,7 +280,7 @@ function terminalOutcomesAgree(receipt, remote) {
 // Reconcile only evidence the current OS user and owning BotBuddy agent can
 // read.  This is intentionally advisory: an inspector must never terminate a
 // worker, replay a callback, or make a retry safe merely by observing a file.
-export async function inspectRun(runId, {
+async function inspectRunEvidence(runId, {
   call = callToolJson,
   read = readFile,
   now = Date.now(),
@@ -292,6 +292,9 @@ export async function inspectRun(runId, {
     return { schema_version: RUN_SCHEMA_VERSION, classification: "rejected", rerun_safe: false, cancellation_safe: false, error: "run_id_required" };
   }
   const id = runId.trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(id)) {
+    return { schema_version: RUN_SCHEMA_VERSION, classification: "rejected", rerun_safe: false, cancellation_safe: false, error: "run_id_invalid" };
+  }
   const localReceiptPath = receiptFile(id);
   const [receiptRaw, contextRaw] = await Promise.all([
     read(localReceiptPath, "utf8").catch(() => null),
@@ -384,6 +387,35 @@ export async function inspectRun(runId, {
     remote,
   };
 }
+
+/** Add advice only from the inspector's public evidence; never from raw output. */
+export async function inspectRun(runId, options = {}) {
+  const result = await inspectRunEvidence(runId, options);
+  const terminal = result.source_bound === true;
+  const running = result.classification === "running";
+  return {
+    ...result,
+    recovery: {
+      schema_version: 1,
+      ...(terminal ? result.recovery : {}),
+      action: terminal ? "read_local_receipt" : running ? "await_original_result" : "preserve_and_escalate",
+      started: terminal && result.local.status === "success" ? "yes" : "unknown",
+      workload: terminal && ["success", "failure"].includes(result.local.status) ? "exited" : "unknown",
+      retry: "unsafe",
+      receipt_available: terminal,
+      evidence: terminal ? "source_bound_terminal_receipt" : running ? "fresh_local_owner_observation" : "insufficient_or_conflicting_evidence",
+      // An original pending tool handle is not a shell command. Do not invent
+      // a waiter or encourage re-inspection as a polling loop.
+      recovery_argv: null,
+      do_not: ["rerun", "cancel", "poll"],
+      ...(!terminal ? {
+        message: running
+          ? "Keep the original command result pending. A live owner does not prove that its child started or stalled. Consume that owner's terminal receipt; do not rerun or cancel to repair telemetry."
+          : "Preserve the original command and identifiers. Evidence is unknown or conflicts; report the gap without rerunning, cancelling, or polling. No safe recovery command can be derived from this observation.",
+      } : {}),
+    },
+  };
+}
 function cancellationPath(contextFile) { return `${contextFile}.cancelled`; }
 
 async function markCancellation(contextFile, runId) {

package/src/stack.mjs

@@ -105,6 +105,15 @@ export const EXIT = Object.freeze({
   CLEANUP_FAILED: 8, // child completed but signed physical reap was not proven
 });
 
+const STACK_READINESS_HELP = `${bold("READINESS")}
+  An active lease proves infrastructure activation. It does not prove application readiness:
+  the child may still be initializing its schema, runtime configuration, or worktree locks.
+  Consume the application's acknowledged ready receipt before starting another consumer.
+  --callback-port provides callback transport; the application must configure its callback URLs.
+  A retained idle lease is still active; idle_since/cleanup.idle distinguish reuse from live work.
+  Preserve the original stack-run result. Do not rerun or release a live workload to recover output.
+  Use bb run inspect <run_id> for a workload launched by bb run; its run ID differs from a lease ID.`;
+
 export const STACK_HELP = `${bold("botbuddy stack")} — one command for a batch-scoped local stack lease (BOT-1218)
 
 ${bold("USAGE")}
@@ -311,10 +320,33 @@ ${bold("HOST_CAPACITY_SOURCE_STALE")} (BOT-2024)
   sustained (no beacon ever or >= 10 min) → report BLOCKED quoting \`stale_since\`; a Helper
   check/restart is the right ask. A single refusal is never evidence of an outage.
 
+${STACK_READINESS_HELP}
+
 ${bold("EXAMPLE")}
   # request a per-worktree stack for this batch, run a lane against it, then reap it
   botbuddy stack run --repo botbuddy-web --ticket BOT-1346 -- pnpm test:integration`;
 
+const STACK_COMMANDS = new Set(["up", "run", "status", "touch", "done", "cancel"]);
+
+/** Scoped help is assembled from the canonical text, so flags cannot drift. */
+export function stackCommandHelp(command) {
+  const headings = {
+    up: ["up OPTIONS", "GLOBAL", "EXIT CODES", "IDLE LEASES", "HOST_CAPACITY_SOURCE_STALE"],
+    run: ["run OPTIONS", "GLOBAL", "EXIT CODES", "IDLE LEASES", "REMOTE LEASES", "HOST_CAPACITY_SOURCE_STALE"],
+    done: ["done OPTIONS", "GLOBAL", "EXIT CODES", "IDLE LEASES"],
+    cancel: ["GLOBAL", "EXIT CODES"],
+    status: ["GLOBAL", "EXIT CODES"],
+    touch: ["GLOBAL", "EXIT CODES", "IDLE LEASES"],
+  };
+  // The OPTIONS headings intentionally use lower-case command names.
+  const all = STACK_HELP.split(/\n(?=\u001b\[1m)/);
+  const selected = all.filter((section) => headings[command]?.some((heading) => section.startsWith(bold(heading))));
+  const usage = command === "run" ? "[options] -- <executable> [args...]"
+    : command === "up" ? "[options]" : "<lease_id> [options]";
+  const detail = command === "cancel" ? "\n  Cancel gives up a queued lease's place (equivalent to done --reap).\n" : "";
+  return `${bold(`botbuddy stack ${command}`)} ${usage}${detail}\n\n${selected.join("\n")}\n\n${STACK_READINESS_HELP}\n  Use bb stack --help for all commands and options.`;
+}
+
 // ── pure helpers (unit-tested) ───────────────────────────────────────────────
 
 /** Derive the event-stream base URL from the MCP server URL. */
@@ -4658,6 +4690,12 @@ export async function cmdStack(argv, { report = reportStackRunOutcome, outcomeCh
     process.stdout.write(STACK_HELP + "\n");
     return EXIT.OK;
   }
+  const divider = argv.indexOf("--");
+  const flags = divider === -1 ? argv.slice(1) : argv.slice(1, divider);
+  if (STACK_COMMANDS.has(argv[0]) && flags.some((flag) => flag === "--help" || flag === "-h")) {
+    process.stdout.write(stackCommandHelp(argv[0]) + "\n");
+    return EXIT.OK;
+  }
   const { command, leaseId, opts, errors, childArgv } = parseStackArgs(argv);
   if (errors.length) {
     for (const e of errors) process.stderr.write(`${yellow("⚠")} stack: ${e}\n`);

package/src/wait-core.mjs

@@ -501,7 +501,7 @@ function parsePrTarget(p, label) {
 // refuses at arm (invalid_conditions, exit 4). `reviewer=` is pr-review only.
 const PR_CONDITION_KEYS = Object.freeze({
   "pr-state": Object.freeze(["repo", "pr", "number", "sha"]),
-  "pr-review": Object.freeze(["repo", "pr", "number", "sha", "reviewer"]),
+  "pr-review": Object.freeze(["repo", "pr", "number", "sha", "reviewer", "stall_minutes"]),
 });
 
 // A GitHub login compared case-insensitively, with the App suffix `[bot]` stripped
@@ -531,14 +531,24 @@ function parsePrCondition(p, label) {
     if (reviewer === "") throw new Error(`${label} reviewer= must be a GitHub login`);
     out.reviewer = reviewer;
   }
+  if (p.stall_minutes !== undefined) {
+    const minutes = Number(p.stall_minutes);
+    if (!/^\d+$/.test(String(p.stall_minutes)) || !Number.isInteger(minutes) || minutes < 10 || minutes > 1440) {
+      throw new Error("pr-review stall_minutes= must be an integer from 10 to 1440");
+    }
+    if (out.number == null || !out.sha || (out.reviewer && out.reviewer !== "chatgpt-codex-connector")) {
+      throw new Error("pr-review stall_minutes= requires pr= and sha= for the Codex reviewer");
+    }
+    out.stall_minutes = minutes;
+  }
   return out;
 }
 
 // Does a spine subject_key (`owner/repo#number`) satisfy a pr target?
 function prSubjectMatches(subjectKey, params) {
   if (typeof subjectKey !== "string") return false;
-  if (params.number != null) return subjectKey === `${params.repo}#${params.number}`;
-  return subjectKey.startsWith(`${params.repo}#`);
+  if (params.number != null) return subjectKey.toLowerCase() === `${params.repo}#${params.number}`.toLowerCase();
+  return subjectKey.toLowerCase().startsWith(`${params.repo}#`.toLowerCase());
 }
 
 // Does a commit field on a signal payload identify the same commit as the
@@ -560,8 +570,13 @@ function prStateFiltersMatch(signal, params) {
 // BOT-1975 / BOT-1972: optional commit + reviewer scoping for pr-review. A
 // `review_unavailable` signal (the Codex usage-limit decline) names no commit, so
 // it always passes the sha filter — the waiter must learn no review is coming.
-function prReviewFiltersMatch(signal, params) {
+function prReviewFiltersMatch(signal, params, guard) {
   const payload = signal.payload ?? {};
+  if (payload.guard_id && guard && (payload.guard_id !== guard.id || !(Date.parse(payload.started_at) >= Date.parse(guard.started_at)))) return false;
+  // Scoped Codex waits use the durable diagnostic. Legacy cron stall notices
+  // are informational and cannot pre-empt a call-specific intervention policy.
+  if (payload.transition === "review_stalled" && params.sha && params.number &&
+      (!params.reviewer || params.reviewer === "chatgpt-codex-connector") && !payload.guard_id) return false;
   if (params.sha != null && payload.transition !== "review_unavailable" &&
       !shaPrefixMatches(payload.commit_sha, params.sha)) {
     return false;
@@ -1123,7 +1138,7 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
         prStateFiltersMatch(signal, params);
     case "pr-review":
       return signal.signal_type === "pr_review" && prSubjectMatches(signal.subject_key, params) &&
-        prReviewFiltersMatch(signal, params);
+        prReviewFiltersMatch(signal, params, condition.review_guard);
     case "test-run":
       return signal.signal_type === "test_run" && signal.subject_key === `run:${params.runId}`;
     case "stack-run":

package/src/wait.mjs

@@ -105,12 +105,15 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       that head, so a previous head's check result can't wake you.
                                       A push alone emits nothing — the head rides on the next
                                       transition.
-  pr-review:repo=<owner/repo>[,pr=<n>][,reviewer=<login>][,sha=<commit>]
+  pr-review:repo=<owner/repo>[,pr=<n>][,reviewer=<login>][,sha=<commit>][,stall_minutes=<10-1440>]
                                       a submitted review, a new review comment, a thread
                                       resolved/re-opened (payload carries the unresolved-thread
-                                      count), a Codex clean pass (payload.transition=clean_pass)
-                                      or the Codex usage-limit decline (transition=
-                                      review_unavailable — no review is coming).
+                                      count), a Codex clean pass (payload.transition=clean_pass),
+                                      the Codex usage-limit decline (transition=
+                                      review_unavailable — no review is coming) or a Codex
+                                      review needing intervention after one backend diagnostic
+                                      (transition=review_stalled, review_available=false,
+                                      reason + next_action). Initial default: 10 min.
                                       Edge-triggered: it wakes only on review activity AFTER
                                       arm, so arm BEFORE requesting the review. If the PR ALREADY
                                       has an outstanding review at arm, bb-wait prints a one-line
@@ -218,6 +221,12 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       tenant after current server-side approval revalidation.
 
 OPTIONS
+  Review intervention: exact-head Codex waits have a durable one-shot diagnostic.
+  stall_minutes= overrides repository → tenant settings (initial default 10 min).
+  A missing/unbound backend guard is refused as review_guard_unsupported.
+  It needs pr= + sha=. A result wakes immediately; a deadline never means approval.
+  Reconnects/re-arms retain the deadline. This is separate from --timeout below.
+
   --any                 wake on the first matching condition (default; only mode in v1)
   --timeout <seconds>   safety cap (default 86400 = 24 h; hard cap 259200 = 72 h). Timeout is exit 2,
                         not an error. The timeout is a SAFETY CAP measured in hours or days, never a
@@ -528,6 +537,7 @@ async function registerWait(opts, conditions, deadlineIso) {
     const body = await res.json().catch(() => ({}));
     const INVALID_CONDITION_CODES = new Set([
       "no_signal_source",
+      "review_guard_registration_failed",
       "unblocked_cross_tenant",
       "unblocked_requires_tenant",
       "wait_tenant_unresolved",
@@ -662,6 +672,24 @@ async function registerWait(opts, conditions, deadlineIso) {
     throw err;
   }
   const body = await res.json();
+  const guardedReviews = conditions.filter((c) => c.type === "pr-review" && c.params?.sha && (c.params.number || c.params.pr) &&
+    String(c.params.reviewer ?? "chatgpt-codex-connector").toLowerCase().replace(/\[bot\]$/, "") === "chatgpt-codex-connector");
+  for (const condition of guardedReviews) {
+    const params = condition.params;
+    const guard = Array.isArray(body.review_guards) && body.review_guards.find((g) =>
+      typeof g?.repo === "string" && g.repo.toLowerCase() === params.repo.toLowerCase() &&
+      Number(g.pr_number) === Number(params.number ?? params.pr) && typeof g.commit_sha === "string" &&
+      /^[0-9a-f]{7,40}$/i.test(g.commit_sha) &&
+      (g.commit_sha.toLowerCase().startsWith(params.sha) || params.sha.startsWith(g.commit_sha.toLowerCase())));
+    const binding = Array.isArray(body.conditions) ? body.conditions.find((c) => c.id === condition.id)?.review_guard : null;
+    if (!guard || typeof guard.id !== "string" || !guard.id || binding?.id !== guard.id ||
+      !Number.isFinite(Date.parse(binding.started_at)) || !Number.isFinite(Date.parse(guard.started_at)) ||
+      !Number.isFinite(Date.parse(guard.deadline)) || !Number.isInteger(guard.minutes) || guard.minutes < 10 || guard.minutes > 1440 ||
+      !["call", "repository", "tenant"].includes(guard.source)) {
+      const err = new Error("relay did not bind the required review intervention policy; upgrade the backend before using this client");
+      err.invalidCondition = true; err.errorCode = "review_guard_unsupported"; throw err;
+    }
+  }
   // BOT-1572/1608: a session-token wait has no profile to attest; the relay
   // returns the derived session_id + agent_id. Their absence means the relay did
   // not honour the token as a session credential — fail closed.
@@ -694,6 +722,7 @@ async function registerWait(opts, conditions, deadlineIso) {
     // BOT-1539: arm-time snapshot of already-outstanding code review for any
     // pr-review/pr-state target. Report-only — surfaced on stderr so a silent
     // edge-triggered park isn't mistaken for "no review yet".
+    reviewGuards: Array.isArray(body.review_guards) ? body.review_guards : [],
     prReviewSnapshot: Array.isArray(body.pr_review_snapshot) ? body.pr_review_snapshot : null,
     // BOT-2400: how often this session already armed this exact condition set (24 h), and
     // the relay's warning once that reaches 3.
@@ -2101,6 +2130,9 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       for (const line of formatPrReviewSnapshotWarnings(reg.prReviewSnapshot)) {
         process.stderr.write(`bb-wait: ${line}\n`);
       }
+      for (const guard of reg.reviewGuards ?? []) {
+        process.stderr.write(`bb-wait: review intervention ${guard.minutes} min (${guard.source}), deadline ${guard.deadline}${guard.diagnosed ? "; already diagnosed for this request" : ""}\n`);
+      }
       // BOT-2400: re-arming the same wait again and again burns tokens on every wake.
       if (reg.rearmWarning) process.stderr.write(`bb-wait: ${reg.rearmWarning}\n`);
       // BOT-1837: one line naming the branch's latest run at arm time. Report-only
@@ -2130,7 +2162,9 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         // and refusing a recycled key). No `tenant` is stamped for `linear` — its cross-tenant
         // isolation rides on the central guard's sessionTenant (BOT-1259), not a per-type param.
         const linearScope = new Map();
+        const reviewScope = new Map();
         for (const rc of reg.conditions) {
+          if (rc?.type === "pr-review" && rc.review_guard) reviewScope.set(rc.id, rc.review_guard);
           if (rc && rc.type === "lock" && rc.params && typeof rc.params.host === "string") {
             canonHost.set(rc.id, rc.params.host);
           }
@@ -2142,6 +2176,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
           }
         }
         for (const c of conditions) {
+          if (c.type === "pr-review" && reviewScope.has(c.id)) c.review_guard = reviewScope.get(c.id);
           if (c.type === "lock" && canonHost.has(c.id)) c.params.host = canonHost.get(c.id);
           if (c.type === "unblocked" && unblockedScope.has(c.id)) {
             const s = unblockedScope.get(c.id);