@botbuddy/cli 1.58.1 → 1.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.58.1",
+  "version": "1.59.0",
   "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;
 
@@ -3061,9 +3062,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 +3092,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 +3724,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 +3982,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 +4037,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 +4060,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);
   }