@botbuddy/cli 1.63.3 → 1.63.5

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.3",
-  "source_commit": "92be9d217698f09b798c814238d50fbecc8dcf98",
-  "source_sha256": "a212c13e8834633e89a5f2739d203915b33178d7d4b4ae0d91ed2304baa50970",
+  "release_version": "1.63.5",
+  "source_commit": "fc9bbe22c3fe8840724c30eae63515cfd70cce9d",
+  "source_sha256": "bed3488d03f054f8c30c49d28bb3d5783d081363f2d9c69063164c79cc70feee",
   "target": "darwin-arm64",
-  "sha256": "3168f56ae654ed633c079266990e8c14a19282a7c48e79947422f84369ea97c7"
+  "sha256": "e6e438fc3e98628a4e5f04a0100c96ba694f75d78210fbebe3623af7b0f085d7"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.63.3",
-  "source_commit": "92be9d217698f09b798c814238d50fbecc8dcf98",
-  "source_sha256": "a212c13e8834633e89a5f2739d203915b33178d7d4b4ae0d91ed2304baa50970",
+  "release_version": "1.63.5",
+  "source_commit": "fc9bbe22c3fe8840724c30eae63515cfd70cce9d",
+  "source_sha256": "bed3488d03f054f8c30c49d28bb3d5783d081363f2d9c69063164c79cc70feee",
   "target": "linux-x64",
-  "sha256": "8c66260a27729a63dcbfcf41996882977a3bf84628aab829e1accf176e675ef6"
+  "sha256": "b224066b8aa6ae1831282fbfd7e60135864dea69847a7187df81bd171674456a"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.63.3",
-  "source_commit": "92be9d217698f09b798c814238d50fbecc8dcf98",
-  "source_sha256": "a212c13e8834633e89a5f2739d203915b33178d7d4b4ae0d91ed2304baa50970",
+  "release_version": "1.63.5",
+  "source_commit": "fc9bbe22c3fe8840724c30eae63515cfd70cce9d",
+  "source_sha256": "bed3488d03f054f8c30c49d28bb3d5783d081363f2d9c69063164c79cc70feee",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "3168f56ae654ed633c079266990e8c14a19282a7c48e79947422f84369ea97c7",
+      "sha256": "e6e438fc3e98628a4e5f04a0100c96ba694f75d78210fbebe3623af7b0f085d7",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "8c66260a27729a63dcbfcf41996882977a3bf84628aab829e1accf176e675ef6",
+      "sha256": "b224066b8aa6ae1831282fbfd7e60135864dea69847a7187df81bd171674456a",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.63.3",
+  "version": "1.63.5",
   "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,8 +292,12 @@ 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(receiptFile(id), "utf8").catch(() => null),
+    read(localReceiptPath, "utf8").catch(() => null),
     read(contextFile(id), "utf8").catch(() => null),
   ]);
   const receipt = typeof receiptRaw === "string" ? parseOwnedRunFile(receiptRaw, id) : null;
@@ -339,7 +343,21 @@ export async function inspectRun(runId, {
       rerun_safe: false,
       cancellation_safe: false,
       source_bound: sourceBound,
-      local: { status: receipt.status, exit_code: receipt.exit_code ?? null },
+      local: {
+        status: receipt.status,
+        exit_code: receipt.exit_code ?? null,
+        ...(sourceBound ? {
+          receipt_path: localReceiptPath,
+          source_sha: receipt.source_sha,
+          command_hash: receipt.command_hash,
+        } : {}),
+      },
+      ...(sourceBound ? {
+        recovery: {
+          action: "read_local_receipt",
+          message: "Read local.receipt_path for the original workload evidence and bounded_log. Preserve its source identity and exit code; do not rerun or cancel to repair missing telemetry. Preserve and investigate any conflicting remote result.",
+        },
+      } : {}),
       remote,
     };
   }
@@ -369,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`);