agents-pod 0.1.0 → 0.3.0

package/src/cli.ts

@@ -1,6 +1,8 @@
 import { randomBytes } from "node:crypto";
 import { spawn } from "node:child_process";
+import { constants } from "node:fs";
 import {
+  access,
   appendFile,
   mkdir,
   readFile,
@@ -20,6 +22,11 @@ import {
   writeAgents,
 } from "./agents-store.ts";
 import { renderTemplate, scanInbox, type InboxItem } from "./inbox.ts";
+import {
+  doctor,
+  type DoctorMark,
+  type DoctorReport,
+} from "./doctor.ts";
 import {
   claimKey,
   newListenerId,
@@ -31,7 +38,8 @@ 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, podDir, reconcileLockPath } from "./paths.ts";
+import { cronLogPath, delivererFile, lastPassFile, podDir, reconcileLockPath } from "./paths.ts";
+import { readDeliverer, retryOutbox, writeDeliverer } from "./outbox.ts";
 import {
   projectHasCapacity,
   projectMaxActive,
@@ -40,6 +48,15 @@ import {
 } from "./projects.ts";
 import type { PodRecord } from "./registry.ts";
 import { readPods, withRegistryLock, writePods } from "./registry.ts";
+import {
+  commitSourceCursors,
+  drainSources,
+  pruneSourceClaims,
+  readSources,
+  recordSourceFailure,
+  writeSources,
+  type SourceDrain,
+} from "./sources.ts";
 import {
   HEARTBEAT_STALE_MS,
   WEDGED_ESCALATE_MS,
@@ -225,22 +242,54 @@ async function acquireReconcileLock(): Promise<boolean> {
  * queued while policy is derived, recorded in `notifiedAt`, and delivered
  * after the locks are gone — a slow channel never holds the registry.
  *
- * The body runs inside the registry lock (ADR 0018): pods.json is re-read
- * 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.
+ * 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 live under the project the tick was invoked from:
-  // the cron line's cwd is the project (ADR 0007, ADR 0004).
+  // 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 {
-    pending = (await withRegistryLock(() => reconcilePass(notify, project))) ?? [];
+    // 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`,
+        );
+        // The failure is also a record fact, so `doctor` can report it without
+        // tailing cron.log (ADR 0027).
+        await recordSourceFailure(result.name, result.error);
+      }
+      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());
+    // The pass marker (ADR 0027): without it, "cron is not installed" and
+    // "cron runs and finds nothing" are the same silence in every report.
+    await writeFile(lastPassFile(), `${JSON.stringify({ at: Date.now() })}\n`).catch(() => undefined);
   }
   // 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.
@@ -259,6 +308,7 @@ async function reconcileCmd(deps: CliDeps = {}): Promise<number> {
 async function reconcilePass(
   notify: NotificationsConfig,
   project: string,
+  drained: SourceDrain[],
 ): Promise<PodNotification[]> {
   const pods = await readPods();
   const agents = await readAgents();
@@ -372,6 +422,10 @@ async function reconcilePass(
       }
     }
 
+    // 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) {
@@ -434,7 +488,7 @@ async function reconcilePass(
   // 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);
+  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
@@ -468,6 +522,12 @@ async function wakeDuePods(now: number): Promise<void> {
   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);
@@ -489,7 +549,7 @@ function matchesListener(rule: string | undefined, item: InboxItem): boolean {
  * 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): Promise<void> {
+async function listenersPass(project: string, drained: SourceDrain[]): Promise<void> {
   const listeners = await readListeners();
   if (listeners.length === 0) return;
 
@@ -507,13 +567,27 @@ async function listenersPass(project: string): Promise<void> {
 
   // Phase 1: scan, hold the stability memory, and claim. Nothing is spawned yet.
   for (const listener of listeners) {
-    const scan = await scanInbox(listener.inbox);
-    itemsByListener.set(listener.id, new Map(scan.items.map((item) => [item.id, item])));
+    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);
-      await appendCronLog(
-        `listener ${listener.id}: inbox ${listener.inbox} unreadable (${scan.error})`,
-      );
+      if (listener.source === undefined) {
+        await appendCronLog(
+          `listener ${listener.id}: inbox ${listener.inbox} unreadable (${scan.error})`,
+        );
+      }
       continue;
     }
     for (const bad of scan.bad) {
@@ -522,24 +596,27 @@ async function listenersPass(project: string): Promise<void> {
       );
     }
 
-    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;
+    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;
+        }
       }
-    }
-    const stable: InboxItem[] = [];
-    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;
+      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()];
     }
-    listener.seen = [...seen.values()];
 
     const pendingClaims = listener.claimed.filter(
       (claim) => claim.spawnedPodId === undefined && claim.blocked === undefined,
@@ -549,20 +626,29 @@ async function listenersPass(project: string): Promise<void> {
       (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.
+    // 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.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(listener.inbox, item.id);
+      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: listener.inbox, item: item.id });
+      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;
@@ -575,7 +661,7 @@ async function listenersPass(project: string): Promise<void> {
   // Phase 2: materialize what is claimed and still unserved.
   let materialized = false;
   for (const listener of listeners) {
-    if (listener.mode !== "template") continue;
+    if (listener.mode !== "template" || unscannable.has(listener.id)) continue;
     const pending = () =>
       listener.claimed.filter(
         (claim) => claim.spawnedPodId === undefined && claim.blocked === undefined,
@@ -620,7 +706,7 @@ async function listenersPass(project: string): Promise<void> {
       }
       const record = await spawnPodRecord(
         rendered.goal,
-        project,
+        listener.project ?? project,
         "default",
         undefined,
         undefined,
@@ -693,6 +779,35 @@ async function listenersPass(project: string): Promise<void> {
   // 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 {
@@ -1324,6 +1439,209 @@ async function agentCmd(
   }
 }
 
+/** 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
@@ -1345,10 +1663,12 @@ async function listenerCmd(
           JSON.stringify(
             listeners.map((listener) => ({
               id: listener.id,
-              inbox: listener.inbox,
+              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 ?? [],
@@ -1366,19 +1686,26 @@ async function listenerCmd(
           listener.mode === "template"
             ? `template ${listener.template}`
             : `pod ${listener.podId}`;
-        out(
-          `${listener.id}  ${target}  ${listener.inbox}  claimed ${listener.claimed?.length ?? 0}`,
-        );
+        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", "template", "pod", "match", "max-concurrent"]);
+      const { flags } = parseFlags(rest, [
+        "inbox",
+        "source",
+        "template",
+        "pod",
+        "match",
+        "max-concurrent",
+        "project",
+      ]);
       const usage =
-        "Usage: agents-pod listener add --inbox <dir|file> [--template <file> | --pod <podId>] [--match <substr>] [--max-concurrent <n>]";
-      if (flags.inbox === undefined) {
-        err(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
@@ -1389,11 +1716,33 @@ async function listenerCmd(
       }
 
       const cwd = deps.cwd ?? process.cwd();
-      const inbox = resolve(cwd, flags.inbox);
-      if (!(await exists(inbox))) {
+      // 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) {
@@ -1407,8 +1756,9 @@ async function listenerCmd(
 
       const listener: ListenerRecord = {
         id: newListenerId(),
-        inbox,
+        ...(inbox === undefined ? { source: flags.source! } : { inbox }),
         mode: "template",
+        ...(targetProject === undefined ? {} : { project: targetProject }),
         maxConcurrent,
         claimed: [],
         seen: [],
@@ -1435,6 +1785,12 @@ async function listenerCmd(
       }
 
       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);
@@ -1444,6 +1800,10 @@ async function listenerCmd(
         err("registry lock unavailable: listener not added");
         return 2;
       }
+      if (!added) {
+        err(`Unknown source ${listener.source}`);
+        return 2;
+      }
       out(listener.id);
       return 0;
     }
@@ -1479,11 +1839,70 @@ async function listenerCmd(
   }
 }
 
+const MARKS: Record<DoctorMark, string> = { ok: "✓", bad: "✗", note: "?" };
+
+/** One line per finding, then the first run only when it is what is missing (ADR 0027). */
+function printDoctor(report: DoctorReport, out: (line: string) => void): void {
+  out(`agents-pod doctor  ${report.store}`);
+  if (report.sections.length > 0) out("");
+  for (const section of report.sections) {
+    section.lines.forEach((line, index) => {
+      const head = index === 0 ? section.title.padEnd(10) : " ".repeat(10);
+      out(`${head}${MARKS[line.mark]} ${line.text}`);
+      for (const detail of line.detail ?? []) out(`${" ".repeat(12)}${detail}`);
+    });
+  }
+  if (report.recipe.length > 0) {
+    out("");
+    out(
+      report.sections.length === 0
+        ? "nothing is configured yet — the first run, in order:"
+        : "still missing:",
+    );
+    for (const step of report.recipe) out(`  ${step}`);
+  }
+}
+
+/**
+ * `doctor` is read-only, and `--probe` is its only mode that runs operator code
+ * (ADR 0027). Exit 0 healthy, 1 something blocks a channel, 2 bad usage.
+ */
+async function doctorCmd(
+  words: string[],
+  deps: CliDeps,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const unknown = words.filter((word) => word !== "--probe" && word !== "--json");
+  if (unknown.length > 0) {
+    err(`Unknown doctor argument: ${unknown[0]}. Usage: agents-pod doctor [--probe] [--json]`);
+    return 2;
+  }
+  const report = await doctor({
+    probe: words.includes("--probe"),
+    ...(deps.cwd === undefined ? {} : { cwd: deps.cwd }),
+  });
+  if (words.includes("--json")) out(JSON.stringify(report));
+  else printDoctor(report, out);
+  return report.healthy ? 0 : 1;
+}
+
 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;
 
+  // The bare invocation is where a first run happens, so it points at the
+  // report that says what is missing (ADR 0027).
+  if (cmd === undefined) {
+    out("agents-pod — standing Pods across days, one cron-ticked pass");
+    out("");
+    out("start here  agents-pod doctor   what is missing on this machine, and the command that fixes it");
+    out("pods        spawn | list | status <id> | logs <id> | wake <id> | cancel <id>");
+    out("records     agent | listener | source | deliver | project | reconcile");
+    return 0;
+  }
+
   switch (cmd) {
     case "spawn":
       return spawnCmd(rest, deps, out, err);
@@ -1503,10 +1922,16 @@ export async function main(argv: string[], deps: CliDeps = {}): Promise<number>
       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);
+    case "doctor":
+      return doctorCmd(rest, deps, out, err);
     default:
-      err(`Unknown command: ${cmd ?? "(none)"}. Try: spawn | list | status | logs | wake | cancel | reconcile | agent | listener | project`);
+      err(`Unknown command: ${cmd ?? "(none)"}. Try: doctor | spawn | list | status | logs | wake | cancel | reconcile | agent | listener | source | deliver | project`);
       return 2;
   }
 }