@botbuddy/cli 1.21.1 → 1.23.0

package/package.json

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

package/src/api.mjs

@@ -1,7 +1,53 @@
 import { getConfig, SERVER_URL } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
+import { findProfileName, getAgentProfile } from "./wait-profile.mjs";
 import { die, cyan, dim, yellow, prettyJson } from "./utils.mjs";
 
+// Same slug shape the server accepts on `?tenant=`.
+const TENANT_PIN_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+// BOT-1571 (Codex P1): a plain `botbuddy login` mints a USER token, which the
+// 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),
+//   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
+// resolves its own tenant, and a differing pin would be a hard conflict
+// (a pin can confirm a sealed tenant, never repoint it). BOTBUDDY_TENANT is
+// always honoured — it is the operator's explicit statement.
+export async function resolveDefaultTenantPin({
+  getConfig: getCfg = getConfig,
+  env = process.env,
+  cwd = process.cwd(),
+  findProfile = findProfileName,
+  profileFor = getAgentProfile,
+} = {}) {
+  const explicit = typeof env.BOTBUDDY_TENANT === "string" ? env.BOTBUDDY_TENANT.trim() : "";
+  if (explicit) {
+    if (!TENANT_PIN_RE.test(explicit)) throw new Error("BOTBUDDY_TENANT must be a lowercase tenant slug");
+    return explicit;
+  }
+  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;
+  const tenants = Array.isArray(cfg.token_tenants) ? cfg.token_tenants.filter((t) => typeof t === "string" && t) : [];
+  return tenants.length === 1 ? tenants[0] : null;
+}
+
+// Endpoint for a generic call: explicit `tenant` beats the derived pin.
+async function genericEndpoint({ tenant = null, resolvePin = resolveDefaultTenantPin } = {}) {
+  let pin = tenant;
+  if (!pin) {
+    try { pin = await resolvePin(); } catch (err) { die(err.message); }
+  }
+  return toolEndpoint(pin);
+}
+
 // BOT-1520: auth headers come from the Keychain, never a plaintext config.json
 // secret. The owner OAuth token (from `botbuddy login`) is preferred; the
 // tenant-bound agent key (from `botbuddy profile setup`) is the fallback.
@@ -23,8 +69,8 @@ async function authHeader() {
   die(`Not authenticated. Run: ${cyan("botbuddy login")}`);
 }
 
-export async function callTool(toolName, args = {}) {
-  const headers = { "Content-Type": "application/json", ...(await authHeader()) };
+export async function callTool(toolName, args = {}, { fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, log = (line) => console.log(line) } = {}) {
+  const headers = { "Content-Type": "application/json", ...(auth ?? await authHeader()) };
   const body = {
     jsonrpc: "2.0",
     id: 1,
@@ -32,16 +78,22 @@ export async function callTool(toolName, args = {}) {
     params: { name: toolName, arguments: args },
   };
 
-  const res = await fetch(SERVER_URL, { method: "POST", headers, body: JSON.stringify(body) });
+  const res = await fetchImpl(await genericEndpoint({ tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
   const data = await res.json();
 
-  if (data.error?.message) die(`Server error: ${data.error.message}`);
+  if (data.error?.message) {
+    const code = data.error?.data?.code;
+    const hint = code === "MCP_TENANT_PIN_REQUIRED"
+      ? ` Pin a tenant: ${cyan("botbuddy call <tool> --pin <slug>")}, ${cyan("BOTBUDDY_TENANT=<slug>")}, or run from a repo with ${dim(".botbuddy-agent.json")}.`
+      : "";
+    die(`Server error: ${data.error.message}${hint}`);
+  }
 
   const text = data.result?.content?.map((c) => c.text).join("\n");
   if (text) {
-    console.log(prettyJson(text));
+    log(prettyJson(text));
   } else {
-    console.log(JSON.stringify(data, null, 2));
+    log(JSON.stringify(data, null, 2));
   }
   return data;
 }
@@ -84,17 +136,26 @@ function toolEndpoint(tenant) {
   return url.toString();
 }
 
-export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, signal, auth: pinnedAuth = null, tenant = null } = {}) {
+export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, signal, auth: pinnedAuth = null, tenant = null, resolvePin = resolveDefaultTenantPin } = {}) {
   let auth = pinnedAuth;
   if (!auth) {
     const resolved = await resolveCallAuth();
     if (resolved.error) return resolved.error;
     auth = resolved.auth;
   }
+  // BOT-1571 (Codex P1, round 2): `botbuddy stack` and every other
+  // callToolJson caller that passes no explicit tenant would send a USER token
+  // unpinned → MCP_TENANT_PIN_REQUIRED. Derive the default pin, but only for
+  // an OWNER bearer — an agent key is already tenant-bound and a differing
+  // derived pin would be a spurious conflict.
+  let pin = tenant;
+  if (!pin && auth && Object.prototype.hasOwnProperty.call(auth, "Authorization")) {
+    try { pin = await resolvePin(); } catch (err) { return { ok: false, status: null, error: `usage: ${err?.message ?? err}` }; }
+  }
   const body = { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: toolName, arguments: args } };
   let res;
   try {
-    res = await fetchImpl(toolEndpoint(tenant), {
+    res = await fetchImpl(toolEndpoint(pin), {
       method: "POST",
       headers: { "Content-Type": "application/json", ...auth },
       body: JSON.stringify(body),
@@ -127,23 +188,23 @@ export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, sig
   return { ok: true, data, isError: payload.result?.isError === true };
 }
 
-export async function listResources() {
-  const headers = { "Content-Type": "application/json", ...(await authHeader()) };
+export async function listResources({ fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, log = (line) => console.log(line) } = {}) {
+  const headers = { "Content-Type": "application/json", ...(auth ?? await authHeader()) };
   const body = { jsonrpc: "2.0", id: 1, method: "resources/list", params: {} };
-  const res = await fetch(SERVER_URL, { method: "POST", headers, body: JSON.stringify(body) });
+  const res = await fetchImpl(await genericEndpoint({ tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
   const data = await res.json();
-  console.log(JSON.stringify(data.result?.resources ?? data.result ?? data, null, 2));
+  log(JSON.stringify(data.result?.resources ?? data.result ?? data, null, 2));
 }
 
-export async function readResource(uri) {
-  const headers = { "Content-Type": "application/json", ...(await authHeader()) };
+export async function readResource(uri, { fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, log = (line) => console.log(line) } = {}) {
+  const headers = { "Content-Type": "application/json", ...(auth ?? await authHeader()) };
   const body = { jsonrpc: "2.0", id: 1, method: "resources/read", params: { uri } };
-  const res = await fetch(SERVER_URL, { method: "POST", headers, body: JSON.stringify(body) });
+  const res = await fetchImpl(await genericEndpoint({ tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
   const data = await res.json();
   const text = data.result?.contents?.[0]?.text;
   if (text) {
-    console.log(prettyJson(text));
+    log(prettyJson(text));
   } else {
-    console.log(JSON.stringify(data.result ?? data, null, 2));
+    log(JSON.stringify(data.result ?? data, null, 2));
   }
 }

package/src/auth.mjs

@@ -170,8 +170,14 @@ export async function doLogin(options = {}, deps = {}) {
     // BOT-1566: a Keychain read-back mismatch (`keychain_readback_mismatch`)
     // propagates from here, so login exits non-zero and the success line below
     // is never printed for a credential that did not verifiably land.
+    // BOT-1571: record the token's scope. A server that predates tenant modes
+    // omits `tenant_mode`; such a token is sealed (or legacy), never assumed
+    // to be a user token.
+    const tenantMode = tokenData.tenant_mode === "user" ? "user" : "tenant";
+    const tenantId = typeof tokenData.tenant_id === "string" && tokenData.tenant_id ? tokenData.tenant_id : null;
+    const tenants = Array.isArray(tokenData.tenants) ? tokenData.tenants.filter((t) => typeof t === "string" && t) : [];
     const { storedInKeychain } = await persist(
-      { token: tokenData.access_token, expiresAt, clientId },
+      { token: tokenData.access_token, expiresAt, clientId, tenantMode, tenantId, tenants },
       { getConfig, saveConfig, warn: errorLog },
     );
 
@@ -180,6 +186,11 @@ export async function doLogin(options = {}, deps = {}) {
         storedInKeychain ? "the macOS Keychain" : dim("~/.botbuddy/config.json")
       }.`,
     );
+    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.`);
+    } 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.`);
+    }
     return { clientId, redirectUri };
   } finally {
     // AC-11/AC-13: always release the socket so re-running login starts clean.

package/src/cli-credentials.mjs

@@ -25,9 +25,19 @@ import {
 } from "./agent-credential-store.mjs";
 import { resolveAgentProfile } from "./wait-profile.mjs";
 
-// Dedicated Keychain service for the owner OAuth token. Distinct from the
-// per-profile agent-key services (BOTBUDDY_BB_AGENT_KEY / BOTBUDDY_SG_AGENT_KEY)
-// so the human owner session and the machine agent identity never collide.
+// 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
+// owner's memberships — and that token IS the machine's client credential. It is
+// stored under ONE Keychain item per machine, distinct from the per-profile
+// agent-key services (BOTBUDDY_BB_AGENT_KEY / BOTBUDDY_SG_AGENT_KEY) and from the
+// per-session token (bb_sess_), so a setup credential is never mistaken for an
+// agent. (The wire format stays `mcp_at_`; "client key" is the kind, not a new
+// prefix — the OAuth token format is out of scope for BOT-1574.)
+export const CLIENT_KEY_SERVICE = "BOTBUDDY_CLIENT_KEY";
+
+// The legacy service the same token was stored under before BOT-1574. Still read
+// (so an already-logged-in user keeps working across the upgrade without
+// re-login) and cleared on logout; `login` always writes CLIENT_KEY_SERVICE now.
 export const OWNER_TOKEN_SERVICE = "BOTBUDDY_OWNER_TOKEN";
 
 // Config keys that must never carry secret material at rest.
@@ -67,11 +77,11 @@ export async function migrateConfigSecrets(config, {
   exists,
   // `createOnly`: the migration write must not overwrite a token another process
   // wrote after our empty-slot read (BOT-1569 Codex P2 TOCTOU).
-  keychainWrite = (value) => writeKeychainSecret(OWNER_TOKEN_SERVICE, value, { createOnly: true }),
+  keychainWrite = (value) => writeKeychainSecret(CLIENT_KEY_SERVICE, value, { createOnly: true }),
   // `strict`: a transient READ failure throws (fail closed) instead of reading as
   // an empty slot, so the migration never overwrites a live stored token because
   // the lookup momentarily failed (BOT-1569 Codex P2).
-  keychainRead = () => readKeychainSecret(OWNER_TOKEN_SERVICE, { strict: true }),
+  keychainRead = () => readKeychainSecret(CLIENT_KEY_SERVICE, { strict: true }),
   warn = (message) => console.error(message),
 } = {}) {
   const out = { ...(config ?? {}) };
@@ -167,13 +177,13 @@ export async function migrateConfigSecrets(config, {
 // the token itself goes to the Keychain on darwin, or (with a warning) stays in
 // the 0600 config.json where no Keychain exists.
 export async function persistOwnerToken(
-  { token, expiresAt, clientId },
+  { token, expiresAt, clientId, tenantMode, tenantId, tenants },
   {
     platform = process.platform,
     exists,
     getConfig,
     saveConfig,
-    keychainWrite = (value) => writeKeychainSecret(OWNER_TOKEN_SERVICE, value),
+    keychainWrite = (value) => writeKeychainSecret(CLIENT_KEY_SERVICE, value),
     warn = (message) => console.error(message),
   } = {},
 ) {
@@ -187,6 +197,16 @@ export async function persistOwnerToken(
   const next = { ...base };
   if (clientId !== undefined) next.client_id = clientId;
   if (expiresAt !== undefined) next.token_expires_at = expiresAt;
+  // BOT-1571: the token's SCOPE (non-secret). `user` = not bound to a tenant,
+  // pins one per request; `tenant` = sealed to token_tenant_id. Recorded from
+  // the /token response so `status` can describe the credential and probe it
+  // with a pin it is known to reach. Always replaced together, never merged
+  // with a previous login's scope.
+  if (tenantMode !== undefined) {
+    next.token_tenant_mode = tenantMode;
+    next.token_tenant_id = tenantId ?? null;
+    next.token_tenants = Array.isArray(tenants) ? tenants.filter((t) => typeof t === "string" && t) : [];
+  }
 
   if (keychain) {
     await keychainWrite(token);
@@ -209,25 +229,38 @@ export async function resolveOwnerToken({
   platform = process.platform,
   exists,
   getConfig,
-  keychainRead = () => readKeychainSecret(OWNER_TOKEN_SERVICE),
+  keychainRead = () => readKeychainSecret(CLIENT_KEY_SERVICE),
+  // BOT-1574 migration: a machine logged in before 1574 has the token under the
+  // legacy OWNER_TOKEN service. Read it as a fallback so an upgrade needs no
+  // re-login; `login` rewrites it to CLIENT_KEY, and `logout` clears both.
+  keychainReadLegacy = () => readKeychainSecret(OWNER_TOKEN_SERVICE),
 } = {}) {
   const cfg = getConfig() ?? {};
   const expiresAt = typeof cfg.token_expires_at === "number" ? cfg.token_expires_at : null;
   let token = null;
   if (keychainAvailable(platform, exists)) {
     token = await keychainRead();
+    if (!token) token = await keychainReadLegacy();
   } else if (typeof cfg.access_token === "string" && cfg.access_token) {
     token = cfg.access_token;
   }
   if (!token) return null;
-  return { token, expiresAt };
+  const tenantMode = cfg.token_tenant_mode === "user" || cfg.token_tenant_mode === "tenant" ? cfg.token_tenant_mode : null;
+  const tenantId = typeof cfg.token_tenant_id === "string" && cfg.token_tenant_id ? cfg.token_tenant_id : null;
+  const tenants = Array.isArray(cfg.token_tenants) ? cfg.token_tenants.filter((t) => typeof t === "string" && t) : [];
+  return { token, expiresAt, tenantMode, tenantId, tenants };
 }
 
-// Remove the owner OAuth token from every store (`botbuddy logout`).
+// Remove the client key from every store (`botbuddy logout`). Clears BOTH the
+// current CLIENT_KEY item and the legacy OWNER_TOKEN item so a pre-1574 token
+// left behind by the read-both migration is never orphaned in the Keychain.
 export async function clearOwnerToken({
   platform = process.platform,
   exists,
-  keychainDelete = () => deleteKeychainSecret(OWNER_TOKEN_SERVICE),
+  keychainDelete = async () => {
+    await deleteKeychainSecret(CLIENT_KEY_SERVICE);
+    await deleteKeychainSecret(OWNER_TOKEN_SERVICE);
+  },
 } = {}) {
   if (keychainAvailable(platform, exists)) {
     await keychainDelete();

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";
@@ -55,6 +56,7 @@ 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 "resources": return callTool("list_resources");
     case "agents": return callTool("list_agents");
     case "tasks": return readResource("botbuddy://tasks");
@@ -96,13 +98,16 @@ ${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("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 +151,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 +286,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 +308,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 +341,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 +398,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 +440,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 +459,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 +516,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 +587,95 @@ 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>   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
 
-  setup <profile>   Mint/reconnect and securely store a tenant-bound agent key
-  env <profile>     Print shell exports that load the stored agent 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}\`.`,
     }));
-    process.exitCode = 3;
+    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 });
 }
 
 function cmdLock(args) {

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 };
 }
 
 /**

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/stack.mjs

@@ -31,6 +31,7 @@ import { callToolJson } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { runDockerCommand, runDockerWorkflow } from "./docker-hygiene.mjs";
+import { machineUuid } from "./machine-id.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
 
 export const STACK_SCHEMA_VERSION = 1;
@@ -667,6 +668,7 @@ export async function cmdUp(opts, {
   localProvisionFn = localProvision,
   waitFn = waitForLease,
   emitResult = emit,
+  machineUuidFn = machineUuid,
 } = {}) {
   let slot;
   try { slot = deriveSlot(opts); } catch (e) {
@@ -696,6 +698,13 @@ export async function cmdUp(opts, {
   const auth = await authProvider();
   if (!auth) return emitResult(buildReceipt({ command: "up", outcome: "error", error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
 
+  // BOT-1585: co-location dispatches the lease to the Helper enrolled for THIS
+  // physical machine (hardware id), since a hostname is not machine-unique. The
+  // server requires it; fail fast with an actionable message if it can't be read.
+  const hardwareUuid = machineUuidFn();
+  if (!hardwareUuid) {
+    return emitResult(buildReceipt({ command: "up", outcome: "error", code: "MACHINE_UUID_REQUIRED", error: "could not determine this machine's hardware id (needed to dispatch the stack lease to the right machine)" }), opts, EXIT.BACKEND);
+  }
   const req = await callTool("request_stack_lease", {
     slot, host_key: opts.host || undefined, repo: opts.repo || undefined,
     ticket_id: opts.ticket || undefined, ticket_url: opts.ticketUrl || undefined,
@@ -703,6 +712,7 @@ export async function cmdUp(opts, {
     purpose: opts.purpose || undefined, idle_ttl_secs: opts.idleTtl ?? undefined,
     stack_path: execution.stackPath,
     worktree_root: execution.worktreeRoot,
+    machine_uuid: hardwareUuid,
   });
   if (!req.ok) {
     return req.auth
@@ -1046,6 +1056,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
     release: (leaseId, signal) => callToolJson("release_stack_lease", { lease_id: leaseId, disposition: "destroy" }, { signal }),
   };
   const auth = adapters.auth ?? await stackAuthHeader();
+  const machineUuidFn = adapters.machineUuidFn ?? machineUuid;
   const wait = adapters.wait ?? ((leaseId, done, failed, options) => waitForLease(leaseId, done, failed, options));
   // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- validated executable + argv only; shell is never used.
   const startChild = adapters.startChild ?? ((argv, env, cwd) => spawn(argv[0], argv.slice(1), { cwd, env, stdio: "inherit", detached: true }));
@@ -1122,6 +1133,13 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
 
   try {
     if (!auth) return { exitCode: EXIT.AUTH, outcome: "error", error: "not authenticated — run botbuddy profile setup botbuddy-dev" };
+    // BOT-1585: request_stack_lease requires this machine's hardware id so the lease
+    // dispatches to the machine the worktree was registered on. `stack run` builds its
+    // own payload (separate from `cmdUp`), so it must send it too.
+    const hardwareUuid = machineUuidFn();
+    if (!hardwareUuid) {
+      return { exitCode: EXIT.BACKEND, outcome: "error", error: "could not determine this machine's hardware id (needed to dispatch the stack lease to the right machine)" };
+    }
     const slot = deriveSlot(opts);
     const execution = resolveStackPath(process.cwd(), opts.stackPath);
     const request = await api.request({
@@ -1129,6 +1147,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
       ticket_url: opts.ticketUrl || undefined, pr_id: opts.prId || undefined, pr_url: opts.prUrl || undefined,
       purpose: opts.purpose || "stack run", idle_ttl_secs: opts.idleTtl ?? undefined,
       stack_path: execution.stackPath, worktree_root: execution.worktreeRoot,
+      machine_uuid: hardwareUuid,
     });
     if (!request?.ok) return { exitCode: request?.auth ? EXIT.AUTH : EXIT.BACKEND, outcome: "error", error: request?.error || "lease request failed" };
     if (!request.data?.success) return { exitCode: EXIT.BACKEND, outcome: "error", error: request.data?.message || request.data?.code || "lease request 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.