@botbuddy/cli 1.58.1 → 1.59.1

package/package.json

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

package/src/pw/session.mjs

@@ -13,6 +13,7 @@
 // recorded. Typed/filled values, @ENV secrets, query strings, fragments, raw
 // Playwright output and error text never reach state, outbox or the server.
 import { createHash, randomUUID } from "node:crypto";
+import { stackLeaseIdFromEnv } from "../stack-lease-correlation.mjs";
 import { chmod, link, mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -330,7 +331,7 @@ function actionView(action) {
 
 // ── Lane tracker ─────────────────────────────────────────────────────────────
 
-function createLaneTracker({ root, tenant, repository, host, lane, getOutbox, deliver, now, monotonic, gitInfo, spawnHeartbeat, onAppended = null, onStateWrite = null }) {
+function createLaneTracker({ root, tenant, repository, host, lane, getOutbox, deliver, now, monotonic, gitInfo, spawnHeartbeat, onAppended = null, onStateWrite = null, env = process.env }) {
   const statePath = sessionStatePath({ root, tenant, repository, host, lane });
   const stateLock = `${statePath}.lock`;
   const execLock = `${statePath}.exec.lock`;
@@ -446,6 +447,9 @@ function createLaneTracker({ root, tenant, repository, host, lane, getOutbox, de
     if (git.branch && git.branch !== "HEAD") context.branch = String(git.branch);
     if (git.prNumber !== null && git.prNumber !== undefined && git.prNumber !== "") context.pr = String(git.prNumber);
     if (git.sha) context.sha = String(git.sha);
+    // BOT-2467: a browser session inside `bb stack run` is linked to that lease.
+    const leaseId = stackLeaseIdFromEnv(env);
+    if (leaseId) context.correlations = { stack_lease_id: leaseId };
     const state = {
       schema_version: 1, tenant, repository, host, lane: String(lane), producer_kind: PRODUCER_KIND, attempt: 1,
       source_run_id: randomUUID(), status: "active", environment, context, started_at: startedAt, next_sequence: 0,
@@ -966,10 +970,11 @@ export function createBrowserTelemetryResolver({
   now = () => new Date(), monotonic = () => performance.now(), gitInfo = () => ({}), spawnHeartbeat = null,
   onAppended = null, // test seam: observe each durable append (e.g. to simulate a crash right after it)
   onStateWrite = null, // test seam: inject a state-write failure
+  env = process.env, // BOT-2467: where BOTBUDDY_STACK_LEASE_ID is read from
 } = {}) {
   let outboxPromise = null;
   const getOutbox = () => (outboxPromise ??= createTelemetryOutbox({ root: join(root, "telemetry"), tenant, repository, producerVersion, now }));
-  const trackerFor = ({ host, lane }) => createLaneTracker({ root, tenant, repository, host, lane, getOutbox, deliver, now, monotonic, gitInfo, spawnHeartbeat, onAppended, onStateWrite });
+  const trackerFor = ({ host, lane }) => createLaneTracker({ root, tenant, repository, host, lane, getOutbox, deliver, now, monotonic, gitInfo, spawnHeartbeat, onAppended, onStateWrite, env });
   return {
     async resolve({ host, lane }) { return { tracked: true, tracker: trackerFor({ host, lane }) }; },
     async forHeartbeat(info) { return trackerFor({ host: info.host, lane: info.lane }); },

package/src/run.mjs

@@ -7,6 +7,7 @@
 // mechanism, never the owner of a child process.
 
 import { createHash, randomUUID } from "node:crypto";
+import { stackLeaseIdFromEnv, withStackLeaseCorrelation } from "./stack-lease-correlation.mjs";
 import { mkdir, readFile, writeFile, chmod, unlink, stat, rename } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
@@ -105,7 +106,7 @@ function signalExitCode(signal) {
 // runner. It has exactly one durable pre-spawn boundary (the outbox start
 // event), then returns the child verdict even when terminal delivery degrades.
 export async function launchForegroundRun(argv, {
-  cwd = process.cwd(), spawnImpl = spawn, identity = null, outbox = null, signalEmitter = process,
+  cwd = process.cwd(), spawnImpl = spawn, identity = null, outbox = null, signalEmitter = process, env = process.env,
 } = {}) {
   const { opts, command, errors } = parseRunArgs(argv);
   if (errors.length) return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", errors, exit_code: EXIT.INVALID } };
@@ -138,13 +139,14 @@ export async function launchForegroundRun(argv, {
     ).catch(() => {});
   }
   const runId = randomUUID();
-  const context = {
+  // BOT-2467: a run inside `bb stack run` is linked to that lease (uuid-validated).
+  const context = withStackLeaseCorrelation({
     repo: identity.repository,
     environment: opts.environment,
     runner: identity.appSlug,
     phase: opts.kind === "wait" ? "waiting" : "testing",
     health: "uninstrumented",
-  };
+  }, stackLeaseIdFromEnv(env));
   const base = {
     schema_version: 1,
     producer_kind: opts.kind,

package/src/stack-lease-correlation.mjs

@@ -0,0 +1,31 @@
+// BOT-2467 — link an execution to the `bb stack run` lease it ran under.
+//
+// `bb stack run` exports BOTBUDDY_STACK_LEASE_ID to its child. Every execution
+// producer (lefthook lane telemetry, `bb run`, `bb pw`) stamps it on the lifecycle
+// context as `correlations.stack_lease_id`, which execution-ingest stores on
+// `execution_runs.stack_lease_id`. Only a UUID is forwarded; anything else is
+// dropped (never sent for the server to reject the whole event). Dependency-free.
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The lease id when it is a UUID (lower-cased), else null. */
+export function validStackLeaseId(value) {
+  return typeof value === "string" && UUID_RE.test(value) ? value.toLowerCase() : null;
+}
+
+/** The lease this process runs under, from `$BOTBUDDY_STACK_LEASE_ID`, or null. */
+export function stackLeaseIdFromEnv(env = process.env) {
+  return validStackLeaseId(env?.BOTBUDDY_STACK_LEASE_ID);
+}
+
+/**
+ * `context` with `correlations.stack_lease_id` set to `leaseId` (other correlations
+ * kept). Returns `context` unchanged when the id is not a UUID.
+ */
+export function withStackLeaseCorrelation(context, leaseId) {
+  const id = validStackLeaseId(leaseId);
+  if (!id) return context;
+  const correlations = context?.correlations && typeof context.correlations === "object" && !Array.isArray(context.correlations)
+    ? context.correlations : {};
+  return { ...context, correlations: { ...correlations, stack_lease_id: id } };
+}

package/src/stack-run-outcome.mjs

@@ -0,0 +1,164 @@
+// BOT-2467 — one secret-free outcome record per `bb stack run`.
+//
+// When a push goes red under `bb stack run` the stdout receipt already says whether
+// the stack broke (a lease/transport/auth failure) or the wrapped command failed
+// (`child_exit_code` decided the exit). Nothing persisted that split. After the
+// receipt is on stdout, `cmdRun` hands the receipt fields to `reportStackRunOutcome`,
+// which makes ONE best-effort `record_stack_run_outcome` MCP call with the same
+// credential the lease calls used. It is capped at 2 s and every failure (timeout,
+// 4xx/5xx, unknown tool on an older server, a thrown error) is a silent drop: the
+// receipt and the exit code are never touched.
+//
+// The payload is an allowlist built here — never the receipt itself — so no token,
+// path, hostname, env value, argv or command output can reach the server. The
+// server re-validates the same allowlist (supabase/functions/_shared/lib/stackRunOutcome.ts).
+
+import { randomUUID } from "node:crypto";
+import { VERSION } from "./version.mjs";
+import { validStackLeaseId } from "./stack-lease-correlation.mjs";
+
+export { validStackLeaseId };
+
+export const STACK_RUN_OUTCOME_TOOL = "record_stack_run_outcome";
+export const STACK_RUN_OUTCOME_TIMEOUT_MS = 2000;
+/** `=off` disables the record (the CLI test suites set it; nothing else should). */
+export const STACK_RUN_OUTCOME_OPT_OUT_ENV = "BOTBUDDY_STACK_RUN_OUTCOME";
+export const STACK_RUN_OUTCOME_CATEGORIES = Object.freeze(["platform", "script", "interrupted", "invocation"]);
+
+const CODE_RE = /^[A-Za-z0-9_.:-]{1,64}$/;
+const TOKEN_RE = /^[a-z0-9_-]{1,64}$/;
+const LANE_RE = /^[A-Za-z0-9:_.-]{1,128}$/;
+const TICKET_RE = /^[A-Za-z][A-Za-z0-9]*-\d{1,9}$/;
+const REPO_RE = /^[A-Za-z0-9._/-]{1,128}$/;
+const VERSION_RE = /^[0-9A-Za-z.+-]{1,32}$/;
+
+// Mirrors stack.mjs EXIT (kept local so this module stays dependency-free for tests).
+const EXIT_TIMEOUT = 2;
+const EXIT_AUTH = 3;
+const EXIT_INVALID = 4;
+const EXIT_BACKEND = 5;
+const EXIT_LEASE_FAILED = 6;
+const EXIT_INTERNAL = 7;
+const EXIT_CLEANUP_FAILED = 8;
+const SIGNAL_EXITS = new Set([129, 130, 143]);
+// Typed codes that are the platform's fault whatever the exit code says.
+const PLATFORM_CODES = new Set(["TUNNEL_LOST", "LEASE_PREEMPTED", "HOST_CAPACITY_SOURCE_STALE"]);
+
+function boundedCode(value) {
+  return typeof value === "string" && CODE_RE.test(value) ? value : null;
+}
+
+/**
+ * Classify one `bb stack run` terminal from its receipt fields (`runReceiptFields`
+ * output, or the argument-error receipt) and its exit code. Pure.
+ *
+ *   script      — the lease was active and the child's exit decided the result
+ *                 (`--hard-ttl` stop → code HARD_TTL)
+ *   platform    — the stack, its transport, the credential or the backend failed
+ *   interrupted — a signal ended the run (operator Ctrl-C / parent kill)
+ *   invocation  — exit 4: bad arguments or a refused request before any lease
+ */
+export function classifyStackRunOutcome(fields = {}, exitCode) {
+  const code = boundedCode(fields.code);
+  const child = Number.isInteger(fields.child_exit_code) ? fields.child_exit_code : null;
+  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" };
+  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 };
+    // The child's exit decided the push; an unproven teardown on top of it is still
+    // named (CLEANUP_FAILED) so the platform half is never silently lost.
+    if (exitCode === child) return { category: "script", code: fields.cleanup === false ? "CLEANUP_FAILED" : null };
+    if (exitCode === EXIT_TIMEOUT) return { category: "script", code: "HARD_TTL" };
+    if (exitCode === EXIT_CLEANUP_FAILED) return { category: "platform", code: "CLEANUP_FAILED" };
+  }
+  if (exitCode === EXIT_INVALID) return { category: "invocation", code: code ?? "INVALID_ARGUMENTS" };
+  if (SIGNAL_EXITS.has(exitCode) && code == null) return { category: "interrupted", code: null };
+  switch (exitCode) {
+    // An admitted lease whose stack never reached active is a provisioning failure, not
+    // a capacity shortage (`timeout_phase` comes from stackRunOutcomeFields).
+    case EXIT_TIMEOUT: return { category: "platform", code: code ?? (fields.timeout_phase === "provision" ? "PROVISION_TIMEOUT" : "CAPACITY_TIMEOUT") };
+    case EXIT_AUTH: return { category: "platform", code: code ?? "AUTH" };
+    case EXIT_BACKEND: return { category: "platform", code: code ?? "BACKEND_UNREACHABLE" };
+    case EXIT_LEASE_FAILED: return { category: "platform", code: code ?? "LEASE_FAILED" };
+    case EXIT_CLEANUP_FAILED: return { category: "platform", code: "CLEANUP_FAILED" };
+    case EXIT_INTERNAL: return { category: "platform", code: code ?? "INTERNAL" };
+    default: return { category: "platform", code: code ?? "UNKNOWN" };
+  }
+}
+
+/** The lane id from `$BOTBUDDY_LANE_SOURCE_RUN_ID` (`lefthook:<invocation>:<lane>`), or null. */
+export function laneFromSourceRunId(value) {
+  if (typeof value !== "string" || !value.startsWith("lefthook:")) return null;
+  const parts = value.split(":");
+  if (parts.length < 3) return null;
+  const lane = parts.slice(2).join(":");
+  return LANE_RE.test(lane) ? lane : null;
+}
+
+const pick = (value, re) => (typeof value === "string" && re.test(value) ? value : null);
+const exitInt = (value) => (Number.isInteger(value) && value >= 0 && value <= 255 ? value : null);
+
+/**
+ * The allowlisted payload for one run. Every field is bounded and shape-checked here
+ * so the call carries nothing the server would refuse — and nothing secret.
+ */
+export function buildStackRunOutcomePayload({ fields = {}, exitCode, runId = randomUUID(), opts = {}, env = process.env, durationMs = null }) {
+  const { category, code } = classifyStackRunOutcome(fields, exitCode);
+  return {
+    run_id: runId,
+    lease_id: validStackLeaseId(fields.lease_id),
+    outcome: pick(fields.outcome, TOKEN_RE) ?? "unknown",
+    code,
+    category,
+    exit_code: exitInt(exitCode) ?? 255,
+    child_exit_code: exitInt(fields.child_exit_code),
+    park_reason: pick(fields.park_reason, TOKEN_RE),
+    execution_mode: pick(fields.execution_mode, TOKEN_RE),
+    transport: pick(fields.transport, TOKEN_RE),
+    fenced: fields.fenced === true,
+    lane: laneFromSourceRunId(env.BOTBUDDY_LANE_SOURCE_RUN_ID),
+    ticket: pick(opts.ticket, TICKET_RE)?.toUpperCase() ?? null,
+    repo: pick(opts.repo, REPO_RE),
+    duration_ms: Number.isFinite(durationMs) && durationMs >= 0 ? Math.round(durationMs) : null,
+    cli_version: pick(VERSION, VERSION_RE) ?? "unknown",
+  };
+}
+
+/**
+ * Best-effort record. `channel` is `{ auth, callTool }` from the lifecycle (the
+ * credential the lease calls used); without one there is nothing to authenticate
+ * with and nothing is sent. Never throws; resolves within `timeoutMs`.
+ */
+export async function reportStackRunOutcome({ fields, exitCode, opts, env = process.env, durationMs = null, channel, timeoutMs = STACK_RUN_OUTCOME_TIMEOUT_MS }) {
+  // Test suites opt out so a spawned real CLI never records a fixture run.
+  if (env?.[STACK_RUN_OUTCOME_OPT_OUT_ENV] === "off") return { sent: false, reason: "disabled" };
+  if (!channel?.auth || typeof channel.callTool !== "function") return { sent: false, reason: "no_credential" };
+  let payload;
+  try {
+    payload = buildStackRunOutcomePayload({ fields, exitCode, opts, env, durationMs });
+  } catch {
+    return { sent: false, reason: "payload_error" };
+  }
+  const ac = new AbortController();
+  let timer;
+  const TIMED_OUT = Symbol("stack-run-outcome-timeout");
+  const timeout = new Promise((resolve) => {
+    // Referenced on purpose: a never-settling call holds no handle of its own, and an
+    // unref'd timer would let the event loop end before the cap resolves the race.
+    // `finally` clears it, so a fast answer never waits on it.
+    timer = setTimeout(() => { ac.abort(); resolve(TIMED_OUT); }, timeoutMs);
+  });
+  try {
+    const call = Promise.resolve().then(() => channel.callTool(STACK_RUN_OUTCOME_TOOL, payload, { auth: channel.auth, signal: ac.signal }));
+    const result = await Promise.race([call.catch(() => null), timeout]);
+    if (result === TIMED_OUT) return { sent: false, reason: "timeout", payload };
+    return { sent: Boolean(result?.ok && !result?.isError), reason: result?.ok ? null : "refused", payload };
+  } catch {
+    return { sent: false, reason: "error", payload };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/stack.mjs

@@ -51,6 +51,7 @@ import { DEFAULT_BUNDLE_MAX_BYTES, buildStackBundle, uploadStackBundle, validate
 import { assertSshTarget, establishSshTunnel } from "./stack-tunnel.mjs";
 import { ENGINE_PUBLISHES_BEYOND_LOOPBACK, engineSocketIsLocal, formatPublishIp, isLoopbackIp, publishIpFix, resolvePublishIp } from "./docker-publish-ip.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
+import { reportStackRunOutcome } from "./stack-run-outcome.mjs";
 
 export const STACK_SCHEMA_VERSION = 1;
 
@@ -133,6 +134,8 @@ ${bold("up OPTIONS")}
                          deadline (exit 2) and a failed wait (its own exit code) never retry.
   --local-exec           FALLBACK (no Helper): run 'supabase start' in an ISOLATED --stack-path
                          stack and self-activate. Refused at the worktree root (shared stack).
+  --keep-volumes         LOCAL-EXEC only: preserve a reaped stack's volumes; refuses when the
+                         latest signed Helper receipt requires a one-time recovery stop.
   --provision-timeout N  LOCAL-EXEC: seconds 'supabase start' may run (default ${LOCAL_EXEC_PROVISION_TIMEOUT_SEC}). On
                          timeout up runs 'stack done --local-exec' itself and exits 6 with
                          park_reason provision_timeout (BOT-2154). The server also fails a local-exec
@@ -327,7 +330,7 @@ export function parseStackArgs(argv) {
     slot: null, host: null, repo: null, ticket: null, ticketUrl: null,
     prId: null, prUrl: null, purpose: null, idleTtl: null, stackPath: ".", stackPathExplicit: false,
     timeout: DEFAULT_TIMEOUT_SEC, provisionTimeout: null, reapTimeout: 300, hardTtl: null,
-    connectionFile: null, noWait: false, claimOnly: false, localExec: false, waitCapacity: null, holdOnTimeout: null,
+    connectionFile: null, noWait: false, claimOnly: false, localExec: false, keepVolumes: false, waitCapacity: null, holdOnTimeout: null,
     dockerContext: null, dockerEndpoint: null,
     // BOT-2142: execution placement (null = command default), remote-lease callback + bundle cap.
     execution: null, remote: false, localOnly: false, callbackPort: null, bundleMaxBytes: null,
@@ -452,6 +455,7 @@ export function parseStackArgs(argv) {
       case "--no-wait": opts.noWait = true; break;
       case "--claim-only": opts.claimOnly = true; break;
       case "--local-exec": opts.localExec = true; break;
+      case "--keep-volumes": opts.keepVolumes = true; break;
       case "--docker-context": if (need(a, rest[i + 1])) opts.dockerContext = rest[++i]; break;
       case "--docker-endpoint": if (need(a, rest[i + 1])) opts.dockerEndpoint = rest[++i]; break;
       case "--stop": opts.disposition = "stop"; break;
@@ -519,6 +523,9 @@ export function parseStackArgs(argv) {
   if (opts.claimOnly && (command !== "up" || !opts.localExec)) {
     errors.push("--claim-only is valid only with `stack up --local-exec`");
   }
+  if (opts.keepVolumes && (command !== "up" || !opts.localExec)) {
+    errors.push("--keep-volumes is valid only with `stack up --local-exec`");
+  }
   if ((opts.dockerContext || opts.dockerEndpoint) && !(["up", "done"].includes(command) && opts.localExec)) {
     errors.push("--docker-context and --docker-endpoint are valid only with `stack up --local-exec` or `stack done --local-exec`");
   }
@@ -1396,13 +1403,13 @@ export async function waitForLease(leaseId, isDone, isFailed, { timeoutSec, auth
         try { sig = JSON.parse(f.data); } catch { continue; }
         if (sig.signal_type !== "stack_lease" || sig.subject_key !== `lease:${leaseId}`) continue;
         const st = sig.payload?.state ?? null;
-        if (isFailed(st)) {
+        if (isFailed(st, sig.payload)) {
           // BOT-2013: carry the server's reap_reason so the receipt says WHY the lease is gone.
           const reapReason = typeof sig.payload?.reap_reason === "string" ? sig.payload.reap_reason : null;
           decided = { reason: "failed", result: { failed: true, state: st, ...(reapReason ? { reap_reason: reapReason } : {}) }, status: "error" };
           break frameLoop;
         }
-        if (isDone(st)) { decided = { reason: "matched", result: { woke: true, state: st }, status: "matched" }; break frameLoop; }
+        if (isDone(st, sig.payload)) { decided = { reason: "matched", result: { woke: true, state: st }, status: "matched" }; break frameLoop; }
       }
     }
   } catch (err) {
@@ -1602,8 +1609,8 @@ export async function parkOnLease(leaseId, isDone, isFailed, {
       // Codex #1168 P1: an authenticated read of the lease proves the outage is over, so a later,
       // independent rotation starts a fresh auth budget instead of inheriting this one.
       if (state != null) recovered();
-      if (state != null && isFailed(state)) return done({ failed: true, state, ...(read?.reap_reason ? { reap_reason: read.reap_reason } : {}) });
-      if (state != null && isDone(state)) return done({ woke: true, state });
+      if (state != null && isFailed(state, read)) return done({ failed: true, state, ...(read?.reap_reason ? { reap_reason: read.reap_reason } : {}) });
+      if (state != null && isDone(state, read)) return done({ woke: true, state });
     }
   }
 }
@@ -2096,6 +2103,60 @@ export function localTeardown(stackDir, dockerTarget, disposition, spawn = spawn
   return labelScopedTeardown(projectId, disposition, spawn, dockerEnv, log);
 }
 
+/** BOT-2398: a prior signed `volumes_reusable=false` receipt permits one exact,
+ * bounded Supabase recovery stop before a local-exec start. This deliberately
+ * has no label-scoped fallback: the signed Helper receipt authorizes only this
+ * Supabase project on this pinned daemon, and any uncertainty leaves the lease
+ * fenced without starting. */
+export async function localVolumeRecoveryStop(opts, execution, dockerTarget, {
+  targetCheck = runLocalExecTargetCheck,
+  spawn = spawnSync,
+  readProjectId = projectIdUnder,
+  acquireLock = acquireStackLock,
+  lockHeld = false,
+  env = process.env,
+} = {}) {
+  if (!opts?.localExec || !ADMITTED_DOCKER_VALIDATIONS.has(dockerTarget?.validation) ||
+      !dockerTarget?.resolved_endpoint || !dockerTarget?.server_id) return false;
+  const stackDir = stackDirFor(execution);
+  const projectId = readProjectId(stackDir);
+  if (typeof projectId !== "string" || !/^[a-z0-9][a-z0-9_-]{0,62}$/.test(projectId)) return false;
+  let lock;
+  if (!lockHeld) {
+    try { lock = await acquireLock(lockPathForProject(projectId), { timeoutMs: 0 }); }
+    catch { return false; }
+  }
+  try {
+    const currentTarget = async () => {
+      const checked = await targetCheck(opts);
+      return checked?.exitCode === 0 ? dockerTargetFromPreflight(checked.receipt) : null;
+    };
+    const before = await currentTarget();
+    if (!dockerTargetsMatch(dockerTarget, before)) return false;
+    const dockerEnv = dockerEnvForTarget(dockerTarget, env);
+    const stop = spawn("supabase", ["stop", "--workdir", stackDir, "--no-backup"], {
+      encoding: "utf8", env: dockerEnv, timeout: 120_000, killSignal: "SIGTERM",
+      stdio: ["ignore", "pipe", "pipe"], maxBuffer: 1024 * 1024,
+    });
+    if (stop?.error || stop?.status !== 0) return false;
+    const after = await currentTarget();
+    if (!dockerTargetsMatch(dockerTarget, after)) return false;
+    const listProjectResources = (args) => spawn("docker", args, {
+      encoding: "utf8", env: dockerEnv, timeout: 30_000, killSignal: "SIGTERM",
+      stdio: ["ignore", "pipe", "pipe"], maxBuffer: 1024 * 1024,
+    });
+    const containers = listProjectResources(["ps", "-aq", "--filter", `label=com.supabase.cli.project=${projectId}`]);
+    if (containers?.error || containers?.status !== 0 || String(containers.stdout || "").trim()) return false;
+    const volumes = listProjectResources(["volume", "ls", "-q", "--filter", `label=com.supabase.cli.project=${projectId}`]);
+    if (volumes?.error || volumes?.status !== 0 || String(volumes.stdout || "").trim()) return false;
+    const networks = listProjectResources(["network", "ls", "-q", "--filter", `label=com.supabase.cli.project=${projectId}`]);
+    if (networks?.error || networks?.status !== 0 || String(networks.stdout || "").trim()) return false;
+    return true;
+  } finally {
+    lock?.release?.();
+  }
+}
+
 /** BOT-2001: remove exactly one Supabase project's containers, network and (for `destroy`)
  * volumes by the CLI's project label; true iff a re-list finds NONE of the resource classes
  * this disposition removes (Codex #1012: a busy volume or network fails closed too). */
@@ -2146,9 +2207,17 @@ export async function cmdUp(opts, {
   callTool = callToolJson,
   authProvider = stackAuthHeader,
   localProvisionFn = localProvision,
+  // BOT-2398: exactly one fixed `supabase stop --no-backup` against the
+  // validated stack directory/engine, only when a signed prior reap requires it.
+  // Keep the fourth argument: the caller holds the project lock across this
+  // stop and the immediately following start, so the recovery primitive must
+  // not try to acquire the same lock recursively.
+  recoveryStopFn = localVolumeRecoveryStop,
   // BOT-2154: the self-release after a timed-out local start (`stack done --local-exec`).
   localDoneFn = null,
   waitFn = waitForLease,
+  // BOT-2398 focused seam; production uses the existing lease SSE park below.
+  waitHandoffFn = null,
   emitResult = emit,
   machineUuidFn = machineUuid,
   assertIsolated = validateLocalExecTarget,
@@ -2459,10 +2528,181 @@ export async function cmdUp(opts, {
       const reservedProjectId = projectIdUnder(stackDirFor(execution));
       const reservedConnection = connectionWithDockerTarget(
         reservedProjectId ? { project_id: reservedProjectId } : {}, localDockerTarget);
-      const reserved = await call("reserve_stack_lease", {
-        lease_id: leaseId,
-        connection: reservedConnection,
-      });
+      let volumeRecoveryRequired = false;
+      let provisionReserved = false;
+      if (d.volume_recovery_protocol === 1) {
+        const priorRead = await call("get_stack_lease", { lease_id: leaseId });
+        const current = priorRead?.ok && priorRead.data?.success ? priorRead.data : null;
+        const exactCurrentContext = current && current.state === "provisioning" &&
+          current.host_key === d.host_key && current.slot === slot &&
+          current.worktree_root === execution.worktreeRoot && current.stack_path === execution.stackPath &&
+          current.execution_mode === "local_exec";
+        if (!exactCurrentContext) {
+          const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+          const leaseCancellation = cancelled.ok && cancelled.data?.success
+            ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+            : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+          return emitResult(buildReceipt({
+            command: "up", outcome: "refused", code: "VOLUME_RECOVERY_CONTEXT_UNVERIFIED", lease_id: leaseId, slot,
+            error: "could not verify the exact local-exec host/slot/worktree before checking volume-recovery state",
+            lease_cancellation: leaseCancellation,
+          }), opts, EXIT.LEASE_FAILED);
+        }
+        const hasPriorSource = Object.prototype.hasOwnProperty.call(current, "prior_volume_source_lease_id");
+        const hasPriorDecision = Object.prototype.hasOwnProperty.call(current, "prior_volumes_reusable");
+        const priorSource = current.prior_volume_source_lease_id;
+        if (!hasPriorSource || !hasPriorDecision ||
+            (priorSource !== null && (typeof priorSource !== "string" || !priorSource.trim()))) {
+          const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+          const leaseCancellation = cancelled.ok && cancelled.data?.success
+            ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+            : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+          return emitResult(buildReceipt({
+            command: "up", outcome: "refused", code: "VOLUME_RECOVERY_HISTORY_UNVERIFIED", lease_id: leaseId, slot,
+            error: "the server omitted or malformed prior local-exec history; no recovery or start was attempted",
+            lease_cancellation: leaseCancellation,
+          }), opts, EXIT.LEASE_FAILED);
+        }
+        const reuseState = current.prior_volumes_reusable;
+        if (reuseState !== undefined && reuseState !== null && typeof reuseState !== "boolean") {
+          const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+          const leaseCancellation = cancelled.ok && cancelled.data?.success
+            ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+            : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+          return emitResult(buildReceipt({
+            command: "up", outcome: "refused", code: "VOLUME_RECOVERY_STATE_INVALID", lease_id: leaseId, slot,
+            error: "the server returned an invalid prior volume-reuse state; no recovery or start was attempted",
+            lease_cancellation: leaseCancellation,
+          }), opts, EXIT.LEASE_FAILED);
+        }
+        if (priorSource !== null && reuseState !== true && reuseState !== false) {
+          // The Helper handoff is bound to the already-reserved ordinary
+          // provision job. Reserve it before enqueueing the distinct control
+          // action; neither job may race the local start.
+          const handoffReservation = await call("reserve_stack_lease", {
+            lease_id: leaseId, connection: reservedConnection,
+          });
+          if (!handoffReservation.ok || handoffReservation.data?.success !== true) {
+            return emitResult(buildReceipt({ command: "up", outcome: "error", code: "PREDECESSOR_HANDOFF_RESERVATION_FAILED",
+              lease_id: leaseId, slot, error: "the local provision job could not be reserved before requesting the Helper fence handoff; local start was not attempted" }),
+              opts, EXIT.LEASE_FAILED);
+          }
+          provisionReserved = true;
+          const requestedHandoff = await call("request_stack_lease_predecessor_handoff", { lease_id: leaseId });
+          if (!requestedHandoff.ok || requestedHandoff.data?.success !== true ||
+              requestedHandoff.data?.handoff_required !== true ||
+              typeof requestedHandoff.data?.handoff_job_id !== "string" ||
+              !requestedHandoff.data.handoff_job_id.trim()) {
+            const cancelled = requestedHandoff.ok && requestedHandoff.data?.success === true &&
+                requestedHandoff.data?.handoff_required === false
+              ? await call("cancel_unclaimed_stack_lease", { lease_id: leaseId }) : null;
+            const leaseCancellation = cancelled
+              ? (cancelled.ok && cancelled.data?.success
+                ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+                : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" })
+              : null;
+            return emitResult(buildReceipt({
+              command: "up", outcome: "refused", code: "PREDECESSOR_HANDOFF_UNAVAILABLE", lease_id: leaseId, slot,
+              error: "the owner-authenticated Helper could not prove an accepted exact schema-1 predecessor handoff; refusing recovery stop and local start",
+              ...(leaseCancellation ? { lease_cancellation: leaseCancellation } : {}),
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          const handoffJobID = requestedHandoff.data.handoff_job_id;
+          const isAcceptedHandoff = (value) => value?.state === "provisioning" &&
+            value?.predecessor_handoff_job_id === handoffJobID &&
+            value?.predecessor_handoff_status === "completed" &&
+            value?.predecessor_handoff_outcome === "succeeded";
+          const isFailedHandoff = (value) => value?.state === "provisioning" &&
+            value?.predecessor_handoff_job_id === handoffJobID &&
+            ["failed", "stale"].includes(value?.predecessor_handoff_status);
+          let handoffState = await call("get_stack_lease", { lease_id: leaseId });
+          if (!handoffState.ok || handoffState.data?.success !== true ||
+              (handoffState.data.predecessor_handoff_job_id != null &&
+                handoffState.data.predecessor_handoff_job_id !== handoffJobID)) {
+            return emitResult(buildReceipt({ command: "up", outcome: "error", code: "PREDECESSOR_HANDOFF_STATE_UNVERIFIED",
+              lease_id: leaseId, slot, error: "the exact Helper handoff job status could not be verified; local start was not attempted" }),
+              opts, EXIT.LEASE_FAILED);
+          }
+          if (!isAcceptedHandoff(handoffState.data) && !isFailedHandoff(handoffState.data)) {
+            const waited = waitHandoffFn
+              ? await waitHandoffFn(leaseId, handoffJobID)
+              : await resilientWait(
+                (leaseState, payload) => leaseState === "provisioning" &&
+                  payload?.predecessor_handoff_job_id === handoffJobID &&
+                  payload?.predecessor_handoff_status === "completed" &&
+                  payload?.predecessor_handoff_outcome === "succeeded",
+                (leaseState, payload) => leaseState === "reap_failed" ||
+                  (leaseState === "provisioning" && payload?.predecessor_handoff_job_id === handoffJobID &&
+                    ["failed", "stale"].includes(payload?.predecessor_handoff_status)),
+              );
+            if (!waited?.woke) {
+              return emitResult(buildReceipt({ command: "up", outcome: waited?.timeout ? "timeout" : "error",
+                code: waited?.timeout ? "PREDECESSOR_HANDOFF_TIMEOUT" : "PREDECESSOR_HANDOFF_FAILED",
+                lease_id: leaseId, slot, error: "the Helper predecessor handoff did not reach accepted success; recovery stop and local start were not attempted" }),
+                opts, waited?.timeout ? EXIT.TIMEOUT : EXIT.LEASE_FAILED);
+            }
+            handoffState = await call("get_stack_lease", { lease_id: leaseId });
+          }
+          if (!handoffState.ok || !isAcceptedHandoff(handoffState.data)) {
+            return emitResult(buildReceipt({ command: "up", outcome: "error", code: "PREDECESSOR_HANDOFF_FAILED",
+              lease_id: leaseId, slot, error: "the exact Helper handoff has no accepted successful terminal receipt; recovery stop and local start were not attempted" }),
+              opts, EXIT.LEASE_FAILED);
+          }
+          // The signed Helper acknowledgement rebinds exact local custody,
+          // but schema 1 did not record whether old volumes were reusable. A
+          // recovery stop would be destructive, so honour --keep-volumes before
+          // it can be attempted.
+          if (opts.keepVolumes) {
+            const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+            const leaseCancellation = cancelled.ok && cancelled.data?.success
+              ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+              : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+            return emitResult(buildReceipt({
+              command: "up", outcome: "refused", code: "VOLUME_RECOVERY_REQUIRED", lease_id: leaseId, slot,
+              error: "the accepted predecessor handoff has no reusable-volume decision; --keep-volumes prevents the required recovery stop",
+              lease_cancellation: leaseCancellation,
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          // Run the established bounded no-backup stop under the project lock
+          // before starting this exact successor.
+          volumeRecoveryRequired = true;
+        }
+        if (reuseState === false || reuseState === true) {
+          const priorProject = current.prior_project_id;
+          const priorTarget = current.prior_docker_target;
+          const exactPriorTarget = priorSource !== null && priorProject === reservedProjectId &&
+            dockerTargetsMatch(priorTarget, localDockerTarget);
+          if (!exactPriorTarget) {
+            const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+            const leaseCancellation = cancelled.ok && cancelled.data?.success
+              ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+              : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+            return emitResult(buildReceipt({
+              command: "up", outcome: "refused", code: "VOLUME_RECOVERY_TARGET_MISMATCH", lease_id: leaseId, slot,
+              error: "the prior signed non-reusable-volume receipt is for a different or incomplete Docker target/project; refusing to start",
+              lease_cancellation: leaseCancellation,
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          if (reuseState === false && opts.keepVolumes) {
+            const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+            const leaseCancellation = cancelled.ok && cancelled.data?.success
+              ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+              : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+            return emitResult(buildReceipt({
+              command: "up", outcome: "refused", code: "VOLUME_RECOVERY_REQUIRED", lease_id: leaseId, slot,
+              error: "the exact prior Helper receipt marked volumes non-reusable; --keep-volumes prevents the required recovery stop",
+              lease_cancellation: leaseCancellation,
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          volumeRecoveryRequired = reuseState === false;
+        }
+      }
+      const reserved = provisionReserved
+        ? { ok: true, data: { success: true, reserved: true } }
+        : await call("reserve_stack_lease", {
+          lease_id: leaseId,
+          connection: reservedConnection,
+        });
       if (!reserved.ok || !reserved.data?.success) {
         // A Helper can win the reservation race by taking the queued provision
         // job between `request_stack_lease` and `reserve_stack_lease`. That is NOT
@@ -2504,10 +2744,46 @@ export async function cmdUp(opts, {
           }), opts, EXIT.LEASE_FAILED);
         }
       } else {
+        let recoveryLock = null;
+        if (volumeRecoveryRequired) {
+          if (opts.keepVolumes) {
+            const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+            return emitResult(buildReceipt({
+              command: "up", outcome: "refused", code: "VOLUME_RECOVERY_REQUIRED", lease_id: leaseId, slot,
+              error: "the exact predecessor handoff requires a recovery stop; --keep-volumes prevents the required recovery",
+              lease_cancellation: cancelled.ok && cancelled.data?.success
+                ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+                : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" },
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          if (typeof reservedProjectId !== "string" || !/^[a-z0-9][a-z0-9_-]{0,62}$/.test(reservedProjectId)) {
+            return emitResult(buildReceipt({
+              command: "up", outcome: "error", code: "VOLUME_RECOVERY_PROJECT_UNVERIFIED", lease_id: leaseId, slot,
+              error: "the isolated stack project id is unavailable; the recovery stop and supabase start were not attempted",
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          try { recoveryLock = await acquireStackLock(lockPathForProject(reservedProjectId), { timeoutMs: 0 }); }
+          catch {
+            return emitResult(buildReceipt({
+              command: "up", outcome: "error", code: "VOLUME_RECOVERY_PROJECT_BUSY", lease_id: leaseId, slot,
+              error: "the isolated stack project lock is held; the recovery stop and supabase start were not attempted",
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          let recovered = false;
+          try { recovered = await recoveryStopFn(opts, execution, localDockerTarget, { lockHeld: true }) === true; } catch { recovered = false; }
+          if (!recovered) {
+            recoveryLock.release();
+            return emitResult(buildReceipt({
+              command: "up", outcome: "error", code: "VOLUME_RECOVERY_STOP_FAILED", lease_id: leaseId, slot,
+              error: "the exact bounded `supabase stop --no-backup` recovery failed; the reserved lease remains fenced and `supabase start` was not attempted",
+            }), opts, EXIT.LEASE_FAILED);
+          }
+        }
         let conn;
         try {
           conn = connectionWithDockerTarget(localProvisionFn(opts, localDockerTarget, execution), localDockerTarget);
         } catch (e) {
+          recoveryLock?.release();
           if (e?.code === "PROVISION_TIMEOUT") {
             // BOT-2154: a bounded start that ran out of time. Release the lease ourselves —
             // `stack done --local-exec` stops whatever the start left behind and reaps the lease
@@ -2532,6 +2808,7 @@ export async function cmdUp(opts, {
           // review); do NOT cancel.
           return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: e.message }), opts, EXIT.LEASE_FAILED);
         }
+        recoveryLock?.release();
         const act = await call("activate_stack_lease", { lease_id: leaseId, connection: conn });
         if (!act.ok || !act.data?.success) {
           return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: act.error || act.data?.code || "activate failed" }), opts, EXIT.BACKEND);
@@ -2690,6 +2967,8 @@ export async function cmdDone(leaseId, opts, {
   if (!auth) return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
   const call = rpc.call;
   let dockerTarget = null;
+  let expectedDockerTarget = null;
+  let provisionedProjectId = null;
   let legacyTargetProof = null;
   let teardownDir = process.cwd();
   let leaseBefore = null;
@@ -2750,6 +3029,7 @@ export async function cmdDone(leaseId, opts, {
     // old lease would still finalize. Refuse on project drift (the provisioned project_id is
     // persisted on the lease connection at `up`).
     const provisionedProject = current.data.connection?.project_id;
+    provisionedProjectId = provisionedProject ?? null;
     if (provisionedProject) {
       const currentProject = projectIdUnder(teardownDir);
       if (currentProject && currentProject !== provisionedProject) {
@@ -2762,6 +3042,7 @@ export async function cmdDone(leaseId, opts, {
       }
     }
     const expected = current.data.connection?.botbuddy_docker_target;
+    expectedDockerTarget = expected ?? null;
     // BOT-1711 (Codex R13 P1): a modern-target lease that lacks a persisted provisioned
     // project_id was NOT provisioned by BOT-1711+ local-exec (e.g. a pre-1.32 lease that
     // recorded a non-root stack_path but actually started the worktree ROOT). Its recorded
@@ -2876,7 +3157,17 @@ export async function cmdDone(leaseId, opts, {
         error: "local `supabase stop` failed — NOT finalizing; the slot stays fenced. Tear the stack down and re-run `stack done --local-exec`, or let the reaper reconcile.",
       }), opts, EXIT.LEASE_FAILED);
     }
-    const fin = await call("finalize_stack_lease", { lease_id: leaseId });
+    // BOT-2398: a successful owner-local teardown is itself an authenticated
+    // custody receipt. Carry the exact provisioned project, Docker daemon, and
+    // disposition so the server can persist a reusable decision without waiting
+    // for a Helper reap receipt that will never exist on this path.
+    const localExecCompletion = opts.localExec && expectedDockerTarget && provisionedProjectId
+      ? { project_id: provisionedProjectId, docker_target: dockerTarget, disposition }
+      : undefined;
+    const fin = await call("finalize_stack_lease", {
+      lease_id: leaseId,
+      ...(localExecCompletion ? { local_exec_completion: localExecCompletion } : {}),
+    });
     if (fin.ok && fin.data?.success) state = fin.data.state;
     else process.stderr.write(`${yellow("⚠")} stack: finalize failed (${fin.error || fin.data?.code}); the reaper will reconcile.\n`);
   }
@@ -3061,9 +3352,17 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   const withExecution = incidentBox.execution && !withIncident?.execution ? { ...withIncident, execution: incidentBox.execution } : withIncident;
   const withIdle = incidentBox.idleLease && !withExecution?.idleLease ? { ...withExecution, idleLease: incidentBox.idleLease } : withExecution;
   const withPortBlock = incidentBox.portBlock && !withIdle?.portBlock ? { ...withIdle, portBlock: incidentBox.portBlock } : withIdle;
-  return incidentBox.webUrl && withPortBlock && !withPortBlock.webUrl ? { ...withPortBlock, webUrl: incidentBox.webUrl } : withPortBlock;
+  const final = incidentBox.webUrl && withPortBlock && !withPortBlock.webUrl ? { ...withPortBlock, webUrl: incidentBox.webUrl } : withPortBlock;
+  // BOT-2467: non-enumerable, so the receipt fields and result comparisons never see it.
+  if (final && typeof final === "object" && incidentBox.outcomeChannel) {
+    Object.defineProperty(final, OUTCOME_CHANNEL, { value: incidentBox.outcomeChannel, enumerable: false });
+  }
+  return final;
 }
 
+/** BOT-2467: where a lifecycle result carries its outcome-record channel. */
+export const OUTCOME_CHANNEL = Symbol.for("botbuddy.stackRunOutcomeChannel");
+
 async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   // BOT-1750 (Codex R9/R11 P2): `stack run` is a lease-creating entry point AND a
   // long-lived one (queue → provision → child → heartbeat → cleanup). A cached token
@@ -3083,6 +3382,8 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     refresh: refreshAuth,
     auth: initialAuth,
   });
+  // BOT-2467: cmdRun records the run's outcome with the credential this run ended on.
+  incidentBox.outcomeChannel = { get auth() { return rpc.auth; }, callTool: adapters.callTool ?? callToolJson };
   const api = adapters.api ?? {
     request: (args) => rpc.call("request_stack_lease", args),
     get: (leaseId) => rpc.call("get_stack_lease", { lease_id: leaseId }),
@@ -3713,7 +4014,9 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         }
         if (!(recheck?.ok && recheck.data?.success && recheck.data.state === "active")) {
           const cleanup = await requestCleanup();
-          return { exitCode: EXIT.TIMEOUT, outcome: "timeout", leaseId, error: `physical provision did not reach active in ${provisionTimeout}s`, cleanup, ...(parkIncident ? { incident: parkIncident } : {}) };
+          // 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 } : {}) };
         }
       }
       if (active?.failed || active?.error || active?.auth) {
@@ -3969,13 +4272,54 @@ export function runReceiptFields(result) {
   };
 }
 
-async function cmdRun(opts, childArgv) {
-  const result = await runStackLifecycle(opts, childArgv);
-  return emit(buildReceipt(runReceiptFields(result)), opts, result.exitCode);
+/**
+ * `stack run`: the lifecycle, its one receipt, then (BOT-2467) one best-effort
+ * `record_stack_run_outcome` call carrying the platform-vs-script classification.
+ * The record runs strictly AFTER the receipt is on stdout and can never change it
+ * or the returned exit code.
+ */
+export async function cmdRun(opts, childArgv, {
+  lifecycle = runStackLifecycle, report = reportStackRunOutcome, now = Date.now, env = process.env,
+} = {}) {
+  const startedAt = now();
+  const result = await lifecycle(opts, childArgv);
+  const fields = runReceiptFields(result);
+  const code = emit(buildReceipt(fields), opts, result.exitCode);
+  try {
+    await report({ fields: stackRunOutcomeFields(result), exitCode: code, opts, env, durationMs: now() - startedAt, channel: result?.[OUTCOME_CHANNEL] ?? null });
+  } catch { /* best-effort: the receipt and exit code are already final */ }
+  return code;
+}
+
+/**
+ * BOT-2467: the credential an argument-refused `stack run` can record its outcome
+ * with — env/flag/cached session only. Never self-heals (no mint, no Keychain read)
+ * on a fail-fast path.
+ */
+/**
+ * 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.
+ */
+export function stackRunOutcomeFields(result) {
+  return { ...runReceiptFields(result), ...(result?.timeoutPhase ? { timeout_phase: result.timeoutPhase } : {}) };
+}
+
+async function parseErrorOutcomeChannel(argv, { resolveCredential = resolveAgentSessionCredential, callTool = callToolJson } = {}) {
+  try {
+    // Only this command's own options: a credential-looking flag in the child argv
+    // (after `--`) is the child's, never ours.
+    const end = argv.indexOf("--");
+    const ownArgv = end === -1 ? argv : argv.slice(0, end);
+    const credential = await resolveCredential({ argv: ownArgv, env: process.env, cwd: process.cwd(), allowSelfHeal: false });
+    if (typeof credential?.token !== "string" || !AGENT_KEY_RE.test(credential.token)) return null;
+    return { auth: { "x-agent-api-key": credential.token }, callTool };
+  } catch {
+    return null;
+  }
 }
 
 /** Entry point wired from commands.mjs (`botbuddy stack ...`). Returns/sets the exit code. */
-export async function cmdStack(argv) {
+export async function cmdStack(argv, { report = reportStackRunOutcome, outcomeChannel = parseErrorOutcomeChannel } = {}) {
   if (argv.length === 0 || argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
     process.stdout.write(STACK_HELP + "\n");
     return EXIT.OK;
@@ -3983,7 +4327,12 @@ export async function cmdStack(argv) {
   const { command, leaseId, opts, errors, childArgv } = parseStackArgs(argv);
   if (errors.length) {
     for (const e of errors) process.stderr.write(`${yellow("⚠")} stack: ${e}\n`);
-    const code = emit(buildReceipt({ command: command || "?", outcome: "error", error: errors[0] }), opts, EXIT.INVALID);
+    const fields = { command: command || "?", outcome: "error", error: errors[0] };
+    const code = emit(buildReceipt(fields), opts, EXIT.INVALID);
+    // BOT-2467: a refused `stack run` is recorded as an `invocation` outcome (no lease).
+    if (command === "run") {
+      try { await report({ fields, exitCode: code, opts, env: process.env, durationMs: 0, channel: await outcomeChannel(argv) }); } catch { /* best-effort */ }
+    }
     process.exitCode = code;
     return code;
   }
@@ -4001,7 +4350,7 @@ export async function cmdStack(argv) {
       case "status": code = await cmdStatus(leaseId, opts); break;
       case "touch": code = await cmdTouch(leaseId, opts); break;
       case "done": code = await cmdDone(leaseId, opts); break;
-      case "run": code = await cmdRun(opts, childArgv); break;
+      case "run": code = await cmdRun(opts, childArgv, { report }); break;
       default:
         process.stderr.write(`${yellow("⚠")} stack: unknown subcommand "${command}". Try ${bold("botbuddy stack help")}.\n`);
         code = emit(buildReceipt({ command: command || "?", outcome: "error", error: `unknown subcommand: ${command}` }), opts, EXIT.INVALID);

package/src/wait-core.mjs

@@ -568,6 +568,72 @@ export function parseConditions(specs) {
   return { conditions, errors };
 }
 
+// ---------------------------------------------------------------------------
+// BOT-2467: a secret-free description of grammar failures, for the
+// `wait_setup_error` sensor event. Per failed spec: the attempted condition TYPE
+// (only when it is a known type or within edit distance 2 of one — else
+// "unknown") and a parse_error category derived from the validator's message.
+// Never the raw spec, a param name or a param value.
+// ---------------------------------------------------------------------------
+
+export const CONDITION_PARSE_ERRORS = Object.freeze([
+  "unknown_type", "missing_param", "bad_param_value", "unknown_param", "param_conflict",
+  "condition_conflict", "empty", "syntax",
+]);
+const MAX_DESCRIBED_CONDITION_ERRORS = 16;
+const TYPE_TOKEN_RE = /^[a-z0-9_-]{1,32}$/;
+
+function editDistanceAtMost(a, b, limit) {
+  if (Math.abs(a.length - b.length) > limit) return false;
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    let best = i;
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+      best = Math.min(best, row[j]);
+    }
+    if (best > limit) return false;
+    prev = row;
+  }
+  return prev[b.length] <= limit;
+}
+
+function attemptedConditionType(spec) {
+  const raw = String(spec ?? "");
+  const colon = raw.indexOf(":");
+  const token = (colon === -1 ? raw : raw.slice(0, colon)).trim();
+  if (Object.prototype.hasOwnProperty.call(VALIDATORS, token)) return token;
+  const lower = token.toLowerCase();
+  if (!TYPE_TOKEN_RE.test(lower)) return "unknown";
+  return Object.keys(VALIDATORS).some((known) => editDistanceAtMost(lower, known, 2)) ? lower : "unknown";
+}
+
+function conditionParseError(error) {
+  const spec = String(error?.spec ?? "");
+  const message = String(error?.message ?? "");
+  if (spec.trim() === "" || /at least one condition is required/.test(message)) return "empty";
+  if (/^unknown condition type/.test(message)) return "unknown_type";
+  if (/must be the only condition/.test(message)) return "condition_conflict";
+  if (/exactly one of|only valid with|takes no /.test(message)) return "param_conflict";
+  if (/unknown key|does not accept|accepts only/.test(message)) return "unknown_param";
+  if (/\bneeds\b/.test(message)) return "missing_param";
+  if (/\bmust\b/.test(message)) return "bad_param_value";
+  return "syntax";
+}
+
+/**
+ * `parseConditions(...).errors` → `[{ attempted_type, parse_error }]`, one per failed
+ * spec in order, at most 16. Pure; safe to send (no spec text, names or values).
+ */
+export function describeConditionErrors(errors) {
+  if (!Array.isArray(errors)) return [];
+  return errors.slice(0, MAX_DESCRIBED_CONDITION_ERRORS).map((error) => {
+    const parseError = conditionParseError(error);
+    return { attempted_type: parseError === "empty" ? "unknown" : attemptedConditionType(error?.spec), parse_error: parseError };
+  });
+}
+
 // ---------------------------------------------------------------------------
 // SSE frame parsing — split-safe, keepalive-aware, multi-line data.
 // ---------------------------------------------------------------------------

package/src/wait.mjs

@@ -13,7 +13,7 @@
 // Usage:  botbuddy wait [--any] <condition>... [options]
 // Run     botbuddy wait --help for the condition grammar.
 
-import { EXIT, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt, formatPrReviewSnapshotWarnings, formatCiLatestRunNotice, formatUnknownWorkflowGuidance } from "./wait-core.mjs";
+import { EXIT, describeConditionErrors, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt, formatPrReviewSnapshotWarnings, formatCiLatestRunNotice, formatUnknownWorkflowGuidance } from "./wait-core.mjs";
 import { readAgentBinding, withPrincipalReceipt } from "./wait-profile.mjs";
 import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
@@ -915,7 +915,7 @@ export const RECOVERY = Object.freeze({
 // only error code, exit code, condition TYPES, auth path, profile name, cli version.
 const SENSOR_TELEMETRY_TIMEOUT_MS = 2000;
 
-async function reportSetupError(opts, { error, exitCode, conditions }) {
+async function reportSetupError(opts, { error, exitCode, conditions, conditionErrors = null }) {
   // Never on the session-token path. A bb_agent_/bb_sess_ SESSION token cannot
   // authenticate at sensor-ingest (edgeAuth resolves only PATs / agent keys), so it
   // would only 401. Discriminate by the credential's SOURCE, not its shape: a
@@ -939,7 +939,7 @@ async function reportSetupError(opts, { error, exitCode, conditions }) {
     timer = setTimeout(() => { ac.abort(); resolve(TIMED_OUT); }, SENSOR_TELEMETRY_TIMEOUT_MS);
   });
   try {
-    await Promise.race([sendSetupErrorEvent(opts, { error, exitCode, conditions }, ac.signal), timeout]);
+    await Promise.race([sendSetupErrorEvent(opts, { error, exitCode, conditions, conditionErrors }, ac.signal), timeout]);
   } catch {
     // Best-effort: an AbortError (2 s timeout) or any transport/lookup error drops.
   } finally {
@@ -947,7 +947,7 @@ async function reportSetupError(opts, { error, exitCode, conditions }) {
   }
 }
 
-async function sendSetupErrorEvent(opts, { error, exitCode, conditions }, signal) {
+async function sendSetupErrorEvent(opts, { error, exitCode, conditions, conditionErrors }, signal) {
   // Resolve a bearer WITHOUT ever touching the Keychain. This telemetry is
   // best-effort and runs on fail-fast paths right before process.exit; a Keychain
   // read (readProfileCredential → `security find-generic-password`) can block/prompt
@@ -994,6 +994,7 @@ async function sendSetupErrorEvent(opts, { error, exitCode, conditions }, signal
       error,
       exit_code: exitCode,
       condition_types: conditionTypes,
+      ...(Array.isArray(conditionErrors) && conditionErrors.length ? { condition_errors: conditionErrors } : {}),
       auth_path: opts.token ? "explicit_token" : "binding",
       profile: null,
       cli_version: VERSION,
@@ -1577,8 +1578,10 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
     process.stderr.write(`bb-wait: ${RECOVERY.conditions}\n`);
     emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_conditions", errors, recovery: RECOVERY.conditions });
     // BOT-1593: condition_types is [] on a grammar failure (the parsed set is
-    // partial/empty and is caller data regardless).
-    await reportSetupError(opts, { error: "invalid_conditions", exitCode: EXIT.INVALID, conditions: [] });
+    // partial/empty and is caller data regardless). BOT-2467: instead, each failed
+    // spec is described by its attempted TYPE and a parse_error category — never
+    // the spec text, a param name or a value.
+    await reportSetupError(opts, { error: "invalid_conditions", exitCode: EXIT.INVALID, conditions: [], conditionErrors: describeConditionErrors(errors) });
     process.exit(EXIT.INVALID);
   }