@botbuddy/cli 1.31.0 → 1.31.2

package/src/credential-kinds.mjs

@@ -30,6 +30,48 @@ export const CREDENTIAL_PREFIXES = [
   { prefix: "bb_", kind: "legacy", label: "legacy personal key" },
 ];
 
+// BOT-1701 — the ONE canonical per-tier credential contract. The same noun,
+// prefix, CLI flag, env var, and `credential_kind` for each tier, named the same
+// way EVERYWHERE it is met: the setup-block help text, the connectivity guide's
+// tier table, the `bb wait/run/test/pw --help` flags, the connectivity error
+// strings, and the server's `whoami credential_kind`. A drift test
+// (credential-naming-contract.test.mjs) fails when any of those surfaces names a
+// tier-3 credential by anything other than the canonical noun/flag/env below.
+// Decided by BOT-1649 — do not re-decide here. Additive only: legacy aliases
+// (TIER3_LEGACY) keep working for one release and are listed separately so a
+// surface can name them ONLY on a line that says "alias"/"legacy".
+/**
+ * @typedef {{ tier: 1|2|3, noun: string, prefix: string, flag: string|null, env: string, kind: string }} CredentialTier
+ * @type {ReadonlyArray<CredentialTier>}
+ */
+export const CREDENTIAL_TIERS = Object.freeze([
+  Object.freeze({ tier: 1, noun: "client key", prefix: "bb_cli_", flag: null, env: "BOTBUDDY_CLIENT_KEY", kind: "cli" }),
+  Object.freeze({ tier: 2, noun: "MCP key", prefix: "bb_mcp_", flag: null, env: "BOTBUDDY_MCP_KEY", kind: "mcp" }),
+  Object.freeze({ tier: 3, noun: "agent session token", prefix: "bb_sess_", flag: "--agent-session-token", env: "BOTBUDDY_AGENT_SESSION_TOKEN", kind: "agent_session" }),
+]);
+
+/**
+ * The tier-3 legacy aliases, accepted for one release. Kept apart from the
+ * canonical table so a surface can name them only on an "alias"/"legacy" line and
+ * the CLI can nudge an operator toward the canonical flag/env (BOT-1701 AC-6).
+ */
+export const TIER3_LEGACY = Object.freeze({
+  flags: Object.freeze(["--agent-key", "--session-token"]),
+  envs: Object.freeze(["BOTBUDDY_AGENT_KEY", "BOTBUDDY_SESSION_TOKEN"]),
+  prefix: "bb_agent_",
+});
+
+/** The canonical tier row for a tier number (1|2|3), or undefined. */
+export function credentialTier(tier) {
+  return CREDENTIAL_TIERS.find((t) => t.tier === tier);
+}
+
+/** The canonical tier row whose prefix a secret carries, or undefined. */
+export function credentialTierByPrefix(secret) {
+  if (typeof secret !== "string") return undefined;
+  return CREDENTIAL_TIERS.find((t) => secret.startsWith(t.prefix));
+}
+
 /**
  * Classify a raw secret by its prefix.
  * @param {unknown} secret

package/src/pw/run.mjs

@@ -7,13 +7,13 @@ import { canonicalizeHostString } from "./host.mjs";
 import { resolveAgentBinding } from "../wait-profile.mjs";
 import { loadConfig, getConfig } from "../config.mjs";
 import { VERSION } from "../version.mjs";
-import { readAgentSessionTokenEnv, AGENT_KEY_RE } from "../agent-key.mjs";
+import { readAgentSessionTokenEnv, AGENT_KEY_RE, legacyAgentAliasHint } 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").
 const hostFor = (env) => canonicalizeHostString(env.PLAYWRIGHT_MCP_HOST || env.HOSTNAME || os.hostname());
-function help(out) { out.write("Usage: pw [--tenant <slug>] [--session-id <id>] <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--tenant <slug>    override the worktree .botbuddy-agent.json tenant when falling\n                   back to the .mcp.json ($BOTBUDDY_MCP_KEY) credential.\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>    override the worktree .botbuddy-agent.json tenant when falling\n                   back to the .mcp.json ($BOTBUDDY_MCP_KEY) credential.\n"); }
 function redact(value, secretValues = []) { return secretValues.reduce((text, secret) => secret ? text.split(secret).join("[redacted]") : text, String(value ?? "")); }
 // BOT-1488: the register_agent identity for this machine, persisted by
 // `botbuddy register` into ~/.botbuddy/config.json. This is the SESSION agent
@@ -99,9 +99,28 @@ export async function runPw(argv, deps = {}) {
   if (code !== 0) stderr.write(`${versionLine()} — if your checkout's cli/package.json is newer, this global is stale: npm i -g @botbuddy/cli@latest, or run node cli/bin/bb-pw.mjs from the repo.\n`);
   return code;
 }
+// The leading option/value pairs bb pw consumes before the lane/verb (mirrors the
+// 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"];
+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]);
+  }
+  return lead;
+}
+
 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-1701 (AC-6): one stderr nudge for a tier-3 legacy flag/env alias. bb pw
+  // only recognizes credential flags as LEADING options (the while-loop below);
+  // a `--agent-key` after the lane/verb is a Playwright workload argument, not a
+  // BotBuddy credential, so scan only the leading options (Codex R9).
+  const aliasHint = legacyAgentAliasHint({ argv: leadingPwOptions(args), env });
+  if (aliasHint) stderr.write(`bb pw: ${aliasHint}\n`);
   // 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

package/src/run.mjs

@@ -14,7 +14,7 @@ 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, readAgentSessionTokenEnv } from "./agent-key.mjs";
+import { AGENT_KEY_RE, readAgentSessionTokenEnv, legacyAgentAliasHint } from "./agent-key.mjs";
 import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredential } from "./agent-session.mjs";
 import { createTelemetryOutbox } from "./telemetry-outbox.mjs";
 import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
@@ -532,9 +532,14 @@ export async function cmdRun(args) {
     return;
   }
   if (args[0] === "help" || args[0] === "--help") {
-    console.log("botbuddy run --session-id <id> --environment <local|preview|staging|production|none> [--timeout <sec>] [--rerun-reason <json>] -- <command> [args...]\nbotbuddy run --foreground --kind <test|wait|browser|ci|hook|stack> --environment <local|preview|staging|production|none> -- <command> [args...]\nbotbuddy run cancel <run_id>");
+    console.log("botbuddy run --session-id <id> --environment <local|preview|staging|production|none> [--timeout <sec>] [--rerun-reason <json>] -- <command> [args...]\nbotbuddy run --foreground --kind <test|wait|browser|ci|hook|stack> --environment <local|preview|staging|production|none> -- <command> [args...]\nbotbuddy run cancel <run_id>\n  --agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN); --agent-key / --session-token are one-release legacy aliases");
     return;
   }
+  // BOT-1701 (AC-6): one stderr nudge when a tier-3 legacy flag/env alias is used
+  // (stderr only, so the stdout receipt stays byte-identical). A cached bb_agent_
+  // token is nudged inside resolveAgentSessionCredential.
+  const aliasHint = legacyAgentAliasHint({ argv: args, env: process.env });
+  if (aliasHint) process.stderr.write(`botbuddy run: ${aliasHint}\n`);
   if (args.includes("--foreground")) {
     let identity;
     try { identity = await loadTelemetryIdentity(); }

package/src/session-bootstrap.mjs

@@ -0,0 +1,375 @@
+// BOT-1650 — the only CLI-side bridge between a harness and the tier-3 token.
+// It never prints or exports a secret; the runtime store is consumed by `bb wait`.
+
+import os from "node:os";
+import { callToolJson } from "./api.mjs";
+import { readAgentState, touchAgentStateExpiry, withStateLock, worktreeRoot, writeAgentState } from "./agent-state.mjs";
+import { clearAgentSessionIfMatches, drainPendingCleanup, recordPendingCleanup } from "./agent-cleanup.mjs";
+import { readAgentBinding } from "./wait-profile.mjs";
+import { resolveAgentKey, resolveOwnerToken } from "./cli-credentials.mjs";
+import { getConfig } from "./config.mjs";
+
+// BOT-1650 → BOT-1649 reconciliation: the harness session lives in the ONE
+// unified client cache (agent-state.mjs), written in main's `agent_session_token`
+// schema. These adapters map between the bootstrap RPC response shape (which uses
+// `session_token`) and the on-disk state, so `bb wait`/`run`/`test`/`pw` can
+// authenticate from the same file via resolveAgentSessionCredential.
+
+/** Read the per-worktree cache back in the RPC-shaped form the bridge expects. */
+export async function loadHarnessSession({ cwd = process.cwd() } = {}) {
+  const state = await readAgentState(cwd);
+  if (!state) return null;
+  return {
+    ...state,
+    session_token: state.agent_session_token,
+    ...(state.session_token_generation ? { session_token_generation: state.session_token_generation } : {}),
+  };
+}
+
+/** Persist a bootstrap-issued session into the unified cache. The bootstrap RPC
+ * does not echo the tenant, so derive it from the committed binding exactly as
+ * selfHealAgentSession does; host/worktree/minted_at are derived locally. */
+export async function saveHarnessSession(session, { cwd = process.cwd() } = {}) {
+  const root = await worktreeRoot(cwd);
+  let tenant;
+  try { tenant = (await readAgentBinding(root))?.tenant; } catch { tenant = undefined; }
+  const state = {
+    schema_version: 1,
+    agent_id: session.agent_id,
+    agent_session_token: session.session_token,
+    session_id: session.session_id ?? null,
+    ...(tenant ? { tenant } : {}),
+    host: os.hostname(),
+    worktree: root,
+    minted_at: new Date().toISOString(),
+    expires_at: session.expires_at,
+    // BOT-1650 (Codex round-28 P2): mark provenance so a TIMER wait only relays for
+    // a bootstrap-issued cache (the cross-shell receipt-of-principal contract). A
+    // bb setup / self-heal cache shares this schema but omits this marker, so a
+    // plain timer from such a shell stays fully offline.
+    harness_origin: "bootstrap_agent_session",
+    ...(session.session_token_generation ? { session_token_generation: session.session_token_generation } : {}),
+  };
+  await writeAgentState(root, state);
+  // Return the RPC-shaped session so callers reading `.session_token` are unchanged.
+  return session;
+}
+
+/** Guarded, lock-free clear used inside the bootstrap transaction (re-exported so
+ * the Codex bridge and `bb setup` close path share one implementation). */
+export const clearHarnessSession = clearAgentSessionIfMatches;
+
+/** Serialize the whole remote-bootstrap-plus-save on the unified per-worktree
+ * state lock — the SAME `<agent-state>.lock` selfHealAgentSession takes — so a
+ * bootstrap and a self-heal can never both write the cache. */
+export async function withHarnessBootstrapLock({ cwd = process.cwd() } = {}, operation) {
+  const root = await worktreeRoot(cwd);
+  return withStateLock(root, {}, () => operation(root));
+}
+
+export async function durableCleanupOptions({
+  resolveAgentKeyFn = resolveAgentKey,
+  resolveOwnerTokenFn = resolveOwnerToken,
+  getConfigFn = getConfig,
+} = {}) {
+  const owner = await resolveOwnerTokenFn({ getConfig: getConfigFn });
+  if (owner && !(owner.expiresAt && owner.expiresAt <= Date.now())) {
+    return { auth: { Authorization: `Bearer ${owner.token}` } };
+  }
+  const agentKey = await resolveAgentKeyFn();
+  if (agentKey) return { auth: { "x-agent-api-key": agentKey } };
+  return null;
+}
+
+function cleanupError(response) {
+  return response?.data?.error || response?.data?.message || response?.error || "remote session cleanup could not be confirmed";
+}
+
+async function closeWithDurableCredential(call, args, options) {
+  try {
+    const response = await call("close_session", args, options);
+    return { response, closed: !!response?.ok && !response.isError };
+  } catch (error) {
+    return { response: null, closed: false, error };
+  }
+}
+
+// BOT-1650 (Codex round-24/25): a session was admitted but could not be retired.
+// Persist a cleanup marker so a later bootstrap retires it, then ALWAYS throw a
+// failure that preserves the primary cause, the retirement failure, AND any
+// persistence failure — never swallowing a marker-write failure (round-25 P2),
+// which would silently revert to leaving an orphaned holder. Never returns.
+async function recordOrphanAndFail({ session, cwd, retirementError, primaryError }) {
+  let persistError;
+  try {
+    await recordPendingCleanup(
+      { session_id: session.session_id, session_token_generation: session.session_token_generation },
+      { cwd },
+    );
+  } catch (error) {
+    persistError = error;
+  }
+  const parts = [];
+  if (primaryError) parts.push(primaryError.message);
+  parts.push(`the admitted session could not be retired: ${retirementError.message}`);
+  if (persistError) parts.push(`and its cleanup marker could not be persisted: ${persistError.message}`);
+  const err = new Error(parts.join("; "));
+  err.cause = primaryError ?? retirementError;
+  throw err;
+}
+
+// Keep a REST-bootstrapped harness alive without handing its durable setup
+// credential to the bridge. The session bearer is scoped to this exact session;
+// the server rejects a mismatched or ended session rather than refreshing an
+// unrelated agent-global heartbeat.
+export async function heartbeatHarnessSession({
+  session,
+  codexThreadId = null,
+  model = null,
+  call = callToolJson,
+  cwd = process.cwd(),
+  touchExpiry = touchAgentStateExpiry,
+} = {}) {
+  if (!session?.session_id || !session?.session_token) {
+    throw new Error("bootstrap heartbeat requires a stored session credential");
+  }
+  const response = await call("heartbeat", {
+    session_id: session.session_id,
+    ...(codexThreadId ? { codex_thread_id: codexThreadId } : {}),
+    ...(model ? { model } : {}),
+  }, { auth: { "x-agent-api-key": session.session_token } });
+  if (!response?.ok || response.isError) {
+    throw new Error(response?.data?.message || response?.error || "bootstrap heartbeat failed");
+  }
+  // BOT-1650 (Codex round-30 P2): the server just rolled this session's expiry
+  // forward, but the runtime cache still holds the ORIGINAL deadline. Without
+  // mirroring the renewal, a later relay wait on a long-lived bridge judges the
+  // cache stale and self-heals into a DIFFERENT work session — losing the harness
+  // principal and creating a second live holder. touchAgentStateExpiry extends the
+  // cache only while it still holds THIS exact bearer, so it never revives a
+  // replaced credential. Best-effort: a heartbeat that cannot refresh the cache is
+  // not itself a failure.
+  await touchExpiry(cwd, session.session_token).catch(() => {});
+  return response.data;
+}
+
+export async function bootstrapHarnessSession({
+  name,
+  type = "codex",
+  harnessSessionId,
+  codexThreadId = null,
+  cwd = process.cwd(),
+  branch = null,
+  ticketId = null,
+  ticketUrl = null,
+  noTicketReason = null,
+  prId = null,
+  prNumber = null,
+  prUrl = null,
+  model = null,
+  effort = null,
+  harness = type,
+  call = callToolJson,
+  callOptions = undefined,
+  resolveCleanupOptions = durableCleanupOptions,
+  store = saveHarnessSession,
+  transaction = withHarnessBootstrapLock,
+} = {}) {
+  if (!name || !harnessSessionId) throw new Error("bootstrap requires name and harnessSessionId");
+  const worktree = await worktreeRoot(cwd);
+  return transaction({ cwd: worktree }, async () => {
+    // BOT-1650 (Codex round-24): before admitting a new session, retry retiring
+    // any session a PRIOR bootstrap orphaned (its replacement retirement failed in
+    // a compound outage). The durable credential retires by id, so no bearer is
+    // needed. Best-effort — a missing durable credential just keeps the marker.
+    await drainPendingCleanup({
+      cwd: worktree,
+      retire: async (entry) => {
+        const opts = callOptions ?? await resolveCleanupOptions();
+        if (!opts) return false;
+        const closed = await closeWithDurableCredential(call, {
+          session_id: entry.session_id,
+          ...(entry.session_token_generation ? { session_token_generation: entry.session_token_generation } : {}),
+        }, opts);
+        return closed.closed;
+      },
+    }).catch(() => {});
+    const cached = await loadHarnessSession({ cwd: worktree });
+    // `expires_at` is a cache snapshot, not authority: an authenticated relay
+    // use can extend the server-side session after the file was written. Pass
+    // bootstrap straight through so the server reuses a still-live incarnation
+    // or rotates a truly expired one; never revoke an active wait from a stale
+    // local timestamp.
+    const response = await call("bootstrap_agent_session", {
+      name,
+      type,
+      harness_session_id: harnessSessionId,
+      host: os.hostname(),
+      worktree,
+      ...(branch ? { branch } : {}),
+      ...(ticketId ? { ticket_id: ticketId } : {}),
+      ...(ticketUrl ? { ticket_url: ticketUrl } : {}),
+      ...(noTicketReason ? { no_ticket_reason: noTicketReason } : {}),
+      ...(prId ? { pr_id: prId } : {}),
+      ...(prNumber != null ? { pr_number: prNumber } : {}),
+      ...(prUrl ? { pr_url: prUrl } : {}),
+      ...(codexThreadId ? { codex_thread_id: codexThreadId } : {}),
+      ...(model ? { model } : {}),
+      ...(effort ? { effort } : {}),
+      harness,
+    }, callOptions);
+    if (!response?.ok || response.isError) {
+      throw new Error(response?.data?.message || response?.error || "bootstrap_agent_session failed");
+    }
+    // Persist only the four session-secret fields. Ticket signals are intentionally
+    // returned to the launcher, never copied into the runtime credential file.
+    const { ticket_signals: ticketSignals, display_name: displayName, linkage, ...session } = response.data;
+    if (ticketSignals?.concurrency) throw new Error(ticketSignals.concurrency.warning || "Another live session holds this ticket.");
+    if (linkage?.status === "gap") throw new Error(linkage.warning || "Session bootstrap requires ticket attribution.");
+    // A new harness may be admitted only after an abandoned cache aged out of
+    // the server's liveness window. Before replacing that file, ask the server
+    // to retire the cached session *only if its authoritative holder-liveness
+    // window elapsed*. The file's timestamp is intentionally not authority:
+    // relay heartbeats can extend it after the snapshot was written.
+    if (cached && cached.session_id !== session.session_id) {
+      const cleanupOptions = callOptions ?? await resolveCleanupOptions();
+      if (!cleanupOptions) {
+        // BOT-1650 (Codex round-27): the new session was admitted but there is no
+        // durable credential to retire the OLD cached session, so the replacement
+        // cannot complete. Do not strand the NEW bearer (never persisted): self-close
+        // it with its own scoped token first, and if that cannot be confirmed record
+        // an orphan marker for a later bootstrap to drain — then fail closed. Matches
+        // the store()-failure path's no-durable-credential handling.
+        const primaryError = new Error("a replacement harness cache requires a durable credential to confirm remote session cleanup");
+        const direct = await closeWithDurableCredential(call, {
+          session_id: session.session_id,
+          ...(session.session_token_generation ? { session_token_generation: session.session_token_generation } : {}),
+        }, { auth: { "x-agent-api-key": session.session_token } });
+        if (!direct.closed) {
+          await recordOrphanAndFail({
+            session,
+            cwd: worktree,
+            retirementError: new Error("no durable credential is available to retire the cached session, and the new session's self-close was not confirmed"),
+            primaryError,
+          });
+        }
+        throw primaryError;
+      }
+      const discardNewSession = async () => {
+        // A successful self-close revokes this tier-3 token before its response
+        // reaches us. If that response is lost, retrying the bearer loops on
+        // 401 forever; the durable setup credential is the authority that can
+        // confirm the idempotent close (including already_closed).
+        const closeArgs = {
+          session_id: session.session_id,
+          ...(session.session_token_generation ? { session_token_generation: session.session_token_generation } : {}),
+        };
+        const direct = await closeWithDurableCredential(call, closeArgs, {
+          auth: { "x-agent-api-key": session.session_token },
+        });
+        if (direct.closed) return;
+        const confirmed = await closeWithDurableCredential(call, closeArgs, cleanupOptions);
+        if (confirmed.closed) return;
+        throw new Error(cleanupError(confirmed.response) || direct.error?.message || "new harness session cleanup could not be confirmed");
+      };
+      const cachedCloseArgs = {
+        session_id: cached.session_id,
+        if_stale: true,
+        ...(cached.session_token_generation ? { session_token_generation: cached.session_token_generation } : {}),
+      };
+      let retired;
+      try {
+        retired = await call("close_session", cachedCloseArgs, cleanupOptions);
+      } catch (error) {
+        // BOT-1650 (Codex round-22): a THROWN cached-close (e.g. its idempotent
+        // close committed but the response was lost) must not bypass cleanup and
+        // strand the newly-admitted session — whose bearer is neither returned nor
+        // persisted — while the active holder blocks a later bridge thread with
+        // agent_session_conflict. Retry once (if_stale is idempotent) to confirm
+        // the old close; if it still cannot be confirmed, retire the new session
+        // before propagating.
+        const confirm = await call("close_session", cachedCloseArgs, cleanupOptions).catch((retryError) => ({ ok: false, error: retryError?.message }));
+        if (!confirm?.ok || confirm.isError) {
+          // BOT-1650 (Codex round-23): if retiring the new session ALSO fails (e.g.
+          // the same outage hits its direct AND durable close), do NOT swallow that
+          // and claim cleanup succeeded — the replacement bearer would stay active
+          // and block the next bootstrap. Surface both failures; a fresh bootstrap
+          // retries retirement (the orphaned session ages out / is re-reconciled).
+          try {
+            await discardNewSession();
+          } catch (discardError) {
+            // BOT-1650 (Codex round-24/25): retirement failed, so the new session
+            // is admitted but unpersisted. Record a cleanup marker (id+generation,
+            // no bearer) for a later bootstrap to drain, and fail closed preserving
+            // the cached-close cause, the retirement failure, and any marker-write
+            // failure (never swallowed).
+            await recordOrphanAndFail({ session, cwd: worktree, retirementError: discardError, primaryError: error });
+          }
+          throw error;
+        }
+        retired = confirm;
+      }
+      if (!retired?.ok || retired.isError) {
+        try {
+          await discardNewSession();
+        } catch (discardError) {
+          // BOT-1650 (Codex round-24/25): retirement failed here too — record the
+          // orphan and fail closed (propagating any marker-write failure).
+          await recordOrphanAndFail({ session, cwd: worktree, retirementError: discardError });
+        }
+        throw new Error(retired?.data?.error || retired?.error || "cached harness session is still live or could not be retired");
+      }
+      await clearHarnessSession(cached.session_id, {
+        cwd: worktree,
+        sessionToken: cached.session_token,
+        lock: false, // already inside withHarnessBootstrapLock (the same state lock); re-locking would deadlock
+      });
+    }
+    let state;
+    try {
+      state = await store(session, { cwd: worktree });
+    } catch (error) {
+      // The server session is unusable if this harness cannot persist its only
+      // credential. The freshly issued session bearer is scoped to this exact
+      // session and can self-close, so try it first — the durable OAuth/MCP
+      // credential may have expired or been revoked between bootstrap and
+      // cleanup, and using only that would strand an active session whose token
+      // was never returned or saved. Fall back to the durable credential just
+      // to confirm an ambiguous close (a lost tier-3 response that already
+      // revoked its own bearer).
+      const closeArgs = {
+        session_id: session.session_id,
+        ...(session.session_token_generation ? { session_token_generation: session.session_token_generation } : {}),
+      };
+      const direct = await closeWithDurableCredential(call, closeArgs, {
+        auth: { "x-agent-api-key": session.session_token },
+      });
+      if (direct.closed) throw error;
+      const cleanupOptions = callOptions ?? await resolveCleanupOptions();
+      if (!cleanupOptions) {
+        // BOT-1650 (Codex round-26): the fresh bearer could not self-close AND no
+        // durable credential is available to retire the admitted session — so it
+        // cannot be closed at all. Record the orphan (so a later bootstrap with a
+        // credential drains it) and fail closed, instead of throwing with no marker.
+        await recordOrphanAndFail({
+          session,
+          cwd: worktree,
+          retirementError: new Error("no durable credential is available to confirm session cleanup"),
+          primaryError: error,
+        });
+      }
+      const confirmed = await closeWithDurableCredential(call, closeArgs, cleanupOptions);
+      if (!confirmed.closed) {
+        // BOT-1650 (Codex round-25): the session was admitted but its credential
+        // could not be persisted AND neither the fresh-bearer nor the durable
+        // close confirmed retirement — an orphaned live holder unrelated to cache
+        // replacement (e.g. a Windows ACL-hardening failure in store()). Record it
+        // so a later bootstrap drains it, and fail closed preserving both causes.
+        const retirementError = new Error(cleanupError(confirmed.response) || direct.error?.message || "bootstrap persistence cleanup could not be confirmed");
+        await recordOrphanAndFail({ session, cwd: worktree, retirementError, primaryError: error });
+      }
+      throw error;
+    }
+    return { ...state, ...(displayName ? { display_name: displayName } : {}), ...(ticketSignals ? { ticket_signals: ticketSignals } : {}), ...(linkage ? { linkage } : {}) };
+  });
+}

package/src/setup-block.mjs

@@ -8,46 +8,39 @@
 // session persistence; normal operator output must never turn that into a
 // multi-command credential handoff.
 
+import { credentialTier } from "./credential-kinds.mjs";
+
 /** The canonical guide, referenced from every SETUP block and recovery. */
 export const CONNECTIVITY_GUIDE = "docs/agent-connectivity.md";
 
 // The three connectivity credential tiers, named consistently everywhere. A
 // connectivity error names the MISSING tier and the exact next command; the
 // guide's tiered table and the help SETUP block use these same labels.
+//
+// BOT-1701: the noun, prefix, flag, env, and kind for each tier are OWNED by
+// credential-kinds.mjs (CREDENTIAL_TIERS) — the single source of truth. This map
+// only adds the setup-specific fields (the tier number, the `setup` command, and
+// the scope). A drift test asserts every user-facing surface agrees with the
+// canonical table, so `label`/`prefix`/`env`/`flag` here can never fork from it.
 export const TIERS = Object.freeze({
   // Tier 1 — per-machine client key. `bb login`, USER-scoped (reaches every
   // tenant you belong to; each request pins one). Never a wait credential.
-  client: Object.freeze({
-    n: 1,
-    label: "client key",
-    prefix: "bb_cli_",
-    env: "BOTBUDDY_CLIENT_KEY",
-    setup: "bb login",
-    scope: "user",
-  }),
+  client: Object.freeze({ ...tierFields(1), setup: "bb login", scope: "user" }),
   // Tier 2 — per-tenant MCP config key. `bb mcp setup`, TENANT-bound, lives in
   // .mcp.json under $BOTBUDDY_MCP_KEY. Authenticates MCP calls + register_agent.
-  mcp: Object.freeze({
-    n: 2,
-    label: "MCP key",
-    prefix: "bb_mcp_",
-    env: "BOTBUDDY_MCP_KEY",
-    setup: "bb mcp setup",
-    scope: "tenant",
-  }),
-  // Tier 3 — per-session agent token, tenant-bound, 8 h TTL, revoked on
+  mcp: Object.freeze({ ...tierFields(2), setup: "bb mcp setup", scope: "tenant" }),
+  // Tier 3 — per-session agent session 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_sess_",
-    env: "BOTBUDDY_AGENT_SESSION_TOKEN",
-    setup: "register_agent",
-    scope: "session",
-  }),
+  session: Object.freeze({ ...tierFields(3), setup: "register_agent", scope: "session" }),
 });
 
+/** Project a canonical CREDENTIAL_TIERS row onto the TIERS shape (n/label/…). */
+function tierFields(tier) {
+  const t = credentialTier(tier);
+  return { n: t.tier, label: t.noun, prefix: t.prefix, env: t.env, flag: t.flag };
+}
+
 /**
  * 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.

package/src/test-lane.mjs

@@ -21,7 +21,7 @@ import { execFileSync } from "node:child_process";
 
 import { EXIT, launchRun, receiptPath, DEFAULT_TIMEOUT_SECONDS } from "./run.mjs";
 import { callToolJson } from "./api.mjs";
-import { readAgentSessionTokenEnv } from "./agent-key.mjs";
+import { readAgentSessionTokenEnv, legacyAgentAliasHint } from "./agent-key.mjs";
 import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredential } from "./agent-session.mjs";
 
 // EXIT.{OK,INVALID,BACKEND,INTERNAL} plus a --wait timeout code (AC-9).
@@ -338,7 +338,8 @@ function laneList(cwd) {
 }
 
 function testHelp() {
-  console.log(`botbuddy test <lane> [--session-id <uuid>] [--environment local] [--ticket <KEY>] [--pr <n>] [--repo <owner/repo>] [--lane-kind <${LANE_KINDS.join("|")}>] [--wait] [--json] [-- <extra args>]
+  console.log(`botbuddy test <lane> [--session-id <uuid>] [--agent-session-token <token>] [--environment local] [--ticket <KEY>] [--pr <n>] [--repo <owner/repo>] [--lane-kind <${LANE_KINDS.join("|")}>] [--wait] [--json] [-- <extra args>]
+  --agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN); --agent-key / --session-token are one-release legacy aliases
 botbuddy test list      List the lanes configured in .botbuddy/lanes.json
 botbuddy test help      Show this help
 
@@ -351,6 +352,9 @@ export async function cmdTest(args, { cwd = process.cwd() } = {}) {
   const { subcommand } = parseTestArgs(args);
   if (subcommand === "help" || args[0] === "--help" || args[0] === "-h") { testHelp(); return; }
   if (subcommand === "list") { process.exitCode = laneList(cwd); return; }
+  // BOT-1701 (AC-6): one stderr nudge for a tier-3 legacy flag/env alias.
+  const aliasHint = legacyAgentAliasHint({ argv: args, env: process.env });
+  if (aliasHint) process.stderr.write(`botbuddy test: ${aliasHint}\n`);
   const result = await launchTestLane(args, { cwd });
   process.stdout.write(result.line + "\n");
   // --wait (AC-9): after launch, block until the run completes and exit with the

package/src/wait.mjs

@@ -18,8 +18,8 @@ import { readAgentBinding, withPrincipalReceipt } from "./wait-profile.mjs";
 import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.mjs";
-import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
-import { clearAgentState, isRejectedCachedSession, resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
+import { AGENT_KEY_RE, readAgentSessionTokenEnv, legacyAgentAliasHint } from "./agent-key.mjs";
+import { clearAgentState, hasBootstrapAgentSession, isRejectedCachedSession, resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
 import { touchAgentStateExpiry } from "./agent-state.mjs";
 import { SETUP_BLOCK } from "./setup-block.mjs";
 import { createWaitCheckpointStore, WaitCheckpointError } from "./wait-checkpoint.mjs";
@@ -1344,6 +1344,16 @@ async function acknowledgeSavedWait(id) {
 
 export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   if (argv.length === 0 || argv[0] === "--offset") return inspectSavedWaits(argv);
+  // BOT-1701 (AC-6): one stderr nudge for a tier-3 legacy alias (flag, env, or a
+  // bb_agent_ token value), emitted BEFORE any subcommand dispatch so the
+  // credentialed recovery actions (resume/cancel/acknowledge) warn too (Codex R7).
+  // STDERR only, so a machine-parseable stdout receipt is byte-identical. Skipped
+  // on the internal recovery re-entry (resumeSavedWait recurses into runWait with
+  // recoveryLocalWaitId set) so a resume never nudges twice (Codex R8).
+  if (recoveryLocalWaitId == null) {
+    const aliasHint = legacyAgentAliasHint({ argv, env: process.env });
+    if (aliasHint) process.stderr.write(`botbuddy wait: ${aliasHint}\n`);
+  }
   if (argv[0] === "resume") {
     const id = argv[1];
     if (!id || argv.length > 2) return emitSavedWaitError(new WaitCheckpointError("wait_not_resumable", "select exactly one saved wait: bb wait resume <local_wait_id>"));
@@ -1505,7 +1515,11 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       : new WaitCheckpointError("wait_checkpoint_write_failed", String(error?.message ?? error)));
   }
 
-  const needsRelay = conditions.some((c) => c.type !== "timer");
+  // BOT-1650: a plain timer stays offline, but a timer from a bootstrapped harness
+  // registers so its terminal receipt proves the current session principal (the
+  // cross-shell bootstrap contract). Detected without a network self-heal.
+  const needsRelay = conditions.some((c) => c.type !== "timer")
+    || await hasBootstrapAgentSession({ cwd: process.cwd() });
   if (needsRelay) {
     try {
       const credential = await resolveAgentSessionCredential({ argv, env: process.env, cwd: process.cwd() });