@botbuddy/cli 1.31.1 → 1.31.2

package/package.json

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

package/src/agent-key.mjs

@@ -9,6 +9,8 @@
 // (supabase/functions/_shared/sessionToken.ts). The prior `bb_agent_` shape is
 // accepted as a legacy alias for one release (its hash is already on `sessions`).
 // This is a SHAPE check only — authorization is the server's hashed lookup.
+import { TIER3_LEGACY, credentialTier } from "./credential-kinds.mjs";
+
 export const AGENT_KEY_RE = /^bb_(agent|sess)_[0-9a-f]{64}$/;
 
 // BOT-1649: BOTBUDDY_AGENT_SESSION_TOKEN names the short-lived credential
@@ -32,3 +34,57 @@ export function readAgentSessionTokenEnv(env = process.env) {
 
 // Deprecated exported alias for downstream CLI integrations.
 export const readAgentKeyEnv = readAgentSessionTokenEnv;
+
+// BOT-1701 (AC-6) — one canonical stderr nudge when a tier-3 legacy alias is used
+// for a wait/run: a legacy CLI flag (--agent-key / --session-token), a legacy env
+// var (BOTBUDDY_AGENT_KEY / BOTBUDDY_SESSION_TOKEN) that actually supplied the
+// token, or a bb_agent_-prefixed token value. Returns a SINGLE line (never more)
+// naming the canonical flag + env, or null when only canonical names were used.
+// The caller writes it to STDERR only, so a machine-parseable stdout receipt is
+// byte-identical to a canonical-flag run. Precedence matches the CLI: a token
+// flag overrides the env, so the env is only "used" when no token flag was given.
+// The value passed after any tier-3 token flag (canonical or legacy), or null.
+function tokenAfterFlag(argv, flags) {
+  for (let i = 0; i < argv.length; i++) {
+    if (flags.includes(argv[i])) return argv[i + 1] ?? null;
+  }
+  return null;
+}
+
+export function legacyAgentAliasHint({ argv = [], env = process.env, token = null } = {}) {
+  const tier3 = credentialTier(3);
+  const canonicalFlag = tier3.flag; // --agent-session-token
+  const canonicalEnv = tier3.env; // BOTBUDDY_AGENT_SESSION_TOKEN
+  const tokenFlags = [canonicalFlag, ...TIER3_LEGACY.flags];
+
+  // Only the CLI's own args count. `bb run/test … -- <workload> --agent-key …`
+  // forwards a workload after `--` whose identically named flags are NOT BotBuddy
+  // credentials, so never scan past the separator (Codex R6).
+  const sep = argv.indexOf("--");
+  const cliArgs = sep === -1 ? argv : argv.slice(0, sep);
+
+  const legacyFlagUsed = TIER3_LEGACY.flags.some((f) => cliArgs.includes(f));
+  const flagToken = tokenAfterFlag(cliArgs, tokenFlags);
+  const anyTokenFlag = flagToken !== null || legacyFlagUsed || cliArgs.includes(canonicalFlag);
+
+  // The value the env would supply (canonical wins), so a bb_agent_ VALUE behind
+  // the canonical flag/env is nudged even though the NAME is canonical.
+  let legacyEnvUsed = false;
+  let envToken = null;
+  if (!anyTokenFlag) {
+    const canonical = typeof env[canonicalEnv] === "string" ? env[canonicalEnv].trim() : "";
+    if (canonical) {
+      envToken = env[canonicalEnv];
+    } else {
+      for (const e of TIER3_LEGACY.envs) {
+        if (typeof env[e] === "string" && env[e].trim() !== "") { legacyEnvUsed = true; envToken = env[e]; break; }
+      }
+    }
+  }
+
+  const effectiveToken = token ?? flagToken ?? envToken;
+  const legacyPrefixUsed = typeof effectiveToken === "string" && effectiveToken.startsWith(TIER3_LEGACY.prefix);
+
+  if (!legacyFlagUsed && !legacyEnvUsed && !legacyPrefixUsed) return null;
+  return `note: --agent-key / --session-token / $BOTBUDDY_AGENT_KEY / ${TIER3_LEGACY.prefix} are one-release legacy aliases — use ${canonicalFlag} or $${canonicalEnv} (docs/agent-connectivity.md)`;
+}

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/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,7 +18,7 @@ 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 { 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";
@@ -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>"));