@botbuddy/cli 1.64.13 → 1.64.15

package/src/feedback.mjs

@@ -0,0 +1,269 @@
+// BOT-2887: explicit feedback submission. The caller's file is the durable
+// retry source; the idempotency key must be inside it before the first send.
+import { lstat, mkdir, open, readFile, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { CALL_EXIT, callToolJson, resolveCallAuth } from "./api.mjs";
+import { containsFeedbackSecret } from "./feedback-safety.mjs";
+import { restrictWindowsAcl, restrictWindowsAclDir, sessionPathIsConfidential } from "./agent-state-fs.mjs";
+import { cacheBelongsToHarness, findAgentStateRoot, harnessSessionIdFromEnv, readAgentState } from "./agent-state.mjs";
+import { hasPendingFeedback, queueFeedback, withFeedbackOutbox } from "./feedback-outbox.mjs";
+import { CONDITION_TYPES } from "./wait-core.mjs";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const OPTIONAL_TEXT = new Set(["goal", "steps", "expected", "actual", "blocked_reason", "blocking_step", "safe_next_action", "environment", "operation", "component_version", "error_code", "correlation_id", "workaround", "cause_confidence", "ticket_ref"]);
+const USAGE = `Usage: bb feedback init --file <report.json>
+       bb feedback init --file <report.json> --from-run <run_id>
+       bb feedback submit --file <report.json>
+       bb feedback enrich --feedback-id <id> --file <report.json>
+       bb feedback status --feedback-id <id>
+       bb feedback updates --feedback-id <id> [--after <revision>]
+       bb feedback acknowledge --feedback-id <id> --revision <revision>
+       bb feedback flush
+       bb feedback recover
+
+init creates a private starter file without overwriting an existing file.
+--from-run adds an exact status command and a bounded status observation from
+the original command run. It never copies raw logs or restarts the workload.
+Fill in the fields before submitting it. The JSON report must contain a stable
+UUID idempotency_key, kind, surface, title and impact. Set kind to bug,
+feature_request, improvement, friction, docs_gap or unknown; surface to mcp, cli, stack,
+wait, web, helper, docs or other; and impact to blocked, workaround, slowed,
+cosmetic or unknown. Unknown values keep the report in needs_context. Include your goal, steps, expected and actual outcomes,
+evidence, why you are blocked and what you can safely do next. Keep the file
+and its idempotency_key unchanged if delivery is uncertain; retry using the
+same reporter and tenant. Tenant identity sharing follows the server's policy;
+a report cannot override it.
+
+An unavailable service does not mean a report was recorded. A failed send is
+queued privately only when the original agent and tenant can be bound to the
+cached session. Run bb feedback flush to replay those drafts after reconnecting.
+Unbound drafts stay in their original file for a deliberate retry.`;
+
+export async function cmdFeedback(args, { call = callToolJson, resolveAuth = resolveCallAuth, read = readFile, write = writeFile, makeDir = mkdir, uuid = randomUUID, inspectStatus = async (id) => (await import("./run.mjs")).statusRun(id), cwd = process.cwd(), loadState = readAgentState, rootFor = findAgentStateRoot, queue = queueFeedback, outbox = withFeedbackOutbox, hasPending = hasPendingFeedback, waitTypes = CONDITION_TYPES, platform = process.platform, restrictAcl = restrictWindowsAcl, restrictAclDir = restrictWindowsAclDir, confidential = sessionPathIsConfidential, log = console.log, errorLog = console.error } = {}) {
+  if (args.length === 1 && ["help", "--help", "-h"].includes(args[0])) { log(USAGE); return CALL_EXIT.OK; }
+  const cachedBinding = async (resolved) => {
+    const state = await loadState(cwd);
+    if (!state || !cacheBelongsToHarness(state, harnessSessionIdFromEnv()) || resolved?.sessionToken !== true ||
+        resolved.auth?.["x-agent-api-key"] !== state.agent_session_token || !UUID.test(state.agent_id ?? "") ||
+        !/^[a-z0-9][a-z0-9-]{0,63}$/.test(state.tenant ?? "")) return null;
+    return { agentId: state.agent_id, tenant: state.tenant };
+  };
+  if (args.length === 1 && args[0] === "flush") {
+    let delivered = 0;
+    const receipts = [];
+    const remember = (id) => { delivered++; receipts.push({ feedback_id: id, status_command: `bb feedback status --feedback-id ${id}`, updates_command: `bb feedback updates --feedback-id ${id}` }); };
+    try {
+      const resolved = await resolveAuth({ toolName: "submit_feedback", preferSession: true });
+      const binding = await cachedBinding(resolved);
+      if (!binding) { errorLog("Feedback replay requires the original worktree's bound agent session and tenant. Drafts remain queued."); return CALL_EXIT.AUTH; }
+      const identity = await call("whoami", {}, { auth: resolved.auth, signal: AbortSignal.timeout(15_000) });
+      if (!identity?.ok || identity.isError || identity.data?.credential_kind !== "agent_session" || identity.data?.agent?.id !== binding.agentId || identity.data?.tenant_id !== binding.tenant) {
+        errorLog("Feedback replay could not verify the original reporter and tenant. Drafts remain queued."); return CALL_EXIT.AUTH;
+      }
+      const root = await rootFor(cwd);
+      const result = await outbox(root, async (items, io) => {
+        for (const item of items) {
+          const record = await io.read(item);
+          if (record.agent_id !== binding.agentId || record.tenant !== binding.tenant) return { ok: false, error: "outbox_identity_mismatch", delivered, receipts, remaining: true };
+          const response = await call("submit_feedback", record.report, { auth: resolved.auth, signal: AbortSignal.timeout(15_000) });
+          const data = response?.data;
+          if (response?.ok && !response.isError && (response.status == null || (response.status >= 200 && response.status < 300)) && data?.ok === true && data.source_duplicate === true && typeof data.feedback_id === "string" && UUID.test(data.feedback_id)) {
+            const current = await call("get_feedback", { feedback_id: data.feedback_id }, { auth: resolved.auth, signal: AbortSignal.timeout(15_000) });
+            const intended = Object.entries(record.report).filter(([key]) => key !== "idempotency_key");
+            if (current?.ok && !current.isError && (current.status == null || (current.status >= 200 && current.status < 300)) && current.data?.ok === true && current.data.feedback_id === data.feedback_id &&
+                current.data.report && intended.every(([key, value]) => isDeepStrictEqual(current.data.report[key], value))) {
+              remember(data.feedback_id); await io.remove(item); continue;
+            }
+            const draft = await io.exportDraft(record);
+            const argv = ["bb", "feedback", "enrich", "--feedback-id", data.feedback_id, "--file", draft];
+            return { ok: false, error: "source_already_reported", delivered, receipts, remaining: true, feedback_id: data.feedback_id,
+              status_command: `bb feedback status --feedback-id ${data.feedback_id}`, enrich_argv: argv,
+              enrich_command: argv.map((value) => `'${value.replaceAll("'", "'\\''")}'`).join(" ") };
+          }
+          if (!response?.ok || response.isError || (response.status != null && (response.status < 200 || response.status >= 300)) || data?.ok !== true ||
+              typeof data.feedback_id !== "string" || !UUID.test(data.feedback_id) || typeof data.occurrence_id !== "string" || !UUID.test(data.occurrence_id) || !["complete", "needs_context"].includes(data.capture_state)) {
+            return { ok: false, error: "delivery_unconfirmed", delivered, receipts, remaining: true,
+              ...(typeof data?.feedback_id === "string" && UUID.test(data.feedback_id) ? { feedback_id: data.feedback_id, status_command: `bb feedback status --feedback-id ${data.feedback_id}` } : {}) };
+          }
+          remember(data.feedback_id);
+          await io.remove(item);
+        }
+        return { ok: true, delivered, receipts, remaining: io.more, ...(io.more ? { continue_command: "bb feedback flush" } : {}) };
+      });
+      log(JSON.stringify(result));
+      if (!result.ok) errorLog("Feedback replay stopped without deleting the unconfirmed draft.");
+      return result.ok ? CALL_EXIT.OK : CALL_EXIT.ERROR;
+    } catch {
+      log(JSON.stringify({ ok: false, error: "replay_unavailable", delivered, receipts, remaining: true, retry_command: "bb feedback flush" }));
+      errorLog("Feedback replay stopped. Check the receipts and retry: bb feedback flush");
+      return CALL_EXIT.ERROR;
+    }
+  }
+  if (args.length === 1 && args[0] === "recover") {
+    let outboxRecovery = null;
+    try {
+      if (await hasPending(await rootFor(cwd))) {
+        let receipt = null;
+        const code = await cmdFeedback(["flush"], { call, resolveAuth, read, write, makeDir, uuid, inspectStatus, cwd, loadState, rootFor, queue, outbox, hasPending,
+          log: (line) => { try { receipt = JSON.parse(line); } catch { /* retain unknown */ } }, errorLog: () => {} });
+        outboxRecovery = { ok: code === 0 && receipt?.ok === true, delivered: receipt?.delivered ?? null, receipts: receipt?.receipts ?? null,
+          remaining: code !== 0 || receipt?.remaining === true, ...(code !== 0 || receipt?.remaining === true ? { retry_command: "bb feedback flush" } : {}),
+          ...(receipt?.error === "source_already_reported" ? { error: receipt.error, feedback_id: receipt.feedback_id, status_command: receipt.status_command, enrich_argv: receipt.enrich_argv, enrich_command: receipt.enrich_command } : {}) };
+      }
+    } catch { outboxRecovery = { ok: false, delivered: null, receipts: null, remaining: true, retry_command: "bb feedback flush" }; }
+    let result;
+    try {
+      const resolved = await resolveAuth({ toolName: "recover_feedback_sources", preferSession: true });
+      result = resolved?.error || !resolved?.auth ? { ok: false, auth: true } : await call("recover_feedback_sources", {}, { auth: resolved.auth, signal: AbortSignal.timeout(15_000) });
+    } catch { result = { ok: false, status: null }; }
+    const data = result?.data;
+    if (!result?.ok || (result.status != null && (result.status < 200 || result.status >= 300)) || result.isError || data?.ok !== true || !Number.isInteger(data.captured) || data.captured < 0 || data.captured > 5 || typeof data.complete !== "boolean" || !["none", "more_sources", "retry_later"].includes(data.remaining) || data.complete !== (data.remaining === "none")) {
+      if (outboxRecovery) log(JSON.stringify({ ok: false, cloud_recovery: "unconfirmed", outbox_recovery: outboxRecovery, all_complete: false, retry_command: "bb feedback recover" }));
+      errorLog("Feedback recovery was not confirmed. Preserve the original run; retry bb feedback recover using the same reporter and tenant.");
+      return result?.auth ? CALL_EXIT.AUTH : !result?.ok && result?.status == null ? CALL_EXIT.TRANSPORT : CALL_EXIT.ERROR;
+    }
+    log(JSON.stringify({ ...data, ...(outboxRecovery ? { outbox_recovery: outboxRecovery, all_complete: data.complete && outboxRecovery.ok && !outboxRecovery.remaining } : {}), list_command: "bb call list_feedback", ...(data.remaining === "more_sources" ? { continue_command: "bb feedback recover" } : {}), ...(data.remaining === "retry_later" ? { retry_command: "bb feedback recover" } : {}) }));
+    return outboxRecovery && !outboxRecovery.ok ? CALL_EXIT.ERROR : CALL_EXIT.OK;
+  }
+  if (["status", "updates", "acknowledge"].includes(args[0])) {
+    const kind = args[0];
+    const validId = args[1] === "--feedback-id" && UUID.test(args[2] ?? "");
+    const cursorText = args[4];
+    const validCursor = typeof cursorText === "string" && /^(0|[1-9][0-9]*)$/.test(cursorText) && Number.isSafeInteger(Number(cursorText)) && Number(cursorText) <= 2147483647;
+    const valid = validId && (kind === "status" ? args.length === 3 : kind === "updates" ? args.length === 3 || (args.length === 5 && args[3] === "--after" && validCursor) : args.length === 5 && args[3] === "--revision" && validCursor && Number(cursorText) > 0);
+    if (!valid) { errorLog(USAGE); return 2; }
+    const tool = kind === "status" ? "get_feedback" : kind === "updates" ? "list_feedback_updates" : "acknowledge_feedback_update";
+    const input = { feedback_id: args[2], ...(kind === "updates" && args.length === 5 ? { after_revision: Number(cursorText) } : {}), ...(kind === "acknowledge" ? { revision: Number(cursorText) } : {}) };
+    let result;
+    try {
+      const resolved = await resolveAuth({ toolName: tool, preferSession: true });
+      result = resolved?.error || !resolved?.auth ? { ok: false, auth: true } : await call(tool, input, { auth: resolved.auth, signal: AbortSignal.timeout(15_000) });
+    } catch { result = { ok: false, status: null }; }
+    const data = result?.data;
+    const receiptValid = data?.ok === true && typeof data.feedback_id === "string" && data.feedback_id.toLowerCase() === args[2].toLowerCase() && (kind === "status" || (kind === "updates" ? Array.isArray(data.items) && data.items.every((item) => Number.isInteger(item?.revision) && item.revision > 0 && item.revision <= 2147483647) && typeof data.has_more === "boolean" && Number.isInteger(data.next_after_revision) && data.next_after_revision >= 0 && data.next_after_revision <= 2147483647 : data.revision === Number(cursorText) && typeof data.acknowledged_at === "string"));
+    if (!result?.ok || (result.status != null && (result.status < 200 || result.status >= 300)) || result.isError || !receiptValid) {
+      errorLog(kind === "acknowledge" ? "Acknowledgement was not confirmed; check updates before retrying." : "Feedback status is unavailable; retry using the same reporter and tenant.");
+      return result?.auth ? CALL_EXIT.AUTH : !result?.ok && result?.status == null ? CALL_EXIT.TRANSPORT : CALL_EXIT.ERROR;
+    }
+    if (kind === "updates") {
+      const items = data.items.map((item) => ({ ...item, acknowledge_command: `bb feedback acknowledge --feedback-id ${args[2]} --revision ${item.revision}` }));
+      const next = data.has_more ? `bb feedback updates --feedback-id ${args[2]} --after ${data.next_after_revision}` : null;
+      const waitCommand = !data.has_more && waitTypes.includes("feedback") ? `bb wait 'feedback:id=${args[2].toLowerCase()},after=${data.next_after_revision}'` : null;
+      log(JSON.stringify({ ...data, items, next_command: next, ...(waitCommand ? { after_consuming_wait_command: waitCommand } : {}) }));
+    } else log(JSON.stringify(data));
+    return CALL_EXIT.OK;
+  }
+  const enrich = args.length === 5 && args[0] === "enrich" && args[1] === "--feedback-id" && UUID.test(args[2] ?? "") && args[3] === "--file";
+  const fromRun = args.length === 5 && args[0] === "init" && args[1] === "--file" && args[3] === "--from-run" && RUN_ID.test(args[4] ?? "");
+  const filename = enrich ? args[4] : args[2];
+  if ((!enrich && !fromRun && (args.length !== 3 || !["init", "submit"].includes(args[0]) || args[1] !== "--file")) || !filename || filename.startsWith("-")) {
+    errorLog(USAGE); return 2;
+  }
+  if (args[0] === "init") {
+    const template = { idempotency_key: uuid(), kind: "", surface: "", title: "", impact: "", goal: "", steps: "", expected: "", actual: "", blocked_reason: "", blocking_step: "", can_continue: null, safe_next_action: "", ticket_ref: "", evidence: [] };
+    if (fromRun) {
+      let status;
+      try { status = await inspectStatus(args[4]); } catch { errorLog("The original run status is unavailable; no feedback file was created. Preserve the original run and retry."); return CALL_EXIT.TRANSPORT; }
+      const allowed = ["running", "completed", "completed_locally_remote_conflict", "completed_locally_remote_stale", "completed_locally_remote_unknown", "unknown"];
+      if (!status || status.run_id !== args[4] || !allowed.includes(status.classification)) { errorLog("The original run status could not be verified; no feedback file was created."); return CALL_EXIT.ERROR; }
+      template.surface = "cli";
+      template.operation = "bb run";
+      template.correlation_id = args[4];
+      const local = status.local;
+      const localOutcome = status.source_bound === true && ["success", "failure", "timed_out", "interrupted", "cancelled"].includes(local?.status)
+        ? ` Local outcome: ${local.status}${Number.isSafeInteger(local.exit_code) && local.exit_code >= 0 && local.exit_code <= 255 ? ` (exit ${local.exit_code})` : ""}.`
+        : "";
+      template.actual = `Original command run status: ${status.classification}.${localOutcome}`;
+      template.evidence = [{ type: "command", value: `bb run status ${args[4]}` }];
+      const counts = status.test_counts;
+      if (counts && typeof counts === "object" && [counts.passed, counts.failed, counts.remaining].every((value) => value === null || (Number.isSafeInteger(value) && value >= 0)) && (counts.passed !== null || counts.failed !== null)) {
+        template.evidence.push({ type: "text", value: `Observed test counts: passed=${counts.passed ?? "unknown"}, failed=${counts.failed ?? "unknown"}, remaining=${counts.remaining ?? "unknown"}. Counts are observations and retries may change them.` });
+      }
+    }
+    if (platform === "win32") {
+      // A mode bit does not protect Windows files. The parent must be private
+      // before path-based ACL checks, so another user cannot replace the file.
+      // Do not change ACLs of an existing user-selected directory.
+      let handle, created = false;
+      try {
+        const parent = dirname(filename);
+        const made = await makeDir(parent, { recursive: true, mode: 0o700 });
+        if (made) await restrictAclDir(parent);
+        const info = await lstat(parent);
+        if (!info.isDirectory() || info.isSymbolicLink() || !(await confidential(parent, info.mode, { platform }))) throw new Error("directory_not_private");
+        handle = await open(filename, "wx", 0o600); created = true;
+        await restrictAcl(filename);
+        const fileInfo = await handle.stat();
+        if (!(await confidential(filename, fileInfo.mode, { platform }))) throw new Error("file_not_private");
+        await handle.writeFile(JSON.stringify(template, null, 2) + "\n");
+        await handle.sync();
+        await handle.close(); handle = null;
+      } catch {
+        if (handle) await handle.close().catch(() => {});
+        if (created) await unlink(filename).catch(() => {});
+        const retryPath = join(".botbuddy", `feedback-${template.idempotency_key}`, "report.json");
+        const retry = `bb feedback init --file "${retryPath}"${fromRun ? ` --from-run ${args[4]}` : ""}`;
+        errorLog(`Could not create a private feedback file. Existing files are never overwritten. Retry in a new private directory: ${retry}`); return 2;
+      }
+    } else {
+      try { await makeDir(dirname(filename), { recursive: true, mode: 0o700 }); await write(filename, JSON.stringify(template, null, 2) + "\n", { flag: "wx", mode: 0o600 }); }
+      catch { errorLog("Could not create the feedback file; an existing file is never overwritten."); return 2; }
+    }
+    const argv = ["bb", "feedback", "submit", "--file", filename];
+    log(JSON.stringify({ ok: true, file: filename, state: "needs_context", submit_argv: argv, submit_command: argv.map((value) => `'${value.replaceAll("'", "'\\''")}'`).join(" ") }));
+    return CALL_EXIT.OK;
+  }
+  let report;
+  try { report = JSON.parse(await read(filename, "utf8")); }
+  catch { errorLog("Could not read the feedback file as JSON; the file was not submitted."); return 2; }
+  if (!report || typeof report !== "object" || Array.isArray(report) || typeof report.idempotency_key !== "string" || !UUID.test(report.idempotency_key)) {
+    errorLog("The feedback file must contain a stable UUID idempotency_key; the file was not submitted."); return 2;
+  }
+  // Blank template slots represent missing context. The server accepts omitted
+  // fields for partial capture, but rejects explicitly blank strings.
+  report = Object.fromEntries(Object.entries(report).filter(([key, value]) => !(OPTIONAL_TEXT.has(key) && typeof value === "string" && !value.trim()) && !(key === "can_continue" && value === null)));
+  if (containsFeedbackSecret(report)) {
+    errorLog("The feedback file contains a possible credential, sensitive header or signed URL; remove it before sending.");
+    return 2;
+  }
+  let result, resolved;
+  const tool = enrich ? "enrich_feedback" : "submit_feedback";
+  const patch = { ...report };
+  delete patch.idempotency_key;
+  try {
+    resolved = await resolveAuth({ toolName: tool, preferSession: true });
+    result = resolved?.error || !resolved?.auth ? { ok: false, auth: true, error: "not_authenticated" } : await call(tool, enrich ? { feedback_id: args[2], patch } : report, { auth: resolved.auth, signal: AbortSignal.timeout(15_000) });
+  }
+  catch { result = { ok: false, status: null, error: "transport_unavailable" }; }
+  if (!result?.ok || (result.status != null && (result.status < 200 || result.status >= 300)) || result.isError || result.data?.ok !== true || typeof result.data.feedback_id !== "string" || !UUID.test(result.data.feedback_id) ||
+      typeof result.data.occurrence_id !== "string" || !UUID.test(result.data.occurrence_id) || !["complete", "needs_context"].includes(result.data.capture_state)) {
+    const reported = result?.auth ? "authentication_failed" : result?.data?.error ?? result?.code ?? result?.error;
+    const code = typeof reported === "string" && /^[A-Za-z0-9_.:-]{1,80}$/.test(reported) ? reported : "feedback_receipt_unavailable";
+    const retryArgv = enrich ? null : ["bb", "feedback", "submit", "--file", filename];
+    const retryCommand = retryArgv ? retryArgv.map((value) => `'${value.replaceAll("'", "'\\''")}'`).join(" ") : null;
+    const existingId = code === "source_already_reported" && typeof result?.data?.existing_feedback_id === "string" && UUID.test(result.data.existing_feedback_id) ? result.data.existing_feedback_id : null;
+    const existingEnrichArgv = existingId ? ["bb", "feedback", "enrich", "--feedback-id", existingId, "--file", filename] : null;
+    let queued = null, outboxReason = null;
+    if (!enrich && !result?.auth && !result?.isError && (result?.status == null || result.status >= 500)) {
+      try { const binding = await cachedBinding(resolved); if (binding) queued = await queue({ root: await rootFor(cwd), ...binding, report }); else outboxReason = "reporter_identity_unavailable"; }
+      catch (error) { outboxReason = typeof error?.message === "string" && /^outbox_[a-z_]+$/.test(error.message) ? error.message : "outbox_unavailable"; }
+    }
+    log(JSON.stringify({ ok: false, error: code, recorded: existingId ? "not_changed" : "unknown", retry_source: filename, retry_argv: retryArgv, retry_command: retryCommand,
+      ...(queued ? { queued_locally: true, flush_command: queued.flush_command } : {}),
+      ...(outboxReason ? { queued_locally: false, outbox_reason: outboxReason } : {}),
+      ...(existingEnrichArgv ? { existing_feedback_id: existingId, enrich_argv: existingEnrichArgv, enrich_command: existingEnrichArgv.map((value) => `'${value.replaceAll("'", "'\\''")}'`).join(" ") } : {}),
+      ...(result?.auth ? { diagnostic_argv: ["bb", "doctor"], diagnostic_command: "bb doctor" } : {}) }));
+    errorLog(existingId ? "This source already has another report. The update was not applied; use the exact enrich command in the receipt to update that report." : enrich ? "The update was not confirmed. Read the feedback before deciding whether to apply it again." : "Feedback was not confirmed. Preserve the file and idempotency_key; retry using the same reporter and tenant.");
+    return result?.auth ? CALL_EXIT.AUTH : !result?.ok && result?.status == null ? CALL_EXIT.TRANSPORT : CALL_EXIT.ERROR;
+  }
+  const sourceDuplicate = result.data.source_duplicate === true && result.data.submitted_context_saved === false;
+  const enrichArgv = result.data.capture_state === "needs_context" || sourceDuplicate ? ["bb", "feedback", "enrich", "--feedback-id", result.data.feedback_id, "--file", filename] : null;
+  const statusArgv = ["bb", "feedback", "status", "--feedback-id", result.data.feedback_id];
+  const updatesArgv = ["bb", "feedback", "updates", "--feedback-id", result.data.feedback_id];
+  log(JSON.stringify({ ...result.data, ...(sourceDuplicate ? { ok: false, error: "source_already_reported" } : {}), status_argv: statusArgv, status_command: statusArgv.join(" "), updates_argv: updatesArgv, updates_command: updatesArgv.join(" "), ...(enrichArgv ? { enrich_argv: enrichArgv, enrich_command: enrichArgv.map((value) => `'${value.replaceAll("'", "'\\''")}'`).join(" ") } : {}) }));
+  if (sourceDuplicate) errorLog("This source already has feedback. The new file was not applied; use the exact enrich command in the receipt to add its context to the existing report.");
+  return sourceDuplicate ? CALL_EXIT.ERROR : CALL_EXIT.OK;
+}

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 {