@botbuddy/cli 1.20.0 → 1.21.1

package/package.json

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

package/src/agent-key.mjs

@@ -0,0 +1,29 @@
+// BOT-1582 — the per-session agent key the CLI presents to the relay for
+// `botbuddy wait`/`run`/`test`/`pw`.
+//
+// register_agent mints this token (bound to the work-graph session it returns)
+// and the relay derives agent, tenant, and the arming session from it, so a
+// session that exports it needs no --profile/--session-id/--token.
+//
+// Prefix: `bb_agent_` + 64 lowercase hex, mirroring the server's SESSION_TOKEN_RE
+// (supabase/functions/_shared/sessionToken.ts). The BOT-1572 `bb_sess_` shape is
+// accepted as a legacy alias for one release (its hash is already on `sessions`).
+// This is a SHAPE check only — authorization is the server's hashed lookup.
+export const AGENT_KEY_RE = /^bb_(agent|sess)_[0-9a-f]{64}$/;
+
+// BOT-1582: the env var was renamed BOTBUDDY_SESSION_TOKEN → BOTBUDDY_AGENT_KEY.
+// The new name wins; the old one is honoured for one release so a session that
+// still exports it keeps working. Returns null when neither is set.
+//
+// An EMPTY/blank value counts as unset (not as a present-but-empty token): an env
+// template that declares BOTBUDDY_AGENT_KEY="" while a valid BOTBUDDY_SESSION_TOKEN
+// is still exported must fall through to the legacy name, or the one-release
+// compatibility guarantee breaks (Codex P2). So trim and skip blanks rather than
+// `??`, which would stop at the empty string.
+export function readAgentKeyEnv(env = process.env) {
+  const first = typeof env.BOTBUDDY_AGENT_KEY === "string" ? env.BOTBUDDY_AGENT_KEY.trim() : "";
+  if (first) return env.BOTBUDDY_AGENT_KEY;
+  const legacy = typeof env.BOTBUDDY_SESSION_TOKEN === "string" ? env.BOTBUDDY_SESSION_TOKEN.trim() : "";
+  if (legacy) return env.BOTBUDDY_SESSION_TOKEN;
+  return null;
+}

package/src/credential-kinds.mjs

@@ -17,11 +17,15 @@ export const CREDENTIAL_PREFIXES = [
   { prefix: "mcp_at_", kind: "oauth", label: "OAuth owner token" },
   { prefix: "bb_pat_", kind: "pat", label: "personal access token" },
   { prefix: "bb_cli_", kind: "cli", label: "client key" },
-  // BOT-1573/1582 transition: TODAY every live bb_agent_ secret is an older
-  // shared service carrier (this PR keeps them authenticating), and the actual
-  // per-session agent token is bb_sess_ (BOT-1572). So bb_agent_ classifies as
-  // the carrier — matching the UI adapter — NOT as an agent. Once BOT-1582 makes
-  // register_agent MINT bb_agent_, this flips to the agent kind.
+  // BOT-1573/1582 transition: bb_agent_ is now BOTH the per-session agent token
+  // (BOT-1582 renamed it from bb_sess_) AND the older shared service carrier, so
+  // the prefix ALONE can no longer tell them apart. Classification is display
+  // only (never auth), and mislabelling a live carrier as an agent is worse than
+  // the reverse, so bb_agent_ stays classified as the carrier — matching the UI
+  // adapter. bb_sess_ (in-flight BOT-1572 tokens, accepted one release) is the
+  // one unambiguously-a-session shape, so it keeps the agent kind. A
+  // shape-independent way to name a live bb_agent_ session token is deferred to
+  // the taxonomy/status work (BOT-1573).
   { prefix: "bb_agent_", kind: "svc", label: "carrier (legacy)" },
   { prefix: "bb_sess_", kind: "agent", label: "agent (session)" },
   { prefix: "bb_ci_", kind: "ci", label: "CI key" },

package/src/pw/coordinator.mjs

@@ -15,7 +15,7 @@ function laneCoordinator(kind, call, agentId) {
   return { kind, async status({ host, slot }) { const result = await call("list_resources", { host, subtype: "playwright_lane" }); const list = Array.isArray(result) ? result : result.resources ?? []; const resource = list.find((item) => item.name === `playwright_lane:${host}:${slot}` || String(item.slot) === String(slot)); /* BOT-1490: canonical_host is a TOP-LEVEL field the server echoes even on an empty page (not-held lane); owner_is_caller is per-row. Older servers send neither → null. */ const canonicalHost = (result && !Array.isArray(result) ? result.canonical_host : null) ?? null; return resource ? { held: resource.status !== "free", heldBy: resource.owner_agent_id ?? null, heldByName: resource.agents?.name ?? null, host: resource.host ?? null, name: resource.name ?? null, slot: resource.slot ?? null, canonicalHost, ownerIsCaller: resource.owner_is_caller ?? null } : { held: false, heldBy: null, heldByName: null, host: null, name: null, slot: null, canonicalHost, ownerIsCaller: null }; }, async emit(event) { await call("record_lane_event", event); }, agentId };
 }
 
-// BOT-1572: authenticate lock verification with a per-session `bb_sess_` token —
+// BOT-1572/1582: authenticate lock verification with a per-session `bb_agent_` token —
 // the server resolves it to the session agent (mcp-server authenticateAgent), so
 // `list_resources`/`record_lane_event` run AS the session, and holder matching
 // rides on the server's `owner_is_caller`. No machine profile is required.

package/src/pw/run.mjs

@@ -8,6 +8,7 @@ import { resolveAgentProfile } from "../wait-profile.mjs";
 import { readProfileIdentity } from "../agent-credential-store.mjs";
 import { loadConfig, getConfig } from "../config.mjs";
 import { VERSION } from "../version.mjs";
+import { readAgentKeyEnv } from "../agent-key.mjs";
 // BOT-1488: canonicalize the raw hostname the SAME way acquire_resources does
 // server-side, so the lane name bb-pw builds/matches/prints is the one the lock
 // kernel actually stored ("jonos-mbp:8", not "Jonos-MBP.localdomain:8").
@@ -23,18 +24,19 @@ function redact(value, secretValues = []) { return secretValues.reduce((text, se
 async function readRegisteredAgentId() { try { await loadConfig(); const id = getConfig()?.agent_id; return typeof id === "string" && id ? id : null; } catch { return null; } }
 async function gate({ env, host, lane, deps }) {
   if (env.BB_PW_NO_LOCK === "1") return { allowed: true };
-  // BOT-1572: a per-session `bb_sess_` token authenticates lock verification AS
-  // the session agent — no machine profile needed. It takes precedence over the
+  // BOT-1572/1582: a per-session `bb_agent_` token authenticates lock verification
+  // AS the session agent — no machine profile needed. It takes precedence over the
   // profile path; holder matching then rides on the server's owner_is_caller
   // (plus any local session/registered agent id). The profile path stays intact
-  // for a session that has not adopted the token.
-  const sessionToken = deps.sessionToken ?? env.BOTBUDDY_SESSION_TOKEN ?? null;
+  // for a session that has not adopted the token. $BOTBUDDY_AGENT_KEY is the norm
+  // ($BOTBUDDY_SESSION_TOKEN still accepted for one release).
+  const sessionToken = deps.sessionToken ?? readAgentKeyEnv(env);
   const sessionAgentId = deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null;
   const registeredAgentId = await (deps.readSessionAgentId ?? readRegisteredAgentId)();
   let coordinator, selfAgentIds, callerId;
   if (sessionToken) {
     coordinator = deps.coordinator ?? createSessionTokenCoordinator({ token: sessionToken, fetchImpl: deps.fetch });
-    if (coordinator.kind === "unverified") return { allowed: false, message: "bb-pw: $BOTBUDDY_SESSION_TOKEN is malformed. Re-register the agent, or set BB_PW_NO_LOCK=1 for local-only work." };
+    if (coordinator.kind === "unverified") return { allowed: false, message: "bb-pw: $BOTBUDDY_AGENT_KEY is malformed. Re-register the agent, or set BB_PW_NO_LOCK=1 for local-only work." };
     selfAgentIds = new Set([sessionAgentId, registeredAgentId, coordinator.agentId].filter(Boolean));
     callerId = coordinator.agentId ?? sessionAgentId ?? "session-token";
   } else {
@@ -99,7 +101,7 @@ export async function runPw(argv, deps = {}) {
 async function runPwInner(argv, deps = {}) {
   const env = deps.env ?? process.env, stdout = deps.stdout ?? process.stdout, stderr = deps.stderr ?? process.stderr; let args = [...argv]; if (["--help", "-h"].includes(args[0])) { help(stdout); return 0; }
   if (["--version", "-v"].includes(args[0])) { stdout.write(`${versionLine()}\n`); return 0; }
-  // BOT-1572 (AC-8): --session-token / $BOTBUDDY_SESSION_TOKEN is accepted as a
+  // BOT-1572/1582 (AC-8): --session-token / $BOTBUDDY_AGENT_KEY is accepted as a
   // session identity alongside --session-id, so a token-armed session need not
   // pass an id. Holder matching still rides on the server's owner_is_caller and
   // the resolved agent ids (gate()).

package/src/run.mjs

@@ -14,6 +14,7 @@ import { spawn } from "child_process";
 import { fileURLToPath } from "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";
 
 export const RUN_SCHEMA_VERSION = 1;
 export const EXIT = Object.freeze({ OK: 0, INVALID: 4, BACKEND: 5, INTERNAL: 7 });
@@ -24,14 +25,16 @@ const MAX_CAPTURE_BYTES = 8_192;
 // Well under AC-3's 5 s so a begin/verdict is visible within the window.
 const LANE_FLUSH_INTERVAL_MS = 2_500;
 
-// BOT-1572: identical to the server's session-token shape check (bb_sess_ + 64 hex).
-const SESSION_TOKEN_RE = /^bb_sess_[0-9a-f]{64}$/;
+// 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.
+const SESSION_TOKEN_RE = AGENT_KEY_RE;
 
 export function parseRunArgs(argv, env = process.env) {
-  // BOT-1572 (AC-8): $BOTBUDDY_SESSION_TOKEN authenticates the run and carries its
-  // session, so --session-id becomes optional (the relay derives it). $BOTBUDDY_SESSION_ID
+  // BOT-1572/1582 (AC-8): $BOTBUDDY_AGENT_KEY authenticates the run and carries its
+  // 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: env.BOTBUDDY_SESSION_TOKEN ?? null, 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, json: false };
   const errors = [];
   const separator = argv.indexOf("--");
   const flags = separator === -1 ? argv : argv.slice(0, separator);
@@ -66,8 +69,8 @@ export function parseRunArgs(argv, env = process.env) {
   // BOT-1572: a session token stands in for --session-id (the backend derives the
   // 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_SESSION_TOKEN must match bb_sess_<64 hex>");
-  if (!opts.sessionId && !opts.sessionToken) errors.push("--session-id is required (from register_agent), or set $BOTBUDDY_SESSION_TOKEN");
+  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.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");

package/src/test-lane.mjs

@@ -21,6 +21,7 @@ import { execFileSync } from "node:child_process";
 
 import { EXIT, launchRun, receiptPath, DEFAULT_TIMEOUT_SECONDS } from "./run.mjs";
 import { callToolJson } from "./api.mjs";
+import { readAgentKeyEnv } from "./agent-key.mjs";
 
 // EXIT.{OK,INVALID,BACKEND,INTERNAL} plus a --wait timeout code (AC-9).
 export const EXIT_TEST = Object.freeze({ ...EXIT, TIMEOUT: 2 });
@@ -36,9 +37,10 @@ const LANE_KIND_SET = new Set(LANE_KINDS);
 export function parseTestArgs(argv, { env = process.env } = {}) {
   const opts = {
     sessionId: env.BOTBUDDY_SESSION_ID ?? null,
-    // BOT-1572 (AC-8): a session token stands in for --session-id; it flows to the
-    // sub-invoked `run`/`wait` which derive the session from it.
-    sessionToken: env.BOTBUDDY_SESSION_TOKEN ?? null,
+    // BOT-1572/1582 (AC-8): a session token stands in for --session-id; it flows to
+    // the sub-invoked `run`/`wait` which derive the session from it. $BOTBUDDY_AGENT_KEY
+    // is the norm ($BOTBUDDY_SESSION_TOKEN still accepted for one release).
+    sessionToken: readAgentKeyEnv(env),
     environment: "local",
     ticket: null, pr: null, repo: null,
     laneKind: null,
@@ -136,8 +138,8 @@ export function defaultGitInfo({ cwd = process.cwd(), ticket = null, pr = null,
 // The production lane launcher: run the lane through the durable `botbuddy run`
 // worker, carrying the telemetry env into its detached child.
 async function defaultLaunchLane({ command, sessionId, sessionToken, environment, expectedDurationSeconds, childEnv, testRun, cwd, call }) {
-  // BOT-1572: pass --session-id only when a plain id is used; a token-only lane
-  // relies on the inherited $BOTBUDDY_SESSION_TOKEN (and an explicit --session-token
+  // BOT-1572/1582: pass --session-id only when a plain id is used; a token-only lane
+  // relies on the inherited $BOTBUDDY_AGENT_KEY (and an explicit --session-token
   // so the child never falls back to a machine credential).
   const argv = [
     ...(sessionId ? ["--session-id", sessionId] : []),
@@ -150,7 +152,7 @@ async function defaultLaunchLane({ command, sessionId, sessionToken, environment
 }
 
 function waitCommand(testRunId, sessionId, sessionToken) {
-  // BOT-1572: a token-armed session runs the wait with only $BOTBUDDY_SESSION_TOKEN.
+  // BOT-1572/1582: a token-armed session runs the wait with only $BOTBUDDY_AGENT_KEY.
   const idFlag = sessionId && !sessionToken ? ` --session-id ${sessionId}` : "";
   return `botbuddy wait 'test-run:id=${testRunId}'${idFlag} --heartbeat`;
 }
@@ -169,7 +171,7 @@ export async function launchTestLane(argv, {
     return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors }) };
   }
   if (!opts.sessionId && !opts.sessionToken) {
-    process.stderr.write("botbuddy test: --session-id is required (or set $BOTBUDDY_SESSION_ID or $BOTBUDDY_SESSION_TOKEN)\n");
+    process.stderr.write("botbuddy test: --session-id is required (or set $BOTBUDDY_SESSION_ID or $BOTBUDDY_AGENT_KEY)\n");
     return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors: ["--session-id is required"] }) };
   }
 

package/src/wait-profile.mjs

@@ -20,6 +20,19 @@ export function getAgentProfile(name) {
   return PROFILES[name] ?? null;
 }
 
+// BOT-1593: when no profile is named (no --profile, no .botbuddy-agent.json) but
+// EXACTLY ONE supported profile's credential env var is populated, that slot is the
+// unambiguous profile. Used only by best-effort setup-error telemetry to attribute a
+// `profile_required` failure that still has a usable env bearer — never for the wait
+// itself. Returns the profile name, or null when zero or more than one slot is set
+// (ambiguous → no attribution). Reads env only; never touches the Keychain.
+export function findEnvProfile(env = process.env) {
+  const populated = Object.entries(PROFILES).filter(
+    ([, { tokenEnv }]) => typeof env[tokenEnv] === "string" && env[tokenEnv].length > 0,
+  );
+  return populated.length === 1 ? populated[0][0] : null;
+}
+
 export async function findProfileName(cwd) {
   let dir = cwd;
   const root = parse(dir).root;

package/src/wait.mjs

@@ -14,17 +14,18 @@
 // Run     botbuddy wait --help for the condition grammar.
 
 import { EXIT, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt, formatPrReviewSnapshotWarnings } from "./wait-core.mjs";
-import { resolveAgentProfile, withPrincipalReceipt, PROFILE_FILE } from "./wait-profile.mjs";
+import { resolveAgentProfile, getAgentProfile, findProfileName, findEnvProfile, withPrincipalReceipt, PROFILE_FILE } from "./wait-profile.mjs";
 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";
 
 // A protocol is deliberately distinct from package semver: compatible pinned
 // clients keep working until the server raises this minimum, while a stale
 // implementation gets a typed, safe upgrade instruction.
 // BOT-1554: protocol 2 makes --session-id mandatory for every non-timer wait (the
 // server keeps MINIMUM_WAIT_PROTOCOL=1 so pre-2 installs are not 426'd).
-// BOT-1572: protocol 3 — a $BOTBUDDY_SESSION_TOKEN (bb_sess_) authenticates the
+// BOT-1572/1582: protocol 3 — a $BOTBUDDY_AGENT_KEY (bb_agent_) authenticates the
 // wait on its own; no profile / --session-id / --token needed (the relay derives
 // agent, tenant, and session from the token). Falls back to protocol-2 behaviour
 // when no session token is present.
@@ -33,8 +34,9 @@ const CLI_UPGRADE_COMMAND = latestPublicCliCommand("wait");
 const MIN_RECEIPT_MAX_BYTES = 512;
 // BOT-1554: identical to the server's session-id shape check.
 const SESSION_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-// BOT-1572: identical to the server's session-token shape check (bb_sess_ + 64 hex).
-const SESSION_TOKEN_RE = /^bb_sess_[0-9a-f]{64}$/;
+// 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.
+const SESSION_TOKEN_RE = AGENT_KEY_RE;
 
 const HELP = `botbuddy wait — one wait command instead of a polling loop (BOT-989)
 
@@ -164,10 +166,11 @@ function parseArgv(argv) {
     // BOT-1467: attribute this wait to the arming session's agent (the id from
     // register_agent) instead of the tenant-bound profile agent. Env fallback.
     sessionId: process.env.BOTBUDDY_SESSION_ID || null,
-    // BOT-1572: the per-session token. When present it is the ONLY credential —
-    // profile, --session-id, and --token are unnecessary. Env is the norm; the
-    // flag is for tests/overrides.
-    sessionToken: process.env.BOTBUDDY_SESSION_TOKEN || null,
+    // BOT-1572/1582: the per-session token. When present it is the ONLY credential —
+    // profile, --session-id, and --token are unnecessary. $BOTBUDDY_AGENT_KEY is
+    // the norm ($BOTBUDDY_SESSION_TOKEN still accepted for one release); the flag
+    // is for tests/overrides.
+    sessionToken: readAgentKeyEnv(process.env),
     help: false,
   };
   for (let i = 0; i < argv.length; i++) {
@@ -659,14 +662,15 @@ function profileErrorReceipt(profile, error) {
 // renders. Keep each to one line and never embed a secret value — names, slots,
 // and env-var names only.
 const RECOVERY = Object.freeze({
-  // $BOTBUDDY_SESSION_TOKEN (bb_sess_+64hex) is minted by register_agent; the
-  // harness exports it at session start.
-  sessionToken: "register_agent → export BOTBUDDY_SESSION_TOKEN=<session_token> (the harness exports it at session start)",
+  // 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)",
   // $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
   // credential, so drop --token (never advise also setting a session id here).
-  sessionTokenConflict: "unset --token — $BOTBUDDY_SESSION_TOKEN is the whole credential (protocol 3)",
+  sessionTokenConflict: "unset --token — $BOTBUDDY_AGENT_KEY is the whole credential (protocol 3)",
   // Grammar/condition errors point at the help and the canonical doc.
   conditions: "check the condition grammar: botbuddy wait --help / docs/agent-wait.md",
 });
@@ -689,11 +693,139 @@ function profileResolutionRecovery(errorCode) {
 // supported path is exporting that same profile env var directly, which
 // resolveAgentProfile reads. (The 0600 config.json store is the owner login
 // token's, not a profile credential's — a wait cannot consume it.)
-const HUMAN_PAT_NOTE = "human PATs (BOTBUDDY_AGENT_KEY / BOTBUDDY_AGENT_API_KEY) are not valid for waits";
+// BOT-1582: $BOTBUDDY_AGENT_KEY is now the per-session token var (valid for
+// waits), so it is no longer named here; BOTBUDDY_AGENT_API_KEY remains a human
+// PAT that never authenticates a wait.
+const HUMAN_PAT_NOTE = "human PATs (e.g. BOTBUDDY_AGENT_API_KEY) are not valid for waits";
 function profileCredentialRecovery(profile) {
   return `${profileRecovery(profile)} (stores $${profile.tokenEnv} in the macOS Keychain; on a non-Keychain host export $${profile.tokenEnv} directly); ${HUMAN_PAT_NOTE}`;
 }
 
+// BOT-1593: emit ONE secret-free sensor event per setup/auth/parameter failure,
+// so the maintainer can see which onboarding gap agents hit most (and whether the
+// BOT-1590 recovery copy is reducing repeats). Best-effort AND time-bounded — the
+// same stance as docker-hygiene's reportReliability: the receipt has already been
+// written to stdout by the time this runs, so a slow/failing POST must never delay
+// the agent's wake or change the exit path. A 2 s AbortController caps the fetch;
+// timeout / network error / non-2xx are all a silent drop (we never read the body).
+//
+// Never posts without a usable bearer, and never on the session-token path: the
+// ingest endpoint authenticates only allowed_users PATs or agent keys
+// (edgeAuth.ts) — a bb_sess_ session token 401s, so we don't spend the round-trip.
+// The event carries NO secret by construction: no token (only the bearer header,
+// never the body), no session id, no condition params/values, no hostnames/paths —
+// only error code, exit code, condition TYPES, auth path, profile name, cli version.
+const SENSOR_TELEMETRY_TIMEOUT_MS = 2000;
+
+async function reportSetupError(opts, { error, exitCode, conditions }) {
+  // Never on the session-token path. A bb_agent_/bb_sess_ SESSION token cannot
+  // authenticate at sensor-ingest (edgeAuth resolves only PATs / agent keys), so it
+  // would only 401. Discriminate by the credential's SOURCE, not its shape: a
+  // session token arrives only via $BOTBUDDY_AGENT_KEY / --session-token
+  // (opts.sessionToken), whereas a resolved PROFILE credential may legitimately be a
+  // legacy bb_agent_ CARRIER key that ingest CAN authenticate — the two share a shape
+  // (BOT-1582), so a shape check would wrongly drop the carrier case (Codex P1).
+  if (opts.sessionToken) return;
+
+  // Time-box the WHOLE operation — the implicit-profile file lookup AND the fetch —
+  // against one 2 s abort, the reportReliability idiom. findProfileName walks up the
+  // directory tree with async readFile; on a slow/unresponsive network or FUSE mount
+  // that read can hang, and it runs on fail-fast paths right before process.exit, so
+  // starting the timer FIRST and racing the whole worker keeps a nominally fail-fast
+  // error inside the advertised bound (Codex P2). On expiry the race resolves and we
+  // return; the orphaned lookup is reaped by the imminent process.exit.
+  const ac = new AbortController();
+  let timer;
+  const TIMED_OUT = Symbol("sensor-telemetry-timeout");
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => { ac.abort(); resolve(TIMED_OUT); }, SENSOR_TELEMETRY_TIMEOUT_MS);
+  });
+  try {
+    await Promise.race([sendSetupErrorEvent(opts, { error, exitCode, conditions }, ac.signal), timeout]);
+  } catch {
+    // Best-effort: an AbortError (2 s timeout) or any transport/lookup error drops.
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function sendSetupErrorEvent(opts, { error, exitCode, conditions }, signal) {
+  // Resolve a bearer WITHOUT ever touching the Keychain. This telemetry is
+  // best-effort and runs on fail-fast paths right before process.exit; a Keychain
+  // read (readProfileCredential → `security find-generic-password`) can block/prompt
+  // on a locked or non--A item AND takes no abort signal, so it would leave an
+  // orphaned `security` child or an auth dialog behind after the wait exits (Codex
+  // P2). So only ever REUSE a token the main flow already resolved (opts.token) or
+  // read the profile's env var directly — never a fresh Keychain lookup.
+  //
+  // Discover the caller's profile — flag or .botbuddy-agent.json — INDEPENDENTLY of
+  // whether --token was supplied, so profile/tenant are attached for attribution and
+  // dual-member disambiguation even on the documented --token override (without it a
+  // multi-tenant bearer is rejected tenant_ambiguous and the event is lost) (Codex P2).
+  // The env-slot inference (findEnvProfile) applies ONLY when there is no explicit
+  // token — inferring a tenant for an explicit --token bearer could attach one it is
+  // not a member of (→ tenant_forbidden drop).
+  let profileName = opts.agentProfile?.name ?? opts.profile ?? null;
+  if (!profileName) {
+    try {
+      profileName = await findProfileName(process.cwd());
+    } catch {
+      profileName = null; // a malformed .botbuddy-agent.json → no profile
+    }
+    if (!profileName && !opts.token) profileName = findEnvProfile(process.env);
+  }
+  // Only a KNOWN profile contributes a name/tenant/env-var — an unknown/oversized/
+  // sensitive raw --profile value (which the token path never validates) must not
+  // ride the secret-free event, matching the wait path's getAgentProfile rejection
+  // (Codex P2).
+  const known = profileName ? getAgentProfile(profileName) : null;
+  let token = opts.token;
+  if (!token && known) token = process.env[known.tokenEnv] || null;
+  // The only unusable bearer is none at all. A credential the RELAY just rejected
+  // (revoked/unauthorized) will 401 at ingest too and drop silently — best-effort, by
+  // design; a valid-key failure (session_id_required, wait_actor_required, wrong-tenant)
+  // authenticates and records (Codex P1: this is an accepted limitation, see docs).
+  if (!token) return;
+  // "profile" auth path whenever a profile was discovered (flag/file/env slot), even
+  // with a --token override; "explicit_token" only for a bare --token, no profile.
+  const explicit = !!opts.token && !profileName;
+  const tenant = opts.agentProfile?.tenant ?? known?.tenant ?? null;
+  const safeProfile = known ? profileName : null;
+  // Omit the explicit tenant for a wrong-tenant credential: the profile's expected
+  // tenant is NOT one the bearer belongs to, and sensor-ingest's resolveWriteTenant
+  // rejects an unauthorized explicit tenant (tenant_forbidden) → the event would drop.
+  // Without it the server resolves the bearer's ACTUAL tenant and the row records
+  // there instead (Codex P1). Every other error's tenant equals the credential's own.
+  const includeTenant = tenant && error !== "profile_credential_wrong_tenant";
+  const conditionTypes = Array.isArray(conditions)
+    ? [...new Set(conditions.map((c) => c.type))].sort()
+    : [];
+  const event = {
+    ...(includeTenant ? { tenant } : {}),
+    source: "bb-wait",
+    kind: "wait_setup_error",
+    dedupe_key: `bb-wait:${error}:${crypto.randomUUID()}`,
+    occurred_at: new Date().toISOString(),
+    payload: {
+      error,
+      exit_code: exitCode,
+      condition_types: conditionTypes,
+      auth_path: explicit ? "explicit_token" : "profile",
+      profile: safeProfile,
+      cli_version: VERSION,
+    },
+  };
+  await fetch(`${opts.url.replace(/\/$/, "")}/sensor-ingest`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(event),
+    signal,
+  });
+}
+
 export async function runWait(argv) {
   const opts = parseArgv(argv);
   const emitReceipt = (receipt, options = {}) => emit(receipt, {
@@ -720,6 +852,9 @@ export async function runWait(argv) {
     for (const e of errors) process.stderr.write(`bb-wait: invalid condition '${e.spec}': ${e.message}\n`);
     process.stderr.write(`bb-wait: ${RECOVERY.conditions}\n`);
     emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_conditions", errors, recovery: RECOVERY.conditions });
+    // BOT-1593: condition_types is [] on a grammar failure (the parsed set is
+    // partial/empty and is caller data regardless).
+    await reportSetupError(opts, { error: "invalid_conditions", exitCode: EXIT.INVALID, conditions: [] });
     process.exit(EXIT.INVALID);
   }
 
@@ -737,20 +872,22 @@ export async function runWait(argv) {
   const deadlineMs = Date.now() + timeoutSec * 1000;
 
   const needsRelay = conditions.some((c) => c.type !== "timer");
-  // BOT-1572: a $BOTBUDDY_SESSION_TOKEN authenticates the wait on its own. When
+  // BOT-1572/1582: a $BOTBUDDY_AGENT_KEY authenticates the wait on its own. When
   // present it supersedes the profile + --session-id path entirely: the relay
   // derives agent, tenant, and session from the token. --profile / --session-id
   // are simply ignored; a conflicting explicit --token (a DIFFERENT credential)
   // is a contradiction and is rejected.
   if (needsRelay && opts.sessionToken) {
     if (!SESSION_TOKEN_RE.test(opts.sessionToken)) {
-      process.stderr.write(`botbuddy wait: $BOTBUDDY_SESSION_TOKEN must match bb_sess_<64 hex>; ${RECOVERY.sessionToken}\n`);
+      process.stderr.write(`botbuddy wait: $BOTBUDDY_AGENT_KEY must match bb_agent_<64 hex>; ${RECOVERY.sessionToken}\n`);
       emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_token", recovery: RECOVERY.sessionToken });
+      await reportSetupError(opts, { error: "invalid_session_token", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     if (opts.token && opts.token !== opts.sessionToken) {
-      process.stderr.write(`botbuddy wait: --token conflicts with $BOTBUDDY_SESSION_TOKEN; ${RECOVERY.sessionTokenConflict}\n`);
+      process.stderr.write(`botbuddy wait: --token conflicts with $BOTBUDDY_AGENT_KEY; ${RECOVERY.sessionTokenConflict}\n`);
       emitReceipt({ schema_version: 1, outcome: "error", error: "session_token_conflict", recovery: RECOVERY.sessionTokenConflict });
+      await reportSetupError(opts, { error: "session_token_conflict", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     opts.useSessionToken = true;
@@ -770,11 +907,13 @@ export async function runWait(argv) {
         error: "session_id_required",
         recovery: RECOVERY.sessionId,
       });
+      await reportSetupError(opts, { error: "session_id_required", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     if (!SESSION_UUID.test(opts.sessionId)) {
       process.stderr.write(`botbuddy wait: --session-id must be a uuid (got '${opts.sessionId}'); ${RECOVERY.sessionId}\n`);
       emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_agent", detail: "session_id must be a uuid", recovery: RECOVERY.sessionId });
+      await reportSetupError(opts, { error: "invalid_session_agent", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     try {
@@ -787,6 +926,7 @@ export async function runWait(argv) {
       const recovery = profileResolutionRecovery(code);
       process.stderr.write(`bb-wait: ${err.message}; ${recovery}\n`);
       emitReceipt({ schema_version: 1, outcome: "error", error: code, recovery });
+      await reportSetupError(opts, { error: code, exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     opts.token = opts.agentProfile.token;
@@ -795,6 +935,10 @@ export async function runWait(argv) {
         `botbuddy wait: profile '${opts.agentProfile.name}' has no tenant-bound agent credential; run ${profileCredentialRecovery(opts.agentProfile)}\n`,
       );
       emitReceipt(profileErrorReceipt(opts.agentProfile, "profile_required"));
+      // No credential resolved (opts.token is null here), so reportSetupError has
+      // no bearer to authenticate with and self-skips — call it for allowlist
+      // symmetry; it is a no-op until a token exists.
+      await reportSetupError(opts, { error: "profile_required", exitCode: EXIT.AUTH, conditions });
       process.exit(EXIT.AUTH);
     }
   }
@@ -909,14 +1053,17 @@ export async function runWait(argv) {
         ]);
         if (opts.useSessionToken || SESSION_TOKEN_ERRORS.has(err.errorCode)) {
           process.stderr.write(
-            `botbuddy wait: session token rejected (${err.errorCode || "unauthorized"}) — re-register the agent and export the new $BOTBUDDY_SESSION_TOKEN\n`,
+            `botbuddy wait: session token rejected (${err.errorCode || "unauthorized"}) — re-register the agent and export the new $BOTBUDDY_AGENT_KEY\n`,
           );
           emitReceipt(withPrincipalReceipt({
             schema_version: 1,
             outcome: "error",
             error: err.errorCode || "unauthorized",
-            recovery: "register_agent → export BOTBUDDY_SESSION_TOKEN=<session_token>",
+            recovery: "register_agent → export BOTBUDDY_AGENT_KEY=<session_token>",
           }, opts.agentProfile, { sessionTenant, agentId: registeredAgentId, sessionId: registeredSessionId }));
+          // Session-token path → reportSetupError self-skips (a bb_sess_ bearer
+          // ingest cannot authenticate); called for allowlist symmetry.
+          await reportSetupError(opts, { error: err.errorCode || "unauthorized", exitCode: EXIT.AUTH, conditions });
           process.exit(EXIT.AUTH);
         }
         // BOT-1554: these are all SESSION-IDENTITY failures — the supplied session id
@@ -944,11 +1091,13 @@ export async function runWait(argv) {
             ...(err.carrierAgentId ? { carrier_agent_id: err.carrierAgentId } : {}),
             recovery: "register_agent → export BOTBUDDY_SESSION_ID=<new session_id>",
           }, opts.agentProfile, { sessionTenant: opts.agentProfile?.tenant ?? sessionTenant ?? null, agentId: null }));
+          await reportSetupError(opts, { error: err.errorCode, exitCode: EXIT.AUTH, conditions });
           process.exit(EXIT.AUTH);
         }
         const error = typedProfileError(err.errorCode);
         process.stderr.write(`botbuddy wait: profile authentication failed (${error}); run ${profileCredentialRecovery(opts.agentProfile)}\n`);
         emitReceipt(profileErrorReceipt(opts.agentProfile, error));
+        await reportSetupError(opts, { error, exitCode: EXIT.AUTH, conditions });
         process.exit(EXIT.AUTH);
       }
       if (err && err.cap) {