@botbuddy/cli 1.25.0 → 1.26.0

package/src/mcp-key.mjs

@@ -1,8 +1,8 @@
 // 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 —
+// reused `bb_agent_` session token the retired `profile setup` planted in
+// BOTBUDDY_BB_AGENT_KEY (BOT-1608). `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` /
@@ -11,24 +11,25 @@
 // 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.
+// (owner/client-gated). This module uses dependency injection throughout so the
+// whole flow is unit-testable with an injected call / auth / keychain.
 
-import { keychainAvailable, readKeychainSecret, writeKeychainSecret } from "./agent-credential-store.mjs";
+import {
+  keychainAvailable,
+  readKeychainSecret,
+  writeKeychainSecret,
+  DEFAULT_MCP_ENV_VAR,
+  LEGACY_MCP_ENV_VAR,
+} 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";
+// The canonical MCP env/Keychain var names live in agent-credential-store.mjs
+// (the one module wait-profile.mjs and this file both import — no cycle). Re-export
+// them so existing importers (commands.mjs) keep resolving them from here.
+//   DEFAULT_MCP_ENV_VAR  — what `.mcp.json` references (BOT-1108 canonical set).
+//   LEGACY_MCP_ENV_VAR   — the pre-1607/1608 var; a DEPRECATED read alias one release.
+export { DEFAULT_MCP_ENV_VAR, LEGACY_MCP_ENV_VAR };
 
 // A valid shell env-var / Keychain service name.
 const ENV_VAR_RE = /^[A-Z][A-Z0-9_]*$/;
@@ -45,14 +46,14 @@ const RESERVED_ENV_VARS = new Set([
   "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_SG_AGENT_KEY",   // retired Supply Guard profile slot — 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.
+// BOTBUDDY_BB_AGENT_KEY is the deprecated MCP READ alias (LEGACY_MCP_ENV_VAR). It
+// was also the retired botbuddy profile Keychain slot, so `mcp status`/`env`
+// (read-only) may still name it, but `mcp setup`/`revoke` must NOT write or delete
+// it — an operator mid-migration may still have a live value there (Codex P2). It
+// is not in RESERVED_ENV_VARS so status/env can still resolve the legacy alias.
 
 export class McpKeyError extends Error {
   constructor(code, { detail = null } = {}) {

package/src/pw/coordinator.mjs

@@ -23,8 +23,3 @@ export function createSessionTokenCoordinator({ token, fetchImpl = fetch } = {})
   if (!token) return { kind: "unverified" };
   return laneCoordinator("session_token", mcpCaller({ "x-agent-api-key": token }, fetchImpl), null);
 }
-
-export function createProfileCoordinator({ profile, identity, fetchImpl = fetch } = {}) {
-  if (!profile?.token || !identity?.agentId || identity.tenant !== profile.tenant) return { kind: "unverified" };
-  return laneCoordinator("profile", mcpCaller({ "x-agent-api-key": profile.token }, fetchImpl), identity.agentId);
-}

package/src/pw/run.mjs

@@ -2,18 +2,17 @@ import os from "node:os";
 import { planInvocation } from "./args.mjs";
 import { actionTypeFromMethod, NAV } from "./readiness.mjs";
 import { isStaleRefError, staleRefRemediation } from "./targets.mjs";
-import { createProfileCoordinator, createSessionTokenCoordinator } from "./coordinator.mjs";
+import { createSessionTokenCoordinator } from "./coordinator.mjs";
 import { canonicalizeHostString } from "./host.mjs";
-import { resolveAgentProfile } from "../wait-profile.mjs";
-import { readProfileIdentity } from "../agent-credential-store.mjs";
+import { resolveAgentBinding } from "../wait-profile.mjs";
 import { loadConfig, getConfig } from "../config.mjs";
 import { VERSION } from "../version.mjs";
-import { readAgentKeyEnv } from "../agent-key.mjs";
+import { readAgentKeyEnv, AGENT_KEY_RE } from "../agent-key.mjs";
 // BOT-1488: canonicalize the raw hostname the SAME way acquire_resources does
 // server-side, so the lane name bb-pw builds/matches/prints is the one the lock
 // kernel actually stored ("jonos-mbp:8", not "Jonos-MBP.localdomain:8").
 const hostFor = (env) => canonicalizeHostString(env.PLAYWRIGHT_MCP_HOST || env.HOSTNAME || os.hostname());
-function help(out) { out.write("Usage: pw [--profile <name>] [--session-id <id>] <lane> <verb> [args…]\n\nAliases: bb-pw <lane> <verb> [args…]   ·   botbuddy pw <lane> <verb> [args…]\n         (all three drive the same lock-gated Playwright lane)\n\n--session-id <id>  accept a lane held by this arming-session agent id (from\n                   register_agent); defaults to $BOTBUDDY_SESSION_ID, then the\n                   id saved by `botbuddy register`.\n"); }
+function help(out) { out.write("Usage: pw [--tenant <slug>] [--session-id <id>] <lane> <verb> [args…]\n\nAliases: bb-pw <lane> <verb> [args…]   ·   botbuddy pw <lane> <verb> [args…]\n         (all three drive the same lock-gated Playwright lane)\n\n--session-id <id>  accept a lane held by this arming-session agent id (from\n                   register_agent); defaults to $BOTBUDDY_SESSION_ID, then the\n                   id saved by `botbuddy register`.\n--tenant <slug>    override the worktree .botbuddy-agent.json tenant when falling\n                   back to the .mcp.json ($BOTBUDDY_MCP_KEY) credential.\n"); }
 function redact(value, secretValues = []) { return secretValues.reduce((text, secret) => secret ? text.split(secret).join("[redacted]") : text, String(value ?? "")); }
 // BOT-1488: the register_agent identity for this machine, persisted by
 // `botbuddy register` into ~/.botbuddy/config.json. This is the SESSION agent
@@ -25,37 +24,38 @@ async function readRegisteredAgentId() { try { await loadConfig(); const id = ge
 async function gate({ env, host, lane, deps }) {
   if (env.BB_PW_NO_LOCK === "1") return { allowed: true };
   // BOT-1572/1582: a per-session `bb_agent_` token authenticates lock verification
-  // AS the session agent — no machine profile needed. It takes precedence over the
-  // profile path; holder matching then rides on the server's owner_is_caller
-  // (plus any local session/registered agent id). The profile path stays intact
-  // for a session that has not adopted the token. $BOTBUDDY_AGENT_KEY is the norm
-  // ($BOTBUDDY_SESSION_TOKEN still accepted for one release).
+  // AS the session agent — the server resolves it, holder matching rides on
+  // owner_is_caller (plus any local session/registered agent id). $BOTBUDDY_AGENT_KEY
+  // is the norm ($BOTBUDDY_SESSION_TOKEN still accepted for one release).
+  //
+  // BOT-1608: the retired profile-identity path is gone (its `agent-profiles.json`
+  // store no longer exists). When no session token is exported, fall back to the
+  // worktree binding's mcp_env credential (the `bb_mcp_` key from `.mcp.json`) —
+  // it authenticates the status call the same way and matching still rides on the
+  // server's owner_is_caller.
   const sessionToken = deps.sessionToken ?? readAgentKeyEnv(env);
+  if (sessionToken && !AGENT_KEY_RE.test(sessionToken)) {
+    return { allowed: false, message: "bb-pw: $BOTBUDDY_AGENT_KEY is malformed (expected bb_agent_<64 hex>). Re-register the agent, or set BB_PW_NO_LOCK=1 for local-only work." };
+  }
   const sessionAgentId = deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null;
   const registeredAgentId = await (deps.readSessionAgentId ?? readRegisteredAgentId)();
-  let coordinator, selfAgentIds, callerId;
-  if (sessionToken) {
-    coordinator = deps.coordinator ?? createSessionTokenCoordinator({ token: sessionToken, fetchImpl: deps.fetch });
-    if (coordinator.kind === "unverified") return { allowed: false, message: "bb-pw: $BOTBUDDY_AGENT_KEY is malformed. Re-register the agent, or set BB_PW_NO_LOCK=1 for local-only work." };
-    selfAgentIds = new Set([sessionAgentId, registeredAgentId, coordinator.agentId].filter(Boolean));
-    callerId = coordinator.agentId ?? sessionAgentId ?? "session-token";
-  } else {
-    let profile, identity;
-    try {
-      profile = await (deps.resolveProfile ?? resolveAgentProfile)({ cwd: deps.cwd ?? process.cwd(), env, explicitProfile: deps.profile ?? null });
-      identity = await (deps.readIdentity ?? readProfileIdentity)(profile.name);
-    } catch (error) {
-      return { allowed: false, message: `bb-pw: profile verification failed (${error.message}). Run botbuddy profile setup or set BB_PW_NO_LOCK=1 for local-only work.` };
+  let coordinator = deps.coordinator ?? null;
+  if (!coordinator) {
+    let token = sessionToken;
+    if (!token) {
+      try {
+        const binding = await (deps.resolveBinding ?? resolveAgentBinding)({ cwd: deps.cwd ?? process.cwd(), env, explicitTenant: deps.tenant ?? null });
+        token = binding.token ?? null;
+      } catch { token = null; }
+    }
+    if (!token) {
+      return { allowed: false, message: "bb-pw: no BotBuddy credential — export $BOTBUDDY_AGENT_KEY (from register_agent) or your .mcp.json key ($BOTBUDDY_MCP_KEY), or set BB_PW_NO_LOCK=1 for local-only work." };
     }
-    coordinator = deps.coordinator ?? createProfileCoordinator({ profile, identity, fetchImpl: deps.fetch });
-    if (!profile.token || !identity || identity.tenant !== profile.tenant || coordinator.kind !== "profile") return { allowed: false, message: "bb-pw: profile identity is missing or tenant-mismatched. Run botbuddy profile setup or set BB_PW_NO_LOCK=1 for local-only work." };
-    // The operator's own holder identities: the tenant-bound profile agent OR the
-    // arming session agent (--session-id / $BOTBUDDY_SESSION_ID / local register_agent
-    // id). A foreign operator's agent is in none of these, so the gate stays a real
-    // refusal (AC-3).
-    selfAgentIds = new Set([identity.agentId, sessionAgentId, registeredAgentId].filter(Boolean));
-    callerId = identity.agentId;
+    coordinator = createSessionTokenCoordinator({ token, fetchImpl: deps.fetch });
   }
+  if (coordinator.kind === "unverified") return { allowed: false, message: "bb-pw: BotBuddy credential is unusable. Re-register the agent, or set BB_PW_NO_LOCK=1 for local-only work." };
+  const selfAgentIds = new Set([sessionAgentId, registeredAgentId, coordinator.agentId].filter(Boolean));
+  const callerId = coordinator.agentId ?? sessionAgentId ?? registeredAgentId ?? "botbuddy";
   const laneName = `playwright_lane:${host}:${lane}`;
   try {
     const status = await coordinator.status({ host, slot: lane });
@@ -105,7 +105,7 @@ async function runPwInner(argv, deps = {}) {
   // session identity alongside --session-id, so a token-armed session need not
   // pass an id. Holder matching still rides on the server's owner_is_caller and
   // the resolved agent ids (gate()).
-  while (args[0] === "--profile" || args[0] === "--session-id" || args[0] === "--session-token") { const flag = args[0]; if (!args[1]) { stderr.write(`bb-pw: ${flag} needs a value\n`); return 2; } deps = flag === "--profile" ? { ...deps, profile: args[1] } : flag === "--session-token" ? { ...deps, sessionToken: args[1] } : { ...deps, sessionId: args[1] }; args = args.slice(2); }
+  while (args[0] === "--tenant" || args[0] === "--session-id" || args[0] === "--session-token") { const flag = args[0]; if (!args[1]) { stderr.write(`bb-pw: ${flag} needs a value\n`); return 2; } deps = flag === "--tenant" ? { ...deps, tenant: args[1] } : flag === "--session-token" ? { ...deps, sessionToken: args[1] } : { ...deps, sessionId: args[1] }; args = args.slice(2); }
   let plan; try { plan = planInvocation(args, env); } catch (error) { stderr.write(`${error.message}\n`); return 2; }
   const { spawnExec, socketRun } = deps.daemon ?? await import("./daemon.mjs");
   if (plan.scope === "global") { if (plan.mode === "reap") { await (deps.reap ?? (await import("./reap.mjs")).reap)({ env, stdout }); return 0; } if (env.BB_PW_NO_LOCK !== "1") { stderr.write("bb-pw: close-all and kill-all require BB_PW_NO_LOCK=1 because they can affect lanes you do not own.\n"); return 3; } return spawnExec(plan, env); }

package/src/stack.mjs

@@ -353,8 +353,8 @@ export function parseSupabaseStatus(text) {
 // ── runtime (network / process) ──────────────────────────────────────────────
 
 // BOT-1520: source both auth headers from the Keychain — the owner OAuth token
-// (`botbuddy login`) is preferred, the tenant-bound agent key
-// (`botbuddy profile setup`) is the fallback. No plaintext config.json secret.
+// (`botbuddy login`) is preferred, the tenant-bound MCP key
+// (`botbuddy mcp setup`, BOT-1608) is the fallback. No plaintext config.json secret.
 export async function stackAuthHeader() {
   const agentKey = await resolveAgentKey();
   const owner = await resolveOwnerToken({ getConfig });
@@ -1132,7 +1132,7 @@ 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" };
+    if (!auth) return { exitCode: EXIT.AUTH, outcome: "error", error: "not authenticated — run botbuddy login (agents: botbuddy mcp setup)" };
     // 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.

package/src/wait-profile.mjs

@@ -1,116 +1,165 @@
 import { readFile } from "node:fs/promises";
 import { dirname, join, parse } from "node:path";
-import { readProfileCredential } from "./agent-credential-store.mjs";
+import {
+  readKeychainSecret,
+  keychainAvailable,
+  DEFAULT_MCP_ENV_VAR,
+} from "./agent-credential-store.mjs";
+import { getConfig } from "./config.mjs";
 
-// Public CLI profiles remain tenant-bound machine-principal contracts.
-export const PROFILE_FILE = ".botbuddy-agent.json";
+// BOT-1608: the committed repo file that binds a worktree to a tenant and names
+// the env/Keychain var carrying its MCP credential — DATA, not an indirection
+// through a hard-coded profile name (the retired PROFILES map). It co-locates
+// with `.mcp.json`, which already declares the tenant via `?tenant=`.
+export const AGENT_BINDING_FILE = ".botbuddy-agent.json";
 
-const PROFILES = Object.freeze({
-  "botbuddy-dev": Object.freeze({
-    tenant: "botbuddy",
-    tokenEnv: "BOTBUDDY_BB_AGENT_KEY",
-  }),
-  "supplyguard-dev": Object.freeze({
-    tenant: "supply-guard",
-    tokenEnv: "BOTBUDDY_SG_AGENT_KEY",
-  }),
-});
+// Same slug shape the server accepts on `?tenant=`, and a shell env-var name.
+const TENANT_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const ENV_VAR_RE = /^[A-Z][A-Z0-9_]*$/;
 
-export function getAgentProfile(name) {
-  return PROFILES[name] ?? null;
-}
-
-// BOT-1593: when no profile is named (no --profile, no .botbuddy-agent.json) but
-// EXACTLY ONE supported profile's credential env var is populated, that slot is the
-// unambiguous profile. Used only by best-effort setup-error telemetry to attribute a
-// `profile_required` failure that still has a usable env bearer — never for the wait
-// itself. Returns the profile name, or null when zero or more than one slot is set
-// (ambiguous → no attribution). Reads env only; never touches the Keychain.
-export function findEnvProfile(env = process.env) {
-  const populated = Object.entries(PROFILES).filter(
-    ([, { tokenEnv }]) => typeof env[tokenEnv] === "string" && env[tokenEnv].length > 0,
-  );
-  return populated.length === 1 ? populated[0][0] : null;
+// Parse a `.botbuddy-agent.json` body into { tenant, mcpEnv }. Fails CLOSED on a
+// malformed file and on the retired `{ profile }` shape — the profile→tenant map
+// is exactly what BOT-1608 deletes, so a `{ profile }` file cannot be migrated
+// without re-introducing it. The error names the new shape (a one-time edit).
+export function parseAgentBinding(raw) {
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch {
+    const err = new Error(`${AGENT_BINDING_FILE} is not valid JSON`);
+    err.code = "invalid_binding";
+    throw err;
+  }
+  if (typeof config?.profile === "string" && config?.tenant == null) {
+    const err = new Error(
+      `${AGENT_BINDING_FILE} uses the retired { "profile" } shape — replace it with `
+        + `{ "schema_version": 1, "tenant": "<slug>", "mcp_env": "${DEFAULT_MCP_ENV_VAR}" } (BOT-1608)`,
+    );
+    err.code = "binding_migration_required";
+    throw err;
+  }
+  if (config?.schema_version !== 1 || typeof config?.tenant !== "string" || !TENANT_SLUG_RE.test(config.tenant)) {
+    const err = new Error(`${AGENT_BINDING_FILE} must declare schema_version 1 and a lowercase tenant slug`);
+    err.code = "invalid_binding";
+    throw err;
+  }
+  let mcpEnv = DEFAULT_MCP_ENV_VAR;
+  if (config.mcp_env != null) {
+    if (typeof config.mcp_env !== "string" || !ENV_VAR_RE.test(config.mcp_env)) {
+      const err = new Error(`${AGENT_BINDING_FILE} mcp_env must be an UPPER_SNAKE_CASE variable name`);
+      err.code = "invalid_binding";
+      throw err;
+    }
+    mcpEnv = config.mcp_env;
+  }
+  return { tenant: config.tenant, mcpEnv };
 }
 
-export async function findProfileName(cwd) {
+// Read the committed `.botbuddy-agent.json`, walking up from cwd to the fs root.
+// Returns { tenant, mcpEnv } or null when no file exists anywhere above cwd; a
+// malformed / retired-shape file throws (see parseAgentBinding).
+export async function readAgentBinding(cwd = process.cwd()) {
   let dir = cwd;
   const root = parse(dir).root;
   while (true) {
+    let raw = null;
     try {
-      const raw = await readFile(join(dir, PROFILE_FILE), "utf8");
-      const config = JSON.parse(raw);
-      if (config?.schema_version !== 1 || typeof config?.profile !== "string") {
-        throw new Error(`${PROFILE_FILE} must contain schema_version 1 and a profile`);
-      }
-      return config.profile;
+      raw = await readFile(join(dir, AGENT_BINDING_FILE), "utf8");
     } catch (err) {
       if (err?.code !== "ENOENT") throw err;
     }
+    if (raw != null) return parseAgentBinding(raw);
     if (dir === root) return null;
     dir = dirname(dir);
   }
 }
 
-export async function resolveAgentProfile({
+// The tenants the current login credential can reach (from `botbuddy login`),
+// used for the "sole configured tenant" resolution rung. Best-effort: an empty
+// list (config not loaded, or a tenant-sealed token) simply skips that rung.
+function defaultConfiguredTenants() {
+  const cfg = getConfig() ?? {};
+  return Array.isArray(cfg.token_tenants) ? cfg.token_tenants.filter((t) => typeof t === "string" && t) : [];
+}
+
+// The credential for a resolved binding: the mcp_env var (loaded from the shell,
+// or the Keychain item whose service name IS that var). Never reads the Keychain
+// when it is unavailable (BOTBUDDY_NO_KEYCHAIN / non-darwin) — the env var is the
+// sole source there.
+async function defaultReadCredential(mcpEnv, env) {
+  const fromEnv = typeof env[mcpEnv] === "string" && env[mcpEnv] ? env[mcpEnv] : null;
+  if (fromEnv) return fromEnv;
+  if (!keychainAvailable()) return null;
+  return readKeychainSecret(mcpEnv);
+}
+
+// BOT-1604 AC9 / BOT-1608 resolution order for in-repo agent-context commands
+// (`bb-wait`, `botbuddy pw`, …): explicit `--tenant`/`--env` → the committed
+// `.botbuddy-agent.json` → the sole configured login tenant if exactly one →
+// else FAIL CLOSED with an actionable error. Never a silent default.
+//
+// Returns { tenant, tokenEnv, token } — tokenEnv is the resolved mcp_env var and
+// token the credential read from it (or an explicit override). `token` may be
+// null (no credential exported yet); the caller decides whether that is fatal.
+export async function resolveAgentBinding({
   cwd = process.cwd(),
   env = process.env,
-  explicitProfile = null,
+  explicitTenant = null,
+  explicitEnv = null,
   explicitToken = null,
-  readCredential = readProfileCredential,
+  readBinding = readAgentBinding,
+  configuredTenants = defaultConfiguredTenants,
+  readCredential = defaultReadCredential,
 } = {}) {
-  const name = explicitProfile || await findProfileName(cwd);
-  if (!name) {
+  let binding = null;
+  let bindingError = null;
+  try {
+    binding = await readBinding(cwd);
+  } catch (err) {
+    bindingError = err;
+  }
+
+  let tenant = explicitTenant || binding?.tenant || null;
+  // A malformed/retired committed file must NOT be silently bypassed by the
+  // sole-configured-tenant fallback (Codex P2): when readBinding threw and no
+  // explicit --tenant overrode it, skip the fallback so bindingError surfaces
+  // below. An explicit --tenant is still an intentional override.
+  if (!tenant && !bindingError) {
+    const tenants = configuredTenants();
+    if (tenants.length === 1) tenant = tenants[0];
+  }
+  if (!tenant) {
+    // A malformed committed file is the more specific failure — surface it so the
+    // operator fixes the file rather than chasing a generic "no binding" message.
+    if (bindingError) throw bindingError;
     const err = new Error(
-      `no BotBuddy agent profile found (add ${PROFILE_FILE} or pass --profile)`,
+      `no BotBuddy tenant resolved — commit a ${AGENT_BINDING_FILE} `
+        + `({"schema_version":1,"tenant":"<slug>","mcp_env":"${DEFAULT_MCP_ENV_VAR}"}) `
+        + "or pass --tenant <slug>",
     );
-    err.code = "profile_required";
+    err.code = "agent_binding_required";
     throw err;
   }
-  const profile = getAgentProfile(name);
-  if (!profile) {
-    const err = new Error(`unknown BotBuddy agent profile '${name}'`);
-    err.code = "unknown_profile";
-    throw err;
-  }
-  return {
-    name,
-    tenant: profile.tenant,
-    tokenEnv: profile.tokenEnv,
-    // A freshly bootstrapped credential must take effect even if a calling shell
-    // still has a stale profile variable. `--token` remains the explicit escape
-    // hatch for a one-off credential.
-    token: explicitToken || await readCredential(name) || env[profile.tokenEnv] || null,
-  };
+
+  const tokenEnv = explicitEnv || binding?.mcpEnv || DEFAULT_MCP_ENV_VAR;
+  const token = explicitToken || (await readCredential(tokenEnv, env)) || null;
+  return { tenant, tokenEnv, token };
 }
 
-export function withPrincipalReceipt(receipt, profile, registration = {}) {
-  if (!profile) {
-    // BOT-1572: a session-token wait has no profile, but the receipt must still
-    // carry principal.session_id / agent_id / tenant_id derived by the relay from
-    // the token. Only attach when the relay actually echoed a session identity.
-    if (registration.sessionId || registration.agentId || registration.sessionTenant != null) {
-      return {
-        ...receipt,
-        principal: {
-          profile: null,
-          tenant_id: registration.sessionTenant ?? null,
-          agent_id: registration.agentId ?? null,
-          session_id: registration.sessionId ?? null,
-          session_agent_id: registration.sessionAgentId ?? null,
-        },
-      };
-    }
-    return receipt;
-  }
+// Attach the resolved principal to a wait receipt. With the profile bridge gone
+// there is no profile name — the tenant comes from the binding (or the relay's
+// session identity). Only attached when a principal identity is known.
+export function withPrincipalReceipt(receipt, binding, registration = {}) {
+  const hasSession =
+    registration.sessionId || registration.agentId || registration.sessionTenant != null;
+  if (!binding && !hasSession) return receipt;
   return {
     ...receipt,
     principal: {
-      profile: profile.name,
-      tenant_id: registration.sessionTenant ?? profile.tenant,
+      tenant_id: registration.sessionTenant ?? binding?.tenant ?? null,
       agent_id: registration.agentId ?? null,
       // BOT-1467: the arming session's agent, when the relay attributed the wait
-      // to it instead of the profile agent (null for an ordinary profile wait).
+      // to it (null for an ordinary binding wait).
       session_id: registration.sessionId ?? null,
       session_agent_id: registration.sessionAgentId ?? null,
     },