@botbuddy/cli 1.26.0 → 1.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.26.0",
+  "version": "1.28.0",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
   },
   "exports": {
     "./playwright-reporter": "./src/test/playwright-reporter.mjs",
+    "./telemetry": "./src/telemetry-outbox.mjs",
     "./package.json": "./package.json"
   },
   "files": [

package/src/commands.mjs

@@ -12,19 +12,23 @@ import { cmdDocker } from "./docker-hygiene.mjs";
 import { cmdRun } from "./run.mjs";
 import { cmdTest } from "./test-lane.mjs";
 import { runWait } from "./wait.mjs";
+import { SETUP_BLOCK } from "./setup-block.mjs";
 import { green, red, cyan, dim, bold, die } from "./utils.mjs";
 import { VERSION } from "./version.mjs";
 import { setupMcpKey, revokeMcpKey, resolveMcpConfigKey, resolveEnvVarName, DEFAULT_MCP_ENV_VAR, McpKeyError, McpKeyStoreError } from "./mcp-key.mjs";
 import { readAgentBinding } from "./wait-profile.mjs";
 import { runPw } from "./pw/run.mjs";
 import { maybeWarnStale, cmdUpdate } from "./update-check.mjs";
+import { createTelemetryOutbox } from "./telemetry-outbox.mjs";
+import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation } from "./telemetry-config.mjs";
+import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
 
 // BOT-1566 D2: the stale-CLI check runs for every command EXCEPT `wait` and any
 // invocation carrying `--json` — those are hot paths whose receipts (BOT-1229)
 // must not pay for a registry round-trip.
 export function shouldCheckForUpdates(argv) {
   const [command] = argv;
-  if (command === "wait") return false;
+  if (command === "wait" || command === "telemetry") return false;
   if (argv.includes("--json")) return false;
   return true;
 }
@@ -53,6 +57,7 @@ export async function run(argv, {
     case "stack": return cmdStack(args);
     case "docker": return cmdDocker(args);
     case "run": return cmdRun(args);
+    case "telemetry": return cmdTelemetry(args);
     case "test": return cmdTest(args);
     case "wait": return runWait(args);
     case "pw": return runPw(args);
@@ -80,8 +85,38 @@ export async function run(argv, {
   }
 }
 
-function cmdHelp() {
-  console.log(`${bold("bb")} ${dim(`v${VERSION}`)} — Swarm coordination CLI
+async function cmdTelemetry(args) {
+  const subcommand = args[0] ?? "help";
+  if (!new Set(["status", "replay", "doctor", "help", "--help"]).has(subcommand) || args.length > 1) {
+    die("Usage: botbuddy telemetry <status|replay|doctor>");
+  }
+  if (subcommand === "help" || subcommand === "--help") {
+    console.log("botbuddy telemetry status\nbotbuddy telemetry replay\nbotbuddy telemetry doctor");
+    return;
+  }
+  let location;
+  try { location = await loadTelemetryLocation(process.cwd()); }
+  catch (error) { console.error(`telemetry: ${error?.message ?? error}`); return 4; }
+  const outbox = await createTelemetryOutbox({ tenant: location.tenant, repository: location.repository, producerVersion: VERSION });
+  if (subcommand === "replay") {
+    let identity;
+    try {
+      identity = await loadTelemetryIdentity(process.cwd());
+      await attestTelemetryCredential(identity, outbox);
+    } catch (error) { console.error(`telemetry: ${error?.message ?? error}`); return 4; }
+    await outbox.importLegacyTestRunReceipts(".botbuddy/test-runs");
+    const receipt = await outbox.replay((event) => deliverExecutionEvent(event, { credential: identity.credential }));
+    console.log(JSON.stringify(receipt));
+    return receipt.remaining === 0 ? 0 : 5;
+  }
+  const status = await outbox.status();
+  console.log(JSON.stringify(status));
+  if (subcommand === "doctor") return status.queued_count === 0 && !status.last_error_class ? 0 : 5;
+  return 0;
+}
+
+export function cmdHelp(log = console.log) {
+  log(`${bold("bb")} ${dim(`v${VERSION}`)} — Swarm coordination CLI
 
 ${dim(`Run everything as ${cyan("bb <command>")} — the short, preferred alias. ${cyan("botbuddy <command>")} is the identical long form.`)}
 
@@ -132,6 +167,10 @@ ${bold("DOCKER HYGIENE")}
 ${bold("DURABLE WORKLOADS")}
   run --session-id <id> --environment <env> -- <command>
                               Launch a receipt-bearing command under a detached owner
+  run --foreground --kind <kind> --environment <env> -- <command>
+                              Run locally with a durable lifecycle outbox
+  telemetry <status|replay|doctor>
+                              Inspect, replay, or gate durable lifecycle delivery
 
 ${bold("AGENT WAITS")}
   wait [--any] <condition>... [options]
@@ -146,7 +185,9 @@ ${bold("OTHER")}
   locks -m [--host name]    Reserve typed local resources, including Playwright MCP lanes
   update                     Install the latest @botbuddy/cli in the background via npm
   help                       Show this help
-  version                    Show version`);
+  version                    Show version
+
+${SETUP_BLOCK}`);
 }
 
 // ─── BOT-876: generic tool access ───────────────────────────────
@@ -287,8 +328,8 @@ async function cmdLogin(args, { errorLog = (line) => console.error(line) } = {})
   }
 }
 
-function loginHelp() {
-  console.log(`${bold("botbuddy login")} — authenticate via OAuth (browser + loopback callback)
+export function loginHelp(log = console.log) {
+  log(`${bold("botbuddy login")} — authenticate via OAuth (browser + loopback callback)
 
 ${bold("USAGE")}
   botbuddy login [--no-browser] [--tenant <slug>]
@@ -352,7 +393,9 @@ ${bold("NOTES")}
 ${bold("RECOVERY")}
   If ${cyan("botbuddy status")} shows no client key, run ${cyan("botbuddy login")}. For an
   unattended CI host (no browser), mint a key on a machine with a browser
-  (${cyan("botbuddy mcp setup")}) and export it as ${cyan("$BOTBUDDY_MCP_KEY")} on the CI host.`);
+  (${cyan("botbuddy mcp setup")}) and export it as ${cyan("$BOTBUDDY_MCP_KEY")} on the CI host.
+
+${SETUP_BLOCK}`);
 }
 
 async function cmdStart(args) {
@@ -561,7 +604,7 @@ function cmdHeartbeat(args) {
 
 // ─── BOT-1607: `botbuddy mcp` — the tier-2 bb_mcp_ config key ────────────────
 
-function mcpHelp(log) {
+export function mcpHelp(log = console.log) {
   log(`Usage: botbuddy mcp <setup|revoke|status|env> [options]
 
   setup [--env <NAME>] [--tenant <slug>] [--label <label>] [--expiry-days <n>] [--force]
@@ -587,7 +630,9 @@ function mcpHelp(log) {
                     or in the desktop LaunchAgent env-install recipe.
 
 Present the key from .mcp.json instead of reusing an agent session token — it is
-independently revocable, so a leaked config credential rotates without a re-login.`);
+independently revocable, so a leaked config credential rotates without a re-login.
+
+${SETUP_BLOCK}`);
 }
 
 // Actionable recovery for an mcp setup/revoke failure code.

package/src/pw/run.mjs

@@ -35,7 +35,7 @@ async function gate({ env, host, lane, deps }) {
   // server's owner_is_caller.
   const sessionToken = deps.sessionToken ?? readAgentKeyEnv(env);
   if (sessionToken && !AGENT_KEY_RE.test(sessionToken)) {
-    return { allowed: false, message: "bb-pw: $BOTBUDDY_AGENT_KEY is malformed (expected bb_agent_<64 hex>). Re-register the agent, or set BB_PW_NO_LOCK=1 for local-only work." };
+    return { allowed: false, message: "bb-pw: $BOTBUDDY_AGENT_KEY is malformed (tier-3 session token; expected bb_agent_<64 hex>). Re-register: register_agent → export BOTBUDDY_AGENT_KEY. See docs/agent-connectivity.md. (BB_PW_NO_LOCK=1 runs local-only, unlocked.)" };
   }
   const sessionAgentId = deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null;
   const registeredAgentId = await (deps.readSessionAgentId ?? readRegisteredAgentId)();
@@ -49,7 +49,7 @@ async function gate({ env, host, lane, deps }) {
       } catch { token = null; }
     }
     if (!token) {
-      return { allowed: false, message: "bb-pw: no BotBuddy credential — export $BOTBUDDY_AGENT_KEY (from register_agent) or your .mcp.json key ($BOTBUDDY_MCP_KEY), or set BB_PW_NO_LOCK=1 for local-only work." };
+      return { allowed: false, message: "bb-pw: no BotBuddy credential — a lane needs the tier-3 session token (bb_agent_: register_agent → export $BOTBUDDY_AGENT_KEY) or your tier-2 .mcp.json key ($BOTBUDDY_MCP_KEY, bb mcp setup). See docs/agent-connectivity.md. (BB_PW_NO_LOCK=1 runs local-only, unlocked.)" };
     }
     coordinator = createSessionTokenCoordinator({ token, fetchImpl: deps.fetch });
   }

package/src/run.mjs

@@ -6,15 +6,19 @@
 // allowed to call update_command_run.  A bb-wait is therefore a notification
 // mechanism, never the owner of a child process.
 
-import { createHash, randomUUID } from "crypto";
-import { mkdir, readFile, writeFile, chmod, unlink, stat, rename } from "fs/promises";
-import { dirname, join } from "path";
-import { homedir } from "os";
-import { spawn } from "child_process";
-import { fileURLToPath } from "url";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile, chmod, unlink, stat, rename } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { callToolJson } from "./api.mjs";
 import { parseLaneEvents, laneCaseCounts, flushLaneCases, buildLaneSummary, laneSummaryFilename } from "./test-lane-events.mjs";
 import { AGENT_KEY_RE, readAgentKeyEnv } from "./agent-key.mjs";
+import { createTelemetryOutbox } from "./telemetry-outbox.mjs";
+import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
+import { attestTelemetryCredential, loadTelemetryIdentity } from "./telemetry-config.mjs";
+import { VERSION } from "./version.mjs";
 
 export const RUN_SCHEMA_VERSION = 1;
 export const EXIT = Object.freeze({ OK: 0, INVALID: 4, BACKEND: 5, INTERNAL: 7 });
@@ -24,6 +28,7 @@ const MAX_CAPTURE_BYTES = 8_192;
 // BOT-1510: how often the worker flushes lane case verdicts to the backend.
 // Well under AC-3's 5 s so a begin/verdict is visible within the window.
 const LANE_FLUSH_INTERVAL_MS = 2_500;
+const FOREGROUND_KINDS = new Set(["test", "wait", "browser", "ci", "hook", "stack"]);
 
 // BOT-1582: the server's session-token shape (bb_agent_ + 64 hex) plus the
 // BOT-1572 bb_sess_ legacy alias, both accepted for one release.
@@ -34,7 +39,7 @@ export function parseRunArgs(argv, env = process.env) {
   // session, so --session-id becomes optional (the relay derives it). The old
   // $BOTBUDDY_SESSION_TOKEN is still accepted for one release. $BOTBUDDY_SESSION_ID
   // is the default when a plain id is used (parity with `botbuddy test`).
-  const opts = { sessionId: env.BOTBUDDY_SESSION_ID ?? null, sessionToken: readAgentKeyEnv(env), environment: null, category: "validation", kind: "other", expectedDuration: 0, timeout: DEFAULT_TIMEOUT_SECONDS, rerunReason: null, json: false };
+  const opts = { sessionId: env.BOTBUDDY_SESSION_ID ?? null, sessionToken: readAgentKeyEnv(env), environment: null, category: "validation", kind: "other", expectedDuration: 0, timeout: DEFAULT_TIMEOUT_SECONDS, rerunReason: null, foreground: false, json: false };
   const errors = [];
   const separator = argv.indexOf("--");
   const flags = separator === -1 ? argv : argv.slice(0, separator);
@@ -62,6 +67,7 @@ export function parseRunArgs(argv, env = process.env) {
         } catch (error) { errors.push(`--rerun-reason must be a JSON object (${error instanceof Error ? error.message : String(error)})`); }
         break;
       }
+      case "--foreground": opts.foreground = true; break;
       case "--json": opts.json = true; break;
       default: errors.push(`unknown option: ${flag}`);
     }
@@ -70,7 +76,8 @@ export function parseRunArgs(argv, env = process.env) {
   // session from the token). A malformed token, or a plain id AND a differing
   // token, is a hard error.
   if (opts.sessionToken && !SESSION_TOKEN_RE.test(opts.sessionToken)) errors.push("$BOTBUDDY_AGENT_KEY must match bb_agent_<64 hex>");
-  if (!opts.sessionId && !opts.sessionToken) errors.push("--session-id is required (from register_agent), or set $BOTBUDDY_AGENT_KEY");
+  if (!opts.foreground && !opts.sessionId && !opts.sessionToken) errors.push("--session-id is required (from register_agent), or set $BOTBUDDY_AGENT_KEY");
+  if (opts.foreground && !FOREGROUND_KINDS.has(opts.kind)) errors.push("--kind must be test, wait, browser, ci, hook, or stack with --foreground");
   if (!opts.environment || !["local", "preview", "staging", "production", "none"].includes(opts.environment)) errors.push("--environment must be local, preview, staging, production, or none");
   if (!command.length) errors.push("a workload is required after --");
   if (!Number.isInteger(opts.expectedDuration) || opts.expectedDuration < 0) errors.push("--expected-duration must be a non-negative integer");
@@ -78,6 +85,118 @@ export function parseRunArgs(argv, env = process.env) {
   return { opts, command, errors };
 }
 
+function foregroundOutcome({ exitCode, signal, timedOut }) {
+  if (timedOut) return "timed_out";
+  if (signal) return "canceled";
+  return exitCode === 0 ? "passed" : "failed";
+}
+
+function signalExitCode(signal) {
+  const codes = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129, SIGKILL: 137 };
+  return codes[signal] ?? EXIT.INTERNAL;
+}
+
+// Foreground deliberately shares no ownership code with BOT-1350's detached
+// runner. It has exactly one durable pre-spawn boundary (the outbox start
+// event), then returns the child verdict even when terminal delivery degrades.
+export async function launchForegroundRun(argv, {
+  cwd = process.cwd(), spawnImpl = spawn, identity = null, outbox = null, signalEmitter = process,
+} = {}) {
+  const { opts, command, errors } = parseRunArgs(argv);
+  if (errors.length) return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", errors, exit_code: EXIT.INVALID } };
+  if (!opts.foreground) return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", error: "foreground_flag_required", exit_code: EXIT.INVALID } };
+  if (!identity?.repository || !identity?.tenant || !identity?.appSlug) {
+    return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", error: "telemetry_identity_required", exit_code: EXIT.INVALID } };
+  }
+  const telemetry = outbox ?? await createTelemetryOutbox({
+    tenant: identity.tenant,
+    repository: identity.repository,
+    producerVersion: identity.producerVersion ?? VERSION,
+  });
+  // An authenticated invocation is also the bounded recovery opportunity for
+  // prior offline records. Failure remains durable and never alters the child
+  // verdict below.
+  if (!outbox) {
+    // A cached proof keeps offline hooks fast; a new or rotated credential must
+    // be authenticated once before it may scope a BotBuddy lifecycle event.
+    try {
+      await attestTelemetryCredential(identity, telemetry);
+    } catch (error) {
+      return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", error: error?.message ?? "telemetry_credential_unattested", exit_code: EXIT.INVALID } };
+    }
+    await telemetry.importLegacyTestRunReceipts(join(cwd, ".botbuddy", "test-runs"), { maxReceipts: 8, deadline: Date.now() + 2_250 }).catch(() => {});
+    await telemetry.replay(
+      (event) => deliverExecutionEvent(event, { credential: identity.credential }),
+      // Recovery is opportunistic: a large offline backlog must never turn the
+      // next hook invocation into an unbounded pre-spawn upload job.
+      { maxEvents: 8, deadline: Date.now() + 2_250 },
+    ).catch(() => {});
+  }
+  const runId = randomUUID();
+  const context = {
+    repo: identity.repository,
+    environment: opts.environment,
+    runner: identity.appSlug,
+    phase: opts.kind === "wait" ? "waiting" : "testing",
+    health: "uninstrumented",
+  };
+  const base = {
+    schema_version: 1,
+    producer_kind: opts.kind,
+    source_run_id: runId,
+    attempt: 1,
+    occurred_at: new Date().toISOString(),
+    context,
+  };
+  try {
+    await telemetry.append({ ...base, action: "start", producer_event_id: `${runId}:start`, producer_sequence: 0 });
+  } catch (error) {
+    return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", error: error?.code ?? "telemetry_start_not_durable", exit_code: EXIT.INTERNAL } };
+  }
+  let child;
+  try {
+    // A foreground command still needs its own process group: hooks commonly
+    // launch package managers or test runners, whose descendants otherwise
+    // survive a timeout after their immediate parent exits.
+    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 } };
+  }
+  let timedOut = false;
+  let killTimer;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    terminateProcessGroup(child, "SIGTERM");
+    killTimer = setTimeout(() => terminateProcessGroup(child, "SIGKILL"), TIMEOUT_GRACE_MS);
+  }, opts.timeout * 1000);
+  const forwarded = forwardTerminationSignals(child, signalEmitter);
+  const result = await waitForChild(child);
+  forwarded.cleanup();
+  clearTimeout(timeout);
+  clearTimeout(killTimer);
+  const terminalSignal = forwarded.signal ?? result.signal;
+  const outcome = result.error ? "crashed" : foregroundOutcome({ ...result, signal: terminalSignal, timedOut });
+  let telemetryState = "durable";
+  try {
+    await telemetry.append({
+      ...base,
+      action: "terminal",
+      producer_event_id: `${runId}:terminal`,
+      producer_sequence: 1,
+      // BOT-1317 derives duration from the two lifecycle timestamps. `base`
+      // intentionally represents pre-spawn time, so terminal needs a fresh
+      // timestamp after the child has actually completed.
+      occurred_at: new Date().toISOString(),
+      context: { ...context, phase: outcome === "passed" ? "complete" : "failed" },
+      outcome,
+      ...(terminalSignal ? { diagnostic: { code: "child_signaled", category: "signal", signal: terminalSignal } } : {}),
+    });
+  } 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 } };
+}
+
 export function terminalStatus({ exitCode, signal, timedOut = false, ownerLost = false }) {
   if (ownerLost) return "owner_lost";
   if (timedOut) return "timed_out";
@@ -280,7 +399,30 @@ function boundedCapture() {
 }
 
 function terminateProcessGroup(child, signal) {
-  try { process.kill(-child.pid, signal); } catch { try { child.kill?.(signal); } catch { /* already exited */ } }
+  if (process.platform !== "win32" && Number.isInteger(child?.pid) && child.pid > 0) {
+    try { process.kill(-child.pid, signal); return; } catch { /* fall back to the immediate child */ }
+  }
+  try { child.kill?.(signal); } catch { /* already exited */ }
+}
+
+function forwardTerminationSignals(child, signalEmitter) {
+  let signal = null;
+  let escalation = null;
+  const handlers = new Map();
+  for (const candidate of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    const handler = () => {
+      if (signal) { terminateProcessGroup(child, "SIGKILL"); return; }
+      signal = candidate;
+      terminateProcessGroup(child, candidate);
+      escalation = setTimeout(() => terminateProcessGroup(child, "SIGKILL"), TIMEOUT_GRACE_MS);
+    };
+    handlers.set(candidate, handler);
+    signalEmitter.on(candidate, handler);
+  }
+  return {
+    get signal() { return signal; },
+    cleanup() { clearTimeout(escalation); for (const [candidate, handler] of handlers) signalEmitter.removeListener(candidate, handler); },
+  };
 }
 
 function waitForChild(child) {
@@ -343,7 +485,20 @@ 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 cancel <run_id>");
+    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 cancel <run_id>");
+    return;
+  }
+  if (args.includes("--foreground")) {
+    let identity;
+    try { identity = await loadTelemetryIdentity(); }
+    catch (error) {
+      oneLine({ schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", error: error?.message ?? "telemetry_identity_invalid", exit_code: EXIT.INVALID }, false);
+      process.exitCode = EXIT.INVALID;
+      return;
+    }
+    const result = await launchForegroundRun(args, { identity: { ...identity, producerVersion: VERSION } });
+    oneLine(result.receipt, Boolean(parseRunArgs(args).opts.json));
+    process.exitCode = result.exitCode;
     return;
   }
   const result = await launchRun(args);

package/src/setup-block.mjs

@@ -0,0 +1,74 @@
+// BOT-1644 — ONE source of truth for the connectivity ladder and the credential
+// tier names, so every CLI help surface (`bb --help`, `bb wait --help`,
+// `bb login --help`, `bb mcp --help`), the recovery strings, and the canonical
+// guide all agree. The snapshot test (agent-connectivity.test.mjs) asserts the
+// SETUP block appears verbatim in all four help outputs, so drift is caught.
+//
+// This documents the CURRENT supported process (BOT-1644 scope). It does NOT
+// describe the P1–P6 "self-healing auth" redesign, which is a separate future
+// project.
+
+/** The canonical guide, referenced from every SETUP block and recovery. */
+export const CONNECTIVITY_GUIDE = "docs/agent-connectivity.md";
+
+// The three connectivity credential tiers, named consistently everywhere. A
+// connectivity error names the MISSING tier and the exact next command; the
+// guide's tiered table and the help SETUP block use these same labels.
+export const TIERS = Object.freeze({
+  // Tier 1 — per-machine client key. `bb login`, USER-scoped (reaches every
+  // tenant you belong to; each request pins one). Never a wait credential.
+  client: Object.freeze({
+    n: 1,
+    label: "client key",
+    prefix: "bb_cli_",
+    env: "BOTBUDDY_CLIENT_KEY",
+    setup: "bb login",
+    scope: "user",
+  }),
+  // Tier 2 — per-tenant MCP config key. `bb mcp setup`, TENANT-bound, lives in
+  // .mcp.json under $BOTBUDDY_MCP_KEY. Authenticates MCP calls + register_agent.
+  mcp: Object.freeze({
+    n: 2,
+    label: "MCP key",
+    prefix: "bb_mcp_",
+    env: "BOTBUDDY_MCP_KEY",
+    setup: "bb mcp setup",
+    scope: "tenant",
+  }),
+  // Tier 3 — per-session agent token. `register_agent` (over MCP), tenant-bound,
+  // 8 h TTL, revoked on re-register. The ONLY credential a wait/run/test/pw
+  // accepts. Exported as $BOTBUDDY_AGENT_KEY (+ $BOTBUDDY_SESSION_ID for
+  // attribution).
+  session: Object.freeze({
+    n: 3,
+    label: "session token",
+    prefix: "bb_agent_",
+    env: "BOTBUDDY_AGENT_KEY",
+    setup: "register_agent",
+    scope: "session",
+  }),
+});
+
+// The register_agent → export handoff, named once. Recovery strings reuse it so
+// the exact two export lines never drift from the guide.
+export const EXPORT_STEP =
+  "register_agent → export BOTBUDDY_AGENT_KEY=<session_token> (and BOTBUDDY_SESSION_ID=<session_id>)";
+
+/**
+ * The shared SETUP block reproduced verbatim in every `--help` output. Plain
+ * text (no ANSI) so the snapshot test can match it byte-for-byte across surfaces.
+ * The E2E ladder in order, then the fresh-shell caveat and the guide link.
+ */
+export const SETUP_BLOCK = `SETUP — the connectivity ladder (install → connect → wait)
+  1. npm i -g @botbuddy/cli                 install the CLI
+  2. bb login                               tier 1 · client key (bb_cli_, user-scoped) → Keychain
+  3. bb mcp setup                           tier 2 · MCP key (bb_mcp_, tenant-bound) → Keychain + .mcp.json ($BOTBUDDY_MCP_KEY)
+                                            (Keychainless host: the key is printed ONCE — store + export + edit .mcp.json yourself)
+                                            the repo's pre-committed .botbuddy-agent.json binds tenant + mcp_env
+  4. register_agent (over MCP)              tier 3 · session token (bb_agent_, per-session, 8 h)
+  5. export BOTBUDDY_AGENT_KEY=<session_token>   and   BOTBUDDY_SESSION_ID=<session_id>
+  6. bb wait                                needs the tier-3 token; bb run/test also accept $BOTBUDDY_SESSION_ID,
+                                            bb pw falls back to the tier-2 MCP key
+  NOTE: each Claude Code Bash call is a FRESH shell — exports do NOT persist between tool calls;
+        re-export (or pass --agent-key <token>) in the same command that runs the wait.
+  Full guide: ${CONNECTIVITY_GUIDE}`;

package/src/telemetry-config.mjs

@@ -0,0 +1,109 @@
+// BOT-1316 — checked-in repo identity, separate from local credentials.
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { resolveAgentBinding } from "./wait-profile.mjs";
+import { callToolJson } from "./api.mjs";
+
+const execFileAsync = promisify(execFile);
+const REQUIRED_KEYS = ["schema_version", "repository", "app_slug", "profile", "expected_tenant"];
+const REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+export function parseTelemetryConfig(raw) {
+  let value;
+  try { value = JSON.parse(raw); } catch { throw new Error(".botbuddy/config.json is not valid JSON"); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(".botbuddy/config.json must be an object");
+  const keys = Object.keys(value).sort();
+  if (keys.length !== REQUIRED_KEYS.length || keys.some((key, index) => key !== [...REQUIRED_KEYS].sort()[index])) {
+    throw new Error(".botbuddy/config.json must contain exactly schema_version, repository, app_slug, profile, expected_tenant");
+  }
+  if (value.schema_version !== 1 || !REPOSITORY.test(value.repository) || !SLUG.test(value.app_slug) || !SLUG.test(value.profile) || !SLUG.test(value.expected_tenant)) {
+    throw new Error(".botbuddy/config.json has an invalid schema_version or identity value");
+  }
+  return { schemaVersion: 1, repository: value.repository, appSlug: value.app_slug, profile: value.profile, expectedTenant: value.expected_tenant };
+}
+
+export async function repositoryFromRemote(cwd = process.cwd()) {
+  const { stdout } = await execFileAsync("git", ["config", "--get", "remote.origin.url"], { cwd });
+  const raw = stdout.trim().replace(/\.git$/, "");
+  const match = raw.match(/(?:github\.com[/:])([^/]+\/[^/]+)$/i);
+  if (!match) throw new Error("origin remote is not a canonical GitHub repository");
+  return match[1];
+}
+
+export async function verifyTelemetryIdentity(config, {
+  cwd = process.cwd(), repositoryFromRemote: remote = repositoryFromRemote, resolveBinding = resolveAgentBinding, call = callToolJson, verifyCredential = false,
+} = {}) {
+  const repository = await remote(cwd);
+  if (repository.toLowerCase() !== config.repository.toLowerCase()) throw new Error("telemetry repository mismatch with origin remote");
+  const binding = await resolveBinding({ cwd });
+  if (!binding?.token) throw new Error("telemetry requires a locally stored tenant-bound credential");
+  if (binding.tenant !== config.expectedTenant) throw new Error("telemetry tenant mismatch with checked-in config");
+  // A binding file names the intended tenant; it is not proof that a rotated
+  // environment credential still belongs there. Ask the server's read-only
+  // identity endpoint before allowing a foreground child to run.
+  if (verifyCredential) {
+    const verified = await call("whoami", {}, {
+      auth: { "x-agent-api-key": binding.token },
+      tenant: config.expectedTenant,
+      signal: AbortSignal.timeout(2_000),
+    });
+    if (!verified?.ok || verified.isError || verified.data?.tenant_id !== config.expectedTenant) {
+      throw new Error("telemetry credential is not attested to the expected tenant");
+    }
+  }
+  return { repository: config.repository, tenant: config.expectedTenant, appSlug: config.appSlug, profile: config.profile, credential: binding.token };
+}
+
+export async function loadTelemetryLocation(cwd = process.cwd(), {
+  repositoryFromRemote: remote = repositoryFromRemote,
+} = {}) {
+  const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd });
+  const root = stdout.trim();
+  const raw = await readFile(join(root, ".botbuddy", "config.json"), "utf8");
+  const config = parseTelemetryConfig(raw);
+  const repository = await remote(root);
+  if (repository.toLowerCase() !== config.repository.toLowerCase()) throw new Error("telemetry repository mismatch with origin remote");
+  return { root, repository: config.repository, tenant: config.expectedTenant, appSlug: config.appSlug, profile: config.profile };
+}
+
+export async function loadTelemetryIdentity(cwd = process.cwd(), options = {}) {
+  const location = await loadTelemetryLocation(cwd, options);
+  const config = {
+    schemaVersion: 1,
+    repository: location.repository,
+    appSlug: location.appSlug,
+    profile: location.profile,
+    expectedTenant: location.tenant,
+  };
+  return verifyTelemetryIdentity(config, { cwd: location.root, ...options });
+}
+
+function credentialFingerprint(credential) {
+  return createHash("sha256").update(credential).digest("hex");
+}
+
+// A tenant-bound key must be proven once before foreground execution can trust
+// it. The proof is keyed to a non-reversible fingerprint in the 0600 outbox
+// status file, so a later rotation or cross-tenant environment value cannot
+// reuse a prior attestation. Once cached, the check remains fully offline.
+export async function attestTelemetryCredential(identity, outbox, { call = callToolJson } = {}) {
+  const fingerprint = credentialFingerprint(identity?.credential ?? "");
+  if (!identity?.credential || !identity?.tenant || !outbox?.hasCredentialAttestation || !outbox?.recordCredentialAttestation) {
+    throw new Error("telemetry credential attestation is unavailable");
+  }
+  if (await outbox.hasCredentialAttestation({ tenant: identity.tenant, fingerprint })) return { cached: true };
+  const verified = await call("whoami", {}, {
+    auth: { "x-agent-api-key": identity.credential },
+    tenant: identity.tenant,
+    signal: AbortSignal.timeout(2_000),
+  });
+  if (!verified?.ok || verified.isError || verified.data?.tenant_id !== identity.tenant) {
+    throw new Error("telemetry credential is not attested to the expected tenant");
+  }
+  await outbox.recordCredentialAttestation({ tenant: identity.tenant, fingerprint });
+  return { cached: false };
+}

package/src/telemetry-delivery.mjs

@@ -0,0 +1,40 @@
+// BOT-1316 — direct HTTP delivery to BOT-1317. This intentionally bypasses the
+// MCP tool surface: agents never need to call telemetry MCP tools.
+export function executionIngestEndpoint(serverUrl = process.env.BOTBUDDY_SERVER_URL || "https://api.bot-buddy.ai/functions/v1/mcp-server") {
+  const url = new URL(serverUrl);
+  url.pathname = url.pathname.replace(/\/mcp-server\/?$/, "/execution-ingest");
+  return url.toString();
+}
+
+export async function deliverExecutionEvent(event, {
+  credential, endpoint = executionIngestEndpoint(), fetchImpl = fetch, timeoutMs = 2_000,
+} = {}) {
+  if (typeof credential !== "string" || !credential) return { accepted: false, error: "credential_missing" };
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "x-agent-api-key": credential },
+      body: JSON.stringify(event),
+      signal: controller.signal,
+    });
+    let body = {};
+    try { body = await response.json(); } catch { /* typed HTTP status still controls retry */ }
+    if (response.status === 200 || response.status === 202) return { accepted: true, receipt: body.receipt ?? "accepted" };
+    // A reaper may have terminalized a run after a successful upload whose
+    // response was lost. BOT-1317 correctly refuses a contradictory terminal;
+    // retaining that record would otherwise block every later local event.
+    if (response.status === 409 && body.error === "terminal_conflict") return { accepted: true, receipt: "terminal_conflict_retired" };
+    // The queue cannot repair an event rejected by the server's contract.
+    // Quarantine these client errors so one malformed historical line does not
+    // starve later valid lifecycle events. Authentication is deliberately left
+    // retryable: a key can be restored or rotated without discarding evidence.
+    if ([400, 404, 409, 413, 422].includes(response.status)) {
+      return { accepted: false, permanent: true, error: body.error ?? `http_${response.status}` };
+    }
+    return { accepted: false, error: body.error ?? `http_${response.status}` };
+  } catch (error) {
+    return { accepted: false, error: controller.signal.aborted ? "timeout" : error?.code ?? "transport" };
+  } finally { clearTimeout(timeout); }
+}

package/src/telemetry-outbox.mjs

@@ -0,0 +1,327 @@
+// BOT-1316 — durable, local-first lifecycle delivery for foreground wrappers.
+// This module deliberately knows nothing about MCP or child output. Producers
+// append a small, allowlisted lifecycle event before spawning a child; delivery
+// is a separate, idempotent step against execution-ingest.
+
+import { createHash } from "node:crypto";
+import { chmod, link, mkdir, open, readFile, readdir, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const OUTBOX_SCHEMA_VERSION = 1;
+export const MAX_OUTBOX_LINE_BYTES = 16 * 1024;
+const LOCK_WAIT_MS = 25;
+const LOCK_ATTEMPTS = 80;
+const SENSITIVE = /(?:[a-z][a-z0-9+.-]*:\/\/[^\s/@:]+:[^\s/@]+@[^\s/]+(?:\/[^\s]*)?|bb_[a-z0-9_-]{10,}|gh[pousr]_[a-z0-9]{16,}|github_pat_[a-z0-9_]{20,}|glpat-[a-z0-9_-]{16,}|xox[baprs]-[a-z0-9-]{10,}|sk-[a-z0-9]{20,}|(?:akia|asia)[a-z0-9]{16}|-----begin[a-z0-9 ]*private key-----[\s\S]*?-----end[a-z0-9 ]*private key-----)|\bbearer\s+[^\s"']+|(?:^|[^a-z0-9])(?:[a-z0-9]+_)*(?:token|api[_-]?key|private[_-]?key|password|secret)(?:_[a-z0-9]+)*\s*[=:]\s*(?:"[^"]*"|'[^']*'|[^\s"']+)/gi;
+const DROP_KEYS = new Set(["stdout", "stderr", "output", "raw_output", "bounded_log", "env", "environment_values", "environment_value", "secrets"]);
+const CONTEXT_KEYS = new Set([
+  "agent", "repo", "ticket", "pr", "branch", "sha", "environment", "runner", "phase",
+  "worker", "shard", "retry", "current_spec", "passed", "failed", "skipped", "health", "correlations",
+]);
+const CORRELATION_KEYS = new Set([
+  "tool_event_id", "command_receipt_id", "test_run_id", "test_execution_id", "wait_session_id",
+  "lane_session_id", "agent_signal_seq", "stack_lease_id",
+]);
+const PROGRESS_KEYS = new Set(["completed", "total", "phase", "current_item", "worker", "shard"]);
+const DIAGNOSTIC_KEYS = new Set(["code", "message", "category", "signal", "retryable"]);
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+
+function redactString(value) {
+  SENSITIVE.lastIndex = 0;
+  return value.replace(SENSITIVE, "[REDACTED]");
+}
+
+// Exported for wrappers and reporter adapters. Removing forbidden fields is more
+// robust than merely redacting values: raw output is never useful lifecycle data.
+export function redactTelemetry(value) {
+  if (Array.isArray(value)) return value.map(redactTelemetry);
+  if (!value || typeof value !== "object") return typeof value === "string" ? redactString(value) : value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !DROP_KEYS.has(key.toLowerCase()))
+    .map(([key, item]) => [key, redactTelemetry(item)]));
+}
+
+function repositoryHash(repository) {
+  return hash(repository.toLowerCase()).slice(0, 32);
+}
+
+function validTenant(value) { return typeof value === "string" && /^[a-z0-9][a-z0-9-]{0,63}$/.test(value); }
+function validRepository(value) { return typeof value === "string" && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value); }
+
+function eventPayload(event) {
+  const clean = redactTelemetry(event);
+  if (!clean || typeof clean !== "object" || Array.isArray(clean)) throw new Error("telemetry event must be an object");
+  // execution-ingest is intentionally strict. Keep this client-side allowlist so
+  // a reporter cannot accidentally turn arbitrary process state into telemetry.
+  const allowed = new Set(["schema_version", "action", "producer_kind", "source_run_id", "attempt", "producer_event_id", "producer_sequence", "occurred_at", "context", "progress", "outcome", "diagnostic", "evidence_refs"]);
+  for (const key of Object.keys(clean)) if (!allowed.has(key)) delete clean[key];
+  // Mirror the server contract at the producer boundary. A malformed reporter
+  // must not create a permanently retrying record merely because it included
+  // a harmless but unrecognised field.
+  if (clean.context && typeof clean.context === "object" && !Array.isArray(clean.context)) {
+    clean.context = Object.fromEntries(Object.entries(clean.context).filter(([key]) => CONTEXT_KEYS.has(key)));
+    if (clean.context.correlations && typeof clean.context.correlations === "object" && !Array.isArray(clean.context.correlations)) {
+      clean.context.correlations = Object.fromEntries(Object.entries(clean.context.correlations).filter(([key]) => CORRELATION_KEYS.has(key)));
+    }
+  }
+  if (clean.progress && typeof clean.progress === "object" && !Array.isArray(clean.progress)) {
+    clean.progress = Object.fromEntries(Object.entries(clean.progress).filter(([key]) => PROGRESS_KEYS.has(key)));
+  }
+  if (clean.diagnostic && typeof clean.diagnostic === "object" && !Array.isArray(clean.diagnostic)) {
+    clean.diagnostic = Object.fromEntries(Object.entries(clean.diagnostic).filter(([key]) => DIAGNOSTIC_KEYS.has(key)));
+  }
+  return clean;
+}
+
+async function durableWrite(path, value, { append = false } = {}) {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  const handle = await open(path, append ? "a" : "w", 0o600);
+  try {
+    await handle.writeFile(text);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await chmod(path, 0o600);
+}
+
+async function atomicJson(path, value) {
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await durableWrite(temp, `${JSON.stringify(value)}\n`);
+  await rename(temp, path);
+  // Persist the directory entry, not just the file data, before reporting the
+  // acknowledgement checkpoint as durable.
+  let dir;
+  try { dir = await open(dirname(path), "r"); await dir.sync(); } finally { await dir?.close(); }
+}
+
+function parseRecord(line) {
+  let parsed;
+  try { parsed = JSON.parse(line); } catch {
+    const error = new Error("invalid_json");
+    error.code = "invalid_json";
+    throw error;
+  }
+  if (!parsed || parsed.schema_version !== OUTBOX_SCHEMA_VERSION || typeof parsed.checksum !== "string" || !parsed.event) throw new Error("invalid_record_shape");
+  const expected = hash(JSON.stringify(parsed.event));
+  if (parsed.checksum !== expected) throw new Error("checksum_mismatch");
+  return parsed;
+}
+
+function safeErrorClass(error) {
+  const raw = String(error?.code ?? error?.name ?? "delivery_failed");
+  return raw.replace(/[^a-z0-9_.-]/gi, "_").slice(0, 96) || "delivery_failed";
+}
+
+export async function createTelemetryOutbox({
+  root = join(homedir(), ".botbuddy", "telemetry"), tenant, repository, producerVersion, now = () => new Date(),
+} = {}) {
+  if (!validTenant(tenant)) throw new Error("telemetry tenant must be a lowercase slug");
+  if (!validRepository(repository)) throw new Error("telemetry repository must be canonical owner/name");
+  if (typeof producerVersion !== "string" || !producerVersion) throw new Error("telemetry producer version is required");
+  const directory = join(root, tenant, repositoryHash(repository));
+  const path = join(directory, "outbox.ndjson");
+  const lockPath = join(directory, "outbox.lock");
+  const quarantinePath = join(directory, "outbox.quarantine.ndjson");
+  const statusPath = join(directory, "status.json");
+  const legacyImportPath = join(directory, "legacy-test-runs.imported.json");
+
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+
+  async function acquireLock() {
+    for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt++) {
+      try {
+        // Write a complete, fsynced owner record first, then atomically publish
+        // it with link(2). A crash can leave an unreferenced temp file but can
+        // never strand the shared lock name with missing PID metadata.
+        const candidate = `${lockPath}.${process.pid}.${Date.now()}.tmp`;
+        await durableWrite(candidate, JSON.stringify({ pid: process.pid, created_at: now().toISOString() }));
+        try { await link(candidate, lockPath); } finally { await unlink(candidate).catch(() => {}); }
+        return async () => { try { await unlink(lockPath); } catch { /* a process may have cleaned its own stale lock */ } };
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+        let owner = null;
+        try { owner = JSON.parse(await readFile(lockPath, "utf8")); } catch { /* incomplete lock is never age-reclaimed */ }
+        // A lock may be reclaimed only after proving the same-host PID is gone.
+        if (Number.isInteger(owner?.pid) && owner.pid > 0) {
+          let alive = true;
+          try { process.kill(owner.pid, 0); } catch (probe) { alive = probe?.code !== "ESRCH"; }
+          if (!alive) { try { await unlink(lockPath); } catch { /* winner will retry */ } continue; }
+        }
+        await sleep(LOCK_WAIT_MS);
+      }
+    }
+    const err = new Error("telemetry_outbox_lock_busy");
+    err.code = "telemetry_outbox_lock_busy";
+    throw err;
+  }
+
+  async function readStatus() {
+    try { return JSON.parse(await readFile(statusPath, "utf8")); } catch { return {}; }
+  }
+
+  async function writeStatus(patch) {
+    const current = await readStatus();
+    await atomicJson(statusPath, { ...current, ...patch, producer_version: producerVersion, updated_at: now().toISOString() });
+  }
+
+  async function hasCredentialAttestation({ tenant: attestedTenant, fingerprint }) {
+    const persisted = await readStatus();
+    const attestation = persisted.credential_attestation;
+    return attestation?.schema_version === 1
+      && attestation.tenant === attestedTenant
+      && attestation.fingerprint === fingerprint;
+  }
+
+  async function recordCredentialAttestation({ tenant: attestedTenant, fingerprint }) {
+    if (!validTenant(attestedTenant) || !/^[a-f0-9]{64}$/.test(fingerprint ?? "")) throw new Error("invalid telemetry credential attestation");
+    await writeStatus({ credential_attestation: { schema_version: 1, tenant: attestedTenant, fingerprint, attested_at: now().toISOString() } });
+  }
+
+  async function readLines() {
+    try { return (await readFile(path, "utf8")).split("\n").filter(Boolean); } catch (error) { if (error?.code === "ENOENT") return []; throw error; }
+  }
+
+  async function append(event) {
+    const release = await acquireLock();
+    try {
+      const payload = eventPayload(event);
+      const record = {
+        schema_version: OUTBOX_SCHEMA_VERSION,
+        created_at: now().toISOString(),
+        producer_version: producerVersion,
+        repository,
+        event: payload,
+        delivery_attempts: 0,
+        checksum: hash(JSON.stringify(payload)),
+      };
+      const line = `${JSON.stringify(record)}\n`;
+      if (Buffer.byteLength(line) > MAX_OUTBOX_LINE_BYTES) {
+        const error = new Error("telemetry_event_oversized"); error.code = "telemetry_event_oversized"; throw error;
+      }
+      // append + fsync completes before the caller gets a durable receipt, which
+      // is the required pre-spawn barrier for foreground commands.
+      await durableWrite(path, line, { append: true });
+      await writeStatus({ last_error_class: null });
+      return { durable: true, path, event: payload };
+    } finally { await release(); }
+  }
+
+  async function quarantine(line, offset, reason) {
+    await durableWrite(quarantinePath, `${JSON.stringify({ offset, reason, quarantined_at: now().toISOString(), line: line.slice(0, MAX_OUTBOX_LINE_BYTES) })}\n`, { append: true });
+  }
+
+  async function replay(deliver, { maxEvents = Infinity, deadline = Infinity } = {}) {
+    if (typeof deliver !== "function") throw new Error("telemetry replay requires a delivery function");
+    const release = await acquireLock();
+    try {
+      const lines = await readLines();
+      const remaining = [];
+      let delivered = 0;
+      let quarantined = 0;
+      let halted = false;
+      let attempted = 0;
+      let offset = 0;
+      for (const line of lines) {
+        let record;
+        try {
+          if (Buffer.byteLength(line) > MAX_OUTBOX_LINE_BYTES) throw new Error("line_oversized");
+          record = parseRecord(line);
+        } catch (error) {
+          quarantined += 1;
+          await quarantine(line, offset, error.message || "invalid_record");
+          offset += Buffer.byteLength(line) + 1;
+          continue;
+        }
+        if (halted || attempted >= maxEvents || Date.now() >= deadline) { halted = true; remaining.push(record); offset += Buffer.byteLength(line) + 1; continue; }
+        try {
+          attempted += 1;
+          const result = await deliver(record.event, record);
+          if (!result?.accepted) {
+            if (result?.permanent) {
+              quarantined += 1;
+              await quarantine(line, offset, result.error ?? "delivery_rejected");
+              continue;
+            }
+            throw Object.assign(new Error("delivery_rejected"), { code: result?.error ?? "delivery_rejected" });
+          }
+          delivered += 1;
+          await writeStatus({ last_successful_delivery_at: now().toISOString(), last_error_class: null });
+        } catch (error) {
+          halted = true;
+          remaining.push({ ...record, delivery_attempts: Number(record.delivery_attempts ?? 0) + 1, last_error_class: safeErrorClass(error), last_attempt_at: now().toISOString() });
+          await writeStatus({ last_error_class: safeErrorClass(error) });
+        }
+        offset += Buffer.byteLength(line) + 1;
+      }
+      const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+      await durableWrite(tmp, remaining.map((record) => `${JSON.stringify(record)}\n`).join(""));
+      await rename(tmp, path);
+      let dir;
+      try { dir = await open(directory, "r"); await dir.sync(); } finally { await dir?.close(); }
+      return { delivered, remaining: remaining.length, quarantined };
+    } finally { await release(); }
+  }
+
+  async function status() {
+    const lines = await readLines();
+    let oldest = null;
+    let queued = 0;
+    for (const line of lines) {
+      try {
+        const record = parseRecord(line);
+        queued += 1;
+        if (!oldest || record.created_at < oldest) oldest = record.created_at;
+      } catch { queued += 1; }
+    }
+    const persisted = await readStatus();
+    return {
+      queued_count: queued,
+      oldest_queued_at: oldest,
+      last_successful_delivery_at: persisted.last_successful_delivery_at ?? null,
+      last_error_class: persisted.last_error_class ?? null,
+      producer_version: producerVersion,
+      path,
+    };
+  }
+
+  // The historical hook reporter writes summaries below `.botbuddy/test-runs`.
+  // Import them only through deterministic source/event keys; the persisted
+  // fingerprint ledger prevents repeated scans from growing the outbox, while
+  // server idempotency remains a second safety net if a machine dies mid-write.
+  async function importLegacyTestRunReceipts(legacyDirectory, { maxReceipts = Infinity, deadline = Infinity } = {}) {
+    let imported = {};
+    try { imported = JSON.parse(await readFile(legacyImportPath, "utf8")); } catch { /* first migration */ }
+    let names = [];
+    try { names = (await readdir(legacyDirectory)).filter((name) => name.endsWith(".json")); } catch (error) { if (error?.code === "ENOENT") return { imported: 0, skipped: 0 }; throw error; }
+    let added = 0;
+    let skipped = 0;
+    for (const name of names.sort()) {
+      if (added >= maxReceipts || Date.now() >= deadline) break;
+      const file = join(legacyDirectory, name);
+      let raw;
+      try { raw = await readFile(file, "utf8"); } catch { skipped += 1; continue; }
+      const fingerprint = hash(`${name}\0${raw}`);
+      if (imported[fingerprint]) { skipped += 1; continue; }
+      let summary;
+      try { summary = JSON.parse(raw); } catch { skipped += 1; continue; }
+      if (!summary || typeof summary !== "object" || typeof summary.runner !== "string") { skipped += 1; continue; }
+      const sourceRunId = `legacy-${fingerprint.slice(0, 32)}`;
+      const started = typeof summary.started_at === "string" ? summary.started_at : now().toISOString();
+      const finished = typeof summary.finished_at === "string" ? summary.finished_at : now().toISOString();
+      const passed = summary.verdict === "pass" || summary.exit_code === 0;
+      const context = { repo: repository, environment: "local", runner: summary.runner, phase: passed ? "complete" : "failed", health: "uninstrumented" };
+      await append({ schema_version: 1, action: "start", producer_kind: "hook", source_run_id: sourceRunId, attempt: 1, producer_event_id: `${sourceRunId}:start`, producer_sequence: 0, occurred_at: started, context });
+      await append({ schema_version: 1, action: "terminal", producer_kind: "hook", source_run_id: sourceRunId, attempt: 1, producer_event_id: `${sourceRunId}:terminal`, producer_sequence: 1, occurred_at: finished, context, outcome: passed ? "passed" : "failed" });
+      imported[fingerprint] = { name, imported_at: now().toISOString() };
+      added += 1;
+    }
+    await atomicJson(legacyImportPath, imported);
+    return { imported: added, skipped };
+  }
+
+  return { directory, path, quarantinePath, statusPath, append, replay, status, hasCredentialAttestation, recordCredentialAttestation, importLegacyTestRunReceipts };
+}

package/src/wait.mjs

@@ -19,6 +19,7 @@ import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.mjs";
 import { AGENT_KEY_RE, readAgentKeyEnv } from "./agent-key.mjs";
+import { SETUP_BLOCK } from "./setup-block.mjs";
 
 // A protocol is deliberately distinct from package semver: compatible pinned
 // clients keep working until the server raises this minimum, while a stale
@@ -36,7 +37,7 @@ const MIN_RECEIPT_MAX_BYTES = 512;
 // BOT-1572 bb_sess_ legacy alias, both accepted for one release.
 const SESSION_TOKEN_RE = AGENT_KEY_RE;
 
-const HELP = `botbuddy wait — one wait command instead of a polling loop (BOT-989)
+export const HELP = `botbuddy wait — one wait command instead of a polling loop (BOT-989)
 
 USAGE
   botbuddy wait [--any] <condition>... [options]
@@ -159,6 +160,8 @@ EXAMPLES
   # after pushing review fixes, wait for the next review comment or a state change
   botbuddy wait --any 'pr-review:repo=bot-buddy/botbuddy-webapp,pr=425' \\
                 'pr-state:repo=bot-buddy/botbuddy-webapp,pr=425' --timeout 3600
+
+${SETUP_BLOCK}
 `;
 
 function parseArgv(argv) {
@@ -630,11 +633,11 @@ function emit(receipt, { versioned = false, maxBytes = null } = {}) {
 // SAME string is written to stderr and the receipt `recovery` field that /waits
 // renders. Keep each to one line and never embed a secret value — names, slots,
 // and env-var names only.
-const RECOVERY = Object.freeze({
+export const RECOVERY = Object.freeze({
   // BOT-1582: $BOTBUDDY_AGENT_KEY (bb_agent_+64hex, renamed from
   // $BOTBUDDY_SESSION_TOKEN) is minted by register_agent; the harness exports it
   // at session start. The legacy var is still accepted for one release.
-  sessionToken: "register_agent → export BOTBUDDY_AGENT_KEY=<session_token> (the harness exports it at session start)",
+  sessionToken: "the tier-3 session token (bb_agent_) is minted by register_agent — export BOTBUDDY_AGENT_KEY=<session_token> (and BOTBUDDY_SESSION_ID=<session_id>); the harness exports both at session start. See docs/agent-connectivity.md",
   // $BOTBUDDY_SESSION_ID is the work-graph session id returned by register_agent.
   sessionId: "register_agent → export BOTBUDDY_SESSION_ID=<session_id> (the work-graph session id from register_agent)",
   // A --token / session-token contradiction: the session token is the whole
@@ -962,7 +965,7 @@ export async function runWait(argv) {
         // register a work agent and export its session token.
         if (err.errorCode === "client_key_cannot_wait") {
           process.stderr.write(
-            "botbuddy wait: a client key (botbuddy login) cannot arm a wait — register_agent, export BOTBUDDY_AGENT_KEY=<session_token>, then re-run\n",
+            "botbuddy wait: a tier-1 client key (bb_cli_, botbuddy login) cannot arm a wait — you need the tier-3 session token: register_agent, export BOTBUDDY_AGENT_KEY=<session_token>, then re-run\n",
           );
           emitReceipt({
             schema_version: 1,