@botbuddy/cli 1.60.6 → 1.60.8

package/src/staging-pool/errors.mjs

@@ -3,15 +3,19 @@
 // command and the doc section. `bb help symptom <code>` prints the same entry.
 //
 // Node-stdlib-only and self-contained (the installed job copies this directory).
-// Templates take only non-secret values (lane, persona alias, paths, labels);
-// a missing value renders as a <placeholder>, never as an empty string.
+// Templates take only non-secret values (lane, persona alias, paths, labels).
+// A real refusal (`{ real: true }`) never prints a <placeholder>: a missing value
+// in prose becomes plain words, and a `next` command that needs a value it does
+// not have falls back to the command that finds it (e.g. `botbuddy call whoami` for
+// the tenant). Only
+// `bb help symptom` (the reference view) shows <placeholders>.
 
 export const DOC_URL = "https://github.com/bot-buddy/botbuddy-webapp/blob/main/docs/agent-staging-acceptance-mfa.md";
 
 // Heading anchors in DOC_URL (checked by errors.test.mjs against the doc).
 export const DOC_SECTIONS = Object.freeze({
   overview: "staging-session-pool-bot-2084",
-  configure: "configure-a-repository",
+  configure: "register-a-tenants-pool",
   install: "install-update-remove-human-only",
   take: "take-a-session-agent",
   close: "close-and-the-residual-window",
@@ -39,15 +43,15 @@ export const ERROR_CODES = Object.freeze({
   auth_requires_lane_lock: entry("agent", "take",
     "bb pw auth needs a lock-gated lane, and this run is unlocked.",
     "BB_PW_NO_LOCK=1 is set in this shell.",
-    `bb locks -m --lane {lane} --ticket <ticket> && env -u BB_PW_NO_LOCK ${AUTH}`),
+    `bb locks -m --lane {lane}{ticketFlag} && env -u BB_PW_NO_LOCK ${AUTH}`),
   lane_not_claimed: entry("agent", "take",
     "The lane lock is not held by this agent session.",
     "The lane was never claimed, its lock expired, or another agent holds it.",
-    `bb locks -m --lane {lane} --ticket <ticket> && ${AUTH}`),
+    `bb locks -m --lane {lane}{ticketFlag} && ${AUTH}`),
   exact_lane_holder_required: entry("agent", "take",
     "The lane lock is held by another agent session of your owner, not by this session.",
     "The lane was claimed from a different session or sub-agent; auth needs the exact holder.",
-    `bb locks -m --lane {lane} --ticket <ticket>   # from THIS session, then: ${AUTH}`),
+    `bb locks -m --lane {lane}{ticketFlag}   # from THIS session, then: ${AUTH}`),
   persona_not_allowlisted: entry("agent", "take",
     "Persona \"{persona}\" is not one of this repository's staging_session_pool personas.",
     "A typo, or an email where the alias is expected. Allowed aliases: {allowed}.",
@@ -64,10 +68,10 @@ export const ERROR_CODES = Object.freeze({
     "Lane {lane} uses a persistent browser profile, which would write the session to disk.",
     "The lane was opened with --persistent or --profile.",
     `${REOPEN} && ${AUTH}   # no --persistent / --profile`),
-  pool_not_configured: entry("agent", "configure",
-    "This directory's repository declares no staging_session_pool, so there is no pool to take from.",
-    "The command ran outside the repository checkout, or the repository has not opted in.",
-    "cd <repository checkout> && {retry}"),
+  pool_ambiguous: entry("agent", "take",
+    "Several staging session pools match ({poolIds}), so the command does not guess.",
+    "More than one pool is installed (or registered for the tenant) and none was named.",
+    "{retryWithPool}"),
 
   // ── bb pw … auth: install into the lane (agent retries once, then reports)
   session_install_failed: entry("agent", "take",
@@ -139,15 +143,15 @@ export const ERROR_CODES = Object.freeze({
   mint_backing_off: entry("human", "repair",
     "Staging sign-in for {persona} keeps failing, so the job is backing off.",
     "The last mint_failed line in {log} names it: password_rejected or no_verified_totp_factor = seed drift; password_source_* = the password env file; totp_source_failed = the botbuddy CLI login.",
-    "grep mint_failed {log} | tail -1   # then the matching code: bb help symptom <code>"),
+    "grep mint_failed {log} | tail -1   # then run bb help symptom with the code that line names"),
   last_tick_failed: entry("human", "repair",
-    "The pool job's last tick could not sign {persona} in.",
+    "The pool job's last tick had sign-in (mint) failures.",
     "The last mint_failed line in {log} names the cause.",
     "grep mint_failed {log} | tail -1   # repair that code, then: {tickCommand}"),
   ticks_failing: entry("human", "repair",
     "Pool ticks run but none has succeeded for 3+ intervals.",
     "A persistent mint failure; {log} names it.",
-    "grep mint_failed {log} | tail -1   # then: bb help symptom <code>"),
+    "grep mint_failed {log} | tail -1   # then run bb help symptom with the code that line names"),
   persona_below_target: entry("human", "repair",
     "The pool has been below its configured size for {persona} for 3+ ticks.",
     "Agents take sessions faster than the job refills them, or mints are partly failing ({log}).",
@@ -161,8 +165,8 @@ export const ERROR_CODES = Object.freeze({
     "It was edited by hand, or an incompatible CLI wrote it.",
     INSTALL + "   # rewrites it from the binding; or fix the named field in {configPath}"),
   pool_not_installed: entry("human", "install",
-    "The pool job is not installed, so it cannot tick or mint.",
-    "The one-time install has not been run on this Mac.",
+    "No staging session pool is installed on this Mac{poolSuffix}, so {consequence}.",
+    "The one-time install has not been run here (pools install from the BotBuddy control plane with --tenant).",
     INSTALL),
   pool_target_mismatch: entry("human", "repair",
     "The pool home belongs to a different staging target than the repository binding now names.",
@@ -180,26 +184,44 @@ export const ERROR_CODES = Object.freeze({
   // ── who may run what
   agent_context: entry("human", "install",
     "This bb staging-pool command is human-only and this shell is inside an agent session ({markers}).",
-    `It ran from a Claude or Codex terminal. ${HUMAN_ONLY}`,
-    "From Terminal.app or iTerm: cd {checkout} && bb staging-pool {command}"),
+    `It ran from a Claude or Codex terminal; run it from Terminal.app or iTerm instead. ${HUMAN_ONLY}`,
+    "bb staging-pool {command}"),
   agent_context_unknown: entry("human", "install",
     "bb staging-pool could not establish that this is not an agent session (ps failed), so it refused.",
-    `/bin/ps is unavailable or restricted in this shell. ${HUMAN_ONLY}`,
-    "From Terminal.app or iTerm: cd {checkout} && bb staging-pool {command}"),
+    `/bin/ps is unavailable or restricted in this shell; run it from Terminal.app or iTerm instead. ${HUMAN_ONLY}`,
+    "bb staging-pool {command}"),
 
-  // ── configuration (repository binding and installed config)
+  // ── the control-plane registry (BOT-2648)
+  tenant_required: entry("human", "install",
+    "bb staging-pool install needs the tenant whose registered pool to install.",
+    "--tenant was not given; pool bindings are registered per tenant in the BotBuddy control plane.",
+    INSTALL),
+  tenant_pool_not_registered: entry("human", "configure",
+    "Tenant {tenant} has no registered staging session pool{poolSuffix}.",
+    "The tenant's staging seed job has not registered one yet (register_staging_pool), or the pool id is wrong.",
+    "botbuddy call get_staging_pool --pin {tenant}   # lists what is registered; the tenant's staging seed job registers it"),
+  pool_registry_unavailable: entry("human", "install",
+    "The BotBuddy control plane did not return the tenant's pool binding.",
+    "botbuddy is signed out on this Mac, the tenant pin is not one of your memberships, or BotBuddy is unreachable.",
+    "botbuddy login && " + INSTALL),
+  pool_registration_refused: entry("human", "configure",
+    "The registered pool binding does not pass this CLI's checks (see detail), so nothing was installed.",
+    "The registration is malformed, or it uses a newer schema than this @botbuddy/cli understands.",
+    "npm i -g @botbuddy/cli@latest && " + INSTALL + "   # if it still refuses, fix the tenant's registration"),
+
+  // ── configuration (the registered binding and the installed config)
   config_missing: entry("human", "configure",
     "A required staging_session_pool value is missing (see detail).",
-    "The repository binding or installed config lacks a field.",
-    INSTALL + "   # after fixing .botbuddy-agent.json staging_session_pool"),
+    "The registered binding or installed config lacks a field.",
+    INSTALL),
   pool_binding_invalid: entry("human", "configure",
-    "The repository's .botbuddy-agent.json staging_session_pool is invalid (see detail).",
-    "A committed edit broke a field; the message names it.",
-    "git log -p -1 -- .botbuddy-agent.json   # fix the named field in a PR, then: bb staging-pool status"),
+    "The registered staging_session_pool binding is invalid (see detail).",
+    "The tenant's registration broke a field; the message names it.",
+    "botbuddy call get_staging_pool --pin {tenant}   # fix the named field in the tenant's registration, then: " + INSTALL),
   origin_not_allowed: entry("human", "configure",
     "The binding's app origin or Supabase URL is not an allowed staging target (see detail).",
-    "It is http, loopback, a path rather than a bare origin, or a production origin.",
-    "git log -p -1 -- .botbuddy-agent.json   # point app_origin / supabase_url at staging in a PR"),
+    "It is http, loopback, a path rather than a bare origin, or a production origin; this CLI refuses it whatever the control plane holds.",
+    "botbuddy call get_staging_pool --pin {tenant}   # point app_origin / supabase_url at staging in the tenant's registration"),
   persona_not_allowed: entry("agent", "take",
     "Persona \"{persona}\" is not an allowlisted seeded persona of this pool.",
     "A typo, or a persona the binding does not list. Allowed: {allowed}.",
@@ -277,7 +299,7 @@ export const ERROR_CODES = Object.freeze({
   persona_mismatch: entry("human", "repair",
     "MFA verify returned a session for a different user.",
     "The binding's persona email does not match the seeded user.",
-    "git log -p -1 -- .botbuddy-agent.json   # check personas, then: bb staging-pool mint-one --persona {persona}"),
+    "botbuddy call get_staging_pool --pin {tenant}   # check the registered personas, then: bb staging-pool mint-one --persona {persona}"),
 
   unexpected_error: entry("agent", "codes",
     "bb staging-pool failed unexpectedly (see detail).",
@@ -285,27 +307,63 @@ export const ERROR_CODES = Object.freeze({
     "bb staging-pool status   # once; report this code, the detail and the CLI version (bb version)", "report_blocker"),
 });
 
+// Codes only `bb pw … auth` can raise; every other code can come from `bb staging-pool`.
+export const AUTH_ONLY_CODES = Object.freeze(new Set([
+  "auth_requires_staging_environment", "auth_requires_lane_lock", "lane_not_claimed", "exact_lane_holder_required",
+  "persona_not_allowlisted", "lane_browser_not_open", "browser_session_not_staging", "persistent_profile_refused",
+  "session_install_failed", "staging_session_cleanup_pending", "session_not_aal2", "session_expired",
+  "session_persona_mismatch", "slot_state_invalid", "slot_state_unreadable", "daemon_node_unsupported",
+  "daemon_run_failed", "daemon_result_missing", "daemon_result_invalid", "pool_take_failed", "pool_empty",
+]));
+
+// `bb staging-pool` subcommands only a human runs. A refusal from one names
+// Human (Jono) whatever the code, and prints no Agent guidance.
+export const HUMAN_ONLY_COMMANDS = Object.freeze(new Set(["install", "uninstall", "tick", "mint-one"]));
+
+// With no tenant known, a remedy names the command that reports it (BOT-2648).
+export const FIND_TENANT_NEXT = 'botbuddy call whoami   # its tenant_id is your --tenant; then: bb staging-pool install --tenant (that slug) --botbuddy-bin "$(command -v botbuddy)"';
+export const installLine = (tenant, poolId) => `bb staging-pool install --tenant ${tenant}${poolId ? ` --pool ${poolId}` : ""} --botbuddy-bin "$(command -v botbuddy)"`;
+
 // Vars that are already whole command lines; every other var is a single shell word.
-const COMMAND_VARS = new Set(["installCommand", "tickCommand", "command", "retry"]);
+const COMMAND_VARS = new Set(["installCommand", "tickCommand", "command", "retry", "retryWithPool", "ticketFlag"]);
+// Vars where an empty string is a real value (no flag), not a missing one.
+const OPTIONAL_VARS = new Set(["ticketFlag"]);
 const SHELL_SAFE = /^[A-Za-z0-9_./:@,=~+-]+$/;
 // A <placeholder> stays as written: the reader replaces it.
 const shellWord = (value) => (SHELL_SAFE.test(value) || /^<[^<>]+>$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`);
 
-// In a `next` command a caller-supplied value (a typed persona, a checkout path
-// with spaces) is shell-quoted, so the line stays one safe copy-paste.
-function fill(template, vars, { shell = false } = {}) {
+// What a missing value reads as in prose (real refusals only).
+const DESCRIBED = Object.freeze({
+  persona: "the persona", lane: "the lane", log: "the pool log", configPath: "the installed pool config",
+  label: "the launchd job", envFile: "the persona password file", markers: "agent markers",
+  cwd: "This directory", consequence: "there is no pool to act on", command: "this command",
+  tenant: "your tenant", poolIds: "several pools", poolSuffix: "", allowed: "the binding's personas", firstAllowed: "a listed persona",
+});
+
+const isMissing = (key, value) => value === undefined || value === null || (value === "" && !OPTIONAL_VARS.has(key)) || (Array.isArray(value) && value.length === 0);
+
+// In a `next` command a caller-supplied value (a typed persona, a path with
+// spaces) is shell-quoted, so the line stays one safe copy-paste.
+function fill(template, vars, { shell = false, missing = null, describe = false } = {}) {
   return String(template).replace(/\{([A-Za-z]+)\}/g, (_, key) => {
     const value = vars?.[key];
-    if (Array.isArray(value)) return value.length ? value.map((item) => (shell ? shellWord(String(item)) : String(item))).join(", ") : `<${key}>`;
-    if (value === undefined || value === null || value === "") return `<${key}>`;
+    if (isMissing(key, value)) {
+      missing?.add(key);
+      return describe ? (DESCRIBED[key] ?? "it") : `<${key}>`;
+    }
+    if (Array.isArray(value)) return value.map((item) => (shell ? shellWord(String(item)) : String(item))).join(", ");
     return shell && !COMMAND_VARS.has(key) ? shellWord(String(value)) : String(value);
   });
 }
 
 export const isKnownCode = (code) => Object.hasOwn(ERROR_CODES, String(code ?? ""));
 
-/** The guidance for one code, interpolated with non-secret vars. */
-export function guidance(code, vars = {}) {
+/**
+ * The guidance for one code, interpolated with non-secret vars.
+ *   real   a refusal someone will act on: no <placeholder> is ever printed.
+ *   actor  "human" for a human-only subcommand, whatever the code's default.
+ */
+export function guidance(code, vars = {}, { real = false, actor = null } = {}) {
   const known = isKnownCode(code);
   const spec = known ? ERROR_CODES[code] : ERROR_CODES.unexpected_error;
   const allowed = Array.isArray(vars.allowed) ? vars.allowed : vars.allowed ? [vars.allowed] : [];
@@ -313,20 +371,37 @@ export function guidance(code, vars = {}) {
     ...vars,
     allowed,
     firstAllowed: vars.firstAllowed ?? allowed[0],
-    // Without a resolved pool these still read as runnable commands from the checkout.
+    ticketFlag: vars.ticketFlag ?? (real ? "" : " --ticket <ticket>"),
+    poolSuffix: vars.poolSuffix ?? (vars.poolId ? ` (${vars.poolId})` : ""),
     tickCommand: vars.tickCommand ?? "bb staging-pool tick",
-    installCommand: vars.installCommand ?? `cd ${vars.checkout ? shellWord(String(vars.checkout)) : "<checkout>"} && bb staging-pool install --botbuddy-bin "$(command -v botbuddy)"`,
+    // Install reads the control plane, so it needs only the tenant: no checkout, no cwd.
+    installCommand: vars.installCommand ?? (vars.tenant ? installLine(shellWord(String(vars.tenant)), vars.installPool ?? null) : (real ? undefined : installLine("<tenant>"))),
   };
-  // What a "go to the right checkout" step re-runs: auth by default.
+  // What a refusal re-runs: auth by default (the consumer), the subcommand otherwise.
   filled.retry = vars.retry ?? fill(AUTH, filled, { shell: true });
+  filled.retryWithPool = vars.retryWithPool ?? (real ? undefined : `${filled.retry} --pool <pool_id>`);
+  let next;
+  if (real) {
+    const missing = new Set();
+    next = fill(spec.next, filled, { shell: true, missing });
+    if (missing.size) {
+      // A value only the tenant or a resolved pool knows is missing: give the
+      // command that finds the tenant, or re-run the subcommand to get the
+      // specific refusal with real values. Never a <placeholder>.
+      next = missing.has("tenant") || missing.has("installCommand") ? FIND_TENANT_NEXT : filled.retry;
+    }
+  } else {
+    next = fill(spec.next, filled, { shell: true });
+  }
+  const finalActor = actor ?? spec.actor;
   return {
     code: known ? code : String(code ?? "unexpected_error"),
-    message: fill(spec.message, filled),
-    cause: fill(spec.cause, filled),
-    actor: spec.actor,
-    actor_label: ACTOR_LABELS[spec.actor],
-    next: fill(spec.next, filled, { shell: true }),
-    agent_action: spec.agentAction,
+    message: fill(spec.message, filled, { describe: real }),
+    cause: fill(spec.cause, filled, { describe: real }),
+    actor: finalActor,
+    actor_label: ACTOR_LABELS[finalActor],
+    next,
+    agent_action: finalActor === "human" ? "report_blocker" : spec.agentAction,
     doc: `${DOC_URL}#${DOC_SECTIONS[spec.doc]}`,
     help: `bb help symptom ${known ? code : "unexpected_error"}`,
   };
@@ -339,13 +414,13 @@ export function remedyLine(g) {
 }
 
 /** Plain-text block for stderr. */
-export function formatGuidance(g, { prefix = "bb staging-pool" } = {}) {
+export function formatGuidance(g, { prefix = "bb staging-pool", agentLine = true } = {}) {
   const lines = [
     `${prefix}: ${g.message} [${g.code}]`,
     `  Likely cause: ${g.cause}`,
     `  Next (${g.actor_label}${g.actor === "human" ? ", from Terminal.app or iTerm" : ""}): ${g.next}`,
   ];
-  if (g.actor === "human") lines.push("  Agent: do not run that. Report this code and the next step to the human once, then stop.");
+  if (g.actor === "human" && agentLine) lines.push("  Agent: do not run that. Report this code and the next step to the human once, then stop.");
   lines.push(`  Docs: ${g.doc}`, `  Explain: ${g.help}`);
   return lines.join("\n");
 }

package/src/staging-pool/health.mjs

@@ -15,7 +15,7 @@ export const HEALTH_REASON_CODES = Object.freeze([
 export function healthReasons({ label, log, installCommand, docs, configPath, tickCommand, checkout, persona }) {
   const vars = { label, log, installCommand, docs, configPath, tickCommand, checkout, persona };
   return Object.freeze(Object.fromEntries(HEALTH_REASON_CODES.map((code) => {
-    const g = guidance(code, vars);
+    const g = guidance(code, vars, { real: true });
     return [code, Object.freeze({ agentAction: g.agent_action, remedy: remedyLine(g), vars })];
   })));
 }
@@ -35,7 +35,7 @@ export function assessPoolHealth({ status, personas, intervalSeconds, nowMs, job
     const record = { ok: false, reason, agentAction, ...extra };
     if (vars) {
       // Re-rendered with the persona this assessment is about.
-      const g = guidance(reason, { ...vars, persona: extra.persona ?? requestedPersona ?? vars.persona });
+      const g = guidance(reason, { ...vars, persona: extra.persona ?? requestedPersona ?? vars.persona }, { real: true });
       remedy = remedyLine(g);
       Object.assign(record, { message: g.message, cause: g.cause, actor: g.actor_label, next: g.next, doc: g.doc, help: g.help });
     }

package/src/staging-pool/help.mjs

@@ -4,18 +4,23 @@ import { DOC_SECTIONS, DOC_URL } from "./errors.mjs";
 
 const doc = (section) => `${DOC_URL}#${DOC_SECTIONS[section]}`;
 
-export const BINDING_KEYS_HELP = `  .botbuddy-agent.json (committed, at the repository root) → staging_session_pool:
-    schema_version 1, pool_id, environment "staging", app_slug, adapter
-    "supabase-gotrue-totp", app_origin, supabase_url, publishable_key (public),
-    storage_key, production_origins, password_env_file, launchd_label, docs,
-    install_command, personas { <alias>: { email, password_env, default_count 0-4 } }.
-  No flag or environment variable can change the origin or add a persona.`;
+export const BINDING_KEYS_HELP = `  Registered per tenant in the BotBuddy control plane by the tenant's staging seed
+  job (register_staging_pool); read with
+  botbuddy call get_staging_pool --pin <tenant>. Keys: schema_version 1,
+    pool_id, environment "staging", app_slug, adapter "supabase-gotrue-totp",
+    app_origin, supabase_url, publishable_key (public), storage_key,
+    production_origins, password_env_file, launchd_label, docs,
+    personas { <alias>: { email, password_env, default_count 0-4 } }.
+  No secret is registered: each persona's password stays in password_env_file
+  (0600) on this Mac. Install refuses a production, http or loopback origin
+  whatever is registered. No repository checkout is read.`;
 
 export const PW_AUTH_HELP = `bb pw auth — sign a claimed browser lane in to staging as a seeded test persona (BOT-2084).
 
 USAGE
-  bb pw --environment staging <lane> auth --persona <alias>
-  (--environment and credential flags go BEFORE the lane; --persona goes after auth)
+  bb pw --environment staging <lane> auth --persona <alias> [--pool <pool_id>]
+  (--environment and credential flags go BEFORE the lane; --persona and --pool go
+  after auth; --pool only when several pools are installed)
 
 WHO RUNS IT
   Agents (and humans). It never types a password or one-time code: it installs a
@@ -23,10 +28,10 @@ WHO RUNS IT
   (bb staging-pool --help).
 
 BEFORE YOU RUN IT
-  1. You are in a checkout of a repository whose .botbuddy-agent.json declares
-     staging_session_pool (check: bb staging-pool status).
-  2. The human has installed the pool on this Mac
-     (check: bb staging-pool status --check prints "ok": true).
+  1. The human has installed the tenant's pool on this Mac, from the BotBuddy
+     control plane (check: bb staging-pool status --check prints "ok": true).
+     Any working directory works; no repository checkout is needed.
+  2. With several pools installed, pass --pool (bb staging-pool status lists them).
   3. THIS agent session holds the lane lock, and the lane is open on staging and
      not persistent:
        bb locks -m --lane <lane> --ticket <ticket>
@@ -64,15 +69,16 @@ IF IT REFUSES
 export const STAGING_POOL_HELP = `bb staging-pool — the human-installed job that keeps signed-in staging sessions ready for agents.
 
 A launchd job on this Mac signs each allowlisted seeded persona in to the
-repository's staging app (password + TOTP via BotBuddy get_totp_code) every
+tenant's staging app (password + TOTP via BotBuddy get_totp_code) every
 5 minutes and keeps a few single-use sessions ready. Agents never sign in: they
 take a session with bb pw --environment staging <lane> auth --persona <alias>
 (bb pw auth --help).
 
-Run from the repository checkout: every command reads .botbuddy-agent.json there.
+Install reads the tenant's pool from the BotBuddy control plane, so every command
+runs from any directory. With several pools installed, name one with --pool <pool_id>.
 
 ANYONE (agents too) — read-only
-  status [--check] [--persona <alias>]
+  status [--check] [--persona <alias>] [--pool <pool_id>]
       Counts and last tick; never session material. --check prints one health
       reason with who acts and the next command (exit 5 when unhealthy).
       e.g. bb staging-pool status --check --persona staging-admin
@@ -86,11 +92,13 @@ ANYONE (agents too) — read-only
 
 HUMAN ONLY (Jono, from Terminal.app or iTerm) — refused inside a Claude or Codex session
   These sign in with the persona password or change the standing sessions.
-  install --botbuddy-bin <absolute path> [--interval <seconds>]
-      Copies the job to the pool home, writes its config and loads the launchd
-      job. Re-run after upgrading @botbuddy/cli; it keeps counts and interval.
-      e.g. cd <checkout> && bb staging-pool install --botbuddy-bin "$(command -v botbuddy)"
-  tick [--home <pool home>]
+  install --tenant <slug> [--pool <pool_id>] --botbuddy-bin <absolute path> [--interval <seconds>]
+      Reads the tenant's registered pool from the BotBuddy control plane, copies
+      the job to the pool home, writes its config and loads the launchd job. Run
+      it from any directory. Re-run after upgrading @botbuddy/cli; it keeps the
+      counts and interval. --pool is needed only when the tenant has several.
+      e.g. bb staging-pool install --tenant botbuddy --botbuddy-bin "$(command -v botbuddy)"
+  tick [--pool <pool_id>] [--home <pool home>]
       One refresh and refill pass now (what the job runs).
       e.g. bb staging-pool tick
   mint-one --persona <alias>
@@ -101,8 +109,9 @@ HUMAN ONLY (Jono, from Terminal.app or iTerm) — refused inside a Claude or Cod
       e.g. bb staging-pool uninstall
 
 PREREQUISITES (human, once per Mac)
-  - @botbuddy/cli installed globally, and botbuddy login done (the job calls
-    botbuddy call get_totp_code).
+  - @botbuddy/cli installed globally, and botbuddy login done as a member of the
+    tenant (install reads get_staging_pool; the job calls get_totp_code).
+  - The tenant's pool registered (its staging seed job does this).
   - The persona password in the binding's password_env_file, mode 0600, never
     committed (BotBuddy: ~/.config/botbuddy-web/.env.local.shared).
 

package/src/staging-pool/registry.mjs

@@ -0,0 +1,79 @@
+// BOT-2648: the pool binding comes from the BotBuddy control plane
+// (get_staging_pool), read through the human's `botbuddy` CLI login and
+// pinned to the tenant. This is the only source `bb staging-pool install` reads;
+// no command reads a staging_session_pool block from the working directory.
+// Node-stdlib-only and self-contained (bundled with the installed job).
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { AGENT_CONTEXT_ENV_MARKERS } from "./policy.mjs";
+
+export class RegistryError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = "RegistryError";
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const defaultExec = promisify(execFile);
+
+function childEnv(env) {
+  const next = { ...env };
+  for (const name of AGENT_CONTEXT_ENV_MARKERS) delete next[name];
+  return next;
+}
+
+/** The tenant's registered pools: [{ pool_id, binding, commit_sha, updated_at }]. */
+export async function fetchRegisteredPools({ exec = defaultExec, botbuddyBin, env = process.env, tenant, poolId = null }) {
+  if (!SLUG_RE.test(String(tenant ?? ""))) throw new RegistryError("tenant_required", "A --tenant slug is required.");
+  let stdout;
+  try {
+    ({ stdout } = await exec(botbuddyBin, ["call", "get_staging_pool", "--pin", tenant, "--json", JSON.stringify(poolId ? { pool_id: poolId } : {})], {
+      env: childEnv(env),
+      timeout: 60_000,
+      maxBuffer: 1024 * 1024,
+    }));
+  } catch (error) {
+    const stderr = String(error?.stderr ?? "").slice(0, 300);
+    throw new RegistryError("pool_registry_unavailable", `botbuddy call get_staging_pool failed (exit ${error?.code ?? "?"}): ${stderr}`, { tenant });
+  }
+  let body;
+  try {
+    body = JSON.parse(String(stdout));
+  } catch {
+    throw new RegistryError("pool_registry_unavailable", "get_staging_pool returned non-JSON output.", { tenant });
+  }
+  if (body?.ok === false) {
+    const code = body.code === "tenant_required" ? "tenant_required" : "pool_registry_unavailable";
+    throw new RegistryError(code, `get_staging_pool refused: ${String(body.code ?? "error")}`, { tenant });
+  }
+  if (!Array.isArray(body?.pools)) throw new RegistryError("pool_registry_unavailable", "get_staging_pool returned no pool list.", { tenant });
+  return body.pools.filter((row) => row && typeof row.pool_id === "string" && row.binding && typeof row.binding === "object");
+}
+
+/** Pick one pool: the named one, or the only one; otherwise a self-guiding refusal. */
+export function choosePool(pools, { tenant, poolId = null }) {
+  if (poolId) {
+    const match = pools.find((row) => row.pool_id === poolId);
+    if (!match) throw new RegistryError("tenant_pool_not_registered", `Tenant ${tenant} has no registered pool ${poolId}.`, { tenant, poolId, poolIds: pools.map((row) => row.pool_id) });
+    return match;
+  }
+  if (pools.length === 0) throw new RegistryError("tenant_pool_not_registered", `Tenant ${tenant} has no registered staging session pool.`, { tenant });
+  if (pools.length > 1) throw new RegistryError("pool_ambiguous", `Tenant ${tenant} has ${pools.length} pools.`, { tenant, poolIds: pools.map((row) => row.pool_id).sort() });
+  return pools[0];
+}
+
+/** Best effort: the tenant this botbuddy login resolves to (for a refusal's next step). */
+export async function whoamiTenant({ exec = defaultExec, botbuddyBin = "botbuddy", env = process.env } = {}) {
+  try {
+    const { stdout } = await exec(botbuddyBin, ["call", "whoami", "--json", "{}"], { env: childEnv(env), timeout: 15_000, maxBuffer: 256 * 1024 });
+    const tenant = JSON.parse(String(stdout))?.tenant_id;
+    return SLUG_RE.test(String(tenant ?? "")) ? tenant : null;
+  } catch {
+    return null;
+  }
+}