@botbuddy/cli 1.60.5 → 1.60.7

package/src/staging-pool/pool.mjs

@@ -0,0 +1,666 @@
+// BOT-2084 (lifted from supplyspark-ent ENT-5120 pool.mjs): a small pool of
+// single-use, signed-in session files.
+//
+// Node-stdlib-only and self-contained; every side effect (sign-in, clock,
+// logging, liveness of a lock holder) is injected. The persona allowlist is the
+// target's (policy.mjs, from the repo binding).
+//
+// Layout under poolDir (dir 0700, files 0600):
+//   ready/<slot>/{state.json,meta.json}  warm sessions; `take` only ever looks here
+//   work/<slot>/                         held by the job while it mints or refreshes
+//   taken/<slot>/                        handed to one agent; never returned
+//   tick.lock, last-tick.json, health.json (backoff + below-target streaks)
+//
+// Every ownership change is one rename(2) of a slot directory, which is atomic on a
+// single filesystem: exactly one of two racing takers — or a taker and the job's
+// refresh — wins, so no two browsers ever hold the same refresh token.
+
+import { randomBytes } from "node:crypto";
+import * as nodeFs from "node:fs/promises";
+import { join } from "node:path";
+
+import { nextMintBackoffMs } from "./health.mjs";
+import { assertPersonaAllowed } from "./policy.mjs";
+import {
+  assertStorageStateClean,
+  buildStorageState,
+  describeStoredSession,
+} from "./state-file.mjs";
+
+export class PoolEmptyError extends Error {
+  constructor(persona, intervalHint) {
+    super(
+      `No ready ${persona} session in the pool. The human-owned pool job refills on its next tick${intervalHint}; ` +
+        "report this blocker and its remedy once, then stop; ask the human to check the job. " +
+        "Agents never sign in to staging themselves.",
+    );
+    this.name = "PoolEmptyError";
+    this.code = "pool_empty";
+  }
+}
+
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+// Lock liveness is a heartbeat, not a PID (Codex R13): a running tick touches tick.lock every
+// lockHeartbeatMs; a lock whose mtime is older than this has no live holder, whatever its
+// recorded PID now belongs to (PID reuse after a crash or reboot) and whether or not its JSON
+// was ever written (a writer that died between create and write).
+const STALE_LOCK_HEARTBEAT_MS = 5 * 60_000;
+
+const personaKey = (persona) => persona.replace(/[^A-Za-z0-9]+/g, "_");
+
+function defaultIsPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+export function createSessionPool({
+  poolDir,
+  target,
+  signIn,
+  fs = nodeFs,
+  now = () => Date.now(),
+  logger = () => {},
+  randomId = () => randomBytes(6).toString("hex"),
+  isPidAlive = defaultIsPidAlive,
+  pid = process.pid,
+  refreshAfterMs = 30 * 60_000,
+  minAccessRemainingMs = 10 * 60_000,
+  takenTtlMs = 60 * 60_000,
+  intervalMs = 300_000,
+  lockHeartbeatMs = 30_000,
+  tickIntervalHint = "",
+} = {}) {
+  if (!poolDir) throw new Error("createSessionPool needs poolDir.");
+  if (!target) throw new Error("createSessionPool needs a resolved mint target.");
+  if (!signIn) throw new Error("createSessionPool needs a signIn recipe.");
+
+  const dirs = {
+    ready: join(poolDir, "ready"),
+    work: join(poolDir, "work"),
+    taken: join(poolDir, "taken"),
+  };
+  const lockPath = join(poolDir, "tick.lock");
+  const lastTickPath = join(poolDir, "last-tick.json");
+  const healthPath = join(poolDir, "health.json");
+
+  async function readHealth() {
+    try {
+      const health = await readJson(healthPath);
+      return { lastSuccessfulTickAt: health.lastSuccessfulTickAt ?? null, personas: health.personas ?? {} };
+    } catch {
+      return { lastSuccessfulTickAt: null, personas: {} };
+    }
+  }
+
+  async function ensureDir(path) {
+    await fs.mkdir(path, { recursive: true, mode: DIR_MODE });
+    await fs.chmod(path, DIR_MODE);
+  }
+
+  // A pool dir belongs to exactly one target (Codex R5): every operation first checks the
+  // binding, so a mistyped --pool-dir can never take, refresh or prune another target's slots.
+  const bindingPath = join(poolDir, "pool-target.json");
+  async function ensureLayout() {
+    await ensureDir(poolDir);
+    const binding = {
+      target: target.name,
+      appOrigin: target.appOrigin,
+      supabaseUrl: target.supabaseUrl,
+      storageKey: target.storageKey,
+    };
+    try {
+      await writeFileExclusive(bindingPath, `${JSON.stringify(binding)}\n`);
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      let existing = null;
+      try {
+        existing = await readJson(bindingPath);
+      } catch {
+        existing = null;
+      }
+      if (Object.keys(binding).some((key) => existing?.[key] !== binding[key])) {
+        throw Object.assign(
+          new Error(
+            `Pool ${poolDir} belongs to ${existing?.target ?? "an unknown target"} (${existing?.appOrigin ?? "?"}, ${existing?.supabaseUrl ?? "?"}), not ${binding.target} (${binding.appOrigin}, ${binding.supabaseUrl}). Use that pool's own target or another --pool-dir.`,
+          ),
+          { code: "pool_target_mismatch" },
+        );
+      }
+    }
+    for (const dir of Object.values(dirs)) await ensureDir(dir);
+  }
+
+  async function list(dir) {
+    try {
+      return (await fs.readdir(dir)).filter((name) => !name.startsWith("."));
+    } catch (error) {
+      if (error?.code === "ENOENT") return [];
+      throw error;
+    }
+  }
+
+  // true = this caller now owns `to`; false = someone else moved it first.
+  async function claim(from, to) {
+    try {
+      await fs.rename(from, to);
+      return true;
+    } catch (error) {
+      if (error?.code === "ENOENT") return false;
+      throw error;
+    }
+  }
+
+  async function writeFileExclusive(path, data) {
+    await fs.writeFile(path, data, { mode: FILE_MODE, flag: "wx" });
+    await fs.chmod(path, FILE_MODE);
+  }
+
+  async function replaceFile(path, data) {
+    const next = `${path}.next`;
+    await fs.rm(next, { force: true });
+    await writeFileExclusive(next, data);
+    await fs.rename(next, path);
+  }
+
+  async function readJson(path) {
+    return JSON.parse(await fs.readFile(path, "utf8"));
+  }
+
+  async function readSlot(dir) {
+    const state = await readJson(join(dir, "state.json"));
+    const storedSession = assertStorageStateClean(state, target);
+    const meta = await readJson(join(dir, "meta.json"));
+    return { storedSession, meta };
+  }
+
+  function buildMeta({ persona, slotId, storedSession, mintedAt, refreshCount }) {
+    const session = describeStoredSession(storedSession, { nowMs: now() });
+    return {
+      slotId,
+      persona,
+      target: target.name,
+      appOrigin: target.appOrigin,
+      mintedAt,
+      verifiedAt: new Date(now()).toISOString(),
+      refreshCount,
+      aal: session.aal,
+      amr: session.amr,
+      accessExpiresAt: session.accessExpiresAt,
+      sessionRef: session.sessionRef,
+    };
+  }
+
+  async function writeSlotFiles(dir, { storedSession, meta, replace }) {
+    const state = buildStorageState({ target, storedSession });
+    assertStorageStateClean(state, target);
+    const write = replace ? replaceFile : writeFileExclusive;
+    await write(join(dir, "state.json"), `${JSON.stringify(state)}\n`);
+    await write(join(dir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`);
+  }
+
+  async function removeSlot(dir) {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+
+  // Tick lock (Codex R6): each holder writes a unique token. A stale lock is reclaimed by
+  // renaming it to a private tombstone and checking the tombstone is the holder judged stale;
+  // if a fresh holder replaced it in between, the tombstone is linked back and this tick skips.
+  // Release unlinks only a lock that still carries this tick's own token.
+  let heldToken = null;
+
+  async function readLock(path) {
+    try {
+      return await readJson(path);
+    } catch {
+      return null;
+    }
+  }
+
+  // File age uses the real wall clock: mtime is set by the filesystem, not the injected clock.
+  async function isAbandonedLockFile(path) {
+    try {
+      const { mtimeMs } = await fs.stat(path);
+      return Date.now() - mtimeMs >= STALE_LOCK_HEARTBEAT_MS;
+    } catch {
+      return false;
+    }
+  }
+
+  async function acquireTickLock() {
+    await ensureLayout();
+    const token = `${pid}-${randomId()}`;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      try {
+        await writeFileExclusive(lockPath, JSON.stringify({ pid, startedAt: now(), token }));
+        heldToken = token;
+        return true;
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+      }
+      // A live holder keeps the lock however long it runs (Codex R10) because it heartbeats.
+      // Reclaim when the holder's process is gone, or when the heartbeat is stale even though
+      // the PID looks alive (reused, R13), or when the file was never written (R12).
+      const holder = await readLock(lockPath);
+      const heartbeatStale = await isAbandonedLockFile(lockPath);
+      const holderGone = holder ? !isPidAlive(Number(holder.pid)) || heartbeatStale : heartbeatStale;
+      if (!holderGone) return false;
+      const tomb = `${lockPath}.reclaim-${token}`;
+      try {
+        await fs.rename(lockPath, tomb);
+      } catch (error) {
+        if (error?.code === "ENOENT") continue; // released or reclaimed meanwhile: retry
+        throw error;
+      }
+      const moved = await readLock(tomb);
+      // The moved file must be the holder judged gone: same token, or (unreadable) still stale.
+      const sameHolder = holder ? moved && moved.token === holder.token && moved.pid === holder.pid : !moved && (await isAbandonedLockFile(tomb));
+      if (!sameHolder) {
+        // We moved a lock someone took after our read: give it back and stand down.
+        try {
+          await fs.link(tomb, lockPath);
+        } catch {
+          // A third tick holds the path now; the moved holder's release will find no lock.
+        }
+        await fs.rm(tomb, { force: true });
+        return false;
+      }
+      await fs.rm(tomb, { force: true });
+      logger({ event: "tick_lock_reclaimed", holderPid: holder?.pid ?? null });
+    }
+    return false;
+  }
+
+  async function releaseTickLock() {
+    const holder = await readLock(lockPath);
+    if (holder?.token && holder.token === heldToken) await fs.rm(lockPath, { force: true });
+    heldToken = null;
+  }
+
+  async function withTickLock(fn) {
+    if (!(await acquireTickLock())) return { skipped: "tick_in_progress" };
+    const token = heldToken;
+    const heartbeat = setInterval(() => {
+      readLock(lockPath)
+        .then((holder) => (holder?.token === token ? fs.utimes(lockPath, new Date(), new Date()) : undefined))
+        .catch(() => {});
+    }, lockHeartbeatMs);
+    try {
+      return await fn();
+    } finally {
+      clearInterval(heartbeat);
+      await releaseTickLock();
+    }
+  }
+
+  async function slotPersona(dir) {
+    try {
+      return (await readJson(join(dir, "meta.json"))).persona ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function countReady(personas) {
+    const counts = Object.fromEntries(personas.map((persona) => [persona, 0]));
+    for (const slotId of await list(dirs.ready)) {
+      const persona = await slotPersona(join(dirs.ready, slotId));
+      if (persona && Object.hasOwn(counts, persona)) counts[persona] += 1;
+    }
+    return counts;
+  }
+
+  // Caller holds the tick lock.
+  async function mintIntoReady(persona) {
+    const mintedAt = new Date(now()).toISOString();
+    const slotId = `${personaKey(persona)}~${now()}~${randomId()}`;
+    const workDir = join(dirs.work, slotId);
+    const storedSession = await signIn.mint({ target, persona });
+    await ensureDir(workDir);
+    try {
+      const meta = buildMeta({ persona, slotId, storedSession, mintedAt, refreshCount: 0 });
+      await writeSlotFiles(workDir, { storedSession, meta, replace: false });
+      await fs.rename(workDir, join(dirs.ready, slotId));
+      return { slotId, meta };
+    } catch (error) {
+      await removeSlot(workDir);
+      throw error;
+    }
+  }
+
+  function refreshDue(meta) {
+    const verifiedAt = Date.parse(meta.verifiedAt);
+    const accessExpiresAt = Date.parse(meta.accessExpiresAt);
+    return (
+      !Number.isFinite(verifiedAt) ||
+      now() - verifiedAt >= refreshAfterMs ||
+      !Number.isFinite(accessExpiresAt) ||
+      accessExpiresAt - now() <= minAccessRemainingMs
+    );
+  }
+
+  // Caller holds the tick lock. Returns "kept" | "refreshed" | "discarded" | "gone".
+  async function refreshUnclaimed(slotId) {
+    const readyDir = join(dirs.ready, slotId);
+    let meta;
+    try {
+      meta = await readJson(join(readyDir, "meta.json"));
+    } catch (error) {
+      if (error?.code === "ENOENT") return "gone";
+      meta = null;
+    }
+    if (meta && !refreshDue(meta)) return "kept";
+    const workDir = join(dirs.work, slotId);
+    if (!(await claim(readyDir, workDir))) return "gone"; // taken meanwhile
+    let slot;
+    try {
+      slot = await readSlot(workDir);
+    } catch (error) {
+      logger({ event: "refresh_discard", slotId, reason: error?.code ?? "unreadable" });
+      await removeSlot(workDir);
+      return "discarded";
+    }
+    const result = await signIn.refresh({ target, storedSession: slot.storedSession, persona: slot.meta.persona });
+    if (result.ok) {
+      const nextMeta = buildMeta({
+        persona: slot.meta.persona,
+        slotId,
+        storedSession: result.storedSession,
+        mintedAt: slot.meta.mintedAt,
+        refreshCount: (slot.meta.refreshCount ?? 0) + 1,
+      });
+      await writeSlotFiles(workDir, { storedSession: result.storedSession, meta: nextMeta, replace: true });
+      await fs.rename(workDir, readyDir);
+      logger({ event: "refresh_ok", slotId, persona: slot.meta.persona });
+      return "refreshed";
+    }
+    if (result.transient) {
+      await fs.rename(workDir, readyDir);
+      logger({ event: "refresh_inconclusive", slotId, reason: result.reason });
+      return "kept";
+    }
+    await removeSlot(workDir);
+    logger({ event: "refresh_discard", slotId, persona: slot.meta.persona, reason: result.reason });
+    return "discarded";
+  }
+
+  async function tick({ personas }) {
+    const plan = Object.entries(personas ?? {});
+    for (const [persona, count] of plan) {
+      assertPersonaAllowed(target, persona);
+      if (!Number.isInteger(count) || count < 0 || count > 4) {
+        throw new Error(`Pool size for ${persona} must be an integer 0-4.`);
+      }
+    }
+    return withTickLock(async () => {
+      const summary = {
+        at: new Date(now()).toISOString(),
+        target: target.name,
+        signIns: 0,
+        refreshed: 0,
+        discarded: 0,
+        purgedTaken: 0,
+        recoveredWork: 0,
+        mintFailures: 0,
+        prunedSurplus: 0,
+        ready: {},
+      };
+
+      // Anything in work/ belongs to a crashed tick or mint: its token state is
+      // unknown, so it is discarded, never promoted.
+      for (const slotId of await list(dirs.work)) {
+        await removeSlot(join(dirs.work, slotId));
+        summary.recoveredWork += 1;
+      }
+
+      // taken/ is the agents' directory: a take may be mid-validation (claimed, takenAt not
+      // yet written). Age a slot by takenAt, else by its claim marker, else by its last
+      // verification, and purge only past the TTL — never because takenAt is still missing.
+      for (const slotId of await list(dirs.taken)) {
+        const dir = join(dirs.taken, slotId);
+        let meta = null;
+        try {
+          meta = await readJson(join(dir, "meta.json"));
+        } catch {
+          meta = null;
+        }
+        let claimedAt = Number.NaN;
+        try {
+          claimedAt = Date.parse((await readJson(join(dir, "claim.json"))).claimedAt);
+        } catch {
+          claimedAt = Number.NaN;
+        }
+        const anchor = [Date.parse(meta?.takenAt ?? ""), claimedAt, Date.parse(meta?.verifiedAt ?? "")].find((value) =>
+          Number.isFinite(value),
+        );
+        if (anchor === undefined || now() - anchor >= takenTtlMs) {
+          await removeSlot(dir);
+          summary.purgedTaken += 1;
+        }
+      }
+
+      // A persona removed from the config, or lowered (0 disables it), keeps no takeable
+      // surplus: discard the least recently verified extras before spending refreshes.
+      const wanted = new Map(plan);
+      const byPersona = new Map();
+      for (const slotId of await list(dirs.ready)) {
+        let meta = null;
+        try {
+          meta = await readJson(join(dirs.ready, slotId, "meta.json"));
+        } catch {
+          meta = null;
+        }
+        const persona = meta?.persona ?? null;
+        if (!byPersona.has(persona)) byPersona.set(persona, []);
+        byPersona.get(persona).push({ slotId, verifiedAt: Date.parse(meta?.verifiedAt ?? "") || 0 });
+      }
+      for (const [persona, slots] of byPersona) {
+        const keep = persona && wanted.has(persona) ? wanted.get(persona) : 0;
+        slots.sort((a, b) => b.verifiedAt - a.verifiedAt);
+        for (const { slotId } of slots.slice(keep)) {
+          const workDir = join(dirs.work, slotId);
+          if (!(await claim(join(dirs.ready, slotId), workDir))) continue; // taken meanwhile
+          await removeSlot(workDir);
+          summary.prunedSurplus += 1;
+          logger({ event: "surplus_discard", slotId, persona, configured: keep });
+        }
+      }
+
+      for (const slotId of await list(dirs.ready)) {
+        const outcome = await refreshUnclaimed(slotId);
+        if (outcome === "refreshed") summary.refreshed += 1;
+        if (outcome === "discarded") summary.discarded += 1;
+      }
+
+      const counts = await countReady(plan.map(([persona]) => persona));
+      const health = await readHealth();
+      summary.backoffSkips = 0;
+      for (const [persona, want] of plan) {
+        const entry = (health.personas[persona] ??= {
+          belowTargetTicks: 0,
+          consecutiveMintFailures: 0,
+          nextMintAttemptAt: null,
+          lastMintError: null,
+        });
+        // Every refill sign-in's MFA verify deletes the persona's AAL1 sessions on
+        // staging (ENT-4994), so repeated failures back off instead of retrying
+        // every tick.
+        if (counts[persona] < want && entry.nextMintAttemptAt && Date.parse(entry.nextMintAttemptAt) > now()) {
+          summary.backoffSkips += 1;
+          logger({
+            event: "mint_backoff_skip",
+            persona,
+            consecutiveMintFailures: entry.consecutiveMintFailures,
+            lastMintError: entry.lastMintError,
+            nextMintAttemptAt: entry.nextMintAttemptAt,
+          });
+        } else {
+          while (counts[persona] < want) {
+            summary.signIns += 1;
+            try {
+              await mintIntoReady(persona);
+              counts[persona] += 1;
+              entry.consecutiveMintFailures = 0;
+              entry.nextMintAttemptAt = null;
+              entry.lastMintError = null;
+            } catch (error) {
+              summary.mintFailures += 1;
+              entry.consecutiveMintFailures += 1;
+              entry.lastMintError = error?.code ?? "error";
+              entry.nextMintAttemptAt = new Date(
+                now() + nextMintBackoffMs({ failures: entry.consecutiveMintFailures, intervalMs }),
+              ).toISOString();
+              logger({
+                event: "mint_failed",
+                persona,
+                code: entry.lastMintError,
+                message: error?.message ?? String(error),
+                consecutiveMintFailures: entry.consecutiveMintFailures,
+                nextMintAttemptAt: entry.nextMintAttemptAt,
+              });
+              break;
+            }
+          }
+        }
+        entry.belowTargetTicks = counts[persona] < want ? entry.belowTargetTicks + 1 : 0;
+      }
+      // A persona the config no longer serves (removed or 0) drops its backoff and streaks, so
+      // re-enabling it after a repair mints on the next tick (Codex R13).
+      for (const persona of Object.keys(health.personas)) {
+        if (!(wanted.get(persona) > 0)) delete health.personas[persona];
+      }
+      if (summary.mintFailures === 0 && summary.backoffSkips === 0) health.lastSuccessfulTickAt = summary.at;
+      await replaceFile(healthPath, `${JSON.stringify(health, null, 2)}\n`);
+      summary.ready = counts;
+      logger({ event: "tick", ...summary });
+      await replaceFile(lastTickPath, `${JSON.stringify(summary, null, 2)}\n`);
+      return summary;
+    });
+  }
+
+  async function mintOne({ persona }) {
+    assertPersonaAllowed(target, persona);
+    const result = await withTickLock(async () => {
+      const minted = await mintIntoReady(persona);
+      logger({ event: "mint_one", persona, slotId: minted.slotId, signIns: 1 });
+      return minted;
+    });
+    if (result.skipped) throw Object.assign(new Error("A pool tick is running; retry in a minute."), { code: result.skipped });
+    return result;
+  }
+
+  async function take({ persona, owner }) {
+    assertPersonaAllowed(target, persona);
+    await ensureLayout();
+    const candidates = [];
+    for (const slotId of await list(dirs.ready)) {
+      if (!slotId.startsWith(`${personaKey(persona)}~`)) continue;
+      try {
+        const meta = await readJson(join(dirs.ready, slotId, "meta.json"));
+        if (meta.persona === persona) candidates.push({ slotId, verifiedAt: Date.parse(meta.verifiedAt) || 0 });
+      } catch {
+        // Moved by a racer or half-written: not a candidate.
+      }
+    }
+    candidates.sort((a, b) => b.verifiedAt - a.verifiedAt);
+    for (const { slotId } of candidates) {
+      const takenDir = join(dirs.taken, slotId);
+      if (!(await claim(join(dirs.ready, slotId), takenDir))) continue;
+      // From here this caller is the slot's only holder; the slot never goes back. The claim
+      // marker tells a concurrent tick this slot is in use even before takenAt exists.
+      await writeFileExclusive(join(takenDir, "claim.json"), JSON.stringify({ claimedAt: new Date(now()).toISOString() }));
+      let slot;
+      try {
+        slot = await readSlot(takenDir);
+      } catch (error) {
+        logger({ event: "take_discard", slotId, reason: error?.code ?? "unreadable" });
+        await removeSlot(takenDir);
+        continue;
+      }
+      const result = await signIn.refresh({ target, storedSession: slot.storedSession, persona });
+      if (!result.ok) {
+        logger({ event: "take_discard", slotId, persona, reason: result.reason, transient: Boolean(result.transient) });
+        await removeSlot(takenDir);
+        continue;
+      }
+      const meta = {
+        ...buildMeta({
+          persona,
+          slotId,
+          storedSession: result.storedSession,
+          mintedAt: slot.meta.mintedAt,
+          refreshCount: (slot.meta.refreshCount ?? 0) + 1,
+        }),
+        takenAt: new Date(now()).toISOString(),
+        owner: String(owner ?? "unknown"),
+      };
+      await writeSlotFiles(takenDir, { storedSession: result.storedSession, meta, replace: true });
+      logger({ event: "take_ok", slotId, persona, owner: meta.owner });
+      return { slotId, statePath: join(takenDir, "state.json"), dir: takenDir, meta };
+    }
+    throw new PoolEmptyError(persona, tickIntervalHint);
+  }
+
+  async function discardTaken(slotId) {
+    await removeSlot(join(dirs.taken, slotId));
+  }
+
+  async function status() {
+    const describe = async (dir, slotId) => {
+      const meta = await readJson(join(dir, slotId, "meta.json"));
+      return {
+        slotId,
+        persona: meta.persona,
+        aal: meta.aal,
+        sessionRef: meta.sessionRef,
+        ageSeconds: Math.round((now() - Date.parse(meta.mintedAt)) / 1000),
+        verifiedAgeSeconds: Math.round((now() - Date.parse(meta.verifiedAt)) / 1000),
+        accessExpiresInSeconds: Math.round((Date.parse(meta.accessExpiresAt) - now()) / 1000),
+      };
+    };
+    const collect = async (dir) => {
+      const rows = [];
+      for (const slotId of await list(dir)) {
+        try {
+          rows.push(await describe(dir, slotId));
+        } catch {
+          rows.push({ slotId, unreadable: true });
+        }
+      }
+      return rows;
+    };
+    let lastTick = null;
+    try {
+      lastTick = await readJson(lastTickPath);
+    } catch {
+      lastTick = null;
+    }
+    return {
+      poolDir,
+      target: target.name,
+      health: await readHealth(),
+      ready: await collect(dirs.ready),
+      taken: (await list(dirs.taken)).length,
+      work: (await list(dirs.work)).length,
+      tickRunning: (await list(poolDir)).includes("tick.lock"),
+      lastTick,
+    };
+  }
+
+  async function purge() {
+    let removed = 0;
+    for (const dir of Object.values(dirs)) {
+      for (const slotId of await list(dir)) {
+        await removeSlot(join(dir, slotId));
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+
+  return { tick, mintOne, take, discardTaken, status, purge, paths: { ...dirs, lockPath, lastTickPath } };
+}