@botbuddy/cli 1.60.5 → 1.60.6

package/src/staging-pool/cli.mjs

@@ -0,0 +1,482 @@
+// BOT-2084 (lifted from supplyspark-ent ENT-5120 cli.mjs): `bb staging-pool`, the
+// human-owned staging session pool broker.
+//
+//   install      install + start the launchd job (human only, from Terminal.app)
+//   uninstall    stop the job and delete its session files (human only)
+//   tick         refresh unclaimed slots, refill to K, purge old takes (job / human only)
+//   mint-one     one real sign-in into the pool (human only; spine check)
+//   status       metadata only, or --check for one health reason (anyone)
+//   probe        list_totp_seeds through the botbuddy CLI; never mints a code (anyone)
+//   print-plist  show the plist install would write (anyone)
+//
+// Agents take sessions only through `bb pw --environment staging <lane> auth`
+// (takeForLane below): a session is handed over by installing it into a claimed
+// lane, never as a reusable file path. The configuration is the repo's committed
+// `.botbuddy-agent.json` `staging_session_pool` binding; the installed job keeps a
+// validated snapshot. Node-stdlib-only and self-contained (install copies this
+// directory to <pool home>/app and the job runs that copy).
+
+import { execFile } from "node:child_process";
+import * as nodeFs from "node:fs/promises";
+import { readFileSync, realpathSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+import { BindingError, findPersona, readRepoPoolBinding } from "./binding.mjs";
+import { ConfigError, DEFAULT_INTERVAL_SECONDS, buildInstalledConfig, poolHomePaths, readInstalledConfig, serialiseInstalledConfig } from "./config.mjs";
+import { assessPoolHealth, healthReasons } from "./health.mjs";
+import { buildLaunchAgentPlist, createLaunchctl } from "./launchd.mjs";
+import { createEnvFilePasswordSource } from "./password-source.mjs";
+import { MintRefusedError, assertMintAllowed, assertPersonaAllowed, listProcessAncestors, stagingTargetFromBinding } from "./policy.mjs";
+import { PoolEmptyError, createSessionPool } from "./pool.mjs";
+import { createGoTrueTotpSignIn } from "./signin-gotrue-totp.mjs";
+import { createRedactor } from "./state-file.mjs";
+import { createBotBuddyTotpProvider, probeBotBuddy } from "./totp-botbuddy.mjs";
+import { formatGuidance, guidance, isKnownCode, remedyLine } from "./errors.mjs";
+import { STAGING_POOL_HELP } from "./help.mjs";
+
+export const BUNDLE_FILES = Object.freeze([
+  "binding.mjs",
+  "cli.mjs",
+  "config.mjs",
+  "errors.mjs",
+  "health.mjs",
+  "help.mjs",
+  "job.mjs",
+  "launchd.mjs",
+  "password-source.mjs",
+  "policy.mjs",
+  "pool.mjs",
+  "signin-gotrue-totp.mjs",
+  "state-file.mjs",
+  "totp-botbuddy.mjs",
+]);
+
+const VALUE_FLAGS = new Set(["persona", "home", "botbuddy-bin", "interval", "owner"]);
+const BOOLEAN_FLAGS = new Set(["keep-sessions", "help", "check"]);
+
+export function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const options = {};
+  for (let index = 0; index < rest.length; index += 1) {
+    const token = rest[index];
+    if (!token.startsWith("--")) throw new ConfigError(`Unexpected argument ${token}.`, "usage");
+    const [flag, inline] = token.slice(2).split(/=(.*)/s, 2);
+    if (BOOLEAN_FLAGS.has(flag)) {
+      options[flag] = true;
+      continue;
+    }
+    if (!VALUE_FLAGS.has(flag)) throw new ConfigError(`Unknown flag --${flag}.`, "usage");
+    const value = inline ?? rest[(index += 1)];
+    if (value === undefined || value === "") throw new ConfigError(`--${flag} needs a value.`, "usage");
+    options[flag] = value;
+  }
+  return { command, options };
+}
+
+export function exitCodeFor(error) {
+  if (error instanceof MintRefusedError || error?.code === "persona_not_allowed") return 2;
+  if (error instanceof PoolEmptyError) return 3;
+  if (error instanceof ConfigError || error instanceof BindingError || error?.code === "config_missing") return 4;
+  if (error?.code === "pool_unhealthy") return 5;
+  return 1;
+}
+
+// Where this invocation's pool lives: the job passes --home; everyone else
+// resolves it from the repo binding (cwd).
+async function resolveContext({ options, cwd, home, readBinding = readRepoPoolBinding }) {
+  if (options.home) {
+    const paths = poolHomePaths({ home, root: options.home });
+    const config = readInstalledConfig(paths.config);
+    return { paths, poolBinding: config.poolBinding, installed: config, rawBinding: config.binding };
+  }
+  const found = await readBinding(cwd);
+  if (!found) {
+    throw new ConfigError("This repository declares no staging_session_pool in .botbuddy-agent.json, so it has no staging session pool.", "pool_not_configured");
+  }
+  const paths = poolHomePaths({ home, poolId: found.binding.poolId });
+  let installed = null;
+  try {
+    installed = readInstalledConfig(paths.config);
+  } catch (error) {
+    if (error?.code !== "config_missing") installed = { error };
+  }
+  return { paths, poolBinding: found.binding, installed, repoRoot: found.repoRoot };
+}
+
+const shellWord = (value) => (/^[A-Za-z0-9_./:@,=~+-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`);
+export const installCommandFor = (repoRoot, fallback) =>
+  repoRoot ? `cd ${shellWord(repoRoot)} && bb staging-pool install --botbuddy-bin "$(command -v botbuddy)"` : fallback;
+
+// The non-secret values every guidance template may name.
+export function guidanceVars(ctx, extra = {}) {
+  if (!ctx) return { ...extra };
+  return {
+    label: ctx.poolBinding.launchdLabel,
+    log: ctx.paths.log,
+    installCommand: installCommandFor(ctx.repoRoot, ctx.poolBinding.installCommand),
+    docs: ctx.poolBinding.docs,
+    configPath: ctx.paths.config,
+    poolHome: ctx.paths.root,
+    tickCommand: `bb staging-pool tick --home ${shellWord(ctx.paths.root)}`,
+    checkout: ctx.repoRoot,
+    envFile: ctx.poolBinding.passwordEnvFile,
+    allowed: Object.keys(ctx.poolBinding.personas ?? {}),
+    ...extra,
+  };
+}
+
+function reasonsFor(ctx) {
+  return healthReasons(guidanceVars(ctx));
+}
+
+function buildPool({ ctx, target, signIn, now, logger, intervalSeconds, fetchImpl, sleep }) {
+  return createSessionPool({
+    poolDir: ctx.paths.pool,
+    target,
+    signIn: signIn ?? createGoTrueTotpSignIn({
+      fetchImpl,
+      totpProvider: async () => {
+        throw new Error("take/status never mint");
+      },
+      passwordFor: async () => {
+        throw new Error("take/status never mint");
+      },
+      logger,
+      sleep,
+      nowMs: now,
+    }),
+    now,
+    logger,
+    ...(intervalSeconds ? { intervalMs: intervalSeconds * 1000 } : {}),
+    tickIntervalHint: intervalSeconds ? ` (every ${Math.round(intervalSeconds / 60)} min)` : "",
+  });
+}
+
+export async function assessHealth({ ctx, pool, now, exec, uid, requestedPersona }) {
+  const reasons = reasonsFor(ctx);
+  if (!ctx.installed) {
+    return assessPoolHealth({ reasons, jobLoaded: false, status: null, personas: {}, intervalSeconds: DEFAULT_INTERVAL_SECONDS, nowMs: now() });
+  }
+  if (ctx.installed.error) {
+    return assessPoolHealth({ reasons, configError: String(ctx.installed.error.message), status: null, personas: {}, intervalSeconds: DEFAULT_INTERVAL_SECONDS, nowMs: now() });
+  }
+  const jobLoaded = await createLaunchctl({ exec, uid }).isLoaded(ctx.poolBinding.launchdLabel);
+  return {
+    ...assessPoolHealth({
+      reasons,
+      status: await pool.status(),
+      personas: ctx.installed.personas,
+      intervalSeconds: ctx.installed.intervalSeconds,
+      nowMs: now(),
+      jobLoaded,
+      requestedPersona,
+    }),
+    intervalSeconds: ctx.installed.intervalSeconds,
+  };
+}
+
+/**
+ * Agent path, used by `bb pw … auth`: claim one verified session for a persona
+ * (alias or email) of this repo's binding. Returns { taken, target, binding,
+ * discard } — the caller installs taken.statePath into its claimed lane and then
+ * MUST call discard() (single use). Throws PoolEmptyError carrying the health
+ * reason/agentAction/remedy when nothing is ready.
+ */
+export async function takeForLane({
+  persona,
+  owner,
+  cwd = process.cwd(),
+  home = homedir(),
+  now = () => Date.now(),
+  fetchImpl = globalThis.fetch,
+  exec = promisify(execFile),
+  uid = userInfo().uid,
+  logger = () => {},
+  readBinding = readRepoPoolBinding,
+} = {}) {
+  const ctx = await resolveContext({ options: {}, cwd, home, readBinding });
+  const entry = findPersona(ctx.poolBinding, persona);
+  const target = stagingTargetFromBinding(ctx.poolBinding);
+  if (!entry) assertPersonaAllowed(target, persona);
+  const intervalSeconds = ctx.installed && !ctx.installed.error ? ctx.installed.intervalSeconds : undefined;
+  const pool = buildPool({ ctx, target, now, logger, intervalSeconds, fetchImpl });
+  try {
+    const taken = await pool.take({ persona: entry.email, owner });
+    return { taken, target, binding: ctx.poolBinding, persona: entry, discard: () => pool.discardTaken(taken.slotId) };
+  } catch (error) {
+    if (!(error instanceof PoolEmptyError)) throw error;
+    const health = await assessHealth({ ctx, pool, now, exec, uid, requestedPersona: entry.email });
+    let effective = health;
+    if (health.ok) {
+      const g = guidance("pool_empty", guidanceVars(ctx, { persona: entry.alias }));
+      effective = { ...health, reason: "pool_empty", agentAction: g.agent_action, remedy: remedyLine(g), message: g.message, cause: g.cause, actor: g.actor_label, next: g.next, doc: g.doc, help: g.help };
+    }
+    for (const field of GUIDANCE_FIELDS) if (effective[field] !== undefined) error[field] = effective[field];
+    throw error;
+  }
+}
+
+// Fields a refusal carries so a caller can act on it without reading the code.
+export const GUIDANCE_FIELDS = Object.freeze(["reason", "agentAction", "remedy", "message", "cause", "actor", "next", "doc", "help", "detail", "intervalSeconds"]);
+
+// The human-only command line to repeat from Terminal.app (no secrets: flags only).
+function humanCommandLine(argv) {
+  if (argv[0] === "install") return 'install --botbuddy-bin "$(command -v botbuddy)"';
+  return argv.map((token) => (/^[A-Za-z0-9_./:=@-]+$/.test(token) ? token : `'${token.replace(/'/g, "'\\''")}'`)).join(" ");
+}
+
+export async function runStagingPool(argv, deps = {}) {
+  const {
+    env = process.env,
+    stdout = (line) => process.stdout.write(`${line}\n`),
+    stderr = (line) => process.stderr.write(`${line}\n`),
+    cwd = process.cwd(),
+    home = homedir(),
+    uid = userInfo().uid,
+    exec = promisify(execFile),
+    listAncestors = listProcessAncestors,
+    fetchImpl = globalThis.fetch,
+    fs = nodeFs,
+    now = () => Date.now(),
+    scriptDir = dirname(fileURLToPath(import.meta.url)),
+    nodeBin = process.execPath,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    readBinding = readRepoPoolBinding,
+    readSecretFile = readFileSync,
+  } = deps;
+
+  const redactor = createRedactor();
+  const emit = (record) => stdout(JSON.stringify(redactor.redact({ ts: new Date(now()).toISOString(), ...record })));
+
+  function minterFor(ctx, target) {
+    const binding = ctx.poolBinding;
+    const botbuddyBin = ctx.installed?.botbuddyBin;
+    if (!botbuddyBin) throw new ConfigError("The pool job is not installed (no botbuddyBin); the human runs the install first.", "pool_not_installed");
+    const password = createEnvFilePasswordSource({ envFile: binding.passwordEnvFile, personas: binding.personas, home, read: readSecretFile });
+    // Register the password with the redactor before any log line can carry it.
+    const passwordFor = async (args) => {
+      const value = await password(args);
+      redactor.register(value);
+      return value;
+    };
+    return createGoTrueTotpSignIn({
+      fetchImpl,
+      totpProvider: createBotBuddyTotpProvider({ exec, botbuddyBin, env, tenant: binding.tenant, appSlug: binding.appSlug }),
+      passwordFor,
+      logger: emit,
+      sleep,
+      nowMs: now,
+    });
+  }
+
+  function requireBotbuddyBin(options) {
+    const bin = options["botbuddy-bin"];
+    if (!bin) throw new ConfigError('install needs --botbuddy-bin "$(command -v botbuddy)".', "botbuddy_bin_required");
+    if (!bin.startsWith("/")) throw new ConfigError("--botbuddy-bin must be an absolute path.", "botbuddy_bin_required");
+    // fnm's per-shell PATH dirs disappear with the shell; the job outlives it.
+    return realpathSync(bin);
+  }
+
+  async function copyBundle(destination) {
+    await fs.mkdir(destination, { recursive: true, mode: 0o700 });
+    for (const file of BUNDLE_FILES) {
+      await fs.copyFile(join(scriptDir, file), join(destination, file));
+      await fs.chmod(join(destination, file), 0o600);
+    }
+    // The bundle is ESM; mark it so whatever package.json sits above the pool home is irrelevant.
+    await fs.writeFile(join(destination, "package.json"), '{ "type": "module" }\n', { mode: 0o600 });
+  }
+
+  function jobPlist(ctx, intervalSeconds) {
+    return buildLaunchAgentPlist({
+      label: ctx.poolBinding.launchdLabel,
+      programArguments: [nodeBin, join(ctx.paths.app, "job.mjs"), "tick", "--home", ctx.paths.root],
+      environment: { PATH: `${dirname(nodeBin)}:/usr/bin:/bin`, HOME: home },
+      workingDirectory: ctx.paths.root,
+      intervalSeconds,
+      stdoutPath: ctx.paths.log,
+      stderrPath: ctx.paths.log,
+    });
+  }
+
+  const commands = {
+    async install(options) {
+      const ctx = await resolveContext({ options: {}, cwd, home, readBinding });
+      const target = stagingTargetFromBinding(ctx.poolBinding);
+      assertMintAllowed({ target, env, listAncestors });
+      const botbuddyBin = requireBotbuddyBin(options);
+      for (const dir of [ctx.paths.root, ctx.paths.logDir]) {
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+        await fs.chmod(dir, 0o700);
+      }
+      await copyBundle(ctx.paths.app);
+      const rawBinding = JSON.parse(await fs.readFile(join(ctx.repoRoot, ".botbuddy-agent.json"), "utf8"));
+      let existing = null;
+      try {
+        existing = JSON.parse(await fs.readFile(ctx.paths.config, "utf8"));
+      } catch (error) {
+        if (error?.code !== "ENOENT") throw error;
+      }
+      const explicitInterval = options.interval === undefined ? undefined : Number(options.interval);
+      const config = buildInstalledConfig({
+        rawBinding,
+        poolBinding: ctx.poolBinding,
+        botbuddyBin,
+        intervalSeconds: explicitInterval ?? existing?.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS,
+        existingPersonas: existing?.personas,
+      });
+      await fs.writeFile(ctx.paths.config, serialiseInstalledConfig(config), { mode: 0o600 });
+      await fs.chmod(ctx.paths.config, 0o600);
+      const plistPath = join(ctx.paths.plistDir, `${ctx.poolBinding.launchdLabel}.plist`);
+      await fs.mkdir(ctx.paths.plistDir, { recursive: true });
+      await fs.writeFile(plistPath, jobPlist(ctx, config.intervalSeconds), { mode: 0o644 });
+      const launchctl = createLaunchctl({ exec, uid });
+      await launchctl.bootout(ctx.poolBinding.launchdLabel);
+      await launchctl.bootstrap(plistPath);
+      emit({
+        ok: true,
+        command: "install",
+        label: ctx.poolBinding.launchdLabel,
+        plistPath,
+        poolHome: ctx.paths.root,
+        log: ctx.paths.log,
+        intervalSeconds: config.intervalSeconds,
+        personas: config.personas,
+        next: "bb staging-pool status --check   # the pool fills within one tick",
+      });
+      return 0;
+    },
+
+    async uninstall(options) {
+      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const target = stagingTargetFromBinding(ctx.poolBinding);
+      // The job and its sessions are the human's: an agent never stops or empties them.
+      assertMintAllowed({ target, env, listAncestors });
+      const launchctl = createLaunchctl({ exec, uid });
+      const wasLoaded = await launchctl.bootout(ctx.poolBinding.launchdLabel);
+      await fs.rm(join(ctx.paths.plistDir, `${ctx.poolBinding.launchdLabel}.plist`), { force: true });
+      let removedSessions = 0;
+      if (!options["keep-sessions"]) removedSessions = await buildPool({ ctx, target, now, logger: emit, fetchImpl, sleep }).purge();
+      emit({ ok: true, command: "uninstall", label: ctx.poolBinding.launchdLabel, wasLoaded, removedSessions });
+      return 0;
+    },
+
+    async tick(options) {
+      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const target = stagingTargetFromBinding(ctx.poolBinding);
+      assertMintAllowed({ target, env, listAncestors });
+      if (!ctx.installed || ctx.installed.error) throw ctx.installed?.error ?? new ConfigError("The pool job is not installed; the human runs the install first.", "pool_not_installed");
+      const pool = buildPool({ ctx, target, signIn: minterFor(ctx, target), now, logger: emit, intervalSeconds: ctx.installed.intervalSeconds, fetchImpl, sleep });
+      const summary = await pool.tick({ personas: ctx.installed.personas });
+      return summary.mintFailures > 0 ? 1 : 0;
+    },
+
+    async "mint-one"(options) {
+      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const target = stagingTargetFromBinding(ctx.poolBinding);
+      assertMintAllowed({ target, env, listAncestors });
+      const entry = findPersona(ctx.poolBinding, options.persona);
+      const persona = entry ? entry.email : assertPersonaAllowed(target, options.persona);
+      if (!ctx.installed || ctx.installed.error) throw ctx.installed?.error ?? new ConfigError("The pool job is not installed; the human runs the install first.", "pool_not_installed");
+      const pool = buildPool({ ctx, target, signIn: minterFor(ctx, target), now, logger: emit, intervalSeconds: ctx.installed.intervalSeconds, fetchImpl, sleep });
+      const minted = await pool.mintOne({ persona });
+      emit({ ok: true, command: "mint-one", target: target.name, signIns: 1, ...minted.meta });
+      return 0;
+    },
+
+    async status(options) {
+      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const target = stagingTargetFromBinding(ctx.poolBinding);
+      const pool = buildPool({ ctx, target, now, logger: emit, fetchImpl, sleep });
+      if (options.check) {
+        const entry = options.persona ? findPersona(ctx.poolBinding, options.persona) : null;
+        if (options.persona && !entry) assertPersonaAllowed(target, options.persona);
+        const health = await assessHealth({ ctx, pool, now, exec, uid, requestedPersona: entry?.email });
+        emit({ command: "status", check: true, ...health });
+        return health.ok ? 0 : 5;
+      }
+      emit({ ok: true, command: "status", ...(await pool.status()) });
+      return 0;
+    },
+
+    async probe(options) {
+      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const botbuddyBin = options["botbuddy-bin"] ?? ctx.installed?.botbuddyBin;
+      if (!botbuddyBin) throw new ConfigError('probe needs --botbuddy-bin "$(command -v botbuddy)" (or an installed job).', "pool_not_installed");
+      const receipt = await probeBotBuddy({
+        exec,
+        botbuddyBin,
+        env,
+        tenant: ctx.poolBinding.tenant,
+        appSlug: ctx.poolBinding.appSlug,
+        environment: ctx.poolBinding.environment,
+        personaEmails: Object.values(ctx.poolBinding.personas).map((persona) => persona.email),
+      });
+      emit({ command: "probe", ...receipt });
+      return receipt.ok ? 0 : 5;
+    },
+
+    async "print-plist"(options) {
+      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      stdout(jobPlist(ctx, Number(options.interval ?? ctx.installed?.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS)));
+      return 0;
+    },
+  };
+
+  // One JSON line (machine-readable) then the same guidance as text, on stderr.
+  async function fail(command, error, options = {}) {
+    const code = typeof error?.code === "string" && isKnownCode(error.code) ? error.code : "unexpected_error";
+    let ctx = null;
+    try {
+      ctx = await resolveContext({ options, cwd, home, readBinding });
+    } catch {
+      ctx = null;
+    }
+    const persona = options.persona ?? error?.persona;
+    const vars = guidanceVars(ctx, {
+      persona,
+      command: humanCommandLine(argv),
+      markers: Array.isArray(error?.markers) ? error.markers.join(", ") : undefined,
+      checkout: ctx?.repoRoot ?? cwd,
+      retry: `bb staging-pool ${humanCommandLine(argv)}`,
+    });
+    const g = guidance(code, vars);
+    const record = {
+      ok: false, command, code, message: g.message, cause: g.cause, actor: g.actor_label, next: g.next,
+      agentAction: g.agent_action, doc: g.doc, help: g.help, detail: String(error?.message ?? error ?? "").slice(0, 500),
+    };
+    // A pool refusal already carries its health guidance (pool_empty / unhealthy).
+    for (const field of GUIDANCE_FIELDS) if (error?.[field] !== undefined) record[field] = error[field];
+    record.remedy ??= remedyLine(g);
+    stderr(JSON.stringify(redactor.redact({ ts: new Date(now()).toISOString(), ...record })));
+    // An empty pool is explained by its health reason (e.g. job_not_loaded).
+    const text = typeof error?.reason === "string" && error.reason !== code && isKnownCode(error.reason) ? guidance(error.reason, vars) : g;
+    stderr(redactor.redact(formatGuidance(text)));
+    return exitCodeFor(error);
+  }
+
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (error) {
+    await fail(argv[0] ?? null, Object.assign(error, { code: "usage" }));
+    return 4;
+  }
+  if (parsed.command === undefined || parsed.command === "help" || parsed.command === "--help" || parsed.command === "-h" || parsed.options.help) {
+    stdout(STAGING_POOL_HELP);
+    return 0;
+  }
+  const handler = commands[parsed.command];
+  if (!handler) {
+    await fail(parsed.command, new ConfigError(`Unknown subcommand ${parsed.command}.`, "usage"));
+    return 4;
+  }
+  try {
+    return await handler(parsed.options);
+  } catch (error) {
+    return fail(parsed.command, error, parsed.options);
+  }
+}

package/src/staging-pool/config.mjs

@@ -0,0 +1,107 @@
+// BOT-2084 (lifted from supplyspark-ent ENT-5120 config.mjs): pool home layout and
+// the installed job's config. Node-stdlib-only and self-contained.
+//
+// ~/.botbuddy/staging-session-pool/<pool_id>/   (0700)
+//   config.json   binding snapshot + persona counts, botbuddy CLI path, tick interval
+//   app/          the installed copy of these modules (the job never runs from a worktree)
+//   pool/         ready/ work/ taken/ (see pool.mjs)
+//   log/pool.log  the job's redacted JSON-lines log
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { MAX_POOL_SIZE, parsePoolBinding } from "./binding.mjs";
+
+export class ConfigError extends Error {
+  constructor(message, code = "config_missing") {
+    super(message);
+    this.name = "ConfigError";
+    this.code = code;
+  }
+}
+
+export const DEFAULT_INTERVAL_SECONDS = 300;
+
+export function poolHomePaths({ home = homedir(), poolId, root } = {}) {
+  const base = root ?? join(home, ".botbuddy", "staging-session-pool", String(poolId));
+  return {
+    root: base,
+    config: join(base, "config.json"),
+    app: join(base, "app"),
+    pool: join(base, "pool"),
+    logDir: join(base, "log"),
+    log: join(base, "log", "pool.log"),
+    plistDir: join(home, "Library", "LaunchAgents"),
+  };
+}
+
+// The installed config: { version, binding: <raw .botbuddy-agent.json subset>,
+// personas: { email: count }, botbuddyBin, intervalSeconds }. Returns it with the
+// parsed binding attached as `poolBinding`.
+export function validateInstalledConfig(config) {
+  if (!config || typeof config !== "object") throw new ConfigError("Pool config is not an object.", "config_invalid");
+  if (config.version !== 1) throw new ConfigError("Pool config version must be 1.", "config_invalid");
+  let poolBinding;
+  try {
+    poolBinding = parsePoolBinding(config.binding);
+  } catch (error) {
+    throw new ConfigError(`Pool config binding is invalid: ${error.message}`, "config_invalid");
+  }
+  if (!poolBinding) throw new ConfigError("Pool config has no staging_session_pool binding.", "config_invalid");
+  if (typeof config.botbuddyBin !== "string" || !config.botbuddyBin.startsWith("/")) {
+    throw new ConfigError("Pool config botbuddyBin must be an absolute path (re-run install).", "config_invalid");
+  }
+  if (!Number.isInteger(config.intervalSeconds) || config.intervalSeconds < 60 || config.intervalSeconds > 3600) {
+    throw new ConfigError("Pool config intervalSeconds must be an integer 60-3600.", "config_invalid");
+  }
+  const allowed = new Set(Object.values(poolBinding.personas).map((persona) => persona.email));
+  const personas = config.personas;
+  if (!personas || typeof personas !== "object" || Object.keys(personas).length === 0) {
+    throw new ConfigError("Pool config personas must name at least one persona.", "config_invalid");
+  }
+  for (const [persona, count] of Object.entries(personas)) {
+    if (!allowed.has(persona)) throw new ConfigError(`Pool config persona ${persona} is not allowlisted by the binding.`, "config_invalid");
+    if (!Number.isInteger(count) || count < 0 || count > MAX_POOL_SIZE) {
+      throw new ConfigError(`Pool size for ${persona} must be an integer 0-${MAX_POOL_SIZE}.`, "config_invalid");
+    }
+  }
+  return { ...config, poolBinding };
+}
+
+export function readInstalledConfig(path, { readFile = readFileSync } = {}) {
+  let text;
+  try {
+    text = readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") throw new ConfigError(`Pool config ${path} is missing: the pool job is not installed.`, "config_missing");
+    throw error;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new ConfigError(`Pool config ${path} is not valid JSON.`, "config_invalid");
+  }
+  return validateInstalledConfig(parsed);
+}
+
+// rawBinding: { tenant, staging_session_pool } exactly as committed.
+export function buildInstalledConfig({ rawBinding, poolBinding, botbuddyBin, intervalSeconds = DEFAULT_INTERVAL_SECONDS, existingPersonas }) {
+  const personas = {};
+  for (const persona of Object.values(poolBinding.personas)) {
+    personas[persona.email] = Number.isInteger(existingPersonas?.[persona.email]) ? existingPersonas[persona.email] : persona.defaultCount;
+  }
+  return validateInstalledConfig({
+    version: 1,
+    binding: { tenant: rawBinding.tenant, staging_session_pool: rawBinding.staging_session_pool },
+    personas,
+    botbuddyBin,
+    intervalSeconds,
+  });
+}
+
+export function serialiseInstalledConfig(config) {
+  const { poolBinding: _parsed, ...rest } = config;
+  return `${JSON.stringify(rest, null, 2)}\n`;
+}