agents-pod 0.0.0-stage → 0.2.0

package/src/cli.ts

@@ -0,0 +1,1864 @@
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import {
+  access,
+  appendFile,
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import {
+  agentTypeRefusal,
+  isAgentType,
+  readAgents,
+  resolveAgentDefinition,
+  writeAgents,
+} from "./agents-store.ts";
+import { renderTemplate, scanInbox, type InboxItem } from "./inbox.ts";
+import {
+  claimKey,
+  newListenerId,
+  readListeners,
+  writeListeners,
+  type ListenerRecord,
+} from "./listeners.ts";
+import { acquireLock, readLock, releaseLock, sleep } from "./locks.ts";
+import { loadNotifyConfig } from "./notify/config.ts";
+import { dispatchNotification, shouldNotify } from "./notify/dispatch.ts";
+import type { NotificationsConfig, PodNotification } from "./notify/types.ts";
+import { cronLogPath, delivererFile, podDir, reconcileLockPath } from "./paths.ts";
+import { readDeliverer, retryOutbox, writeDeliverer } from "./outbox.ts";
+import {
+  projectHasCapacity,
+  projectMaxActive,
+  readProjects,
+  writeProjects,
+} from "./projects.ts";
+import type { PodRecord } from "./registry.ts";
+import { readPods, withRegistryLock, writePods } from "./registry.ts";
+import {
+  commitSourceCursors,
+  drainSources,
+  pruneSourceClaims,
+  readSources,
+  writeSources,
+  type SourceDrain,
+} from "./sources.ts";
+import {
+  HEARTBEAT_STALE_MS,
+  WEDGED_ESCALATE_MS,
+  livenessFacts,
+  pidDead,
+  readWrapperRecord,
+  verifyProcess,
+  wrapperJsonPath,
+  wrapperVerifiablyDead,
+  type LivenessFacts,
+} from "./liveness.ts";
+import { appendInbox, createPodWorkspace, snapshotDocs, type DocFacts } from "./workspace.ts";
+import { resolveAgentBinary, wrapperScript } from "./wrapper.ts";
+
+/**
+ * Spawn and wake name their agent explicitly; the wrapper resolves it (ADR
+ * 0012). `--warm` is a wrapper argument, not an agent one (ADR 0011): the
+ * wrapper parses it and points the agent at the lost wake-up's session.
+ */
+function launchWrapperDetached(podId: string, agentId?: string, warm = false): void {
+  const args = [wrapperScript(), podId, ...(agentId ? [agentId] : []), ...(warm ? ["--warm"] : [])];
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+}
+
+/**
+ * Flags may appear anywhere among the goal words (README's CLI surface), and
+ * the words that are not flags compose the goal. A flag without a value is
+ * left unset and surfaces through the command's own validation.
+ */
+function parseFlags(
+  words: string[],
+  allowed: readonly string[],
+): { flags: Record<string, string>; rest: string[] } {
+  const flags: Record<string, string> = {};
+  const rest: string[] = [];
+  for (let index = 0; index < words.length; index += 1) {
+    const word = words[index]!;
+    const name = word.startsWith("--") ? word.slice(2) : undefined;
+    const value = words[index + 1];
+    if (name !== undefined && allowed.includes(name) && value !== undefined) {
+      flags[name] = value;
+      index += 1;
+    } else {
+      rest.push(word);
+    }
+  }
+  return { flags, rest };
+}
+
+/** Exponential backoff after `failed`/`lost`: 1m ×2, capped at 15m (ADR 0011). */
+function backoffMs(streak: number): number {
+  return Math.min(60_000 * 2 ** (streak - 1), 900_000);
+}
+
+/**
+ * Signal a pod's process group — never our own. The pgid comes from store
+ * data only (wrapper.json, ADR 0003), and the guards make a corrupt record a
+ * no-op instead of a self-kill.
+ */
+function signalGroup(pgid: number, signal: NodeJS.Signals): boolean {
+  if (!Number.isInteger(pgid) || pgid <= 1 || pgid === process.pid) return false;
+  try {
+    process.kill(-pgid, signal);
+    return true;
+  } catch {
+    return false; // the group is already gone
+  }
+}
+
+/** The lost detail names the fact that condemned the wake-up (ADR 0002, 0020). */
+function lostDetail(facts: LivenessFacts): string {
+  switch (facts.lostCause) {
+    case "ghost":
+      return "ghost record (no wrapper.json)";
+    case "reboot":
+      return "machine rebooted";
+    default:
+      return "wrapper gone, heartbeat stale";
+  }
+}
+
+/** The highest wake-up number on disk: a ghost is numbered by its directory. */
+async function maxWakeupNumber(pod: PodRecord): Promise<number | undefined> {
+  const dir = join(podDir(pod.project, pod.id), "wakeups");
+  const entries = await readdir(dir).catch(() => []);
+  const numbers = entries
+    .map((name) => Number.parseInt(name, 10))
+    .filter((n) => Number.isInteger(n));
+  return numbers.length > 0 ? Math.max(...numbers) : undefined;
+}
+
+async function livenessOf(pod: PodRecord): Promise<string> {
+  return (await livenessFacts(pod)).quadrant;
+}
+
+/**
+ * Staleness is a TTL of five minutes of wall clock, never pid liveness
+ * (ADR 0018): a live-but-wedged holder must not wedge every later tick, and a
+ * reused pid must not read as alive.
+ */
+const LOCK_STALE_MS = 300_000;
+
+/** The progress window: 60 minutes of a live wake-up with no document change (ADR 0019). */
+const PROGRESS_WINDOW_MS = 3_600_000;
+
+/** The verdict a progress kill records, in reconcile's own word (ADR 0019). */
+const PROGRESSLESS_DETAIL = "progressless (killed by reconcile)";
+
+/**
+ * ADR 0019's only progress signal: any of the three documents moving mtime or
+ * size. A file appearing or vanishing counts; the pod log is never read — a
+ * looping printer is the thief this rule exists to catch.
+ */
+async function documentsMoved(
+  docsDir: string,
+  baseline: Record<string, DocFacts>,
+): Promise<boolean> {
+  const current = await snapshotDocs(docsDir);
+  for (const name of new Set([...Object.keys(baseline), ...Object.keys(current)])) {
+    const before = baseline[name];
+    const after = current[name];
+    if (before === undefined || after === undefined) return true; // appeared or vanished
+    if (before.mtimeMs !== after.mtimeMs || before.size !== after.size) return true;
+  }
+  return false;
+}
+
+async function exists(file: string): Promise<boolean> {
+  return stat(file).then(
+    () => true,
+    () => false,
+  );
+}
+
+/** Overlap is audited, not silent: one line per steal (ADR 0018). */
+async function appendCronLog(line: string): Promise<void> {
+  const file = cronLogPath();
+  await mkdir(dirname(file), { recursive: true });
+  await appendFile(file, `${line}\n`);
+}
+
+/**
+ * The single-flight acquire (ADR 0018). `false` means a fresh holder owns the
+ * pass: the tick exits 0 and loses nothing, because passes are idempotent. A
+ * lock past its TTL is stolen and the steal recorded. Two stealers both
+ * unlink and both race the exclusive create — one wins, the other re-reads a
+ * fresh lock and skips; no arbitration needed.
+ */
+async function acquireReconcileLock(): Promise<boolean> {
+  const file = reconcileLockPath();
+  const now = Date.now();
+  const held = await readLock(file);
+  if (held !== undefined && now - held.startedAt < LOCK_STALE_MS) return false;
+  if (held === undefined && !(await exists(file))) {
+    return acquireLock(file, { pid: process.pid, startedAt: now });
+  }
+
+  // A lock file whose contents cannot be parsed is stale by definition:
+  // nothing about it can prove the holder is recent.
+  await unlink(file).catch(() => undefined);
+  const stolen = await acquireLock(file, { pid: process.pid, startedAt: now });
+  if (stolen) {
+    await appendCronLog(
+      held === undefined
+        ? "reconcile lock stolen from pid unknown (unreadable lock)"
+        : `reconcile lock stolen from pid ${held.pid} (${Math.floor((now - held.startedAt) / 1000)}s stale)`,
+    );
+  }
+  return stolen;
+}
+
+/**
+ * Reconcile is a stateless, idempotent pass (ADR 0002): it derives policy from
+ * outcome facts the wrapper recorded, then walks the single wake path —
+ * idle + goal open + not parked + now ≥ nextWakeAt (ADR 0011). The wrapper
+ * records facts; the pass writes policy; neither does the other's job.
+ *
+ * The pass also consumes this episode's notification (ADR 0021): the moment is
+ * queued while policy is derived, recorded in `notifiedAt`, and delivered
+ * after the locks are gone — a slow channel never holds the registry.
+ *
+ * Sources drain before the body takes the registry lock (ADR 0024). The body
+ * then re-reads pods.json there, so each transition is a compare-and-swap
+ * against the record as it is now. The single-flight lock above is a courtesy;
+ * this is the correctness.
+ */
+async function reconcileCmd(deps: CliDeps = {}): Promise<number> {
+  if (!(await acquireReconcileLock())) return 0;
+  const warnings: string[] = [];
+  const notify = await loadNotifyConfig(undefined, (message) => warnings.push(message));
+  // Listener-spawned pods default to the tick's project; `listener add
+  // --project` overrides that destination per Listener (ADR 0007, ADR 0004).
+  const project = deps.cwd ?? process.cwd();
+  let pending: PodNotification[] = [];
+  try {
+    // A slow drain holds no registry lock and runs before any Pod is touched.
+    const drained = await drainSources(project, await readListeners());
+    for (const result of drained) {
+      if (result.error !== undefined) {
+        await appendCronLog(
+          `source ${result.name}: drain failed (${result.error}); no items, cursor unchanged`,
+        );
+      }
+      for (const bad of result.bad) {
+        await appendCronLog(
+          `source ${result.name}: line ${bad.line}: ${bad.reason} (skipped, unclaimed)`,
+        );
+      }
+    }
+    // Delivery is the drain's mirror: network-bound, so outside the lock
+    // (ADRs 0024, 0025). Every Pod that is not active gets the Wrapper's own
+    // bounded flush; the state is re-read per Pod so a wake that started
+    // meanwhile keeps its Wrapper the only writer over that outbox.
+    for (const pod of await readPods()) {
+      if (pod.state === "active") continue;
+      const fresh = await podState(pod.id);
+      if (fresh === undefined || fresh === "active") continue;
+      await retryOutbox(pod.id, pod.project);
+    }
+    pending =
+      (await withRegistryLock(() => reconcilePass(notify, project, drained))) ?? [];
+  } finally {
+    await releaseLock(reconcileLockPath());
+  }
+  // A bad config degrades, it never kills the pass (ADR 0021): the warnings
+  // and any delivery failure are cron.log lines, and nothing is retried.
+  for (const warning of warnings) await appendCronLog(`notify: ${warning}`);
+  // Independent pods are announced in parallel: one hung channel spends one
+  // ten-second budget, not one per parked pod (ADR 0021).
+  const deliveries = await Promise.all(
+    pending.map((notification) => dispatchNotification(notify, notification)),
+  );
+  for (const notes of deliveries) {
+    for (const note of notes) await appendCronLog(`notify: ${note}`);
+  }
+  return 0;
+}
+
+async function reconcilePass(
+  notify: NotificationsConfig,
+  project: string,
+  drained: SourceDrain[],
+): Promise<PodNotification[]> {
+  const pods = await readPods();
+  const agents = await readAgents();
+  const now = Date.now();
+  let changed = false;
+  const pending: PodNotification[] = [];
+
+  for (const pod of pods) {
+    pod.policy ??= { failureStreak: 0, appliedOutcomes: 0 };
+
+    // Once per episode (ADR 0021): the flip announces, the marker records.
+    // A human wake clears the marker, so the next park is a new episode.
+    const announcePark = (reason?: string): void => {
+      if (pod.notifiedAt !== undefined) return;
+      if (!shouldNotify(notify.on, "park")) return;
+      pending.push(parkNotification(pod, reason));
+      pod.notifiedAt = now;
+      changed = true;
+    };
+
+    // 1. Liveness adjudication for active pods first (ADR 0002, 0017): a
+    // ghost or crash becomes a `lost` outcome this pass records, so the
+    // policy derivation below sees it and backoff applies before the wake
+    // path could touch the pod again.
+    if (pod.state === "active") {
+      const facts = await livenessFacts(pod);
+      if (facts.quadrant === "lost") {
+        const n = facts.wrapper?.wakeup ?? (await maxWakeupNumber(pod)) ?? 1;
+        pod.wakeUps.push({ n, outcome: "lost", detail: lostDetail(facts) });
+        pod.state = "idle";
+        delete pod.wedgedAt; // a lost wake-up spends any wedged observation
+        changed = true;
+        // Orphans are reaped, never adopted (ADR 0003): if the agent's group
+        // survives its wrapper, the group goes — nothing here can `wait()` it.
+        // The reap is three-verified too (ADR 0020): only a wrapper that is
+        // verifiably dead on this same boot licenses a group signal, so a
+        // post-reboot pgid — a stale number — is never touched.
+        if (facts.wrapper !== undefined && (await wrapperVerifiablyDead(facts.wrapper))) {
+          signalGroup(facts.wrapper.pgid, "SIGKILL");
+        }
+      } else if (facts.quadrant === "wedged-pending") {
+        // The two-pass rule (ADR 0017): the first pass records a stably stale
+        // observation; the confirming pass runs cancel's signal path, records
+        // `lost`, and removes the identity. No grace wait here — a wedged
+        // wrapper's trap may be dead, and the next pass collects the group.
+        if (pod.wedgedAt === undefined) {
+          pod.wedgedAt = now;
+          changed = true;
+        } else if (
+          facts.wrapper !== undefined &&
+          (facts.beatAgeMs === undefined || facts.beatAgeMs >= WEDGED_ESCALATE_MS)
+        ) {
+          // Three-verified (ADR 0020): a live pid whose start time is not the
+          // recorded one is somebody else. The wake-up is still lost — the
+          // record cannot be trusted — but nothing is signalled. The intent
+          // lands first so a live trap defers to this verdict instead of
+          // overwriting it with `cancelled` (the same deference ADR 0019
+          // gives the progress kill — one mechanism, two causes).
+          const trusted = await verifyProcess(facts.wrapper);
+          if (trusted) {
+            pod.killIntent = { n: facts.wrapper.wakeup, at: now, cause: "wedged" };
+            await writePods(pods);
+            signalGroup(facts.wrapper.pgid, "SIGTERM");
+          }
+          pod.wakeUps.push({
+            n: facts.wrapper.wakeup,
+            outcome: "lost",
+            detail: trusted
+              ? "wedged wrapper killed by reconcile"
+              : "wedged wrapper signal withheld (recorded process is gone)",
+          });
+          pod.state = "idle";
+          delete pod.wedgedAt;
+          await rm(wrapperJsonPath(pod.project, pod.id), { force: true });
+          changed = true;
+        }
+      } else if (facts.quadrant === "healthy") {
+        // Beats resumed: the wake-from-sleep race closes (ADR 0017).
+        if (pod.wedgedAt !== undefined) {
+          delete pod.wedgedAt;
+          changed = true;
+        }
+        // Liveness outranks progress (ADR 0019): only a healthy wake-up — pid
+        // live, heartbeat fresh — is judged on its documents at all.
+        const wrapper = facts.wrapper;
+        if (
+          wrapper !== undefined &&
+          wrapper.docs !== undefined &&
+          now - wrapper.startedAt >= PROGRESS_WINDOW_MS &&
+          !(await documentsMoved(join(podDir(pod.project, pod.id), "docs"), wrapper.docs))
+        ) {
+          // Three-verified (ADR 0020): a live pid whose start time is not the
+          // recorded one is somebody else — nothing to judge, nothing to kill.
+          if (await verifyProcess(wrapper)) {
+            // Intent first (ADR 0019): the registry-lock write lands before the
+            // signal, so the verdict is on disk before it is acted on, and the
+            // wrapper sees it and records no second outcome. The pass waits for
+            // nothing — the wrapper owns the wind-down (ADR 0017).
+            pod.killIntent = { n: wrapper.wakeup, at: now, cause: "progressless" };
+            await writePods(pods);
+            signalGroup(wrapper.pgid, "SIGTERM");
+            pod.wakeUps.push({
+              n: wrapper.wakeup,
+              outcome: "failed",
+              detail: PROGRESSLESS_DETAIL,
+            });
+            pod.state = "idle";
+            changed = true;
+          }
+        }
+      }
+    }
+
+    // Delivery retries ran outside this lock, before the pass (ADR 0025).
+    // Delivery failure writes only cron.log, never Pod policy or the
+    // two-event notification inventory (ADRs 0021, 0025).
+
+    // 2. Policy derivation from outcome facts the wrapper (or step 1) recorded.
+    const fresh = pod.wakeUps.slice(pod.policy.appliedOutcomes);
+    for (const wake of fresh) {
+      if (wake.outcome === "failed" || wake.outcome === "lost") {
+        pod.policy.failureStreak += 1;
+        pod.policy.nextWakeAt = now + backoffMs(pod.policy.failureStreak);
+        // Backoff without a stop is a money pit: streak 3 parks the pod, and
+        // only a human wake lifts it (ADR 0011). Park is policy data, not a state.
+        if (pod.policy.failureStreak >= 3 && !pod.policy.parked) {
+          pod.policy.parked = true;
+          announcePark();
+        }
+      } else if (wake.outcome === "more" || wake.outcome === "done") {
+        pod.policy.failureStreak = 0;
+        delete pod.policy.nextWakeAt;
+      }
+      pod.policy.appliedOutcomes += 1;
+      changed = true;
+    }
+
+    const goalOpen = pod.state !== "done" && pod.state !== "cancelled";
+
+    // 3. Terminal observation (ADR 0021): done is announced once, however many
+    // passes later find the record. The marker is what makes it once.
+    if (
+      pod.state === "done" &&
+      pod.notifiedAt === undefined &&
+      shouldNotify(notify.on, "done")
+    ) {
+      const handoff = await handoffStatusLine(pod);
+      pending.push({
+        event: "done",
+        podId: pod.id,
+        goal: goalHeadline(pod.goal),
+        ...(handoff ? { handoffStatus: handoff } : {}),
+      });
+      pod.notifiedAt = now;
+      changed = true;
+    }
+
+    // Deleting a definition an idle pod still references is not an error at
+    // `agent rm`: the orphan fails resolution here and parks (ADR 0012). An
+    // active pod is the wrapper's to fail — the streak machinery takes over.
+    // The park it causes is a park episode too, so it notifies (ADR 0021).
+    const agentId = pod.policy.agent ?? "default";
+    const agentKnown = resolveAgentDefinition(agents, agentId) !== undefined;
+    if (!agentKnown && goalOpen && pod.state !== "active") {
+      if (!pod.policy.parked) {
+        pod.policy.parked = true;
+        announcePark(`agent "${agentId}" no longer resolves (ADR 0012)`);
+        changed = true;
+      }
+      continue;
+    }
+  }
+
+  if (changed) await writePods(pods);
+
+  // Intake comes before the wake phase (ADR 0014): a batch appended to an idle
+  // pod in this pass must be served by this pass's wake — one batch, one wake,
+  // appended and marked before anything is launched. Claim-before-touch still
+  // holds (ADR 0007): the claims are written before a document is opened.
+  await listenersPass(project, drained);
+
+  // 4. The wake phase (ADR 0011): the guarded idle → active transition, read
+  // fresh because intake may have claimed, appended, or spawned since the pass
+  // began. A pod intake already woke is active here and is not woken twice.
+  await wakeDuePods(now);
+  return pending;
+}
+
+/**
+ * The wake phase: every idle, goal-open, unparked pod whose backoff expired is
+ * woken. It runs after intake so an item that just landed in a pod's `## Inbox`
+ * is served by the same pass's wake (ADR 0014), and the read is the registry's
+ * current state — the same compare-and-swap ADR 0018 relies on, one write.
+ */
+async function wakeDuePods(now: number): Promise<void> {
+  const pods = await readPods();
+  const projects = await readProjects();
+  let changed = false;
+  for (const pod of pods) {
+    if (pod.state !== "idle" || pod.policy?.parked) continue;
+    if (pod.policy?.nextWakeAt !== undefined && pod.policy.nextWakeAt > now) continue;
+    if (pod.after !== undefined) {
+      const upstream = pods.find((candidate) => candidate.id === pod.after);
+      if (upstream?.state !== "done") continue;
+    }
+    if (!projectHasCapacity(pod.project, pods, projects)) continue;
+    launchWrapperDetached(pod.id, pod.policy?.agent ?? "default");
+    pod.state = "active";
+    changed = true;
+  }
+  if (changed) await writePods(pods);
+}
+
+/** One Pod's state as the registry holds it now, read without any lock (ADR 0025). */
+async function podState(podId: string): Promise<PodRecord["state"] | undefined> {
+  const pods = await readPods();
+  return pods.find((candidate) => candidate.id === podId)?.state;
+}
+
+/** Non-terminal materializations occupy a listener's bound, even while capacity-waiting. */
+function livePod(claimedBy: string, pods: PodRecord[]): boolean {
+  const pod = pods.find((candidate) => candidate.id === claimedBy);
+  return pod !== undefined && pod.state !== "done" && pod.state !== "cancelled";
+}
+
+/** P0's match rule: a plain substring over title and body; absent means all. */
+function matchesListener(rule: string | undefined, item: InboxItem): boolean {
+  if (rule === undefined || rule === "") return true;
+  return `${item.title}\n${item.body}`.includes(rule);
+}
+
+/**
+ * The listener pass (ADR 0007, 0013, 0014). The inbox is read-only; a claim is
+ * registry data written here — inside the registry lock, before any pod is
+ * touched — so a crash between claim and materialization is repaired by the
+ * next pass. Directory items are claimable only once their mtime and size held
+ * across two consecutive scans; JSONL malformed lines are skipped and warned
+ * every pass until their writer fixes them. Claims then reach their target: a
+ * template spawns a pod, a bound standing pod takes them as `## Inbox` blocks.
+ */
+async function listenersPass(project: string, drained: SourceDrain[]): Promise<void> {
+  const listeners = await readListeners();
+  if (listeners.length === 0) return;
+
+  /** The inbox, not the listener, is the claim namespace (ADR 0013). */
+  const claimedInInbox = new Set<string>();
+  for (const listener of listeners) {
+    listener.claimed ??= [];
+    listener.seen ??= [];
+    for (const claim of listener.claimed) claimedInInbox.add(claimKey(claim.inbox, claim.item));
+  }
+
+  const itemsByListener = new Map<string, Map<string, InboxItem>>();
+  const unscannable = new Set<string>();
+  let changed = false;
+
+  // Phase 1: scan, hold the stability memory, and claim. Nothing is spawned yet.
+  for (const listener of listeners) {
+    const origin =
+      listener.source === undefined ? listener.inbox! : `source:${listener.source}`;
+    const sourceDrain = drained.find((candidate) => candidate.name === listener.source);
+    const scan =
+      listener.source === undefined
+        ? await scanInbox(listener.inbox!)
+        : {
+            items: sourceDrain?.items ?? [],
+            bad: [],
+            ...(sourceDrain?.error === undefined ? {} : { error: sourceDrain.error }),
+          };
+    const byId = new Map<string, InboxItem>();
+    for (const item of scan.items) if (!byId.has(item.id)) byId.set(item.id, item);
+    itemsByListener.set(listener.id, byId);
+    if (scan.error !== undefined) {
+      unscannable.add(listener.id);
+      if (listener.source === undefined) {
+        await appendCronLog(
+          `listener ${listener.id}: inbox ${listener.inbox} unreadable (${scan.error})`,
+        );
+      }
+      continue;
+    }
+    for (const bad of scan.bad) {
+      await appendCronLog(
+        `listener ${listener.id}: ${listener.inbox} line ${bad.line}: ${bad.reason} (skipped, unclaimed)`,
+      );
+    }
+
+    let stable: InboxItem[] = scan.items;
+    if (listener.source === undefined) {
+      const seen = new Map(listener.seen.map((fact) => [fact.item, fact]));
+      for (const known of [...seen.keys()]) {
+        if (!scan.items.some((item) => item.id === known)) {
+          seen.delete(known); // gone from the inbox; the inbox is the writer's
+          changed = true;
+        }
+      }
+      stable = [];
+      for (const item of scan.items) {
+        const before = seen.get(item.id);
+        if (before !== undefined && before.mtimeMs === item.mtimeMs && before.size === item.size) {
+          stable.push(item);
+        } else {
+          seen.set(item.id, { item: item.id, mtimeMs: item.mtimeMs, size: item.size });
+          changed = true;
+        }
+      }
+      listener.seen = [...seen.values()];
+    }
+
+    const pendingClaims = listener.claimed.filter(
+      (claim) => claim.spawnedPodId === undefined && claim.blocked === undefined,
+    ).length;
+    const pods = await readPods();
+    const live = listener.claimed.filter(
+      (claim) => claim.spawnedPodId !== undefined && livePod(claim.spawnedPodId, pods),
+    ).length;
+    // A bound pod is served by a queue (ADR 0014), so only template spawns
+    // compete for its slots — and a pending claim already holds one. A Source
+    // claim is unbounded too: its items exist only in this drain's output and
+    // the cursor commits behind the claims, so an unclaimed item would be lost
+    // rather than re-scanned. The bound then defers materialization, below.
+    let room =
+      listener.mode === "pod" || listener.source !== undefined
+        ? Number.POSITIVE_INFINITY
+        : Math.max(0, listener.maxConcurrent - live - pendingClaims);
+
+    for (const item of stable) {
+      if (room <= 0) break;
+      const key = claimKey(origin, item.id);
+      if (claimedInInbox.has(key) || !matchesListener(listener.match, item)) continue;
+      // One claim shape for both targets (ADR 0013): a template materializes a
+      // pod from it later, a bound standing pod takes it as a document in
+      // phase 3 (ADR 0014). Claim first, always.
+      listener.claimed.push({
+        inbox: origin,
+        item: item.id,
+        ...(sourceDrain?.drainedAt === undefined
+          ? {}
+          : { claimedAt: sourceDrain.drainedAt }),
+      });
+      claimedInInbox.add(key);
+      changed = true;
+      if (room !== Number.POSITIVE_INFINITY) room -= 1;
+    }
+  }
+
+  // The claim is on disk before any pod is touched (ADR 0007).
+  if (changed) await writeListeners(listeners);
+
+  // Phase 2: materialize what is claimed and still unserved.
+  let materialized = false;
+  for (const listener of listeners) {
+    if (listener.mode !== "template" || unscannable.has(listener.id)) continue;
+    const pending = () =>
+      listener.claimed.filter(
+        (claim) => claim.spawnedPodId === undefined && claim.blocked === undefined,
+      );
+    if (pending().length === 0) continue;
+
+    const body = await readFile(listener.template ?? "", "utf8").catch(() => undefined);
+    if (body === undefined) {
+      for (const claim of pending()) {
+        claim.blocked = `template ${listener.template} unreadable`;
+        await appendCronLog(
+          `listener ${listener.id}: item ${claim.item} materialization failed: template ${listener.template} unreadable (claim consumed, ADR 0013)`,
+        );
+      }
+      materialized = true;
+      continue;
+    }
+
+    const pods = await readPods();
+    let live = listener.claimed.filter(
+      (claim) => claim.spawnedPodId !== undefined && livePod(claim.spawnedPodId, pods),
+    ).length;
+    for (const claim of pending()) {
+      if (live >= listener.maxConcurrent) break; // bound: the claim waits a pass
+      const item = itemsByListener.get(listener.id)?.get(claim.item);
+      if (item === undefined) {
+        claim.blocked = "item vanished before materialization";
+        await appendCronLog(
+          `listener ${listener.id}: item ${claim.item} materialization failed: item vanished (claim consumed, ADR 0013)`,
+        );
+        materialized = true;
+        continue;
+      }
+      const rendered = renderTemplate(body, item);
+      if ("error" in rendered) {
+        claim.blocked = rendered.error;
+        await appendCronLog(
+          `listener ${listener.id}: item ${claim.item} materialization failed: ${rendered.error} (claim consumed, ADR 0013)`,
+        );
+        materialized = true;
+        continue;
+      }
+      const record = await spawnPodRecord(
+        rendered.goal,
+        listener.project ?? project,
+        "default",
+        undefined,
+        undefined,
+        true,
+      );
+      claim.spawnedPodId = record.id;
+      live += 1;
+      materialized = true;
+    }
+  }
+  if (materialized) await writeListeners(listeners);
+
+  // Phase 3: a bound standing pod takes the claimed batch as documents
+  // (ADR 0014). Nothing is written while a wake-up is live — TASKS.md is the
+  // one file both sides write, so one writer at a time, and a parked pod's
+  // items accumulate in the registry until a human lifts the park.
+  let appended = false;
+  for (const listener of listeners) {
+    if (listener.mode !== "pod" || listener.podId === undefined) continue;
+    if (unscannable.has(listener.id)) continue; // no bodies to copy this pass
+    const waiting = listener.claimed.filter(
+      (claim) => claim.blocked === undefined && claim.appended !== true,
+    );
+    if (waiting.length === 0) continue;
+
+    const pods = await readPods();
+    const pod = pods.find((candidate) => candidate.id === listener.podId);
+    if (pod === undefined) {
+      await appendCronLog(
+        `listener ${listener.id}: bound pod ${listener.podId} is not in the registry (claim waits)`,
+      );
+      continue;
+    }
+    if (pod.state !== "idle" || pod.policy?.parked) continue;
+
+    // The body is copied at append time (ADR 0014), so the item must still be
+    // readable: a writer that deleted it first leaves nothing to copy.
+    const scanned = itemsByListener.get(listener.id);
+    const batch: InboxItem[] = [];
+    for (const claim of waiting) {
+      const item = scanned?.get(claim.item);
+      if (item === undefined) {
+        claim.blocked = "item vanished before append";
+        await appendCronLog(
+          `listener ${listener.id}: item ${claim.item} vanished before append (claim consumed, ADR 0014)`,
+        );
+        appended = true;
+        continue;
+      }
+      batch.push(item);
+    }
+    if (batch.length === 0) continue;
+
+    try {
+      await appendInbox(join(podDir(pod.project, pod.id), "docs"), batch);
+    } catch (error) {
+      // The claims stay unappended: the next pass retries the same batch.
+      await appendCronLog(
+        `listener ${listener.id}: bound pod ${pod.id} Inbox append failed (${(error as Error).message})`,
+      );
+      continue;
+    }
+    for (const item of batch) {
+      const claim = waiting.find((candidate) => candidate.item === item.id);
+      if (claim !== undefined) claim.appended = true;
+    }
+    appended = true;
+  }
+  // Append first, then mark: the marker is on disk before the wake phase can
+  // launch anything, so a crash anywhere between claim and wake repairs on the
+  // next pass (ADR 0014). The wake itself is the pass's ordinary transition.
+  if (appended) await writeListeners(listeners);
+
+  // Two stores, in this order: claims first, then each successful cursor in
+  // the source store's own atomic write. A bound standing pod adds one gate:
+  // its claims must also be appended, because their bodies exist only in this
+  // drain's output. While a wake-up holds the append back, the unchanged cursor
+  // makes the next pass drain the same items again. A crash between writes
+  // replays into id and document dedupe rather than repeating work (ADR 0024).
+  // A Listener removed while its drain was running no longer licenses a cursor.
+  const consumed = new Set(listeners.flatMap((listener) => listener.source ?? []));
+  const waitingForAppend = new Set(
+    listeners.flatMap((listener) =>
+      listener.mode === "pod" &&
+      listener.source !== undefined &&
+      listener.claimed.some(
+        (claim) =>
+          claim.inbox === `source:${listener.source}` &&
+          claim.blocked === undefined &&
+          claim.appended !== true,
+      )
+        ? [listener.source]
+        : [],
+    ),
+  );
+  const committable = drained.filter(
+    (drain) => consumed.has(drain.name) && !waitingForAppend.has(drain.name),
+  );
+  const pruning = pruneSourceClaims(listeners, committable);
+  if (pruning.changed) await writeListeners(pruning.listeners);
+  await commitSourceCursors(committable);
+}
+
+export interface CliDeps {
+  cwd?: string;
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+}
+
+function newPodId(): string {
+  return `pod-${randomBytes(3).toString("hex")}`;
+}
+
+/** A goal is standing text; its first line is the one-line handle (ADR 0011). */
+function goalHeadline(goal: string): string {
+  return goal.split("\n", 1)[0]!.trim();
+}
+
+/**
+ * The consecutive failed/lost run that condemned the pod, in wake-up order.
+ * The streak is policy's count; this is the evidence behind it (ADR 0021).
+ */
+function failureTrail(pod: PodRecord): Array<{ n: number; outcome: string; detail?: string }> {
+  const trail: Array<{ n: number; outcome: string; detail?: string }> = [];
+  for (let index = pod.wakeUps.length - 1; index >= 0; index -= 1) {
+    const wake = pod.wakeUps[index]!;
+    if (wake.outcome !== "failed" && wake.outcome !== "lost") break;
+    trail.unshift(wake);
+  }
+  return trail;
+}
+
+/** The park verdict: id, goal headline, the failures and their details (ADR 0021). */
+function parkNotification(pod: PodRecord, reason?: string): PodNotification {
+  const failures = failureTrail(pod);
+  return {
+    event: "park",
+    podId: pod.id,
+    goal: goalHeadline(pod.goal),
+    consecutiveFailures: pod.policy?.failureStreak ?? failures.length,
+    ...(failures.length > 0 ? { failures } : {}),
+    ...(reason ? { reason } : {}),
+  };
+}
+
+/**
+ * The handoff's status line, from the wrapper's snapshot (ADR 0009): a done
+ * notification carries the agent's own word, not a reconstruction.
+ */
+async function handoffStatusLine(pod: PodRecord): Promise<string | undefined> {
+  const wakeup = pod.wakeUps.at(-1)?.n;
+  if (wakeup === undefined) return undefined;
+  const file = join(podDir(pod.project, pod.id), "wakeups", String(wakeup), "handoff.md");
+  const body = await readFile(file, "utf8").catch(() => undefined);
+  const line = (body?.split("\n", 1)[0] ?? "").trim();
+  return line || undefined;
+}
+
+async function requirePod(
+  podId: string | undefined,
+  command: string,
+  err: (line: string) => void,
+): Promise<PodRecord | undefined> {
+  if (!podId) {
+    err(`Usage: agents-pod ${command} <podId>`);
+    return undefined;
+  }
+  const pod = (await readPods()).find((candidate) => candidate.id === podId);
+  if (!pod) {
+    err(`Unknown pod ${podId}`);
+    return undefined;
+  }
+  return pod;
+}
+
+/** A read-only view: status never writes the store (ADR 0011, ADR 0015). */
+async function statusCmd(
+  rest: string[],
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const pod = await requirePod(rest[0], "status", err);
+  if (!pod) return 2;
+
+  const last = pod.wakeUps.at(-1);
+  out(pod.id);
+  out(`  goal: ${goalHeadline(pod.goal)}`);
+  out(`  state: ${pod.state}`);
+  if (pod.after !== undefined) {
+    const upstream = (await readPods()).find((candidate) => candidate.id === pod.after);
+    out(`  after: ${pod.after} (${upstream?.state ?? "missing"})`);
+  }
+  out(`  liveness: ${await livenessOf(pod)}`);
+  if (pod.policy?.parked) {
+    out(`  parked (consecutive failures: ${pod.policy.failureStreak})`);
+  }
+  out(`  agent: ${resolveAgentBinary(process.env)}`);
+  out(`  wake-ups: ${pod.wakeUps.length} (last outcome: ${last?.outcome ?? "none"})`);
+  return 0;
+}
+
+/**
+ * The attention ruler's first use (DESIGN Part 1): a healthy pod takes one
+ * quiet line at the bottom; the pods that need a human lead. Read-only.
+ */
+async function listCmd(out: (line: string) => void): Promise<number> {
+  const pods = await readPods();
+  if (pods.length === 0) {
+    out("No pods");
+    return 0;
+  }
+
+  const rows = await Promise.all(
+    pods.map(async (pod) => ({ pod, liveness: await livenessOf(pod) })),
+  );
+  const needsHuman = (row: (typeof rows)[number]) =>
+    row.pod.policy?.parked === true || row.liveness !== "healthy";
+  const ordered = [...rows.filter(needsHuman), ...rows.filter((row) => !needsHuman(row))];
+
+  for (const { pod } of ordered) {
+    const parked = pod.policy?.parked ? " (parked)" : "";
+    out(`${pod.id}  ${pod.state}${parked}  ${goalHeadline(pod.goal)}`);
+  }
+  return 0;
+}
+
+/**
+ * `logs` is the human's window into the wrapper's dual log (ADR 0009):
+ * output.log carries the wake-up separators and the assistant's text. A tail
+ * is deliberately boring — a 50 ms stat poll, no fs.watch (a watch is an
+ * inotify edge to miss, a poll is a fact to re-read).
+ */
+const FOLLOW_POLL_MS = 50;
+
+async function logsCmd(
+  words: string[],
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  // `--follow` carries no value, so parseFlags leaves it among the words; the
+  // pod id is the only non-flag word (README's `logs <podId> [--follow]`).
+  const { rest } = parseFlags(words, []);
+  const follow = rest.includes("--follow");
+  const pod = await requirePod(
+    rest.find((word) => !word.startsWith("--")),
+    "logs",
+    err,
+  );
+  if (!pod) return 2;
+
+  const file = join(podDir(pod.project, pod.id), "output.log");
+  if (!(await exists(file))) return 0; // a pod that never logged is not an error
+
+  // Complete lines only: bytes past the last newline wait for the rest, so a
+  // half-written line is never printed twice or torn in half.
+  let offset = 0;
+  const drain = async (): Promise<void> => {
+    const body = await readFile(file).catch(() => undefined);
+    if (body === undefined) return;
+    const lastNewline = body.lastIndexOf(0x0a);
+    if (lastNewline < offset) return;
+    const chunk = body.subarray(offset, lastNewline + 1).toString("utf8");
+    offset = lastNewline + 1;
+    for (const line of chunk.slice(0, -1).split("\n")) out(line);
+  };
+
+  await drain();
+  if (!follow) {
+    const body = await readFile(file).catch(() => undefined);
+    if (body !== undefined && body.length > offset) {
+      out(body.subarray(offset).toString("utf8"));
+    }
+    return 0;
+  }
+
+  // The tail never returns: the follower is ended by a signal, not by an exit.
+  for (;;) {
+    await sleep(FOLLOW_POLL_MS);
+    await drain();
+  }
+}
+
+/**
+ * The human override (ADR 0011): one rule, no `--force`. A wake on an idle,
+ * goal-open pod always succeeds and clears parked, failureStreak, and
+ * nextWakeAt; terminal is terminal; a running pod has nothing to wake.
+ *
+ * `--warm` is crash recovery, not an override (ADR 0011, 0020): it is legal
+ * only when the last outcome is `lost`, still counts as wake-up n+1 with its
+ * own wrapper and outcome, and neither clears nor advances the streak — so it
+ * must not walk through the policy-clearing branch below.
+ */
+async function wakeCmd(
+  words: string[],
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const { flags, rest } = parseFlags(words, ["agent"]);
+  // `--warm` carries no value, so parseFlags leaves it among the words.
+  const warm = rest.includes("--warm");
+  const podId = rest.find((word) => !word.startsWith("--"));
+  if (!podId) {
+    err("Usage: agents-pod wake <podId> [--agent <id>] [--warm]");
+    return 2;
+  }
+  const pods = await readPods();
+  const pod = pods.find((candidate) => candidate.id === podId);
+  if (!pod) {
+    err(`Unknown pod ${podId}`);
+    return 2;
+  }
+
+  if (pod.state === "done" || pod.state === "cancelled") {
+    err(`Pod ${pod.id} is ${pod.state}: terminal is terminal — spawn a new pod instead`);
+    return 2;
+  }
+  if (pod.state === "active" || pod.state === "spawning") {
+    err(`Pod ${pod.id} is ${pod.state}: nothing to wake`);
+    return 0;
+  }
+
+  // Only a crash has a session worth resuming (ADR 0011): a `failed` wake-up
+  // ended cleanly, and a fresh window is the honest continuation for it.
+  const last = pod.wakeUps.at(-1);
+  if (warm && last?.outcome !== "lost") {
+    err(
+      `Pod ${pod.id}: --warm is valid only when the last outcome is lost (last: ${last?.outcome ?? "none"})`,
+    );
+    return 2;
+  }
+
+  if (pod.after !== undefined) {
+    const upstream = (await readPods()).find((candidate) => candidate.id === pod.after);
+    if (upstream?.state !== "done") {
+      err(`Pod ${pod.id} is waiting for pod ${pod.after} (${upstream?.state ?? "missing"})`);
+      return 2;
+    }
+  }
+  const projects = await readProjects();
+  if (!projectHasCapacity(pod.project, pods, projects)) {
+    const active = pods.filter(
+      (candidate) =>
+        resolve(candidate.project) === resolve(pod.project) &&
+        (candidate.state === "spawning" || candidate.state === "active"),
+    ).length;
+    err(`Pod ${pod.id} is waiting for project capacity (${active}/${projectMaxActive(pod.project, projects)})`);
+    return 2;
+  }
+
+  // A one-off override: it serves this wake-up only, never the pod's policy
+  // (ADR 0012). An unknown id is a configuration error at the surface.
+  const agentId = flags.agent ?? pod.policy?.agent ?? "default";
+  const agent = resolveAgentDefinition(await readAgents(), agentId);
+  if (!agent) {
+    err(`Unknown agent ${agentId}: define it with agents-pod agent add`);
+    return 2;
+  }
+  const refusal = agentTypeRefusal(agent.type);
+  if (refusal !== undefined) {
+    err(`Agent ${agent.id} has type ${agent.type}: ${refusal}`);
+    return 2;
+  }
+
+  // The wake is a read-modify-write compare-and-swap (ADR 0018): the record is
+  // re-read inside the registry lock and the condition re-verified, so a pass
+  // that woke the pod between the check above and here wins and this skips.
+  const woke = await withRegistryLock(async () => {
+    const current = await readPods();
+    const target = current.find((candidate) => candidate.id === pod.id);
+    if (!target || target.state !== "idle") return false;
+    if (target.after !== undefined) {
+      const upstream = current.find((candidate) => candidate.id === target.after);
+      if (upstream?.state !== "done") return false;
+    }
+    if (!projectHasCapacity(target.project, current, await readProjects())) return false;
+    // Warm is crash recovery, not the human override: policy is the streak's
+    // and stays exactly where reconcile left it (ADR 0011). A non-warm wake is
+    // a new episode: the park-clearing also clears notifiedAt (ADR 0021).
+    if (!warm) {
+      if (target.policy) {
+        target.policy.failureStreak = 0;
+        delete target.policy.nextWakeAt;
+        delete target.policy.parked;
+      }
+      delete target.notifiedAt;
+    }
+    launchWrapperDetached(target.id, agentId, warm);
+    target.state = "active";
+    await writePods(current);
+    return true;
+  });
+  if (!woke) {
+    // The loser's CAS saw a pod someone else already woke: skip, not an error.
+    err(`Pod ${pod.id} is already running: nothing to wake`);
+    return 0;
+  }
+  out(`woke ${pod.id}${warm ? " (warm)" : ""}`);
+  return 0;
+}
+
+/**
+ * The human's stop (ADR 0003, 0017): signal the wake-up's whole process group
+ * and return — the wrapper owns the wind-down (trap, forward, grace, kill) and
+ * the `cancelled` record. Refusing a non-active pod is a no-op, not an error.
+ */
+async function cancelCmd(
+  rest: string[],
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const pod = await requirePod(rest[0], "cancel", err);
+  if (!pod) return 2;
+
+  if (pod.state !== "active") {
+    err(`pod ${pod.id} is ${pod.state}: nothing to cancel`);
+    return 0;
+  }
+  const wrapper = await readWrapperRecord(pod);
+  if (wrapper === undefined) {
+    // A ghost record: nothing to signal; reconcile owns that verdict (ADR 0002).
+    err(`pod ${pod.id} has no wrapper record: nothing to cancel`);
+    return 0;
+  }
+  // Three-verified (ADR 0020): the recorded pid is live, its start time
+  // matches, and the boot time is this boot's. Otherwise the record points at
+  // a stranger — a recycled pid, or any pid at all after a reboot — and the
+  // pod's verdict stays reconcile's.
+  if (!(await verifyProcess(wrapper))) {
+    err(`pod ${pod.id} recorded process is gone: nothing to signal`);
+    return 0;
+  }
+  if (!signalGroup(wrapper.pgid, "SIGTERM")) {
+    err(`pod ${pod.id} has no live wrapper: nothing to cancel`);
+    return 0;
+  }
+
+  out(`cancel signalled ${pod.id}`);
+  return 0;
+}
+
+/**
+ * The one spawn path: record, workspace, then wake admission (ADR 0022). An
+ * admitted pod gets its detached wrapper; a blocked one waits idle. `spawn`
+ * and a listener's template materialization both walk it (ADR 0007).
+ */
+async function spawnPodRecord(
+  goal: string,
+  project: string,
+  agentId: string,
+  model?: string,
+  after?: string,
+  registryHeld = false,
+): Promise<PodRecord> {
+  const record: PodRecord = {
+    id: newPodId(),
+    goal,
+    state: "spawning",
+    project: resolve(project),
+    ...(after === undefined ? {} : { after }),
+    wakeUps: [],
+    // The policy names the agent and the optional model pin; `--model` beats
+    // the definition's model, which beats the adapter default (ADR 0012).
+    policy: {
+      failureStreak: 0,
+      appliedOutcomes: 0,
+      agent: agentId,
+      ...(model === undefined ? {} : { model }),
+    },
+  };
+  await createPodWorkspace(record);
+
+  const admit = async (): Promise<PodRecord> => {
+    const pods = await readPods();
+    const projects = await readProjects();
+    const upstream = after === undefined
+      ? undefined
+      : pods.find((candidate) => candidate.id === after);
+    const blocked =
+      (after !== undefined && upstream?.state !== "done") ||
+      !projectHasCapacity(record.project, pods, projects);
+    pods.push(record);
+
+    if (blocked) {
+      record.state = "idle";
+      await writePods(pods);
+      return record;
+    }
+
+    await writePods(pods);
+    launchWrapperDetached(record.id, agentId);
+    record.state = "active";
+    await writePods(pods);
+    return record;
+  };
+
+  if (registryHeld) return admit();
+  const spawned = await withRegistryLock(admit);
+  if (spawned === undefined) throw new Error("registry lock unavailable: pod not spawned");
+  return spawned;
+}
+
+async function spawnCmd(
+  words: string[],
+  deps: CliDeps,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const { flags, rest } = parseFlags(words, ["agent", "model", "cwd", "project", "after"]);
+  const goal = rest.join(" ").trim();
+  if (!goal) {
+    err("Usage: agents-pod spawn <goal prompt> [--agent <id>] [--model <id>] [--cwd <dir>] [--after <podId>]");
+    return 2;
+  }
+
+  // Fail fast at the surface (ADR 0012): an unknown id is an exit-2
+  // configuration error, before any pod record or workspace exists. An
+  // unsupported adapter type is the same kind of error, and refusing it here
+  // keeps a pod from being born into a wake-up that can only fail.
+  const agentId = flags.agent ?? "default";
+  const agent = resolveAgentDefinition(await readAgents(), agentId);
+  if (!agent) {
+    err(`Unknown agent ${agentId}: define it with agents-pod agent add`);
+    return 2;
+  }
+  const refusal = agentTypeRefusal(agent.type);
+  if (refusal !== undefined) {
+    err(`Agent ${agent.id} has type ${agent.type}: ${refusal}`);
+    return 2;
+  }
+
+  if (flags.after !== undefined) {
+    const upstream = (await readPods()).find((candidate) => candidate.id === flags.after);
+    if (upstream === undefined) {
+      err(`Unknown pod ${flags.after}`);
+      return 2;
+    }
+  }
+
+  const record = await spawnPodRecord(
+    goal,
+    flags.project ?? flags.cwd ?? deps.cwd ?? process.cwd(),
+    agentId,
+    flags.model,
+    flags.after,
+  );
+  out(record.id);
+  return 0;
+}
+
+/** Per-project wake-up capacity: a small persistent guardrail, not a scheduler. */
+async function projectCmd(
+  words: string[],
+  deps: CliDeps,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const [sub, ...rest] = words;
+  const { flags, rest: positional } = parseFlags(rest, ["project"]);
+  const project = resolve(flags.project ?? deps.cwd ?? process.cwd());
+  if (sub !== "cap" || positional.length > 1) {
+    err("Usage: agents-pod project cap [n|unlimited] [--project <dir>]");
+    return 2;
+  }
+
+  if (positional.length === 0) {
+    const maxActive = projectMaxActive(project, await readProjects());
+    out(`${project}  ${maxActive === undefined ? "unlimited" : maxActive}`);
+    return 0;
+  }
+
+  const value = positional[0]!;
+  const maxActive = value === "unlimited" ? undefined : Number(value);
+  if (maxActive !== undefined && (!Number.isInteger(maxActive) || maxActive < 1)) {
+    err("Project capacity must be a positive integer or unlimited");
+    return 2;
+  }
+  const updated = await withRegistryLock(async () => {
+    const projects = await readProjects();
+    const remaining = projects.filter((candidate) => resolve(candidate.project) !== project);
+    if (maxActive !== undefined) remaining.push({ project, maxActive });
+    await writeProjects(remaining);
+    return true;
+  });
+  if (updated === undefined) {
+    err("registry lock unavailable: project capacity not changed");
+    return 2;
+  }
+  out(`${project}  ${maxActive === undefined ? "unlimited" : maxActive}`);
+  return 0;
+}
+
+/** The first line of role instructions is the list's one-line handle. */
+function instructionsHeadline(instructions: string): string {
+  return instructions.split("\n", 1)[0]!.trim() || "(no role instructions)";
+}
+
+/**
+ * `agents-pod agent` is add / edit / rm / list (ADR 0012): one machine-global
+ * store, no version numbers, no pin flags, no `--force` ceremony. Definitions
+ * are the operator's worker identities, so the store is a file a human reads.
+ */
+async function agentCmd(
+  words: string[],
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const [sub, ...rest] = words;
+  switch (sub) {
+    case "list": {
+      const agents = await readAgents();
+      if (rest.includes("--json")) {
+        out(
+          JSON.stringify(
+            agents.map((agent) => ({
+              id: agent.id,
+              type: agent.type,
+              model: agent.model ?? null,
+              instructions: agent.instructions,
+              displayName: agent.displayName ?? null,
+            })),
+          ),
+        );
+        return 0;
+      }
+      for (const agent of agents) {
+        out(
+          `${agent.id}  ${agent.type}  ${agent.model ?? "-"}  ${instructionsHeadline(agent.instructions)}`,
+        );
+      }
+      return 0;
+    }
+
+    case "add": {
+      const { flags, rest: positional } = parseFlags(rest, [
+        "type",
+        "model",
+        "instructions",
+      ]);
+      const id = positional[0];
+      if (!id || flags.type === undefined) {
+        err("Usage: agents-pod agent add <id> --type <pi|claude|codex> [--model <id>] [--instructions <file>]");
+        return 2;
+      }
+      if (!isAgentType(flags.type)) {
+        err(`Unknown agent type ${flags.type}: expected pi, claude, or codex`);
+        return 2;
+      }
+      const refusal = agentTypeRefusal(flags.type);
+      if (refusal !== undefined) {
+        err(`Cannot add agent ${id}: --type ${flags.type} — ${refusal}`);
+        return 2;
+      }
+      const agents = await readAgents();
+      if (agents.some((agent) => agent.id === id)) {
+        err(`Agent ${id} already exists: use agents-pod agent edit ${id}`);
+        return 2;
+      }
+      let instructions = "";
+      if (flags.instructions !== undefined) {
+        // Read once, store the text, never the path (ADR 0012).
+        const body = await readFile(flags.instructions, "utf8").catch(() => undefined);
+        if (body === undefined) {
+          err(`Cannot read instructions file ${flags.instructions}`);
+          return 2;
+        }
+        instructions = body;
+      }
+      agents.push({
+        id,
+        type: flags.type,
+        instructions,
+        ...(flags.model === undefined ? {} : { model: flags.model }),
+      });
+      await writeAgents(agents);
+      return 0;
+    }
+
+    case "edit": {
+      const id = rest.find((word) => !word.startsWith("--"));
+      if (!id) {
+        err("Usage: agents-pod agent edit <id>");
+        return 2;
+      }
+      const agents = await readAgents();
+      const agent = agents.find((candidate) => candidate.id === id);
+      if (!agent) {
+        err(`Unknown agent ${id}`);
+        return 2;
+      }
+      // $EDITOR on the stored text, written back on a clean exit (ADR 0012).
+      const draft = join(tmpdir(), `agents-pod-agent-${randomBytes(6).toString("hex")}.md`);
+      await writeFile(draft, agent.instructions);
+      const editor = process.env.EDITOR?.trim() || "vi";
+      const code = await new Promise<number>((resolve) => {
+        const child = spawn(editor, [draft], { stdio: "inherit" });
+        child.on("error", () => resolve(-1));
+        child.on("close", (exitCode) => resolve(exitCode ?? -1));
+      });
+      const saved = code === 0 ? await readFile(draft, "utf8") : undefined;
+      await unlink(draft).catch(() => undefined);
+      if (saved === undefined) {
+        err(`Editor ${editor} exited ${code}: ${id} is unchanged`);
+        return 2;
+      }
+      agent.instructions = saved;
+      await writeAgents(agents);
+      return 0;
+    }
+
+    case "rm": {
+      const id = rest.find((word) => !word.startsWith("--"));
+      if (!id) {
+        err("Usage: agents-pod agent rm <id>");
+        return 2;
+      }
+      const agents = await readAgents();
+      const remaining = agents.filter((agent) => agent.id !== id);
+      if (remaining.length === agents.length) {
+        err(`Unknown agent ${id}`);
+        return 2;
+      }
+      // No --force: pods still referencing it park at the next reconcile (ADR 0012).
+      await writeAgents(remaining);
+      return 0;
+    }
+
+    default:
+      err(`Unknown agent command: ${sub ?? "(none)"}. Try: add | edit | rm | list`);
+      return 2;
+  }
+}
+
+/** Sources are named operator commands; configuration errors fail fast (ADR 0024). */
+async function sourceCmd(
+  words: string[],
+  deps: CliDeps,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const [sub, ...rest] = words;
+  switch (sub) {
+    case "list": {
+      const sources = await readSources();
+      if (rest.includes("--json")) {
+        out(
+          JSON.stringify(
+            sources.map((source) => ({
+              name: source.name,
+              cmd: source.cmd,
+              timeoutMs: source.timeoutMs,
+              cursor: source.cursor ?? null,
+            })),
+          ),
+        );
+        return 0;
+      }
+      if (sources.length === 0) {
+        out("No sources");
+        return 0;
+      }
+      for (const source of sources) {
+        out(
+          `${source.name}  ${source.cmd}  timeout ${source.timeoutMs / 1000}s  cursor ${source.cursor ?? "-"}`,
+        );
+      }
+      return 0;
+    }
+
+    case "add": {
+      const { flags, rest: positional } = parseFlags(rest, ["cmd", "timeout"]);
+      const name = positional[0];
+      if (positional.length !== 1 || name === undefined || flags.cmd === undefined) {
+        err("Usage: agents-pod source add <name> --cmd <path> [--timeout <s>]");
+        return 2;
+      }
+      const timeoutSeconds = flags.timeout === undefined ? 10 : Number(flags.timeout);
+      const timeoutMs = timeoutSeconds * 1000;
+      if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0 || !Number.isFinite(timeoutMs)) {
+        err(`--timeout must be a positive number, got ${flags.timeout}`);
+        return 2;
+      }
+      const cmd = resolve(deps.cwd ?? process.cwd(), flags.cmd);
+      const info = await stat(cmd).catch(() => undefined);
+      if (info === undefined || !info.isFile()) {
+        err(`Drain command ${cmd} is missing or not a regular file`);
+        return 2;
+      }
+      if (!(await access(cmd, constants.X_OK).then(() => true, () => false))) {
+        err(`Drain command ${cmd} is not executable`);
+        return 2;
+      }
+      const added = await withRegistryLock(async () => {
+        const sources = await readSources();
+        if (sources.some((source) => source.name === name)) return false;
+        sources.push({ name, cmd, timeoutMs });
+        await writeSources(sources);
+        return true;
+      });
+      if (added === undefined) {
+        err("registry lock unavailable: source not added");
+        return 2;
+      }
+      if (!added) {
+        err(`Source ${name} already exists`);
+        return 2;
+      }
+      return 0;
+    }
+
+    case "rm": {
+      const name = rest.find((word) => !word.startsWith("--"));
+      if (name === undefined) {
+        err("Usage: agents-pod source rm <name>");
+        return 2;
+      }
+      const removed = await withRegistryLock(async () => {
+        const sources = await readSources();
+        if (!sources.some((source) => source.name === name)) return "missing" as const;
+        const listeners = await readListeners();
+        if (listeners.some((listener) => listener.source === name)) return "in-use" as const;
+        await writeSources(sources.filter((source) => source.name !== name));
+        return "removed" as const;
+      });
+      if (removed === undefined) {
+        err("registry lock unavailable: source not removed");
+        return 2;
+      }
+      if (removed === "missing") {
+        err(`Unknown source ${name}`);
+        return 2;
+      }
+      if (removed === "in-use") {
+        err(`Source ${name} is still consumed by a Listener`);
+        return 2;
+      }
+      return 0;
+    }
+
+    default:
+      err(`Unknown source command: ${sub ?? "(none)"}. Try: add | list | rm`);
+      return 2;
+  }
+}
+
+/** P0 has one outbound delivery command; configuration errors fail fast (ADR 0025). */
+async function deliverCmd(
+  words: string[],
+  deps: CliDeps,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const [sub, ...rest] = words;
+  switch (sub) {
+    case "list": {
+      const deliverer = await readDeliverer();
+      if (rest.includes("--json")) {
+        out(JSON.stringify(deliverer === undefined ? [] : [deliverer]));
+        return 0;
+      }
+      if (deliverer === undefined) {
+        out("No deliverer");
+        return 0;
+      }
+      out(`${deliverer.name}  ${deliverer.cmd}  timeout ${deliverer.timeoutMs / 1000}s`);
+      return 0;
+    }
+
+    case "add": {
+      const { flags, rest: positional } = parseFlags(rest, ["cmd", "timeout"]);
+      const name = positional[0];
+      if (positional.length !== 1 || name === undefined || flags.cmd === undefined) {
+        err("Usage: agents-pod deliver add <name> --cmd <path> [--timeout <s>]");
+        return 2;
+      }
+      const timeoutSeconds = flags.timeout === undefined ? 10 : Number(flags.timeout);
+      const timeoutMs = timeoutSeconds * 1000;
+      if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0 || !Number.isFinite(timeoutMs)) {
+        err(`--timeout must be a positive number, got ${flags.timeout}`);
+        return 2;
+      }
+      const cmd = resolve(deps.cwd ?? process.cwd(), flags.cmd);
+      const info = await stat(cmd).catch(() => undefined);
+      if (info === undefined || !info.isFile()) {
+        err(`Delivery command ${cmd} is missing or not a regular file`);
+        return 2;
+      }
+      if (!(await access(cmd, constants.X_OK).then(() => true, () => false))) {
+        err(`Delivery command ${cmd} is not executable`);
+        return 2;
+      }
+      const added = await withRegistryLock(async () => {
+        if ((await readDeliverer()) !== undefined) return false;
+        await writeDeliverer({ name, cmd, timeoutMs });
+        return true;
+      });
+      if (added === undefined) {
+        err("registry lock unavailable: deliverer not added");
+        return 2;
+      }
+      if (!added) {
+        err("A deliverer is already configured: remove it before adding another");
+        return 2;
+      }
+      return 0;
+    }
+
+    case "rm": {
+      const name = rest.find((word) => !word.startsWith("--"));
+      if (name === undefined) {
+        err("Usage: agents-pod deliver rm <name>");
+        return 2;
+      }
+      const removed = await withRegistryLock(async () => {
+        const deliverer = await readDeliverer();
+        if (deliverer?.name !== name) return false;
+        await rm(delivererFile(), { force: true });
+        return true;
+      });
+      if (removed === undefined) {
+        err("registry lock unavailable: deliverer not removed");
+        return 2;
+      }
+      if (!removed) {
+        err(`Unknown deliverer ${name}`);
+        return 2;
+      }
+      return 0;
+    }
+
+    default:
+      err(`Unknown deliver command: ${sub ?? "(none)"}. Try: add | list | rm`);
+      return 2;
+  }
+}
+
+/**
+ * `agents-pod listener` is add / list / rm (ADR 0007): a listener is a registry
+ * record, never a process. Bad references are exit-2 configuration errors
+ * (ADR 0012's fail-fast habit), and add/rm take the registry lock because a
+ * pass rewrites listeners.json wholesale — an unlocked add could be overwritten.
+ */
+async function listenerCmd(
+  words: string[],
+  deps: CliDeps,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const [sub, ...rest] = words;
+  switch (sub) {
+    case "list": {
+      const listeners = await readListeners();
+      if (rest.includes("--json")) {
+        out(
+          JSON.stringify(
+            listeners.map((listener) => ({
+              id: listener.id,
+              inbox: listener.inbox ?? null,
+              source: listener.source ?? null,
+              match: listener.match ?? null,
+              mode: listener.mode,
+              template: listener.template ?? null,
+              project: listener.project ?? null,
+              podId: listener.podId ?? null,
+              maxConcurrent: listener.maxConcurrent,
+              claimed: listener.claimed ?? [],
+            })),
+          ),
+        );
+        return 0;
+      }
+      if (listeners.length === 0) {
+        out("No listeners");
+        return 0;
+      }
+      for (const listener of listeners) {
+        const target =
+          listener.mode === "template"
+            ? `template ${listener.template}`
+            : `pod ${listener.podId}`;
+        const origin = listener.source === undefined ? listener.inbox : `source:${listener.source}`;
+        out(`${listener.id}  ${target}  ${origin}  claimed ${listener.claimed?.length ?? 0}`);
+      }
+      return 0;
+    }
+
+    case "add": {
+      const { flags } = parseFlags(rest, [
+        "inbox",
+        "source",
+        "template",
+        "pod",
+        "match",
+        "max-concurrent",
+        "project",
+      ]);
+      const usage =
+        "Usage: agents-pod listener add (--inbox <dir|file> | --source <name>) (--template <file> | --pod <podId>) [--match <substr>] [--max-concurrent <n>] [--project <dir>]";
+      if ((flags.inbox === undefined) === (flags.source === undefined)) {
+        err(`listener add takes exactly one of --inbox or --source. ${usage}`);
+        return 2;
+      }
+      // A listener has one target, exactly (ADR 0007): a fresh pod per item, or
+      // a bound standing pod's queue.
+      if ((flags.template === undefined) === (flags.pod === undefined)) {
+        err(`listener add takes exactly one of --template <file> or --pod <podId>. ${usage}`);
+        return 2;
+      }
+
+      const cwd = deps.cwd ?? process.cwd();
+      // Only a template materializes a Pod, so only a template has a destination
+      // project; a bound standing Pod already lives where it lives (ADR 0007).
+      if (flags.project !== undefined && flags.pod !== undefined) {
+        err(`--project needs --template: a bound standing Pod keeps its own project. ${usage}`);
+        return 2;
+      }
+      const targetProject =
+        flags.project === undefined ? undefined : resolve(cwd, flags.project);
+      if (targetProject !== undefined) {
+        const info = await stat(targetProject).catch(() => undefined);
+        if (info === undefined || !info.isDirectory()) {
+          err(`Project ${targetProject} does not exist or is not a directory`);
+          return 2;
+        }
+      }
+      const inbox = flags.inbox === undefined ? undefined : resolve(cwd, flags.inbox);
+      if (inbox !== undefined && !(await exists(inbox))) {
+        err(`Inbox ${inbox} does not exist: pass a directory or a JSONL file`);
+        return 2;
+      }
+      if (
+        flags.source !== undefined &&
+        !(await readSources()).some((source) => source.name === flags.source)
+      ) {
+        err(`Unknown source ${flags.source}`);
+        return 2;
+      }
+
+      let maxConcurrent = 1;
+      if (flags["max-concurrent"] !== undefined) {
+        const parsed = Number(flags["max-concurrent"]);
+        if (!Number.isInteger(parsed) || parsed < 1) {
+          err(`--max-concurrent must be a positive integer, got ${flags["max-concurrent"]}`);
+          return 2;
+        }
+        maxConcurrent = parsed;
+      }
+
+      const listener: ListenerRecord = {
+        id: newListenerId(),
+        ...(inbox === undefined ? { source: flags.source! } : { inbox }),
+        mode: "template",
+        ...(targetProject === undefined ? {} : { project: targetProject }),
+        maxConcurrent,
+        claimed: [],
+        seen: [],
+      };
+      if (flags.match !== undefined) listener.match = flags.match;
+
+      if (flags.template !== undefined) {
+        // Read once to prove the reference, store the path (ADR 0007): the
+        // template is the operator's file, edited in place between passes.
+        const template = resolve(cwd, flags.template);
+        if ((await readFile(template, "utf8").catch(() => undefined)) === undefined) {
+          err(`Cannot read template file ${template}`);
+          return 2;
+        }
+        listener.template = template;
+      } else {
+        const pod = (await readPods()).find((candidate) => candidate.id === flags.pod);
+        if (!pod) {
+          err(`Unknown pod ${flags.pod}`);
+          return 2;
+        }
+        listener.mode = "pod";
+        listener.podId = pod.id;
+      }
+
+      const added = await withRegistryLock(async () => {
+        if (
+          listener.source !== undefined &&
+          !(await readSources()).some((source) => source.name === listener.source)
+        ) {
+          return false;
+        }
+        const listeners = await readListeners();
+        listeners.push(listener);
+        await writeListeners(listeners);
+        return true;
+      });
+      if (added === undefined) {
+        err("registry lock unavailable: listener not added");
+        return 2;
+      }
+      if (!added) {
+        err(`Unknown source ${listener.source}`);
+        return 2;
+      }
+      out(listener.id);
+      return 0;
+    }
+
+    case "rm": {
+      const id = rest.find((word) => !word.startsWith("--"));
+      if (!id) {
+        err("Usage: agents-pod listener rm <listenerId>");
+        return 2;
+      }
+      const removed = await withRegistryLock(async () => {
+        const listeners = await readListeners();
+        const remaining = listeners.filter((listener) => listener.id !== id);
+        if (remaining.length === listeners.length) return false;
+        // Claims go with the record: re-adding is a fresh claim namespace (ADR 0013).
+        await writeListeners(remaining);
+        return true;
+      });
+      if (removed === undefined) {
+        err("registry lock unavailable: listener not removed");
+        return 2;
+      }
+      if (!removed) {
+        err(`Unknown listener ${id}`);
+        return 2;
+      }
+      return 0;
+    }
+
+    default:
+      err(`Unknown listener command: ${sub ?? "(none)"}. Try: add | list | rm`);
+      return 2;
+  }
+}
+
+export async function main(argv: string[], deps: CliDeps = {}): Promise<number> {
+  const out = deps.stdout ?? ((line: string) => console.log(line));
+  const err = deps.stderr ?? ((line: string) => console.error(line));
+  const [cmd, ...rest] = argv;
+
+  switch (cmd) {
+    case "spawn":
+      return spawnCmd(rest, deps, out, err);
+    case "status":
+      return statusCmd(rest, out, err);
+    case "list":
+      return listCmd(out);
+    case "logs":
+      return logsCmd(rest, out, err);
+    case "wake":
+      return wakeCmd(rest, out, err);
+    case "cancel":
+      return cancelCmd(rest, out, err);
+    case "reconcile":
+      return reconcileCmd(deps);
+    case "agent":
+      return agentCmd(rest, out, err);
+    case "listener":
+      return listenerCmd(rest, deps, out, err);
+    case "source":
+      return sourceCmd(rest, deps, out, err);
+    case "deliver":
+      return deliverCmd(rest, deps, out, err);
+    case "project":
+      return projectCmd(rest, deps, out, err);
+    default:
+      err(`Unknown command: ${cmd ?? "(none)"}. Try: spawn | list | status | logs | wake | cancel | reconcile | agent | listener | source | deliver | project`);
+      return 2;
+  }
+}