@botbuddy/cli 1.22.0 → 1.24.0

package/src/mcp-key.mjs

@@ -0,0 +1,385 @@
+// BOT-1607 — `botbuddy mcp`: mint / revoke the tier-2 `bb_mcp_` MCP config key.
+//
+// A `.mcp.json` should present its OWN independently-revocable key, not the
+// reused `bb_agent_` session token `profile setup` planted in
+// BOTBUDDY_BB_AGENT_KEY. `botbuddy mcp setup` mints a `bb_mcp_` key —
+// authenticated by the tier-1 owner/client credential (resolveCallAuth: the
+// owner OAuth/client key from `botbuddy login`) — stores it in the Keychain
+// under a default-or-`--env` service, and prints the `.mcp.json` /
+// `.codex/config.toml` snippets that reference that var. `botbuddy mcp revoke`
+// invalidates ONLY that key, so a leaked config credential rotates without a
+// re-login or agent disruption.
+//
+// The mint/revoke calls are the server tools mint_mcp_key / revoke_mcp_key
+// (owner/client-gated). This module mirrors profile-bootstrap.mjs's dependency
+// injection so the whole flow is unit-testable with an injected call / auth /
+// keychain.
+
+import { keychainAvailable, readKeychainSecret, writeKeychainSecret } from "./agent-credential-store.mjs";
+import { callToolJson, resolveCallAuth } from "./api.mjs";
+import { SERVER_URL } from "./config.mjs";
+
+// The default env/Keychain var a `.mcp.json` references (BOT-1108 canonical set,
+// aligned with src/components/credentials/SetupSnippet.tsx). `--env <NAME>`
+// overrides it.
+export const DEFAULT_MCP_ENV_VAR = "BOTBUDDY_MCP_KEY";
+
+// BOT-1607 AC5: the pre-1607 var `profile setup` wrote the reused bb_agent_ session token into.
+// A `.mcp.json` still referencing it keeps authenticating for one release (the
+// server authenticates by hash regardless of which env var carried the key); 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 valid shell env-var / Keychain service name.
+const ENV_VAR_RE = /^[A-Z][A-Z0-9_]*$/;
+
+// BOT-1607 (Codex P2): --env doubles as the macOS Keychain service name, so a
+// name owned by ANOTHER BotBuddy credential kind would silently overwrite that
+// credential's Keychain slot (e.g. BOTBUDDY_CLIENT_KEY is the bb_cli_ token
+// `botbuddy login` installs). Refuse those; the MCP default var and its legacy
+// alias are fine, as is any distinct custom name (BOTBUDDY_MCP_KEY_WORK, …).
+const RESERVED_ENV_VARS = new Set([
+  "BOTBUDDY_CLIENT_KEY",     // bb_cli_ — botbuddy login client key
+  "BOTBUDDY_AGENT_KEY",      // bb_agent_ — per-session agent token
+  "BOTBUDDY_SVC_KEY",        // bb_svc_ — legacy carrier
+  "BOTBUDDY_CI_KEY",         // bb_ci_ — CI key
+  "BOTBUDDY_TOKEN",          // PAT / OAuth owner token
+  "BOTBUDDY_TEST_RUN_TOKEN", // publishable test-run token
+  "BOTBUDDY_SG_AGENT_KEY",   // Supply Guard profile Keychain slot (profileCredentialEnvironment) — never an MCP var
+]);
+
+// BOTBUDDY_BB_AGENT_KEY is dual-purpose: the deprecated MCP READ alias AND the
+// botbuddy profile Keychain slot (agent-credential-store profileCredentialEnvironment).
+// A `mcp status` (read-only) may name it, but `mcp setup`/`revoke` must NOT write
+// or delete it — that would clobber/destroy the profile client credential (Codex P2).
+// It is not in RESERVED_ENV_VARS so status can still resolve the legacy alias.
+
+export class McpKeyError extends Error {
+  constructor(code, { detail = null } = {}) {
+    super(detail ? `${code}: ${detail}` : code);
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+// A Keychain write failed AFTER minting succeeded. Distinct so the CLI never
+// mislabels a storage failure as an auth failure (AC2: a read-back mismatch /
+// locked keychain must fail loudly, never a silent success).
+export class McpKeyStoreError extends Error {
+  constructor(message, { cause, agentId = null, rolledBack = false } = {}) {
+    super(message);
+    this.name = "McpKeyStoreError";
+    this.code = "mcp_key_store_failed";
+    // BOT-1607 (Codex P2): the minted key's id + whether the best-effort rollback
+    // revoked it, so the receipt can point the operator at a manual revoke when
+    // an orphan key survives.
+    this.agentId = agentId;
+    this.rolledBack = rolledBack;
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+// A structured MCP error code on a tool-result body (`data.code`) or, for a
+// 401/403, on the auth receipt (`code`) callToolJson lifts out (BOT-1561).
+function structuredCode(response) {
+  if (typeof response?.data?.code === "string") return response.data.code;
+  if (typeof response?.code === "string") return response.code;
+  return null;
+}
+
+/** Validate an explicit `--env <NAME>`; the default needs no validation. */
+export function resolveEnvVarName(explicit, { forWrite = true } = {}) {
+  if (explicit == null) return DEFAULT_MCP_ENV_VAR;
+  const name = String(explicit).trim();
+  if (!ENV_VAR_RE.test(name)) {
+    throw new McpKeyError("invalid_env_var", { detail: `${explicit} (use UPPER_SNAKE_CASE)` });
+  }
+  if (RESERVED_ENV_VARS.has(name)) {
+    throw new McpKeyError("reserved_env_var", { detail: `${name} is owned by another BotBuddy credential; choose a distinct name like BOTBUDDY_MCP_KEY_WORK` });
+  }
+  // Only a WRITE (setup) or DELETE (revoke) into the botbuddy profile slot is
+  // dangerous; a read-only status may still resolve the deprecated MCP alias.
+  if (forWrite && name === LEGACY_MCP_ENV_VAR) {
+    throw new McpKeyError("reserved_env_var", { detail: `${name} is the botbuddy profile Keychain slot — mint/revoke into a dedicated MCP var like ${DEFAULT_MCP_ENV_VAR}` });
+  }
+  return name;
+}
+
+/**
+ * The consumer snippets for the MCP key — the SAME shape the web UI renders
+ * (src/components/credentials/SetupSnippet.tsx): a `.mcp.json` block and a
+ * `.codex/config.toml` block that reference `$envVar` (never the raw secret), and
+ * the macOS Keychain store-once command. Kept in sync by tests on both sides.
+ */
+export function mcpKeySnippets(envVar, { mcpUrl = SERVER_URL, loaderOnly = false } = {}) {
+  const mcpJson = JSON.stringify(
+    {
+      mcpServers: {
+        botbuddy: {
+          type: "http",
+          url: mcpUrl,
+          headers: { Authorization: `Bearer \${${envVar}}` },
+        },
+      },
+    },
+    null,
+    2,
+  );
+  // Codex does NOT interpolate ${VAR} inside a `headers` table (unlike Claude's
+  // .mcp.json above) — a literal `Bearer ${BOTBUDDY_MCP_KEY}` would be sent. Its
+  // supported env-backed auth is `bearer_token_env_var = "<NAME>"` (the same
+  // setting .codex/config.toml uses for the botbuddy server), so emit that.
+  const codexToml = `[mcp_servers.botbuddy]\ntype = "http"\nurl = "${mcpUrl}"\nbearer_token_env_var = "${envVar}"`;
+  // Storing the secret and EXPORTING it are two separate steps (README.md /
+  // AGENTS.md). Both client configs above read $envVar at launch, so the snippet
+  // must emit the Keychain-to-environment loader too — otherwise the operator
+  // stores the key, then launches Claude/Codex with $envVar unset (Codex P1).
+  // Mirrors the web keychain tab (SetupSnippet.tsx). The service name IS the var.
+  const load = `export ${envVar}="$(security find-generic-password -w -a "$USER" -s ${envVar})"`;
+  // loaderOnly (Codex P2): after a successful `mcp setup`, the key is ALREADY in
+  // the Keychain and its plaintext is intentionally not echoed — so the receipt
+  // must NOT show a `security add-generic-password -w` store prompt (the user has
+  // nothing to paste and could overwrite the valid key with garbage). Emit only
+  // the loader. The store+load pair is for the minted_no_keychain path, where the
+  // raw key is returned for the operator to place themselves.
+  const keychain = loaderOnly
+    ? `# Already stored in your Keychain by \`botbuddy mcp setup\` — load it into each shell:\n${load}`
+    : `# 1) Store once — prompted; nothing hits shell history\n`
+      + `security add-generic-password -U -a "$USER" -s ${envVar} -T /usr/bin/security -w\n\n`
+      + `# 2) Every subsequent shell (and the MCP client it launches) reads it back\n${load}`;
+  return { mcp_json: mcpJson, codex_toml: codexToml, keychain };
+}
+
+/**
+ * BOT-1607 AC5: resolve the MCP config key from the environment. Prefers
+ * BOTBUDDY_MCP_KEY; falls back to the deprecated BOTBUDDY_BB_AGENT_KEY alias with
+ * a migration notice. Never logs the key itself — only which var carries it.
+ */
+export function resolveMcpConfigKey(env = process.env, { envVar = null, explicit = false } = {}) {
+  const legacyNotice =
+    `${LEGACY_MCP_ENV_VAR} is a deprecated alias for ${DEFAULT_MCP_ENV_VAR} and will stop being read in a future release. `
+    + `Run \`botbuddy mcp setup\` to mint a dedicated ${DEFAULT_MCP_ENV_VAR} and update your .mcp.json.`;
+
+  // BOT-1607 (Codex P2): when `--env <NAME>` is EXPLICITLY supplied — a canonical
+  // name (default OR legacy alias) or a custom one — inspect exactly that
+  // variable, never the default-first fallback. Otherwise `status --env
+  // BOTBUDDY_BB_AGENT_KEY` (unset) could report BOTBUDDY_MCP_KEY, and vice versa.
+  if (explicit && envVar) {
+    const val = env?.[envVar];
+    if (typeof val === "string" && val) {
+      const deprecated = envVar === LEGACY_MCP_ENV_VAR;
+      return { envVar, key: val, deprecated, ...(deprecated ? { notice: legacyNotice } : {}) };
+    }
+    return null;
+  }
+
+  // No explicit selector: default → legacy-alias precedence.
+  const primary = env?.[DEFAULT_MCP_ENV_VAR];
+  if (typeof primary === "string" && primary) {
+    return { envVar: DEFAULT_MCP_ENV_VAR, key: primary, deprecated: false };
+  }
+  const legacy = env?.[LEGACY_MCP_ENV_VAR];
+  if (typeof legacy === "string" && legacy) {
+    return { envVar: LEGACY_MCP_ENV_VAR, key: legacy, deprecated: true, notice: legacyNotice };
+  }
+  return null;
+}
+
+// Map a mint_mcp_key server refusal code to a CLI error code the receipt reports.
+function mapMintCode(code) {
+  if (code === "MCP_TENANT_PIN_REQUIRED" || code === "MCP_TENANT_SELECTION_REQUIRED") return "tenant_pin_required";
+  if (code === "MCP_TENANT_MEMBERSHIP_REQUIRED") return "tenant_forbidden";
+  if (code === "mcp_key_owner_required") return "owner_required";
+  if (code === "owner_auth_required") return "not_authenticated";
+  return code || "mint_failed";
+}
+
+/**
+ * Mint a `bb_mcp_` key, authenticated by the tier-1 owner/client credential, and
+ * store it in the Keychain under `envVar` (read-back verified). On a host without
+ * a Keychain (BOTBUDDY_NO_KEYCHAIN / non-darwin) it is NOT persisted — the raw
+ * key is returned so the caller can place it in a secret store (CI should prefer
+ * a `bb_ci_` key, not a planted `bb_mcp_`).
+ */
+export async function setupMcpKey({
+  envVar = DEFAULT_MCP_ENV_VAR,
+  tenant = null,
+  label = null,
+  expiryDays = null,
+  force = false,
+  call = callToolJson,
+  resolveAuth = resolveCallAuth,
+  keychainAvailable: keychainAvail = keychainAvailable,
+  writeKeychain = writeKeychainSecret,
+  readKeychain = readKeychainSecret,
+  mcpUrl = SERVER_URL,
+} = {}) {
+  const pinned = await resolveAuth();
+  if (pinned?.error) throw new McpKeyError("not_authenticated");
+  const auth = pinned?.auth ?? null;
+
+  // Codex P1/P2: refuse to mint into an OCCUPIED Keychain slot unless --force.
+  // Re-running setup would `security -U`-overwrite the local secret AFTER a
+  // second server credential is minted, silently orphaning the previous, still
+  // ACTIVE bb_mcp_ row (its plaintext + agent_id no longer on this machine).
+  // Check BEFORE minting so a collision creates no new credential — and fail
+  // CLOSED: a STRICT read distinguishes a genuinely-empty slot from a transient
+  // read failure (a swallowed failure would look empty and overwrite a live key).
+  if (!force && keychainAvail()) {
+    let existing = null;
+    try {
+      existing = await readKeychain(envVar, { strict: true });
+    } catch (error) {
+      throw new McpKeyError("keychain_read_failed", { detail: error?.message ?? String(error) });
+    }
+    if (typeof existing === "string" && existing) {
+      throw new McpKeyError("env_var_in_use", { detail: envVar });
+    }
+  }
+
+  const args = {
+    ...(label ? { label } : {}),
+    ...(expiryDays != null ? { expiry_days: expiryDays } : {}),
+  };
+  const response = await call("mint_mcp_key", args, { auth, ...(tenant ? { tenant } : {}) });
+
+  const code = structuredCode(response);
+  // A 401/403 that carries a STRUCTURED tenant code (pin/membership) is not a
+  // credential failure — the login is valid, the tenant is wrong. Map it so the
+  // recovery is accurate; only a code-less refusal is a true auth failure (Codex P2).
+  if (response?.auth || (response?.ok === false && response?.error === "unauthorized")) {
+    if (code) throw new McpKeyError(mapMintCode(code));
+    throw new McpKeyError("not_authenticated");
+  }
+  if (!response?.ok || response.isError || response.data?.ok === false) {
+    throw new McpKeyError(mapMintCode(code));
+  }
+  const key = response.data?.api_key;
+  const agentId = response.data?.agent_id;
+  const tenantId = response.data?.tenant_id ?? tenant ?? null;
+  if (typeof key !== "string" || !key.startsWith("bb_mcp_") || typeof agentId !== "string") {
+    throw new McpKeyError("mint_failed");
+  }
+
+  let stored = false;
+  if (keychainAvail()) {
+    try {
+      // createOnly when !force makes the write itself the atomic guard: if the
+      // slot filled between the preflight read and here, `security` (no -U) fails
+      // "already exists" and we roll the just-minted key back below (Codex P2).
+      await writeKeychain(envVar, key, { createOnly: !force });
+      stored = true;
+    } catch (error) {
+      // AC2: a read-back mismatch / locked Keychain must fail LOUDLY — the key
+      // was minted, so never report success with an unverified store.
+      // Codex P2: the server already persisted the key. An un-stored key is an
+      // orphan the operator can't see to revoke, and every retry would mint
+      // another live row — so roll it back (best-effort) before failing. If the
+      // rollback itself fails, surface the agent_id so it can be revoked by hand.
+      let rolledBack = false;
+      try {
+        const undo = await call("revoke_mcp_key", { agent_id: agentId }, { auth, ...(tenant ? { tenant } : {}) });
+        rolledBack = Boolean(undo?.ok && !undo.isError && undo.data?.ok !== false);
+      } catch {
+        // keep rolledBack=false — the message tells the operator to revoke it.
+      }
+      // Codex P2: a create-only write can fail its read-back verification AFTER
+      // the item was created, leaving a stale item the strict occupied-slot
+      // preflight would then reject on retry — so always spell out clearing it.
+      const clearHint = `if a stale item remains under ${envVar}, clear it first with \`security delete-generic-password -s ${envVar}\`, then `;
+      const tail = rolledBack
+        ? `the freshly minted key was rolled back — unlock the Keychain, ${clearHint}re-run \`botbuddy mcp setup\`.`
+        : `the minted key could NOT be rolled back — revoke it with \`botbuddy mcp revoke ${agentId} --env ${envVar}\`, ${clearHint}re-run setup.`;
+      throw new McpKeyStoreError(
+        `minted the MCP key but could not store it in the macOS Keychain under ${envVar}: ${error?.message ?? error}; ${tail}`,
+        { cause: error, agentId, rolledBack },
+      );
+    }
+  }
+
+  return {
+    schema_version: 1,
+    outcome: stored ? "installed" : "minted_no_keychain",
+    // Codex P1: storing ≠ exporting. When stored in the Keychain, the key is not
+    // yet in the environment the MCP client reads — spell out the loader so the
+    // operator doesn't launch Claude/Codex with $envVar unset.
+    ...(stored
+      ? { next_step: `Load it into your shell (and the MCP client it launches): export ${envVar}="$(security find-generic-password -w -a "$USER" -s ${envVar})" — see snippets.keychain for the store+load pair.` }
+      : {}),
+    env_var: envVar,
+    key_prefix: "bb_mcp_",
+    agent_id: agentId,
+    tenant_id: tenantId,
+    // Only surface the raw key when it could NOT be stored (headless/CI), so the
+    // operator can place it themselves. On a Keychain host it is never echoed.
+    ...(stored ? {} : { api_key: key }),
+    // When stored, the snippet is loader-only (no store prompt for a key the user
+    // no longer has); otherwise it carries the store+load pair (Codex P2).
+    snippets: mcpKeySnippets(envVar, { mcpUrl, loaderOnly: stored }),
+  };
+}
+
+// Map a revoke_mcp_key server refusal to a CLI error code.
+function mapRevokeCode(code) {
+  if (code === "MCP_TENANT_PIN_REQUIRED" || code === "MCP_TENANT_SELECTION_REQUIRED") return "tenant_pin_required";
+  if (code === "MCP_TENANT_MEMBERSHIP_REQUIRED") return "tenant_forbidden";
+  if (code === "mcp_key_owner_required") return "owner_required";
+  if (code === "owner_auth_required") return "not_authenticated";
+  if (code === "mcp_key_wrong_kind") return "not_an_mcp_key";
+  if (code === "mcp_key_not_found") return "not_found";
+  if (code === "mcp_key_forbidden") return "forbidden";
+  return code || "revoke_failed";
+}
+
+/**
+ * Revoke a `bb_mcp_` key by its agent_id via the owner/client credential.
+ *
+ * The server binds revocation to the connection's authenticated tenant (BOT-1607
+ * Codex P1), so a multi-tenant owner MUST pin the tenant the key lives in — the
+ * same tenant `mcp setup --tenant` minted it for. Without `tenant` the call rides
+ * the repo profile's default pin and the server refuses a cross-tenant revoke,
+ * leaving the key live. Forward `--tenant` so `mcp revoke --tenant <slug>` works.
+ */
+export async function revokeMcpKey({
+  agentId,
+  tenant = null,
+  envVar = null,
+  call = callToolJson,
+  resolveAuth = resolveCallAuth,
+} = {}) {
+  if (typeof agentId !== "string" || !agentId.trim()) throw new McpKeyError("agent_id_required");
+  const id = agentId.trim();
+  const pinned = await resolveAuth();
+  if (pinned?.error) throw new McpKeyError("not_authenticated");
+  const auth = pinned?.auth ?? null;
+
+  const response = await call("revoke_mcp_key", { agent_id: id }, { auth, ...(tenant ? { tenant } : {}) });
+  const code = structuredCode(response);
+  // A structured tenant code (pin/membership) on a 401/403 is a tenant mismatch,
+  // not a credential failure — map it so recovery is accurate (Codex P2).
+  if (response?.auth || (response?.ok === false && response?.error === "unauthorized")) {
+    if (code) throw new McpKeyError(mapRevokeCode(code));
+    throw new McpKeyError("not_authenticated");
+  }
+  if (!response?.ok || response.isError || response.data?.ok === false) {
+    throw new McpKeyError(mapRevokeCode(code));
+  }
+
+  // The server key is now dead. The CLI does NOT delete the local Keychain slot
+  // itself (BOT-1607, Codex rounds 5–11): revoke is keyed by agent_id, which
+  // cannot be safely mapped to a machine Keychain slot — `--env` accepts any
+  // service name (a typo could name an unrelated secret), the probe/delete cannot
+  // be made atomic against a concurrent `mcp setup` (no OS compare-and-delete),
+  // and macOS offers no per-service cross-process lock. So we always hand back the
+  // exact, side-effect-free deletion command instead of deleting anything.
+  const slot = envVar || "<NAME>";
+  return {
+    schema_version: 1,
+    outcome: "revoked",
+    agent_id: id,
+    ...(envVar ? { env_var: envVar } : {}),
+    next_step:
+      `The server key is revoked. If a local Keychain slot still holds it, the next \`mcp setup\` will refuse that slot — `
+      + `clear it yourself with \`security delete-generic-password -s ${slot}\`.`,
+  };
+}

package/src/oauth-loopback.mjs

@@ -89,10 +89,18 @@ export function buildAuthorizeUrl({
   url.searchParams.set("state", state);
   url.searchParams.set("code_challenge", codeChallenge);
   url.searchParams.set("code_challenge_method", "S256");
-  // BOT-1566: `login --tenant <slug>` preselects the tenant. /authorize forwards
-  // it to the /mcp-auth picker as `requestedTenant`; membership is still
-  // enforced server-side at authorize_complete — this only preselects.
-  if (tenant) url.searchParams.set("tenant", tenant);
+  // BOT-1571: two OAuth modes. A plain `login` asks for a USER token
+  // (`tenant_mode=user`): not bound to any tenant, so one login serves every
+  // `profile setup`, each of which pins its own tenant per request. `login
+  // --tenant <slug>` asks for a TENANT token SEALED to that slug
+  // (`tenant_mode=tenant` + `tenant=` — membership is still enforced
+  // server-side at authorize_complete).
+  if (tenant) {
+    url.searchParams.set("tenant_mode", "tenant");
+    url.searchParams.set("tenant", tenant);
+  } else {
+    url.searchParams.set("tenant_mode", "user");
+  }
   // BOT-1580: display-only caller identity, so the human approving the login can
   // check it against the agent session they are actually running. These are
   // UNVERIFIED hints — /authorize only forwards them to the consent screen; they

package/src/profile-bootstrap.mjs

@@ -210,10 +210,23 @@ export function profileBootstrapRecovery(code, profileName) {
     // tenant-bound token can't be repointed) or the owner isn't a member of the
     // profile's tenant. The fix is to authenticate INTO the profile's tenant —
     // not the bare login loop, which relogs into the same wrong tenant.
+    // BOT-1571: a plain `botbuddy login` (no --tenant) now mints a USER token
+    // that reaches every tenant the owner belongs to, so the fix is that — not
+    // "log in again and pick this tenant", which is exactly the per-tenant
+    // re-login friction BOT-1571 removes.
+    // BOT-1571 (Codex follow-up): MCP_TENANT_MEMBERSHIP_REQUIRED conflates two
+    // causes and the CLI cannot tell them apart from the code alone — the owner
+    // is not a member of the tenant, OR a `--tenant`-sealed login is pinned to a
+    // different one. Lead with the membership case and say re-login will NOT fix
+    // it (a user token still can't reach a tenant you don't belong to), so a
+    // non-member is not sent through a no-op `botbuddy login` loop; offer the
+    // re-login only for the genuinely-sealed case.
     const tenant = getAgentProfile(profileName)?.tenant;
-    return tenant
-      ? `run botbuddy login and select the "${tenant}" tenant during authentication, then re-run: botbuddy profile setup ${profileName} (if you are not a member of "${tenant}", ask an admin for access)`
-      : `run botbuddy login and select the profile's tenant during authentication, then re-run: botbuddy profile setup ${profileName}`;
+    const forTenant = tenant ? ` tenant "${tenant}"` : " this profile's tenant";
+    const memberHint = tenant
+      ? `if you are not a member of "${tenant}", ask an admin to add you — a re-login will not help`
+      : "if you are not a member of it, ask an admin to add you — a re-login will not help";
+    return `your login is not authorized for${forTenant}: ${memberHint}. If instead your login is sealed to a different tenant (you signed in with --tenant), run botbuddy login (without --tenant) to get a user token that reaches all your tenants, then re-run: botbuddy profile setup ${profileName}`;
   }
   if (code === "profile_tenant_unverified") {
     // whoami could not confirm the bound tenant, so registration was refused

package/src/wait.mjs

@@ -120,12 +120,23 @@ OPTIONS
   --receipt-max-bytes <n>   cap the receipt (minimum 512; default 10240; payloads truncate to pointers)
   --heartbeat           keep this agent session alive while waiting (so it is not reaped)
   --url <base>          relay base URL (default $BOTBUDDY_RELAY_URL or https://api.bot-buddy.ai/functions/v1)
-  --profile <name>      tenant-bound machine profile (normally read from .botbuddy-agent.json)
+  --agent-key <token>   the bb_agent_ session token to authenticate this wait — a one-liner
+                        equivalent to exporting $BOTBUDDY_AGENT_KEY (which is the default).
+                        Only accepts a session token; a client/profile key is refused.
+                        (--session-token is the one-release legacy alias.)
   --session-id <uuid>   attribute this wait to the arming session (the work-graph session id from register_agent); default $BOTBUDDY_SESSION_ID.
-                        REQUIRED for any non-timer wait (a wait must name the work agent that armed it).
-  --token <key>         explicit agent key override; otherwise the profile-specific env is used
+                        Unnecessary when $BOTBUDDY_AGENT_KEY / --agent-key is set (the relay derives the session from the token).
   --help                show this help
 
+AUTH
+  A wait authenticates from the bb_agent_ session token (minted by register_agent):
+  export $BOTBUDDY_AGENT_KEY, or pass it inline with --agent-key for a one-liner
+  ($BOTBUDDY_SESSION_TOKEN / --session-token still accepted for one release).
+  --token and --profile are RETIRED (BOT-1574): they were untyped and could carry a
+  machine credential; use --agent-key, which only accepts a session token. The
+  per-machine client key (botbuddy login) is a setup credential, never a wait
+  credential.
+
 OUTPUT
   Exactly one JSON receipt line on stdout at exit, with client semver and
   protocol identity. Diagnostics go to stderr.
@@ -191,9 +202,19 @@ function parseArgv(argv) {
     else if (a === "--since") opts.since = optionValue();
     else if (a === "--receipt-max-bytes") opts.receiptMaxBytes = Number(optionValue());
     else if (a === "--url") opts.url = optionValue();
-    else if (a === "--token") opts.token = optionValue();
-    else if (a === "--session-token") opts.sessionToken = optionValue();
-    else if (a === "--profile") opts.profile = optionValue();
+    // BOT-1574: --token and --profile are RETIRED. A wait authenticates from
+    // $BOTBUDDY_SESSION_TOKEN (minted by register_agent) alone; the per-machine
+    // client key (`botbuddy login`) is never a wait credential. Consume any
+    // following value so it is not mis-parsed as a condition, then fail fast in
+    // runWait with a migration hint (AC3).
+    else if (a === "--token" || a === "--profile") { opts.retiredFlag ??= a; optionValue(); }
+    // BOT-1574: --agent-key is the typed one-liner for the wait credential — it
+    // carries the bb_agent_ session token (equivalent to exporting
+    // $BOTBUDDY_AGENT_KEY), and NOTHING else: a client key / profile key is the
+    // wrong shape and is refused invalid_session_token, so it can never smuggle a
+    // machine credential onto a wait. --session-token is the one-release legacy
+    // alias for the same value.
+    else if (a === "--agent-key" || a === "--session-token") opts.sessionToken = optionValue();
     else if (a === "--session-id") opts.sessionId = optionValue();
     else if (a.startsWith("--")) opts.unknown = a;
     else opts.conditions.push(a);
@@ -836,6 +857,23 @@ export async function runWait(argv) {
     process.stdout.write(HELP);
     process.exit(0);
   }
+  // BOT-1574 (AC3): --token / --profile are retired. Emit the migration hint and
+  // a typed `unknown_option` receipt, then exit 4 — before any relay call.
+  if (opts.retiredFlag) {
+    process.stderr.write(
+      `botbuddy wait: ${opts.retiredFlag} is retired (it could carry a machine credential) — a wait authenticates from the bb_agent_ session token. `
+        + "Pass it typed with --agent-key <token>, or export $BOTBUDDY_AGENT_KEY (from register_agent), then: botbuddy wait '<condition>'. "
+        + "The per-machine client key (botbuddy login) is never a wait credential.\n",
+    );
+    emitReceipt({
+      schema_version: 1,
+      outcome: "error",
+      error: "unknown_option",
+      option: opts.retiredFlag,
+      recovery: `${RECOVERY.sessionToken}; then: botbuddy wait '<condition>'`,
+    });
+    process.exit(EXIT.INVALID);
+  }
   if (opts.unknown) {
     process.stderr.write(`bb-wait: unknown option ${opts.unknown}\n`);
     emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_arguments", option: opts.unknown });
@@ -1045,6 +1083,22 @@ export async function runWait(argv) {
         process.exit(EXIT.INVALID);
       }
       if (err && err.auth) {
+        // BOT-1574 (AC4): the relay refused a wait armed by the per-machine client
+        // key (or any owner/setup credential). The fix is never profile setup —
+        // register a work agent and export its session token. Handle it before the
+        // profile-recovery branches, which would dereference an absent agentProfile.
+        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",
+          );
+          emitReceipt({
+            schema_version: 1,
+            outcome: "error",
+            error: "client_key_cannot_wait",
+            recovery: `${RECOVERY.sessionToken}; then: botbuddy wait '<condition>'`,
+          });
+          process.exit(EXIT.AUTH);
+        }
         // BOT-1572: a session-token failure (revoked/expired/rotated, or the relay
         // refusing to honour the token) is fixed by RE-REGISTERING, not by profile
         // setup. Lead with that, and never touch the (absent) agentProfile.