@botbuddy/cli 1.64.13 → 1.64.15

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-core.mjs

@@ -225,6 +225,17 @@ const VALIDATORS = {
     if (!CANONICAL_UUID_RE.test(jobId)) throw new Error("staging-pool-refill id must be a canonical UUID");
     return { jobId };
   },
+  // BOT-2888: a reporter waits for a revision after the last consumed update.
+  // The server binds the report to the registering agent and tenant.
+  feedback: (p, raw) => {
+    const match = /^\s*id\s*=\s*([0-9A-Fa-f-]+)\s*,\s*after\s*=\s*(0|[1-9][0-9]*)\s*$/.exec(raw ?? "");
+    if (!match || Object.keys(p).length !== 2 || p.id !== match[1] || String(p.after) !== match[2]) {
+      throw new Error("feedback needs exactly id=<feedback UUID>,after=<last consumed revision>");
+    }
+    const feedbackId = match[1].toLowerCase(), after = Number(match[2]);
+    if (!CANONICAL_UUID_RE.test(feedbackId) || !Number.isSafeInteger(after)) throw new Error("feedback requires a canonical UUID and safe nonnegative revision");
+    return { feedbackId, after };
+  },
   // BOT-2629: this is deliberately a dedicated condition rather than a raw
   // event escape hatch. The UUID is chosen before dispatch and the exact subject
   // prevents another run on the same idle/re-adopted lease waking this waiter.
@@ -1309,6 +1320,11 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
         signal.subject_key === `staging-pool-refill:${params.jobId}` &&
         signal.payload?.job_id === params.jobId &&
         ["completed", "failed"].includes(signal.payload?.status);
+    case "feedback":
+      return signal.signal_type === "feedback_update" &&
+        signal.subject_key === `feedback:${params.feedbackId}` &&
+        signal.payload?.feedback_id === params.feedbackId &&
+        Number.isSafeInteger(signal.payload?.revision) && signal.payload.revision > params.after;
     case "stack-run":
       return signal.signal_type === "stack_run" && signal.subject_key === `stack-run:${params.id}` &&
         signal.payload?.run_id === params.id && Number.isInteger(signal.payload?.exit_code);
@@ -1523,6 +1539,7 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
 export function signalTenantBlocked(signal, sessionTenant) {
   if (sessionTenant === undefined) return false;
   if (signal.tenant_id == null) return false;
+  if (signal.signal_type === "feedback_update") return signal.tenant_id !== sessionTenant;
   // Mirror the relay's precedence (recipient > owner > tenant): a signal that is
   // owner- or recipient-scoped keeps THAT isolation and is never tenant-fenced, even
   // though owner-scoped pr_review/ci_run also carry a tenant_id — otherwise a caller who

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)
@@ -169,6 +175,9 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       completed or failed. This is the only condition of its
                                       wait and is available to each tenant agent that requested
                                       the deduped job; its terminal receipt is safe to display.
+  feedback:id=<feedback UUID>,after=<revision>
+                                      Wait for a later update to your own feedback; use the
+                                      revision you last consumed and read/acknowledge updates.
   stack-run:id=<run UUID>             one named bb stack run reaching its terminal outcome
                                       (BOT-2629). Choose the UUID BEFORE dispatch and pass it as
                                       bb stack run --run-id <UUID>; the receipt carries exit_code,
@@ -654,6 +663,7 @@ async function registerWait(opts, conditions, deadlineIso) {
       "command_run_single_condition_required",
       "staging_pool_refill_unavailable",
       "staging_pool_refill_single_condition_required",
+      "feedback_wait_unavailable",
     ]);
     if (INVALID_CONDITION_CODES.has(body.error)) {
       const err = new Error(body.detail || body.error);
@@ -902,6 +912,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 +1635,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 +1873,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 +2341,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 +2496,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 +2518,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 +2626,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 }