@botbuddy/cli 1.32.1 → 1.32.3

package/package.json

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

package/src/agent-doctor.mjs

@@ -1,11 +1,14 @@
 // BOT-1649 — diagnose and repair a worktree's short-lived agent credential
 // without ever printing the token unless the operator explicitly requests an
 // export snippet for the current shell.
+import { hostname } from "node:os";
 import { readAgentBinding } from "./wait-profile.mjs";
-import { resolveOwnerToken } from "./cli-credentials.mjs";
+import { resolveOwnerToken, CLIENT_KEY_SERVICE, OWNER_TOKEN_SERVICE } from "./cli-credentials.mjs";
+import { readKeychainSecret } from "./agent-credential-store.mjs";
 import { getConfig } from "./config.mjs";
 import { isAgentStateFresh, readAgentState } from "./agent-state.mjs";
 import { selfHealAgentSession } from "./agent-session.mjs";
+import { machineUuid } from "./machine-id.mjs";
 
 export function parseDoctorArgs(argv = []) {
   const parsed = { fix: false, printExports: false, json: false, errors: [] };
@@ -29,54 +32,134 @@ function shellQuote(value) {
  * `expired` (not `available`) so `--fix` does not try to repair the cache and the
  * verdict points at `bb login` instead of a bogus binding repair.
  */
-function clientKeyStatus(owner, nowMs) {
+function clientKeyStatus(owner, nowMs, readFailed = false) {
+  // BOT-1750 (Codex R5 P2): a credential-store READ FAILURE (locked/erroring
+  // Keychain) is distinct from an absent key — reporting it as `missing` would send
+  // the operator to `bb login` when the real remedy is to unlock the store.
+  if (readFailed) return { status: "unavailable" };
   if (!owner?.token) return { status: "missing" };
   if (typeof owner.expiresAt === "number" && owner.expiresAt <= nowMs) return { status: "expired" };
   return { status: "available" };
 }
 
+/**
+ * BOT-1750 (Codex R3/R5 P2): the recovery for a missing/unreadable repair
+ * prerequisite, in priority order — a credential-store FAILURE first (unlock it,
+ * not `bb login`), then an absent/expired key, then a missing binding. Returns null
+ * when every prerequisite is satisfied.
+ */
+function prerequisiteRecovery(report) {
+  if (report.client_key.status === "unavailable") {
+    return "the client key could not be read (locked or failing credential store); unlock it, then run `bb doctor --fix`";
+  }
+  if (report.client_key.status === "missing" || report.client_key.status === "expired") {
+    return "run `bb login`, then `bb doctor --fix`";
+  }
+  if (report.binding.status === "missing") {
+    return "add a valid .botbuddy-agent.json tenant binding, then run `bb doctor --fix`";
+  }
+  return null;
+}
+
+/**
+ * BOT-1750 (Codex R6 P2): recovery for a self-heal that THREW during the repair pass
+ * (the Keychain can lock/error between the first probe and the register read). A
+ * credential-store failure must point at unlocking the store — not `bb login` or a
+ * binding repair — matching prerequisiteRecovery's wording.
+ */
+function repairFailureRecovery(code) {
+  if (code === "client_key_unavailable") {
+    return "the client key could not be read (locked or failing credential store); unlock it, then run `bb doctor --fix`";
+  }
+  // BOT-1750 (Codex R9 P2): `session_mint_unauthorized` means a locally-unexpired
+  // client key was revoked/rejected server-side — only a fresh login replaces it, so
+  // point at `bb login`, not a binding repair (the binding is valid).
+  if (code === "client_key_required" || code === "session_mint_unauthorized") return "run `bb login`, then `bb doctor --fix`";
+  // BOT-1750 (Codex R10 P2): a transport/server mint failure (or a malformed mint
+  // response) is not a binding problem — the binding was verified available before
+  // repair began. Point at retrying rather than editing a valid .botbuddy-agent.json.
+  if (code === "session_mint_failed" || code === "session_mint_invalid") return "the BotBuddy service could not mint a session (transient/server error); retry `bb doctor --fix`";
+  return "repair .botbuddy-agent.json, then run `bb doctor --fix`";
+}
+
+/**
+ * BOT-1750 (AC-4): fold the server's stack-lease capability verdict (from a mint)
+ * into the report. `established` clears the line; anything else records the reason
+ * and points the operator at the missing attestation.
+ */
+function applyStackLeaseCapability(report, capability) {
+  if (!capability || typeof capability.status !== "string") return;
+  report.stack_lease.capability = capability.status;
+  if (capability.reason) report.stack_lease.reason = capability.reason;
+  if (capability.status !== "established" && !report.recovery) {
+    report.recovery = `stack leases need a device-consented Helper on this machine: ${capability.reason ?? "worktree not attested"}`;
+  }
+}
+
 /** Inspect a worktree credential. Only `exports` ever contains the secret. */
 export async function doctorAgentAuth({
   cwd = process.cwd(), env = process.env, fix = false, printExports = false,
   readState = readAgentState, isFresh = isAgentStateFresh, now = () => Date.now(),
-  binding = readAgentBinding, ownerToken = () => resolveOwnerToken({ getConfig }),
+  binding = readAgentBinding,
+  // BOT-1750 (Codex R5 P2): read the client key STRICTLY here too, so doctor's own
+  // probe distinguishes a locked/failing credential store (throws → `unavailable`)
+  // from a genuinely absent key (`missing`) — the strict read must not live only
+  // inside selfHeal, which the `--fix` gate skips when it reports the key missing.
+  ownerToken = () => resolveOwnerToken({
+    getConfig,
+    keychainRead: () => readKeychainSecret(CLIENT_KEY_SERVICE, { strict: true }),
+    keychainReadLegacy: () => readKeychainSecret(OWNER_TOKEN_SERVICE, { strict: true }),
+  }),
   selfHeal = selfHealAgentSession,
+  hostFn = hostname, machineUuidFn = machineUuid,
 } = {}) {
-  const [state, bound, owner] = await Promise.all([
-    readState(cwd), binding(cwd).catch(() => null), ownerToken().catch(() => null),
+  let owner = null;
+  let ownerReadFailed = false;
+  const [state, bound] = await Promise.all([
+    readState(cwd), binding(cwd).catch(() => null),
   ]);
+  try { owner = await ownerToken(); } catch { ownerReadFailed = true; }
   const fresh = Boolean(state && isFresh(state, new Date()));
   const report = {
     schema_version: 1,
     worktree: cwd,
     binding: bound?.tenant ? { status: "available", tenant: bound.tenant } : { status: "missing" },
-    client_key: clientKeyStatus(owner, now()),
+    client_key: clientKeyStatus(owner, now(), ownerReadFailed),
     session: fresh
       ? { status: "fresh", agent_id: state.agent_id, session_id: state.session_id, expires_at: state.expires_at }
       : { status: state ? "stale" : "missing" },
+    // BOT-1750 (AC-3/AC-4): the worktree's stack-lease readiness. `machine_id_readable`
+    // only reports that a hardware id could be read (true on almost any host) — it is
+    // NOT attestation (Codex P2): a machine is only attested when a device-consented
+    // Helper backs it, which the server's `capability` verdict reflects. The verdict
+    // is known only after a register call, so a plain `bb doctor` reports `unverified`
+    // and `--fix` re-registers to (re)establish it (`established` | `unattested`).
+    stack_lease: {
+      host: hostFn(),
+      machine_id_readable: Boolean(machineUuidFn()),
+      capability: "unverified",
+    },
   };
   let credential = fresh
     ? { token: state.agent_session_token, sessionId: state.session_id, agentId: state.agent_id, source: "cache" }
     : null;
-  if (!fresh && fix && report.binding.status === "available" && report.client_key.status === "available") {
+  // BOT-1750 (Codex P1): repair on `--fix` even when the cache is FRESH — otherwise
+  // `bb doctor --fix` (the remedy the stack refusal points at) would reuse a fresh but
+  // never-attested session and never re-establish the capability. `force` makes the
+  // self-heal run a registration/attestation round regardless of cache freshness.
+  if (fix && report.binding.status === "available" && report.client_key.status === "available") {
     try {
-      credential = await selfHeal({ cwd, env });
+      credential = await selfHeal({ cwd, env, force: true });
       report.session = { status: credential.source === "minted" ? "minted" : credential.source, agent_id: credential.agentId ?? null, session_id: credential.sessionId ?? null };
+      applyStackLeaseCapability(report, credential.stackLeaseCapability);
     } catch (error) {
       report.session = { status: "repair_failed", error: error?.code ?? "agent_session_unavailable" };
-      report.recovery = error?.code === "client_key_required"
-        ? "run `bb login`, then `bb doctor --fix`"
-        : "repair .botbuddy-agent.json, then run `bb doctor --fix`";
+      report.recovery = repairFailureRecovery(error?.code);
       return { exitCode: 3, report, exports: null };
     }
   }
   if (!credential) {
-    const needsLogin = report.client_key.status === "missing" || report.client_key.status === "expired";
-    report.recovery = needsLogin
-      ? "run `bb login`, then `bb doctor --fix`"
-      : report.binding.status === "missing"
-        ? "add a valid .botbuddy-agent.json tenant binding, then run `bb doctor --fix`"
-        : "run `bb doctor --fix` to mint a replacement session";
+    report.recovery = prerequisiteRecovery(report) ?? "run `bb doctor --fix` to mint a replacement session";
     return { exitCode: 3, report, exports: null };
   }
   const exports = printExports
@@ -85,9 +168,31 @@ export async function doctorAgentAuth({
       ...(credential.sessionId ? [`export BOTBUDDY_SESSION_ID=${shellQuote(credential.sessionId)}`] : []),
     ].join("\n")
     : null;
+  // BOT-1750 (Codex R3 P2): when `--fix` could not even attempt a repair because a
+  // prerequisite is missing (no tenant binding, or no/expired client key) yet a fresh
+  // cached session left `credential` populated, report THAT prerequisite — not the
+  // Helper/capability message below, since registration never ran and the real remedy
+  // is `bb login` or restoring the binding.
+  if (fix && (report.binding.status !== "available" || report.client_key.status !== "available")) {
+    report.recovery = prerequisiteRecovery(report) ?? "run `bb doctor --fix` to mint a replacement session";
+    return { exitCode: 3, report, exports };
+  }
+  // BOT-1750 (Codex R2 P1): `bb doctor --fix` is the advertised remedy for a stack-
+  // lease refusal, so it must not report success while the worktree's capability is
+  // still not `established` — including an `unattested` verdict or an omitted verdict
+  // from an older server (which leaves it `unverified`). The session is still minted
+  // and usable for wait/run/pw, but the exit fails closed so the lease-refusal remedy
+  // never falsely reports fixed. A plain `bb doctor` (no --fix) stays exit 0: it is a
+  // read-only report that has not attempted to establish anything.
+  if (fix && report.stack_lease.capability !== "established") {
+    if (!report.recovery) {
+      report.recovery = "session minted, but this worktree's stack-lease capability is not established — no device-consented Helper attests this machine, so `bb stack` will still be refused.";
+    }
+    return { exitCode: 3, report, exports };
+  }
   return { exitCode: 0, report, exports };
 }
 
 export function doctorHelp() {
-  return "bb doctor [--fix] [--print-exports] [--json]\n\nChecks the client key, repo binding, and cached agent session. --fix mints a replacement session; --print-exports prints its canonical shell exports.";
+  return "bb doctor [--fix] [--print-exports] [--json]\n\nChecks the client key, repo binding, cached agent session, and this worktree's stack-lease capability (registered host + attested machine). --fix mints a replacement session and (re)establishes the stack-lease capability; --print-exports prints its canonical shell exports.";
 }

package/src/commands.mjs

@@ -227,6 +227,10 @@ export async function cmdDoctor(args, { log = (line) => console.log(line), error
     log(`binding: ${result.report.binding.status}${result.report.binding.tenant ? ` (${result.report.binding.tenant})` : ""}`);
     log(`client key: ${result.report.client_key.status}`);
     log(`agent session: ${result.report.session.status}`);
+    if (result.report.stack_lease) {
+      const sl = result.report.stack_lease;
+      log(`stack lease: ${sl.capability} (host ${sl.host}, machine id ${sl.machine_id_readable ? "readable" : "unavailable"})${sl.reason ? ` — ${sl.reason}` : ""}`);
+    }
     if (result.report.recovery) log(`recovery: ${result.report.recovery}`);
   }
   if (result.exports) log(result.exports);

package/src/pw/args.mjs

@@ -1,6 +1,26 @@
 import { TARGET_VERBS, parseTargetFlags, hasTargetFlags, buildLocatorTarget, classifyTarget, isSnapshotRef } from "./targets.mjs";
 import { TRANSLATE_VERBS, planTranslateVerb, MAX_EXEC_ARG } from "./translate.mjs";
 export const GLOBAL_VERBS = new Set(["list", "close-all", "kill-all", "reap"]);
+// BOT-1682: the bb pw credential/session flags. They are accepted ONLY before the
+// lane (consumed in run.mjs). Once one reaches planInvocation it is after the lane
+// — the verb slot or the workload — which upstream @playwright/cli would reject
+// with an "Unknown option" + help dump; catch it here and name the fix (move it
+// before the lane) instead. `--tenant` after the lane also cannot be safely
+// honored for session/lane auth, another reason to refuse rather than forward it.
+export const PW_CREDENTIAL_FLAGS = ["--tenant", "--session-id", "--agent-session-token", "--agent-key", "--session-token"];
+const credentialFlagOf = (token) => PW_CREDENTIAL_FLAGS.find((flag) => token === flag || String(token).startsWith(`${flag}=`)) ?? null;
+function misplacedCredentialFlag(token) {
+  return new Error(`bb-pw: ${credentialFlagOf(token)} is a bb pw credential flag, not a Playwright argument — put it before the lane: bb-pw [--tenant <slug>] <lane> <verb> …`);
+}
+// BOT-1682: verbs that once existed under bb pw / an older @playwright/cli and now
+// map to a differently-named upstream command. On these, hint the rename in one
+// line instead of dumping ~110 lines of upstream usage. `console` and `status`
+// are NOT here — they are live commands.
+export const RETIRED_VERBS = { network: "use 'requests' (list) or 'request-headers <n>' / 'request <n>'" };
+// BOT-1682: everything after a bare `--` is a positional Playwright argument (the
+// upstream CLI treats `fill e1 -- --tenant` as literal text), so misplaced-flag
+// detection must not look past it. Mirrors legacyAgentAliasHint's own `--` cutoff.
+const beforeSeparator = (tokens) => { const sep = tokens.indexOf("--"); return sep === -1 ? tokens : tokens.slice(0, sep); };
 const secret = /^@ENV:(.+)$/;
 export function resolveRef(value, env = process.env) {
   const match = secret.exec(String(value));
@@ -12,16 +32,51 @@ export const normaliseLane = (token) => String(token).replace(/^agent-0*/, "").r
 function validLane(lane) { return /^[1-9]\d*$/.test(lane); }
 export function planInvocation(argv, env = process.env) {
   if (!argv.length) throw new Error("bb-pw: usage: bb-pw <lane> <verb> [args…]  (or: bb-pw <reap|list|close-all|kill-all>)");
-  if (GLOBAL_VERBS.has(argv[0])) return argv[0] === "reap" ? { scope: "global", verb: "reap", mode: "reap" } : { scope: "global", verb: argv[0], mode: "exec", execArgv: argv };
+  if (GLOBAL_VERBS.has(argv[0])) {
+    // BOT-1682: a credential flag after a global verb (`bb-pw list --tenant …`)
+    // has no lane to sit before, and would otherwise be forwarded to upstream —
+    // which rejects it with its own "Unknown option" dump. Refuse it here too.
+    // Global verbs (list/close-all/kill-all/reap) take NO positional workload, so
+    // unlike lane verbs there is no `--` exemption — a credential-shaped token in
+    // ANY position (incl. after `--`) is misplaced, never a literal value that
+    // upstream would accept (Codex: `list -- --tenant` otherwise reaches upstream,
+    // which errors "too many arguments").
+    const strayGlobal = argv.slice(1).find((value) => credentialFlagOf(value));
+    if (strayGlobal) throw misplacedCredentialFlag(strayGlobal);
+    return argv[0] === "reap" ? { scope: "global", verb: "reap", mode: "reap" } : { scope: "global", verb: argv[0], mode: "exec", execArgv: argv };
+  }
   const lane = normaliseLane(argv[0]), verb = argv[1];
   if (!validLane(lane) || !verb) throw new Error(`bb-pw: usage: lane must be a positive integer and include a verb`);
-  if (verb === "status") return { scope: "lane", lane, session: `lane-${lane}`, verb, mode: "status" };
+  // BOT-1682: a credential flag in the verb slot (`<lane> --tenant …`) or a
+  // retired verb — caught before status/target handling so neither leaks upstream.
+  if (credentialFlagOf(verb)) throw misplacedCredentialFlag(verb);
+  if (Object.hasOwn(RETIRED_VERBS, verb)) throw new Error(`bb-pw: '${verb}' was retired — ${RETIRED_VERBS[verb]}`);
+  if (verb === "status") {
+    // `status` has no workload, so — like the global verbs — there is no `--`
+    // exemption: a credential flag in ANY position (incl. after `--`) is misplaced
+    // and must be refused, or `status -- --tenant` would return success while
+    // silently ignoring it and still leaving the id readable downstream (Codex).
+    const strayStatus = argv.slice(2).find((value) => credentialFlagOf(value));
+    if (strayStatus) throw misplacedCredentialFlag(strayStatus);
+    return { scope: "lane", lane, session: `lane-${lane}`, verb, mode: "status" };
+  }
   const rest = argv.slice(2); let forwarded = rest, target = null, fresh = false;
   // BOT-1702: bb-pw OWNS upload/route/unroute and translates them to upstream
   // `run-code` (see translate.mjs). A resolved `@ENV:` secret in any value routes
   // the generated code through the socket path so it never lands in argv, and is
   // tracked for redaction — mirroring the sibling verbs' guarantee.
   if (TRANSLATE_VERBS.has(verb)) {
+    // BOT-1682: run the misplaced-credential-flag guard BEFORE dispatching a
+    // translated verb (upload/route/unroute/route-list), so `route … stall --tenant …`
+    // gets the one-line "put it before the lane" refusal rather than an unrelated
+    // translate-parse error (Codex). But a translated verb's parsers consume the
+    // token AFTER an option as that option's VALUE (`upload --label --tenant`,
+    // `route … fulfill --body --session-token`), so a credential-shaped token whose
+    // predecessor is an option (`--x`) is a legitimate value and is left alone;
+    // only one in a non-value position is misplaced (Codex R17). `--` still exempts.
+    const scanT = beforeSeparator(rest);
+    const strayTranslate = scanT.find((value, i) => credentialFlagOf(value) && !(i > 0 && /^--[a-z]/.test(String(scanT[i - 1]))));
+    if (strayTranslate) throw misplacedCredentialFlag(strayTranslate);
     const { code, secretValues } = planTranslateVerb(verb, rest, { env, resolveRef });
     // Use the daemon socket (JSON, no argv limit) for a resolved secret OR a
     // payload too large for a single child-process argument (Codex R2 P2: a big
@@ -37,6 +92,11 @@ export function planInvocation(argv, env = process.env) {
     target = forwarded.find((value) => !String(value).startsWith("--")) ?? null;
     if (fresh && target && isSnapshotRef(target)) throw new Error("bb-pw: --fresh cannot target a snapshot ref; use a stable locator");
   }
+  // BOT-1682: a credential flag surviving into the workload (`<lane> <verb> …
+  // --tenant …`) is misplaced — target-flag VALUES have already been consumed by
+  // parseTargetFlags, so only a genuine standalone credential-flag token remains.
+  const stray = beforeSeparator(forwarded).find((value) => credentialFlagOf(value));
+  if (stray) throw misplacedCredentialFlag(stray);
   const resolved = forwarded.map((value) => resolveRef(value, env));
   const sensitive = resolved.some((value) => value.secret);
   return { scope: "lane", lane, session: `lane-${lane}`, verb, mode: sensitive ? "socket" : "exec", execArgv: sensitive ? null : [`-s=lane-${lane}`, verb, ...forwarded], socketArgs: sensitive ? [verb, ...resolved.map((value) => value.value)] : null, telemetryUrl: ["goto", "open", "go-back", "go-forward", "reload"].includes(verb) ? (resolved[0]?.secret ? resolved[0].ref : forwarded[0] ?? null) : null, secretValues: resolved.filter((value) => value.secret).map((value) => String(value.value)), rollup: verb === "close", target, targetKind: target === null ? null : classifyTarget(target), fresh };

package/src/pw/run.mjs

@@ -1,5 +1,5 @@
 import os from "node:os";
-import { planInvocation } from "./args.mjs";
+import { planInvocation, GLOBAL_VERBS } from "./args.mjs";
 import { actionTypeFromMethod, NAV } from "./readiness.mjs";
 import { isStaleRefError, staleRefRemediation } from "./targets.mjs";
 import { createSessionTokenCoordinator } from "./coordinator.mjs";
@@ -13,7 +13,7 @@ import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredent
 // 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").
 const hostFor = (env) => canonicalizeHostString(env.PLAYWRIGHT_MCP_HOST || env.HOSTNAME || os.hostname());
-function help(out) { out.write("Usage: pw [--tenant <slug>] [--session-id <id>] [--agent-session-token <token>] <lane> <verb> [args…]\n\nAliases: bb-pw <lane> <verb> [args…]   ·   botbuddy pw <lane> <verb> [args…]\n         (all three drive the same lock-gated Playwright lane)\n\n--session-id <id>  accept a lane held by this arming-session agent id (from\n                   register_agent); defaults to $BOTBUDDY_SESSION_ID, then the\n                   id saved by `botbuddy register`.\n--agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN);\n                   --agent-key / --session-token are one-release legacy aliases.\n--tenant <slug>    override the worktree .botbuddy-agent.json tenant when falling\n                   back to the .mcp.json ($BOTBUDDY_MCP_KEY) credential.\n\nFile upload (BOT-1702) — works on a hidden <input type=file>:\n  bb-pw <lane> upload <selector> <path...>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,size=<bytes>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,bytes=@base64:<b64>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,text=<str>\n     --inline repeats; builds synthetic files in memory (no workstation FS).\n     <selector> also accepts --testid/--role/--label/--text like click/fill.\n\nNetwork mocking (BOT-1702) — routes persist on the lane across invocations:\n  bb-pw <lane> route <url-glob> stall                 hold the request pending\n                                                      (screenshot the loading state)\n  bb-pw <lane> route <url-glob> abort [--error <code>] fail the request (default: failed)\n  bb-pw <lane> route <url-glob> fulfill --status <n> [--content-type <ct>]\n                                        [--body <str|@base64:..|@file:PATH>]\n  bb-pw <lane> unroute [<url-glob>]                    release one route, or all\n  bb-pw <lane> route-list                              list the routes owned on this lane\n  (offline mode already exists upstream: bb-pw <lane> network-state-set offline)\n"); }
+function help(out) { out.write("Usage: pw [--tenant <slug>] [--session-id <id>] [--agent-session-token <token>] <lane> <verb> [args…]\n\nAliases: bb-pw <lane> <verb> [args…]   ·   botbuddy pw <lane> <verb> [args…]\n         (all three drive the same lock-gated Playwright lane)\n\n--session-id <id>  accept a lane held by this arming-session agent id (from\n                   register_agent); defaults to $BOTBUDDY_SESSION_ID, then the\n                   id saved by `botbuddy register`.\n--agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN);\n                   --agent-key / --session-token are one-release legacy aliases.\n--tenant <slug>    accepted before the lane but currently INERT — the tenant\n                   comes from your resolved credential, so bb pw does not act on\n                   this flag for session/lane auth yet (server-validated tenant\n                   selection is tracked in BOT-1732).\n\nCredential flags (--tenant / --session-id / --agent-session-token) go BEFORE the\nlane. Placed after the lane they are refused with guidance (they are not\nPlaywright arguments, and a --tenant after the lane cannot be safely honored).\n\nFile upload (BOT-1702) — works on a hidden <input type=file>:\n  bb-pw <lane> upload <selector> <path...>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,size=<bytes>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,bytes=@base64:<b64>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,text=<str>\n     --inline repeats; builds synthetic files in memory (no workstation FS).\n     <selector> also accepts --testid/--role/--label/--text like click/fill.\n\nNetwork mocking (BOT-1702) — routes persist on the lane across invocations:\n  bb-pw <lane> route <url-glob> stall                 hold the request pending\n                                                      (screenshot the loading state)\n  bb-pw <lane> route <url-glob> abort [--error <code>] fail the request (default: failed)\n  bb-pw <lane> route <url-glob> fulfill --status <n> [--content-type <ct>]\n                                        [--body <str|@base64:..|@file:PATH>]\n  bb-pw <lane> unroute [<url-glob>]                    release one route, or all\n  bb-pw <lane> route-list                              list the routes owned on this lane\n  (offline mode already exists upstream: bb-pw <lane> network-state-set offline)\n"); }
 // Redact LONGEST secrets first: replacing a short value that is a substring of a
 // longer secret (e.g. a filename that also appears inside the payload's base64)
 // would otherwise break the longer match and leave the remainder recoverable
@@ -114,14 +114,58 @@ export async function runPw(argv, deps = {}) {
 // while-loop in runPwInner). Everything after the first non-option (the lane) is a
 // Playwright workload argument and is never a BotBuddy credential.
 const PW_LEADING_FLAGS = ["--tenant", "--session-id", "--agent-session-token", "--agent-key", "--session-token"];
+const selfHealErrorLine = (error) => `bb-pw: ${error?.message ?? "agent session unavailable"}. ${error?.code === "client_key_required" ? "Run `bb login` then retry." : "Run `bb doctor --fix` then retry."}\n`;
+// The leading credential options, NORMALIZED to split `flag value` pairs so an
+// inline `--agent-key=<token>` is recognized by legacyAgentAliasHint (which
+// matches exact flag tokens) exactly like the split form. Credential flags are
+// only accepted BEFORE the lane (BOT-1682 P1: `--tenant` after the lane cannot be
+// safely honored for session/lane auth and is refused, see planInvocation), so
+// this leading scan is the whole surface the alias hint needs to consider.
 function leadingPwOptions(args) {
   const lead = [];
-  for (let i = 0; i < args.length && PW_LEADING_FLAGS.includes(args[i]); i += 2) {
-    lead.push(args[i]);
-    if (i + 1 < args.length) lead.push(args[i + 1]);
+  let rest = [...args];
+  let match;
+  while ((match = matchWrapperFlag(rest[0]))) {
+    lead.push(match.flag);
+    if (match.inline !== null) { lead.push(match.inline); rest = rest.slice(1); }
+    else { if (rest[1] === undefined) break; lead.push(rest[1]); rest = rest.slice(2); }
   }
   return lead;
 }
+// BOT-1682: match a leading credential flag in either `--flag value` or
+// `--flag=value` form. Returns the base flag + its inline value (null when the
+// value is the NEXT token), or null when the token is not a credential flag.
+function matchWrapperFlag(token) {
+  for (const flag of PW_LEADING_FLAGS) {
+    if (token === flag) return { flag, inline: null };
+    if (typeof token === "string" && token.startsWith(`${flag}=`)) return { flag, inline: token.slice(flag.length + 1) };
+  }
+  return null;
+}
+const applyWrapperFlag = (deps, flag, value) => flag === "--tenant"
+  ? { ...deps, tenant: value }
+  : ["--agent-session-token", "--agent-key", "--session-token"].includes(flag)
+    ? { ...deps, sessionToken: value }
+    : { ...deps, sessionId: value };
+// Consume a run of credential flags from `list` starting at `start`, folding each
+// into deps. Returns { deps, rest } on success, or { error: flag } when a flag
+// has no value. `rest` is the tokens after the consumed run.
+function consumeWrapperFlags(list, deps, start = 0) {
+  let rest = list.slice(start);
+  let match;
+  while ((match = matchWrapperFlag(rest[0]))) {
+    let value;
+    if (match.inline !== null) { value = match.inline; rest = rest.slice(1); }
+    else { if (rest[1] === undefined) return { error: match.flag }; value = rest[1]; rest = rest.slice(2); }
+    // An empty value (`--flag=` or `--flag ""`) is a usage error, not a silent
+    // no-op: an empty session token would make `!deps.sessionToken` true and fall
+    // back to another credential, executing under a different identity (Codex P2).
+    // Matches the old `if (!args[1])` guard this helper replaced.
+    if (value === "") return { error: match.flag };
+    deps = applyWrapperFlag(deps, match.flag, value);
+  }
+  return { deps, rest };
+}
 
 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; }
@@ -137,7 +181,14 @@ async function runPwInner(argv, deps = {}) {
   // 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 (["--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); }
+  // Credential flags are accepted ONLY as LEADING options (before the lane). A
+  // `--tenant` after the lane cannot be safely honored — bb pw would authenticate
+  // with the resolved session/key regardless of the named tenant, so a tenant B
+  // request could run under tenant A's cached session (Codex P1). Anything
+  // credential-flag-shaped still present once we reach the verb is refused by
+  // planInvocation with guidance to move it before the lane; a real, server-pinned
+  // `--tenant` lane fallback is BOT-1732.
+  { const consumed = consumeWrapperFlags(args, deps, 0); if (consumed.error) { stderr.write(`bb-pw: ${consumed.error} needs a value\n`); return 2; } deps = consumed.deps; args = consumed.rest; }
   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); }
@@ -146,12 +197,11 @@ async function runPwInner(argv, deps = {}) {
   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() });
+      const credential = await (deps.resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd: deps.cwd ?? process.cwd(), sessionId: deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null, flagToken: null });
       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;
+      stderr.write(selfHealErrorLine(error)); return 3;
     }
   }
   const telemetry = deps.telemetry ?? (await import("./telemetry.mjs")).makeTelemetry({ env }); const host = deps.host ?? hostFor(env);
@@ -161,9 +211,17 @@ async function runPwInner(argv, deps = {}) {
   // 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 };
+    try {
+      const credential = await (deps.resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd: deps.cwd ?? process.cwd(), sessionId: deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null, flagToken: null });
+      managedCredential = credential;
+      // Keep an explicit --session-id holder authoritative over the freshly minted
+      // one, same precedence as the initial resolution (Codex).
+      deps = { ...deps, sessionToken: credential.token, sessionId: deps.sessionId ?? credential.sessionId ?? null };
+    } catch (error) {
+      // BOT-1682: the renewal after a revoked cache can also fail self-heal; fail
+      // closed with a clear message rather than letting the error escape to exit 1.
+      stderr.write(selfHealErrorLine(error)); return 3;
+    }
     auth = await gate({ env, host, lane: plan.lane, deps });
   }
   if (!auth.allowed) { stderr.write(`${auth.message}\n`); return 3; }

package/src/stack.mjs

@@ -30,7 +30,9 @@ import { randomUUID } from "crypto";
 import { callToolJson } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
-import { AGENT_KEY_RE, readAgentKeyEnv } from "./agent-key.mjs";
+import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
+import { resolveAgentSessionCredential } from "./agent-session.mjs";
+import { clearAgentState } from "./agent-state.mjs";
 import { runDockerCommand, runDockerWorkflow, ADMITTED_DOCKER_VALIDATIONS } from "./docker-hygiene.mjs";
 import { projectIdFromConfig } from "./stack-file-lock.mjs";
 import { machineUuid } from "./machine-id.mjs";
@@ -347,30 +349,176 @@ export function parseSupabaseStatus(text) {
 
 // ── runtime (network / process) ──────────────────────────────────────────────
 
-// BOT-1599: a stack lease is a host-bound operation. When a session token is
-// present it must win over the durable OAuth client credential, otherwise the
-// lease RPC resolves the hostless/stale OAuth agent rather than the agent that
-// registered this worktree and machine attestation. The MCP server accepts the
-// session token through the same agent-key header used by bb-pw.
+// BOT-1750: a stack lease is a host-bound operation, so it must resolve its
+// session credential through the SAME shared resolver `bb wait`/`run`/`pw` use —
+// exported token, then the fresh per-worktree `.botbuddy-agent.json` cache, then
+// ONE self-heal that re-establishes this worktree's host + machine attestation.
+// That is what makes the lease resolve to the agent row carrying `host`, instead
+// of the hostless tier-2 MCP key that produced `AGENT_HOST_REQUIRED` (BOT-1599
+// fixed only the case where the token was already exported in the environment).
 //
-// Without a session token, retain the BOT-1520 Keychain-backed OAuth/MCP-key
-// fallback for operator commands and legacy callers.
-export async function stackAuthHeader() {
-  const sessionToken = readAgentKeyEnv();
-  if (sessionToken) return AGENT_KEY_RE.test(sessionToken) ? { "x-agent-api-key": sessionToken } : null;
-  const agentKey = await resolveAgentKey();
-  const owner = await resolveOwnerToken({ getConfig });
+// When the resolver has nothing to work with (no client key or no tenant binding
+// to self-heal from — e.g. an operator running `stack status` with only a tier-2
+// MCP key), fall through to the BOT-1520 Keychain-backed OAuth/MCP-key path. That
+// credential is valid for operator commands but is NOT the lease path; the lease
+// RPC will refuse it with an actionable AGENT_HOST_REQUIRED message (see cmdUp).
+export async function stackAuthHeader({
+  argv = process.argv.slice(2),
+  env = process.env,
+  cwd = process.cwd(),
+  resolveCredential = resolveAgentSessionCredential,
+  resolveAgentKeyFn = resolveAgentKey,
+  resolveOwnerTokenFn = () => resolveOwnerToken({ getConfig }),
+} = {}) {
+  let credential = null;
+  try {
+    credential = await resolveCredential({ argv, env, cwd });
+  } catch (error) {
+    // BOT-1750 (Codex P2): only the "nothing to self-heal from" cases fall through
+    // to the operator credential path — no durable client key, or no tenant binding.
+    // A transport/server/tenant/malformed self-heal failure must FAIL CLOSED, not
+    // silently switch principals: for `up` that would turn a real error into a
+    // misleading host-registration refusal, and for owner-scoped `status`/`touch`/
+    // `done` it would run as a different agent that cannot see the original lease.
+    if (error?.code !== "client_key_required" && error?.code !== "tenant_binding_required") throw error;
+    credential = null;
+  }
+  if (credential) {
+    // BOT-1750 (Codex R3 P2): a resolver that RETURNED a credential must yield a
+    // well-formed session token. A nonempty-but-malformed token (a corrupt cache or
+    // an incompatible server response) must FAIL CLOSED — not skip the session header
+    // and silently authenticate as the OAuth/MCP-key principal, which is the exact
+    // principal switch the catch above guards against.
+    if (typeof credential.token === "string" && AGENT_KEY_RE.test(credential.token)) {
+      return withSource({ "x-agent-api-key": credential.token }, credential.source);
+    }
+    throw Object.assign(new Error(`resolved agent session token has an unexpected shape (source: ${credential.source ?? "unknown"}); re-run \`bb doctor --fix\``), { code: "session_token_malformed" });
+  }
+  // Only reached when a missing prerequisite (no client key / no tenant binding)
+  // routed us here — the operator credential path for status/touch/done.
+  const agentKey = await resolveAgentKeyFn();
+  const owner = await resolveOwnerTokenFn();
   if (owner) {
     if (owner.expiresAt && Date.now() >= owner.expiresAt) {
-      if (agentKey) return { Authorization: `Bearer ${agentKey}`, "x-agent-api-key": agentKey };
+      if (agentKey) return withSource({ Authorization: `Bearer ${agentKey}`, "x-agent-api-key": agentKey }, "operator");
       return null;
     }
-    return { Authorization: `Bearer ${owner.token}`, "x-agent-api-key": agentKey || "" };
+    return withSource({ Authorization: `Bearer ${owner.token}`, "x-agent-api-key": agentKey || "" }, "operator");
   }
-  if (agentKey) return { Authorization: `Bearer ${agentKey}`, "x-agent-api-key": agentKey };
+  if (agentKey) return withSource({ Authorization: `Bearer ${agentKey}`, "x-agent-api-key": agentKey }, "operator");
   return null;
 }
 
+// BOT-1750 (Codex R7 P2): carry the credential SOURCE on the returned headers as a
+// NON-enumerable property, so callers can clear+self-heal+retry once on a
+// server-rejected cached session (parity with run/test/pw/wait) without the source
+// ever leaking into the spread fetch headers.
+function withSource(headers, source) {
+  Object.defineProperty(headers, "__source", { value: source ?? null, enumerable: false });
+  return headers;
+}
+
+/**
+ * BOT-1750 (Codex R7 P2): a locally-fresh cache whose token was revoked server-side
+ * (e.g. a concurrent re-registration rotated the session) is rejected at the lease
+ * RPC. Mirror the other consumers: when the FIRST auth came from the per-worktree
+ * cache and the RPC returns an auth rejection, clear the cache and self-heal once,
+ * then let the caller retry with the fresh headers. Returns the fresh headers, or
+ * null when no retry applies (not cache-sourced, or the refresh could not authenticate).
+ */
+export async function refreshRejectedCacheAuth(auth, {
+  cwd = process.cwd(), authProvider = stackAuthHeader, clear = clearAgentState,
+} = {}) {
+  if (auth?.__source !== "cache") return null;
+  await clear(cwd);
+  const fresh = await authProvider();
+  // BOT-1750 (Codex R8 P2): retry ONLY with a genuinely self-healed session. If the
+  // client key or binding vanished after clearing the cache, authProvider falls
+  // through to the OAuth/MCP operator credential — a DIFFERENT principal whose token
+  // also differs, so a bare "different token" check would retry as the wrong agent.
+  // Require source "minted" AND a well-formed, changed session token.
+  if (fresh?.__source !== "minted") return null;
+  const token = fresh["x-agent-api-key"];
+  if (typeof token !== "string" || !AGENT_KEY_RE.test(token) || token === auth["x-agent-api-key"]) return null;
+  return fresh;
+}
+
+/**
+ * BOT-1750 (Codex R10 P2): a stack RPC caller that transparently recovers from a
+ * server-rejected cached session ONCE — the owner-scoped management commands
+ * (`status`/`touch`/`done`) need the same recovery as the lease-creating paths, or a
+ * revoked-but-locally-fresh cache leaves an active lease unreleasable. `init()`
+ * resolves auth; `call()` runs the RPC and, on the FIRST auth rejection, clears +
+ * self-heals + retries with the fresh credential (every later `call` reuses it).
+ */
+export function retryingStackCall({
+  callTool = callToolJson, authProvider = stackAuthHeader,
+  refresh = refreshRejectedCacheAuth, cwd = () => process.cwd(),
+  auth: seedAuth,
+} = {}) {
+  // A pre-resolved `auth` seed lets a caller that already resolved the credential
+  // (runStackLifecycle short-circuits its own await) skip init() — avoiding an extra
+  // await point before the first RPC is dispatched.
+  let auth = seedAuth;
+  let refreshed = false;
+  return {
+    async init() { if (auth === undefined) auth = await authProvider(); return auth; },
+    async call(name, args, callOptions = {}) {
+      let r = await callTool(name, args, { ...callOptions, auth });
+      if (!refreshed && !r?.ok && r?.auth) {
+        refreshed = true;
+        const fresh = await refresh(auth, { cwd: cwd() });
+        if (fresh) { auth = fresh; r = await callTool(name, args, { ...callOptions, auth }); }
+      }
+      return r;
+    },
+    get auth() { return auth; },
+  };
+}
+
+// BOT-1750 (Codex R7 P2): map a thrown auth/self-heal failure to the documented exit
+// taxonomy so automation sees AUTH/BACKEND, not a CLI-defect INTERNAL. Credential
+// problems are AUTH (3); a transport/server mint failure is BACKEND (5); anything
+// unrecognized stays INTERNAL (7).
+const AUTH_ERROR_CODES = new Set(["client_key_required", "client_key_unavailable", "tenant_binding_required", "session_token_malformed", "session_mint_unauthorized"]);
+// BOT-1750 (Codex R11 P2): `session_mint_invalid` is an incompatible/malformed SERVER
+// response, not a credential problem — classify it with the transport/server failures.
+const BACKEND_ERROR_CODES = new Set(["session_mint_failed", "session_mint_invalid"]);
+export function classifyStackAuthError(error) {
+  const code = error?.code;
+  if (AUTH_ERROR_CODES.has(code)) return EXIT.AUTH;
+  if (BACKEND_ERROR_CODES.has(code)) return EXIT.BACKEND;
+  return EXIT.INTERNAL;
+}
+
+// BOT-1750 (AC-2): name the credential kind a refused lease was authenticated with,
+// so the AGENT_HOST_REQUIRED / WORKTREE_NOT_REGISTERED hint tells the operator what
+// they actually sent (a hostless MCP key vs. a real session token).
+export function describeStackCredentialKind(auth) {
+  if (!auth) return "no credential";
+  const key = auth["x-agent-api-key"];
+  if (typeof key === "string" && AGENT_KEY_RE.test(key)) return "agent session token";
+  const bearer = typeof auth.Authorization === "string" ? auth.Authorization.replace(/^Bearer\s+/, "") : null;
+  // The MCP-key-only fallback sends the SAME key as bearer AND x-agent-api-key; a
+  // real OAuth client credential sends a distinct owner token as the bearer.
+  if (bearer && key && bearer === key) return "tier-2 MCP key";
+  if (bearer) return "OAuth client credential";
+  if (key) return "tier-2 MCP key";
+  return "unknown credential";
+}
+
+// BOT-1750 (AC-2): the server refuses a lease from a worktree it can't attest with
+// one of these codes. They are actionable in the same way — register this worktree's
+// host + machine so the lease resolves to a host-bearing agent.
+const WORKTREE_UNREGISTERED_CODES = new Set(["AGENT_HOST_REQUIRED", "WORKTREE_NOT_REGISTERED"]);
+
+/** One-line, operator-facing fix for an unregistered-worktree lease refusal (or null). */
+export function worktreeRegistrationHint(code, auth) {
+  if (!WORKTREE_UNREGISTERED_CODES.has(code)) return null;
+  return `${yellow("⚠")} stack: this worktree is not registered for stack leases (sent ${describeStackCredentialKind(auth)}). `
+    + `Run \`bb doctor --fix\` here to register its host + machine id, then retry.`;
+}
+
 // The MCP lease endpoint accepts a session token in x-agent-api-key, whereas
 // the event-stream relay requires that same token in its bearer form too. Keep
 // the lease RPC shape unchanged and derive the relay-compatible form only at
@@ -954,6 +1102,7 @@ export async function cmdUp(opts, {
   emitResult = emit,
   machineUuidFn = machineUuid,
   assertIsolated = validateLocalExecTarget,
+  refreshAuth = refreshRejectedCacheAuth,
 } = {}) {
   let slot;
   try { slot = deriveSlot(opts); } catch (e) {
@@ -994,9 +1143,9 @@ export async function cmdUp(opts, {
       process.stderr.write(`${yellow("⚠")} stack: ${engine} preflight warns of network pressure; ${remedy}.\n`);
     }
   }
-  const auth = await authProvider();
+  let auth = await authProvider();
   if (!auth) return emitResult(buildReceipt({ command: "up", outcome: "error", error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
-  const call = (name, args, callOptions = {}) => callTool(name, args, { ...callOptions, auth });
+  let call = (name, args, callOptions = {}) => callTool(name, args, { ...callOptions, auth });
 
   // BOT-1585: co-location dispatches the lease to the Helper enrolled for THIS
   // physical machine (hardware id), since a hostname is not machine-unique. The
@@ -1005,7 +1154,7 @@ export async function cmdUp(opts, {
   if (!hardwareUuid) {
     return emitResult(buildReceipt({ command: "up", outcome: "error", code: "MACHINE_UUID_REQUIRED", error: "could not determine this machine's hardware id (needed to dispatch the stack lease to the right machine)" }), opts, EXIT.BACKEND);
   }
-  const req = await call("request_stack_lease", {
+  const leaseArgs = {
     slot, host_key: opts.host || undefined, repo: opts.repo || undefined,
     ticket_id: opts.ticket || undefined, ticket_url: opts.ticketUrl || undefined,
     pr_id: opts.prId || undefined, pr_url: opts.prUrl || undefined,
@@ -1013,7 +1162,20 @@ export async function cmdUp(opts, {
     stack_path: execution.stackPath,
     worktree_root: execution.worktreeRoot,
     machine_uuid: hardwareUuid,
-  });
+  };
+  let req = await call("request_stack_lease", leaseArgs);
+  if (!req.ok && req.auth) {
+    // BOT-1750 (Codex R7 P2): a locally-fresh cached session whose token was revoked
+    // server-side (e.g. a concurrent re-registration) is rejected here. Clear the
+    // cache and self-heal once, then retry — parity with run/test/pw/wait, so `bb
+    // stack` recovers on its own instead of bricking until a manual cache repair.
+    const fresh = await refreshAuth(auth, { cwd: process.cwd() });
+    if (fresh) {
+      auth = fresh;
+      call = (name, args, callOptions = {}) => callTool(name, args, { ...callOptions, auth });
+      req = await call("request_stack_lease", leaseArgs);
+    }
+  }
   if (!req.ok) {
     return req.auth
       ? emitResult(buildReceipt({ command: "up", outcome: "error", error: req.error || "unauthorized" }), opts, EXIT.AUTH)
@@ -1021,6 +1183,8 @@ export async function cmdUp(opts, {
   }
   const d = req.data;
   if (!d.success) {
+    const hint = worktreeRegistrationHint(d.code, auth);
+    if (hint) process.stderr.write(`${hint}\n`);
     return emitResult(buildReceipt({ command: "up", outcome: "error", code: d.code, error: d.message || d.code || "request refused", slot }), opts, EXIT.BACKEND);
   }
   let leaseId = d.lease_id;
@@ -1208,10 +1372,10 @@ export async function cmdUp(opts, {
   }), opts, EXIT.OK);
 }
 
-async function cmdStatus(leaseId, opts) {
-  const auth = await stackAuthHeader();
+async function cmdStatus(leaseId, opts, { rpc = retryingStackCall() } = {}) {
+  const auth = await rpc.init();
   if (!auth) return emit(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
-  const got = await callToolJson("get_stack_lease", { lease_id: leaseId }, { auth });
+  const got = await rpc.call("get_stack_lease", { lease_id: leaseId });
   if (!got.ok) return got.auth
     ? emit(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, error: got.error }), opts, EXIT.AUTH)
     : emit(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, error: got.error }), opts, EXIT.BACKEND);
@@ -1224,10 +1388,10 @@ async function cmdStatus(leaseId, opts) {
   }), opts, EXIT.OK);
 }
 
-async function cmdTouch(leaseId, opts) {
-  const auth = await stackAuthHeader();
+async function cmdTouch(leaseId, opts, { rpc = retryingStackCall() } = {}) {
+  const auth = await rpc.init();
   if (!auth) return emit(buildReceipt({ command: "touch", outcome: "error", lease_id: leaseId, error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
-  const r = await callToolJson("touch_stack_lease", { lease_id: leaseId }, { auth });
+  const r = await rpc.call("touch_stack_lease", { lease_id: leaseId });
   if (!r.ok) return emit(buildReceipt({ command: "touch", outcome: "error", lease_id: leaseId, error: r.error }), opts, r.auth ? EXIT.AUTH : EXIT.BACKEND);
   if (!r.data.success) return emit(buildReceipt({ command: "touch", outcome: "error", lease_id: leaseId, code: r.data.code, error: r.data.code }), opts, EXIT.BACKEND);
   return emit(buildReceipt({ command: "touch", outcome: "touched", lease_id: leaseId, last_used_at: r.data.last_used_at }), opts, EXIT.OK);
@@ -1240,10 +1404,15 @@ export async function cmdDone(leaseId, opts, {
   proveLegacyTarget = proveLegacyLocalExecTarget,
   localTeardownFn = localTeardown,
   emitResult = emit,
+  refreshAuth = refreshRejectedCacheAuth,
 } = {}) {
-  const auth = await authProvider();
+  // BOT-1750 (Codex R10 P2): `done` must recover a server-rejected cached session on
+  // its own — otherwise an active lease can't be released until the cache is manually
+  // repaired. The retrying caller clears+self-heals+retries the FIRST auth rejection.
+  const rpc = retryingStackCall({ callTool, authProvider, refresh: refreshAuth });
+  const auth = await rpc.init();
   if (!auth) return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
-  const call = (name, args, callOptions = {}) => callTool(name, args, { ...callOptions, auth });
+  const call = rpc.call;
   let dockerTarget = null;
   let legacyTargetProof = null;
   let teardownDir = process.cwd();
@@ -1475,12 +1644,29 @@ export async function materializeLeasedTestConfig(worktreeRoot, leaseId, connect
  * without Docker or a live BotBuddy service.
  */
 export async function runStackLifecycle(opts, childArgv, adapters = {}) {
-  const auth = adapters.auth ?? await stackAuthHeader();
+  // BOT-1750 (Codex R9/R11 P2): `stack run` is a lease-creating entry point AND a
+  // long-lived one (queue → provision → child → heartbeat → cleanup). A cached token
+  // can be rotated server-side at ANY of those points, so EVERY RPC — not just the
+  // initial request — must be able to clear + self-heal + retry once. Route them all
+  // through one retryingStackCall so a single self-heal re-authenticates the rest
+  // (heartbeat, get, cleanup release), instead of fencing a healthy child or leaking
+  // an unreleasable lease. Retry only when we own the credential or a test provides an
+  // explicit refreshAuth — never for an injected api double without one.
+  const refreshAuth = adapters.refreshAuth ?? (adapters.auth ? async () => null : refreshRejectedCacheAuth);
+  // Resolve the initial credential with the same short-circuit as before (an injected
+  // auth skips the network resolve), then seed the retrying caller so no extra await
+  // point is introduced before the first RPC.
+  const initialAuth = adapters.auth ?? await stackAuthHeader();
+  const rpc = retryingStackCall({
+    callTool: adapters.callTool ?? callToolJson,
+    refresh: refreshAuth,
+    auth: initialAuth,
+  });
   const api = adapters.api ?? {
-    request: (args) => callToolJson("request_stack_lease", args, { auth }),
-    get: (leaseId) => callToolJson("get_stack_lease", { lease_id: leaseId }, { auth }),
-    touch: (leaseId) => callToolJson("touch_stack_lease", { lease_id: leaseId }, { auth }),
-    release: (leaseId, signal) => callToolJson("release_stack_lease", { lease_id: leaseId, disposition: "destroy" }, { auth, signal }),
+    request: (args) => rpc.call("request_stack_lease", args),
+    get: (leaseId) => rpc.call("get_stack_lease", { lease_id: leaseId }),
+    touch: (leaseId) => rpc.call("touch_stack_lease", { lease_id: leaseId }),
+    release: (leaseId, signal) => rpc.call("release_stack_lease", { lease_id: leaseId, disposition: "destroy" }, { signal }),
   };
   const machineUuidFn = adapters.machineUuidFn ?? machineUuid;
   const wait = adapters.wait ?? ((leaseId, done, failed, options) => waitForLease(leaseId, done, failed, options));
@@ -1526,7 +1712,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
       return cleanupResult = { ok: false, error: release?.error || release?.data?.code || "release failed" };
     }
     if (release.data.state === "reaped") return cleanupResult = { ok: true, state: "reaped" };
-    const reaped = await wait(leaseId, (state) => state === "reaped", () => false, { timeoutSec: opts.reapTimeout, auth });
+    const reaped = await wait(leaseId, (state) => state === "reaped", () => false, { timeoutSec: opts.reapTimeout, auth: rpc.auth });
     if (reaped?.woke || reaped?.state === "reaped") return cleanupResult = { ok: true, state: "reaped" };
     return cleanupResult = { ok: false, error: reaped?.timeout ? `signed reap did not arrive within ${opts.reapTimeout}s` : (reaped?.error || "signed reap was not proven") };
     })();
@@ -1558,7 +1744,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   }
 
   try {
-    if (!auth) return { exitCode: EXIT.AUTH, outcome: "error", error: "not authenticated — run botbuddy login (agents: botbuddy mcp setup)" };
+    if (!rpc.auth) return { exitCode: EXIT.AUTH, outcome: "error", error: "not authenticated — run botbuddy login (agents: botbuddy mcp setup)" };
     // BOT-1585: request_stack_lease requires this machine's hardware id so the lease
     // dispatches to the machine the worktree was registered on. `stack run` builds its
     // own payload (separate from `cmdUp`), so it must send it too.
@@ -1568,15 +1754,22 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
     }
     const slot = deriveSlot(opts);
     const execution = resolveStackPath(process.cwd(), opts.stackPath);
-    const request = await api.request({
+    const leaseArgs = {
       slot, host_key: opts.host || undefined, repo: opts.repo, ticket_id: opts.ticket,
       ticket_url: opts.ticketUrl || undefined, pr_id: opts.prId || undefined, pr_url: opts.prUrl || undefined,
       purpose: opts.purpose || "stack run", idle_ttl_secs: opts.idleTtl ?? undefined,
       stack_path: execution.stackPath, worktree_root: execution.worktreeRoot,
       machine_uuid: hardwareUuid,
-    });
+    };
+    // The retrying caller (api → rpc.call) transparently clears+self-heals+retries the
+    // FIRST auth rejection among any of request/get/touch/release.
+    const request = await api.request(leaseArgs);
     if (!request?.ok) return { exitCode: request?.auth ? EXIT.AUTH : EXIT.BACKEND, outcome: "error", error: request?.error || "lease request failed" };
-    if (!request.data?.success) return { exitCode: EXIT.BACKEND, outcome: "error", error: request.data?.message || request.data?.code || "lease request refused" };
+    if (!request.data?.success) {
+      const hint = worktreeRegistrationHint(request.data?.code, rpc.auth);
+      if (hint) process.stderr.write(`${hint}\n`);
+      return { exitCode: EXIT.BACKEND, outcome: "error", error: request.data?.message || request.data?.code || "lease request refused" };
+    }
     leaseId = request.data.lease_id;
     if (request.data.reused) {
       return { exitCode: EXIT.BACKEND, outcome: "error", leaseId, error: "a live lease already exists for this agent and stack slot; wait for that batch to finish instead of sharing its stack" };
@@ -1589,7 +1782,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
     }
     if (state === "queued") {
       activeWaitAbort = new AbortController();
-      const parked = await wait(leaseId, (s) => s !== "queued" && s != null, (s) => s === "reaped", { timeoutSec: opts.timeout, auth, signal: activeWaitAbort.signal });
+      const parked = await wait(leaseId, (s) => s !== "queued" && s != null, (s) => s === "reaped", { timeoutSec: opts.timeout, auth: rpc.auth, signal: activeWaitAbort.signal });
       activeWaitAbort = null;
       if (parked?.interrupted || receivedSignal) { const cleanup = await requestCleanup(); return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup }; }
       if (parked?.timeout) { const cleanup = await requestCleanup(); return { exitCode: EXIT.TIMEOUT, outcome: "timeout", leaseId, error: `parked ${opts.timeout}s without capacity`, cleanup }; }
@@ -1598,7 +1791,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
     }
     if (state !== "active") {
       activeWaitAbort = new AbortController();
-      const active = await wait(leaseId, (s) => s === "active", (s) => s === "reaped", { timeoutSec: provisionTimeout, auth, signal: activeWaitAbort.signal });
+      const active = await wait(leaseId, (s) => s === "active", (s) => s === "reaped", { timeoutSec: provisionTimeout, auth: rpc.auth, signal: activeWaitAbort.signal });
       activeWaitAbort = null;
       if (active?.interrupted || receivedSignal) { const cleanup = await requestCleanup(); return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup }; }
       if (active?.timeout) { const cleanup = await requestCleanup(); return { exitCode: EXIT.TIMEOUT, outcome: "timeout", leaseId, error: `physical provision did not reach active in ${provisionTimeout}s`, cleanup }; }
@@ -1657,7 +1850,12 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
     return { exitCode, outcome: exitCode === 0 ? "completed" : "failed", leaseId, childExitCode: childResult.code, cleanup, fenced: fencing };
   } catch (error) {
     const cleanup = await requestCleanup();
-    return { exitCode: cleanup?.ok === false ? EXIT.CLEANUP_FAILED : EXIT.INTERNAL, outcome: "error", leaseId, error: String(error?.message ?? error), cleanup };
+    // BOT-1750 (Codex R10 P2): a thrown auth/self-heal failure (e.g. a refresh that
+    // re-minted and was rejected) must keep the documented exit taxonomy — AUTH for a
+    // credential problem, BACKEND for a transport/server mint failure — instead of a
+    // blanket INTERNAL. A genuine cleanup failure still wins (it is the louder signal).
+    const exitCode = cleanup?.ok === false ? EXIT.CLEANUP_FAILED : classifyStackAuthError(error);
+    return { exitCode, outcome: "error", leaseId, error: String(error?.message ?? error), cleanup };
   } finally {
     if (heartbeat) clock.clearInterval(heartbeat);
     if (hardTimer) clock.clearTimeout(hardTimer);
@@ -1689,9 +1887,9 @@ export async function cmdStack(argv) {
     process.exitCode = code;
     return code;
   }
-  const sessionToken = readAgentKeyEnv();
+  const sessionToken = readAgentSessionTokenEnv();
   if (sessionToken && !AGENT_KEY_RE.test(sessionToken)) {
-    process.stderr.write(`${yellow("⚠")} stack: $BOTBUDDY_AGENT_KEY must match bb_agent_<64 hex>; re-register and export a fresh session token.\n`);
+    process.stderr.write(`${yellow("⚠")} stack: $BOTBUDDY_AGENT_SESSION_TOKEN must match bb_sess_<64 hex>; re-register and export a fresh session token.\n`);
     const code = emit(buildReceipt({ command, outcome: "error", error: "invalid_session_token" }), opts, EXIT.INVALID);
     process.exitCode = code;
     return code;
@@ -1709,7 +1907,13 @@ export async function cmdStack(argv) {
         code = emit(buildReceipt({ command: command || "?", outcome: "error", error: `unknown subcommand: ${command}` }), opts, EXIT.INVALID);
     }
   } catch (err) {
-    code = emit(buildReceipt({ command: command || "?", outcome: "error", error: `internal: ${err?.message ?? err}` }), opts, EXIT.INTERNAL);
+    // BOT-1750 (Codex R7 P2): a thrown auth/self-heal failure carries a typed code —
+    // map it to the documented exit taxonomy (AUTH for credential problems, BACKEND
+    // for a transport/server mint failure) so automation never reads a routine
+    // outage as a CLI defect. Only a genuinely unrecognized error stays INTERNAL.
+    const exit = classifyStackAuthError(err);
+    const message = exit === EXIT.INTERNAL ? `internal: ${err?.message ?? err}` : (err?.message ?? String(err));
+    code = emit(buildReceipt({ command: command || "?", outcome: "error", code: err?.code, error: message }), opts, exit);
   }
   process.exitCode = code;
   return code;