@botbuddy/cli 1.25.0 → 1.26.0

package/package.json

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

package/src/agent-credential-store.mjs

@@ -1,15 +1,8 @@
-import { chmod, link, mkdir, readFile, rename, stat, unlink, utimes, writeFile } from "node:fs/promises";
-import { homedir, userInfo } from "node:os";
+import { userInfo } from "node:os";
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
-import { dirname, join } from "node:path";
-import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 
-const STORE_SCHEMA_VERSION = 1;
-const LOCK_RETRY_MS = 10;
-const LOCK_MAX_ATTEMPTS = 100;
-const STALE_LOCK_MS = 30_000;
 const execFileAsync = promisify(execFile);
 
 // BOT-1520: is the macOS Keychain backend usable on this host? The CLI stores
@@ -24,20 +17,17 @@ export function keychainAvailable(platform = process.platform, exists = existsSy
   return platform === "darwin" && exists("/usr/bin/security");
 }
 
-export function ensureProfileCredentialBackend({ platform = process.platform, exists = existsSync } = {}) {
-  if (!keychainAvailable(platform, exists)) {
-    throw new Error("profile setup requires the macOS Keychain credential backend");
-  }
-}
-
-export function profileCredentialEnvironment(profile) {
-  return profile === "botbuddy-dev" ? "BOTBUDDY_BB_AGENT_KEY"
-    : profile === "supplyguard-dev" ? "BOTBUDDY_SG_AGENT_KEY" : null;
-}
+// BOT-1607 / BOT-1608: the canonical env/Keychain var a `.mcp.json` references.
+// The `.botbuddy-agent.json` binding's `mcp_env` defaults to this; `botbuddy mcp`
+// mints into it (or an `--env <NAME>` override). Defined here — the one module
+// both mcp-key.mjs and wait-profile.mjs already import — so neither has to import
+// the other (an api.mjs ↔ wait-profile.mjs ↔ mcp-key.mjs cycle).
+export const DEFAULT_MCP_ENV_VAR = "BOTBUDDY_MCP_KEY";
 
-function keychainService(profile) {
-  return profileCredentialEnvironment(profile);
-}
+// The pre-1607 var `profile setup` planted the reused bb_agent_ session token in.
+// A `.mcp.json` still referencing it keeps authenticating for one release; the
+// CLI recognises it as a DEPRECATED alias and tells the operator to migrate.
+export const LEGACY_MCP_ENV_VAR = "BOTBUDDY_BB_AGENT_KEY";
 
 // A keychain/credential-store write failed AFTER OAuth + registration already
 // succeeded. It carries its own code so the CLI never mislabels a storage
@@ -212,163 +202,3 @@ export async function deleteKeychainSecret(service, { execFileImpl = execFileAsy
     return false;
   }
 }
-
-export async function writeKeychain(profile, token, options = {}) {
-  const service = keychainService(profile);
-  if (!service) throw new ProfileCredentialStoreError(`unknown profile keychain service for "${profile}"`);
-  return writeKeychainSecret(service, token, options);
-}
-
-async function readKeychain(profile) {
-  // Honor the keychain escape hatch (BOTBUDDY_NO_KEYCHAIN / non-darwin) so the
-  // per-profile environment key is the sole credential source there.
-  if (!keychainAvailable()) return null;
-  return readKeychainSecret(keychainService(profile));
-}
-
-function profileCredentialStorePath(home = homedir()) {
-  return join(home, ".botbuddy", "agent-profiles.json");
-}
-
-async function readStore({ home = homedir() } = {}) {
-  try {
-    const raw = await readFile(profileCredentialStorePath(home), "utf8");
-    const parsed = JSON.parse(raw);
-    if (parsed?.schema_version !== STORE_SCHEMA_VERSION || !parsed.profiles || typeof parsed.profiles !== "object") {
-      return { schema_version: STORE_SCHEMA_VERSION, profiles: {} };
-    }
-    return parsed;
-  } catch (error) {
-    if (error?.code === "ENOENT") return { schema_version: STORE_SCHEMA_VERSION, profiles: {} };
-    throw error;
-  }
-}
-
-function validIdentityEntry(entry) {
-  return entry && typeof entry === "object" && typeof entry.name === "string";
-}
-
-async function withStoreLock(path, operation) {
-  const lockPath = `${path}.lock`;
-  for (let attempt = 0; attempt < LOCK_MAX_ATTEMPTS; attempt++) {
-    const ownerPath = `${lockPath}.${process.pid}.${randomUUID()}`;
-    try {
-      await writeFile(ownerPath, JSON.stringify({ pid: process.pid, owner_path: ownerPath }), { flag: "wx", mode: 0o600 });
-      await link(ownerPath, lockPath);
-      const ownerStat = await stat(ownerPath);
-      const ownsLock = async () => {
-        try {
-          const current = await stat(lockPath);
-          return current.dev === ownerStat.dev && current.ino === ownerStat.ino;
-        } catch (error) {
-          if (error?.code === "ENOENT") return false;
-          throw error;
-        }
-      };
-      const refresh = setInterval(() => {
-        const now = new Date();
-        void ownsLock().then((owned) => owned && utimes(lockPath, now, now)).catch(() => {});
-      }, Math.floor(STALE_LOCK_MS / 3));
-      try {
-        return await operation();
-      } finally {
-        clearInterval(refresh);
-        if (await ownsLock()) await unlink(lockPath).catch(() => {});
-        await unlink(ownerPath).catch(() => {});
-      }
-    } catch (error) {
-      await unlink(ownerPath).catch(() => {});
-      if (error?.code !== "EEXIST") throw error;
-      try {
-        const lockStat = await stat(lockPath);
-        if (Date.now() - lockStat.mtimeMs > STALE_LOCK_MS) {
-          const lock = JSON.parse(await readFile(lockPath, "utf8"));
-          let ownerAlive = false;
-          try { process.kill(lock.pid, 0); ownerAlive = true; } catch (ownerError) { ownerAlive = ownerError?.code === "EPERM"; }
-          if (!ownerAlive) {
-            await unlink(lockPath);
-            if (typeof lock.owner_path === "string") await unlink(lock.owner_path).catch(() => {});
-          }
-        }
-      } catch (lockError) {
-        if (lockError?.code !== "ENOENT") throw lockError;
-      }
-      await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_MS));
-    }
-  }
-  throw new Error("profile credential store is busy; retry profile setup");
-}
-
-export async function readProfileIdentity(profile, options = {}) {
-  const store = await readStore(options);
-  const entry = store.profiles[profile];
-  if (!validIdentityEntry(entry) || typeof entry.tenant !== "string" || typeof entry.agent_id !== "string") return null;
-  return { agentId: entry.agent_id, tenant: entry.tenant, name: entry.name };
-}
-
-export async function readProfileRetryIdentity(profile, options = {}) {
-  const store = await readStore(options);
-  const entry = store.profiles[profile];
-  if (!validIdentityEntry(entry)) return null;
-  const agentId = typeof entry.agent_id === "string" ? entry.agent_id : entry.pending_agent_id;
-  return typeof agentId === "string" ? { agentId, name: entry.name } : null;
-}
-
-export async function readProfileCredential(profile, options = {}) {
-  return (options.keychainRead ?? readKeychain)(profile);
-}
-
-async function writeProfileMetadata(profile, entry, {
-  home = homedir(),
-  onlyIfNoAttestedIdentity = false,
-  afterWrite = null,
-} = {}) {
-  const path = profileCredentialStorePath(home);
-  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-  await withStoreLock(path, async () => {
-    const store = await readStore({ home });
-    const current = store.profiles[profile];
-    if (onlyIfNoAttestedIdentity && validIdentityEntry(current) && typeof current.tenant === "string" && typeof current.agent_id === "string") {
-      return false;
-    }
-    const next = {
-      schema_version: STORE_SCHEMA_VERSION,
-      profiles: { ...store.profiles, [profile]: entry },
-    };
-    const temporaryPath = `${path}.${randomUUID()}.tmp`;
-    await writeFile(temporaryPath, JSON.stringify(next), { mode: 0o600 });
-    await chmod(temporaryPath, 0o600);
-    await rename(temporaryPath, path);
-    await chmod(path, 0o600);
-    await afterWrite?.();
-    return true;
-  });
-}
-
-export async function recordProfileRetryIdentity({ profile, agentId, name }, options = {}) {
-  if (![profile, agentId, name].every((value) => typeof value === "string" && value.length > 0)) {
-    throw new Error("profile retry identity requires profile, agentId, and name");
-  }
-  // This entry is explicitly not tenant-attested and contains no credential. It
-  // may only be used to reconnect with the profile's fixed tenant on retry.
-  await writeProfileMetadata(profile, { pending_agent_id: agentId, name }, {
-    ...options,
-    onlyIfNoAttestedIdentity: true,
-  });
-}
-
-export async function installProfileCredential({ profile, tenant, agentId, name, token }, { home = homedir(), keychainWrite = writeKeychain } = {}) {
-  if (![profile, tenant, agentId, name, token].every((value) => typeof value === "string" && value.length > 0)) {
-    throw new Error("profile credential store requires profile, tenant, agentId, name, and token");
-  }
-  // Keep non-secret identity metadata even if Keychain is momentarily locked.
-  // The next setup call reconnects this same server agent instead of minting a
-  // random orphan; credentials are never written to this file.
-  await writeProfileMetadata(profile, { tenant, agent_id: agentId, name }, {
-    home,
-    // Keep this Keychain operation in the same lock as the metadata write. A
-    // later setup cannot leave metadata from one agent beside another agent's
-    // credential, while a failed write still leaves resumable metadata.
-    afterWrite: () => keychainWrite(profile, token),
-  });
-}

package/src/api.mjs

@@ -1,6 +1,6 @@
 import { getConfig, SERVER_URL } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
-import { findProfileName, getAgentProfile } from "./wait-profile.mjs";
+import { readAgentBinding } from "./wait-profile.mjs";
 import { die, cyan, dim, yellow, prettyJson } from "./utils.mjs";
 
 // Same slug shape the server accepts on `?tenant=`.
@@ -10,7 +10,7 @@ const TENANT_PIN_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
 // server refuses unpinned (MCP_TENANT_PIN_REQUIRED). Generic commands
 // (`botbuddy call`, resources) therefore derive a default pin:
 //   1. BOTBUDDY_TENANT (explicit; malformed → usage error, never sent),
-//   2. the repo's .botbuddy-agent.json profile tenant (walks up from cwd),
+//   2. the repo's .botbuddy-agent.json tenant (walks up from cwd),
 //   3. the token's sole reachable tenant,
 //   4. none — the server's error names the fix.
 // A sealed (tenant-mode) or pre-1571 token gets NO derived pin: the server
@@ -21,8 +21,7 @@ export async function resolveDefaultTenantPin({
   getConfig: getCfg = getConfig,
   env = process.env,
   cwd = process.cwd(),
-  findProfile = findProfileName,
-  profileFor = getAgentProfile,
+  readBinding = readAgentBinding,
 } = {}) {
   const explicit = typeof env.BOTBUDDY_TENANT === "string" ? env.BOTBUDDY_TENANT.trim() : "";
   if (explicit) {
@@ -31,10 +30,11 @@ export async function resolveDefaultTenantPin({
   }
   const cfg = getCfg() ?? {};
   if (cfg.token_tenant_mode !== "user") return null;
-  let profileName = null;
-  try { profileName = await findProfile(cwd); } catch { profileName = null; }
-  const profileTenant = profileName ? profileFor(profileName)?.tenant ?? null : null;
-  if (profileTenant) return profileTenant;
+  // A malformed / retired-shape .botbuddy-agent.json never breaks a generic call —
+  // fall through to the sole-tenant rung rather than throwing here.
+  let bindingTenant = null;
+  try { bindingTenant = (await readBinding(cwd))?.tenant ?? null; } catch { bindingTenant = null; }
+  if (bindingTenant) return bindingTenant;
   const tenants = Array.isArray(cfg.token_tenants) ? cfg.token_tenants.filter((t) => typeof t === "string" && t) : [];
   return tenants.length === 1 ? tenants[0] : null;
 }

package/src/auth.mjs

@@ -187,7 +187,7 @@ export async function doLogin(options = {}, deps = {}) {
       }.`,
     );
     if (tenantMode === "user") {
-      log(`  Token scope: ${cyan("user")} — works for every tenant you belong to${tenants.length ? ` (${tenants.join(", ")})` : ""}; each ${cyan("botbuddy profile setup")} pins its own.`);
+      log(`  Token scope: ${cyan("user")} — works for every tenant you belong to${tenants.length ? ` (${tenants.join(", ")})` : ""}; each ${cyan("botbuddy mcp setup --tenant <slug>")} mints a key pinned to its own.`);
     } else if (tenantId) {
       log(`  Token scope: ${cyan("tenant")} — sealed to ${cyan(tenantId)}. Run ${cyan("botbuddy login")} without ${dim("--tenant")} for a token that reaches all your tenants.`);
     }

package/src/cli-credentials.mjs

@@ -23,7 +23,7 @@ import {
   readKeychainSecret,
   deleteKeychainSecret,
 } from "./agent-credential-store.mjs";
-import { resolveAgentProfile } from "./wait-profile.mjs";
+import { resolveAgentBinding } from "./wait-profile.mjs";
 
 // BOT-1574: the per-machine CLIENT KEY. `botbuddy login` mints a user-mode OAuth
 // token (BOT-1571) — tenant-agnostic, pins one tenant per request against the
@@ -267,15 +267,20 @@ export async function clearOwnerToken({
   }
 }
 
-// Resolve the tenant-bound agent key from the profile Keychain store (or the
-// per-profile environment key), without throwing when no profile is configured.
-// This is the sole source of the agent credential now that `register` is gone.
+// Resolve the agent-context credential from the worktree binding — the
+// `.botbuddy-agent.json` mcp_env var (env or Keychain) — without throwing when no
+// binding is configured. This is the fallback the owner OAuth token defers to for
+// tool-call auth now that `register` and `profile setup` are both gone.
 export async function resolveAgentKey(options = {}) {
   try {
-    const { token } = await resolveAgentProfile(options);
+    const { token } = await resolveAgentBinding(options);
     return token || null;
   } catch (error) {
-    if (error?.code === "profile_required" || error?.code === "unknown_profile") return null;
+    // A missing / malformed / retired-shape binding is not authenticated — let the
+    // caller fall through to its "not authenticated" path rather than throwing.
+    if (["agent_binding_required", "invalid_binding", "binding_migration_required"].includes(error?.code)) {
+      return null;
+    }
     throw error;
   }
 }

package/src/codex-bridge.mjs

@@ -66,14 +66,14 @@ function isAddressInUseError(text) {
 
 export async function runBridge(args) {
   const cfg = getConfig(); // non-secret metadata only (agent_name)
-  // BOT-1520: authenticate from the Keychain — the profile agent key
-  // (`botbuddy profile setup`) or the owner OAuth token (`botbuddy login`).
+  // BOT-1520: authenticate from the Keychain — the MCP key
+  // (`botbuddy mcp setup`, BOT-1608) or the owner OAuth token (`botbuddy login`).
   // Resolve ONCE here for the life of the bridge and cache it, so the relay
   // helpers don't shell out to `security` on every request.
   const agentKey = await resolveAgentKey();
   const owner = agentKey ? null : await resolveOwnerToken({ getConfig });
   if (!agentKey && !owner) {
-    die(`Not authenticated. Run: ${cyan("botbuddy start")} or ${cyan("botbuddy login")} (agents: ${cyan("botbuddy profile setup <profile>")}).`);
+    die(`Not authenticated. Run: ${cyan("botbuddy start")} or ${cyan("botbuddy login")} (agents: ${cyan("botbuddy mcp setup")}).`);
   }
   bridgeAuth = { agentKey, owner };
 

package/src/commands.mjs

@@ -14,8 +14,8 @@ import { cmdTest } from "./test-lane.mjs";
 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 { readAgentBinding } from "./wait-profile.mjs";
 import { runPw } from "./pw/run.mjs";
 import { maybeWarnStale, cmdUpdate } from "./update-check.mjs";
 
@@ -56,8 +56,6 @@ export async function run(argv, {
     case "test": return cmdTest(args);
     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");
@@ -102,8 +100,6 @@ ${bold("AUTH")}
                              Authenticate via OAuth (opens browser + localhost callback)
   logout                     Remove saved credentials
   status                     Show current auth status (local metadata + server check)
-  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>]
@@ -111,6 +107,7 @@ ${bold("MCP CONFIG KEY")}
                              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)
+  mcp env                    Print the shell loader for the MCP key ($BOTBUDDY_MCP_KEY)
 
 ${bold("TOOLS")}
   help --tools               List every BotBuddy tool
@@ -301,8 +298,9 @@ ${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).
+  exchanges it for a per-session agent token. No per-tenant credential is needed
+  for normal use — mint a ${bold("bb_mcp_")} key per tenant (${cyan("botbuddy mcp setup")}) only
+  when a repo binds a distinct ${dim("mcp_env")}.
   ${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.
 
@@ -353,7 +351,8 @@ ${bold("NOTES")}
 
 ${bold("RECOVERY")}
   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>")}.`);
+  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.`);
 }
 
 async function cmdStart(args) {
@@ -556,143 +555,14 @@ async function cmdLogout() {
   console.log(`${green("✓")} Logged out. Credentials removed.`);
 }
 
-async function cmdAgentAuth(args) {
-  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
-    console.log(`Usage: botbuddy auth <login|status|logout> [--profile <name>] [--token <key>]
-
-  auth login    Store a tenant-bound agent credential in the OS keyring. On macOS,
-                it imports the existing launchd credential once when no --token or
-                profile-specific environment key is supplied.
-  auth status   Show whether the profile has a stored key (never prints it).
-  auth logout   Remove the profile's stored key.`);
-    return;
-  }
-  let options;
-  try {
-    options = parseAgentAuthArgs(args);
-  } catch (error) {
-    die(error.message);
-  }
-  const profile = options.profile || await findProfileName(process.cwd());
-  if (!profile || !getProfileDefinition(profile)) {
-    die("No supported BotBuddy agent profile found. Add .botbuddy-agent.json or pass --profile <name>.");
-  }
-  if (options.action === "login") {
-    const token = await resolveLoginToken({ profile, explicitToken: options.token });
-    const result = await loginAgentCredential({ profile, token });
-    console.log(`${green("✓")} Stored ${result.profile} (${result.tenant}) agent credential in the OS keyring.`);
-    return;
-  }
-  if (options.action === "status") {
-    const result = await getAgentAuthStatus({ profile });
-    console.log(result.authenticated
-      ? `${green("✓")} ${result.profile} (${result.tenant}) machine credential is stored in the OS keyring.`
-      : `${red("✗")} ${result.profile} (${result.tenant}) has no stored machine credential.`);
-    return;
-  }
-  const result = await logoutAgentCredential({ profile });
-  console.log(`${green("✓")} ${result.profile} (${result.tenant}) machine credential ${result.removed ? "removed" : "was not present"}.`);
-}
-
 function cmdHeartbeat(args) {
   return args[0] ? callTool("heartbeat", { current_task: args[0] }) : callTool("heartbeat");
 }
 
-// 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> [--unattended]
-
-  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 {
-      log(profileShellRefresh(args[1]));
-      return;
-    } catch {
-      die("Usage: botbuddy profile 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]");
-  }
-  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: "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]
+  log(`Usage: botbuddy mcp <setup|revoke|status|env> [options]
 
   setup [--env <NAME>] [--tenant <slug>] [--label <label>] [--expiry-days <n>] [--force]
                     Mint a bb_mcp_ MCP config key (authenticated by your
@@ -711,6 +581,10 @@ function mcpHelp(log) {
                     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.
+  env [--env <NAME>]
+                    Print the shell loader that reads the key from the Keychain
+                    into ${dim("$BOTBUDDY_MCP_KEY")}: eval "$(botbuddy mcp env)" in a shell,
+                    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.`);
@@ -821,11 +695,34 @@ export async function cmdMcp(args, {
   revoke = revokeMcpKey,
   resolveConfigKey = resolveMcpConfigKey,
   env = process.env,
+  cwd = process.cwd(),
+  readBinding = readAgentBinding,
 } = {}) {
   if (args[0] === "--help" || args[0] === "-h") return mcpHelp(log);
   const sub = args.find((a) => !a.startsWith("-"));
   if (!sub) return mcpHelp(log);
 
+  // BOT-1608 Codex P2: `mcp status`/`mcp env` with no explicit --env must report
+  // and export the var the committed .botbuddy-agent.json actually binds (e.g.
+  // BOTBUDDY_MCP_KEY_SG), not the hard-coded default — otherwise the MCP client's
+  // configured slot is left unset and auth fails unless --env is redundantly
+  // passed. An explicit --env still wins; a malformed binding falls back to the
+  // default var (status/env are diagnostics, not the fail-closed wait path).
+  const resolveRequestedEnv = async (requested) => {
+    if (requested.explicit) return requested;
+    try {
+      const binding = await readBinding(cwd);
+      // A binding that names a NON-default var is an explicit selection of that
+      // var (declared in the file rather than on the flag) — so status inspects
+      // exactly it. A binding naming the default var stays non-explicit so the
+      // deprecated-alias fallback still applies.
+      if (binding?.mcpEnv && binding.mcpEnv !== DEFAULT_MCP_ENV_VAR) {
+        return { envVar: binding.mcpEnv, explicit: true };
+      }
+    } catch { /* malformed binding: keep the default var for diagnostics */ }
+    return requested;
+  };
+
   if (sub === "setup") {
     try {
       // Parse inside the try so a bad --env (missing value / reserved name) becomes
@@ -890,7 +787,7 @@ export async function cmdMcp(args, {
   if (sub === "status") {
     let requested;
     try {
-      requested = parseMcpStatusEnv(args);
+      requested = await resolveRequestedEnv(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) }));
@@ -913,6 +810,25 @@ export async function cmdMcp(args, {
     return;
   }
 
+  if (sub === "env") {
+    // BOT-1608 (AC4): the "export the key" job folded out of the retired
+    // `profile env`. Prints the shell loader that reads the MCP key from the
+    // Keychain into $envVar so `eval "$(botbuddy mcp env)"` (and the desktop
+    // LaunchAgent recipe) load the credential the MCP client / bb-wait consume.
+    let requested;
+    try {
+      requested = await resolveRequestedEnv(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 envVar = requested.envVar;
+    log(`export ${envVar}="$(security find-generic-password -w -a "$USER" -s ${envVar})"`);
+    return;
+  }
+
   die(`Unknown mcp subcommand: ${sub}. Run ${cyan("botbuddy mcp --help")}.`);
 }
 

package/src/config.mjs

@@ -65,7 +65,7 @@ export async function loadConfig({ platform = process.platform, warn = (m) => co
       warn(
         migrated
           ? "✓ Migrated the owner token from ~/.botbuddy/config.json into the macOS Keychain."
-          : "⚠ Removed a legacy plaintext credential from ~/.botbuddy/config.json. Run `botbuddy login` (and `botbuddy profile setup <profile>` for agents) to re-establish credentials in the Keychain.",
+          : "⚠ Removed a legacy plaintext credential from ~/.botbuddy/config.json. Run `botbuddy login` (and `botbuddy mcp setup` for agents) to re-establish credentials in the Keychain.",
       );
     }
   }