@botbuddy/cli 1.60.5 → 1.60.6

package/src/staging-pool/errors.mjs

@@ -0,0 +1,380 @@
+// BOT-2084: every `bb staging-pool` and `bb pw … auth` refusal or failure, as a
+// stable code with what happened, the likely cause, who acts, the exact next
+// 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.
+
+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",
+  install: "install-update-remove-human-only",
+  take: "take-a-session-agent",
+  close: "close-and-the-residual-window",
+  repair: "repair-the-pool-human-only",
+  codes: "staging-session-pool-error-codes",
+});
+
+export const ACTOR_LABELS = Object.freeze({ agent: "Agent", human: "Human (Jono)" });
+
+const HUMAN_ONLY = "Agents never run this: it signs in with the persona password or changes the standing sessions.";
+
+const AUTH = "bb pw --environment staging {lane} auth --persona {persona}";
+const REOPEN = "bb pw {lane} close && bb pw --environment staging {lane} open about:blank";
+const INSTALL = "{installCommand}";
+
+const entry = (actor, doc, message, cause, next, agentAction = actor === "human" ? "report_blocker" : "fix_and_retry") =>
+  Object.freeze({ actor, doc, message, cause, next, agentAction });
+
+export const ERROR_CODES = Object.freeze({
+  // ── bb pw … auth: the caller's lane and arguments (agent fixes and retries)
+  auth_requires_staging_environment: entry("agent", "take",
+    "bb pw auth installs staging sessions only, and this lane is not on staging.",
+    "--environment staging was not given before the lane (or BB_PW_ENV names another environment).",
+    AUTH),
+  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}`),
+  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}`),
+  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}`),
+  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}.",
+    "bb pw --environment staging {lane} auth --persona {firstAllowed}"),
+  lane_browser_not_open: entry("agent", "take",
+    "Lane {lane} has no open browser to install the session into.",
+    "auth runs after open; the lane was never opened or was closed.",
+    `bb pw --environment staging {lane} open about:blank && ${AUTH}`),
+  browser_session_not_staging: entry("agent", "take",
+    "Lane {lane}'s open browser session is tracked as another environment.",
+    "The lane was opened with a different --environment.",
+    `${REOPEN} && ${AUTH}`),
+  persistent_profile_refused: entry("agent", "take",
+    "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}"),
+
+  // ── bb pw … auth: install into the lane (agent retries once, then reports)
+  session_install_failed: entry("agent", "take",
+    "The session could not be installed in lane {lane}; its slot was deleted and the lane cleared.",
+    "The lane's page navigated or closed mid-install, or the daemon was restarting.",
+    `${REOPEN} && ${AUTH}   # once; if it repeats, report this code`, "retry_once"),
+  staging_session_cleanup_pending: entry("agent", "close",
+    "Lane {lane}'s browser may still hold a staging session that should have been cleared, and clearing it failed.",
+    "The lane's browser stopped answering while bb pw removed the session.",
+    "bb pw {lane} close"),
+  session_not_aal2: entry("agent", "take",
+    "The pool's session for {persona} is no longer AAL2, so it was discarded.",
+    "The persona's TOTP factor was rotated (the staging seed job ran) after the session was minted.",
+    `${AUTH}   # once; the next ready slot is fresh. If it repeats, report this code`, "retry_once"),
+  session_expired: entry("agent", "take",
+    "The pool's session for {persona} had expired, so it was discarded.",
+    "The pool job has not refreshed recently (the Mac slept or the job stopped).",
+    `${AUTH}   # once; if it repeats, run: bb staging-pool status --check`, "retry_once"),
+  session_persona_mismatch: entry("human", "repair",
+    "The pool handed over a session for a different user than {persona}; it was discarded.",
+    "The pool's slot files were edited or mixed up by hand.",
+    "bb staging-pool uninstall && " + INSTALL),
+  slot_state_invalid: entry("human", "repair",
+    "The pool's slot file is not a single-origin, single-key session state; it was discarded.",
+    "The pool's slot files were edited by hand, or an older pool wrote them.",
+    "bb staging-pool uninstall && " + INSTALL),
+  slot_state_unreadable: entry("agent", "take",
+    "The lane's browser could not read the pool's slot file; it was discarded.",
+    "The lane's browser runs as another user or in a sandbox that cannot read ~/.botbuddy.",
+    `${REOPEN} && ${AUTH}   # once; if it repeats, report this code`, "retry_once"),
+  daemon_node_unsupported: entry("human", "take",
+    "The lane's Playwright daemon runs a Node.js without process.getBuiltinModule.",
+    "Node.js older than 22.3 runs the daemon.",
+    "node --version   # upgrade to Node.js 22.3 or newer, then: " + REOPEN),
+  daemon_run_failed: entry("agent", "take",
+    "The lane's browser did not run the install step.",
+    "The lane's daemon exited or restarted.",
+    `${REOPEN} && ${AUTH}   # once; if it repeats, report this code`, "retry_once"),
+  daemon_result_missing: entry("agent", "take",
+    "The lane's browser returned no install result.",
+    "The lane's daemon output changed shape (a @playwright/cli upgrade).",
+    "bb pw --version   # report this code with that version", "report_blocker"),
+  daemon_result_invalid: entry("agent", "take",
+    "The lane's browser returned an unreadable install result.",
+    "The lane's daemon output changed shape (a @playwright/cli upgrade).",
+    "bb pw --version   # report this code with that version", "report_blocker"),
+  pool_take_failed: entry("agent", "take",
+    "Taking a session from the pool failed unexpectedly (see detail).",
+    "A filesystem or pool error outside the known cases.",
+    `${AUTH}   # once; if it repeats, report this code and detail`, "retry_once"),
+
+  // ── the pool's health (human repairs; agents report once and stop)
+  pool_empty: entry("human", "repair",
+    "The staging session pool is healthy but has no ready session for {persona}.",
+    "Agents took every ready session since the last tick, or the ready ones were dead or AAL1 (factor rotated) and were discarded.",
+    "{tickCommand}"),
+  job_not_loaded: entry("human", "install",
+    "The staging session pool is not installed (or not loaded) on this Mac.",
+    "The one-time install has not been run here, or the Mac was migrated.",
+    INSTALL),
+  no_tick_yet: entry("human", "repair",
+    "The pool job is installed but has not completed a tick.",
+    "It was installed moments ago, or its first tick failed (see {log}).",
+    "{tickCommand}"),
+  tick_stale: entry("human", "repair",
+    "The pool job has not ticked for 3+ intervals.",
+    "The Mac was asleep or the launchd job is wedged.",
+    "launchctl kickstart -k gui/$(id -u)/{label}"),
+  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>"),
+  last_tick_failed: entry("human", "repair",
+    "The pool job's last tick could not sign {persona} in.",
+    "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>"),
+  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}).",
+    "grep mint_failed {log} | tail -1   # if clean, raise the persona's count (max 4) in {configPath}"),
+  persona_not_configured: entry("human", "repair",
+    "The pool does not serve {persona} (absent from, or 0 in, {configPath} personas).",
+    "The persona was added to the binding after install, or its count was set to 0.",
+    INSTALL + "   # re-install adds new personas; or set a count of 1-4 in {configPath}"),
+  config_invalid: entry("human", "repair",
+    "The installed pool config {configPath} is invalid (see detail).",
+    "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.",
+    INSTALL),
+  pool_target_mismatch: entry("human", "repair",
+    "The pool home belongs to a different staging target than the repository binding now names.",
+    "The binding's app_origin or supabase_url changed after install.",
+    "bb staging-pool uninstall && " + INSTALL),
+  state_file_rejected: entry("human", "repair",
+    "A minted session did not pass the pool's state checks (one origin, one key, an allowlisted persona), so it was not stored.",
+    "The binding's storage_key or personas do not match what staging Auth returned.",
+    "grep mint_failed {log} | tail -1   # compare with .botbuddy-agent.json storage_key / personas"),
+  tick_in_progress: entry("agent", "overview",
+    "A pool tick is already running.",
+    "The launchd job is mid-tick (each tick takes a few seconds per persona).",
+    "bb staging-pool status --check   # once, a minute later; do not loop", "retry_once"),
+
+  // ── 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}"),
+  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}"),
+
+  // ── configuration (repository binding and 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"),
+  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"),
+  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"),
+  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}.",
+    "bb staging-pool status --check --persona {firstAllowed}"),
+  usage: entry("agent", "overview",
+    "bb staging-pool did not understand the command line (see detail).",
+    "An unknown subcommand or flag, or a flag without its value.",
+    "bb staging-pool --help"),
+  botbuddy_bin_required: entry("human", "install",
+    "install needs the absolute path of the botbuddy CLI the job will call.",
+    "--botbuddy-bin was omitted or is relative.",
+    INSTALL),
+
+  // ── signing in (logged as mint_failed by the job; mint-one prints them)
+  botbuddy_cli_missing: entry("human", "repair",
+    "The job cannot find the botbuddy CLI it was installed with.",
+    "@botbuddy/cli was moved or uninstalled (fnm/nvm Node switch).",
+    "npm i -g @botbuddy/cli@latest && " + INSTALL),
+  totp_source_failed: entry("human", "repair",
+    "botbuddy call get_totp_code failed, so the job could not complete the MFA step.",
+    "The botbuddy CLI is signed out on this Mac, or the persona's TOTP seed is not registered.",
+    "botbuddy login && bb staging-pool probe"),
+  totp_response_invalid: entry("human", "repair",
+    "get_totp_code answered without a usable 6-digit code.",
+    "The BotBuddy server or CLI is out of date.",
+    "npm i -g @botbuddy/cli@latest && bb staging-pool probe"),
+  totp_response_mismatch: entry("human", "repair",
+    "get_totp_code answered for a different app, persona or environment.",
+    "The binding's app_slug or the registered seed changed.",
+    "bb staging-pool probe   # compare with .botbuddy-agent.json app_slug / personas"),
+  probe_response_invalid: entry("human", "repair",
+    "list_totp_seeds returned something other than a list of seeds.",
+    "The botbuddy CLI is signed out or out of date.",
+    "botbuddy login && bb staging-pool probe"),
+  password_source_missing: entry("human", "repair",
+    "The persona password is missing from {envFile}.",
+    "The file is absent, or lacks the persona's password_env variable (never committed).",
+    "ls -l {envFile}   # restore it with the persona's variable, then: bb staging-pool mint-one --persona {persona}"),
+  password_source_invalid: entry("human", "repair",
+    "{envFile} is not a regular file.",
+    "It is a directory, socket or broken link.",
+    "ls -l {envFile}   # replace it with a regular file, then: bb staging-pool mint-one --persona {persona}"),
+  password_source_permissions: entry("human", "repair",
+    "{envFile} is readable by group/others or not owned by you, so the job will not read it.",
+    "It was created without mode 0600 or copied from another user.",
+    "chmod 600 {envFile} && bb staging-pool mint-one --persona {persona}"),
+  password_rejected: entry("human", "repair",
+    "Staging Auth rejected the persona password.",
+    "Seed drift: the staging persona was re-seeded with another password, or the env file is stale.",
+    "bb staging-pool mint-one --persona {persona}   # after re-running the staging persona seed or updating the env file"),
+  no_verified_totp_factor: entry("human", "repair",
+    "The persona has no verified TOTP factor on staging.",
+    "Seed drift: the staging seed job has not enrolled the factor.",
+    "bb staging-pool probe   # after re-running the staging persona seed"),
+  challenge_failed: entry("human", "repair",
+    "Staging Auth refused the MFA challenge.",
+    "Auth rate limiting or a GoTrue change; {log} has the status.",
+    "grep mint_failed {log} | tail -1   # then: bb staging-pool mint-one --persona {persona}"),
+  verify_failed: entry("human", "repair",
+    "Staging Auth refused the TOTP code.",
+    "The Mac clock is skewed, or the registered seed differs from the enrolled factor.",
+    "sntp time.apple.com   # prints the clock offset; fix it in System Settings > Date & Time, then: bb staging-pool mint-one --persona {persona}"),
+  verify_response_invalid: entry("human", "repair",
+    "Staging Auth's MFA verify answer was not a usable session.",
+    "A GoTrue change; the pool's REST shapes are pinned by dated fixtures.",
+    "grep mint_failed {log} | tail -1   # report this code"),
+  mint_retries_exhausted: entry("human", "repair",
+    "The sign-in gave up after its retries.",
+    "Transient Auth or network failures; {log} names the last one.",
+    "grep mint_failed {log} | tail -1   # then: bb staging-pool mint-one --persona {persona}"),
+  not_aal2: entry("human", "repair",
+    "MFA verify returned a session that is not AAL2.",
+    "The persona's factor is not verified, or Auth's MFA settings changed.",
+    "bb staging-pool probe   # after re-running the staging persona seed"),
+  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}"),
+
+  unexpected_error: entry("agent", "codes",
+    "bb staging-pool failed unexpectedly (see detail).",
+    "An error outside the known cases.",
+    "bb staging-pool status   # once; report this code, the detail and the CLI version (bb version)", "report_blocker"),
+});
+
+// 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 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 } = {}) {
+  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}>`;
+    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 = {}) {
+  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] : [];
+  const filled = {
+    ...vars,
+    allowed,
+    firstAllowed: vars.firstAllowed ?? allowed[0],
+    // Without a resolved pool these still read as runnable commands from the checkout.
+    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)"`,
+  };
+  // What a "go to the right checkout" step re-runs: auth by default.
+  filled.retry = vars.retry ?? fill(AUTH, filled, { shell: true });
+  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,
+    doc: `${DOC_URL}#${DOC_SECTIONS[spec.doc]}`,
+    help: `bb help symptom ${known ? code : "unexpected_error"}`,
+  };
+}
+
+/** One line for JSON receipts and health records: who acts and the exact command. */
+export function remedyLine(g) {
+  const where = g.actor === "human" ? ", from Terminal.app or iTerm" : "";
+  return `${g.actor_label}${where}: ${g.next}  (${g.cause} Docs: ${g.doc})`;
+}
+
+/** Plain-text block for stderr. */
+export function formatGuidance(g, { prefix = "bb staging-pool" } = {}) {
+  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.");
+  lines.push(`  Docs: ${g.doc}`, `  Explain: ${g.help}`);
+  return lines.join("\n");
+}
+
+/** `bb help symptom staging-pool` and `bb help symptom <code>`. Null for an unknown topic. */
+export function symptomHelp(topic) {
+  const key = String(topic ?? "").trim().toLowerCase().replace(/-/g, "_");
+  if (key === "staging_pool" || key === "staging_pool_codes") {
+    const rows = Object.entries(ERROR_CODES).map(([code, spec]) => `  ${code.padEnd(36)} ${ACTOR_LABELS[spec.actor].padEnd(13)} ${spec.message.replace(/\{[A-Za-z]+\}/g, "…")}`);
+    return [
+      "bb staging-pool / bb pw auth error codes (BOT-2084). Actor = who runs the next step.",
+      "",
+      ...rows,
+      "",
+      "bb help symptom <code> shows the cause and the exact next command.",
+      `Docs: ${DOC_URL}#${DOC_SECTIONS.codes}`,
+    ].join("\n");
+  }
+  if (!isKnownCode(key)) return null;
+  const g = guidance(key);
+  return [
+    `Symptom: ${key}  (bb pw auth / bb staging-pool, BOT-2084)`,
+    "",
+    `What happened  ${g.message}`,
+    `Likely cause   ${g.cause}`,
+    `Who acts       ${g.actor_label}${g.actor === "human" ? " (agents report this once and stop)" : ""}`,
+    `Next           ${g.next}`,
+    `Docs           ${g.doc}`,
+    "",
+    "<placeholders> are filled in when the command prints this for a real refusal.",
+  ].join("\n");
+}

package/src/staging-pool/health.mjs

@@ -0,0 +1,84 @@
+// BOT-2084 (lifted from supplyspark-ent ENT-5120 health.mjs): pool health — one
+// machine-readable reason, the human remedy and the agent's action. Pure and
+// Node-stdlib-only; the remedy text is per repo (label, log, install command, docs).
+
+import { guidance, remedyLine } from "./errors.mjs";
+
+// Each reason's guidance (what happened, cause, who acts, next command, docs)
+// comes from the shared error registry (errors.mjs); `remedy` is its one-line form.
+export const HEALTH_REASON_CODES = Object.freeze([
+  "config_invalid", "persona_not_configured", "job_not_loaded", "no_tick_yet", "tick_stale",
+  "mint_backing_off", "last_tick_failed", "ticks_failing", "persona_below_target",
+]);
+
+// report_blocker → state the reason + remedy to the human ONCE and stop.
+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);
+    return [code, Object.freeze({ agentAction: g.agent_action, remedy: remedyLine(g), vars })];
+  })));
+}
+
+const STALE_INTERVALS = 3;
+const BELOW_TARGET_TICK_LIMIT = 2;
+const MAX_BACKOFF_MS = 2 * 60 * 60_000;
+
+export function nextMintBackoffMs({ failures, intervalMs }) {
+  return Math.min(intervalMs * 2 ** failures, MAX_BACKOFF_MS);
+}
+
+export function assessPoolHealth({ status, personas, intervalSeconds, nowMs, jobLoaded, configError, requestedPersona, reasons }) {
+  const unhealthy = (reason, extra = {}) => {
+    const { agentAction, vars } = reasons[reason];
+    let { remedy } = reasons[reason];
+    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 });
+      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 });
+    }
+    return { ...record, remedy };
+  };
+  const intervalMs = intervalSeconds * 1000;
+  if (configError) return unhealthy("config_invalid", { detail: configError });
+  if (jobLoaded === false) return unhealthy("job_not_loaded");
+  // Only when the configured persona set is known (an installed config, or --personas).
+  if (requestedPersona && Object.keys(personas).length > 0 && !(personas[requestedPersona] > 0)) {
+    return unhealthy("persona_not_configured", { persona: requestedPersona });
+  }
+  const lastTick = status?.lastTick;
+  if (!lastTick?.at) return unhealthy("no_tick_yet");
+  if (nowMs - Date.parse(lastTick.at) > STALE_INTERVALS * intervalMs) {
+    return unhealthy("tick_stale", { detail: `last tick ${lastTick.at}` });
+  }
+  const personaHealth = status.health?.personas ?? {};
+  // A take is diagnosed for its own persona; an unscoped `status --check` looks at all.
+  const scope = requestedPersona ? [requestedPersona] : Object.keys(personas);
+  for (const persona of scope) {
+    const entry = personaHealth[persona];
+    if (entry?.nextMintAttemptAt && Date.parse(entry.nextMintAttemptAt) > nowMs) {
+      return unhealthy("mint_backing_off", {
+        persona,
+        detail: `${entry.consecutiveMintFailures} consecutive failures, last ${entry.lastMintError}; next attempt ${entry.nextMintAttemptAt}`,
+      });
+    }
+  }
+  const requestedFailing = requestedPersona ? (personaHealth[requestedPersona]?.consecutiveMintFailures ?? 0) > 0 : true;
+  if (lastTick.mintFailures > 0 && requestedFailing) {
+    return unhealthy("last_tick_failed", { detail: `${lastTick.mintFailures} mint failure(s) at ${lastTick.at}` });
+  }
+  // Job-wide: a scoped take is judged by its persona's own backoff / shortfall instead,
+  // so one persona's repeated failure does not block another persona's take.
+  const lastSuccess = status.health?.lastSuccessfulTickAt;
+  if (!requestedPersona && (!lastSuccess || nowMs - Date.parse(lastSuccess) > STALE_INTERVALS * intervalMs)) {
+    return unhealthy("ticks_failing", { detail: `last successful tick ${lastSuccess ?? "never"}` });
+  }
+  for (const persona of scope) {
+    if ((personaHealth[persona]?.belowTargetTicks ?? 0) > BELOW_TARGET_TICK_LIMIT) {
+      return unhealthy("persona_below_target", { persona, detail: `${personaHealth[persona].belowTargetTicks} ticks below ${personas[persona]}` });
+    }
+  }
+  return { ok: true, reason: "healthy" };
+}

package/src/staging-pool/help.mjs

@@ -0,0 +1,125 @@
+// BOT-2084: help for `bb staging-pool` and `bb pw … auth`. Node-stdlib-only and
+// self-contained (bundled with the installed job).
+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 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)
+
+WHO RUNS IT
+  Agents (and humans). It never types a password or one-time code: it installs a
+  session the human-installed staging session pool already signed in
+  (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).
+  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>
+       bb pw --environment staging <lane> open about:blank
+  4. <alias> is a key of the binding's personas (BotBuddy: staging-admin).
+
+EXAMPLE (BotBuddy, lane 8)
+  bb pw --environment staging 8 open about:blank
+  bb pw --environment staging 8 auth --persona staging-admin
+  bb pw 8 goto https://staging.bot-buddy.ai/
+  …acceptance…
+  bb pw 8 verdict pass
+  bb pw 8 close      # discards the browser's copy (no sign-out), then release the lock
+
+WHAT IT PRINTS
+  stdout: one JSON receipt {"staging_auth": {…}} with ok, persona (alias), origin,
+  lane, aal, session_ref (12 hex, non-secret), access_expires_at, the landing path
+  and on_close. A refusal has ok: false, code, message, cause, actor, next, doc and
+  remedy, and stderr repeats it as text. Exit 0 installed, 2 fix the command,
+  3 refused or blocked.
+  Never printed, logged or kept: the password, the one-time code, the access or
+  refresh token, or the slot file's path or contents.
+
+CONFIGURATION
+${BINDING_KEYS_HELP}
+
+IF IT REFUSES
+  The refusal names the code, who acts ("Agent" or "Human (Jono)") and the exact
+  next command. For a Human step, report the code and next step once and stop;
+  never sign in yourself and never loop on status.
+  bb help symptom <code>          one code's cause and next command
+  bb help symptom staging-pool    every code
+  Docs: ${doc("take")}`;
+
+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
+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.
+
+ANYONE (agents too) — read-only
+  status [--check] [--persona <alias>]
+      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
+  probe [--botbuddy-bin <path>]
+      Confirms each persona's TOTP seed is registered (list_totp_seeds). Never
+      mints a code or signs in.
+      e.g. bb staging-pool probe
+  print-plist [--interval <seconds>]
+      Prints the launchd plist install would write. Writes nothing.
+      e.g. bb staging-pool print-plist
+
+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>]
+      One refresh and refill pass now (what the job runs).
+      e.g. bb staging-pool tick
+  mint-one --persona <alias>
+      One real sign-in into the pool, to prove a repair worked.
+      e.g. bb staging-pool mint-one --persona staging-admin
+  uninstall [--keep-sessions]
+      Stops the job and deletes its sessions (keeps them with --keep-sessions).
+      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).
+  - The persona password in the binding's password_env_file, mode 0600, never
+    committed (BotBuddy: ~/.config/botbuddy-web/.env.local.shared).
+
+CONFIGURATION
+${BINDING_KEYS_HELP}
+
+FILES
+  ~/.botbuddy/staging-session-pool/<pool_id>/
+      config.json, app/, pool/{ready,work,taken}/, log/pool.log (dirs 0700, files 0600)
+  ~/Library/LaunchAgents/<launchd_label>.plist
+
+OUTPUT
+  JSON lines on stdout. A failure prints one JSON line on stderr (code, message,
+  cause, actor, next, doc) and the same guidance as text. Never prints a
+  password, one-time code, token or session file contents.
+  Exit 0 ok, 1 a tick had mint failures, 2 refused (agent session, persona,
+  origin), 3 pool empty, 4 configuration or usage, 5 unhealthy.
+
+bb help symptom <code> explains one code; bb help symptom staging-pool lists them.
+Docs: ${doc("overview")}`;

package/src/staging-pool/job.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// BOT-2084: launchd entry for the installed staging session pool job
+// (<pool home>/app/job.mjs tick --home <pool home>). It runs the installed copy
+// of these modules and reads only the installed config, never a repo checkout.
+import { runStagingPool } from "./cli.mjs";
+
+process.exitCode = await runStagingPool(process.argv.slice(2));