@botbuddy/cli 1.48.0 → 1.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.48.0",
+  "version": "1.50.0",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/commands.mjs

@@ -30,8 +30,10 @@ import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation
 import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
 import { doctorAgentAuth, doctorHelp, parseDoctorArgs, readClientKeyStrict, repairFailureRecovery } from "./agent-doctor.mjs";
 import { formatPublishIp, isLoopbackIp, probeEnginePublishIp, publishIpFix } from "./docker-publish-ip.mjs";
+import { cmdHost, fixHelperWorkers, formatHelperWorkersLines, inspectHelperWorkers } from "./helper-host.mjs";
 import { clearAgentState, selfHealAgentSession } from "./agent-session.mjs";
 import { runUsage, usageStatus } from "./usage/sync.mjs";
+import { cmdTestIngest, doctorTestIngest, formatTestIngestLine } from "./test-ingest.mjs";
 import { installUsageAgent, usageAgentStatus } from "./usage/launchd.mjs";
 
 // BOT-1566 D2: the stale-CLI check runs for every command EXCEPT `wait` and any
@@ -40,7 +42,8 @@ import { installUsageAgent, usageAgentStatus } from "./usage/launchd.mjs";
 // runs inside every `git push` under a 5 s budget.
 export function shouldCheckForUpdates(argv) {
   const [command] = argv;
-  if (command === "wait" || command === "telemetry" || command === "usage") return false;
+  // BOT-1982: nor `test-ingest`, which runs at the tail of every test harness.
+  if (command === "wait" || command === "telemetry" || command === "usage" || command === "test-ingest") return false;
   if (argv.includes("--json")) return false;
   return true;
 }
@@ -83,6 +86,8 @@ export async function run(argv, {
     case "logout": return cmdLogout();
     case "status": return cmdStatus();
     case "doctor": return cmdDoctor(args);
+    // BOT-2367: this Mac's Helper host key, whatever the status file's age.
+    case "host": return cmdHost(args);
     case "update": return cmdUpdate();
     // Agent-only commands (used by MCP agents, not humans)
     case "heartbeat": return cmdHeartbeat(args);
@@ -106,6 +111,7 @@ export async function run(argv, {
       return code;
     }
     case "test": return cmdTest(args);
+    case "test-ingest": return cmdTestIngest(args);
     case "wait": return runWait(args);
     case "pw": return runPw(args);
     case "mcp": return cmdMcp(args);
@@ -188,7 +194,9 @@ ${bold("AUTH")}
   logout                     Remove saved credentials
   status                     Show current auth status (local metadata + server check)
   doctor [--fix] [--print-exports] [--json]
-                             Diagnose or repair the cached agent session
+                             Diagnose or repair the cached agent session; on macOS also
+                             reports duplicate Helper workers (--fix terminates them)
+  host key [--json]          This Mac's Helper host key, whatever the status file's age
 
 ${bold("MCP CONFIG KEY")}
   mcp setup [--env <NAME>] [--tenant <slug>] [--label <l>] [--expiry-days <n>]
@@ -226,6 +234,8 @@ ${bold("DURABLE WORKLOADS")}
                               Run locally with a durable lifecycle outbox
   telemetry <status|replay|doctor>
                               Inspect, replay, or gate durable lifecycle delivery
+  test-ingest --file <payload.json|-> [--tenant <slug>]
+                              Upload a test-run report with this worktree's agent session
 
 ${bold("USAGE INGEST")}
   usage sync [--since 2d] [--provider claude|codex|all] [--file <transcript>] [--dry-run] [--quiet]
@@ -257,6 +267,11 @@ export async function cmdDoctor(args, {
   log = (line) => console.log(line), errorLog = (line) => console.error(line),
   doctor = doctorAgentAuth, usageReport = doctorUsageSync, bootstrapReport = doctorBootstrapState,
   publishReport = () => probeEnginePublishIp(),
+  helperWorkersReport = async () => inspectHelperWorkers(),
+  helperWorkersFix = (report) => fixHelperWorkers(report),
+  // BOT-1982: which credential test-run uploads would use — the ONE place a
+  // missing upload credential is reported (the harnesses skip silently).
+  testIngestReport = () => doctorTestIngest(),
 } = {}) {
   const parsed = parseDoctorArgs(args);
   if (parsed.help) { log(doctorHelp()); return 0; }
@@ -271,8 +286,20 @@ export async function cmdDoctor(args, {
   const usage = await usageReport().catch(() => null);
   // BOT-1945 (AC-3): informational, like usage sync — never changes the exit code.
   const bootstrap = await bootstrapReport().catch(() => null);
+  // BOT-2367: duplicate Helper workers / stale Helper locks (macOS). Reported on
+  // every run; `--fix` SIGTERMs a duplicate launchd is not running, then
+  // re-checks. Informational: never changes doctor's exit code.
+  let helperWorkers = await helperWorkersReport().catch(() => null);
+  let helperFix = null;
+  if (parsed.fix && helperWorkers?.status === "duplicate") {
+    helperFix = await helperWorkersFix(helperWorkers).catch(() => null);
+    const recheck = await helperWorkersReport().catch(() => null);
+    helperWorkers = recheck ? { ...recheck, fix: helperFix } : { ...helperWorkers, fix: helperFix };
+  }
+  // BOT-1982: informational, like usage sync — never changes the exit code.
+  const testIngest = await Promise.resolve().then(testIngestReport).catch(() => null);
   if (parsed.json) {
-    log(JSON.stringify({ ...result.report, ...(usage ? { usage_sync: usage } : {}), ...(bootstrap ? { bootstrap } : {}) }));
+    log(JSON.stringify({ ...result.report, ...(usage ? { usage_sync: usage } : {}), ...(bootstrap ? { bootstrap } : {}), ...(helperWorkers ? { helper_workers: helperWorkers } : {}), ...(testIngest ? { test_ingest: testIngest } : {}) }));
   } else {
     log(`binding: ${result.report.binding.status}${result.report.binding.tenant ? ` (${result.report.binding.tenant})` : ""}`);
     log(`client key: ${result.report.client_key.status}`);
@@ -288,6 +315,8 @@ export async function cmdDoctor(args, {
     if (result.report.recovery) log(`recovery: ${result.report.recovery}`);
     if (bootstrap) log(formatBootstrapLine(bootstrap));
     if (usage) log(formatUsageSyncLine(usage));
+    for (const line of formatHelperWorkersLines(helperWorkers, helperFix)) log(line);
+    if (testIngest) log(formatTestIngestLine(testIngest));
   }
   if (result.exports) log(result.exports);
   return result.exitCode;

package/src/helper-host.mjs

@@ -0,0 +1,223 @@
+// BOT-2367 — this Mac's BotBuddy Helper host key, and the `bb doctor` Helper
+// duplicate-worker / stale-lock check.
+//
+// The Helper writes `managed-container-host-status.json` with this machine's
+// `host_key` and `checked_at` (Apple-epoch seconds; there is no `updated_at`).
+// The host key is derived from the machine's P-256 identity and is static, so
+// it never depends on the file's age: `bb host key` returns it whatever the
+// age and reports freshness separately. On 2026-10-14 a 7-minute Helper job
+// tick aged the file past Supply Guard's 300 s limit on a healthy host and SG
+// refused to name the host (exit 4); Helper 0.2.37 refreshes the file on every
+// beacon, and this command gives wrappers a resolver that cannot fail that way.
+//
+// Read-only except `fixHelperWorkers`, which only SIGTERMs a
+// `botbuddyhelper-worker` process launchd is not running, and only when the
+// launchd PID was read twice and agreed (fail-closed otherwise).
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { basename, join } from "node:path";
+
+export const HELPER_WORKER_LABEL = "com.botbuddy.helper.worker";
+export const HELPER_WORKER_BINARY = "botbuddyhelper-worker";
+/** Supply Guard's freshness limit; Helper 0.2.37 refreshes every ~20 s. */
+export const HELPER_STATUS_FRESH_SECONDS = 300;
+const APPLE_REFERENCE_EPOCH_SECONDS = 978_307_200;
+const HOST_KEY_PATTERN = /^[A-Za-z0-9._:-]+$/;
+const HELPER_LOCK_FILES = [".worker.lock", ".beacon.lock", ".metrics.lock"];
+const START_REMEDY = "start the BotBuddy Helper (open \"BotBuddy Helper.app\") so it writes this file";
+
+export function helperSupportDir(home = homedir()) {
+  return join(home, "Library", "Application Support", "BotBuddyHelper");
+}
+
+export function helperStatusPath(home = homedir()) {
+  return join(helperSupportDir(home), "managed-container-host-status.json");
+}
+
+/**
+ * `{ ok: true, host_key, checked_at, age_seconds, fresh, path }`, or
+ * `{ ok: false, code, path, message }` when the file is missing or names no
+ * well-formed host key. Freshness never decides whether the key is returned.
+ */
+export function readHelperHostKey({ home = homedir(), nowMs = Date.now(), readFile = (p) => readFileSync(p, "utf8") } = {}) {
+  const path = helperStatusPath(home);
+  let contents;
+  try {
+    contents = readFile(path);
+  } catch (error) {
+    return { ok: false, code: "HELPER_STATUS_MISSING", path, message: `could not read ${path} (${error?.code ?? "unreadable"}); ${START_REMEDY}` };
+  }
+  let status;
+  try {
+    status = JSON.parse(contents);
+  } catch {
+    status = null;
+  }
+  const hostKey = status?.host_key;
+  if (typeof hostKey !== "string" || !HOST_KEY_PATTERN.test(hostKey)) {
+    return { ok: false, code: "HELPER_STATUS_MALFORMED", path, message: `${path} names no well-formed host_key; ${START_REMEDY}` };
+  }
+  const checkedAt = status.checked_at;
+  if (!Number.isFinite(checkedAt)) {
+    return { ok: true, host_key: hostKey, checked_at: null, age_seconds: null, fresh: false, path };
+  }
+  const checkedAtMs = (checkedAt + APPLE_REFERENCE_EPOCH_SECONDS) * 1000;
+  const ageSeconds = Math.round((nowMs - checkedAtMs) / 1000);
+  return {
+    ok: true,
+    host_key: hostKey,
+    checked_at: new Date(checkedAtMs).toISOString(),
+    age_seconds: ageSeconds,
+    fresh: ageSeconds >= -60 && ageSeconds <= HELPER_STATUS_FRESH_SECONDS,
+    path,
+  };
+}
+
+const HOST_USAGE = "Usage: bb host key [--json]";
+
+export function hostHelp() {
+  return `${HOST_USAGE}
+
+Prints this Mac's managed-container host key from the BotBuddy Helper's status
+file, whatever the file's age: the key is this machine's static identity. A file
+older than ${HELPER_STATUS_FRESH_SECONDS} s still prints the key (exit 0) with a freshness warning on
+stderr. Exit 4 when the file is missing or names no host key.
+--json prints {host_key, checked_at, age_seconds, fresh, path}.`;
+}
+
+/** `bb host key [--json]` → exit code. */
+export async function cmdHost(args, {
+  log = (line) => console.log(line), errorLog = (line) => console.error(line),
+  read = () => readHelperHostKey(),
+} = {}) {
+  const [sub, ...rest] = args;
+  if (sub === "help" || sub === "--help" || sub === "-h") { log(hostHelp()); return 0; }
+  const json = rest.includes("--json");
+  const unknown = rest.filter((a) => a !== "--json");
+  if (sub !== "key" || unknown.length) { errorLog(HOST_USAGE); return 4; }
+  const r = read();
+  if (!r.ok) {
+    errorLog(`bb host key: ${r.code}: ${r.message}`);
+    return 4;
+  }
+  if (json) {
+    log(JSON.stringify({ host_key: r.host_key, checked_at: r.checked_at, age_seconds: r.age_seconds, fresh: r.fresh, path: r.path }));
+  } else {
+    log(r.host_key);
+  }
+  if (!r.fresh) {
+    const age = r.age_seconds == null ? "has no checked_at" : `is ${r.age_seconds} s old`;
+    errorLog(`bb host key: warning: the Helper status file ${age} (fresh is ≤ ${HELPER_STATUS_FRESH_SECONDS} s); the key is still this Mac's. ` +
+      `If the Helper is not running, check \`launchctl print gui/$(id -u)/${HELPER_WORKER_LABEL}\` and the worker log.`);
+  }
+  return 0;
+}
+
+// ── bb doctor: duplicate Helper workers and stale Helper locks ───────────────
+
+function defaultRun(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 5000 });
+  return { status: r.error ? null : r.status, stdout: r.stdout ?? "" };
+}
+
+/** `launchctl list <label>` → pid number, null (loaded, not running), or undefined (unreadable). */
+export function parseLaunchctlListPid(result) {
+  if (!result || result.status !== 0) return undefined;
+  const m = /"PID"\s*=\s*(\d+)\s*;/.exec(result.stdout);
+  return m ? Number(m[1]) : null;
+}
+
+/** `ps -axo pid=,comm=` → the pids of `botbuddyhelper-worker` processes. */
+export function parseWorkerPids(stdout) {
+  const pids = [];
+  for (const line of String(stdout).split("\n")) {
+    const m = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
+    if (m && basename(m[2]) === HELPER_WORKER_BINARY) pids.push(Number(m[1]));
+  }
+  return pids.sort((a, b) => a - b);
+}
+
+/** `lsof -F pcn` → Helper lock files held open by a process that is not a Helper process. */
+export function parseStaleLocks(stdout) {
+  const stale = [];
+  let pid = null; let command = null;
+  for (const line of String(stdout).split("\n")) {
+    const tag = line[0]; const value = line.slice(1);
+    if (tag === "p") { pid = Number(value); command = null; }
+    else if (tag === "c") command = value;
+    else if (tag === "n") {
+      const file = basename(value);
+      if (HELPER_LOCK_FILES.includes(file) && !/^botbuddyhelper/i.test(command ?? "")) {
+        stale.push({ file, pid, command });
+      }
+    }
+  }
+  return stale;
+}
+
+/**
+ * Read-only census of Helper worker processes against launchd's own job PID.
+ * A duplicate is a `botbuddyhelper-worker` launchd is not running. The launchd
+ * PID is read before and after `ps`; if launchd's answer is unreadable or
+ * changed (a tick started mid-check), nothing is called a duplicate.
+ */
+export function inspectHelperWorkers({ run = defaultRun, home = homedir(), platformFn = platform } = {}) {
+  if (platformFn() !== "darwin") return null;
+  const before = parseLaunchctlListPid(run("launchctl", ["list", HELPER_WORKER_LABEL]));
+  const workers = parseWorkerPids(run("ps", ["-axo", "pid=,comm="]).stdout);
+  const after = parseLaunchctlListPid(run("launchctl", ["list", HELPER_WORKER_LABEL]));
+  const lockPaths = HELPER_LOCK_FILES.map((f) => join(helperSupportDir(home), f));
+  const lsof = run("lsof", ["+c", "0", "-F", "pcn", ...lockPaths]);
+  const staleLocks = parseStaleLocks(lsof.stdout);
+  const base = { launchd_pid: after ?? null, workers, duplicates: [], stale_locks: staleLocks };
+  if (before === undefined || after === undefined) {
+    return { status: "unknown", ...base, reason: `launchd job ${HELPER_WORKER_LABEL} is not readable in this session` };
+  }
+  if (before !== after) return { status: "unsettled", ...base, reason: "launchd started a worker tick during the check" };
+  const duplicates = workers.filter((pid) => pid !== after);
+  return { status: duplicates.length ? "duplicate" : "ok", ...base, duplicates };
+}
+
+function defaultIsAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === "EPERM"; }
+}
+
+/** SIGTERM each duplicate (never launchd's worker); wait up to ~3 s for exit. */
+export async function fixHelperWorkers(report, {
+  kill = (pid, signal) => process.kill(pid, signal), isAlive = defaultIsAlive,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+} = {}) {
+  const result = { terminated: [], failed: [] };
+  if (report?.status !== "duplicate") return result;
+  for (const pid of report.duplicates) {
+    if (pid === report.launchd_pid) continue;
+    try { kill(pid, "SIGTERM"); } catch { /* already gone or not ours; checked below */ }
+  }
+  for (let i = 0; i < 30 && report.duplicates.some((pid) => isAlive(pid)); i++) await sleep(100);
+  for (const pid of report.duplicates) (isAlive(pid) ? result.failed : result.terminated).push(pid);
+  return result;
+}
+
+/** Human lines for `bb doctor`. */
+export function formatHelperWorkersLines(report, fix = null) {
+  if (!report) return [];
+  const lines = [];
+  const launchd = report.launchd_pid ? `launchd ${HELPER_WORKER_LABEL} pid ${report.launchd_pid}` : `launchd ${HELPER_WORKER_LABEL} idle between ticks`;
+  if (fix && (fix.terminated.length || fix.failed.length)) {
+    // A re-checked report (cmdDoctor attaches `fix`) already lists the survivors.
+    const running = report.fix ? report.workers.length : report.workers.length - fix.terminated.length;
+    for (const pid of fix.terminated) lines.push(`helper workers: terminated duplicate pid ${pid}; ${running} running (${launchd})`);
+    for (const pid of fix.failed) lines.push(`helper workers: could not terminate duplicate pid ${pid}; stop it with \`kill ${pid}\``);
+  } else if (report.status === "ok") {
+    lines.push(`helper workers: ${report.workers.length} running (${launchd})`);
+  } else if (report.status === "duplicate") {
+    lines.push(`helper workers: ${report.workers.length} running — duplicate pid ${report.duplicates.join(", ")} (${launchd}); fix: \`bb doctor --fix\` terminates the duplicate`);
+  } else {
+    lines.push(`helper workers: ${report.workers.length} running — ${report.reason}; not checked for duplicates${report.status === "unsettled" ? " (re-run bb doctor)" : ""}`);
+  }
+  for (const s of report.stale_locks) {
+    lines.push(`helper lock: ${s.file} is held open by pid ${s.pid} (${s.command}), not a Helper process, so the Helper cannot take it; stop pid ${s.pid}`);
+  }
+  return lines;
+}

package/src/test-ingest.mjs

@@ -0,0 +1,224 @@
+// BOT-1982 — upload a test-run payload to the `test-ingest` edge function with
+// THIS worktree's credential. One resolver + one transport, shared by
+// `bb test-ingest` (tenant repos' harnesses call the binary) and this repo's
+// pre-push reporter (scripts/report-test-runs.mjs imports the module).
+//
+// Why an ordered candidate list with 401 fall-through: the old reporters sent the
+// FIRST exported key, so a dead legacy `BOTBUDDY_API_KEY` left in a shell profile
+// shadowed a valid key and every upload 401'd. Now the worktree's agent session
+// (`bb setup`) is preferred, the durable keys follow, the legacy exports come
+// last, and a 401 tries the next candidate — a stale credential can never shadow
+// a valid one. A missing credential is NOT reported per run: callers stay silent
+// and `bb doctor` reports it once (doctorTestIngest).
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { promisify } from "node:util";
+import { isAgentStateFresh, readAgentState } from "./agent-state.mjs";
+import { readAgentSessionTokenEnv } from "./agent-key.mjs";
+import { readKeychainSecret } from "./agent-credential-store.mjs";
+import { resolveAgentBinding } from "./wait-profile.mjs";
+
+const execFileP = promisify(execFile);
+export const DEFAULT_TEST_INGEST_URL = "https://api.bot-buddy.ai/functions/v1/test-ingest";
+export const DEFAULT_TIMEOUT_MS = 5_000;
+export const EXIT_DELIVERED = 0;
+export const EXIT_NO_CREDENTIAL = 3;
+export const EXIT_NOT_DELIVERED = 5;
+export const TEST_INGEST_FIX = "run `bb setup` in this worktree (or `bb doctor --fix`) so test-run uploads use its agent session";
+
+/** test-ingest URL: explicit → functions base → derived from the MCP server URL. */
+export function testIngestEndpoint(env = process.env) {
+  if (env.BOTBUDDY_TEST_INGEST_URL) return env.BOTBUDDY_TEST_INGEST_URL;
+  if (env.BOTBUDDY_FUNCTIONS_URL) return `${env.BOTBUDDY_FUNCTIONS_URL.replace(/\/+$/, "")}/test-ingest`;
+  if (env.BOTBUDDY_SERVER_URL) {
+    const url = new URL(env.BOTBUDDY_SERVER_URL);
+    url.pathname = url.pathname.replace(/\/mcp-server\/?$/, "/test-ingest");
+    return url.toString();
+  }
+  return DEFAULT_TEST_INGEST_URL;
+}
+
+// A time-bounded Keychain read: a locked/prompting Keychain must never hang a push.
+async function boundedKeychainRead(service, timeoutMs = 3_000) {
+  if (process.platform !== "darwin") return null;
+  const bounded = (cmd, args) => execFileP(cmd, args, { timeout: timeoutMs, killSignal: "SIGKILL" });
+  return readKeychainSecret(service, { execFileImpl: bounded });
+}
+
+async function bindingKey({ cwd, env, readCredential }) {
+  try {
+    const { token, tokenEnv } = await resolveAgentBinding({ cwd, env, readCredential });
+    return token ? { token, source: "mcp_key", env: tokenEnv } : null;
+  } catch {
+    return null; // no/malformed binding → no binding key; never throws into a push
+  }
+}
+
+/**
+ * Ordered, de-duplicated credential candidates `{ token, source }` (never logged):
+ *   1. BOTBUDDY_TEST_INGEST_KEY — an explicit override (CI's dedicated key)
+ *   2. the agent session — BOTBUDDY_AGENT_SESSION_TOKEN, else this worktree's
+ *      FRESH .botbuddy/agent-state.json (an expired cache is never offered or
+ *      advertised by `bb doctor`; offline, no self-heal registration from a hook)
+ *   3. the binding's tier-2 MCP key (env, else a bounded Keychain read)
+ *   4. legacy BOTBUDDY_API_KEY / BOTBUDDY_BB_AGENT_KEY — last, so a stale export
+ *      can never shadow a valid credential
+ */
+export async function resolveTestIngestCredentials({
+  env = process.env, cwd = process.cwd(), readState = readAgentState, isFresh = isAgentStateFresh,
+  readCredential = async (name, e) => (typeof e[name] === "string" && e[name].trim()) || (await boundedKeychainRead(name)),
+} = {}) {
+  const out = [];
+  const add = (token, source) => {
+    const value = typeof token === "string" ? token.trim() : "";
+    if (value && !out.some((c) => c.token === value)) out.push({ token: value, source });
+  };
+  add(env.BOTBUDDY_TEST_INGEST_KEY, "explicit");
+  add(readAgentSessionTokenEnv(env), "session_env");
+  try {
+    const state = await readState(cwd);
+    if (state?.agent_session_token && isFresh(state, new Date())) add(state.agent_session_token, "session");
+  } catch { /* unreadable cache = no session candidate */ }
+  const key = await bindingKey({ cwd, env, readCredential });
+  if (key) add(key.token, key.source);
+  add(env.BOTBUDDY_API_KEY, "legacy_api_key");
+  add(env.BOTBUDDY_BB_AGENT_KEY, "legacy_agent_key");
+  return out;
+}
+
+async function postOnce({ url, token, payload, fetchImpl, timeoutMs }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: typeof payload === "string" ? payload : JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    const text = res.text ? await res.text().catch(() => "") : "";
+    let body = null;
+    try { body = text ? JSON.parse(text) : null; } catch { body = null; }
+    return { status: res.status, ok: res.ok, text, body };
+  } catch (error) {
+    return { status: null, ok: false, error: controller.signal.aborted ? `timed out after ${timeoutMs}ms` : (error?.message ?? String(error)) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * POST `payload` with the first candidate test-ingest accepts. Only a 401 moves to
+ * the next candidate (any other answer is the server's verdict on the payload).
+ * Returns a token-free receipt:
+ *   { ok:true, status, source, attempts, summary, errors, deep_link }
+ *   { ok:false, code:"credential_missing", attempts:[] }
+ *   { ok:false, code:"ingest_errors", status, source, attempts, summary, errors }  (200 + row errors)
+ *   { ok:false, code:"rejected"|"unreachable", status, source, attempts, error }
+ */
+export async function uploadTestRun({
+  payload, url = testIngestEndpoint(), credentials, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  const candidates = Array.isArray(credentials) ? credentials : [];
+  if (candidates.length === 0) return { ok: false, code: "credential_missing", attempts: [] };
+  const attempts = [];
+  let last = null;
+  for (const candidate of candidates) {
+    const res = await postOnce({ url, token: candidate.token, payload, fetchImpl, timeoutMs });
+    attempts.push({ source: candidate.source, status: res.status });
+    last = { ...res, source: candidate.source };
+    if (res.status === 401) continue;
+    break;
+  }
+  if (last.ok) {
+    const summary = last.body?.summary ?? null;
+    const errors = Array.isArray(summary?.errors) ? summary.errors : [];
+    // test-ingest answers 200 with summary.errors for permanent per-row write
+    // failures: the request was accepted but rows are missing, so it is NOT a
+    // delivery (the harness must not treat it as one and drop its results).
+    if (errors.length > 0) {
+      return { ok: false, code: "ingest_errors", status: last.status, source: last.source, attempts, summary, errors, deep_link: last.body?.deep_link ?? null };
+    }
+    return { ok: true, status: last.status, source: last.source, attempts, summary, errors, deep_link: last.body?.deep_link ?? null };
+  }
+  if (last.status === null) return { ok: false, code: "unreachable", status: null, source: last.source, attempts, error: last.error };
+  const message = last.body?.error ?? last.body?.message ?? String(last.text ?? "").slice(0, 200);
+  return { ok: false, code: "rejected", status: last.status, source: last.source, attempts, error: message || `http_${last.status}` };
+}
+
+/** `bb doctor` line for test-run uploads: which credential would be tried first. */
+export async function doctorTestIngest(opts = {}) {
+  const candidates = await resolveTestIngestCredentials(opts);
+  if (candidates.length === 0) return { status: "missing", fix: TEST_INGEST_FIX };
+  return { status: "available", source: candidates[0].source, candidates: candidates.map((c) => c.source) };
+}
+
+export function formatTestIngestLine(report) {
+  if (!report) return null;
+  return report.status === "available"
+    ? `test-run upload: available (${report.source})`
+    : `test-run upload: MISSING — ${report.fix}`;
+}
+
+export function parseTestIngestArgs(argv = []) {
+  const args = { file: null, tenant: null, timeoutMs: null, help: false, errors: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const value = () => {
+      const v = argv[i + 1];
+      if (v === undefined || (v.startsWith("--") && v !== "-")) { args.errors.push(`${a} requires a value`); return null; }
+      i++;
+      return v;
+    };
+    if (a === "--help" || a === "-h" || a === "help") args.help = true;
+    else if (a === "--file") args.file = value();
+    else if (a === "--tenant") args.tenant = value();
+    else if (a === "--timeout-ms") {
+      const v = value();
+      if (v !== null) { const n = Number(v); if (Number.isInteger(n) && n > 0) args.timeoutMs = n; else args.errors.push("--timeout-ms must be a positive integer"); }
+    } else args.errors.push(`unknown argument ${a}`);
+  }
+  if (!args.help && !args.file) args.errors.push("--file <path|-> is required");
+  return args;
+}
+
+export function testIngestHelp() {
+  return [
+    "bb test-ingest --file <payload.json|-> [--tenant <slug>] [--timeout-ms <n>]",
+    "",
+    "POSTs a test-run payload ({ executions: [...] }, or a raw vitest/playwright --reporter=json",
+    "report plus context fields) to BotBuddy's test-ingest with this worktree's credential:",
+    "BOTBUDDY_TEST_INGEST_KEY → agent session (bb setup) → the binding's MCP key → legacy exports.",
+    "A 401 tries the next credential. Prints one JSON receipt (never a secret).",
+    "Exit 0 delivered · 3 no credential (see `bb doctor`) · 5 rejected, unreachable, or accepted with row errors.",
+  ].join("\n");
+}
+
+export async function cmdTestIngest(argv, {
+  env = process.env, cwd = process.cwd(), log = (l) => console.log(l), errorLog = (l) => console.error(l),
+  readStdin = () => readFileSync(0, "utf8"), readFile = (p) => readFileSync(p, "utf8"),
+  resolveCredentials = resolveTestIngestCredentials, upload = uploadTestRun,
+} = {}) {
+  const args = parseTestIngestArgs(argv);
+  if (args.help) { log(testIngestHelp()); return 0; }
+  if (args.errors.length) { errorLog(`bb test-ingest: ${args.errors.join("; ")}`); return 2; }
+  let payload;
+  try {
+    payload = JSON.parse(args.file === "-" ? readStdin() : readFile(args.file));
+  } catch (error) {
+    errorLog(`bb test-ingest: cannot read a JSON payload from ${args.file}: ${error?.message ?? error}`);
+    return 2;
+  }
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    errorLog("bb test-ingest: the payload must be a JSON object");
+    return 2;
+  }
+  if (args.tenant && !payload.tenant) payload.tenant = args.tenant;
+  const credentials = await resolveCredentials({ env, cwd });
+  const receipt = await upload({
+    payload, credentials, url: testIngestEndpoint(env), timeoutMs: args.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  });
+  log(JSON.stringify(receipt));
+  if (receipt.ok) return EXIT_DELIVERED;
+  return receipt.code === "credential_missing" ? EXIT_NO_CREDENTIAL : EXIT_NOT_DELIVERED;
+}