@botbuddy/cli 1.60.0 → 1.60.1

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.60.0",
-  "source_commit": "2bde2741ba9158ce03147a2ff28f1c6a44f89e25",
-  "source_sha256": "7091f785b4820eccd5f9596e04def9ef58a02cbb5130ccb84bd55ae77e71ec67",
+  "release_version": "1.60.1",
+  "source_commit": "ac9d46a93d57bb9d5af94cba238532767c1f19cc",
+  "source_sha256": "667acf404a591bd0e09357645192040cba7a0b2085f33d89be6a4bbc84a6dd53",
   "target": "darwin-arm64",
-  "sha256": "b6fe4ed183d92a32e398cb9de3f82ac6b4634188409f51eadad457ca6b37c307"
+  "sha256": "9dd4af84ad4131cf69c94bbed69f3c51087ca8ac4d742df6e9367faadbeddb97"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.60.0",
-  "source_commit": "2bde2741ba9158ce03147a2ff28f1c6a44f89e25",
-  "source_sha256": "7091f785b4820eccd5f9596e04def9ef58a02cbb5130ccb84bd55ae77e71ec67",
+  "release_version": "1.60.1",
+  "source_commit": "ac9d46a93d57bb9d5af94cba238532767c1f19cc",
+  "source_sha256": "667acf404a591bd0e09357645192040cba7a0b2085f33d89be6a4bbc84a6dd53",
   "target": "linux-x64",
-  "sha256": "3a1839c5800e38bf9bb7a1465555e0cace01ef82d9c382fde1e036608c536fe8"
+  "sha256": "61db8eb2108fcf9407460e96f487316728e262927241b5ee672ffca3443a11d3"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.60.0",
-  "source_commit": "2bde2741ba9158ce03147a2ff28f1c6a44f89e25",
-  "source_sha256": "7091f785b4820eccd5f9596e04def9ef58a02cbb5130ccb84bd55ae77e71ec67",
+  "release_version": "1.60.1",
+  "source_commit": "ac9d46a93d57bb9d5af94cba238532767c1f19cc",
+  "source_sha256": "667acf404a591bd0e09357645192040cba7a0b2085f33d89be6a4bbc84a6dd53",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "b6fe4ed183d92a32e398cb9de3f82ac6b4634188409f51eadad457ca6b37c307",
+      "sha256": "9dd4af84ad4131cf69c94bbed69f3c51087ca8ac4d742df6e9367faadbeddb97",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "3a1839c5800e38bf9bb7a1465555e0cace01ef82d9c382fde1e036608c536fe8",
+      "sha256": "61db8eb2108fcf9407460e96f487316728e262927241b5ee672ffca3443a11d3",
       "mode": "0755"
     }
   }

package/package.json

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

package/src/commands.mjs

@@ -483,12 +483,24 @@ does not prove that the workload is still running.
 
 ${bold("Safe recovery")}
   1. Preserve the command-run ID and the original result.
-  2. Prefer the owning runner's local terminal receipt for the workload verdict.
-  3. If the receipt is terminal, do not cancel or duplicate the command solely
+  2. Run ${cyan("bb run inspect <command-run-id>")} from the owning checkout.
+  3. Prefer the owning runner's local terminal receipt for the workload verdict.
+  4. If the receipt is terminal, do not cancel or duplicate the command solely
      because remote state remains ${cyan("registered")} or ${cyan("running")}.
-  4. If the receipt is absent/non-terminal, retain the original runner result;
+  5. If the receipt is absent/non-terminal, retain the original runner result;
      do not poll or infer completion from elapsed time.
-  5. Report the receipt and remote discrepancy as telemetry evidence.
+  6. Report the receipt and remote discrepancy as telemetry evidence. A stale
+     test-run or command-run is never validation evidence.
+
+${bold("One controlled push retry")}
+Only after inspection leaves the original push unresolved, arm an exact-SHA CI
+wait before one new push, then verify the resulting CI run reports that SHA:
+
+  ${cyan("bb wait 'ci:repo=SupplySpark/supplyspark-ent,scope=next,sha=<full-sha>' --heartbeat")}
+
+Do not substitute ${cyan("pr-state")}, a timer, or a status-polling loop for a bare
+push. If the prior push has no terminal receipt, keep it unresolved rather than
+counting it as validation evidence.
 
 ${bold("Boundary")}
 Command-run status is agent-owned. A different agent may be denied access; that

package/src/run.mjs

@@ -11,7 +11,7 @@ import { stackLeaseIdFromEnv, withStackLeaseCorrelation } from "./stack-lease-co
 import { mkdir, readFile, writeFile, chmod, unlink, stat, rename } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { performance } from "node:perf_hooks";
 import { callToolJson } from "./api.mjs";
@@ -26,7 +26,7 @@ import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
 import { attestTelemetryCredential, loadTelemetryIdentity } from "./telemetry-config.mjs";
 import { VERSION } from "./version.mjs";
 import {
-  TERMINAL_RETRY_BUDGET_MS, DELIVERY_CALL_TIMEOUT_MS, callWithContextIdentity, classifyTerminalUpdateFailure,
+  TERMINAL_RETRY_BUDGET_MS, DELIVERY_CALL_TIMEOUT_MS, callWithContextIdentity, classifyTerminalUpdateFailure, contextServerUrl,
   ensureRunDelivery, parkedRecord, runDelivery, terminalUpdateAccepted,
 } from "./run-delivery.mjs";
 
@@ -221,6 +221,154 @@ export function commandHash(command) { return createHash("sha256").update(JSON.s
 export function environmentHash(cwd, environment) { return createHash("sha256").update(`${cwd}\0${environment}`).digest("hex"); }
 export function receiptPath(runId) { return join(homedir(), ".botbuddy", "command-runs", `${runId}.receipt.json`); }
 export function contextPath(runId) { return join(homedir(), ".botbuddy", "command-runs", `${runId}.context.json`); }
+
+// A command receipt is evidence about one checkout revision, not a claim that
+// its working tree was clean.  Resolving this once at launch lets recovery
+// distinguish a stale callback from an unrelated later command without ever
+// returning the command line itself.
+export function sourceSha(cwd, { exec = execFileSync } = {}) {
+  try {
+    const sha = String(exec("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })).trim();
+    return /^[0-9a-f]{40,64}$/i.test(sha) ? sha.toLowerCase() : null;
+  } catch { return null; }
+}
+
+const TERMINAL_COMMAND_STATUSES = new Set(["success", "failure", "cancelled", "timed_out", "owner_lost"]);
+const TERMINAL_REMOTE_STATUSES = new Set(["succeeded", "failed", "cancelled", "timed_out", "owner_lost", "invalidated"]);
+const REMOTE_STATUS_FOR_COMMAND_STATUS = Object.freeze({
+  success: "succeeded",
+  failure: "failed",
+  cancelled: "cancelled",
+  timed_out: "timed_out",
+  owner_lost: "owner_lost",
+});
+
+function parseOwnedRunFile(raw, runId) {
+  try {
+    const value = JSON.parse(raw);
+    return value && value.run_id === runId ? value : null;
+  } catch { return null; }
+}
+
+function freshContext(context, now) {
+  const launchedAt = Date.parse(context?.launched_at ?? "");
+  const timeoutMs = Number(context?.timeout_seconds) * 1_000;
+  return Number.isFinite(launchedAt) && Number.isFinite(timeoutMs) && timeoutMs > 0
+    && now <= launchedAt + timeoutMs + TIMEOUT_GRACE_MS + 60_000;
+}
+
+function publicRemoteSummary(result) {
+  if (!result?.ok || result.isError || !result.data || typeof result.data !== "object") return { state: "unavailable" };
+  const status = typeof result.data.status === "string" ? result.data.status : null;
+  return {
+    state: status ? "available" : "unavailable",
+    ...(status ? { status } : {}),
+    ...(typeof result.data.exit_code === "number" ? { exit_code: result.data.exit_code } : {}),
+    ...(typeof result.data.ended_at === "string" ? { ended_at: result.data.ended_at } : {}),
+  };
+}
+
+function terminalOutcomesAgree(receipt, remote) {
+  if (!receipt || remote.state !== "available") return false;
+  if (REMOTE_STATUS_FOR_COMMAND_STATUS[receipt.status] !== remote.status) return false;
+  // A missing exit code is meaningful for cancellation, timeout, and
+  // owner-loss. When both sides do have one, a disagreement is never hidden.
+  return typeof receipt.exit_code !== "number" || typeof remote.exit_code !== "number"
+    || receipt.exit_code === remote.exit_code;
+}
+
+// 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, {
+  call = callToolJson,
+  read = readFile,
+  now = Date.now(),
+  processAlive = workerProcessGroupAlive,
+  receiptFile = receiptPath,
+  contextFile = contextPath,
+} = {}) {
+  if (typeof runId !== "string" || !runId.trim()) {
+    return { schema_version: RUN_SCHEMA_VERSION, classification: "rejected", rerun_safe: false, cancellation_safe: false, error: "run_id_required" };
+  }
+  const id = runId.trim();
+  const [receiptRaw, contextRaw] = await Promise.all([
+    read(receiptFile(id), "utf8").catch(() => null),
+    read(contextFile(id), "utf8").catch(() => null),
+  ]);
+  const receipt = typeof receiptRaw === "string" ? parseOwnedRunFile(receiptRaw, id) : null;
+  const context = typeof contextRaw === "string" ? parseOwnedRunFile(contextRaw, id) : null;
+  // A durable run belongs to the agent that launched it. Prefer its sealed
+  // session identity; older contexts must use a current worktree session and
+  // never silently fall back to an unrelated durable machine credential.
+  const remoteResult = await callWithContextIdentity(context, call)("get_command_run", { run_id: id }, {
+    ...(context ? { serverUrl: contextServerUrl(context) } : {}),
+  }).catch(() => null);
+  const remote = publicRemoteSummary(remoteResult);
+  const receiptTerminal = Boolean(receipt && TERMINAL_COMMAND_STATUSES.has(receipt.status));
+  const receiptFingerprint = receipt && typeof receipt.command_hash === "string" && /^[a-f0-9]{64}$/i.test(receipt.command_hash)
+    && typeof receipt.source_sha === "string" && /^[a-f0-9]{40,64}$/i.test(receipt.source_sha);
+  const fingerprintMismatch = Boolean(context && (
+    (context.command_hash && context.command_hash !== receipt?.command_hash)
+    || (context.source_sha && context.source_sha !== receipt?.source_sha)
+  ));
+  const contextMatchesReceipt = !fingerprintMismatch;
+  const sourceBound = Boolean(receiptTerminal && receiptFingerprint && contextMatchesReceipt);
+
+  if (receiptTerminal) {
+    // A context that identifies a different command/revision must never be
+    // promoted to completed evidence, even if its receipt is terminal.
+    if (fingerprintMismatch) {
+      return {
+        schema_version: RUN_SCHEMA_VERSION,
+        run_id: id,
+        classification: "unknown",
+        rerun_safe: false,
+        cancellation_safe: false,
+        source_bound: false,
+        local: { status: null, exit_code: null },
+        remote,
+      };
+    }
+    const remoteTerminal = remote.state === "available" && TERMINAL_REMOTE_STATUSES.has(remote.status);
+    const outcomesAgree = remoteTerminal && terminalOutcomesAgree(receipt, remote);
+    return {
+      schema_version: RUN_SCHEMA_VERSION,
+      run_id: id,
+      classification: outcomesAgree ? "completed" : remoteTerminal ? "completed_locally_remote_conflict" : remote.status === "registered" || remote.status === "running" || remote.status === "approval_required" ? "completed_locally_remote_stale" : "completed_locally_remote_unknown",
+      rerun_safe: false,
+      cancellation_safe: false,
+      source_bound: sourceBound,
+      local: { status: receipt.status, exit_code: receipt.exit_code ?? null },
+      remote,
+    };
+  }
+
+  const pids = [context?.worker_pid, context?.workload_pid].filter((pid) => Number.isInteger(pid) && pid > 0);
+  if (context && freshContext(context, now) && pids.some((pid) => processAlive(pid))) {
+    return {
+      schema_version: RUN_SCHEMA_VERSION,
+      run_id: id,
+      classification: "running",
+      rerun_safe: false,
+      cancellation_safe: false,
+      source_bound: false,
+      local: { status: null, exit_code: null },
+      remote,
+    };
+  }
+
+  return {
+    schema_version: RUN_SCHEMA_VERSION,
+    run_id: id,
+    classification: "unknown",
+    rerun_safe: false,
+    cancellation_safe: false,
+    source_bound: false,
+    local: { status: null, exit_code: null },
+    remote,
+  };
+}
 function cancellationPath(contextFile) { return `${contextFile}.cancelled`; }
 
 async function markCancellation(contextFile, runId) {
@@ -250,6 +398,8 @@ async function preWorkloadCancellationReceipt(context) {
     ended_at: now,
     exit_code: null,
     signal: "SIGTERM",
+    command_hash: context.command_hash ?? commandHash(context.command ?? []),
+    source_sha: context.source_sha ?? null,
     recovery_command: null,
     bounded_log: "",
     output_characters: 0,
@@ -347,7 +497,7 @@ function rejectedSessionReceipt(error, runId) {
 
 export async function launchRun(argv, {
   cwd = process.cwd(), spawnImpl = spawn, call = null, childEnv = null, testRun = null,
-  resolveCredential = null, renewCredential = selfHealAgentSession, env = process.env,
+  resolveCredential = null, renewCredential = selfHealAgentSession, env = process.env, getSourceSha = sourceSha,
 } = {}) {
   const parsed = parseRunArgs(argv, env);
   let managedCredential = null;
@@ -376,12 +526,14 @@ export async function launchRun(argv, {
   const effectiveCall = (t, a) => (call ?? callToolJson)(t, a,
     opts.sessionToken ? { auth: { "x-agent-api-key": opts.sessionToken } } : {});
   const runId = randomUUID();
+  const commandFingerprint = commandHash(command);
+  const launchSourceSha = getSourceSha(cwd);
   const registerArgs = () => ({
     // Omit session_id entirely when only a token is present — the backend derives
     // it. A plain id is still sent (and honoured) when supplied.
     ...(opts.sessionId ? { session_id: opts.sessionId } : {}),
     run_id: runId, tool_category: opts.category,
-    command_hash: commandHash(command), environment_hash: environmentHash(cwd, opts.environment),
+    command_hash: commandFingerprint, ...(launchSourceSha ? { source_sha: launchSourceSha } : {}), environment_hash: environmentHash(cwd, opts.environment),
     environment: opts.environment, command_kind: opts.kind, expected_duration_seconds: opts.expectedDuration,
     rerun_reason: opts.rerunReason,
   });
@@ -411,7 +563,7 @@ export async function launchRun(argv, {
   // every callback is attributable to the same agent. It deliberately stays
   // outside child_env, receipts, and the workload's process environment.
   const knownSession = opts.sessionId ?? managedCredential?.identity?.sessionId ?? managedCredential?.sessionId;
-  await writeJson(context, { schema_version: RUN_SCHEMA_VERSION, context_path: context, run_id: runId, run_credential: registration.data.run_credential, receipt_upload: registration.data.receipt_upload, command, cwd, timeout_seconds: opts.timeout, receipt_path: receipt, launched_at: new Date().toISOString(), server_url: SERVER_URL,...(opts.sessionToken ? { callback_session_token: opts.sessionToken } : {}), ...(knownSession ? { callback_session_id: knownSession } : {}), ...(childEnv && Object.keys(childEnv).length ? { child_env: childEnv } : {}), ...(testRun ? { test_run: testRun } : {}) });
+  await writeJson(context, { schema_version: RUN_SCHEMA_VERSION, context_path: context, run_id: runId, run_credential: registration.data.run_credential, receipt_upload: registration.data.receipt_upload, command, command_hash: commandFingerprint, source_sha: launchSourceSha, cwd, timeout_seconds: opts.timeout, receipt_path: receipt, launched_at: new Date().toISOString(), server_url: SERVER_URL, ...(opts.sessionToken ? { callback_session_token: opts.sessionToken } : {}), ...(knownSession ? { callback_session_id: knownSession } : {}), ...(childEnv && Object.keys(childEnv).length ? { child_env: childEnv } : {}), ...(testRun ? { test_run: testRun } : {}) });
   const [file, args] = workerInvocation(context);
   try {
     const worker = spawnImpl(file, args, { detached: true, stdio: "ignore", windowsHide: true });
@@ -804,7 +956,7 @@ export async function cancelRun(runId, {
 async function finalize(context, state, call, retry = {}) {
   const boundedLog = String(state.output ?? "").slice(-8192);
   const outputCharacters = state.outputCharacters ?? String(state.output ?? "").length;
-  const receipt = { schema_version: RUN_SCHEMA_VERSION, run_id: context.run_id, status: state.status, started_at: state.startedAt, ended_at: state.endedAt, exit_code: state.exitCode, signal: state.signal, recovery_command: state.status === "failure" ? `botbuddy run --session-id <new-session-id> --environment local -- ${context.command.map((x) => JSON.stringify(x)).join(" ")}` : null, bounded_log: boundedLog, output_characters: outputCharacters, reason: state.reason ?? null };
+  const receipt = { schema_version: RUN_SCHEMA_VERSION, run_id: context.run_id, status: state.status, started_at: state.startedAt, ended_at: state.endedAt, exit_code: state.exitCode, signal: state.signal, command_hash: context.command_hash ?? commandHash(context.command ?? []), source_sha: context.source_sha ?? null, recovery_command: state.status === "failure" ? `botbuddy run --session-id <new-session-id> --environment local -- ${context.command.map((x) => JSON.stringify(x)).join(" ")}` : null, bounded_log: boundedLog, output_characters: outputCharacters, reason: state.reason ?? null };
   await writeJson(context.receipt_path, receipt);
   const bytes = await stat(context.receipt_path);
   const sha256 = createHash("sha256").update(await readFile(context.receipt_path)).digest("hex");
@@ -882,6 +1034,12 @@ export async function cmdRun(args) {
     if (args.includes("--json")) oneLine({ schema_version: RUN_SCHEMA_VERSION, ...result }, false);
     return;
   }
+  if (args[0] === "inspect") {
+    const result = await inspectRun(args[1] ?? "");
+    oneLine(result, false);
+    process.exitCode = result.classification === "rejected" ? EXIT.INVALID : EXIT.OK;
+    return;
+  }
   if (args[0] === "cancel") {
     const result = await cancelRun(args[1] ?? "");
     oneLine(result.receipt, false);
@@ -889,7 +1047,7 @@ export async function cmdRun(args) {
     return;
   }
   if (args[0] === "help" || args[0] === "--help") {
-    console.log("botbuddy run --session-id <id> --environment <local|preview|staging|production|none> [--timeout <sec>] [--rerun-reason <json>] -- <command> [args...]\nbotbuddy run --foreground --kind <test|wait|browser|ci|hook|stack> --environment <local|preview|staging|production|none> -- <command> [args...]\nbotbuddy run cancel <run_id>\n  --agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN); --agent-key / --session-token are one-release legacy aliases");
+    console.log("botbuddy run --session-id <id> --environment <local|preview|staging|production|none> [--timeout <sec>] [--rerun-reason <json>] -- <command> [args...]\nbotbuddy run --foreground --kind <test|wait|browser|ci|hook|stack> --environment <local|preview|staging|production|none> -- <command> [args...]\nbotbuddy run inspect <run_id>\nbotbuddy run cancel <run_id>\n  --agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN); --agent-key / --session-token are one-release legacy aliases");
     return;
   }
   // BOT-1701 (AC-6): one stderr nudge when a tier-3 legacy flag/env alias is used