@botbuddy/cli 1.27.0 → 1.29.0

package/package.json

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

package/src/commands.mjs

@@ -12,6 +12,7 @@ import { cmdDocker } from "./docker-hygiene.mjs";
 import { cmdRun } from "./run.mjs";
 import { cmdTest } from "./test-lane.mjs";
 import { runWait } from "./wait.mjs";
+import { SETUP_BLOCK } from "./setup-block.mjs";
 import { green, red, cyan, dim, bold, die } from "./utils.mjs";
 import { VERSION } from "./version.mjs";
 import { setupMcpKey, revokeMcpKey, resolveMcpConfigKey, resolveEnvVarName, DEFAULT_MCP_ENV_VAR, McpKeyError, McpKeyStoreError } from "./mcp-key.mjs";
@@ -114,8 +115,8 @@ async function cmdTelemetry(args) {
   return 0;
 }
 
-function cmdHelp() {
-  console.log(`${bold("bb")} ${dim(`v${VERSION}`)} — Swarm coordination CLI
+export function cmdHelp(log = console.log) {
+  log(`${bold("bb")} ${dim(`v${VERSION}`)} — Swarm coordination CLI
 
 ${dim(`Run everything as ${cyan("bb <command>")} — the short, preferred alias. ${cyan("botbuddy <command>")} is the identical long form.`)}
 
@@ -184,7 +185,9 @@ ${bold("OTHER")}
   locks -m [--host name]    Reserve typed local resources, including Playwright MCP lanes
   update                     Install the latest @botbuddy/cli in the background via npm
   help                       Show this help
-  version                    Show version`);
+  version                    Show version
+
+${SETUP_BLOCK}`);
 }
 
 // ─── BOT-876: generic tool access ───────────────────────────────
@@ -325,8 +328,8 @@ async function cmdLogin(args, { errorLog = (line) => console.error(line) } = {})
   }
 }
 
-function loginHelp() {
-  console.log(`${bold("botbuddy login")} — authenticate via OAuth (browser + loopback callback)
+export function loginHelp(log = console.log) {
+  log(`${bold("botbuddy login")} — authenticate via OAuth (browser + loopback callback)
 
 ${bold("USAGE")}
   botbuddy login [--no-browser] [--tenant <slug>]
@@ -390,7 +393,9 @@ ${bold("NOTES")}
 ${bold("RECOVERY")}
   If ${cyan("botbuddy status")} shows no client key, run ${cyan("botbuddy login")}. For an
   unattended CI host (no browser), mint a key on a machine with a browser
-  (${cyan("botbuddy mcp setup")}) and export it as ${cyan("$BOTBUDDY_MCP_KEY")} on the CI host.`);
+  (${cyan("botbuddy mcp setup")}) and export it as ${cyan("$BOTBUDDY_MCP_KEY")} on the CI host.
+
+${SETUP_BLOCK}`);
 }
 
 async function cmdStart(args) {
@@ -599,7 +604,7 @@ function cmdHeartbeat(args) {
 
 // ─── BOT-1607: `botbuddy mcp` — the tier-2 bb_mcp_ config key ────────────────
 
-function mcpHelp(log) {
+export function mcpHelp(log = console.log) {
   log(`Usage: botbuddy mcp <setup|revoke|status|env> [options]
 
   setup [--env <NAME>] [--tenant <slug>] [--label <label>] [--expiry-days <n>] [--force]
@@ -607,6 +612,9 @@ function mcpHelp(log) {
                     ${cyan("botbuddy login")} owner/client credential), store it in the
                     Keychain under ${dim("BOTBUDDY_MCP_KEY")} (or --env <NAME>), and print
                     the .mcp.json / .codex/config.toml snippets that reference it.
+                    A bb_mcp_ key is tenant-sealed: on a machine serving more than
+                    one tenant, mint each tenant under a distinct --env <NAME> var
+                    and commit that repo's matching .botbuddy-agent.json mcp_env.
                     Refuses an occupied Keychain slot unless --force (revoke the
                     old key first — --force leaves it live server-side).
   revoke <agent_id> [--tenant <slug>] [--env <NAME>]
@@ -625,7 +633,9 @@ function mcpHelp(log) {
                     or in the desktop LaunchAgent env-install recipe.
 
 Present the key from .mcp.json instead of reusing an agent session token — it is
-independently revocable, so a leaked config credential rotates without a re-login.`);
+independently revocable, so a leaked config credential rotates without a re-login.
+
+${SETUP_BLOCK}`);
 }
 
 // Actionable recovery for an mcp setup/revoke failure code.

package/src/pw/run.mjs

@@ -35,7 +35,7 @@ async function gate({ env, host, lane, deps }) {
   // server's owner_is_caller.
   const sessionToken = deps.sessionToken ?? readAgentKeyEnv(env);
   if (sessionToken && !AGENT_KEY_RE.test(sessionToken)) {
-    return { allowed: false, message: "bb-pw: $BOTBUDDY_AGENT_KEY is malformed (expected bb_agent_<64 hex>). Re-register the agent, or set BB_PW_NO_LOCK=1 for local-only work." };
+    return { allowed: false, message: "bb-pw: $BOTBUDDY_AGENT_KEY is malformed (tier-3 session token; expected bb_agent_<64 hex>). Re-register: register_agent → export BOTBUDDY_AGENT_KEY. See docs/agent-connectivity.md. (BB_PW_NO_LOCK=1 runs local-only, unlocked.)" };
   }
   const sessionAgentId = deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null;
   const registeredAgentId = await (deps.readSessionAgentId ?? readRegisteredAgentId)();
@@ -49,7 +49,7 @@ async function gate({ env, host, lane, deps }) {
       } catch { token = null; }
     }
     if (!token) {
-      return { allowed: false, message: "bb-pw: no BotBuddy credential — export $BOTBUDDY_AGENT_KEY (from register_agent) or your .mcp.json key ($BOTBUDDY_MCP_KEY), or set BB_PW_NO_LOCK=1 for local-only work." };
+      return { allowed: false, message: "bb-pw: no BotBuddy credential — a lane needs the tier-3 session token (bb_agent_: register_agent → export $BOTBUDDY_AGENT_KEY) or your tier-2 .mcp.json key ($BOTBUDDY_MCP_KEY, bb mcp setup). See docs/agent-connectivity.md. (BB_PW_NO_LOCK=1 runs local-only, unlocked.)" };
     }
     coordinator = createSessionTokenCoordinator({ token, fetchImpl: deps.fetch });
   }

package/src/setup-block.mjs

@@ -0,0 +1,75 @@
+// BOT-1644 — ONE source of truth for the connectivity ladder and the credential
+// tier names, so every CLI help surface (`bb --help`, `bb wait --help`,
+// `bb login --help`, `bb mcp --help`), the recovery strings, and the canonical
+// guide all agree. The snapshot test (agent-connectivity.test.mjs) asserts the
+// SETUP block appears verbatim in all four help outputs, so drift is caught.
+//
+// This documents the CURRENT supported process (BOT-1644 scope). It does NOT
+// describe the P1–P6 "self-healing auth" redesign, which is a separate future
+// project.
+
+/** 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.
+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",
+  }),
+  // 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. `register_agent` (over MCP), tenant-bound,
+  // 8 h TTL, revoked on re-register. The ONLY credential a wait/run/test/pw
+  // accepts. Exported as $BOTBUDDY_AGENT_KEY (+ $BOTBUDDY_SESSION_ID for
+  // attribution).
+  session: Object.freeze({
+    n: 3,
+    label: "session token",
+    prefix: "bb_agent_",
+    env: "BOTBUDDY_AGENT_KEY",
+    setup: "register_agent",
+    scope: "session",
+  }),
+});
+
+// The register_agent → export handoff, named once. Recovery strings reuse it so
+// the exact two export lines never drift from the guide.
+export const EXPORT_STEP =
+  "register_agent → export BOTBUDDY_AGENT_KEY=<session_token> (and BOTBUDDY_SESSION_ID=<session_id>)";
+
+/**
+ * The shared SETUP block reproduced verbatim in every `--help` output. Plain
+ * text (no ANSI) so the snapshot test can match it byte-for-byte across surfaces.
+ * The E2E ladder in order, then the fresh-shell caveat and the guide link.
+ */
+export const SETUP_BLOCK = `SETUP — the connectivity ladder (install → connect → wait)
+  1. npm i -g @botbuddy/cli                 install the CLI
+  2. bb login                               tier 1 · client key (bb_cli_, user-scoped) → Keychain
+  3. bb mcp setup                           tier 2 · MCP key (bb_mcp_, tenant-bound) → Keychain + .mcp.json ($BOTBUDDY_MCP_KEY)
+                                            (Keychainless host: the key is printed ONCE — store + export + edit .mcp.json yourself)
+                                            the repo's pre-committed .botbuddy-agent.json binds tenant + mcp_env
+                                            multi-tenant machine: mint each tenant under a distinct --env <NAME> var (they collide otherwise)
+  4. register_agent (over MCP)              tier 3 · session token (bb_agent_, per-session, 8 h)
+  5. export BOTBUDDY_AGENT_KEY=<session_token>   and   BOTBUDDY_SESSION_ID=<session_id>
+  6. bb wait                                needs the tier-3 token; bb run/test also accept $BOTBUDDY_SESSION_ID,
+                                            bb pw falls back to the tier-2 MCP key
+  NOTE: each Claude Code Bash call is a FRESH shell — exports do NOT persist between tool calls;
+        re-export (or pass --agent-key <token>) in the same command that runs the wait.
+  Full guide: ${CONNECTIVITY_GUIDE}`;

package/src/wait.mjs

@@ -19,6 +19,7 @@ import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.mjs";
 import { AGENT_KEY_RE, readAgentKeyEnv } from "./agent-key.mjs";
+import { SETUP_BLOCK } from "./setup-block.mjs";
 
 // A protocol is deliberately distinct from package semver: compatible pinned
 // clients keep working until the server raises this minimum, while a stale
@@ -36,7 +37,7 @@ const MIN_RECEIPT_MAX_BYTES = 512;
 // BOT-1572 bb_sess_ legacy alias, both accepted for one release.
 const SESSION_TOKEN_RE = AGENT_KEY_RE;
 
-const HELP = `botbuddy wait — one wait command instead of a polling loop (BOT-989)
+export const HELP = `botbuddy wait — one wait command instead of a polling loop (BOT-989)
 
 USAGE
   botbuddy wait [--any] <condition>... [options]
@@ -159,6 +160,8 @@ EXAMPLES
   # after pushing review fixes, wait for the next review comment or a state change
   botbuddy wait --any 'pr-review:repo=bot-buddy/botbuddy-webapp,pr=425' \\
                 'pr-state:repo=bot-buddy/botbuddy-webapp,pr=425' --timeout 3600
+
+${SETUP_BLOCK}
 `;
 
 function parseArgv(argv) {
@@ -630,11 +633,11 @@ function emit(receipt, { versioned = false, maxBytes = null } = {}) {
 // SAME string is written to stderr and the receipt `recovery` field that /waits
 // renders. Keep each to one line and never embed a secret value — names, slots,
 // and env-var names only.
-const RECOVERY = Object.freeze({
+export const RECOVERY = Object.freeze({
   // BOT-1582: $BOTBUDDY_AGENT_KEY (bb_agent_+64hex, renamed from
   // $BOTBUDDY_SESSION_TOKEN) is minted by register_agent; the harness exports it
   // at session start. The legacy var is still accepted for one release.
-  sessionToken: "register_agent → export BOTBUDDY_AGENT_KEY=<session_token> (the harness exports it at session start)",
+  sessionToken: "the tier-3 session token (bb_agent_) is minted by register_agent — export BOTBUDDY_AGENT_KEY=<session_token> (and BOTBUDDY_SESSION_ID=<session_id>); the harness exports both at session start. See docs/agent-connectivity.md",
   // $BOTBUDDY_SESSION_ID is the work-graph session id returned by register_agent.
   sessionId: "register_agent → export BOTBUDDY_SESSION_ID=<session_id> (the work-graph session id from register_agent)",
   // A --token / session-token contradiction: the session token is the whole
@@ -962,7 +965,7 @@ export async function runWait(argv) {
         // register a work agent and export its session token.
         if (err.errorCode === "client_key_cannot_wait") {
           process.stderr.write(
-            "botbuddy wait: a client key (botbuddy login) cannot arm a wait — register_agent, export BOTBUDDY_AGENT_KEY=<session_token>, then re-run\n",
+            "botbuddy wait: a tier-1 client key (bb_cli_, botbuddy login) cannot arm a wait — you need the tier-3 session token: register_agent, export BOTBUDDY_AGENT_KEY=<session_token>, then re-run\n",
           );
           emitReceipt({
             schema_version: 1,