@botbuddy/cli 1.30.0 → 1.30.1

package/src/pw/run.mjs

@@ -7,7 +7,8 @@ import { canonicalizeHostString } from "./host.mjs";
 import { resolveAgentBinding } from "../wait-profile.mjs";
 import { loadConfig, getConfig } from "../config.mjs";
 import { VERSION } from "../version.mjs";
-import { readAgentKeyEnv, AGENT_KEY_RE } from "../agent-key.mjs";
+import { readAgentSessionTokenEnv, AGENT_KEY_RE } from "../agent-key.mjs";
+import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredential } from "../agent-session.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,19 +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/1582: a per-session `bb_agent_` token authenticates lock verification
+  // BOT-1649: a per-session `bb_sess_` token authenticates lock verification
   // AS the session agent — the server resolves it, holder matching rides on
-  // owner_is_caller (plus any local session/registered agent id). $BOTBUDDY_AGENT_KEY
-  // is the norm ($BOTBUDDY_SESSION_TOKEN still accepted for one release).
+  // owner_is_caller (plus any local session/registered agent id).
+  // $BOTBUDDY_AGENT_SESSION_TOKEN is canonical; the former names remain aliases.
   //
   // BOT-1608: the retired profile-identity path is gone (its `agent-profiles.json`
   // store no longer exists). When no session token is exported, fall back to the
   // worktree binding's mcp_env credential (the `bb_mcp_` key from `.mcp.json`) —
   // it authenticates the status call the same way and matching still rides on the
   // server's owner_is_caller.
-  const sessionToken = deps.sessionToken ?? readAgentKeyEnv(env);
+  const sessionToken = deps.sessionToken ?? readAgentSessionTokenEnv(env);
   if (sessionToken && !AGENT_KEY_RE.test(sessionToken)) {
-    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.)" };
+    return { allowed: false, message: "bb-pw: the supplied session override is malformed. Remove it and run bb setup from this project worktree, then retry. 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 +50,7 @@ async function gate({ env, host, lane, deps }) {
       } catch { token = null; }
     }
     if (!token) {
-      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.)" };
+      return { allowed: false, message: "bb-pw: no worktree session — run bb setup from this project worktree, then retry. See docs/agent-connectivity.md. (BB_PW_NO_LOCK=1 runs local-only, unlocked.)" };
     }
     coordinator = createSessionTokenCoordinator({ token, fetchImpl: deps.fetch });
   }
@@ -82,7 +83,7 @@ async function gate({ env, host, lane, deps }) {
     const holderName = status.heldByName ? ` (${status.heldByName})` : "";
     return { allowed: false, message: `bb-pw: lane lock ${foundLaneName} is held by ${holder}${holderName}, not you (caller ${callerId}). Acquire it first or set BB_PW_NO_LOCK=1 for local-only work.` };
   } catch (error) {
-    return { allowed: false, message: `bb-pw: could not verify lane lock ${laneName} (${error.message}). Set BB_PW_NO_LOCK=1 for local-only work.` };
+    return { allowed: false, errorCode: error?.code ?? null, message: `bb-pw: could not verify lane lock ${laneName} (${error.message}). Set BB_PW_NO_LOCK=1 for local-only work.` };
   }
 }
 // BOT-1522: a stale global install (1.6.1 on the reporting host) replayed the
@@ -101,16 +102,41 @@ 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/1582 (AC-8): --session-token / $BOTBUDDY_AGENT_KEY is accepted as a
+  // BOT-1649: --agent-session-token / $BOTBUDDY_AGENT_SESSION_TOKEN is canonical;
+  // legacy flags and env aliases remain 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()).
-  while (args[0] === "--tenant" || args[0] === "--session-id" || args[0] === "--session-token") { const flag = args[0]; if (!args[1]) { stderr.write(`bb-pw: ${flag} needs a value\n`); return 2; } deps = flag === "--tenant" ? { ...deps, tenant: args[1] } : flag === "--session-token" ? { ...deps, sessionToken: args[1] } : { ...deps, sessionId: args[1] }; args = args.slice(2); }
+  while (["--tenant", "--session-id", "--agent-session-token", "--agent-key", "--session-token"].includes(args[0])) { const flag = args[0]; if (!args[1]) { stderr.write(`bb-pw: ${flag} needs a value\n`); return 2; } deps = flag === "--tenant" ? { ...deps, tenant: args[1] } : ["--agent-session-token", "--agent-key", "--session-token"].includes(flag) ? { ...deps, sessionToken: args[1] } : { ...deps, sessionId: args[1] }; args = args.slice(2); }
   let plan; try { plan = planInvocation(args, env); } catch (error) { stderr.write(`${error.message}\n`); return 2; }
   const { spawnExec, socketRun } = deps.daemon ?? await import("./daemon.mjs");
   if (plan.scope === "global") { if (plan.mode === "reap") { await (deps.reap ?? (await import("./reap.mjs")).reap)({ env, stdout }); return 0; } if (env.BB_PW_NO_LOCK !== "1") { stderr.write("bb-pw: close-all and kill-all require BB_PW_NO_LOCK=1 because they can affect lanes you do not own.\n"); return 3; } return spawnExec(plan, env); }
+  // Local-only lanes explicitly opt out of lock ownership, so they also need no
+  // remote session mint. Every lock-gated shipped invocation shares the resolver.
+  let managedCredential = null;
+  if (env.BB_PW_NO_LOCK !== "1" && !deps.sessionToken && !readAgentSessionTokenEnv(env) && (!deps.coordinator || deps.resolveCredential)) {
+    try {
+      const credential = await (deps.resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd: deps.cwd ?? process.cwd() });
+      managedCredential = credential;
+      deps = { ...deps, sessionToken: credential.token, sessionId: deps.sessionId ?? credential.sessionId ?? null };
+    } catch (error) {
+      stderr.write(`bb-pw: ${error?.message ?? "agent session unavailable"}. ${error?.code === "client_key_required" ? "Run `bb login` then retry." : "Run `bb doctor --fix` then retry."}\n`);
+      return 3;
+    }
+  }
   const telemetry = deps.telemetry ?? (await import("./telemetry.mjs")).makeTelemetry({ env }); const host = deps.host ?? hostFor(env);
-  const auth = await gate({ env, host, lane: plan.lane, deps }); if (!auth.allowed) { stderr.write(`${auth.message}\n`); return 3; }
+  let auth = await gate({ env, host, lane: plan.lane, deps });
+  // Only an ACTUAL auth rejection carries an errorCode (the coordinator surfaces
+  // the MCP auth code). A plain lock denial (lane held by another agent) returns
+  // allowed:false with NO errorCode and must never rotate the session (Codex round-5).
+  if (!auth.allowed && !deps.coordinator && auth.errorCode != null && isRejectedCachedMcpSession({ auth: true, code: auth.errorCode }, managedCredential?.source, 0)) {
+    await clearAgentState(deps.cwd ?? process.cwd());
+    const credential = await (deps.resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd: deps.cwd ?? process.cwd() });
+    managedCredential = credential;
+    deps = { ...deps, sessionToken: credential.token, sessionId: credential.sessionId ?? deps.sessionId ?? null };
+    auth = await gate({ env, host, lane: plan.lane, deps });
+  }
+  if (!auth.allowed) { stderr.write(`${auth.message}\n`); return 3; }
   // Report the host the lock service actually stored (alias-collapsed), so the
   // status view and lane telemetry match the server, not the local string (AC-4).
   const effHost = auth.canonicalHost ?? host;

package/src/run.mjs

@@ -14,14 +14,15 @@ 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 { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
+import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredential } from "./agent-session.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 });
+export const EXIT = Object.freeze({ OK: 0, AUTH: 3, INVALID: 4, BACKEND: 5, INTERNAL: 7 });
 export const DEFAULT_TIMEOUT_SECONDS = 8 * 60 * 60;
 export const TIMEOUT_GRACE_MS = 5_000;
 const MAX_CAPTURE_BYTES = 8_192;
@@ -30,16 +31,16 @@ const MAX_CAPTURE_BYTES = 8_192;
 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.
+// BOT-1649: the canonical session-token shape is bb_sess_ + 64 hex; bb_agent_
+// remains accepted as a one-release legacy alias.
 const SESSION_TOKEN_RE = AGENT_KEY_RE;
 
 export function parseRunArgs(argv, env = process.env) {
-  // BOT-1572/1582 (AC-8): $BOTBUDDY_AGENT_KEY authenticates the run and carries its
+  // BOT-1649: $BOTBUDDY_AGENT_SESSION_TOKEN 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: readAgentKeyEnv(env), environment: null, category: "validation", kind: "other", expectedDuration: 0, timeout: DEFAULT_TIMEOUT_SECONDS, rerunReason: null, foreground: false, json: false };
+  const opts = { sessionId: env.BOTBUDDY_SESSION_ID ?? null, sessionToken: readAgentSessionTokenEnv(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);
@@ -52,6 +53,8 @@ export function parseRunArgs(argv, env = process.env) {
     const flag = flags[i];
     switch (flag) {
       case "--session-id": opts.sessionId = value(flag, i); i++; break;
+      case "--agent-session-token":
+      case "--agent-key":
       case "--session-token": opts.sessionToken = value(flag, i); i++; break;
       case "--environment": opts.environment = value(flag, i); i++; break;
       case "--category": opts.category = value(flag, i); i++; break;
@@ -75,8 +78,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_AGENT_KEY must match bb_agent_<64 hex>");
-  if (!opts.foreground && !opts.sessionId && !opts.sessionToken) errors.push("--session-id is required (from register_agent), or set $BOTBUDDY_AGENT_KEY");
+  if (opts.sessionToken && !SESSION_TOKEN_RE.test(opts.sessionToken)) errors.push("$BOTBUDDY_AGENT_SESSION_TOKEN must match bb_sess_<64 hex> (bb_agent_ is a legacy alias)");
+  if (!opts.foreground && !opts.sessionId && !opts.sessionToken) errors.push("--session-id is required (from register_agent), or set $BOTBUDDY_AGENT_SESSION_TOKEN");
   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 --");
@@ -228,8 +231,40 @@ function workerInvocation(context) {
   return [process.execPath, [bin, "run", "--worker", context]];
 }
 
-export async function launchRun(argv, { cwd = process.cwd(), spawnImpl = spawn, call = null, childEnv = null, testRun = null } = {}) {
-  const { opts, command, errors } = parseRunArgs(argv);
+export async function launchRun(argv, {
+  cwd = process.cwd(), spawnImpl = spawn, call = null, childEnv = null, testRun = null,
+  resolveCredential = null, env = process.env,
+} = {}) {
+  let effectiveArgv = argv;
+  let parsed = parseRunArgs(effectiveArgv, env);
+  let managedCredential = null;
+  // A local test double owns its credential boundary; production invocations
+  // self-heal when the session credential was not supplied by flag or env.
+  // Keep all other usage failures local and deterministic before minting.
+  const onlyMissingIdentity = parsed.errors.length === 1 && parsed.errors[0].includes("session-id");
+  if (!parsed.opts.foreground && !parsed.opts.sessionId && !parsed.opts.sessionToken
+    && onlyMissingIdentity && (resolveCredential || call === null)) {
+    try {
+      const credential = await (resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd });
+      managedCredential = credential;
+      effectiveArgv = ["--agent-session-token", credential.token, ...argv];
+      parsed = parseRunArgs(effectiveArgv, env);
+    } catch (error) {
+      return {
+        exitCode: EXIT.AUTH,
+        receipt: {
+          schema_version: RUN_SCHEMA_VERSION,
+          outcome: "rejected",
+          error: error?.code ?? "agent_session_unavailable",
+          recovery: error?.code === "client_key_required"
+            ? "run `bb login` to install the durable client key, then retry"
+            : "run `bb doctor --fix` to repair agent authentication, then retry",
+          exit_code: EXIT.AUTH,
+        },
+      };
+    }
+  }
+  const { opts, command, errors } = parsed;
   if (errors.length) return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", errors, exit_code: EXIT.INVALID } };
   // BOT-1572 (AC-8): when a session token is present it is the credential — pin it
   // so register_command authenticates as the session's agent and derives session_id
@@ -238,7 +273,7 @@ export async function launchRun(argv, { cwd = process.cwd(), spawnImpl = spawn,
     ? (t, a) => callToolJson(t, a, { auth: { "x-agent-api-key": opts.sessionToken } })
     : callToolJson);
   const runId = randomUUID();
-  const registration = await effectiveCall("register_command", {
+  const registerArgs = {
     // Omit session_id entirely when only a token is present — the backend derives
     // it. A plain id is still sent (and honoured) when supplied.
     ...(opts.sessionId ? { session_id: opts.sessionId } : {}),
@@ -246,7 +281,19 @@ export async function launchRun(argv, { cwd = process.cwd(), spawnImpl = spawn,
     command_hash: commandHash(command), environment_hash: environmentHash(cwd, opts.environment),
     environment: opts.environment, command_kind: opts.kind, expected_duration_seconds: opts.expectedDuration,
     rerun_reason: opts.rerunReason,
-  });
+  };
+  let registration = await effectiveCall("register_command", registerArgs);
+  // A cached session can be revoked server-side before its local expiry.  The
+  // managed cache is ours to replace once; explicit flag/env credentials belong
+  // to the caller and are never silently rotated.
+  if (isRejectedCachedMcpSession(registration, managedCredential?.source, 0)) {
+    await clearAgentState(cwd);
+    const credential = await (resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd });
+    managedCredential = credential;
+    opts.sessionToken = credential.token;
+    opts.sessionId = credential.sessionId ?? opts.sessionId;
+    registration = await effectiveCall("register_command", registerArgs);
+  }
   if (!registration.ok || registration.isError || !registration.data?.accepted || !registration.data?.run_credential) {
     return { exitCode: EXIT.BACKEND, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: registration.data?.error ?? registration.error ?? "durable_owner_not_established", exit_code: EXIT.BACKEND } };
   }

package/src/setup-block.mjs

@@ -4,9 +4,9 @@
 // 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.
+// This documents the supported BOT-1649 process. The CLI owns registration and
+// session persistence; normal operator output must never turn that into a
+// multi-command credential handoff.
 
 /** The canonical guide, referenced from every SETUP block and recovery. */
 export const CONNECTIVITY_GUIDE = "docs/agent-connectivity.md";
@@ -35,41 +35,30 @@ export const TIERS = Object.freeze({
     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).
+  // Tier 3 — per-session agent token, tenant-bound, 8 h TTL, revoked on
+  // re-register. The CLI caches it in .botbuddy/agent-state.json and restores
+  // it automatically for wait/run/test/pw.
   session: Object.freeze({
     n: 3,
     label: "session token",
-    prefix: "bb_agent_",
-    env: "BOTBUDDY_AGENT_KEY",
+    prefix: "bb_sess_",
+    env: "BOTBUDDY_AGENT_SESSION_TOKEN",
     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.
+ * Keep it to the normal two-command flow; low-level credential plumbing belongs
+ * only in the advanced reference.
  */
-export const SETUP_BLOCK = `SETUP — the connectivity ladder (install → connect → wait)
+export const SETUP_BLOCK = `SETUP — one command, then 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
-                                            multi-tenant machine: mint each tenant under a distinct --env <NAME> var (they collide otherwise)
-  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.
+  2. bb setup [--tenant <slug>]             sign in, verify this repo binding, and cache a worktree session
+  3. bb wait '<condition>'                  no environment variables or setup flags required
+  NOTE: setup keeps one user-scoped client key; --tenant only validates this worktree binding.
+        bb wait restores or renews its cached worktree session automatically.
+        bb mcp setup is separate and only needed to configure an MCP client.
   Full guide: ${CONNECTIVITY_GUIDE}`;

package/src/test-lane.mjs

@@ -21,7 +21,8 @@ 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";
+import { readAgentSessionTokenEnv } from "./agent-key.mjs";
+import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredential } from "./agent-session.mjs";
 
 // EXIT.{OK,INVALID,BACKEND,INTERNAL} plus a --wait timeout code (AC-9).
 export const EXIT_TEST = Object.freeze({ ...EXIT, TIMEOUT: 2 });
@@ -38,9 +39,9 @@ export function parseTestArgs(argv, { env = process.env } = {}) {
   const opts = {
     sessionId: env.BOTBUDDY_SESSION_ID ?? 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),
+    // the sub-invoked `run`/`wait` which derive the session from it.
+    // $BOTBUDDY_AGENT_SESSION_TOKEN is canonical; former names remain aliases.
+    sessionToken: readAgentSessionTokenEnv(env),
     environment: "local",
     ticket: null, pr: null, repo: null,
     laneKind: null,
@@ -57,6 +58,8 @@ export function parseTestArgs(argv, { env = process.env } = {}) {
     const flag = flags[i];
     switch (flag) {
       case "--session-id": opts.sessionId = value(flag, i); i++; break;
+      case "--agent-session-token":
+      case "--agent-key":
       case "--session-token": opts.sessionToken = value(flag, i); i++; break;
       case "--environment": opts.environment = value(flag, i); i++; break;
       case "--ticket": opts.ticket = value(flag, i); i++; break;
@@ -139,11 +142,11 @@ export function defaultGitInfo({ cwd = process.cwd(), ticket = null, pr = null,
 // worker, carrying the telemetry env into its detached child.
 async function defaultLaunchLane({ command, sessionId, sessionToken, environment, expectedDurationSeconds, childEnv, testRun, cwd, call }) {
   // 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
+  // relies on the inherited $BOTBUDDY_AGENT_SESSION_TOKEN (and an explicit --agent-session-token
   // so the child never falls back to a machine credential).
   const argv = [
     ...(sessionId ? ["--session-id", sessionId] : []),
-    ...(sessionToken ? ["--session-token", sessionToken] : []),
+    ...(sessionToken ? ["--agent-session-token", sessionToken] : []),
     "--environment", environment, "--category", "validation", "--kind", "full_suite",
     "--expected-duration", String(expectedDurationSeconds ?? 0), "--", ...command,
   ];
@@ -152,7 +155,7 @@ async function defaultLaunchLane({ command, sessionId, sessionToken, environment
 }
 
 function waitCommand(testRunId, sessionId, sessionToken) {
-  // BOT-1572/1582: a token-armed session runs the wait with only $BOTBUDDY_AGENT_KEY.
+  // BOT-1649: a token-armed session runs the wait with only the canonical session token.
   const idFlag = sessionId && !sessionToken ? ` --session-id ${sessionId}` : "";
   return `botbuddy wait 'test-run:id=${testRunId}'${idFlag} --heartbeat`;
 }
@@ -162,6 +165,8 @@ export async function launchTestLane(argv, {
   env = process.env,
   call = callToolJson,
   launchLane = defaultLaunchLane,
+  resolveCredential = null,
+  clearState = clearAgentState,
   gitInfo = defaultGitInfo,
   eventsDir = join(homedir(), ".botbuddy", "test-lanes"),
 } = {}) {
@@ -170,9 +175,24 @@ export async function launchTestLane(argv, {
     for (const e of errors) process.stderr.write(`botbuddy test: ${e}\n`);
     return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors }) };
   }
+  let managedCredential = null;
   if (!opts.sessionId && !opts.sessionToken) {
-    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"] }) };
+    // Test doubles intentionally do not self-mint. The shipped command does,
+    // using exactly the same cache/re-adoption resolver as `bb wait` and `run`.
+    if (!resolveCredential && call !== callToolJson) {
+      process.stderr.write("botbuddy test: --session-id is required (or set BOTBUDDY_AGENT_SESSION_TOKEN)\n");
+      return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors: ["--session-id is required"] }) };
+    }
+    try {
+      const credential = await (resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd });
+      managedCredential = credential;
+      opts.sessionToken = credential.token;
+      opts.sessionId = credential.sessionId ?? null;
+    } catch (error) {
+      const code = error?.code ?? "agent_session_unavailable";
+      process.stderr.write(`botbuddy test: ${error?.message ?? code}\n`);
+      return { exitCode: 3, line: JSON.stringify({ outcome: "rejected", error: code, recovery: code === "client_key_required" ? "run `bb login` then retry" : "run `bb doctor --fix` then retry" }) };
+    }
   }
 
   // BOT-1572 (Codex P1): a token-only session has no owner/profile credential, so
@@ -180,9 +200,20 @@ export async function launchTestLane(argv, {
   // otherwise both fail and the run launches with test_run_id=null, silently
   // dropping the test-run record and case telemetry. Wrap the call so the token
   // is pinned; an injected test `call` that ignores the 3rd arg is unaffected.
-  const apiCall = opts.sessionToken
-    ? (name, args) => call(name, args, { auth: { "x-agent-api-key": opts.sessionToken } })
-    : call;
+  const apiCall = (name, args) => opts.sessionToken
+    ? call(name, args, { auth: { "x-agent-api-key": opts.sessionToken } })
+    : call(name, args);
+  const callWithSessionRetry = async (name, args) => {
+    let result = await apiCall(name, args);
+    if (!isRejectedCachedMcpSession(result, managedCredential?.source, 0)) return result;
+    await clearState(cwd);
+    const credential = await (resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd });
+    managedCredential = credential;
+    opts.sessionToken = credential.token;
+    opts.sessionId = credential.sessionId ?? opts.sessionId;
+    result = await apiCall(name, args);
+    return result;
+  };
 
   const resolved = resolveLane(laneName, { cwd });
   if (!resolved.ok) {
@@ -218,12 +249,12 @@ export async function launchTestLane(argv, {
     // BOT-1549: stamp the resolved lane kind on the run; absent ⇒ omitted (NULL).
     lane_kind: laneKind ?? undefined,
   };
-  const created = await apiCall("create_test_run", createArgs);
+  const created = await callWithSessionRetry("create_test_run", createArgs);
   const testRunId = created?.ok && !created.isError ? created.data?.id ?? null : null;
 
   if (testRunId) {
     // Step 2: attach the ticket + promote to active in one update.
-    await apiCall("update_test_run", {
+    await callWithSessionRetry("update_test_run", {
       test_run_id: testRunId,
       ticket_id: git.ticket ?? undefined,
       ticket_url: git.ticketUrl ?? undefined,