@botbuddy/cli 1.60.0 → 1.60.2

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.2",
+  "source_commit": "6c687a8220e66196ede9b560405ff1493d0752f0",
+  "source_sha256": "2bb86426999a110ead51a17d7ab60b5cc816901b9cbd3c4426b6d02e75ab6288",
   "target": "darwin-arm64",
-  "sha256": "b6fe4ed183d92a32e398cb9de3f82ac6b4634188409f51eadad457ca6b37c307"
+  "sha256": "5a197ab76ecd57a479f26d364ad06b1f226a45ac6642a7f034ab725c432940e7"
 }

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.2",
+  "source_commit": "6c687a8220e66196ede9b560405ff1493d0752f0",
+  "source_sha256": "2bb86426999a110ead51a17d7ab60b5cc816901b9cbd3c4426b6d02e75ab6288",
   "target": "linux-x64",
-  "sha256": "3a1839c5800e38bf9bb7a1465555e0cace01ef82d9c382fde1e036608c536fe8"
+  "sha256": "f3c2ae3f7dd8c80ff439817d25e0577f236d532dafbc6714402945a84abce354"
 }

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.2",
+  "source_commit": "6c687a8220e66196ede9b560405ff1493d0752f0",
+  "source_sha256": "2bb86426999a110ead51a17d7ab60b5cc816901b9cbd3c4426b6d02e75ab6288",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "b6fe4ed183d92a32e398cb9de3f82ac6b4634188409f51eadad457ca6b37c307",
+      "sha256": "5a197ab76ecd57a479f26d364ad06b1f226a45ac6642a7f034ab725c432940e7",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "3a1839c5800e38bf9bb7a1465555e0cace01ef82d9c382fde1e036608c536fe8",
+      "sha256": "f3c2ae3f7dd8c80ff439817d25e0577f236d532dafbc6714402945a84abce354",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.60.0",
+  "version": "1.60.2",
   "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

package/src/stack-run-outcome.mjs

@@ -49,8 +49,8 @@ function boundedCode(value) {
 }
 
 /**
- * Classify one `bb stack run` terminal from its receipt fields (`runReceiptFields`
- * output, or the argument-error receipt) and its exit code. Pure.
+ * Classify one `bb stack run` terminal from its internal outcome fields
+ * (`stackRunOutcomeFields`, or the argument-error receipt) and exit code. Pure.
  *
  *   script      — the lease was active and the child's exit decided the result
  *                 (`--hard-ttl` stop → code HARD_TTL)
@@ -64,7 +64,9 @@ export function classifyStackRunOutcome(fields = {}, exitCode) {
   const outcome = typeof fields.outcome === "string" ? fields.outcome : null;
   if (outcome === "interrupted") return { category: "interrupted", code };
   if (code && PLATFORM_CODES.has(code)) return { category: "platform", code };
-  if (fields.fenced === true) return { category: "platform", code: code ?? "LEASE_LOST" };
+  // The stdout fence also covers unresolved cleanup. The lifecycle supplies its
+  // original lease-fence fact separately so coincident child exits cannot hide it.
+  if ((fields.lease_fenced ?? fields.fenced) === true) return { category: "platform", code: code ?? "LEASE_LOST" };
   if (outcome === "completed" && exitCode === 0) return { category: "script", code: null };
   if (outcome === "failed" && code == null && child != null) {
     if (SIGNAL_EXITS.has(exitCode)) return { category: "interrupted", code: null };

package/src/stack.mjs

@@ -728,6 +728,10 @@ export function truncateReceipt(receipt, maxBytes = DEFAULT_RECEIPT_MAX_BYTES) {
     schema_version: r.schema_version, command: r.command, outcome: r.outcome,
     lease_id: r.lease_id ?? null, state: r.state ?? null, exit_code: r.exit_code,
     error: r.error ?? null, truncated: true,
+    ...(r.cleanup !== undefined ? { cleanup: r.cleanup } : {}),
+    ...(r.fenced !== undefined ? { fenced: r.fenced } : {}),
+    ...(r.cleanup_code ? { cleanup_code: r.cleanup_code } : {}),
+    ...(r.cleanup_error ? { cleanup_error: String(r.cleanup_error).slice(0, 160) } : {}),
   };
 }
 
@@ -1156,6 +1160,11 @@ export const REMOTE_REFUSAL_GUIDANCE = Object.freeze({
 
 /** The refusal text for a receipt: the server's message, else the CLI's guidance, else the code. */
 export function leaseRefusalError(data) {
+  if (data?.lease_id && ["STACK_CONTEXT_BIND_FAILED", "STACK_CONTEXT_ALREADY_BOUND"].includes(data?.code)) {
+    return `${data.message || data.code}; lease ${data.lease_id} is ${data.state ?? "unknown"}. ` +
+      `Inspect with \`bb stack status ${data.lease_id}\`; after the owning batch ends, release with \`bb stack done ${data.lease_id} --reap\`, ` +
+      `then wait with \`bb wait 'lease:id=${data.lease_id},state=reaped' --heartbeat\`.`;
+  }
   return data?.message || REMOTE_REFUSAL_GUIDANCE[data?.code] || data?.code || "lease request refused";
 }
 
@@ -3452,9 +3461,11 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   // BOT-2099: a best-effort diagnostic read (ledger, persisted Helper reason) never throws.
   const readLeaseQuietly = async (id) => { try { return await api.get?.(id) ?? null; } catch { return null; } };
   // BOT-2237: the typed end of a park that cannot re-authenticate — names the lease, never a
-  // capacity timeout. Exit AUTH: the caller's credential, not the lease, is what failed.
+  // capacity timeout. Keep AUTH after confirmed cleanup; unproven cleanup takes
+  // CLEANUP_FAILED while preserving the primary credential diagnostic.
   const authUnavailableResult = (waited, phase, cleanup, waitedLeaseId = leaseId) => ({
-    exitCode: EXIT.AUTH, outcome: "error", code: PARK_INCIDENT_REASONS.AUTH, leaseId: waitedLeaseId ?? null, cleanup,
+    exitCode: cleanup?.ok === false ? EXIT.CLEANUP_FAILED : EXIT.AUTH,
+    outcome: "error", code: PARK_INCIDENT_REASONS.AUTH, leaseId: waitedLeaseId ?? null, cleanup,
     error: `${waited.error} while the lease was ${phase}; its server state is unknown to this run — inspect it with \`bb stack status ${waitedLeaseId}\` after \`bb doctor --fix\``,
     ...(parkIncident ? { incident: parkIncident } : {}),
   });
@@ -3595,7 +3606,9 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     // state — instead of leaving this wait to park until --reap-timeout on a reap
     // that already failed. Report that specific outcome instead of the generic
     // "was not proven" timeout message.
-    // BOT-2099 (Codex #1057 R6): the signed-reap wait survives auth/availability blips too.
+    // Cleanup owns one immutable deadline. Its signed reap wait may recover from a
+    // transient relay/auth blip, but never repeats the release request. A persistent
+    // failure remains explicit receipt data below; it never fabricates a reap.
     const reaped = await resilientWait(leaseId, (state) => state === "reaped", (state) => state === "reap_failed", { timeoutSec: opts.reapTimeout, auth: rpc.auth });
     if (reaped?.woke || reaped?.state === "reaped") return cleanupResult = { ok: true, state: "reaped" };
     if (reaped?.failed) return cleanupResult = { ok: false, error: "the signed reap failed and the lease may still hold containers (fenced) — see stack hygiene" };
@@ -3612,12 +3625,21 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     if (recheck?.ok && recheck.data?.success && recheck.data.state === "reaped") return cleanupResult = { ok: true, state: "reaped" };
     const postCheck = durableReapFailure(recheck);
     if (postCheck) return cleanupResult = postCheck;
-    return cleanupResult = { ok: false, error: reaped?.timeout ? `signed reap did not arrive within ${opts.reapTimeout}s` : (reaped?.error || "signed reap was not proven") };
+    const persistentWaitFailure = reaped?.incident && reaped.incident.recovered === false
+      ? reaped.incident.last_error
+      : null;
+    return cleanupResult = {
+      ok: false,
+      error: persistentWaitFailure ?? (reaped?.timeout ? `signed reap did not arrive within ${opts.reapTimeout}s` : (reaped?.error || "signed reap was not proven")),
+    };
     })().catch((error) => {
-      // BOT-2237: a release/read whose session renewal THROWS (e.g. `session_mint_invalid`
-      // once the cache names another agent) is a failed cleanup of THIS lease — never an
-      // exception that escapes the lifecycle and loses the lease id from the receipt.
-      return cleanupResult = { ok: false, error: `cleanup could not run: ${error?.code ? `${error.code}: ` : ""}${error?.message ?? error}` };
+      // A release/read whose session renewal throws is a failed cleanup of THIS lease —
+      // never an exception that escapes the lifecycle and loses its recovery receipt.
+      return cleanupResult = {
+        ok: false,
+        code: error?.code ?? null,
+        error: String(error?.message ?? error),
+      };
     });
     return cleanupPromise;
   };
@@ -3906,11 +3928,14 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         ?? stackPathRootRefusalNotice(request.data?.code, request.data?.message)
         ?? remoteRefusalNotice(request.data?.code);
       if (hint) stderrLine(hint);
-      // BOT-1803: the slot's idle lease stays idle (another mode/host); keep its block.
-      if (request.data?.code === "STACK_EXECUTION_MODE_MISMATCH" && request.data?.lease_id) retainBlock = true;
+      // A refusal naming an admitted lease (including a failed context bind or
+      // an idle mode mismatch) is not proof that its ports are free. Keep the
+      // claim until owner-safe cleanup is verified; never reap a possibly live batch.
+      if (request.data?.lease_id) retainBlock = true;
       return {
         exitCode: leaseRefusalExit(request.data?.code), outcome: "error", code: request.data?.code,
         ...capacityStaleReceiptFields(request.data), error: leaseRefusalError(request.data),
+        ...(request.data.lease_id ? { leaseId: request.data.lease_id, state: request.data.state ?? null } : {}),
       };
     }
     leaseId = request.data.lease_id;
@@ -3934,7 +3959,12 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       // With a stable identity a live lease in THIS stack directory is bound to our block.
       if (request.data.stack_path != null && request.data.stack_path === execution.stackPath &&
           (request.data.worktree_root == null || request.data.worktree_root === execution.worktreeRoot)) retainBlock = true;
-      return { exitCode: EXIT.BACKEND, outcome: "error", leaseId, error: "a live lease already exists for this agent and stack slot; wait for that batch to finish instead of sharing its stack" };
+      const blockedState = request.data.state ?? "unknown";
+      const recovery = blockedState === "reaping"
+        ? `wait with \`bb wait 'lease:id=${leaseId},state=reaped' --heartbeat\``
+        : `inspect with \`bb stack status ${leaseId}\`; after the owning batch ends, release with \`bb stack done ${leaseId} --reap\`, then wait with \`bb wait 'lease:id=${leaseId},state=reaped' --heartbeat\``;
+      return { exitCode: EXIT.BACKEND, outcome: "error", leaseId, state: blockedState,
+        error: `live lease already exists for this agent and stack slot: ${leaseId} is ${blockedState}; ${recovery}` };
     }
 
     leaseProvisioned = true; // from here a Helper may act on this lease
@@ -4112,7 +4142,13 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         };
       }
       if (parked?.failed) { const cleanup = await requestCleanup(); return { exitCode: EXIT.LEASE_FAILED, outcome: "error", leaseId, error: `lease was ${parked.state} while queued (reap_reason=${parked.reap_reason ?? "unknown"})`, cleanup, ...incident }; }
-      if (parked?.error || parked?.auth) { const cleanup = await requestCleanup(); return { exitCode: parked?.auth ? EXIT.AUTH : EXIT.LEASE_FAILED, outcome: "error", leaseId, error: parked?.error || "lease did not leave queue", cleanup, ...incident }; }
+      if (parked?.error || parked?.auth) {
+        const cleanup = await requestCleanup();
+        return {
+          exitCode: parked?.auth && cleanup?.ok === false ? EXIT.CLEANUP_FAILED : (parked?.auth ? EXIT.AUTH : EXIT.LEASE_FAILED),
+          outcome: "error", leaseId, error: parked?.error || "lease did not leave queue", cleanup, ...incident,
+        };
+      }
       state = parked.state;
     }
     if (state !== "active") {
@@ -4143,7 +4179,10 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         // BOT-1816's class of dropped wakes) even though the lease genuinely went
         // active or was deferred back to queued. One direct read before declaring
         // a timeout avoids reaping a healthy stack or destroying a kept queue place.
-        const recheck = await api.get(leaseId);
+        // Production adapters always expose `get`. Focused lifecycle adapters may
+        // intentionally model only admission and release; preserve their original
+        // terminal cleanup receipt rather than replacing it with a test-only TypeError.
+        const recheck = api.get ? await api.get(leaseId) : null;
         if (recheck?.ok && recheck.data?.success && recheck.data.state === "queued") {
           parkView = recheck.data;
           const why = parkView.provision_defer_reason ?? "host capacity";
@@ -4153,9 +4192,16 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         }
         if (!(recheck?.ok && recheck.data?.success && recheck.data.state === "active")) {
           const cleanup = await requestCleanup();
-          // BOT-2467: `timeoutPhase` is for the outcome record only (never on the receipt):
-          // an admitted lease whose stack never started is not a capacity shortage.
-          return { exitCode: EXIT.TIMEOUT, outcome: "timeout", timeoutPhase: "provision", leaseId, error: `physical provision did not reach active in ${provisionTimeout}s`, cleanup, ...(parkIncident ? { incident: parkIncident } : {}) };
+          const cleanupFailed = cleanup?.ok === false;
+          return {
+            exitCode: cleanupFailed ? EXIT.CLEANUP_FAILED : EXIT.TIMEOUT,
+            outcome: "timeout", timeoutPhase: "provision", leaseId,
+            // An unproven cleanup is more actionable than the generic timeout for an
+            // admitted lease, because recovery must preserve its fenced claim.
+            error: cleanupFailed ? cleanup.error : `physical provision did not reach active in ${provisionTimeout}s`,
+            cleanup, ...(parkIncident ? { incident: parkIncident } : {}),
+          };
+
         }
       }
       if (active?.failed || active?.error || active?.auth) {
@@ -4167,7 +4213,11 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
           if (read?.ok && read.data?.success && typeof read.data.error === "string" && read.data.error) why = ` — ${read.data.error}`;
         }
         const cleanup = await requestCleanup();
-        return { exitCode: active?.auth ? EXIT.AUTH : EXIT.LEASE_FAILED, outcome: "error", leaseId, error: active?.error || `lease ${active?.state ?? "failed"} before reaching active${why}`, cleanup, ...(parkIncident ? { incident: parkIncident } : {}) };
+        return {
+          exitCode: cleanup?.ok === false ? EXIT.CLEANUP_FAILED : (active?.auth ? EXIT.AUTH : EXIT.LEASE_FAILED),
+          outcome: "error", leaseId, state: active?.state ?? null, error: active?.error || `lease ${active?.state ?? "failed"} before reaching active${why}`, cleanup,
+          ...(parkIncident ? { incident: parkIncident } : {}),
+        };
       }
     }
     break;
@@ -4374,6 +4424,7 @@ export function runReceiptFields(result) {
     // BOT-1797: carry the server's typed refusal code (e.g. stack_path_root_refused)
     // so automation can branch on it instead of matching the message text.
     command: "run", outcome: result.outcome, code: result.code ?? null, lease_id: result.leaseId ?? null,
+    ...(result.state ? { state: result.state } : {}),
     // BOT-2468: the lease's /docker?lease= deeplink (null when the server sent none).
     web_url: result.webUrl ?? null,
     // BOT-2024: a stale-capacity refusal carries its phase + armable wait on the receipt.
@@ -4382,6 +4433,13 @@ export function runReceiptFields(result) {
     child_exit_code: result.childExitCode ?? null,
     // BOT-1803: an idle release is `cleanup: { idle: true, idle_since }` (nothing was reaped).
     cleanup: result.cleanup?.idle ? { idle: true, idle_since: result.cleanup.idle_since ?? null } : result.cleanup?.ok ?? null,
+    cleanup_code: result.cleanup?.code ?? null,
+    cleanup_error: result.cleanup?.ok === false ? result.cleanup.error ?? "cleanup was not proven" : null,
+    ...(result.leaseId && result.cleanup?.ok === false ? { recovery: {
+      status: `bb stack status ${result.leaseId}`,
+      wait: `bb wait 'lease:id=${result.leaseId},state=reaped' --heartbeat`,
+      release: `bb stack done ${result.leaseId} --reap`,
+    } } : {}),
     ...(result.volumesKept ? { volumes_kept: true } : {}),
     ...(result.idleLease?.reused ? { reused: result.idleLease.reused } : {}),
     ...(result.idleLease?.reprovisioned ? { reprovisioned: result.idleLease.reprovisioned } : {}),
@@ -4401,7 +4459,7 @@ export function runReceiptFields(result) {
     // BOT-2207: why it ran where it did (e.g. moved_remote_on_requeue) and every host weighed.
     ...(result.execution?.placementReason ? { placement_reason: result.execution.placementReason } : {}),
     ...(result.execution?.considered ? { considered: result.execution.considered } : {}),
-    fenced: result.fenced ?? false, error: result.error ?? result.cleanup?.error ?? null,
+    fenced: result.fenced === true || result.cleanup?.ok === false, error: result.error ?? result.cleanup?.error ?? null,
     // BOT-2099: a platform auth/availability blip during the park is reported as an
     // incident (reason, window, attempts, recovered) — never as the lease's outcome.
     ...(result.incident ? { platform_incident: result.incident } : {}),
@@ -4440,10 +4498,14 @@ export async function cmdRun(opts, childArgv, {
  */
 /**
  * BOT-2467: the fields the outcome classifier reads — the receipt's, plus facts the
- * receipt deliberately does not carry (which wait a timeout ended). Never emitted.
+ * receipt deliberately does not carry (which wait a timeout ended and the original
+ * lease fence). Never emitted.
  */
 export function stackRunOutcomeFields(result) {
-  return { ...runReceiptFields(result), ...(result?.timeoutPhase ? { timeout_phase: result.timeoutPhase } : {}) };
+  return {
+    ...runReceiptFields(result), lease_fenced: result?.fenced === true,
+    ...(result?.timeoutPhase ? { timeout_phase: result.timeoutPhase } : {}),
+  };
 }
 
 async function parseErrorOutcomeChannel(argv, { resolveCredential = resolveAgentSessionCredential, callTool = callToolJson } = {}) {

package/src/wait-core.mjs

@@ -35,6 +35,7 @@ export const EXIT = Object.freeze({
   // liveness reaper abandoned it, it was cancelled, or its row is gone. The relay
   // refuses the stream with a typed `wait_abandoned` error frame; re-arm from next_cursor.
   ABANDONED: 11,
+  LEASE_CLEANUP_FAILED: 12,
 });
 
 // BOT-2013: the uuid spellings Postgres accepts for a lease id (uuid_in), mirrored by the SQL
@@ -58,6 +59,7 @@ export function leaseLostDetail(signal, condition) {
     lease_id: signal.payload?.lease_id ?? condition.params?.id ?? null,
     lease_state: leaseState,
     reap_reason: typeof signal.payload?.reap_reason === "string" ? signal.payload.reap_reason : null,
+    ...(condition.params?.state === "active" && signal.payload?.error_class ? { error_class: signal.payload.error_class } : {}),
   };
 }
 
@@ -797,7 +799,15 @@ function compactLeaseLostState(state) {
   if (!state || typeof state !== "object") return null;
   const short = (v) => (typeof v === "string" ? v.slice(0, 64) : null);
   if (state.lease_id == null && state.reap_reason == null) return null;
-  return { lease_id: short(state.lease_id), lease_state: short(state.lease_state), reap_reason: short(state.reap_reason) };
+  return { lease_id: short(state.lease_id), lease_state: short(state.lease_state), reap_reason: short(state.reap_reason),
+    ...(state.cleanup_unverified === true ? { cleanup_unverified: true } : {}) };
+}
+
+function compactCleanupState(state) {
+  if (!state || !["signed_reap", "never_provisioned", "local_exec_teardown", "pre_driver_absence"].includes(state.cleanup_proof)) return null;
+  const short = (v) => typeof v === "string" ? v.slice(0, 64) : null;
+  return Object.fromEntries(["lease_id", "lease_state", "reap_disposition", "cleanup_proof", "cleanup_receipt_id"]
+    .filter((key) => state[key] != null).map((key) => [key, short(state[key])]));
 }
 
 /**
@@ -818,8 +828,9 @@ export function truncateReceipt(receipt, maxBytes = 10240) {
   // state is the whole point of that receipt (which lease, why) and is already three short
   // fields, so it is kept compact instead (BOT-2013, Codex #1017 P2).
   const leaseLostState = clone.outcome === "lease_lost" ? compactLeaseLostState(clone.state) : null;
+  const cleanupState = ["matched", "error"].includes(clone.outcome) ? compactCleanupState(clone.state) : null;
   if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes) {
-    clone.state = leaseLostState ?? { truncated: true };
+    clone.state = leaseLostState ?? cleanupState ?? { truncated: true };
   }
   // A matched signal's subject key can be caller-controlled through the raw
   // event escape hatch. Keep the durable sequence pointer, but not an
@@ -863,6 +874,19 @@ export function truncateReceipt(receipt, maxBytes = 10240) {
     delete clone.detail;
     clone.detail_truncated = true;
   }
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && cleanupState) {
+    const base = {
+      schema_version: clone.schema_version, outcome: clone.outcome,
+      ...(clone.error ? { error: String(clone.error).slice(0, 48) } : {}),
+      state: cleanupState, truncated: true,
+    };
+    for (const key of ["client", "next_cursor", "wait_session_id"]) {
+      if (clone[key] == null) continue;
+      const candidate = { ...base, [key]: clone[key] };
+      if (Buffer.byteLength(JSON.stringify(candidate)) <= maxBytes) base[key] = clone[key];
+    }
+    return base;
+  }
   if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.outcome === "lease_lost") {
     // BOT-2013: the bounded fallback keeps the lease-lost detail, then adds the resume
     // pointers only while they still fit.
@@ -1096,12 +1120,22 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
       // stack_lease frame for this lease id is ours to wake on.
       if (signal.signal_type !== "stack_lease" || signal.subject_key !== `lease:${params.id}`) return false;
       // BOT-2400: with `state=`, only that state matches — or a terminal loss on the way
-      // (reap_failed for a reap wait; any reap state while waiting for provisioning/active),
-      // which finalizeMatch reports as lease_lost. `reaping` en route to `reaped` keeps waiting.
+      // (any reap state while waiting for provisioning/active), which finalizeMatch reports
+      // as lease_lost. `reaping` en route to `reaped` keeps waiting.
       if (params.state != null) {
         const leaseState = signal.payload?.state;
+        if (params.state === "reaped") {
+          // BOT-1948: a raw `reaped` row is not cleanup proof. Only the server's verified
+          // evidence (an accepted signed reap receipt, or a verified never-provisioned no-op)
+          // ends the reap wait as matched/cleanup-failed. An unverified reap_failed is still
+          // terminal (BOT-2400 Codex #1194 P1) and ends lease_lost without claiming cleanup.
+          if (signal.payload?.cleanup_verified === true) return leaseState === "reaped" || leaseState === "reap_failed";
+          // The server marks a reaped registration snapshot it can never prove as
+          // explicitly unverified (strictly false; an absent field keeps waiting).
+          if (signal.payload?.cleanup_verified === false && leaseState === "reaped") return true;
+          return leaseState === "reap_failed";
+        }
         if (leaseState === params.state) return true;
-        if (params.state === "reaped") return leaseState === "reap_failed";
         return LEASE_LOST_STATES.has(leaseState);
       }
       return true;
@@ -1564,6 +1598,25 @@ export async function runWaitLoop({
   // provisioning against a dead lease.
   const finalizeMatch = async (entry, signal) => {
     const condition = conditions.find((c) => c.id === entry.condition_id);
+    if (condition?.type === "lease" && condition.params.state === "reaped" && signal.payload?.cleanup_verified === true) {
+      const p = signal.payload;
+      const failed = p.state === "reap_failed";
+      return finalize(failed ? "error" : "matched", {
+        exitCode: failed ? EXIT.LEASE_CLEANUP_FAILED : EXIT.MATCHED, matched: [entry],
+        state: { lease_id: condition.params.id, lease_state: p.state,
+          reap_disposition: p.reap_disposition ?? null, cleanup_proof: p.cleanup_proof ?? null,
+          cleanup_receipt_id: p.cleanup_receipt_id ?? null },
+        error: failed ? "lease_cleanup_failed" : null,
+      });
+    }
+    if (condition?.type === "lease" && condition.params.state === "reaped" && signal.payload?.cleanup_verified === false) {
+      const p = signal.payload;
+      return finalize("lease_lost", {
+        exitCode: EXIT.LEASE_LOST, matched: [entry], error: "lease_lost",
+        state: { lease_id: p.lease_id ?? condition.params.id, lease_state: p.state ?? null,
+          reap_reason: typeof p.reap_reason === "string" ? p.reap_reason : null, cleanup_unverified: true },
+      });
+    }
     const lost = leaseLostDetail(signal, condition);
     if (lost) {
       return finalize("lease_lost", { exitCode: EXIT.LEASE_LOST, matched: [entry], state: lost, error: "lease_lost" });

package/src/wait.mjs

@@ -108,9 +108,14 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       \`botbuddy stack up\` (recipient-scoped to the owner).
                                       Level-triggered: an already-granted lease wakes at once.
   lease:id=<lease_id>,state=<s>       BOT-2400: wait for that exact state (provisioning, active,
-                                      reaped). state=reaped is the reap wait: an already-reaped
-                                      lease matches at once and a reaping one keeps waiting
-                                      (only reap_failed ends it, exit 9).
+                                      reaped). provisioning/active end on lease loss (exit 9,
+                                      with the provisioning failure's reason and class).
+  lease:id=<lease_id>,state=reaped    proven cleanup of that owned lease (BOT-1948). Requires an
+                                      accepted successful reap receipt or a verified
+                                      never-provisioned no-op; preserves stop/destroy
+                                      disposition. An already-cleaned lease matches at once;
+                                      reaping keeps waiting. A verified failed reap exits 12;
+                                      an unverified gave-up reap exits 9 (lease_lost).
   guidance:request=<post_id>          a command-post guidance request being answered
                                       (scoped to the asking agent; fetch the body with
                                       get_guidance_response)
@@ -200,7 +205,8 @@ OUTPUT
                 · 11 abandoned (the server ended this wait while it
                 was parked — reaped after 180 s without a live stream,
                 or cancelled; receipt outcome abandoned +
-                state.status/reason — re-arm with --since <next_cursor>).
+                state.status/reason — re-arm with --since <next_cursor>)
+                · 12 named lease cleanup failed.
                 If the receipt has
                 reacquire_lock (claim=true), acquire_lock again FIRST and re-run
                 only on a queued/busy result (granted = you hold it — just resume);