@botbuddy/cli 1.29.4 → 1.30.1

package/src/docker-hygiene.mjs

@@ -15,6 +15,56 @@ export const SCHEMA_VERSION = 1;
 export const DEFAULT_PROJECTED_ENDPOINTS = 10;
 export const DEFAULT_WARN_PRESSURE = 192;
 export const DEFAULT_FAIL_PRESSURE = 224;
+
+// BOT-1681 / BOT-1630 Step 3 — explicit Docker-engine allowlist. The org cut the
+// dev fleet back from OrbStack to Docker Desktop (OrbStack Helper heap runaway,
+// SG ENT-4356 F4), so preflight must admit Docker Desktop deliberately instead of
+// hard-requiring OrbStack. Each entry maps `docker info`.OperatingSystem to a
+// stable `validation` label persisted on the lease and matched at teardown, plus
+// an optional secondary identity guard. Anything not listed fails closed. The
+// `orbstack_unavailable` fault label is deliberately NOT an admitted engine.
+export const DOCKER_ENGINE_ALLOWLIST = Object.freeze([
+  Object.freeze({ operating_system: "OrbStack", validation: "orbstack", identity: /orbstack/i }),
+  Object.freeze({ operating_system: "Docker Desktop", validation: "docker-desktop", identity: null }),
+]);
+
+// `hygiene` DELETES containers, so it keeps the original OrbStack-only fence
+// (BOT-1630 Must-NOT-1). Only the read-only `preflight` widens to the full
+// allowlist; that is what stack leases gate on.
+const HYGIENE_ENGINE_ALLOWLIST = Object.freeze(
+  DOCKER_ENGINE_ALLOWLIST.filter((entry) => entry.validation === "orbstack"),
+);
+
+// Validation labels the stack-lease target identity/fence accepts, shared with
+// stack.mjs so provision and teardown agree on what a valid engine looks like.
+export const ADMITTED_DOCKER_VALIDATIONS = Object.freeze(
+  new Set(DOCKER_ENGINE_ALLOWLIST.map((entry) => entry.validation)),
+);
+
+// Optional fleet override: `BOTBUDDY_DOCKER_ENGINES` (comma-separated validation
+// labels, e.g. "orbstack") narrows admission for machines that must stay on a
+// single engine. Unset/blank → the org-default full allowlist. Because this is a
+// SAFETY control that RESTRICTS admission, a non-empty value that names no known
+// engine label (a typo like "orbstak", or only empties) fails CLOSED with an
+// error rather than silently widening back to the default — otherwise a
+// misspelled restriction would admit exactly the engine it meant to block
+// (Codex P2). Known-but-inapplicable labels (e.g. "docker-desktop" for the
+// OrbStack-only hygiene command) narrow to nothing and fall back to the command's
+// inherent base, which is the same or stricter — never wider.
+export function resolveEngineAllowlist(command, env = process.env) {
+  const base = command === "hygiene" ? HYGIENE_ENGINE_ALLOWLIST : DOCKER_ENGINE_ALLOWLIST;
+  const raw = env?.BOTBUDDY_DOCKER_ENGINES;
+  if (typeof raw !== "string" || !raw.trim()) return base;
+  const requested = raw.split(",").map((label) => label.trim().toLowerCase()).filter(Boolean);
+  const unknown = requested.filter((label) => !ADMITTED_DOCKER_VALIDATIONS.has(label));
+  if (requested.length === 0 || unknown.length > 0) {
+    throw new Error(`engine_override_invalid: BOTBUDDY_DOCKER_ENGINES="${raw}" names no usable engine label${unknown.length ? ` (unknown: ${unknown.join(", ")})` : ""}; known labels: ${[...ADMITTED_DOCKER_VALIDATIONS].join(", ")}`);
+  }
+  const wanted = new Set(requested);
+  const narrowed = base.filter((entry) => wanted.has(entry.validation));
+  return narrowed.length > 0 ? narrowed : base;
+}
+
 const INSPECT_BATCH_SIZE = 10;
 const MAX_APPLY_BUDGET_MS = 5 * 60 * 1000;
 const MAX_DOCKER_COMMAND_MS = 30 * 1000;
@@ -50,8 +100,10 @@ REQUIRED SELECTOR
   --endpoint <uri>     Explicit Docker endpoint, e.g.
                        unix:///Users/me/.orbstack/run/docker.sock
 
-  Exactly one selector is required. The target must identify itself as
-  OrbStack; the ambient Docker context and DOCKER_HOST are never trusted.
+  Exactly one selector is required; the ambient Docker context and DOCKER_HOST
+  are never trusted. hygiene (which deletes) admits only OrbStack. preflight
+  admits an allowlisted engine — OrbStack or Docker Desktop — and refuses any
+  other daemon with engine_not_allowed:<OperatingSystem>.
 
 HYGIENE OPTIONS
   --ticket <BOT|ENT-N> Scope discovery/apply to the owning ticket's project.
@@ -68,6 +120,11 @@ PREFLIGHT OPTIONS
   --fail-pressure <n>        Refuse threshold (default ${DEFAULT_FAIL_PRESSURE})
   --json                       Emit exactly one compact machine-readable receipt.
 
+  Engine allowlist (preflight): OrbStack and Docker Desktop are admitted by
+  default. Set BOTBUDDY_DOCKER_ENGINES to a comma-separated list of engine
+  labels (orbstack, docker-desktop) to keep a fleet on a single engine, e.g.
+  BOTBUDDY_DOCKER_ENGINES=orbstack.
+
 SAFETY
   • Apply requires a ticket that matches each candidate's Docker project label.
   • Apply must run from a Git worktree branch carrying that same ticket.
@@ -90,8 +147,10 @@ RELIABILITY MEASUREMENT
 
 LIFECYCLE
   Use one worktree and one ticket-scoped managed stack for one test/fix batch;
-  finish or reap that stack before starting another. Run preflight before start,
-  and ticket-scoped dry-run hygiene when pressure warns or refuses admission.
+  finish or reap that stack before starting another. Run preflight before start.
+  When pressure warns or refuses: on OrbStack, run ticket-scoped dry-run hygiene;
+  on Docker Desktop (where hygiene stays OrbStack-only) release your own idle stack
+  with 'botbuddy stack done <lease>' instead.
 
 PERSISTENT ORBSTACK GHOSTS
   If an exact ID remains listed but OrbStack cannot inspect it, inventory is
@@ -672,7 +731,7 @@ function readInventory(runDocker, selector) {
   };
 }
 
-function validateOrbStack(runDocker, opts) {
+function validateDockerEngine(runDocker, opts, allowlist = DOCKER_ENGINE_ALLOWLIST) {
   let resolvedEndpoint = opts.endpoint;
   let targetHintsOrbStack = /orbstack/i.test(String(opts.endpoint || ""));
   if (opts.context) {
@@ -694,10 +753,14 @@ function validateOrbStack(runDocker, opts) {
     }
     throw error;
   }
-  const osIsOrbStack = info?.OperatingSystem === "OrbStack";
   const identity = `${info?.KernelVersion || ""} ${info?.Name || ""} ${info?.ServerVersion || ""}`;
-  if (!osIsOrbStack || !/orbstack/i.test(identity)) {
-    throw new Error(`Docker target is not OrbStack (OperatingSystem=${info?.OperatingSystem || "unknown"}, kernel=${info?.KernelVersion || "unknown"})`);
+  const engine = allowlist.find((entry) =>
+    entry.operating_system === info?.OperatingSystem &&
+    (!entry.identity || entry.identity.test(identity)));
+  if (!engine) {
+    // Fail closed on any daemon we do not positively recognise. The reason string
+    // is stable (`engine_not_allowed:<OperatingSystem>`) so wrappers can branch on it.
+    throw new Error(`engine_not_allowed:${info?.OperatingSystem || "unknown"} (Docker target is not an allowlisted engine; OperatingSystem=${info?.OperatingSystem || "unknown"}, kernel=${info?.KernelVersion || "unknown"}, admitted=${allowlist.map((entry) => entry.operating_system).join(", ") || "(none)"})`);
   }
 
   return {
@@ -705,7 +768,7 @@ function validateOrbStack(runDocker, opts) {
     receipt: {
       requested: opts.context ? { type: "context", value: opts.context } : { type: "endpoint", value: opts.endpoint },
       resolved_endpoint: resolvedEndpoint,
-      validation: "orbstack",
+      validation: engine.validation,
       server: {
         id: info.ID || null,
         name: info.Name || null,
@@ -784,6 +847,15 @@ function baseReceipt(command, opts, now) {
 
 export function buildReliabilityTelemetry(receipt, { dedupeKey } = {}) {
   const unavailable = receipt.context?.validation === "orbstack_unavailable";
+  // BOT-1681: the reliability experiment (BOT-1421, `v_orbstack_*`) is OrbStack-only
+  // and correlates rows by host/time with no engine stratum. A newly-admitted Docker
+  // Desktop preflight must NOT emit an unlabeled `capacity_observed` row that would
+  // contaminate the OrbStack strata, so suppress telemetry for any non-OrbStack
+  // engine outright. (Engine-stratified reliability reporting is BOT-1543/BOT-1630.)
+  const validation = receipt.context?.validation;
+  if (validation && validation !== "orbstack" && !unavailable) {
+    return null;
+  }
   const ghostInventory = (receipt.inventory_errors?.length ?? 0) > 0;
   // A successful target check is not a capacity measurement. If discovery
   // fails before evaluatePressure produces a decision, suppress the generic
@@ -902,10 +974,22 @@ function addSkipOnce(receipt, item) {
   }
 }
 
-function recommendationFor(opts, apply = false, candidates = []) {
+function recommendationFor(opts, apply = false, candidates = [], engine = "orbstack") {
   const selector = opts.context ? `--context ${opts.context}` : `--endpoint ${opts.endpoint}`;
   const ticket = opts.ticket ? ` --ticket ${opts.ticket}` : "";
-  if (!apply) return `botbuddy docker hygiene ${selector}${ticket}`;
+  if (!apply) {
+    // BOT-1681: `docker hygiene` is OrbStack-only, so recommending it on a
+    // non-OrbStack engine (e.g. Docker Desktop) would hand back a command that
+    // refuses with engine_not_allowed. Give a remedy that actually works there.
+    if (engine !== "orbstack") {
+      // Only recommend the OWNERSHIP-SCOPED remedy. Never suggest broad supabase_*
+      // container removal here: it bypasses hygiene's ticket filter, reviewed
+      // candidate IDs, and file/stack locks, so on a shared host it could delete a
+      // stopped service belonging to another live stack (Codex round-7 P2).
+      return `docker hygiene is OrbStack-only; on ${engine} reduce Docker load by releasing your own idle stack leases (botbuddy stack done <lease>), then retry`;
+    }
+    return `botbuddy docker hygiene ${selector}${ticket}`;
+  }
   if (!opts.ticket) return `botbuddy docker hygiene ${selector} --ticket <BOT-or-ENT-ticket>`;
   const projects = [...new Set(candidates.map((item) => item.project))];
   const lockSlot = projects.length === 1 ? lockSlotForProject(projects[0], opts.ticket) : null;
@@ -923,6 +1007,7 @@ export function runDockerWorkflow(argv, {
   monotonicNow = Date.now,
   platform = process.platform,
   now = () => new Date(),
+  env = process.env,
 } = {}) {
   const parsed = parseDockerArgs(argv);
   const receipt = baseReceipt(parsed.command || "unknown", parsed.opts, now);
@@ -970,10 +1055,10 @@ export function runDockerWorkflow(argv, {
   let validated;
   let inventory;
   try {
-    validated = validateOrbStack(runDocker, parsed.opts);
+    validated = validateDockerEngine(runDocker, parsed.opts, resolveEngineAllowlist(parsed.command, env));
     receipt.context = validated.receipt;
     inventory = classifyInventory(readInventory(runDocker, validated.selector));
-    receipt.recommendation = recommendationFor(parsed.opts);
+    receipt.recommendation = recommendationFor(parsed.opts, false, [], validated.receipt.validation);
   } catch (error) {
     receipt.outcome = "error";
     receipt.errors = [error.message];
@@ -1013,7 +1098,12 @@ export function runDockerWorkflow(argv, {
     for (const item of receipt.inventory_errors) {
       receipt.errors.push(`${item.type} ${item.id}${item.name ? ` (${item.name})` : ""} remains listed but cannot be authoritatively inspected: ${item.error}`);
     }
-    receipt.recommendation = "Persistent OrbStack inventory blocker: restart or repair OrbStack, then rerun the hygiene dry run with the same explicit selector; never use broad cleanup.";
+    // BOT-1681: this inventory-error path is shared by preflight, which now admits
+    // Docker Desktop. Keep the OrbStack remedy for OrbStack, but never tell a Docker
+    // Desktop operator to "repair OrbStack" or run the OrbStack-only hygiene dry run.
+    receipt.recommendation = receipt.context?.validation === "orbstack"
+      ? "Persistent OrbStack inventory blocker: restart or repair OrbStack, then rerun the hygiene dry run with the same explicit selector; never use broad cleanup."
+      : `Persistent Docker inventory blocker: restart or repair the ${receipt.context?.server?.operating_system || "Docker"} daemon, then rerun preflight with the same explicit selector; never use broad cleanup.`;
     return { exitCode: EXIT.DOCKER, receipt, json: parsed.opts.json };
   }
 
@@ -1025,12 +1115,20 @@ export function runDockerWorkflow(argv, {
       warn: parsed.opts.warnPressure,
       fail: parsed.opts.failPressure,
     });
+    // BOT-1681: dry-run hygiene is the OrbStack-only remedy. On Docker Desktop it
+    // refuses, so the pressure warning/refusal must not tell operators to run it;
+    // point them at the engine-aware recommendation instead.
+    const pressureEngine = receipt.context?.validation;
     if (receipt.pressure.status === "warn") {
       receipt.outcome = "warn";
-      receipt.warnings.push("Projected OrbStack network pressure is at or above the warning threshold; run dry-run hygiene before starting another stack.");
+      receipt.warnings.push(pressureEngine === "orbstack"
+        ? "Projected OrbStack network pressure is at or above the warning threshold; run dry-run hygiene before starting another stack."
+        : "Projected Docker network pressure is at or above the warning threshold; reduce Docker load (see recommendation) before starting another stack.");
     } else if (receipt.pressure.status === "fail") {
       receipt.outcome = "refused";
-      receipt.errors.push("Projected OrbStack network pressure is at or above the refusal threshold; cleanup or release an owning stack before start.");
+      receipt.errors.push(pressureEngine === "orbstack"
+        ? "Projected OrbStack network pressure is at or above the refusal threshold; cleanup or release an owning stack before start."
+        : "Projected Docker network pressure is at or above the refusal threshold; release an owning stack (see recommendation) before start.");
       return { exitCode: EXIT.PRESSURE, receipt, json: parsed.opts.json };
     }
     return { exitCode: EXIT.OK, receipt, json: parsed.opts.json };

package/src/pw/coordinator.mjs

@@ -5,7 +5,13 @@ function mcpCaller(authHeader, fetchImpl) {
   let id = 0;
   return async function call(name, args) {
     const response = await fetchImpl(SERVER_URL, { method: "POST", headers: { "content-type": "application/json", ...authHeader }, body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method: "tools/call", params: { name, arguments: args } }) });
-    if (!response.ok) throw new Error(`BotBuddy lock verification returned HTTP ${response.status}`);
+    if (!response.ok) {
+      let payload = null;
+      try { payload = await response.json(); } catch { /* keep the HTTP diagnostic */ }
+      const error = new Error(payload?.error?.message ?? payload?.error ?? `BotBuddy lock verification returned HTTP ${response.status}`);
+      error.code = payload?.error?.code ?? payload?.error?.error ?? payload?.code ?? payload?.error ?? null;
+      throw error;
+    }
     const json = await response.json(); if (json.error) throw new Error(json.error.message || "BotBuddy lock verification failed");
     const text = json.result?.content?.find((item) => item.type === "text")?.text; try { return text ? JSON.parse(text) : {}; } catch { throw new Error("BotBuddy lock verification returned invalid JSON"); }
   };

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}`;