@botbuddy/cli 1.64.12 → 1.64.14

package/src/run.mjs

@@ -102,6 +102,12 @@ export function parseRunArgs(argv, env = process.env) {
   return { opts, command, errors };
 }
 
+const FOREGROUND_INSPECTION = Object.freeze({
+  run_kind: "foreground_telemetry",
+  telemetry_status_command: "bb telemetry status",
+  inspection_note: "Preserve the original terminal output. bb run inspect and bb run status inspect detached command runs; bb telemetry status checks delivery, not the command outcome.",
+});
+
 function foregroundOutcome({ exitCode, signal, timedOut }) {
   if (timedOut) return "timed_out";
   if (signal) return "canceled";
@@ -179,7 +185,7 @@ export async function launchForegroundRun(argv, {
     child = spawnImpl(command[0], command.slice(1), { cwd, detached: process.platform !== "win32", stdio: "inherit", windowsHide: true });
   } catch (error) {
     await telemetry.append({ ...base, action: "terminal", producer_event_id: `${runId}:terminal`, producer_sequence: 1, outcome: "crashed", diagnostic: { code: "spawn_failed", category: "spawn" } }).catch(() => {});
-    return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "crashed", run_id: runId, telemetry: "degraded", exit_code: EXIT.INTERNAL } };
+    return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "crashed", run_id: runId, telemetry: "degraded", exit_code: EXIT.INTERNAL, ...FOREGROUND_INSPECTION } };
   }
   let timedOut = false;
   let killTimer;
@@ -212,7 +218,7 @@ export async function launchForegroundRun(argv, {
     });
   } catch { telemetryState = "degraded"; }
   const exitCode = result.error ? EXIT.INTERNAL : timedOut ? signalExitCode("SIGTERM") : terminalSignal ? signalExitCode(terminalSignal) : result.exitCode ?? EXIT.INTERNAL;
-  return { exitCode, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome, run_id: runId, telemetry: telemetryState, exit_code: exitCode } };
+  return { exitCode, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome, run_id: runId, telemetry: telemetryState, exit_code: exitCode, ...FOREGROUND_INSPECTION } };
 }
 
 export function terminalStatus({ exitCode, signal, timedOut = false, ownerLost = false }) {
@@ -292,6 +298,7 @@ async function inspectRunEvidence(runId, {
   processAlive = workerProcessGroupAlive,
   receiptFile = receiptPath,
   contextFile = contextPath,
+  remoteTimeoutMs = 3000,
 } = {}) {
   if (typeof runId !== "string" || !runId.trim()) {
     return { schema_version: RUN_SCHEMA_VERSION, classification: "rejected", rerun_safe: false, cancellation_safe: false, error: "run_id_required" };
@@ -310,9 +317,15 @@ async function inspectRunEvidence(runId, {
   // 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);
+  let remoteResult = null, remoteTimer;
+  try {
+    remoteResult = await Promise.race([
+      callWithContextIdentity(context, call)("get_command_run", { run_id: id }, {
+        ...(context ? { serverUrl: contextServerUrl(context) } : {}), signal: AbortSignal.timeout(remoteTimeoutMs),
+      }).catch(() => null),
+      new Promise((resolve) => { remoteTimer = setTimeout(() => resolve(null), remoteTimeoutMs); }),
+    ]);
+  } finally { if (remoteTimer) clearTimeout(remoteTimer); }
   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)
@@ -421,6 +434,124 @@ export async function inspectRun(runId, options = {}) {
     },
   };
 }
+
+function laneProgressFromText(raw) {
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  const { cases, malformed, catalogComplete } = parseLaneEvents(raw, { warn: () => {} });
+  if (malformed !== 0 || (!cases.size && !catalogComplete)) return null;
+  const counts = laneCaseCounts(cases);
+  return { passed: counts.passed, failed: counts.failed, executed: counts.passed + counts.failed, total: catalogComplete ? counts.case_count : null, remaining: catalogComplete ? counts.pending : null, observed_pending: counts.pending, skipped: counts.skipped,
+    reason: catalogComplete ? "complete_reporter_catalog" : "observed_cases_only_catalog_may_be_incomplete" };
+}
+
+/** A compact status for the original owned run. Only count explicit case
+ * events; a partially written catalog does not establish total remaining. */
+export async function statusRun(runId, options = {}) {
+  const inspection = await inspectRun(runId, options);
+  let testCounts = { passed: null, failed: null, executed: null, total: null, remaining: null, reason: "producer_progress_unavailable" };
+  let eventsArgv = null;
+  let logArgv = null;
+  let elapsedSeconds = null;
+  let progressObservedAt = null;
+  if (inspection.classification === "running") {
+    const read = options.read ?? readFile;
+    const contextFile = options.contextFile ?? contextPath;
+    const contextRaw = await read(contextFile(inspection.run_id), "utf8").catch(() => null);
+    const context = typeof contextRaw === "string" ? parseOwnedRunFile(contextRaw, inspection.run_id) : null;
+    const alive = options.processAlive ?? workerProcessGroupAlive;
+    const pids = [context?.worker_pid, context?.workload_pid].filter((pid) => Number.isInteger(pid) && pid > 0);
+    if (context && freshContext(context, options.now ?? Date.now()) && pids.some((pid) => alive(pid))) {
+      const started = Date.parse(context.launched_at ?? "");
+      const observedNow = options.now ?? Date.now();
+      if (Number.isFinite(started) && observedNow >= started) elapsedSeconds = Math.floor((observedNow - started) / 1000);
+      if (typeof context.test_run?.events_path === "string") {
+        const raw = await read(context.test_run.events_path, "utf8").catch(() => null);
+        if (typeof raw === "string") eventsArgv = ["cat", context.test_run.events_path];
+        testCounts = laneProgressFromText(raw) ?? testCounts;
+        if (testCounts.passed !== null) {
+          const info = await (options.stat ?? stat)(context.test_run.events_path).catch(() => null);
+          if (Number.isFinite(info?.mtimeMs) && info.mtimeMs >= 0 && info.mtimeMs <= observedNow) progressObservedAt = new Date(info.mtimeMs).toISOString();
+        }
+      }
+      const logPath = `${contextFile(inspection.run_id)}.live-log.json`;
+      const rawLog = await read(logPath, "utf8").catch(() => null);
+      const log = typeof rawLog === "string" ? parseOwnedRunFile(rawLog, inspection.run_id) : null;
+      if (log && /^[a-f0-9]{64}$/i.test(context.command_hash ?? "") && /^[a-f0-9]{40,64}$/i.test(context.source_sha ?? "") && log.command_hash === context.command_hash && log.source_sha === context.source_sha && typeof log.bounded_log === "string") logArgv = ["cat", logPath];
+    }
+  } else if (inspection.source_bound === true && typeof inspection.local?.receipt_path === "string") {
+    const read = options.read ?? readFile;
+    const raw = await read(inspection.local.receipt_path, "utf8").catch(() => null);
+    const receipt = typeof raw === "string" ? parseOwnedRunFile(raw, inspection.run_id) : null;
+    const start = Date.parse(receipt?.started_at ?? ""), end = Date.parse(receipt?.ended_at ?? "");
+    if (Number.isFinite(start) && Number.isFinite(end) && end >= start) elapsedSeconds = Math.floor((end - start) / 1000);
+    const progress = receipt?.test_counts;
+    if (receipt?.command_hash === inspection.local.command_hash && receipt?.source_sha === inspection.local.source_sha && progress && [progress.passed, progress.failed, progress.observed_pending, progress.skipped].every((n) => Number.isSafeInteger(n) && n >= 0) &&
+      (progress.remaining === null || (Number.isSafeInteger(progress.remaining) && progress.remaining >= 0)) &&
+      ["complete_reporter_catalog", "observed_cases_only_catalog_may_be_incomplete"].includes(progress.reason) &&
+      (progress.reason === "complete_reporter_catalog" ? progress.remaining === progress.observed_pending : progress.remaining === null)) {
+      testCounts = { passed: progress.passed, failed: progress.failed, executed: progress.passed + progress.failed, total: progress.reason === "complete_reporter_catalog" ? progress.passed + progress.failed + progress.observed_pending + progress.skipped : null, remaining: progress.remaining, observed_pending: progress.observed_pending, skipped: progress.skipped, reason: progress.reason };
+    }
+  }
+  const path = inspection.source_bound === true ? inspection.local?.receipt_path : null;
+  const receiptArgv = typeof path === "string" && path.length > 0 ? ["cat", path] : null;
+  const logReadArgv = (logArgv || receiptArgv) && inspection.run_id ? ["bb", "run", "logs", inspection.run_id, "--tail", "100"] : null;
+  const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+  return {
+    schema_version: RUN_SCHEMA_VERSION,
+    run_id: inspection.run_id ?? null,
+    classification: inspection.classification,
+    ...(inspection.error ? { error: inspection.error } : {}),
+    source_bound: inspection.source_bound === true,
+    local: inspection.local ?? null,
+    remote: inspection.remote ?? null,
+    test_counts: testCounts,
+    elapsed_seconds: elapsedSeconds,
+    progress_observed_at: progressObservedAt,
+    current_batch: null,
+    current_batch_reason: "producer_batch_unavailable",
+    counts_basis: testCounts.passed === null ? null : "latest_observed_case_verdicts_retries_may_change",
+    receipt_argv: receiptArgv,
+    receipt_command: receiptArgv ? receiptArgv.map(quote).join(" ") : null,
+    test_events_argv: eventsArgv,
+    test_events_command: eventsArgv ? eventsArgv.map(quote).join(" ") : null,
+    live_log_argv: logArgv,
+    live_log_command: logArgv ? logArgv.map(quote).join(" ") : null,
+    log_read_argv: logReadArgv,
+    log_read_command: logReadArgv ? logReadArgv.map(quote).join(" ") : null,
+    recovery: inspection.recovery,
+  };
+}
+
+/** Read only the original source-bound local snapshot. Remote logs are not
+ * assumed available, and no command is rerun to obtain output. */
+export async function logsRun(runId, { tail = 100, ...options } = {}) {
+  if (!Number.isSafeInteger(tail) || tail < 1 || tail > 1000) return { schema_version: RUN_SCHEMA_VERSION, available: false, error: "invalid_tail", classification: "rejected" };
+  const status = await statusRun(runId, options);
+  const statusArgv = status.run_id ? ["bb", "run", "status", status.run_id] : null;
+  const base = { schema_version: RUN_SCHEMA_VERSION, run_id: status.run_id, status_argv: statusArgv, status_command: statusArgv?.join(" ") ?? null };
+  if (status.classification === "rejected") return { ...base, available: false, classification: "rejected", error: status.error };
+  const path = status.live_log_argv?.[1] ?? status.receipt_argv?.[1];
+  if (!path) return { ...base, available: false, reason: "owned_log_unavailable", remote_logs: "unavailable" };
+  const read = options.read ?? readFile;
+  const raw = await read(path, "utf8").catch(() => null);
+  const snapshot = typeof raw === "string" ? parseOwnedRunFile(raw, status.run_id) : null;
+  let bound = false;
+  if (status.live_log_argv) {
+    const contextFile = options.contextFile ?? contextPath;
+    const contextRaw = await read(contextFile(status.run_id), "utf8").catch(() => null);
+    const context = typeof contextRaw === "string" ? parseOwnedRunFile(contextRaw, status.run_id) : null;
+    const alive = options.processAlive ?? workerProcessGroupAlive;
+    const pids = [context?.worker_pid, context?.workload_pid].filter((pid) => Number.isInteger(pid) && pid > 0);
+    bound = Boolean(context && freshContext(context, options.now ?? Date.now()) && pids.some((pid) => alive(pid)) &&
+      /^[a-f0-9]{64}$/i.test(context.command_hash ?? "") && /^[a-f0-9]{40,64}$/i.test(context.source_sha ?? "") &&
+      snapshot?.command_hash === context.command_hash && snapshot?.source_sha === context.source_sha);
+  } else bound = status.source_bound && snapshot?.command_hash === status.local?.command_hash && snapshot?.source_sha === status.local?.source_sha;
+  if (!bound || typeof snapshot?.bounded_log !== "string") return { ...base, available: false, reason: "owned_log_changed_or_unavailable", remote_logs: "unavailable" };
+  const text = snapshot.bounded_log.slice(-8192);
+  const lines = text ? text.split(/\r?\n/) : [];
+  if (lines.at(-1) === "") lines.pop();
+  return { ...base, available: true, source: status.live_log_argv ? "local_live_snapshot" : "local_terminal_receipt", lines: lines.slice(-tail), truncated: lines.length > tail, remote_logs: "not_read" };
+}
 function cancellationPath(contextFile) { return `${contextFile}.cancelled`; }
 
 async function markCancellation(contextFile, runId) {
@@ -644,6 +775,7 @@ export async function runWorker(contextFile, {
   sleep, now, terminalBudgetMs, startDelivery,
   // BOT-2530: worker liveness lease renewal cadence (tests inject a fake timer).
   workerHeartbeatIntervalMs = WORKER_HEARTBEAT_INTERVAL_MS, setIntervalFn = setInterval,
+  liveLogIntervalMs = 1_000,
 } = {}) {
   const retry = { sleep, now, budgetMs: terminalBudgetMs, startDelivery };
   const context = JSON.parse(await readFile(contextFile, "utf8"));
@@ -653,6 +785,7 @@ export async function runWorker(contextFile, {
   const startedAt = new Date().toISOString();
   let timedOut = false;
   let child;
+  let liveLogTimer;
   let cancellationStateWrite = Promise.resolve();
   let contextWrite = Promise.resolve();
   const persistWorkerContext = (state) => {
@@ -726,6 +859,20 @@ export async function runWorker(contextFile, {
   const capture = boundedCapture();
   child.stdout?.on("data", (chunk) => capture.append(chunk));
   child.stderr?.on("data", (chunk) => capture.append(chunk));
+  // A bounded, mode-0600 snapshot gives the owner an exact local log command
+  // while the detached workload runs. It is advisory; failure to write it
+  // must not stop the workload or replace the terminal receipt.
+  let logWrites = Promise.resolve();
+  let loggedCharacters = -1;
+  const flushLiveLog = () => {
+    if (loggedCharacters === capture.characters) return;
+    loggedCharacters = capture.characters;
+    const snapshot = { run_id: context.run_id, command_hash: context.command_hash ?? null, source_sha: context.source_sha ?? null, observed_at: new Date().toISOString(), bounded_log: capture.output, output_characters: capture.characters };
+    logWrites = logWrites.then(() => writeJson(`${contextFile}.live-log.json`, snapshot)).catch(() => { loggedCharacters = -1; });
+  };
+  flushLiveLog();
+  liveLogTimer = setInterval(flushLiveLog, liveLogIntervalMs);
+  liveLogTimer.unref?.();
     await persistWorkerContext({ workload_pid: child.pid, worker_state: "running" });
   // BOT-1510: for a test lane, tail the reporter's NDJSON and flush per-case
   // verdicts while the child runs. The test process never touches the network.
@@ -739,6 +886,9 @@ export async function runWorker(contextFile, {
     const result = await completion;
     clearTimeout(timer);
     clearTimeout(killTimer);
+    clearInterval(liveLogTimer);
+    flushLiveLog();
+    await logWrites;
     await cancellationStateWrite;
     if (lane) await lane.stop();
     const endedAt = new Date().toISOString();
@@ -750,6 +900,7 @@ export async function runWorker(contextFile, {
     const receipt = await finalize(context, { status, startedAt, endedAt, exitCode: result.exitCode, signal: result.signal, output: capture.output, outputCharacters: capture.characters }, callbackCall, retry);
     return receipt;
   } finally {
+    clearInterval(liveLogTimer);
     if (workerLease) await workerLease.stop();
     if (ownerHeartbeat) await ownerHeartbeat.stop();
     signalEmitter.removeListener("SIGTERM", cancellationHandler);
@@ -1049,6 +1200,11 @@ 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, 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 };
+  if (typeof context.test_run?.events_path === "string") {
+    const events = await readFile(context.test_run.events_path, "utf8").catch(() => null);
+    const progress = laneProgressFromText(events);
+    if (progress) receipt.test_counts = progress;
+  }
   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");
@@ -1132,6 +1288,19 @@ export async function cmdRun(args) {
     process.exitCode = result.classification === "rejected" ? EXIT.INVALID : EXIT.OK;
     return;
   }
+  if (args[0] === "status") {
+    const result = await statusRun(args[1] ?? "");
+    oneLine(result, false);
+    process.exitCode = result.classification === "rejected" ? EXIT.INVALID : EXIT.OK;
+    return;
+  }
+  if (args[0] === "logs") {
+    const valid = args.length === 2 || (args.length === 4 && args[2] === "--tail" && /^(?:[1-9][0-9]{0,2}|1000)$/.test(args[3] ?? ""));
+    const result = valid ? await logsRun(args[1] ?? "", { tail: args.length === 4 ? Number(args[3]) : 100 }) : { schema_version: RUN_SCHEMA_VERSION, available: false, classification: "rejected", error: "invalid_logs_arguments" };
+    oneLine(result, false);
+    process.exitCode = result.classification === "rejected" ? EXIT.INVALID : result.available ? EXIT.OK : EXIT.BACKEND;
+    return;
+  }
   if (args[0] === "cancel") {
     const result = await cancelRun(args[1] ?? "");
     oneLine(result.receipt, false);
@@ -1139,7 +1308,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 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");
+    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 status <run_id>  Show observed counts and exact local log, test-event and receipt commands when available; counts may be unknown. Live logs are bounded private snapshots.\nbotbuddy run logs <run_id> --tail 100  Read the original owned local log snapshot; remote logs may be unavailable.\nbotbuddy run inspect <run_id>  Inspect a detached command run; foreground telemetry IDs use the original terminal receipt.\nbotbuddy run cancel <run_id>\n  bb telemetry status  Check foreground telemetry delivery, not the command outcome.\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

@@ -239,7 +239,9 @@ export async function reportStackRunOutcome({ fields, exitCode, runId, opts, env
     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 };
+    const capture = result?.data?.feedback_capture;
+    const feedbackCapture = result?.ok && !result?.isError && capture?.status === "captured" && typeof capture.feedback_id === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(capture.feedback_id) ? { status: "captured", feedback_id: capture.feedback_id } : result?.ok && !result?.isError && capture?.status === "pending" ? { status: "pending" } : null;
+    return { sent: Boolean(result?.ok && !result?.isError), reason: result?.ok ? null : "refused", payload, ...(feedbackCapture ? { feedback_capture: feedbackCapture } : {}) };
   } catch {
     return { sent: false, reason: "error", payload };
   } finally {

package/src/stack.mjs

@@ -28,6 +28,7 @@
 //     `stop` itself and self-activates/finalizes via the fallback MCP tools.
 
 import { writeLaneStatus } from "./lane-status.mjs";
+import { markFeedbackGuidanceShown } from "./feedback-reminder.mjs";
 import { spawn, spawnSync } from "child_process";
 import { existsSync, lstatSync, readFileSync, realpathSync } from "fs";
 import { open, unlink, readFile } from "fs/promises";
@@ -58,7 +59,7 @@ import { FORWARD_ATTESTATION_ENV, startForwardAttestation, readForwardAttestatio
 import { stackServicesForForwards } from "./stack-service-discovery.mjs";
 import { ENGINE_PUBLISHES_BEYOND_LOOPBACK, engineSocketIsLocal, formatPublishIp, isLoopbackIp, publishIpFix, resolvePublishIp } from "./docker-publish-ip.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
-import { STACK_RELEASE_INTENT_ENV, observeStackRunSignal, ownerReleaseHeld, reportStackRunOutcome } from "./stack-run-outcome.mjs";
+import { STACK_RELEASE_INTENT_ENV, classifyStackRunOutcome, observeStackRunSignal, ownerReleaseHeld, reportStackRunOutcome } from "./stack-run-outcome.mjs";
 
 export const STACK_SCHEMA_VERSION = 1;
 
@@ -149,6 +150,10 @@ const STACK_READINESS_HELP = `${bold("READINESS")}
 
 export const STACK_HELP = `${bold("botbuddy stack")} — one command for a batch-scoped local stack lease (BOT-1218)
 
+If BotBuddy blocks your work, run bb feedback init --file .botbuddy/feedback-report.json,
+fill in the failure and evidence, then run bb feedback submit --file .botbuddy/feedback-report.json.
+Preserve the original lease and do not cancel or repeat it merely to report the problem.
+
 ${bold("USAGE")}
   botbuddy stack up [options]        Request a lease; park if the host is full; hold it active
   botbuddy stack status --admission-request-id <uuid>
@@ -887,7 +892,7 @@ export function truncateReceipt(receipt, maxBytes = DEFAULT_RECEIPT_MAX_BYTES) {
   const r = { ...receipt };
   if (r.connection !== undefined) r.connection = { connection_truncated: true };
   if (enc(r) <= maxBytes) return r;
-  return {
+  const minimal = {
     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,
@@ -896,6 +901,8 @@ export function truncateReceipt(receipt, maxBytes = DEFAULT_RECEIPT_MAX_BYTES) {
     ...(r.cleanup_code ? { cleanup_code: r.cleanup_code } : {}),
     ...(r.cleanup_error ? { cleanup_error: String(r.cleanup_error).slice(0, 160) } : {}),
   };
+  const withFeedback = r.feedback_recovery ? { ...minimal, feedback_recovery: r.feedback_recovery } : minimal;
+  return enc(withFeedback) <= maxBytes ? withFeedback : minimal;
 }
 
 /** Resolve the requested stack directory once, before it leaves the coding
@@ -1442,6 +1449,12 @@ const AGENT_DEEPLINK_REQUIRED_GUIDANCE = "the control plane refused this stack b
 
 /** The refusal text for a receipt: the server's message, else the CLI's guidance, else the code. */
 export function leaseRefusalError(data) {
+  if (data?.code === "STALE_AGENT_CONTEXT") {
+    // These identifiers are shown only in the local receipt; never copy an
+    // arbitrary server string into it or into the separate telemetry envelope.
+    const ticket = (value) => typeof value === "string" && /^[A-Z][A-Z0-9]{1,15}-[0-9]{1,12}$/.test(value) ? value : "unknown";
+    return `STALE_AGENT_CONTEXT: registered ticket ${ticket(data.registered_ticket_id)}; requested ticket ${ticket(data.requested_ticket_id)}. No lease was created. Run \`bb help register_agent\` to inspect the supported session registration options before retrying.`;
+  }
   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\`, ` +
@@ -5326,7 +5339,7 @@ export function runReceiptFields(result) {
  * or the returned exit code.
  */
 export async function cmdRun(opts, childArgv, {
-  lifecycle = runStackLifecycle, report = reportStackRunOutcome, now = Date.now, env = process.env,
+  lifecycle = runStackLifecycle, report = reportStackRunOutcome, now = Date.now, env = process.env, feedbackLog = (message) => process.stderr.write(message), markFeedback = markFeedbackGuidanceShown,
 } = {}) {
   // A caller that needs a wait selects this immutable UUID before dispatch.
   // Ordinary foreground runs still receive a unique telemetry id, but it is not
@@ -5335,9 +5348,23 @@ export async function cmdRun(opts, childArgv, {
   const startedAt = now();
   const result = await lifecycle(opts, childArgv);
   const fields = runReceiptFields(result);
-  const code = emit(buildReceipt(fields), opts, result.exitCode);
+  const receipt = buildReceipt(fields);
+  const failureClass = classifyStackRunOutcome(stackRunOutcomeFields(result), result.exitCode);
+  const feedbackEligible = failureClass.category === "platform" || (failureClass.category === "invocation" && failureClass.code !== "INVALID_ARGUMENTS");
+  if (feedbackEligible) {
+    receipt.feedback_recovery = { status: "not_yet_checked", available_after: "command_exits", recover_command: "bb feedback recover", list_command: "bb call list_feedback" };
+  }
+  const code = emit(receipt, opts, result.exitCode);
   try {
-    await report({ fields: stackRunOutcomeFields(result), exitCode: code, runId, opts, env, durationMs: now() - startedAt, channel: result?.[OUTCOME_CHANNEL] ?? null });
+    const outcome = await report({ fields: stackRunOutcomeFields(result), exitCode: code, runId, opts, env, durationMs: now() - startedAt, channel: result?.[OUTCOME_CHANNEL] ?? null });
+    const capture = outcome?.feedback_capture;
+    if (!opts?.json && capture?.status === "captured" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(capture.feedback_id ?? "")) {
+      feedbackLog(`BotBuddy retained a failure report. Check it: bb feedback status --feedback-id ${capture.feedback_id}\nCreate a private draft: bb feedback init --file bb-feedback.json\nEdit the draft, then add your explanation: bb feedback enrich --feedback-id ${capture.feedback_id} --file bb-feedback.json\n`);
+      markFeedback();
+    } else if (!opts?.json && (capture?.status === "pending" || (outcome?.sent === false && feedbackEligible))) {
+      feedbackLog("Automatic feedback capture was not confirmed and may still complete. Recover using the same identity: bb feedback recover\nThen check existing reports: bb call list_feedback\nIf the source event was not recorded, create a report: bb feedback init --file bb-feedback.json\n");
+      markFeedback();
+    }
   } catch { /* best-effort: the receipt and exit code are already final */ }
   return code;
 }

package/src/test/playwright-reporter.mjs

@@ -68,13 +68,15 @@ export default class BotBuddyPlaywrightReporter {
 
   onBegin(_config, suite) {
     if (!this._path) return;
-    const tests = typeof suite?.allTests === "function" ? suite.allTests() : [];
+    const tests = typeof suite?.allTests === "function" ? suite.allTests() : null;
+    if (!Array.isArray(tests)) return;
     tests.forEach((t, i) => {
       const key = caseKey(t);
       this._order.set(key, i);
       const title = (typeof t?.titlePath === "function" ? t.titlePath() : []).filter(Boolean).join(" › ") || key;
       this._append({ type: "begin", key, title, sort_order: i });
     });
+    this._append({ type: "catalog_complete", case_count: tests.length });
   }
 
   onTestEnd(test, result) {

package/src/test-lane-events.mjs

@@ -14,12 +14,19 @@ export const SYNC_BATCH = 500;
 export function parseLaneEvents(text, { warn = (m) => process.stderr.write(m) } = {}) {
   const cases = new Map();
   let malformed = 0;
+  let catalogComplete = false;
   for (const raw of String(text ?? "").split("\n")) {
     const line = raw.trim();
     if (!line) continue;
     let ev;
     try { ev = JSON.parse(line); } catch { malformed += 1; warn("[botbuddy] skipping corrupt lane event line\n"); continue; }
+    if (ev?.type === "catalog_complete") {
+      catalogComplete = Number.isSafeInteger(ev.case_count) && ev.case_count >= 0 && ev.case_count === cases.size;
+      if (!catalogComplete) malformed += 1;
+      continue;
+    }
     if (!ev || typeof ev.key !== "string" || (ev.type !== "begin" && ev.type !== "verdict")) { malformed += 1; continue; }
+    if (!cases.has(ev.key)) catalogComplete = false;
     const c = cases.get(ev.key) ?? { key: ev.key, title: ev.key, sort_order: cases.size, verdict: "pending", fail_reason: null, duration_ms: null };
     if (typeof ev.title === "string" && ev.title) c.title = ev.title;
     if (Number.isInteger(ev.sort_order)) c.sort_order = ev.sort_order;
@@ -30,7 +37,7 @@ export function parseLaneEvents(text, { warn = (m) => process.stderr.write(m) }
     }
     cases.set(ev.key, c);
   }
-  return { cases, malformed };
+  return { cases, malformed, catalogComplete };
 }
 
 // Case map → the sync_test_run_cases payload, ordered by sort_order.

package/src/wait-feedback-capture.mjs

@@ -0,0 +1,62 @@
+// Retain only the fixed failure code, and only when this exact session token
+// binds to the cached agent and tenant. Replay re-verifies both identities.
+import { randomUUID } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cacheBelongsToHarness, findAgentStateRoot, harnessSessionIdFromEnv, readAgentState } from "./agent-state.mjs";
+import { restrictWindowsAcl, restrictWindowsAclDir } from "./agent-state-fs.mjs";
+import { queueFeedback } from "./feedback-outbox.mjs";
+
+/** @param {any} options */
+export async function captureWaitRegistrationFailure({ token, claim = false, cwd = process.cwd(),
+  loadState = readAgentState, rootFor = findAgentStateRoot, queue = queueFeedback,
+  harnessId = harnessSessionIdFromEnv(), uuid = randomUUID } = {}) {
+  try {
+    const state = await loadState(cwd);
+    if (!state || !cacheBelongsToHarness(state, harnessId) ||
+        typeof token !== "string" || token !== state.agent_session_token ||
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(state.agent_id ?? "") ||
+        !/^[a-z0-9][a-z0-9-]{0,63}$/.test(state.tenant ?? "")) return false;
+    const code = claim ? "claim_registration_failed" : "register_failed";
+    const result = await queue({ root: await rootFor(cwd), agentId: state.agent_id, tenant: state.tenant,
+      report: { idempotency_key: uuid(), kind: "unknown", surface: "wait", impact: "unknown",
+        title: claim ? "Wait claim registration failed" : "Wait registration failed", error_code: code,
+        actual: claim ? "The claim wait could not confirm a registered session." : "The wait could not confirm a registered session.",
+        evidence: [{ type: "text", value: `Wait receipt error: ${code}` }] } });
+    return result?.queued === true;
+  } catch {
+    return false;
+  }
+}
+
+export function captureClaimRegistrationFailure(options = {}) {
+  return captureWaitRegistrationFailure({ ...options, claim: true });
+}
+
+// With no proven reporter binding, save only fixed, non-identifying context.
+// It is never replayed automatically: the agent must review it and choose its
+// authenticated reporter and tenant before submitting.
+export async function saveUnboundWaitDraft({ claim = false, tempRoot = tmpdir() } = {}) {
+  let directory;
+  try {
+    directory = await mkdtemp(join(tempRoot, "bb-feedback-wait-"));
+    if (process.platform === "win32") await restrictWindowsAclDir(directory);
+    const file = join(directory, "report.json");
+    const code = claim ? "claim_registration_failed" : "register_failed";
+    const report = {
+      idempotency_key: randomUUID(), kind: "unknown", surface: "wait", impact: "unknown",
+      title: claim ? "Wait claim registration failed" : "Wait registration failed",
+      error_code: code, goal: "", steps: "", expected: "",
+      actual: claim ? "The claim wait could not confirm a registered session." : "The wait could not confirm a registered session.",
+      blocked_reason: "", blocking_step: "", can_continue: null, safe_next_action: "", ticket_ref: "",
+      evidence: [{ type: "text", value: `Wait receipt error: ${code}` }],
+    };
+    await writeFile(file, `${JSON.stringify(report, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    if (process.platform === "win32") await restrictWindowsAcl(file);
+    return file;
+  } catch {
+    if (directory) await rm(directory, { recursive: true, force: true }).catch(() => {});
+    return null;
+  }
+}

package/src/wait.mjs

@@ -22,6 +22,8 @@ import { AGENT_KEY_RE, readAgentSessionTokenEnv, legacyAgentAliasHint } from "./
 import { clearAgentState, hasAgentSessionRuntime, isRejectedCachedSession, resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
 import { repairFailureRecovery } from "./agent-doctor.mjs";
 import { touchAgentStateExpiry } from "./agent-state.mjs";
+import { captureWaitRegistrationFailure, saveUnboundWaitDraft } from "./wait-feedback-capture.mjs";
+import { markFeedbackGuidanceShown } from "./feedback-reminder.mjs";
 import { SETUP_BLOCK } from "./setup-block.mjs";
 import { createWaitCheckpointStore, WaitCheckpointError } from "./wait-checkpoint.mjs";
 import { realpath } from "node:fs/promises";
@@ -56,6 +58,10 @@ Park until a condition holds, then exit ONCE with one JSON receipt on stdout. Ze
 and zero tokens while parked. Every wait — time included — is a bb wait: never sleep loops,
 until/while polling, watch, or gh run watch. Full guide: docs/agent-wait.md.
 
+If BotBuddy blocks your work, run bb feedback init --file .botbuddy/feedback-report.json,
+fill in the failure and evidence, then run bb feedback submit --file .botbuddy/feedback-report.json.
+Preserve the original wait and do not cancel or repeat it merely to report the problem.
+
 USAGE
   bb wait [--any] <condition>... [options]       arm a wait (also: bb help wait)
   bb wait <subcommand> …                         inspect or recover a saved wait (SUBCOMMANDS)
@@ -902,6 +908,12 @@ async function finalizeWait(opts, waitSessionId, receipt, timeoutMs = 5000) {
       process.stderr.write(`bb-wait: finalize (non-fatal) returned ${res.status}\n`);
       return { delivered: false, error: body?.error || (res.ok ? "finalize_not_applied" : `finalize_http_${res.status}`) };
     }
+    const capture = body?.feedback_capture;
+    if (capture?.status === "captured" && typeof capture.feedback_id === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(capture.feedback_id)) {
+      process.stderr.write(`bb-wait: failure context retained as feedback ${capture.feedback_id}. Create the file, then set kind, surface to wait, title, impact, goal, reproduction, expected and actual outcomes, blocking reason, whether you can continue, safe next action and evidence before enriching:\n  bb feedback init --file .botbuddy/feedback-report.json\n  bb feedback enrich --feedback-id ${capture.feedback_id} --file .botbuddy/feedback-report.json\n`);
+    } else if (capture?.status === "pending") {
+      process.stderr.write("bb-wait: feedback capture is pending. After reconnecting with the same agent and tenant, run: bb feedback recover\n");
+    }
     return { delivered: true };
   } catch (err) {
     process.stderr.write(`bb-wait: finalize (non-fatal) failed: ${err && err.message || err}\n`);
@@ -1619,10 +1631,32 @@ async function sameWorktree(first, second) {
   catch { return false; }
 }
 
+function writeWaitFeedbackGuidance() {
+  markFeedbackGuidanceShown();
+  process.stderr.write("bb-wait: If this error blocks your work, preserve the receipt and report your goal, expected and actual outcomes, why you are blocked and evidence:\n  bb feedback init --file .botbuddy/feedback-report.json\n  bb feedback submit --file .botbuddy/feedback-report.json\nEdit the report before submitting; these instructions do not record feedback. If a partial draft is saved or queued below, use it instead of creating a duplicate. If the file exists, choose a new filename in both commands.\n");
+}
+
+async function preserveWaitRegistrationFeedback(token, claim) {
+  if (await captureWaitRegistrationFailure({ token, claim })) {
+    process.stderr.write("bb-wait: A partial draft was queued for this agent and tenant. Do not submit a duplicate. Reconnect and run:\n  bb feedback flush\nUse the feedback_id from its receipt. Create and edit the details file with your goal, expected and actual outcomes and why you are blocked, then enrich the same report:\n  bb feedback init --file .botbuddy/feedback-details.json\n  bb feedback enrich --feedback-id <feedback_id> --file .botbuddy/feedback-details.json\n");
+    return;
+  }
+  const file = await saveUnboundWaitDraft({ claim });
+  if (!file) {
+    process.stderr.write("bb-wait: Could not save a partial draft. Preserve the receipt and use the feedback init and submit commands above.\n");
+    return;
+  }
+  const quoted = process.platform === "win32"
+    ? `'${file.replace(/'/g, "''")}'`
+    : `'${file.replace(/'/g, "'\\''")}'`;
+  process.stderr.write(`bb-wait: A private partial draft was saved without a verified reporter or tenant. Review and complete ${quoted}; verify the reporter and tenant before submitting. The OS may clear temporary files. Run:\n  bb call whoami\n  bb feedback submit --file ${quoted}\n`);
+}
+
 async function emitSavedWaitError(error) {
   const code = error?.code ?? "wait_checkpoint_invalid";
   const exitCode = code === "wait_checkpoint_write_failed" ? EXIT.INTERNAL : EXIT.INVALID;
   process.stderr.write(`bb-wait: ${error?.message ?? code}\n`);
+  writeWaitFeedbackGuidance();
   await writeWaitReceipt({
     schema_version: 1,
     outcome: "error",
@@ -1835,6 +1869,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   // replayed — carries the lease-lost stderr line when it is a lease_lost terminal.
   const emitReceipt = (receipt, options = {}) => {
     writeLeaseLostNotice(receipt);
+    if (receipt?.outcome === "error") writeWaitFeedbackGuidance();
     return emit(receipt, { ...options, maxBytes: opts.receiptMaxBytes });
   };
   if (opts.help) return writeThenExit(HELP);
@@ -2302,6 +2337,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       if (hasClaim && waitSessionId == null) {
         process.stderr.write("bb-wait: claim=true registration returned no wait_session_id; refusing to arm an unmatchable claim wait\n");
         await emitReceipt({ schema_version: 1, outcome: "error", error: "claim_registration_failed" });
+        await preserveWaitRegistrationFeedback(opts.token, true);
         process.exit(EXIT.INTERNAL);
       }
     } catch (err) {
@@ -2456,6 +2492,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       if (hasClaim) {
         process.stderr.write(`bb-wait: claim=true wait-session registration failed (failing closed, not arming untracked): ${err && err.message || err}\n`);
         await emitReceipt({ schema_version: 1, outcome: "error", error: "claim_registration_failed" });
+        await preserveWaitRegistrationFeedback(opts.token, true);
         process.exit(EXIT.INTERNAL);
       }
       // BOT-1338/1608: every non-timer wait is a relay-tracked, session-token wait.
@@ -2477,6 +2514,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         null,
         { sessionTenant: sessionTenant ?? null, agentId: null },
       ));
+      await preserveWaitRegistrationFeedback(opts.token, false);
       process.exit(EXIT.INTERNAL);
     }
   }
@@ -2584,6 +2622,9 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
     // BOT-2360: likewise `abandoned` — the relay refused the stream because the row is ended.
     if (waitSessionId && !SERVER_ENDED_OUTCOMES.has(receipt.outcome)) {
       const finalized = await finalizeWait(opts, waitSessionId, terminalReceipt);
+      if (!finalized.delivered && terminalReceipt.outcome === "error" && typeof checkpoint.local_wait_id === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(checkpoint.local_wait_id)) {
+        process.stderr.write(`bb-wait: the Wait receipt is saved locally, but cloud finalization was not confirmed. With the same agent and tenant, recover the saved Wait and then recover feedback:\n  bb wait resume ${checkpoint.local_wait_id}\n  bb feedback recover\n`);
+      }
       try {
         checkpoint = await store.update(checkpoint.local_wait_id, finalized.delivered
           ? { cloud_finalize_pending: false, cloud_finalized_at: new Date().toISOString(), cloud_finalize_error: null }