@botbuddy/cli 1.22.0 → 1.24.0

package/src/commands.mjs

@@ -1,3 +1,4 @@
+import os from "node:os";
 import { callTool, callToolJson, readResource } from "./api.mjs";
 import { doLogin } from "./auth.mjs";
 import { runBridge } from "./codex-bridge.mjs";
@@ -14,6 +15,7 @@ import { runWait } from "./wait.mjs";
 import { green, red, cyan, dim, bold, die } from "./utils.mjs";
 import { VERSION } from "./version.mjs";
 import { bootstrapProfile, ProfileBootstrapError, profileBootstrapRecovery, profileShellRefresh } from "./profile-bootstrap.mjs";
+import { setupMcpKey, revokeMcpKey, resolveMcpConfigKey, resolveEnvVarName, DEFAULT_MCP_ENV_VAR, McpKeyError, McpKeyStoreError } from "./mcp-key.mjs";
 import { runPw } from "./pw/run.mjs";
 import { maybeWarnStale, cmdUpdate } from "./update-check.mjs";
 
@@ -55,6 +57,8 @@ export async function run(argv, {
     case "wait": return runWait(args);
     case "pw": return runPw(args);
     case "profile": return cmdProfile(args);
+    case "carrier": return cmdCarrier(args);
+    case "mcp": return cmdMcp(args);
     case "resources": return callTool("list_resources");
     case "agents": return callTool("list_agents");
     case "tasks": return readResource("botbuddy://tasks");
@@ -96,13 +100,23 @@ ${bold("AUTH")}
                              Authenticate via OAuth (opens browser + localhost callback)
   logout                     Remove saved credentials
   status                     Show current auth status (local metadata + server check)
-  profile setup <profile>    Mint/reconnect and securely store a tenant-bound agent key
+  carrier setup <profile>    CI hosts only: store an unattended tenant-bound carrier key
+                             (interactive operators use ${cyan("login")} — it installs the client key)
+
+${bold("MCP CONFIG KEY")}
+  mcp setup [--env <NAME>] [--tenant <slug>] [--label <l>] [--expiry-days <n>]
+                             Mint a bb_mcp_ key for your .mcp.json (independently
+                             revocable; stored under ${dim("BOTBUDDY_MCP_KEY")})
+  mcp revoke <agent_id>      Revoke only that MCP key (login + sessions unaffected)
+  mcp status                 Which env var holds the MCP key (never prints it)
 
 ${bold("TOOLS")}
   help --tools               List every BotBuddy tool
   help <tool>                Show one tool's arguments
   call <tool> [--key value]  Invoke any tool
   call <tool> --json '{...}' Invoke with a JSON arguments object
+  call <tool> --pin <slug>   Pin the connection tenant (a user token needs one;
+                             default: BOTBUDDY_TENANT → repo profile → sole tenant)
 
 ${bold("STACK LEASES")}
   stack up [options]         Request a batch-scoped local stack lease; park if full; hold it active
@@ -146,7 +160,8 @@ async function cmdCall(args) {
     if (e instanceof CallUsageError) die(e.message);
     throw e;
   }
-  return callTool(parsedArgs.tool, parsedArgs.args);
+  // BOT-1571: an explicit --pin beats the derived default pin (see api.mjs).
+  return callTool(parsedArgs.tool, parsedArgs.args, { tenant: parsedArgs.pin });
 }
 
 async function cmdToolHelp(args) {
@@ -280,6 +295,15 @@ ${bold("USAGE")}
   botbuddy login [--no-browser] [--tenant <slug>]
                  [--caller <name>] [--caller-harness <harness>] [--caller-ticket <ref>]
 
+${bold("TOKEN SCOPE")}
+  By default login installs this machine's ${bold("client key (bb_cli_)")}: a user
+  token that is not bound to a tenant and reaches every tenant you belong to —
+  each request pins one. ONE login serves ALL tenants; ${cyan("register_agent")} then
+  exchanges it for a per-session agent token. No per-tenant ${cyan("profile setup")} is
+  needed (that path is now CI-carrier only).
+  ${cyan("--tenant <slug>")} instead mints a ${bold("tenant token")} sealed to that one
+  tenant (the MCP-session model); use it only when you want that guarantee.
+
 ${bold("HOW IT WORKS")}
   Starts a localhost callback listener on an ephemeral 127.0.0.1 port, opens
   your default browser at the BotBuddy authorization page, and waits for you to
@@ -293,9 +317,10 @@ ${bold("OPTIONS")}
                  in a browser on THIS machine yourself. The callback listener
                  still runs on this machine's localhost.
   --tenant <slug>
-                 Preselect a tenant (e.g. ${cyan("supply-guard")}) on the sign-in page when
-                 your account belongs to more than one. Must be a lowercase slug;
-                 membership is still enforced by the server.
+                 Mint a token SEALED to one tenant (e.g. ${cyan("supply-guard")}); the
+                 sign-in page shows it as requested by the CLI. Must be a lowercase
+                 slug; membership is still enforced by the server. Without it the
+                 token is a user token that reaches all your tenants.
   --caller <name>
                  Show WHO requested this login on the authorization screen, so
                  the human approving it can confirm the request came from the
@@ -325,8 +350,8 @@ ${bold("NOTES")}
     reach the listener and login will time out.
 
 ${bold("RECOVERY")}
-  If ${cyan("botbuddy profile setup <profile>")} reports an authentication error,
-  run ${cyan("botbuddy login")} first, then re-run profile setup.`);
+  If ${cyan("botbuddy status")} shows no client key, run ${cyan("botbuddy login")}. For an
+  unattended CI host (no browser), use ${cyan("botbuddy carrier setup <profile>")}.`);
 }
 
 async function cmdStart(args) {
@@ -382,27 +407,38 @@ const STATUS_PROBE_TIMEOUT_MS = 4000;
 // so a future opaque-token size change can't reintroduce the false rejection.
 const looksLikeOwnerToken = (t) => typeof t === "string" && /^mcp_at_[0-9a-f]{32,}$/.test(t);
 
-async function logServerStatus(call, auth, log) {
-  let res;
-  try {
-    res = await call("whoami", {}, { auth, signal: AbortSignal.timeout(STATUS_PROBE_TIMEOUT_MS) });
-  } catch {
-    log(`  server: ${red("unreachable")}`);
-    return;
-  }
-  if (res?.ok && !res.isError) {
-    const slug = typeof res.data?.tenant_id === "string" && res.data.tenant_id ? res.data.tenant_id : "tenant unresolved";
-    log(`  server: ${green("authenticated")} (${slug})`);
-    return;
+async function logServerStatus(call, auth, log, { tenant = null, tenants = null } = {}) {
+  // BOT-1571: a USER token is refused unpinned (MCP_TENANT_PIN_REQUIRED), so the
+  // probe carries a pin the token is known to reach when one is stored. Codex
+  // round 9 (P2): user-token membership is evaluated PER REQUEST, so a tenant
+  // cached at login may be stale — probe EACH recorded tenant until one
+  // authenticates before reporting the token rejected.
+  const pins = Array.isArray(tenants) && tenants.length ? tenants : [tenant];
+  let lastRes = null;
+  for (const pin of pins) {
+    let res;
+    try {
+      res = await call("whoami", {}, { auth, signal: AbortSignal.timeout(STATUS_PROBE_TIMEOUT_MS), ...(pin ? { tenant: pin } : {}) });
+    } catch {
+      log(`  server: ${red("unreachable")}`);
+      return;
+    }
+    if (res?.ok && !res.isError) {
+      const slug = typeof res.data?.tenant_id === "string" && res.data.tenant_id ? res.data.tenant_id : "tenant unresolved";
+      log(`  server: ${green("authenticated")} (${slug})`);
+      return;
+    }
+    if (res?.status === null && /^transport:/.test(String(res?.error ?? ""))) {
+      log(`  server: ${red("unreachable")}`);
+      return;
+    }
+    lastRes = res; // a rejection for this pin — try the next recorded tenant
   }
+  const res = lastRes;
   if (res?.ok && res.isError) {
     log(`  server: ${red("rejected")} (${res.data?.error ?? res.data?.code ?? "tool error"})`);
     return;
   }
-  if (res?.status === null && /^transport:/.test(String(res?.error ?? ""))) {
-    log(`  server: ${red("unreachable")}`);
-    return;
-  }
   log(`  server: ${red("rejected")} (${res?.error ?? "unknown error"})`);
 }
 
@@ -413,6 +449,8 @@ export async function cmdStatus({
   callToolJson: call = callToolJson,
   log = (line) => console.log(line),
   now = () => Date.now(),
+  hostname = () => os.hostname(),
+  env = process.env,
 } = {}) {
   const cfg = getCfg();
   const owner = await resolveOwner({ getConfig: getCfg });
@@ -430,6 +468,29 @@ export async function cmdStatus({
     }
     if (cfg.agent_name) log(`  Agent: ${cyan(cfg.agent_name)}`);
     if (cfg.client_id) log(`  Client: ${dim(cfg.client_id)}`);
+    // BOT-1571/BOT-1574: what kind of token this is. A `user` token is the
+    // per-machine CLIENT KEY (bb_cli_): host-bound at login, reaching every
+    // listed tenant (each request pins one). A `tenant` token is sealed to one.
+    // A pre-1571 login has no recorded scope and prints nothing rather than a
+    // guess.
+    const ownerTenants = Array.isArray(owner.tenants) ? owner.tenants : [];
+    if (ownerValid && owner.tenantMode === "user") {
+      const memberships = ownerTenants.length ? ownerTenants.join(", ") : dim("none recorded");
+      log(`  ${cyan("Client key (bb_cli_)")} · host ${dim(hostname())} · memberships: ${memberships}`);
+      // BOT-1574 AC1: the per-tenant Keychain agent-key slots (BOT-1558) are
+      // retired for interactive use — the client key replaces them. If any are
+      // still exported, they are IGNORED; say so once so the operator can drop
+      // them. The per-session token var $BOTBUDDY_AGENT_KEY (no middle segment)
+      // is the live wait credential and must never be flagged here.
+      const ignoredSlots = Object.keys(env ?? {})
+        .filter((k) => /^BOTBUDDY_[A-Z0-9]+_AGENT_KEY$/.test(k))
+        .sort();
+      if (ignoredSlots.length) {
+        log(`  ${dim("!")} ignoring ${ignoredSlots.join(", ")} — botbuddy login's client key is used instead (per-tenant agent-key slots are retired for interactive use).`);
+      }
+    } else if (ownerValid && owner.tenantMode === "tenant" && owner.tenantId) {
+      log(`  Token scope: ${cyan("tenant")} (${owner.tenantId})`);
+    }
     if (ownerValid && owner.expiresAt) {
       const remaining = owner.expiresAt - now();
       if (remaining <= 0) {
@@ -464,6 +525,11 @@ export async function cmdStatus({
       call,
       fallbackKey ? { "x-agent-api-key": fallbackKey } : { Authorization: `Bearer ${owner.token}` },
       log,
+      // Pin only for a user token probed as itself; an agent key or a sealed
+      // token resolves its own tenant. Probe EVERY recorded tenant (round 9 P2):
+      // membership is per-request, so the first cached tenant may be stale while
+      // another is still valid.
+      !fallbackKey && owner.tenantMode === "user" ? { tenants: ownerTenants } : {},
     );
     return;
   }
@@ -530,38 +596,322 @@ function cmdHeartbeat(args) {
   return args[0] ? callTool("heartbeat", { current_task: args[0] }) : callTool("heartbeat");
 }
 
-async function cmdProfile(args) {
+// BOT-1574 AC6: the carrier bootstrap that `profile setup --unattended` and
+// `carrier setup` share. Never gated on a TTY — the caller decides whether the
+// interactive guard applies before reaching here.
+async function runCarrierSetup(profile, { log, setExitCode, bootstrap }) {
+  try {
+    const receipt = await bootstrap(profile, { call: callToolJson });
+    log(JSON.stringify(receipt));
+  } catch (error) {
+    const code = error instanceof ProfileBootstrapError ? error.code : "profile_agent_required";
+    log(JSON.stringify({
+      schema_version: 1,
+      outcome: "error",
+      error: code,
+      recovery: profileBootstrapRecovery(code, profile),
+    }));
+    setExitCode(3);
+  }
+}
+
+export async function cmdProfile(args, {
+  isTTY = Boolean(process.stdout.isTTY),
+  log = (line) => console.log(line),
+  setExitCode = (n) => { process.exitCode = n; },
+  bootstrap = bootstrapProfile,
+} = {}) {
   if (args[0] === "--help" || args[0] === "-h") {
-    console.log(`Usage: botbuddy profile <setup|env> <botbuddy-dev|supplyguard-dev>
+    console.log(`Usage: botbuddy profile <setup|env> <botbuddy-dev|supplyguard-dev> [--unattended]
 
-  setup <profile>   Mint/reconnect and securely store a tenant-bound agent key
-  env <profile>     Print shell exports that load the stored agent key`);
+  setup <profile>   Carrier-only (CI): mint/reconnect and store a tenant-bound
+                    carrier key. Retired for interactive use — run ${cyan("botbuddy login")}
+                    on a workstation. On a TTY this refuses unless --unattended.
+  env <profile>     Print shell exports that load the stored carrier key
+
+Interactive operators: ${cyan("botbuddy login")} installs the per-machine client key.
+CI hosts: ${cyan("botbuddy carrier setup <profile>")} (alias of setup --unattended).`);
     return;
   }
   if (args[0] === "env" && args[1] && args.length === 2) {
     try {
-      console.log(profileShellRefresh(args[1]));
+      log(profileShellRefresh(args[1]));
       return;
     } catch {
       die("Usage: botbuddy profile env <botbuddy-dev|supplyguard-dev>");
     }
   }
-  if (args[0] !== "setup" || !args[1] || args.length > 2) {
-    die("Usage: botbuddy profile <setup|env> <botbuddy-dev|supplyguard-dev>");
+  const unattended = args.includes("--unattended");
+  const positionals = args.filter((a) => !a.startsWith("-"));
+  if (positionals[0] !== "setup" || !positionals[1] || positionals.length > 2) {
+    die("Usage: botbuddy profile <setup|env> <botbuddy-dev|supplyguard-dev> [--unattended]");
   }
-  try {
-    const receipt = await bootstrapProfile(args[1], { call: callToolJson });
-    console.log(JSON.stringify(receipt));
-  } catch (error) {
-    const code = error instanceof ProfileBootstrapError ? error.code : "profile_agent_required";
-    console.log(JSON.stringify({
+  const profile = positionals[1];
+  // BOT-1574 AC6: interactive setup is retired. A human on a TTY who did not ask
+  // for the unattended carrier path is redirected to `botbuddy login` (which
+  // installs the machine client key) instead of minting a per-tenant slot. A
+  // non-TTY caller (CI) or an explicit --unattended keeps the carrier path.
+  if (isTTY && !unattended) {
+    log(JSON.stringify({
       schema_version: 1,
       outcome: "error",
-      error: code,
-      recovery: profileBootstrapRecovery(code, args[1]),
+      error: "interactive_use_retired",
+      recovery: `Interactive profile setup is retired. Run \`botbuddy login\` to install this machine's client key (bb_cli_) — it reaches every tenant you belong to, no per-tenant slot needed. For an unattended CI carrier, re-run with --unattended or use \`botbuddy carrier setup ${profile}\`.`,
+    }));
+    setExitCode(4);
+    return;
+  }
+  await runCarrierSetup(profile, { log, setExitCode, bootstrap });
+}
+
+// BOT-1574 AC6: `botbuddy carrier setup <profile>` — the explicit CI-carrier
+// alias of `profile setup --unattended`. Being the named carrier command, it is
+// never subject to the interactive-TTY guard.
+export async function cmdCarrier(args, {
+  log = (line) => console.log(line),
+  setExitCode = (n) => { process.exitCode = n; },
+  bootstrap = bootstrapProfile,
+} = {}) {
+  if (args[0] === "--help" || args[0] === "-h" || args.length === 0) {
+    console.log(`Usage: botbuddy carrier setup <botbuddy-dev|supplyguard-dev>
+
+  Mint/reconnect and store an unattended CI carrier key (alias of
+  ${cyan("botbuddy profile setup <profile> --unattended")}). Interactive operators use
+  ${cyan("botbuddy login")} instead.`);
+    return;
+  }
+  const positionals = args.filter((a) => !a.startsWith("-"));
+  if (positionals[0] !== "setup" || !positionals[1] || positionals.length > 2) {
+    die("Usage: botbuddy carrier setup <botbuddy-dev|supplyguard-dev>");
+  }
+  await runCarrierSetup(positionals[1], { log, setExitCode, bootstrap });
+}
+
+// ─── BOT-1607: `botbuddy mcp` — the tier-2 bb_mcp_ config key ────────────────
+
+function mcpHelp(log) {
+  log(`Usage: botbuddy mcp <setup|revoke|status> [options]
+
+  setup [--env <NAME>] [--tenant <slug>] [--label <label>] [--expiry-days <n>] [--force]
+                    Mint a bb_mcp_ MCP config key (authenticated by your
+                    ${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.
+                    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>]
+                    Revoke ONLY that MCP key (returned by setup). Your login and
+                    live agent sessions keep working. Multi-tenant owners must
+                    pin the tenant the key was minted for with --tenant. Pass
+                    --env <NAME> and the receipt's cleanup command names that
+                    slot (revoke never deletes local Keychain items itself).
+  status [--env <NAME>]
+                    Report which env var holds the MCP config key (never prints
+                    the secret). ${dim("BOTBUDDY_BB_AGENT_KEY")} is honoured as a deprecated
+                    alias for one release.
+
+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.`);
+}
+
+// Actionable recovery for an mcp setup/revoke failure code.
+export function mcpRecovery(code) {
+  switch (code) {
+    case "not_authenticated":
+      return "run `botbuddy login` to install this machine's client key, then re-run `botbuddy mcp setup`.";
+    case "owner_required":
+      return "minting requires your owner/client credential — run `botbuddy login` (an agent or MCP key cannot mint a key).";
+    case "tenant_pin_required":
+      return "you belong to more than one tenant — pin the tenant the key lives in: `botbuddy mcp setup --tenant <slug>` (or `botbuddy mcp revoke <agent_id> --tenant <slug>`).";
+    case "mcp_key_store_failed":
+      return "the key was minted but not stored — unlock your login keychain (`security unlock-keychain`) and re-run `botbuddy mcp setup`.";
+    case "invalid_env_var":
+      return "--env must be an UPPER_SNAKE_CASE variable name, e.g. BOTBUDDY_MCP_KEY_WORK.";
+    case "reserved_env_var":
+      return "that --env name belongs to another BotBuddy credential (it would clobber that Keychain slot) — pick a distinct MCP var like BOTBUDDY_MCP_KEY_WORK.";
+    case "env_var_in_use":
+      return "that Keychain slot already holds a key — revoke the old server key (`botbuddy mcp revoke <agent_id>`) if it is still live, then clear the local slot with `security delete-generic-password -s <NAME>`; or use a different --env, or pass --force to replace it in place.";
+    case "keychain_read_failed":
+      return "couldn't read the Keychain to check the slot (locked/unavailable) — unlock it (`security unlock-keychain`) and retry, or pass --force to skip the check.";
+    case "not_an_mcp_key":
+      return "that agent_id is not a bb_mcp_ key — pass the agent_id `botbuddy mcp setup` returned.";
+    case "not_found":
+      return "no MCP key with that agent_id — check the id from `botbuddy mcp setup`.";
+    case "forbidden":
+      return "that key is not in the pinned tenant — pin the tenant it was minted for with `--tenant <slug>` (and you must be a member).";
+    case "tenant_forbidden":
+      return "you are not a member of the pinned tenant — pin one you belong to with `--tenant <slug>` (re-login won't fix a tenant mismatch).";
+    case "invalid_label":
+      return "--label requires a value, e.g. --label laptop.";
+    case "unexpected_arg":
+      return "botbuddy mcp setup takes no positional arguments — pass options like --env <NAME> / --tenant <slug> / --label <label>.";
+    default:
+      return "run `botbuddy login`, then re-run the command.";
+  }
+}
+
+export function parseMcpSetupArgs(args) {
+  const out = { envVar: DEFAULT_MCP_ENV_VAR, tenant: null, label: null, expiryDays: null, force: false };
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    const take = (flag) => (arg.startsWith(`${flag}=`) ? arg.slice(flag.length + 1) : args[++i]);
+    if (arg === "--force" || arg === "-f") { out.force = true; continue; }
+    if (arg === "--env" || arg.startsWith("--env=")) {
+      // Codex P2: a bare `--env` (no value) must NOT silently fall back to the
+      // default slot and mint there — distinguish a missing value from a missing
+      // option.
+      const val = take("--env");
+      if (val === undefined || val === "") throw new McpKeyError("invalid_env_var", { detail: "--env requires a variable name, e.g. BOTBUDDY_MCP_KEY_WORK" });
+      out.envVar = resolveEnvVarName(val);
+      continue;
+    }
+    if (arg === "--tenant" || arg.startsWith("--tenant=")) {
+      const value = take("--tenant");
+      if (typeof value !== "string" || !TENANT_SLUG_RE.test(value)) die("error: --tenant must be a lowercase slug");
+      out.tenant = value;
+      continue;
+    }
+    if (arg === "--label" || arg.startsWith("--label=")) {
+      // Codex P2: a bare `--label` (no value) must not silently mint an unlabeled
+      // key — a missing value is a usage error, like --env.
+      const val = take("--label");
+      if (val === undefined || val === "") throw new McpKeyError("invalid_label", { detail: "--label requires a value" });
+      out.label = val;
+      continue;
+    }
+    if (arg === "--expiry-days" || arg.startsWith("--expiry-days=")) {
+      const value = Number(take("--expiry-days"));
+      if (!Number.isInteger(value) || value <= 0) die("error: --expiry-days must be a positive integer");
+      out.expiryDays = value;
+      continue;
+    }
+    if (arg.startsWith("-")) die(`Unknown mcp setup option: ${arg}. Run ${cyan("botbuddy mcp --help")}.`);
+    // Codex P2: a stray positional (`mcp setup laptop`, or a misspelled option
+    // value) must be a usage error, not silently ignored while a live credential
+    // is minted with defaults. mcp setup takes options only.
+    throw new McpKeyError("unexpected_arg", { detail: arg });
+  }
+  return out;
+}
+
+// BOT-1607 (Codex P2): `mcp status` accepts the same `--env <NAME>` an install
+// used, so a custom install reports correctly. Returns the requested var name
+// (the default when the flag is absent); a bad name throws invalid_env_var.
+export function parseMcpStatusEnv(args) {
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--env" || arg.startsWith("--env=")) {
+      const raw = arg.startsWith("--env=") ? arg.slice("--env=".length) : args[++i];
+      if (raw === undefined || raw === "") throw new McpKeyError("invalid_env_var", { detail: "--env requires a variable name, e.g. BOTBUDDY_MCP_KEY_WORK" });
+      // Explicit selector → inspect exactly this var (canonical or custom).
+      // Read-only: the deprecated alias BOTBUDDY_BB_AGENT_KEY is allowed here.
+      return { envVar: resolveEnvVarName(raw, { forWrite: false }), explicit: true };
+    }
+    if (arg.startsWith("-")) die(`Unknown mcp status option: ${arg}. Run ${cyan("botbuddy mcp --help")}.`);
+  }
+  return { envVar: DEFAULT_MCP_ENV_VAR, explicit: false };
+}
+
+export async function cmdMcp(args, {
+  log = (line) => console.log(line),
+  setExitCode = (n) => { process.exitCode = n; },
+  setup = setupMcpKey,
+  revoke = revokeMcpKey,
+  resolveConfigKey = resolveMcpConfigKey,
+  env = process.env,
+} = {}) {
+  if (args[0] === "--help" || args[0] === "-h") return mcpHelp(log);
+  const sub = args.find((a) => !a.startsWith("-"));
+  if (!sub) return mcpHelp(log);
+
+  if (sub === "setup") {
+    try {
+      // Parse inside the try so a bad --env (missing value / reserved name) becomes
+      // an error receipt rather than an uncaught throw (Codex P2).
+      const opts = parseMcpSetupArgs(args);
+      log(JSON.stringify(await setup({ envVar: opts.envVar, tenant: opts.tenant, label: opts.label, expiryDays: opts.expiryDays, force: opts.force })));
+    } catch (error) {
+      const code = (error instanceof McpKeyError || error instanceof McpKeyStoreError) ? error.code : "mint_failed";
+      const extra = {};
+      if (error instanceof McpKeyStoreError) {
+        extra.detail = error.message;
+        // An un-rolled-back mint left a live orphan — name it so the operator
+        // can `botbuddy mcp revoke <id>` rather than pile up unusable keys.
+        if (!error.rolledBack && error.agentId) extra.orphan_agent_id = error.agentId;
+      }
+      log(JSON.stringify({ schema_version: 1, outcome: "error", error: code, ...extra, recovery: mcpRecovery(code) }));
+      setExitCode(3);
+    }
+    return;
+  }
+
+  if (sub === "revoke") {
+    // The server binds revocation to the pinned tenant (BOT-1607 Codex P1), so a
+    // multi-tenant owner must pin the tenant the key was minted for. --env names
+    // the local Keychain slot to clear after a successful revoke (Codex P2). Parse
+    // flag-aware so a flag value is not mistaken for an extra positional.
+    let agentId = null, tenant = null, envVar = null, extraPositionals = 0;
+    try {
+      for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--tenant" || arg.startsWith("--tenant=")) {
+          tenant = arg.startsWith("--tenant=") ? arg.slice("--tenant=".length) : args[++i];
+          if (typeof tenant !== "string" || !TENANT_SLUG_RE.test(tenant)) die("error: --tenant must be a lowercase slug");
+          continue;
+        }
+        if (arg === "--env" || arg.startsWith("--env=")) {
+          const raw = arg.startsWith("--env=") ? arg.slice("--env=".length) : args[++i];
+          if (raw === undefined || raw === "") throw new McpKeyError("invalid_env_var", { detail: "--env requires a variable name, e.g. BOTBUDDY_MCP_KEY_WORK" });
+          envVar = resolveEnvVarName(raw);
+          continue;
+        }
+        if (arg.startsWith("-")) die(`Unknown mcp revoke option: ${arg}. Run ${cyan("botbuddy mcp --help")}.`);
+        if (agentId == null) agentId = arg; else extraPositionals++;
+      }
+    } catch (error) {
+      const code = error instanceof McpKeyError ? error.code : "revoke_failed";
+      log(JSON.stringify({ schema_version: 1, outcome: "error", error: code, recovery: mcpRecovery(code) }));
+      setExitCode(3);
+      return;
+    }
+    if (!agentId || extraPositionals > 0) die("Usage: botbuddy mcp revoke <agent_id> [--tenant <slug>] [--env <NAME>]");
+    try {
+      log(JSON.stringify(await revoke({ agentId, tenant, envVar })));
+    } catch (error) {
+      const code = error instanceof McpKeyError ? error.code : "revoke_failed";
+      log(JSON.stringify({ schema_version: 1, outcome: "error", error: code, recovery: mcpRecovery(code) }));
+      setExitCode(3);
+    }
+    return;
+  }
+
+  if (sub === "status") {
+    let requested;
+    try {
+      requested = parseMcpStatusEnv(args);
+    } catch (error) {
+      const code = error instanceof McpKeyError ? error.code : "invalid_env_var";
+      log(JSON.stringify({ schema_version: 1, outcome: "error", error: code, recovery: mcpRecovery(code) }));
+      setExitCode(3);
+      return;
+    }
+    const resolved = resolveConfigKey(env, { envVar: requested.envVar, explicit: requested.explicit });
+    if (!resolved) {
+      log(JSON.stringify({ schema_version: 1, outcome: "status", configured: false, env_var: requested.envVar }));
+      return;
+    }
+    log(JSON.stringify({
+      schema_version: 1,
+      outcome: "status",
+      configured: true,
+      env_var: resolved.envVar,
+      deprecated: resolved.deprecated,
+      ...(resolved.notice ? { notice: resolved.notice } : {}),
     }));
-    process.exitCode = 3;
+    return;
   }
+
+  die(`Unknown mcp subcommand: ${sub}. Run ${cyan("botbuddy mcp --help")}.`);
 }
 
 function cmdLock(args) {

package/src/credential-kinds.mjs

@@ -17,6 +17,9 @@ export const CREDENTIAL_PREFIXES = [
   { prefix: "mcp_at_", kind: "oauth", label: "OAuth owner token" },
   { prefix: "bb_pat_", kind: "pat", label: "personal access token" },
   { prefix: "bb_cli_", kind: "cli", label: "client key" },
+  // BOT-1607: the tier-2 MCP config key a .mcp.json presents (independently
+  // revocable; minted by `botbuddy mcp`). Unambiguous by prefix.
+  { prefix: "bb_mcp_", kind: "mcp", label: "MCP key" },
   // BOT-1573/1582 transition: bb_agent_ is now BOTH the per-session agent token
   // (BOT-1582 renamed it from bb_sess_) AND the older shared service carrier, so
   // the prefix ALONE can no longer tell them apart. Classification is display

package/src/discovery.mjs

@@ -30,10 +30,23 @@ export function parseCallArgs(argv) {
 
   let args = {};
   let sawJson = false;
+  // BOT-1571: `--pin <slug>` pins the CONNECTION tenant (the ?tenant= query),
+  // which a user token needs on every request. Deliberately not `--tenant`:
+  // several tools take a `tenant` / `tenant_id` argument of their own.
+  let pin = null;
 
   for (let i = 0; i < rest.length; i++) {
     const token = rest[i];
 
+    if (token === "--pin") {
+      const raw = rest[++i];
+      if (raw === undefined || raw.startsWith("--") || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(raw)) {
+        throw new CallUsageError("--pin requires a lowercase tenant slug, e.g. --pin supply-guard.");
+      }
+      pin = raw;
+      continue;
+    }
+
     if (token === "--json" || token === "-j") {
       const raw = rest[++i];
       if (raw === undefined) throw new CallUsageError("--json requires a JSON object argument.");
@@ -73,7 +86,7 @@ export function parseCallArgs(argv) {
     );
   }
 
-  return { tool, args, usedJson: sawJson };
+  return { tool, args, usedJson: sawJson, pin };
 }
 
 /**