@botbuddy/cli 1.60.7 → 1.60.9

package/src/staging-pool/errors.mjs

@@ -6,7 +6,8 @@
 // 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 "run this from inside a repository checkout …". Only
+// 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";
@@ -14,7 +15,7 @@ export const DOC_URL = "https://github.com/bot-buddy/botbuddy-webapp/blob/main/d
 // 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",
@@ -67,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",
-    "{cwd} is not inside a repository whose .botbuddy-agent.json declares staging_session_pool, so {consequence}.",
-    "The command ran outside the repository checkout (for example from your home directory), or that repository has not opted in.",
-    "cd {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",
@@ -164,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.",
@@ -184,25 +185,43 @@ export const ERROR_CODES = Object.freeze({
   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; run it from Terminal.app or iTerm instead. ${HUMAN_ONLY}`,
-    "cd {checkout} && bb staging-pool {command}"),
+    "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; run it from Terminal.app or iTerm instead. ${HUMAN_ONLY}`,
-    "cd {checkout} && bb staging-pool {command}"),
+    "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}.",
@@ -280,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).",
@@ -301,11 +320,12 @@ export const AUTH_ONLY_CODES = Object.freeze(new Set([
 // Human (Jono) whatever the code, and prints no Agent guidance.
 export const HUMAN_ONLY_COMMANDS = Object.freeze(new Set(["install", "uninstall", "tick", "mint-one"]));
 
-export const CHECKOUT_SENTENCE = "From inside a repository checkout whose .botbuddy-agent.json declares staging_session_pool (for BotBuddy: your botbuddy-webapp clone on main), run";
-export const BARE_INSTALL = 'bb staging-pool install --botbuddy-bin "$(command -v botbuddy)"';
+// 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", "ticketFlag"]);
+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_./:@,=~+-]+$/;
@@ -317,13 +337,13 @@ 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",
-  checkout: "the repository checkout", allowed: "the binding's personas", firstAllowed: "a listed persona",
+  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 checkout path
-// with spaces) is shell-quoted, so the line stays one safe copy-paste.
+// 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];
@@ -352,22 +372,23 @@ export function guidance(code, vars = {}, { real = false, actor = null } = {}) {
     allowed,
     firstAllowed: vars.firstAllowed ?? allowed[0],
     ticketFlag: vars.ticketFlag ?? (real ? "" : " --ticket <ticket>"),
-    // Without a resolved pool these still read as runnable commands from the checkout.
+    poolSuffix: vars.poolSuffix ?? (vars.poolId ? ` (${vars.poolId})` : ""),
     tickCommand: vars.tickCommand ?? "bb staging-pool tick",
-    installCommand: vars.installCommand ?? (vars.checkout ? `cd ${shellWord(String(vars.checkout))} && ${BARE_INSTALL}` : (real ? undefined : `cd <checkout> && ${BARE_INSTALL}`)),
+    // 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) {
-      // No concrete checkout (or a value only a resolved pool knows): say where to
-      // run it, and give the command that works from there.
-      const bareMissing = new Set();
-      const bare = fill(spec.next.replace("cd {checkout} && ", ""), { ...filled, installCommand: BARE_INSTALL }, { shell: true, missing: bareMissing });
-      next = `${CHECKOUT_SENTENCE}: ${bareMissing.size ? filled.retry : bare}`;
+      // 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 });

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;
+  }
+}

package/src/usage/sync.mjs

@@ -10,6 +10,7 @@
 // success). It carries row COUNTS only — never paths, never prompt text, never
 // token totals. Fail-open: any failure exits 0 unless --strict.
 import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { homedir, hostname as systemHostname } from "node:os";
@@ -90,16 +91,20 @@ export function transcriptRoots(env = process.env, home = homedir()) {
  * subdirectories) modified since `cutoffMs`. `shouldStop` is checked before
  * every directory read and stat, so a huge history or a slow filesystem cannot
  * outlive the run's time budget (the pre-push lane runs with 5 s).
- * @returns {Promise<{ files: string[], stopped: boolean }>}
+ * `errors` counts directories or files that exist but could not be read
+ * (EACCES, EPERM, …); a missing root or a file that vanished is not an error.
+ * @returns {Promise<{ files: string[], stopped: boolean, errors: number }>}
  */
 export async function listTranscripts(root, cutoffMs, { shouldStop = () => false, keep = () => false } = {}) {
   const out = [];
   let stopped = false;
+  let errors = 0;
+  const benign = (error) => error?.code === "ENOENT" || error?.code === "ENOTDIR";
   const halt = () => (stopped = stopped || shouldStop());
   async function walk(dir) {
     if (halt()) return;
     let entries;
-    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch (error) { if (!benign(error)) errors += 1; return; }
     entries.sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of entries) {
       if (halt()) return;
@@ -109,12 +114,12 @@ export async function listTranscripts(root, cutoffMs, { shouldStop = () => false
         try {
           const info = await stat(path);
           if (info.mtimeMs >= cutoffMs || keep(path, info)) out.push(path);
-        } catch { /* vanished between readdir and stat */ }
+        } catch (error) { if (!benign(error)) errors += 1; /* ENOENT: vanished between readdir and stat */ }
       }
     }
   }
   await walk(root);
-  return { files: out, stopped };
+  return { files: out, stopped, errors };
 }
 
 /** Which adapter owns a single `--file`: under a Codex root, or a rollout whose first record is session_meta. */
@@ -373,19 +378,24 @@ export async function syncUsage(opts, deps = {}) {
     roots = transcriptRoots(env, home), repoFor = createRepoResolver(), branchFor = createBranchResolver({ env }), cliVersion = "0.0.0",
     tenantFor = createTenantResolver({ env }), resolveTarget = defaultResolveTarget, readLines = readCompleteLines,
     serverUrl = env.BOTBUDDY_SERVER_URL || DEFAULT_SERVER_URL, statePath = cursorPath(home),
+    newSyncId = randomUUID,
   } = deps;
   const startedMs = now();
   const deadlineMs = startedMs + opts.maxSeconds * 1000;
   const parseDeadlineMs = startedMs + opts.maxSeconds * 1000 * PARSE_BUDGET_FRACTION;
   const startedAt = new Date(startedMs).toISOString();
+  // BOT-2649: one id for this whole invocation, sent with every batch (both
+  // providers), so v_usage_sync_hosts judges the attempt as a whole: one
+  // refused batch fails the sync even when a later batch succeeded.
+  const syncId = newSyncId();
   const receipt = {
     schema_version: 1, command: "usage sync", outcome: "ok", trigger: opts.trigger, dry_run: opts.dryRun,
     providers: [], files_scanned: 0, files_read: 0, envelopes: 0, batches: 0,
     tenant: null, skipped_other_tenant: 0, skipped_unbound: 0,
     seen: 0, inserted: 0, superseded: 0, deduped: 0, refused: 0, refusal_reasons: {}, batches_all_refused: 0,
-    refused_local: 0, parse_errors: 0,
+    refused_local: 0, parse_errors: 0, read_errors: 0,
     held_open_messages: 0, cost_state_withheld: 0,
-    privacy: "pass", budget_exhausted: false, run_ids: [], started_at: startedAt, duration_ms: 0,
+    privacy: "pass", budget_exhausted: false, run_ids: [], started_at: startedAt, sync_id: syncId, duration_ms: 0,
   };
   const finish = (outcome, error) => {
     receipt.outcome = outcome;
@@ -441,6 +451,8 @@ export async function syncUsage(opts, deps = {}) {
         },
       });
       if (listed.stopped) receipt.budget_exhausted = true;
+      // BOT-2649: an unreadable transcript directory is a read failure, not an idle host.
+      receipt.read_errors += listed.errors ?? 0;
       plan.push({ provider, files: listed.stopped ? [] : listed.files });
     }
   }
@@ -466,7 +478,7 @@ export async function syncUsage(opts, deps = {}) {
       : createClaudeAdapter({ hmac, environment, repoFor, tenantFor });
     const run = {
       host: hostname(), trigger: opts.trigger, provider, cli_version: cliVersion,
-      parser_version: adapter.parserVersion, started_at: startedAt,
+      parser_version: adapter.parserVersion, started_at: startedAt, sync_id: syncId,
     };
 
     // Envelopes are queued with a global sequence; a file's cursor commits only
@@ -535,7 +547,9 @@ export async function syncUsage(opts, deps = {}) {
     for (const path of files) {
       if (now() >= parseDeadlineMs) { receipt.budget_exhausted = true; break; }
       let info;
-      try { info = await stat(path); } catch { continue; }
+      // A file that vanished since listing is benign; any other stat failure
+      // (e.g. EACCES) means this run could not read pending usage (BOT-2649).
+      try { info = await stat(path); } catch (error) { if (error?.code !== "ENOENT") receipt.read_errors += 1; continue; }
       const sourceHmac = hmac(resolve(path));
       // Cursors are per (tenant, file): a run skips other tenants' records, so a
       // shared per-file cursor would consume them for every later tenant's run.
@@ -560,6 +574,7 @@ export async function syncUsage(opts, deps = {}) {
           parser.parseRecord(record, offset);
         }, { shouldStop: () => now() >= parseDeadlineMs });
       } catch {
+        receipt.read_errors += 1; // counted: a run that could not read is not a clean idle run
         continue; // unreadable file: skip, cursor unchanged
       }
       if (result.stopped) receipt.budget_exhausted = true;
@@ -606,8 +621,43 @@ export async function syncUsage(opts, deps = {}) {
     }
     commitDelivered();
   }
+  // BOT-2649: a run that uploaded nothing still records one empty ok run, so an
+  // idle but healthy host is not aged into "stale" by v_usage_sync_hosts. Only a
+  // CLEAN idle run does: one that refused records locally, hit unparseable lines,
+  // could not read a transcript or ran out of budget did not prove usage lands, so it records nothing and the
+  // host ages as before rather than reading healthy (independent review on #1324).
+  if (!opts.dryRun && receipt.batches === 0) {
+    const withheld = receipt.budget_exhausted ? "budget_exhausted"
+      : receipt.refused_local > 0 ? "refused_local"
+      : receipt.parse_errors > 0 ? "parse_errors"
+      : receipt.read_errors > 0 ? "read_errors" : null;
+    if (withheld) {
+      receipt.empty_run_withheld = withheld;
+    } else {
+      const error = await postEmptyRun();
+      if (error === OUT_OF_TIME) return finalize(null);
+      if (error) return finalize(error);
+    }
+  }
   return finalize(null);
 
+  async function postEmptyRun() {
+    // Same deadline rules as a batch: never START a request past the budget.
+    if (now() >= deadlineMs) { receipt.budget_exhausted = true; return OUT_OF_TIME; }
+    const resolved = await ensureAuth();
+    if (resolved.error) return resolved.error;
+    if (now() >= deadlineMs) { receipt.budget_exhausted = true; return OUT_OF_TIME; }
+    const run = { host: hostname(), trigger: opts.trigger, cli_version: cliVersion, started_at: startedAt, sync_id: syncId };
+    const result = await postBatch({
+      endpoint: usageIngestEndpoint(serverUrl), tenant: resolved.tenant,
+      headers: resolved.headers, run, envelopes: [], fetchImpl, timeoutMs: deadlineMs - now(),
+    });
+    if (!result.ok) return result.error;
+    receipt.empty_run = true;
+    if (result.run_id) receipt.run_ids.push(result.run_id);
+    return null;
+  }
+
   async function finalize(error) {
     const outcome = error ? "error" : opts.dryRun ? "dry_run" : receipt.budget_exhausted ? "partial" : "ok";
     finish(outcome, error);

package/src/staging-pool/checkouts.mjs

@@ -1,120 +0,0 @@
-// BOT-2084 (AC-8 follow-up): which repository checkouts on this Mac declare a
-// staging_session_pool, so a refusal run from the wrong directory (e.g. `~`) can
-// name a concrete `cd <path>` instead of a placeholder.
-//
-// Sources, both non-secret paths only:
-//   * every installed pool's config.json `checkout` (written by install);
-//   * ~/.botbuddy/staging-session-pool/known-checkouts.json (0600), updated each
-//     time a bb staging-pool / bb pw auth command resolves a binding from a cwd.
-// A candidate counts only if it still exists and still declares a pool binding.
-// Node-stdlib-only and self-contained (bundled with the installed job).
-import { chmodSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
-import { join, sep } from "node:path";
-
-import { readRepoPoolBinding } from "./binding.mjs";
-
-const MAX_KNOWN = 20;
-
-const linkedWorktree = (path) => {
-  try {
-    return statSync(join(path, ".git")).isFile();
-  } catch {
-    return false;
-  }
-};
-const TEMP_ROOTS = ["/tmp", "/private/tmp", "/var/folders", "/private/var/folders"];
-// Path segments that mark agent, scratch or disposable checkouts.
-const DISPOSABLE_SEGMENTS = new Set(["worktrees", "scratch-workspaces"]);
-
-/**
- * A checkout a human can be told to `cd` into: not under a temp dir, not an agent
- * or scratch worktree (a `worktrees` / `scratch-workspaces` path segment), and not
- * a linked git worktree (`.git` is a file). Remedies addressed to a human never
- * embed any other path (AC-8 follow-up, found on staging acceptance).
- */
-export function isStableCheckout(path, { tmp = tmpdir(), gitFileIsWorktree = linkedWorktree } = {}) {
-  if (typeof path !== "string" || !path.startsWith("/")) return false;
-  const roots = [...TEMP_ROOTS, tmp];
-  try {
-    roots.push(realpathSync(tmp));
-  } catch {
-    // tmp may not resolve in a test sandbox
-  }
-  for (const root of roots) {
-    const base = String(root).replace(/\/+$/, "");
-    if (base && (path === base || path.startsWith(`${base}/`))) return false;
-  }
-  if (path.split(sep).some((segment) => DISPOSABLE_SEGMENTS.has(segment))) return false;
-  return !gitFileIsWorktree(path);
-}
-const poolsRoot = (home) => join(home, ".botbuddy", "staging-session-pool");
-export const knownCheckoutsPath = (home = homedir()) => join(poolsRoot(home), "known-checkouts.json");
-
-function readKnown(home) {
-  try {
-    const data = JSON.parse(readFileSync(knownCheckoutsPath(home), "utf8"));
-    return Array.isArray(data?.checkouts) ? data.checkouts.filter((entry) => typeof entry?.path === "string" && entry.path.startsWith("/")) : [];
-  } catch {
-    return [];
-  }
-}
-
-/** Best effort: remember a checkout that resolved a binding. Never throws. */
-export function recordCheckout({ home = homedir(), path, poolId, now = Date.now() } = {}) {
-  try {
-    if (typeof path !== "string" || !path.startsWith("/")) return;
-    const entries = [{ path, pool_id: poolId ?? null, seen_at: new Date(now).toISOString() }, ...readKnown(home).filter((entry) => entry.path !== path)].slice(0, MAX_KNOWN);
-    mkdirSync(poolsRoot(home), { recursive: true, mode: 0o700 });
-    const file = knownCheckoutsPath(home);
-    const tmp = `${file}.${process.pid}.tmp`;
-    writeFileSync(tmp, `${JSON.stringify({ version: 1, checkouts: entries }, null, 2)}\n`, { mode: 0o600 });
-    chmodSync(tmp, 0o600);
-    renameSync(tmp, file);
-  } catch {
-    // A refusal's hint must never fail the command that produced it.
-  }
-}
-
-function installedCheckouts(home) {
-  const found = [];
-  let names = [];
-  try {
-    names = readdirSync(poolsRoot(home));
-  } catch {
-    return found;
-  }
-  for (const name of names) {
-    try {
-      const config = JSON.parse(readFileSync(join(poolsRoot(home), name, "config.json"), "utf8"));
-      if (typeof config?.checkout === "string" && config.checkout.startsWith("/")) found.push({ path: config.checkout, pool_id: name, seen_at: config.installedAt ?? null });
-    } catch {
-      // not installed, or unreadable: not a candidate
-    }
-  }
-  return found;
-}
-
-/**
- * Checkouts that still declare a staging_session_pool, most relevant first:
- * installed pools' checkouts, then the most recently seen. `poolId` narrows to
- * one pool when it is known.
- */
-export async function findKnownCheckouts({ home = homedir(), poolId = null, readBinding = readRepoPoolBinding, isStable = isStableCheckout } = {}) {
-  const seen = new Set();
-  const result = [];
-  for (const entry of [...installedCheckouts(home), ...readKnown(home)]) {
-    if (seen.has(entry.path)) continue;
-    seen.add(entry.path);
-    if (!isStable(entry.path)) continue;
-    try {
-      const found = await readBinding(entry.path);
-      if (!found || found.repoRoot !== entry.path) continue;
-      if (poolId && found.binding.poolId !== poolId) continue;
-      result.push({ path: entry.path, poolId: found.binding.poolId });
-    } catch {
-      // gone, or no longer a valid binding
-    }
-  }
-  return result;
-}