@botbuddy/cli 1.64.12 → 1.64.14

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/locks.mjs

@@ -152,3 +152,108 @@ export function buildAcquireResourcesPayload(args, options = {}) {
     ...(environment ? { environment } : {}),
   };
 }
+
+// BOT-2994: `bb lock`, `bb locks` and `bb unlock` exit by what the server did, not
+// by whether it answered. Before this every one of them exited 0, so a shell loop
+// that trusted the exit code drove another agent's Playwright lane (ENT-6416).
+// 0 = acquired (or released / withdrawn); 2 = queued behind a holder (you hold
+// nothing yet; wait for the grant or withdraw); 1 = refused or not understood.
+// Auth (3) and transport (5) exits from callTool pass through unchanged.
+export const LOCK_EXIT = Object.freeze({ ACQUIRED: 0, REFUSED: 1, QUEUED: 2 });
+
+function parseJson(text) {
+  try { return JSON.parse(text); } catch { return undefined; }
+}
+
+function toolText(response) {
+  const content = response?.result?.content;
+  if (!Array.isArray(content)) return null;
+  const text = content.map((part) => part?.text ?? "").join("\n");
+  return text || null;
+}
+
+/**
+ * Classify a lock tool response (acquire_lock, acquire_resources, release_lock,
+ * retire_queued_lock_attempt) as returned by callTool: the JSON-RPC body, or a
+ * numeric exit when callTool already classified an auth/transport failure.
+ * Fails closed: an error flag, `success: false`, or an unreadable result is
+ * never "acquired".
+ */
+export function classifyLockResponse(response) {
+  if (typeof response === "number") return { exit: response, results: [] };
+  const isError = response?.result?.isError === true;
+  const text = toolText(response);
+  if (text === null) return { exit: LOCK_EXIT.REFUSED, results: [] };
+  const parsed = parseJson(text);
+  let results;
+  if (parsed && Array.isArray(parsed.results)) {
+    results = parsed.results.map((r) => ({ ...r, success: r?.success === true }));
+  } else if (parsed && typeof parsed === "object" && "success" in parsed) {
+    results = [{ ...parsed, resource_name: parsed.resource_name ?? parsed.resource, success: parsed.success === true && !isError }];
+  } else {
+    // The human success string (acquire_lock / release_lock) or a plain error text.
+    results = [{ success: !isError, message: text }];
+  }
+  const failed = results.filter((r) => !r.success);
+  let exit = LOCK_EXIT.ACQUIRED;
+  if (failed.some((r) => r.queued !== true)) exit = LOCK_EXIT.REFUSED;
+  else if (failed.length) exit = LOCK_EXIT.QUEUED;
+  else if (isError || !results.length) exit = LOCK_EXIT.REFUSED;
+  return { exit, results };
+}
+
+function holderLabel(holder) {
+  if (!holder || typeof holder !== "object") return null;
+  const who = holder.agent ?? holder.agent_name ?? holder.name ?? null;
+  if (!who) return null;
+  const ticket = holder.ticket_id ? `, ${holder.ticket_id}` : "";
+  return `${who}${ticket}`;
+}
+
+// `bb wait 'lock:…,claim=true'` only addresses typed resources
+// (`<subtype>:<host>:<slot>`); an untyped name gets no wait line.
+function claimWaitFor(name) {
+  const parts = typeof name === "string" ? name.split(":") : [];
+  if (parts.length !== 3 || parts.some((p) => !p)) return null;
+  const [subtype, host, slot] = parts;
+  return `bb wait 'lock:subtype=${subtype},host=${host},slot=${slot},claim=true' --heartbeat`;
+}
+
+/** The stderr lines that tell the caller what it holds and what to do next. */
+export function lockOutcomeLines({ exit, results }) {
+  if (exit === LOCK_EXIT.ACQUIRED || exit > LOCK_EXIT.QUEUED) return [];
+  const lines = [`✗ Lock not acquired (exit ${exit}: ${exit === LOCK_EXIT.QUEUED ? "queued" : "refused"}). Do not use ${results.length > 1 ? "these resources" : "this resource"} until a lock command exits 0.`];
+  for (const r of results.filter((x) => !x.success)) {
+    const name = r.resource_name ?? r.resource ?? "resource";
+    const holder = holderLabel(r.holder);
+    if (r.queued === true) {
+      lines.push(`  ${name}: queued${holder ? ` behind ${holder}` : ""}${r.queue_depth != null ? ` (queue depth ${r.queue_depth})` : ""}.`);
+      const wait = claimWaitFor(name);
+      if (wait) lines.push(`    wait to be handed it:  ${wait}`);
+      if (r.resource_id && r.resource_lock_id) lines.push(`    or withdraw the request: bb unlock --queued ${r.resource_id} ${r.resource_lock_id}`);
+    } else {
+      lines.push(`  ${name}: refused${holder ? ` (held by ${holder})` : ""}${r.message ? ` — ${r.message}` : ""}`);
+    }
+  }
+  const held = results.filter((r) => r.success && r.resource_name);
+  if (held.length && results.length > 1) {
+    lines.push("  Acquired in this batch (release what you will not use):");
+    for (const r of held) lines.push(`    bb unlock ${r.resource_name}`);
+  }
+  return lines;
+}
+
+/** `bb unlock` refused: say how a queued caller withdraws instead. */
+export function unlockOutcomeLines({ exit, results }, { queued = false } = {}) {
+  if (exit === LOCK_EXIT.ACQUIRED || exit > LOCK_EXIT.QUEUED) return [];
+  // The first line is the server's reason; later lines are generic guidance.
+  const why = results.find((r) => r.message)?.message?.split("\n")[0];
+  if (queued) return [`✗ Queued request not withdrawn${why ? `: ${why}` : ""}.`];
+  return [
+    `✗ Lock not released${why ? `: ${why}` : ""}.`,
+    "  bb unlock <name> releases a lock you hold; it does not withdraw a queued request.",
+    "  To withdraw one, use the ids from the queued lock result: bb unlock --queued <resource_id> <resource_lock_id>",
+  ];
+}
+
+export const UNLOCK_QUEUED_USAGE = "Usage: botbuddy unlock --queued <resource_id> <resource_lock_id>";

package/src/pw/run.mjs

@@ -92,7 +92,7 @@ async function gate({ env, host, lane, deps }) {
     // callerIds/holder let staging-auth cleanup touch only what this caller installed.
     const callerIds = [...selfAgentIds];
     if (status.held && selfAgentIds.has(status.heldBy)) return { allowed: true, coordinator, canonicalHost, holderMatch: "self", holder: status.heldBy, callerIds };
-    if (status.held && status.ownerIsCaller === true) return { allowed: true, coordinator, canonicalHost, holderMatch: "owner", holder: status.heldBy ?? null, callerIds };
+    if (status.held && status.ownerIsCaller === true) return { allowed: true, coordinator, canonicalHost, holderMatch: "owner", holder: status.heldBy ?? null, holderName: status.heldByName ?? null, callerIds };
     // Distinguish an expired/free lane from one another operator holds so the
     // operator knows whether to re-acquire vs. wait for a handover (BOT-660). Name it
     // by the server's canonical host so a not-held message matches the dashboard even
@@ -296,6 +296,23 @@ async function runPwInner(argv, deps = {}) {
   // Report the host the lock service actually stored (alias-collapsed), so the
   // status view and lane telemetry match the server, not the local string (AC-4).
   const effHost = auth.canonicalHost ?? host;
+  // BOT-2994: a lane is driven only by the agent that holds it. The gate also
+  // passes a same-owner holder (BOT-1490 owner_is_caller), and every agent one
+  // person runs shares that owner, so an agent whose `bb lock` had only queued
+  // drove another agent's browser (ENT-6416, 2026-11-03). Resolve an owner-only
+  // match to the exact agent once (server whoami); only read-only `status` may
+  // proceed without it. `auth` keeps its own staging refusal receipt below.
+  let holderMatch = auth.holderMatch;
+  if (holderMatch === "owner" && auth.holder && authCtx.resolveCallerId) {
+    const me = await authCtx.resolveCallerId().catch(() => null);
+    if (me && me === auth.holder) { holderMatch = "self"; authCtx.callerIds = [...authCtx.callerIds, me]; }
+  }
+  if (holderMatch === "owner" && plan.mode !== "status" && plan.mode !== "auth") {
+    const lane = `playwright_lane:${effHost}:${plan.lane}`;
+    const who = `${auth.holder ?? "unknown"}${auth.holderName ? ` (${auth.holderName})` : ""}`;
+    stderr.write(`bb-pw: lane lock ${lane} is held by ${who}, another agent session of your owner, not this agent session. A lane is driven only by the agent that holds it. Claim a lane from this session with bb locks -m --lane <n> --ticket <ticket> and use it only after that exits 0, or wait to be handed this one: bb wait 'lock:subtype=playwright_lane,host=${effHost},slot=${plan.lane},claim=true' --heartbeat\n`);
+    return 3;
+  }
   // BOT-1318: resolve the lane's browser-acceptance tracker AFTER the gate (a
   // refused/unverified lane writes no lifecycle) and never for unlocked local mode.
   let tracker = null;
@@ -312,11 +329,6 @@ async function runPwInner(argv, deps = {}) {
   if (tracker && envResolution.error) { stderr.write(`${envResolution.error}\n`); return 2; }
   const environment = envResolution.environment ?? null;
   if (plan.mode === "auth") {
-    let holderMatch = auth.holderMatch;
-    if (holderMatch === "owner" && auth.holder && authCtx.resolveCallerId) {
-      const me = await authCtx.resolveCallerId().catch(() => null);
-      if (me && me === auth.holder) { holderMatch = "self"; authCtx.callerIds = [...authCtx.callerIds, me]; }
-    }
     if (holderMatch !== "self") return stagingAuth.refuse({ stdout, stderr }, "exact_lane_holder_required", 3, {}, authVars(plan, deps));
     if (tracker) {
       const browserSession = await tracker.status();