@botbuddy/cli 1.60.5 → 1.60.7

package/src/pw/staging-auth.mjs

@@ -0,0 +1,393 @@
+// BOT-2084: `bb pw --environment staging <lane> auth --persona <alias>` — install
+// one signed-in session from the human-installed staging session pool
+// (cli/src/staging-pool, lifted from Supply Guard's ENT-5120 pool) into the
+// claimed lane's browser.
+//
+//   * The pool claims one slot by atomic rename and re-verifies it through the
+//     refresh grant (aal2, same persona); no two lanes ever hold one session.
+//   * The lane's Playwright daemon reads the claimed slot file itself and writes
+//     the session into the bound origin's storage, then the slot is deleted
+//     whatever happens. The session never passes through this process's output,
+//     argv, the run-code source or the ledger.
+//   * Close discards the browser's copy with no sign-out (as Supply Guard does);
+//     see docs/agent-staging-acceptance-mfa.md for the residual window. A crashed
+//     browser took its copy with it; a lost lane lock clears what is left, and a
+//     clear that fails blocks the lane until it is resolved.
+//   * The ledger (~/.botbuddy/pw-staging-auth/<host>/lane-<n>.json, 0600) holds
+//     non-secret install records only.
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const SOURCE_NAME = "staging-session-pool";
+
+// Every refusal's text (what happened, cause, who acts, next command, docs) comes
+// from the shared registry, cli/src/staging-pool/errors.mjs (`bb help symptom <code>`).
+import { formatGuidance, guidance, isKnownCode, remedyLine } from "../staging-pool/errors.mjs";
+
+// ---------------------------------------------------------------- redaction
+// Defense in depth: nothing this command writes may look like a bearer. The
+// daemon never returns one; this guard turns a regression into a refusal.
+const JWT_RE = /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/;
+const SECRET_KEY_RE = /"(access_token|refresh_token|password|totp_secret|otp|code_verifier)"\s*:/i;
+export function containsBearerMaterial(text) { const value = String(text ?? ""); return JWT_RE.test(value) || SECRET_KEY_RE.test(value); }
+function safeWrite(stream, text) { stream.write(containsBearerMaterial(text) ? "bb-pw: auth output withheld (bearer-shaped content detected).\n" : text); }
+
+// ---------------------------------------------------------------- ledger
+// Non-secret install records only — never a token or slot path. One file per
+// host+lane, mode 0600 in a 0700 directory, replaced atomically.
+export const stagingAuthDir = (env = process.env) => env.BB_PW_STAGING_AUTH_DIR || join(homedir(), ".botbuddy", "pw-staging-auth");
+const safeSegment = (value) => String(value).replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120) || "_";
+export const ledgerPath = (env, host, slot) => join(stagingAuthDir(env), safeSegment(host), `lane-${safeSegment(slot)}.json`);
+const REF_RE = /^[0-9a-f]{12}$/;
+export function readLedger(env, host, slot) {
+  const file = ledgerPath(env, host, slot);
+  if (!existsSync(file)) return { version: 2, entries: [] };
+  try {
+    const data = JSON.parse(readFileSync(file, "utf8"));
+    return { version: 2, entries: Array.isArray(data?.entries) ? data.entries.filter((entry) => REF_RE.test(String(entry?.session_ref ?? ""))) : [] };
+  } catch {
+    return { version: 2, entries: [] };
+  }
+}
+export function writeLedger(env, host, slot, entries) {
+  const file = ledgerPath(env, host, slot);
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  try { chmodSync(dirname(file), 0o700); } catch { /* best effort */ }
+  const clean = entries.map((entry) => ({
+    session_ref: entry.session_ref, persona: entry.persona, generation: entry.generation ?? null, installed_at: entry.installed_at,
+    holder: entry.holder ?? null,
+    origin: entry.origin ?? null, storage_key: entry.storage_key ?? null,
+    access_expires_at: entry.access_expires_at ?? null, ...(entry.clear_pending === true ? { clear_pending: true } : {}),
+  }));
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 2, entries: clean }, null, 2) + "\n", { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+// ---------------------------------------------------------------- daemon code
+const j = (value) => JSON.stringify(value);
+const realm = 'const G = page.constructor.constructor("return globalThis")();';
+
+// Runs inside the lane's Playwright daemon: read the claimed slot's state file
+// (a Playwright storage state holding exactly the bound origin + one supabase-js
+// key), check it is the persona's unexpired aal2 session, write it to the origin's
+// localStorage and reload the lane's pages on it. Returns no session material.
+export function installCode({ statePath, origin, storageKey, email }) {
+  const args = { statePath, origin, storageKey, email };
+  return `async (page) => {
+  ${realm}
+  const args = ${j(args)};
+  const fs = typeof G.process.getBuiltinModule === "function" ? G.process.getBuiltinModule("node:fs") : null;
+  if (!fs) return { ok: false, code: "daemon_node_unsupported" };
+  let value;
+  let claims;
+  try {
+    const state = JSON.parse(fs.readFileSync(args.statePath, "utf8"));
+    const origins = Array.isArray(state.origins) ? state.origins : [];
+    if ((state.cookies ?? []).length !== 0 || origins.length !== 1 || origins[0].origin !== args.origin) return { ok: false, code: "slot_state_invalid" };
+    const items = origins[0].localStorage ?? [];
+    if (items.length !== 1 || items[0].name !== args.storageKey) return { ok: false, code: "slot_state_invalid" };
+    value = items[0].value;
+    const session = JSON.parse(value);
+    const segment = String(session.access_token ?? "").split(".")[1] ?? "";
+    claims = JSON.parse(G.Buffer.from(segment, "base64url").toString("utf8"));
+    if (typeof session.refresh_token !== "string" || !session.refresh_token) return { ok: false, code: "slot_state_invalid" };
+  } catch {
+    return { ok: false, code: "slot_state_unreadable" };
+  }
+  if (claims.aal !== "aal2") return { ok: false, code: "session_not_aal2" };
+  if (String(claims.email ?? "").toLowerCase() !== args.email) return { ok: false, code: "session_persona_mismatch" };
+  if (typeof claims.exp !== "number" || claims.exp * 1000 <= Date.now() + 60000) return { ok: false, code: "session_expired" };
+  try {
+    const sameOrigin = (url) => { try { return new G.URL(url).origin === args.origin; } catch { return false; } };
+    if (!sameOrigin(page.url())) await page.goto(args.origin + "/", { waitUntil: "domcontentloaded" });
+    await page.evaluate(([name, item]) => { window.localStorage.setItem(name, item); }, [args.storageKey, value]);
+    value = null;
+    const ctx = page.context();
+    for (const other of ctx.pages()) if (sameOrigin(other.url())) await other.reload({ waitUntil: "domcontentloaded" });
+    return { ok: true, path: new G.URL(page.url()).pathname, access_expires_at: new Date(claims.exp * 1000).toISOString() };
+  } catch {
+    return { ok: false, code: "session_install_failed" };
+  }
+}`;
+}
+
+// Local storage outlives navigation, so clearing must not depend on a lane tab
+// still being on the origin. A temporary page is pointed at the origin with every
+// request fulfilled by a blank document (the app never runs, so it cannot write
+// the session back), the key is removed there, and lane tabs still on the origin
+// are reloaded (or closed) so the app drops its in-memory copy.
+export function clearCode({ origin, storageKey }) {
+  const args = { origin, storageKey };
+  return `async (page) => {
+  ${realm}
+  const args = ${j(args)};
+  const ctx = page.context();
+  const onOrigin = (candidate) => { try { return new G.URL(candidate.url()).origin === args.origin; } catch { return false; } };
+  const lanePages = ctx.pages().filter(onOrigin);
+  const scratch = await ctx.newPage();
+  try {
+    await scratch.route("**/*", (route) => route.fulfill({ status: 200, contentType: "text/html", body: "<!doctype html><title>bb-pw cleanup</title>" }));
+    await scratch.goto(args.origin + "/", { waitUntil: "domcontentloaded" });
+    await scratch.evaluate((name) => { window.localStorage.removeItem(name); }, args.storageKey);
+  } finally {
+    await scratch.close();
+  }
+  // Removing the key clears storage, but a tab still on the origin keeps the
+  // app's in-memory session until it reloads. A tab that cannot reload is closed;
+  // one that can neither reload nor close leaves the cleanup unresolved.
+  let reloaded = 0;
+  let closed = 0;
+  let stuck = 0;
+  for (const other of lanePages) {
+    try {
+      await other.reload({ waitUntil: "domcontentloaded" });
+      reloaded++;
+    } catch {
+      try { await other.close(); closed++; } catch { stuck++; }
+    }
+  }
+  return { ok: stuck === 0, reloaded, closed, stuck };
+}`;
+}
+
+// `run-code` replies "### Result\n<JSON>\n…"; only that line is read, never echoed.
+export function parseRunCodeResult(reply) {
+  if (!reply?.ok) return { ok: false, code: "daemon_run_failed" };
+  const match = /### Result\n([^\n]*)/.exec(String(reply.text ?? ""));
+  if (!match) return { ok: false, code: "daemon_result_missing" };
+  try {
+    const value = JSON.parse(match[1]);
+    return value && typeof value === "object" ? value : { ok: false, code: "daemon_result_invalid" };
+  } catch {
+    return { ok: false, code: "daemon_result_invalid" };
+  }
+}
+
+// One browser launch. The pinned @playwright/cli derives the socket path from
+// the workspace and session name, so a restarted daemon reuses it; the session
+// record's launch `timestamp` is what changes.
+export const generationOf = (session) => session ? `${String(session.socketPath ?? "")}#${String(session.timestamp ?? "")}` : null;
+
+export const isPersistentLane = (session) => session?.cli?.persistent === true ||
+  (typeof session?.browser?.userDataDir === "string" && session.browser.userDataDir.length > 0);
+
+// ---------------------------------------------------------------- lifecycle
+function context({ plan, host, env, socketRun, target }) {
+  const run = async (code) => parseRunCodeResult(await socketRun({ session: plan.session, socketArgs: ["run-code", code] }, env));
+  return { run, env, host, slot: plan.lane, target };
+}
+
+// The bound origin/storage key for cleanup is recorded on each ledger entry, so a
+// cleanup never needs the repo binding (it may run from another directory).
+const targetOf = (entry) => entry?.origin && entry?.storage_key ? { origin: entry.origin, storageKey: entry.storage_key } : null;
+
+// Clear sessions from the lane's live browser, or record that they may still be
+// there. A browser holds one session key per origin+storage key, so entries are
+// grouped by that target and each target is cleared once. Only same-generation
+// entries chosen by `select` are touched: other generations lived in a browser
+// that is gone, and other holders' installs are not this caller's to clear.
+const targetKey = (target) => `${target.origin}\n${target.storageKey}`;
+async function clearBrowserOrMark(ctx, generation, select = () => true) {
+  const entries = readLedger(ctx.env, ctx.host, ctx.slot).entries;
+  const chosen = new Set(entries.filter((entry) => generation && entry.generation === generation && select(entry)));
+  if (!chosen.size) return true;
+  const cleared = new Map();
+  for (const entry of chosen) {
+    const target = targetOf(entry) ?? ctx.target;
+    if (!target || cleared.has(targetKey(target))) continue;
+    cleared.set(targetKey(target), (await ctx.run(clearCode(target)).catch(() => ({ ok: false }))).ok === true);
+  }
+  let all = true;
+  writeLedger(ctx.env, ctx.host, ctx.slot, entries.flatMap((entry) => {
+    if (!chosen.has(entry)) return [entry];
+    const target = targetOf(entry) ?? ctx.target;
+    if (target && cleared.get(targetKey(target)) === true) return [];
+    all = false;
+    return [{ ...entry, clear_pending: true }];
+  }));
+  return all;
+}
+
+// Drop entries whose browser is gone (crash, close, new launch).
+function dropGone(ctx, generation) {
+  const entries = readLedger(ctx.env, ctx.host, ctx.slot).entries;
+  const kept = entries.filter((entry) => generation && entry.generation === generation);
+  const dropped = entries.length - kept.length;
+  if (dropped) writeLedger(ctx.env, ctx.host, ctx.slot, kept);
+  return dropped;
+}
+
+function receipt(stdout, body) { safeWrite(stdout, `${JSON.stringify({ staging_auth: body }, null, 2)}\n`); }
+
+const GUIDED_FIELDS = ["message", "cause", "actor", "next", "doc", "help", "agentAction", "remedy"];
+
+/**
+ * Refuse with self-guiding text: the receipt (stdout) and the stderr block carry
+ * what happened, the likely cause, who acts, the exact next command and the doc.
+ * `extra` fields already rendered by the pool (an empty pool's health reason) win.
+ * `vars` are non-secret only: lane, persona alias, allowed aliases, checkout.
+ */
+/**
+ * ` --ticket BOT-123` from the checkout's branch name (`…/bot-123-…`), or "" so a
+ * lane-claim command never prints a <ticket> placeholder. Best effort, refusal-only.
+ */
+export function ticketFlagFor(cwd, { exec = execFileSync } = {}) {
+  try {
+    // symbolic-ref also names an unborn branch; a detached HEAD has no ticket.
+    const branch = String(exec("git", ["-C", cwd, "symbolic-ref", "--short", "-q", "HEAD"], { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] })).trim();
+    const match = /(?:^|[/_-])((?:bot|ent)-\d+)(?=$|[/_-])/i.exec(branch);
+    return match ? ` --ticket ${match[1].toUpperCase()}` : "";
+  } catch {
+    return "";
+  }
+}
+
+export function refuse({ stdout, stderr }, code, exitCode = 3, extra = {}, vars = {}) {
+  // A real refusal: never a <placeholder> (AC-8 follow-up).
+  const g = guidance(isKnownCode(code) ? code : "pool_take_failed", { consequence: "bb pw auth has no pool to take a session from", ...vars }, { real: true });
+  const guided = { message: g.message, cause: g.cause, actor: g.actor_label, next: g.next, doc: g.doc, help: g.help, agentAction: g.agent_action, remedy: remedyLine(g) };
+  for (const field of GUIDED_FIELDS) if (extra[field] !== undefined) guided[field] = extra[field];
+  const text = {
+    ...g, code: extra.reason && extra.reason !== code ? extra.reason : code,
+    message: guided.message, cause: guided.cause, next: guided.next, doc: guided.doc, help: guided.help,
+    actor_label: guided.actor, actor: guided.actor === g.actor_label ? g.actor : (/^Human/.test(guided.actor) ? "human" : "agent"),
+  };
+  safeWrite(stderr, `${formatGuidance(text, { prefix: "bb pw auth refused" })}\n`);
+  receipt(stdout, { ok: false, code, ...guided, source: SOURCE_NAME, ...Object.fromEntries(Object.entries(extra).filter(([key]) => !GUIDED_FIELDS.includes(key))) });
+  return exitCode;
+}
+
+async function loadPool() { return import("../staging-pool/cli.mjs"); }
+async function loadBinding() { return import("../staging-pool/binding.mjs"); }
+
+/**
+ * `auth --persona <alias>` after the wrapper has proven: environment=staging, a
+ * lock-gated lane held by this exact agent, and a staging (or untracked) browser
+ * session. Returns the process exit code.
+ */
+export async function runStagingAuth({ plan, host, env, deps, socketRun, resolveSession, stdout, stderr, holder = null }) {
+  const io = { stdout, stderr };
+  const poolModule = deps.stagingPoolModule ?? await loadPool();
+  const poolOptions = deps.stagingPool ?? {};
+  const cwd = deps.cwd ?? process.cwd();
+  const vars = { lane: plan.lane, persona: plan.persona, cwd, ticketFlag: ticketFlagFor(cwd) };
+  let found;
+  try {
+    found = await (await loadBinding()).readRepoPoolBinding(cwd);
+  } catch (error) {
+    return refuse(io, error?.code === "pool_binding_invalid" ? "pool_binding_invalid" : "pool_not_configured", 3, { detail: String(error?.message ?? error) }, vars);
+  }
+  if (!found) {
+    // Name a stable checkout that declares a pool, if this Mac has one on record.
+    const { findKnownCheckouts } = await import("../staging-pool/checkouts.mjs");
+    const [candidate] = await findKnownCheckouts({ ...(poolOptions.home ? { home: poolOptions.home } : {}), ...(poolOptions.isStableCheckout ? { isStable: poolOptions.isStableCheckout } : {}) }).catch(() => []);
+    return refuse(io, "pool_not_configured", 3, {}, { ...vars, checkout: candidate?.path });
+  }
+  Object.assign(vars, { allowed: Object.keys(found.binding.personas ?? {}) });
+  const { findPersona } = await loadBinding();
+  const persona = findPersona(found.binding, plan.persona);
+  if (!persona) return refuse(io, "persona_not_allowlisted", 2, {}, vars);
+  const { stagingTargetFromBinding } = await import("../staging-pool/policy.mjs");
+  const bound = stagingTargetFromBinding(found.binding);
+  // deps.stagingAuthTarget is a test-only seam (a loopback page for the real-daemon
+  // test); no flag or environment variable can redirect the install origin.
+  const target = deps.stagingAuthTarget ?? { origin: bound.appOrigin, storageKey: bound.storageKey };
+  const { session } = await resolveSession(plan.session, env);
+  if (!session) return refuse(io, "lane_browser_not_open", 2, {}, vars);
+  if (isPersistentLane(session)) return refuse(io, "persistent_profile_refused", 3, {}, vars);
+  const generation = generationOf(session);
+  const ctx = context({ plan, host, env, socketRun, target });
+  dropGone(ctx, generation);
+  let claim;
+  try {
+    claim = await poolModule.takeForLane({ persona: persona.email, owner: `lane-${plan.lane}@${host}`, cwd, ...poolOptions });
+  } catch (error) {
+    if (error?.code === "pool_empty") {
+      return refuse(io, "pool_empty", 3, Object.fromEntries(["reason", "detail", ...GUIDED_FIELDS].filter((key) => error[key] !== undefined).map((key) => [key, error[key]])), vars);
+    }
+    const code = typeof error?.code === "string" && isKnownCode(error.code) ? error.code : "pool_take_failed";
+    return refuse(io, code, 3, { detail: String(error?.message ?? error).slice(0, 300) }, vars);
+  }
+  let installed;
+  try {
+    installed = await ctx.run(installCode({ statePath: claim.taken.statePath, origin: target.origin, storageKey: target.storageKey, email: persona.email }));
+  } finally {
+    // Single use either way: the slot never outlives this command.
+    await claim.discard().catch(() => {});
+  }
+  const sessionRef = claim.taken.meta.sessionRef;
+  if (!installed.ok) {
+    // The install may have written storage before failing: clear that target
+    // (its key held at most one session, so any earlier entry for it goes too).
+    const entries = readLedger(env, host, plan.lane).entries;
+    writeLedger(env, host, plan.lane, [...entries, { session_ref: sessionRef, persona: persona.alias, generation, installed_at: new Date().toISOString(), origin: target.origin, storage_key: target.storageKey, holder }]);
+    const cleared = await clearBrowserOrMark(ctx, generation, (entry) => entry.origin === target.origin && entry.storage_key === target.storageKey);
+    return refuse(io, isKnownCode(installed.code) ? installed.code : "session_install_failed", 3, { cleared }, vars);
+  }
+  // Re-auth replaces the previous session under the same key: one entry per
+  // browser and target. Sessions for other origins in this browser stay tracked.
+  const others = readLedger(env, host, plan.lane).entries.filter((entry) => entry.generation === generation && !(entry.origin === target.origin && entry.storage_key === target.storageKey));
+  writeLedger(env, host, plan.lane, [...others, { session_ref: sessionRef, persona: persona.alias, generation, installed_at: new Date().toISOString(), origin: target.origin, storage_key: target.storageKey, access_expires_at: installed.access_expires_at, holder }]);
+  receipt(stdout, {
+    ok: true, source: SOURCE_NAME, environment: "staging", origin: target.origin, persona: persona.alias,
+    lane: plan.lane, host, aal: claim.taken.meta.aal, session_ref: sessionRef, access_expires_at: installed.access_expires_at,
+    path: installed.path, slot: "deleted after install",
+    on_close: "browser closed, no sign-out (the refresh lineage stays valid server-side; see docs/agent-staging-acceptance-mfa.md)",
+    ledger: ledgerPath(env, host, plan.lane),
+  });
+  return 0;
+}
+
+/**
+ * Before any other gate-passed lane command: drop entries whose browser is gone,
+ * settle a pending clear, and refuse while a same-browser clear is unresolved.
+ * Returns null to proceed, or an exit code to stop the command.
+ */
+export async function beforeLaneCommand({ plan, host, env, socketRun, resolveSession, stdout, stderr }) {
+  if (!readLedger(env, host, plan.lane).entries.length) return null;
+  const { session } = await resolveSession(plan.session, env).catch(() => ({ session: null }));
+  const generation = generationOf(session);
+  const ctx = context({ plan, host, env, socketRun, target: null });
+  dropGone(ctx, generation);
+  const pending = readLedger(env, host, plan.lane).entries.some((entry) => entry.clear_pending === true);
+  if (!pending) return null;
+  if (await clearBrowserOrMark(ctx, generation, (entry) => entry.clear_pending === true)) return null;
+  if (plan.verb === "close") return null;
+  return refuse({ stdout, stderr }, "staging_session_cleanup_pending", 3, { lane: plan.lane, host }, { lane: plan.lane });
+}
+
+/** After `close` (successful or not): a browser that survived is cleared, or its cleanup kept. */
+export async function afterLaneClose({ plan, host, env, socketRun, resolveSession, stderr }) {
+  if (!readLedger(env, host, plan.lane).entries.length) return;
+  const { session } = await resolveSession(plan.session, env).catch(() => ({ session: null }));
+  const generation = generationOf(session);
+  const ctx = context({ plan, host, env, socketRun, target: null });
+  const cleared = await clearBrowserOrMark(ctx, generation);
+  dropGone(ctx, generation);
+  safeWrite(stderr, `bb-pw: staging auth cleanup ${JSON.stringify({ browser: generation ? (cleared ? "cleared" : "clear_pending") : "closed", sign_out: "none" })}\n`);
+}
+
+/**
+ * The lane lock is provably no longer this agent's: clear the sessions THIS
+ * caller installed from the same browser. A session the current holder installed
+ * is not the stale caller's to clear (an entry with no recorded holder is).
+ */
+export async function onLaneAuthorityLost({ plan, host, env, socketRun, resolveSession, stderr, callerIds = [], resolveCallerId = null }) {
+  const recorded = readLedger(env, host, plan.lane).entries;
+  if (!recorded.length) return;
+  // A token-only caller has no local agent id; resolve it only when an entry needs it.
+  if (resolveCallerId && recorded.some((entry) => entry.holder && !callerIds.includes(entry.holder))) {
+    const me = await resolveCallerId().catch(() => null);
+    if (me) callerIds = [...callerIds, me];
+  }
+  const { session } = await resolveSession(plan.session, env).catch(() => ({ session: null }));
+  const generation = generationOf(session);
+  const ctx = context({ plan, host, env, socketRun, target: null });
+  dropGone(ctx, generation);
+  const mine = (entry) => !entry.holder || callerIds.includes(entry.holder);
+  const cleared = await clearBrowserOrMark(ctx, generation, mine);
+  safeWrite(stderr, `bb-pw: lane authority lost; staging auth cleanup ${JSON.stringify({ browser: generation ? (cleared ? "cleared" : "clear_pending") : "closed" })}\n`);
+}

package/src/staging-pool/binding.mjs

@@ -0,0 +1,122 @@
+// BOT-2084: the per-repo staging session pool binding.
+//
+// A repository opts in by declaring `staging_session_pool` in its committed
+// `.botbuddy-agent.json` (next to its tenant binding). This module parses and
+// validates that section into the camelCase shape the pool uses. Node-stdlib-only
+// and self-contained: the installed job keeps a validated snapshot in its config.
+
+import { readFile } from "node:fs/promises";
+import { dirname, join, parse } from "node:path";
+
+export const AGENT_BINDING_FILE = ".botbuddy-agent.json";
+
+export class BindingError extends Error {
+  constructor(message, code = "pool_binding_invalid") {
+    super(message);
+    this.name = "BindingError";
+    this.code = code;
+  }
+}
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const ALIAS_RE = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const EMAIL_RE = /^[a-z0-9._+-]+@[a-z0-9.-]+\.[a-z]{2,}$/i;
+const ENV_RE = /^[A-Z][A-Z0-9_]*$/;
+const LABEL_RE = /^[a-z0-9][a-z0-9.-]{2,127}$/;
+const STORAGE_KEY_RE = /^sb-[A-Za-z0-9-]{1,80}-auth-token$/;
+// Supabase publishable keys and legacy anon JWTs are public, browser-shipped values.
+const PUBLIC_KEY_RE = /^(sb_publishable_[A-Za-z0-9_-]{16,128}|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/;
+export const ADAPTERS = Object.freeze(["supabase-gotrue-totp"]);
+export const MAX_POOL_SIZE = 4;
+
+function need(condition, message) {
+  if (!condition) throw new BindingError(`${AGENT_BINDING_FILE} staging_session_pool: ${message}`);
+}
+
+// raw: the parsed .botbuddy-agent.json object. Returns null when the repo does not
+// opt in; throws BindingError on a present but invalid section (fail closed).
+export function parsePoolBinding(raw) {
+  const section = raw?.staging_session_pool;
+  if (section === undefined || section === null) return null;
+  need(typeof section === "object" && !Array.isArray(section), "must be an object");
+  need(section.schema_version === 1, "schema_version must be 1");
+  need(typeof raw.tenant === "string" && SLUG_RE.test(raw.tenant), "the binding's tenant slug is required (it pins get_totp_code)");
+  need(typeof section.pool_id === "string" && SLUG_RE.test(section.pool_id), "pool_id must be a lowercase slug");
+  need(section.environment === "staging", 'environment must be "staging"');
+  need(typeof section.app_slug === "string" && SLUG_RE.test(section.app_slug), "app_slug must be a lowercase slug");
+  need(ADAPTERS.includes(section.adapter), `adapter must be one of ${ADAPTERS.join(", ")}`);
+  need(typeof section.app_origin === "string", "app_origin is required");
+  need(typeof section.supabase_url === "string", "supabase_url is required");
+  need(typeof section.publishable_key === "string" && PUBLIC_KEY_RE.test(section.publishable_key), "publishable_key must be the public publishable/anon key");
+  need(typeof section.storage_key === "string" && STORAGE_KEY_RE.test(section.storage_key), "storage_key must be the app's supabase-js auth storage key");
+  need(Array.isArray(section.production_origins ?? []), "production_origins must be an array");
+  need(typeof section.password_env_file === "string" && /^(~\/|\/)/.test(section.password_env_file), "password_env_file must be an absolute or ~/ path");
+  need(typeof section.launchd_label === "string" && LABEL_RE.test(section.launchd_label), "launchd_label must be a reverse-DNS label");
+  need(typeof section.docs === "string" && section.docs.length > 0, "docs (where the pool is documented) is required");
+  need(typeof section.install_command === "string" && section.install_command.length > 0, "install_command (the human's install line) is required");
+  const personas = section.personas;
+  need(personas && typeof personas === "object" && Object.keys(personas).length > 0, "personas must name at least one persona");
+  const parsedPersonas = {};
+  const emails = new Set();
+  for (const [alias, persona] of Object.entries(personas)) {
+    need(ALIAS_RE.test(alias), `persona alias "${alias}" must be a short lowercase slug`);
+    need(persona && typeof persona.email === "string" && EMAIL_RE.test(persona.email), `persona ${alias} needs a seeded email`);
+    need(/\.(local|test)$/i.test(persona.email), `persona ${alias} must use a non-routable .local/.test seeded email`);
+    need(!emails.has(persona.email.toLowerCase()), `persona email ${persona.email} is listed twice`);
+    emails.add(persona.email.toLowerCase());
+    need(typeof persona.password_env === "string" && ENV_RE.test(persona.password_env), `persona ${alias} needs password_env (an UPPER_SNAKE env var name in password_env_file)`);
+    const count = persona.default_count ?? 1;
+    need(Number.isInteger(count) && count >= 0 && count <= MAX_POOL_SIZE, `persona ${alias} default_count must be 0-${MAX_POOL_SIZE}`);
+    parsedPersonas[alias] = Object.freeze({ alias, email: persona.email, passwordEnv: persona.password_env, defaultCount: count });
+  }
+  return Object.freeze({
+    tenant: raw.tenant,
+    poolId: section.pool_id,
+    environment: section.environment,
+    appSlug: section.app_slug,
+    adapter: section.adapter,
+    appOrigin: section.app_origin,
+    supabaseUrl: section.supabase_url,
+    publishableKey: section.publishable_key,
+    storageKey: section.storage_key,
+    productionOrigins: Object.freeze([...(section.production_origins ?? [])].map(String)),
+    passwordEnvFile: section.password_env_file,
+    personas: Object.freeze(parsedPersonas),
+    launchdLabel: section.launchd_label,
+    docs: section.docs,
+    installCommand: section.install_command,
+  });
+}
+
+// alias or email → persona entry; null when not allowlisted.
+export function findPersona(binding, aliasOrEmail) {
+  const key = String(aliasOrEmail ?? "");
+  if (Object.hasOwn(binding.personas, key)) return binding.personas[key];
+  return Object.values(binding.personas).find((persona) => persona.email === key) ?? null;
+}
+
+// Walk up from cwd to the committed binding file; null when none or no section.
+export async function readRepoPoolBinding(cwd = process.cwd(), { read = readFile } = {}) {
+  let dir = cwd;
+  const root = parse(dir).root;
+  while (true) {
+    let text = null;
+    try {
+      text = await read(join(dir, AGENT_BINDING_FILE), "utf8");
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    if (text !== null) {
+      let raw;
+      try {
+        raw = JSON.parse(text);
+      } catch {
+        throw new BindingError(`${AGENT_BINDING_FILE} is not valid JSON`);
+      }
+      const binding = parsePoolBinding(raw);
+      return binding ? { binding, repoRoot: dir } : null;
+    }
+    if (dir === root) return null;
+    dir = dirname(dir);
+  }
+}

package/src/staging-pool/checkouts.mjs

@@ -0,0 +1,120 @@
+// 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;
+}