@botbuddy/cli 1.60.6 → 1.60.8

package/src/staging-pool/cli.mjs

@@ -11,20 +11,23 @@
 //
 // Agents take sessions only through `bb pw --environment staging <lane> auth`
 // (takeForLane below): a session is handed over by installing it into a claimed
-// lane, never as a reusable file path. The configuration is the repo's committed
-// `.botbuddy-agent.json` `staging_session_pool` binding; the installed job keeps a
-// validated snapshot. Node-stdlib-only and self-contained (install copies this
-// directory to <pool home>/app and the job runs that copy).
+// lane, never as a reusable file path. The configuration is the tenant's pool
+// binding registered in the BotBuddy control plane (BOT-2648): `install --tenant`
+// reads it through the botbuddy CLI from any directory and keeps a validated
+// snapshot in the pool home, which every other subcommand (and `bb pw … auth`)
+// reads. Nothing reads a binding from the working directory. Node-stdlib-only and
+// self-contained (install copies this directory to <pool home>/app and the job
+// runs that copy).
 
 import { execFile } from "node:child_process";
 import * as nodeFs from "node:fs/promises";
-import { readFileSync, realpathSync } from "node:fs";
+import { readFileSync, readdirSync, realpathSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
-import { BindingError, findPersona, readRepoPoolBinding } from "./binding.mjs";
+import { BindingError, findPersona, parsePoolBinding } from "./binding.mjs";
 import { ConfigError, DEFAULT_INTERVAL_SECONDS, buildInstalledConfig, poolHomePaths, readInstalledConfig, serialiseInstalledConfig } from "./config.mjs";
 import { assessPoolHealth, healthReasons } from "./health.mjs";
 import { buildLaunchAgentPlist, createLaunchctl } from "./launchd.mjs";
@@ -34,7 +37,8 @@ import { PoolEmptyError, createSessionPool } from "./pool.mjs";
 import { createGoTrueTotpSignIn } from "./signin-gotrue-totp.mjs";
 import { createRedactor } from "./state-file.mjs";
 import { createBotBuddyTotpProvider, probeBotBuddy } from "./totp-botbuddy.mjs";
-import { formatGuidance, guidance, isKnownCode, remedyLine } from "./errors.mjs";
+import { HUMAN_ONLY_COMMANDS, formatGuidance, guidance, installLine, isKnownCode, remedyLine } from "./errors.mjs";
+import { RegistryError, choosePool, fetchRegisteredPools, whoamiTenant } from "./registry.mjs";
 import { STAGING_POOL_HELP } from "./help.mjs";
 
 export const BUNDLE_FILES = Object.freeze([
@@ -49,12 +53,13 @@ export const BUNDLE_FILES = Object.freeze([
   "password-source.mjs",
   "policy.mjs",
   "pool.mjs",
+  "registry.mjs",
   "signin-gotrue-totp.mjs",
   "state-file.mjs",
   "totp-botbuddy.mjs",
 ]);
 
-const VALUE_FLAGS = new Set(["persona", "home", "botbuddy-bin", "interval", "owner"]);
+const VALUE_FLAGS = new Set(["persona", "home", "botbuddy-bin", "interval", "owner", "tenant", "pool"]);
 const BOOLEAN_FLAGS = new Set(["keep-sessions", "help", "check"]);
 
 export function parseArgs(argv) {
@@ -79,51 +84,83 @@ export function parseArgs(argv) {
 export function exitCodeFor(error) {
   if (error instanceof MintRefusedError || error?.code === "persona_not_allowed") return 2;
   if (error instanceof PoolEmptyError) return 3;
-  if (error instanceof ConfigError || error instanceof BindingError || error?.code === "config_missing") return 4;
+  if (error instanceof ConfigError || error instanceof BindingError || error instanceof RegistryError || error?.code === "config_missing") return 4;
   if (error?.code === "pool_unhealthy") return 5;
   return 1;
 }
 
-// Where this invocation's pool lives: the job passes --home; everyone else
-// resolves it from the repo binding (cwd).
-async function resolveContext({ options, cwd, home, readBinding = readRepoPoolBinding }) {
+// Where this invocation's pool lives: the job passes --home; everyone else names
+// an installed pool with --pool (or --tenant), or uses the only one installed.
+// Never the working directory (BOT-2648).
+export function poolsRoot(home) {
+  return join(home, ".botbuddy", "staging-session-pool");
+}
+
+/** Installed pool homes: [{ poolId, paths, installed | error }]. */
+export function listInstalledPools(home) {
+  let names = [];
+  try {
+    names = readdirSync(poolsRoot(home), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+  const pools = [];
+  for (const poolId of names.sort()) {
+    const paths = poolHomePaths({ home, poolId });
+    try {
+      pools.push({ poolId, paths, installed: readInstalledConfig(paths.config) });
+    } catch (error) {
+      if (error?.code !== "config_missing") pools.push({ poolId, paths, installed: { error } });
+    }
+  }
+  return pools;
+}
+
+function contextFor({ poolId, paths, installed }) {
+  if (installed?.error) return { paths, poolId, poolBinding: null, installed };
+  return { paths, poolId, poolBinding: installed.poolBinding, installed, rawBinding: installed.binding, tenant: installed.tenant ?? installed.binding?.tenant ?? null };
+}
+
+async function resolveContext({ options, home }) {
   if (options.home) {
     const paths = poolHomePaths({ home, root: options.home });
-    const config = readInstalledConfig(paths.config);
-    return { paths, poolBinding: config.poolBinding, installed: config, rawBinding: config.binding };
-  }
-  const found = await readBinding(cwd);
-  if (!found) {
-    throw new ConfigError("This repository declares no staging_session_pool in .botbuddy-agent.json, so it has no staging session pool.", "pool_not_configured");
+    return contextFor({ poolId: null, paths, installed: readInstalledConfig(paths.config) });
   }
-  const paths = poolHomePaths({ home, poolId: found.binding.poolId });
-  let installed = null;
-  try {
-    installed = readInstalledConfig(paths.config);
-  } catch (error) {
-    if (error?.code !== "config_missing") installed = { error };
+  const installed = listInstalledPools(home);
+  let candidates = installed;
+  if (options.pool) candidates = installed.filter((pool) => pool.poolId === options.pool);
+  else if (options.tenant) candidates = installed.filter((pool) => !pool.installed.error && (pool.installed.tenant ?? pool.installed.binding?.tenant) === options.tenant);
+  if (candidates.length === 1) return contextFor(candidates[0]);
+  if (candidates.length === 0) {
+    throw Object.assign(new ConfigError(`No staging session pool${options.pool ? ` ${options.pool}` : ""} is installed on this Mac.`, "pool_not_installed"), {
+      tenant: options.tenant ?? null, poolId: options.pool ?? null, poolIds: installed.map((pool) => pool.poolId),
+    });
   }
-  return { paths, poolBinding: found.binding, installed, repoRoot: found.repoRoot };
+  throw Object.assign(new ConfigError(`Several staging session pools are installed: ${candidates.map((pool) => pool.poolId).join(", ")}.`, "pool_ambiguous"), {
+    poolIds: candidates.map((pool) => pool.poolId),
+  });
 }
 
 const shellWord = (value) => (/^[A-Za-z0-9_./:@,=~+-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`);
-export const installCommandFor = (repoRoot, fallback) =>
-  repoRoot ? `cd ${shellWord(repoRoot)} && bb staging-pool install --botbuddy-bin "$(command -v botbuddy)"` : fallback;
+// The one upgrade/re-install command for an installed pool (its tenant is known).
+export const installCommandFor = (tenant, poolId = null) => (tenant ? installLine(shellWord(String(tenant)), poolId) : undefined);
 
 // The non-secret values every guidance template may name.
 export function guidanceVars(ctx, extra = {}) {
   if (!ctx) return { ...extra };
+  const binding = ctx.poolBinding;
   return {
-    label: ctx.poolBinding.launchdLabel,
+    label: binding?.launchdLabel,
     log: ctx.paths.log,
-    installCommand: installCommandFor(ctx.repoRoot, ctx.poolBinding.installCommand),
-    docs: ctx.poolBinding.docs,
+    installCommand: installCommandFor(ctx.tenant),
+    docs: binding?.docs,
     configPath: ctx.paths.config,
     poolHome: ctx.paths.root,
     tickCommand: `bb staging-pool tick --home ${shellWord(ctx.paths.root)}`,
-    checkout: ctx.repoRoot,
-    envFile: ctx.poolBinding.passwordEnvFile,
-    allowed: Object.keys(ctx.poolBinding.personas ?? {}),
+    tenant: ctx.tenant ?? undefined,
+    poolId: ctx.poolId ?? binding?.poolId,
+    envFile: binding?.passwordEnvFile,
+    allowed: Object.keys(binding?.personas ?? {}),
     ...extra,
   };
 }
@@ -178,9 +215,28 @@ export async function assessHealth({ ctx, pool, now, exec, uid, requestedPersona
   };
 }
 
+/**
+ * The installed pool `bb pw … auth` takes from: --pool, else the only installed
+ * pool, else the one for `tenantHint` (the lane credential's tenant). Throws
+ * ConfigError pool_not_installed / pool_ambiguous (with poolIds) otherwise.
+ */
+export function resolveInstalledPool({ home = homedir(), poolId = null, tenantHint = null } = {}) {
+  const installed = listInstalledPools(home).filter((pool) => !pool.installed.error);
+  if (poolId) {
+    const match = installed.find((pool) => pool.poolId === poolId);
+    if (!match) throw Object.assign(new ConfigError(`Staging session pool ${poolId} is not installed on this Mac.`, "pool_not_installed"), { poolId, poolIds: installed.map((pool) => pool.poolId) });
+    return contextFor(match);
+  }
+  if (installed.length === 1) return contextFor(installed[0]);
+  if (installed.length === 0) throw Object.assign(new ConfigError("No staging session pool is installed on this Mac.", "pool_not_installed"), { tenant: tenantHint, poolIds: [] });
+  const forTenant = tenantHint ? installed.filter((pool) => (pool.installed.tenant ?? pool.installed.binding?.tenant) === tenantHint) : [];
+  if (forTenant.length === 1) return contextFor(forTenant[0]);
+  throw Object.assign(new ConfigError(`Several staging session pools are installed: ${installed.map((pool) => pool.poolId).join(", ")}.`, "pool_ambiguous"), { poolIds: installed.map((pool) => pool.poolId) });
+}
+
 /**
  * Agent path, used by `bb pw … auth`: claim one verified session for a persona
- * (alias or email) of this repo's binding. Returns { taken, target, binding,
+ * (alias or email) of the installed pool. Returns { taken, target, binding,
  * discard } — the caller installs taken.statePath into its claimed lane and then
  * MUST call discard() (single use). Throws PoolEmptyError carrying the health
  * reason/agentAction/remedy when nothing is ready.
@@ -188,16 +244,16 @@ export async function assessHealth({ ctx, pool, now, exec, uid, requestedPersona
 export async function takeForLane({
   persona,
   owner,
-  cwd = process.cwd(),
+  poolId = null,
+  tenantHint = null,
   home = homedir(),
   now = () => Date.now(),
   fetchImpl = globalThis.fetch,
   exec = promisify(execFile),
   uid = userInfo().uid,
   logger = () => {},
-  readBinding = readRepoPoolBinding,
 } = {}) {
-  const ctx = await resolveContext({ options: {}, cwd, home, readBinding });
+  const ctx = resolveInstalledPool({ home, poolId, tenantHint });
   const entry = findPersona(ctx.poolBinding, persona);
   const target = stagingTargetFromBinding(ctx.poolBinding);
   if (!entry) assertPersonaAllowed(target, persona);
@@ -222,12 +278,107 @@ export async function takeForLane({
 // Fields a refusal carries so a caller can act on it without reading the code.
 export const GUIDANCE_FIELDS = Object.freeze(["reason", "agentAction", "remedy", "message", "cause", "actor", "next", "doc", "help", "detail", "intervalSeconds"]);
 
-// The human-only command line to repeat from Terminal.app (no secrets: flags only).
+// The command line to repeat (no secrets: flags only).
 function humanCommandLine(argv) {
-  if (argv[0] === "install") return 'install --botbuddy-bin "$(command -v botbuddy)"';
   return argv.map((token) => (/^[A-Za-z0-9_./:=@-]+$/.test(token) ? token : `'${token.replace(/'/g, "'\\''")}'`)).join(" ");
 }
 
+// argv with one flag set or replaced (for a refusal's "run it with --pool X").
+function withFlag(argv, flag, value) {
+  const out = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === `--${flag}`) { index += 1; continue; }
+    if (token.startsWith(`--${flag}=`)) continue;
+    out.push(token);
+  }
+  return [...out, `--${flag}`, value];
+}
+
+// What a missing pool binding means for each subcommand (AC-8 follow-up: an
+// install refusal must not talk about taking a session).
+const NO_POOL_CONSEQUENCE = Object.freeze({
+  install: "there is no pool definition to install",
+  uninstall: "there is no pool to remove",
+  tick: "there is no pool to refill",
+  "mint-one": "there is no pool to sign a persona in for",
+  status: "there is no pool to report on",
+  probe: "there are no pool personas to probe",
+  "print-plist": "there is no pool job to describe",
+});
+
+/**
+ * Build the refusal for a failed subcommand: the JSON record and the text block.
+ * A human-only subcommand always names Human (Jono) and prints no Agent line. No
+ * remedy names a directory: install reads the control plane by tenant (BOT-2648),
+ * so a refusal needs only the tenant (from --tenant, the installed pool, or the
+ * botbuddy login's whoami) and never prints a <placeholder>.
+ */
+export async function refusalFor({ argv, command, error, options = {}, home = homedir(), exec = promisify(execFile), env = process.env }) {
+  const code = typeof error?.code === "string" && isKnownCode(error.code) ? error.code : "unexpected_error";
+  const humanOnly = HUMAN_ONLY_COMMANDS.has(command);
+  let ctx = null;
+  try {
+    ctx = await resolveContext({ options, home });
+  } catch {
+    ctx = null;
+  }
+  const args = argv ?? [command];
+  let tenant = options.tenant ?? error?.tenant ?? ctx?.tenant ?? null;
+  if (!tenant && command === "install") tenant = await whoamiTenant({ exec, botbuddyBin: options["botbuddy-bin"] ?? "botbuddy", env });
+  const poolIds = Array.isArray(error?.poolIds) ? error.poolIds : [];
+  // install's re-run is always the complete line: --tenant and --botbuddy-bin included.
+  const installPool = command === "install" ? (options.pool ?? null) : null;
+  const retry = command === "install"
+    ? (tenant ? installLine(tenant, installPool) : undefined)
+    : `bb staging-pool ${humanCommandLine(args)}`;
+  const retryWithPool = poolIds.length
+    ? (command === "install" ? (tenant ? installLine(tenant, poolIds[0]) : undefined) : `bb staging-pool ${humanCommandLine(withFlag(args, "pool", poolIds[0]))}`)
+    : undefined;
+  const vars = guidanceVars(ctx, {
+    // install's line is always the complete one (tenant + --botbuddy-bin), never the typed args.
+    command: command === "install" && retry ? retry.replace(/^bb staging-pool /, "") : humanCommandLine(args),
+    retry,
+    retryWithPool,
+    tenant: tenant ?? undefined,
+    installPool,
+    installCommand: tenant ? installLine(tenant, installPool) : undefined,
+    poolIds,
+    poolId: error?.poolId ?? options.pool ?? ctx?.poolId,
+    consequence: NO_POOL_CONSEQUENCE[command] ?? "there is no pool to act on",
+    markers: Array.isArray(error?.markers) ? error.markers.join(", ") : undefined,
+  });
+  vars.poolSuffix = vars.poolId ? ` (${vars.poolId})` : "";
+  vars.persona = options.persona ?? error?.persona ?? vars.allowed?.[0];
+  const actor = humanOnly ? "human" : null;
+  const g = guidance(code, vars, { real: true, actor });
+  const record = {
+    ok: false, command, code, message: g.message, cause: g.cause, actor: g.actor_label, next: g.next,
+    agentAction: g.agent_action, doc: g.doc, help: g.help, detail: String(error?.message ?? error ?? "").slice(0, 500),
+  };
+  // A pool refusal (pool_empty / unhealthy) already carries its health guidance;
+  // an ordinary error's own message stays in `detail`.
+  if (typeof error?.reason === "string") for (const field of GUIDANCE_FIELDS) if (error[field] !== undefined) record[field] = error[field];
+  record.remedy ??= remedyLine(g);
+  if (humanOnly) Object.assign(record, { actor: g.actor_label, agentAction: "report_blocker" });
+  // An empty pool is explained by its health reason (e.g. job_not_loaded).
+  const textG = typeof error?.reason === "string" && error.reason !== code && isKnownCode(error.reason) ? guidance(error.reason, vars, { real: true, actor }) : g;
+  return { record, text: formatGuidance(textG, { agentLine: !humanOnly }), exitCode: exitCodeFor(error) };
+}
+
+// A pool home whose config.json is unreadable refuses with that config error.
+function usable(ctx) {
+  if (ctx.installed?.error) throw ctx.installed.error;
+  return ctx;
+}
+
+// BOT-2648 migration: an install from before the control-plane registry keeps
+// working; status names the one command that re-installs it from the registry.
+export function upgradeNotice(ctx) {
+  if (!ctx?.installed || ctx.installed.error || ctx.installed.source === "control-plane" || !ctx.tenant) return {};
+  return { upgrade: { reason: "installed_before_registry", message: "This pool was installed from a repository checkout; re-install it from the BotBuddy control plane (keeps counts and interval).", next: installCommandFor(ctx.tenant) } };
+}
+
 export async function runStagingPool(argv, deps = {}) {
   const {
     env = process.env,
@@ -244,7 +395,6 @@ export async function runStagingPool(argv, deps = {}) {
     scriptDir = dirname(fileURLToPath(import.meta.url)),
     nodeBin = process.execPath,
     sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-    readBinding = readRepoPoolBinding,
     readSecretFile = readFileSync,
   } = deps;
 
@@ -304,45 +454,68 @@ export async function runStagingPool(argv, deps = {}) {
 
   const commands = {
     async install(options) {
-      const ctx = await resolveContext({ options: {}, cwd, home, readBinding });
-      const target = stagingTargetFromBinding(ctx.poolBinding);
-      assertMintAllowed({ target, env, listAncestors });
+      // Human-only: refuse an agent session before any network or file call.
+      assertMintAllowed({ target: { name: "staging", appOrigin: "the tenant's staging app", loopback: false }, env, listAncestors });
+      if (!options.tenant) throw Object.assign(new ConfigError("install needs --tenant <slug>: pool bindings are registered per tenant.", "tenant_required"), {});
+      const tenant = options.tenant;
       const botbuddyBin = requireBotbuddyBin(options);
-      for (const dir of [ctx.paths.root, ctx.paths.logDir]) {
+      // The one source: the tenant's registration in the BotBuddy control plane.
+      const pools = await fetchRegisteredPools({ exec, botbuddyBin, env, tenant, poolId: options.pool ?? null });
+      const row = choosePool(pools, { tenant, poolId: options.pool ?? null });
+      const rawBinding = { schema_version: 1, tenant, staging_session_pool: row.binding };
+      let poolBinding;
+      try {
+        poolBinding = parsePoolBinding(rawBinding);
+      } catch (error) {
+        throw Object.assign(new ConfigError(String(error?.message ?? error), "pool_registration_refused"), { tenant });
+      }
+      // The origin allowlist and production refusal hold whatever the control plane returned.
+      try {
+        stagingTargetFromBinding(poolBinding);
+      } catch (error) {
+        throw Object.assign(error, { tenant });
+      }
+      const paths = poolHomePaths({ home, poolId: poolBinding.poolId });
+      const ctx = { paths, poolBinding, tenant, poolId: poolBinding.poolId };
+      for (const dir of [paths.root, paths.logDir]) {
         await fs.mkdir(dir, { recursive: true, mode: 0o700 });
         await fs.chmod(dir, 0o700);
       }
-      await copyBundle(ctx.paths.app);
-      const rawBinding = JSON.parse(await fs.readFile(join(ctx.repoRoot, ".botbuddy-agent.json"), "utf8"));
+      await copyBundle(paths.app);
       let existing = null;
       try {
-        existing = JSON.parse(await fs.readFile(ctx.paths.config, "utf8"));
+        existing = JSON.parse(await fs.readFile(paths.config, "utf8"));
       } catch (error) {
         if (error?.code !== "ENOENT") throw error;
       }
       const explicitInterval = options.interval === undefined ? undefined : Number(options.interval);
       const config = buildInstalledConfig({
         rawBinding,
-        poolBinding: ctx.poolBinding,
+        poolBinding,
         botbuddyBin,
         intervalSeconds: explicitInterval ?? existing?.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS,
         existingPersonas: existing?.personas,
+        tenant,
+        registry: { commit_sha: row.commit_sha ?? null, updated_at: row.updated_at ?? null },
+        installedAt: new Date(now()).toISOString(),
       });
-      await fs.writeFile(ctx.paths.config, serialiseInstalledConfig(config), { mode: 0o600 });
-      await fs.chmod(ctx.paths.config, 0o600);
-      const plistPath = join(ctx.paths.plistDir, `${ctx.poolBinding.launchdLabel}.plist`);
-      await fs.mkdir(ctx.paths.plistDir, { recursive: true });
+      await fs.writeFile(paths.config, serialiseInstalledConfig(config), { mode: 0o600 });
+      await fs.chmod(paths.config, 0o600);
+      const plistPath = join(paths.plistDir, `${poolBinding.launchdLabel}.plist`);
+      await fs.mkdir(paths.plistDir, { recursive: true });
       await fs.writeFile(plistPath, jobPlist(ctx, config.intervalSeconds), { mode: 0o644 });
       const launchctl = createLaunchctl({ exec, uid });
-      await launchctl.bootout(ctx.poolBinding.launchdLabel);
+      await launchctl.bootout(poolBinding.launchdLabel);
       await launchctl.bootstrap(plistPath);
       emit({
         ok: true,
         command: "install",
-        label: ctx.poolBinding.launchdLabel,
+        tenant,
+        poolId: poolBinding.poolId,
+        label: poolBinding.launchdLabel,
         plistPath,
-        poolHome: ctx.paths.root,
-        log: ctx.paths.log,
+        poolHome: paths.root,
+        log: paths.log,
         intervalSeconds: config.intervalSeconds,
         personas: config.personas,
         next: "bb staging-pool status --check   # the pool fills within one tick",
@@ -351,7 +524,7 @@ export async function runStagingPool(argv, deps = {}) {
     },
 
     async uninstall(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = usable(await resolveContext({ options, home }));
       const target = stagingTargetFromBinding(ctx.poolBinding);
       // The job and its sessions are the human's: an agent never stops or empties them.
       assertMintAllowed({ target, env, listAncestors });
@@ -365,7 +538,7 @@ export async function runStagingPool(argv, deps = {}) {
     },
 
     async tick(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = usable(await resolveContext({ options, home }));
       const target = stagingTargetFromBinding(ctx.poolBinding);
       assertMintAllowed({ target, env, listAncestors });
       if (!ctx.installed || ctx.installed.error) throw ctx.installed?.error ?? new ConfigError("The pool job is not installed; the human runs the install first.", "pool_not_installed");
@@ -375,7 +548,7 @@ export async function runStagingPool(argv, deps = {}) {
     },
 
     async "mint-one"(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = usable(await resolveContext({ options, home }));
       const target = stagingTargetFromBinding(ctx.poolBinding);
       assertMintAllowed({ target, env, listAncestors });
       const entry = findPersona(ctx.poolBinding, options.persona);
@@ -388,22 +561,28 @@ export async function runStagingPool(argv, deps = {}) {
     },
 
     async status(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = await resolveContext({ options, home });
+      if (ctx.installed?.error) {
+        // An unreadable installed config is one health reason, not a crash.
+        const health = await assessHealth({ ctx, pool: null, now, exec, uid });
+        emit({ command: "status", check: Boolean(options.check), ...health });
+        return 5;
+      }
       const target = stagingTargetFromBinding(ctx.poolBinding);
       const pool = buildPool({ ctx, target, now, logger: emit, fetchImpl, sleep });
       if (options.check) {
         const entry = options.persona ? findPersona(ctx.poolBinding, options.persona) : null;
         if (options.persona && !entry) assertPersonaAllowed(target, options.persona);
         const health = await assessHealth({ ctx, pool, now, exec, uid, requestedPersona: entry?.email });
-        emit({ command: "status", check: true, ...health });
+        emit({ command: "status", check: true, ...health, ...upgradeNotice(ctx) });
         return health.ok ? 0 : 5;
       }
-      emit({ ok: true, command: "status", ...(await pool.status()) });
+      emit({ ok: true, command: "status", ...(await pool.status()), ...upgradeNotice(ctx) });
       return 0;
     },
 
     async probe(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = usable(await resolveContext({ options, home }));
       const botbuddyBin = options["botbuddy-bin"] ?? ctx.installed?.botbuddyBin;
       if (!botbuddyBin) throw new ConfigError('probe needs --botbuddy-bin "$(command -v botbuddy)" (or an installed job).', "pool_not_installed");
       const receipt = await probeBotBuddy({
@@ -420,7 +599,7 @@ export async function runStagingPool(argv, deps = {}) {
     },
 
     async "print-plist"(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = usable(await resolveContext({ options, home }));
       stdout(jobPlist(ctx, Number(options.interval ?? ctx.installed?.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS)));
       return 0;
     },
@@ -428,34 +607,10 @@ export async function runStagingPool(argv, deps = {}) {
 
   // One JSON line (machine-readable) then the same guidance as text, on stderr.
   async function fail(command, error, options = {}) {
-    const code = typeof error?.code === "string" && isKnownCode(error.code) ? error.code : "unexpected_error";
-    let ctx = null;
-    try {
-      ctx = await resolveContext({ options, cwd, home, readBinding });
-    } catch {
-      ctx = null;
-    }
-    const persona = options.persona ?? error?.persona;
-    const vars = guidanceVars(ctx, {
-      persona,
-      command: humanCommandLine(argv),
-      markers: Array.isArray(error?.markers) ? error.markers.join(", ") : undefined,
-      checkout: ctx?.repoRoot ?? cwd,
-      retry: `bb staging-pool ${humanCommandLine(argv)}`,
-    });
-    const g = guidance(code, vars);
-    const record = {
-      ok: false, command, code, message: g.message, cause: g.cause, actor: g.actor_label, next: g.next,
-      agentAction: g.agent_action, doc: g.doc, help: g.help, detail: String(error?.message ?? error ?? "").slice(0, 500),
-    };
-    // A pool refusal already carries its health guidance (pool_empty / unhealthy).
-    for (const field of GUIDANCE_FIELDS) if (error?.[field] !== undefined) record[field] = error[field];
-    record.remedy ??= remedyLine(g);
+    const { record, text, exitCode } = await refusalFor({ argv, command, error, options, home, exec, env });
     stderr(JSON.stringify(redactor.redact({ ts: new Date(now()).toISOString(), ...record })));
-    // An empty pool is explained by its health reason (e.g. job_not_loaded).
-    const text = typeof error?.reason === "string" && error.reason !== code && isKnownCode(error.reason) ? guidance(error.reason, vars) : g;
-    stderr(redactor.redact(formatGuidance(text)));
-    return exitCodeFor(error);
+    stderr(redactor.redact(text));
+    return exitCode;
   }
 
   let parsed;

package/src/staging-pool/config.mjs

@@ -87,7 +87,7 @@ export function readInstalledConfig(path, { readFile = readFileSync } = {}) {
 }
 
 // rawBinding: { tenant, staging_session_pool } exactly as committed.
-export function buildInstalledConfig({ rawBinding, poolBinding, botbuddyBin, intervalSeconds = DEFAULT_INTERVAL_SECONDS, existingPersonas }) {
+export function buildInstalledConfig({ rawBinding, poolBinding, botbuddyBin, intervalSeconds = DEFAULT_INTERVAL_SECONDS, existingPersonas, tenant, registry, installedAt }) {
   const personas = {};
   for (const persona of Object.values(poolBinding.personas)) {
     personas[persona.email] = Number.isInteger(existingPersonas?.[persona.email]) ? existingPersonas[persona.email] : persona.defaultCount;
@@ -98,6 +98,10 @@ export function buildInstalledConfig({ rawBinding, poolBinding, botbuddyBin, int
     personas,
     botbuddyBin,
     intervalSeconds,
+    // BOT-2648: installed from the tenant's control-plane registration.
+    ...(tenant ? { tenant, poolId: poolBinding.poolId, source: "control-plane" } : {}),
+    ...(registry ? { registry } : {}),
+    ...(installedAt ? { installedAt } : {}),
   });
 }