agents-pod 0.3.6 → 0.3.7

package/src/cli.ts

@@ -40,6 +40,7 @@ import {
   newListenerId,
   readListeners,
   writeListeners,
+  type ClaimRecord,
   type ListenerRecord,
 } from "./listeners.ts";
 import { acquireLock, readLock, releaseLock, sleep } from "./locks.ts";
@@ -116,27 +117,59 @@ function launchWrapperDetached(podId: string, agentId?: string, warm = false): v
  * value; one that arrives without a value is reported as `dangling` — left in
  * `rest` it would become part of a goal (`spawn fix it --wake-budget`) and the
  * command would proceed with the flag silently unset.
+ *
+ * A token that begins with `--` is the *next* flag's name, never this flag's
+ * value: `spawn … --model --dormant` used to set `model` to the literal string
+ * `--dormant`, drop the dormancy and launch the wake-up the flag was there to
+ * prevent (#43 review). No flag's value is a flag name — an agent id, a model
+ * id, a path, a pod id and a count never start with `--` — so the token stays
+ * unconsumed and this flag is reported dangling, exactly as if it had arrived
+ * last. A single leading `-` is still a value (`--wake-budget -3` must reach the
+ * integer check, not the usage error).
  */
 function parseFlags(
   words: string[],
   allowed: readonly string[],
-): { flags: Record<string, string>; rest: string[]; dangling: string[] } {
+  multi: readonly string[] = [],
+): {
+  flags: Record<string, string>;
+  multiFlags: Record<string, string[]>;
+  rest: string[];
+  dangling: string[];
+} {
   const flags: Record<string, string> = {};
+  const multiFlags: Record<string, string[]> = {};
   const rest: string[] = [];
   const dangling: 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];
+    const next = words[index + 1];
+    const value = next !== undefined && !next.startsWith("--") ? next : undefined;
     if (name !== undefined && allowed.includes(name) && value !== undefined) {
-      flags[name] = value;
+      // A flag that may repeat keeps every value (ADR 0034's `--chat`): a scalar
+      // would silently drop all but the last group.
+      if (multi.includes(name)) (multiFlags[name] ??= []).push(value);
+      else flags[name] = value;
       index += 1;
     } else {
       if (name !== undefined && allowed.includes(name)) dangling.push(`--${name}`);
       rest.push(word);
     }
   }
-  return { flags, rest, dangling };
+  return { flags, multiFlags, rest, dangling };
+}
+
+/**
+ * The routing filter as one rule (ADR 0034): the groups an item's `chat_id` must
+ * be among, ANDed with the text substring. An item with no routing field can
+ * never satisfy a filter; that is a fact about directory items, and `listener
+ * add` refuses to write a filter they could never match.
+ */
+function routingChats(values: readonly string[] | undefined): string[] | undefined {
+  if (values === undefined) return undefined;
+  const chats = values.map((value) => value.trim()).filter((value) => value !== "");
+  return chats.length === 0 ? undefined : chats;
 }
 
 /** Exponential backoff after `failed`/`lost`: 1m ×2, capped at 15m (ADR 0011). */
@@ -720,10 +753,47 @@ function livePod(claimedBy: string, pods: PodRecord[]): boolean {
   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);
+/**
+ * A Listener's match rule (ADRs 0007, 0034): a routing filter over the item's
+ * `chat_id`, ANDed with a plain substring over title and body. Either half alone
+ * is a rule; both together must hold.
+ */
+function matchesListener(
+  rule: Pick<ListenerRecord, "match" | "chats">,
+  item: InboxItem,
+): boolean {
+  if (rule.chats !== undefined && rule.chats.length > 0) {
+    if (item.chatId === undefined || !rule.chats.includes(item.chatId)) return false;
+  }
+  if (rule.match === undefined || rule.match === "") return true;
+  return `${item.title}\n${item.body}`.includes(rule.match);
+}
+
+/**
+ * A Source claim owns its item after the drain has moved on (ADR 0034). Claims
+ * written before that decision fall back to this pass's scan. Filesystem inbox
+ * claims carry no copy at all: `{{path}}` and deletion are meaningful there, and
+ * the file itself is the truth.
+ */
+function itemForClaim(
+  listener: ListenerRecord,
+  claim: ClaimRecord,
+  scanned: InboxItem | undefined,
+): InboxItem | undefined {
+  if (listener.source === undefined || claim.title === undefined || claim.body === undefined) {
+    return scanned;
+  }
+  return {
+    id: claim.item,
+    title: claim.title,
+    body: claim.body,
+    path: "",
+    mtimeMs: 0,
+    size: 0,
+    ...(claim.chatId === undefined ? {} : { chatId: claim.chatId }),
+    ...(claim.rootId === undefined ? {} : { rootId: claim.rootId }),
+    ...(claim.threadId === undefined ? {} : { threadId: claim.threadId }),
+  };
 }
 
 /**
@@ -741,10 +811,20 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
 
   /** The inbox, not the listener, is the claim namespace (ADR 0013). */
   const claimedInInbox = new Set<string>();
+  const deferredClaims = new Set<ClaimRecord>();
   for (const listener of listeners) {
     listener.claimed ??= [];
     listener.seen ??= [];
-    for (const claim of listener.claimed) claimedInInbox.add(claimKey(claim.inbox, claim.item));
+    for (const claim of listener.claimed) {
+      claimedInInbox.add(claimKey(claim.inbox, claim.item));
+      if (
+        claim.spawnedPodId === undefined &&
+        claim.blocked === undefined &&
+        claim.appended !== true
+      ) {
+        deferredClaims.add(claim);
+      }
+    }
   }
 
   const itemsByListener = new Map<string, Map<string, InboxItem>>();
@@ -813,9 +893,9 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
     ).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.
+    // claim is unbounded too: the cursor commits behind the claims, so an
+    // unclaimed item would be lost rather than re-scanned. Its item copy lets
+    // the bound defer only materialization, not the content itself (ADR 0034).
     let room =
       listener.mode === "pod" || listener.source !== undefined
         ? Number.POSITIVE_INFINITY
@@ -824,16 +904,28 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
     for (const item of stable) {
       if (room <= 0) break;
       const key = claimKey(origin, item.id);
-      if (claimedInInbox.has(key) || !matchesListener(listener.match, item)) continue;
+      if (claimedInInbox.has(key) || !matchesListener(listener, 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.
+      // phase 3 (ADR 0014). Claim first, always. Only a Source claim copies its
+      // item (ADR 0034): a filesystem item is still on disk and the document is
+      // the truth there, so a copy would only swell `listeners.json` with
+      // bodies nothing ever reads.
       listener.claimed.push({
         inbox: origin,
         item: item.id,
         ...(sourceDrain?.drainedAt === undefined
           ? {}
           : { claimedAt: sourceDrain.drainedAt }),
+        ...(listener.source === undefined
+          ? {}
+          : {
+              title: item.title,
+              body: item.body,
+              ...(item.chatId === undefined ? {} : { chatId: item.chatId }),
+              ...(item.rootId === undefined ? {} : { rootId: item.rootId }),
+              ...(item.threadId === undefined ? {} : { threadId: item.threadId }),
+            }),
       });
       claimedInInbox.add(key);
       changed = true;
@@ -841,6 +933,18 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
     }
   }
 
+  // Routing makes "nobody wants this group" an ordinary state, so the pass counts
+  // it (ADR 0034): unique ids only, because the overlap re-emits the same message
+  // pass after pass, and a filter's whole job is to leave some of them unclaimed.
+  for (const drain of drained) {
+    if (drain.error !== undefined) continue;
+    let unrouted = 0;
+    for (const id of new Set(drain.items.map((item) => item.id))) {
+      if (!claimedInInbox.has(claimKey(`source:${drain.name}`, id))) unrouted += 1;
+    }
+    drain.unrouted = unrouted;
+  }
+
   // The claim is on disk before any pod is touched (ADR 0007).
   if (changed) await writeListeners(listeners);
 
@@ -872,7 +976,11 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
     ).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);
+      const item = itemForClaim(
+        listener,
+        claim,
+        itemsByListener.get(listener.id)?.get(claim.item),
+      );
       if (item === undefined) {
         claim.blocked = "item vanished before materialization";
         await appendCronLog(
@@ -912,7 +1020,7 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
   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
+    if (unscannable.has(listener.id)) continue; // a failed scan still waits for a successful retry
     const waiting = listener.claimed.filter(
       (claim) => claim.blocked === undefined && claim.appended !== true,
     );
@@ -928,12 +1036,12 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
     }
     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.
+    // The body is copied at append time (ADR 0014). A Source claim supplies its
+    // own copy; a legacy claim or filesystem inbox still needs the current scan.
     const scanned = itemsByListener.get(listener.id);
     const batch: InboxItem[] = [];
     for (const claim of waiting) {
-      const item = scanned?.get(claim.item);
+      const item = itemForClaim(listener, claim, scanned?.get(claim.item));
       if (item === undefined) {
         claim.blocked = "item vanished before append";
         await appendCronLog(
@@ -979,10 +1087,11 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
 
   // 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).
+  // its claims must also be appended, preserving ADR 0014's document handoff.
+  // While a wake-up holds the append back, the unchanged cursor makes the next
+  // pass drain the same items again; their snapshots now cover a drain that
+  // does not (ADR 0034). 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(
@@ -1002,8 +1111,18 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
   const committable = drained.filter(
     (drain) => consumed.has(drain.name) && !waitingForAppend.has(drain.name),
   );
-  const pruning = pruneSourceClaims(listeners, committable);
+  const pruning = pruneSourceClaims(listeners, committable, deferredClaims);
   if (pruning.changed) await writeListeners(pruning.listeners);
+  // The count is a fact of the pass that committed it, printed once: a group an
+  // operator never aimed a Listener at is legitimate, a group nothing wants is
+  // what they need told (ADR 0034).
+  for (const drain of committable) {
+    if ((drain.unrouted ?? 0) > 0) {
+      await appendCronLog(
+        `source ${drain.name}: ${drain.unrouted} item(s) matched no listener (unrouted, the cursor passed them)`,
+      );
+    }
+  }
   await commitSourceCursors(committable);
 }
 
@@ -1091,18 +1210,30 @@ async function statusCmd(
   const last = pod.wakeUps.at(-1);
   out(pod.id);
   out(`  goal: ${goalHeadline(pod.goal)}`);
-  // The suffix qualifies a resting pod: `awaiting` says why the tick leaves it
-  // alone, and a live wake-up is a different answer to the same question.
-  const awaiting = pod.policy?.awaiting === true && pod.state === "idle";
-  out(`  state: ${pod.state}${awaiting ? " (awaiting)" : ""}`);
   // Who admits this Pod (ADR 0030) — the fact that decides whether the tick
-  // wakes it at all, so `status` says it before it says anything about liveness.
+  // wakes it at all, so the record's owner is read before the state line, which
+  // now also depends on it.
   const bound = new Set(
     (await readListeners()).flatMap((listener) =>
       listener.mode === "pod" && listener.podId !== undefined ? [listener.podId] : [],
     ),
   );
   const owner = admissionOf(pod, bound);
+  // The suffix qualifies a resting pod: `awaiting` says why the tick leaves it
+  // alone, and a live wake-up is a different answer to the same question.
+  const awaiting = pod.policy?.awaiting === true && pod.state === "idle";
+  // `dormant` (#43): the record exists and no wake-up has ever run, so the first
+  // one still belongs to the owner — the fact a spawn wrote and a hybrid ask
+  // depends on. Derived, never stored: the empty wake-up list is the fact, and a
+  // marker would have to be cleared by three launchers. A Pod the tick owns is
+  // never reported this way; the tick is on its way to it.
+  const dormant = pod.state === "idle" && pod.wakeUps.length === 0 && owner !== "self";
+  out(
+    `  state: ${pod.state}${awaiting ? " (awaiting)" : ""}${
+      dormant ? " (dormant: no wake-up yet)" : ""
+    }`,
+  );
+  // The owner line comes before anything about liveness (ADR 0030).
   out(
     `  admission: ${owner}${
       pod.admission === undefined
@@ -1153,19 +1284,51 @@ function cadenceLine(pod: PodRecord, now: number): string {
   return `${day} in 24h, ${rhythm}, last trigger ${trigger}`;
 }
 
+/** Terminal states (ADR 0006): what `list` hides by default and `wake` refuses. */
+function isTerminal(pod: PodRecord): boolean {
+  return pod.state === "done" || pod.state === "cancelled";
+}
+
 /**
  * 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.
+ *
+ * Terminal pods are the exception (ADR 0035): a retired Pod asks nothing of a
+ * human, and a wall of `cancelled` records buries the ones that do. They stay
+ * one flag away, and the footer says how many are hidden — silence about them
+ * would make the registry look smaller than it is.
  */
-async function listCmd(out: (line: string) => void): Promise<number> {
+async function listCmd(
+  words: string[],
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const unknown = words.filter((word) => word !== "--all" && word !== "--json");
+  if (unknown.length > 0) {
+    err(`Unknown list argument: ${unknown[0]}. Usage: agents-pod list [--all] [--json]`);
+    return 2;
+  }
+  const all = words.includes("--all");
   const pods = await readPods();
-  if (pods.length === 0) {
-    out("No pods");
+  const visible = all ? pods : pods.filter((pod) => !isTerminal(pod));
+  const hidden = pods.length - visible.length;
+
+  if (visible.length === 0) {
+    out(
+      hidden === 0
+        ? "No pods"
+        : `No live pods (${hidden} terminal: agents-pod list --all)`,
+    );
+    return 0;
+  }
+
+  if (words.includes("--json")) {
+    out(JSON.stringify(visible));
     return 0;
   }
 
   const rows = await Promise.all(
-    pods.map(async (pod) => ({ pod, liveness: await livenessOf(pod) })),
+    visible.map(async (pod) => ({ pod, liveness: await livenessOf(pod) })),
   );
   const needsHuman = (row: (typeof rows)[number]) =>
     row.pod.policy?.parked === true || row.liveness !== "healthy";
@@ -1175,6 +1338,9 @@ async function listCmd(out: (line: string) => void): Promise<number> {
     const parked = pod.policy?.parked ? " (parked)" : "";
     out(`${pod.id}  ${pod.state}${parked}  ${goalHeadline(pod.goal)}`);
   }
+  if (hidden > 0) {
+    out(`${hidden} terminal pod${hidden === 1 ? "" : "s"} hidden (agents-pod list --all)`);
+  }
   return 0;
 }
 
@@ -1268,6 +1434,7 @@ async function wakeCmd(
 
   if (pod.state === "done" || pod.state === "cancelled") {
     err(`Pod ${pod.id} is ${pod.state}: terminal is terminal — spawn a new pod instead`);
+    err(`      or forget it: agents-pod rm ${pod.id}`);
     return 2;
   }
   if (pod.state === "active" || pod.state === "spawning") {
@@ -1388,7 +1555,12 @@ async function cancelCmd(
   if (!pod) return 2;
 
   if (pod.state !== "active") {
-    err(`pod ${pod.id} is ${pod.state}: nothing to cancel`);
+    err(
+      `pod ${pod.id} is ${pod.state}: nothing to cancel (` +
+        (isTerminal(pod)
+          ? `agents-pod rm ${pod.id} removes the record)`
+          : `agents-pod rm ${pod.id} discards it)`),
+    );
     return 0;
   }
   const wrapper = await readWrapperRecord(pod);
@@ -1414,6 +1586,107 @@ async function cancelCmd(
   return 0;
 }
 
+/** Undelivered entries a removal would delete with the workspace (ADR 0025, 0035). */
+async function pendingOutbox(pod: PodRecord): Promise<number> {
+  const dir = join(podDir(pod.project, pod.id), "outbox");
+  const names = await readdir(dir).catch(() => []);
+  // A `.dead` entry is already a verdict, not a message waiting to go out.
+  return names.filter((name) => !name.startsWith(".") && !name.endsWith(".dead")).length;
+}
+
+/**
+ * The record's end (ADR 0035): remove a Pod that no live wake-up owns — its
+ * record and its workspace, so the registry and the disk agree again. This is
+ * garbage collection, not a stop: `cancel` still owns every running process,
+ * and a live pod is refused here rather than deleted under its wrapper.
+ *
+ * Refusals are the references that would be left dangling: a bound Listener
+ * (its claims would wait forever), a dependent Pod (`after` could never be
+ * satisfied), and an undelivered Outbox entry (a message a wake-up already
+ * decided to send). A Listener claim's `spawnedPodId` is deliberately *not* a
+ * reference: it is intake's history, and a missing pod simply reads as not
+ * live (ADR 0034).
+ */
+async function removeCmd(
+  rest: string[],
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const unknown = rest.filter((word) => word.startsWith("--"));
+  if (unknown.length > 0) {
+    err(`Unknown rm argument: ${unknown[0]}. Usage: agents-pod rm <podId>`);
+    return 2;
+  }
+  const pod = await requirePod(rest[0], "rm", err);
+  if (!pod) return 2;
+
+  if (pod.state === "active" || pod.state === "spawning") {
+    err(`pod ${pod.id} is ${pod.state}: a live wake-up owns it — agents-pod cancel ${pod.id} first`);
+    return 2;
+  }
+
+  const bound = (await readListeners()).filter(
+    (listener) => listener.mode === "pod" && listener.podId === pod.id,
+  );
+  if (bound.length > 0) {
+    err(
+      `pod ${pod.id} is bound by ${bound.map((listener) => listener.id).join(", ")}: remove the listener first`,
+    );
+    return 2;
+  }
+
+  const dependents = (await readPods()).filter((candidate) => candidate.after === pod.id);
+  if (dependents.length > 0) {
+    err(
+      `pod ${pod.id} is the upstream of ${dependents.map((candidate) => candidate.id).join(", ")}: remove the dependent pod${dependents.length === 1 ? "" : "s"} first`,
+    );
+    return 2;
+  }
+
+  const waiting = await pendingOutbox(pod);
+  if (waiting > 0) {
+    const dir = join(podDir(pod.project, pod.id), "outbox");
+    err(
+      `pod ${pod.id} has ${waiting} undelivered outbox entr${waiting === 1 ? "y" : "ies"}: deliver or delete ${dir} first`,
+    );
+    return 2;
+  }
+
+  // The same CAS as every other transition (ADR 0018): the refusal checks above
+  // ran outside the lock, so the state and the references are re-read inside it
+  // and a wake, a spawn or a new dependent that landed meanwhile wins.
+  const removed = await withRegistryLock(async () => {
+    const current = await readPods();
+    const target = current.find((candidate) => candidate.id === pod.id);
+    if (!target || target.state === "active" || target.state === "spawning") return false;
+    if (current.some((candidate) => candidate.after === pod.id)) return false;
+    await writePods(current.filter((candidate) => candidate.id !== pod.id));
+    return true;
+  });
+  if (removed === undefined) {
+    err(`pod ${pod.id}: the registry is locked; nothing removed`);
+    return 1;
+  }
+  if (!removed) {
+    err(`pod ${pod.id} changed while removing it: nothing removed`);
+    return 2;
+  }
+
+  // The record goes first: it is what every read surface shows, and a crash
+  // between the two leaves an invisible directory, not a pod that looks alive.
+  const dir = podDir(pod.project, pod.id);
+  const line = `removed ${pod.id} (${pod.state}): ${goalHeadline(pod.goal)}`;
+  try {
+    await rm(dir, { recursive: true, force: true });
+  } catch (error) {
+    out(line);
+    err(`workspace ${dir} could not be deleted (${(error as Error).message}); remove it by hand`);
+    return 1;
+  }
+  out(line);
+  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`
@@ -1428,6 +1701,13 @@ export interface SpawnOptions {
   model?: string;
   after?: string;
   wakeBudgetPerDay?: number;
+  /**
+   * Write the record and launch nothing (#43, ADR 0033 amendment). A hybrid
+   * Pod's first firing belongs to the handover, not to the spawn that created
+   * it; the blocked path below already writes exactly this record, so dormancy
+   * is the absence of a launch rather than a state of its own.
+   */
+  dormant?: boolean;
 }
 
 async function spawnPodRecord(
@@ -1436,7 +1716,7 @@ async function spawnPodRecord(
   options: SpawnOptions,
   registryHeld = false,
 ): Promise<PodRecord> {
-  const { agentId, admission, model, after, wakeBudgetPerDay } = options;
+  const { agentId, admission, model, after, wakeBudgetPerDay, dormant } = options;
   const record: PodRecord = {
     id: newPodId(),
     goal,
@@ -1475,6 +1755,16 @@ async function spawnPodRecord(
       return record;
     }
 
+    // Dormant (#43): the record, the workspace and the owner exist; the first
+    // wake-up does not. Nothing in the store says "dormant" — zero wake-ups on
+    // an idle Pod is the fact, and a marker would have to be cleared by three
+    // launchers.
+    if (dormant === true) {
+      record.state = "idle";
+      await writePods(pods);
+      return record;
+    }
+
     record.admitted = "spawn";
     await writePods(pods);
     launchWrapperDetached(record.id, agentId);
@@ -1504,23 +1794,28 @@ async function spawnCmd(
     "admission",
     "wake-budget",
   ]);
-  // `--external` carries no value, so parseFlags leaves it among the words: it
-  // is the shorthand ADR 0030 documents for `--admission external`, and it is
-  // taken out before the remaining words compose the goal.
+  // `--external` and `--dormant` carry no value, so parseFlags leaves them among
+  // the words: the first is the shorthand ADR 0030 documents for `--admission
+  // external`, the second declares the Pod without its spawn wake-up (#43).
+  // Both are taken out before the remaining words compose the goal.
   const external = rest.includes("--external");
-  const goal = rest.filter((word) => word !== "--external").join(" ").trim();
+  const dormant = rest.includes("--dormant");
+  const goal = rest
+    .filter((word) => word !== "--external" && word !== "--dormant")
+    .join(" ")
+    .trim();
   if (dangling.length > 0) {
     // A flag with no value would otherwise compose the goal and leave its own
     // setting at the default — a typo that silently disables a guardrail is not
     // a guardrail (ADR 0032).
     err(`${dangling[0]} needs a value`);
     err("Usage: agents-pod spawn <goal prompt> [--agent <id>] [--model <id>] [--cwd <dir>] [--after <podId>]");
-    err("                            [--admission intake|external|self | --external] [--wake-budget <n>]");
+    err("                            [--admission intake|external|self | --external] [--wake-budget <n>] [--dormant]");
     return 2;
   }
   if (!goal) {
     err("Usage: agents-pod spawn <goal prompt> [--agent <id>] [--model <id>] [--cwd <dir>] [--after <podId>]");
-    err("                            [--admission intake|external|self | --external] [--wake-budget <n>]");
+    err("                            [--admission intake|external|self | --external] [--wake-budget <n>] [--dormant]");
     return 2;
   }
 
@@ -1557,6 +1852,17 @@ async function spawnCmd(
     return 2;
   }
   const admission: Admission = declared ?? "self";
+  // Dormancy is not an owner, it is the absence of a first launch — and the tick
+  // does not wait to launch. A `self` Pod is admitted on the very next pass, so
+  // `--dormant` there would promise a stop nothing honours (#43, ADR 0033
+  // amendment: refuse the flag where it cannot mean anything).
+  if (dormant && admission === "self") {
+    err("--dormant needs an owner that arrives later: a `self` pod is admitted by the tick on its next pass, so it would be dormant for a minute at most");
+    err("  --admission intake     a listener feeds it: the first batch is its first wake-up");
+    err("  --admission external   an outside clock or a human calls `agents-pod wake`");
+    err("or drop --dormant and let its spawn wake-up run now");
+    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
@@ -1588,6 +1894,7 @@ async function spawnCmd(
     ...(flags.model === undefined ? {} : { model: flags.model }),
     ...(flags.after === undefined ? {} : { after: flags.after }),
     ...(wakeBudgetPerDay === undefined ? {} : { wakeBudgetPerDay }),
+    ...(dormant ? { dormant: true } : {}),
   });
   out(record.id);
   return 0;
@@ -1964,6 +2271,8 @@ async function sourceCmd(
               cmd: source.cmd,
               timeoutMs: source.timeoutMs,
               cursor: source.cursor ?? null,
+              lastDrainItems: source.lastDrainItems ?? null,
+              unrouted: source.lastDrainUnrouted ?? null,
             })),
           ),
         );
@@ -1974,8 +2283,13 @@ async function sourceCmd(
         return 0;
       }
       for (const source of sources) {
+        // The unrouted count rides the line an operator already reads (ADR 0034):
+        // a drain that delivers into nothing is otherwise indistinguishable from a
+        // quiet chat, which is the state this number exists to separate.
+        const unrouted =
+          (source.lastDrainUnrouted ?? 0) === 0 ? "" : `  unrouted ${source.lastDrainUnrouted}`;
         out(
-          `${source.name}  ${source.cmd}  timeout ${source.timeoutMs / 1000}s  cursor ${source.cursor ?? "-"}`,
+          `${source.name}  ${source.cmd}  timeout ${source.timeoutMs / 1000}s  cursor ${source.cursor ?? "-"}${unrouted}`,
         );
       }
       return 0;
@@ -2051,8 +2365,40 @@ async function sourceCmd(
       return 0;
     }
 
+    case "rewind": {
+      // The one explicit way back past a cursor (ADR 0034): a batch an unrouted
+      // drain swallowed, or a route fixed after the fact. Claims dedupe on id, so
+      // a rewind re-serves exactly what was never claimed; `--to ""` clears the
+      // cursor and makes the adapter decide where to start again.
+      const { flags, rest: words } = parseFlags(rest, ["to"]);
+      const name = words.find((word) => !word.startsWith("--"));
+      if (name === undefined || flags.to === undefined) {
+        err('Usage: agents-pod source rewind <name> --to <cursor|"">');
+        return 2;
+      }
+      const rewound = await withRegistryLock(async () => {
+        const sources = await readSources();
+        const source = sources.find((candidate) => candidate.name === name);
+        if (source === undefined) return false;
+        if (flags.to === "") delete source.cursor;
+        else source.cursor = flags.to;
+        await writeSources(sources);
+        return true;
+      });
+      if (rewound === undefined) {
+        err("registry lock unavailable: cursor not rewound");
+        return 2;
+      }
+      if (!rewound) {
+        err(`Unknown source ${name}`);
+        return 2;
+      }
+      out(flags.to === "" ? `${name}  cursor cleared` : `${name}  cursor ${flags.to}`);
+      return 0;
+    }
+
     default:
-      err(`Unknown source command: ${sub ?? "(none)"}. Try: add | list | rm`);
+      err(`Unknown source command: ${sub ?? "(none)"}. Try: add | list | rm | rewind`);
       return 2;
   }
 }
@@ -2172,6 +2518,7 @@ async function listenerCmd(
               inbox: listener.inbox ?? null,
               source: listener.source ?? null,
               match: listener.match ?? null,
+              chats: listener.chats ?? null,
               mode: listener.mode,
               template: listener.template ?? null,
               project: listener.project ?? null,
@@ -2193,23 +2540,32 @@ async function listenerCmd(
             ? `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}`);
+        const filter =
+          listener.chats === undefined ? "" : `  chats ${listener.chats.join(",")}`;
+        out(
+          `${listener.id}  ${target}  ${origin}  claimed ${listener.claimed?.length ?? 0}${filter}`,
+        );
       }
       return 0;
     }
 
     case "add": {
-      const { flags } = parseFlags(rest, [
-        "inbox",
-        "source",
-        "template",
-        "pod",
-        "match",
-        "max-concurrent",
-        "project",
-      ]);
+      const { flags, multiFlags } = parseFlags(
+        rest,
+        [
+          "inbox",
+          "source",
+          "template",
+          "pod",
+          "match",
+          "chat",
+          "max-concurrent",
+          "project",
+        ],
+        ["chat"],
+      );
       const usage =
-        "Usage: agents-pod listener add (--inbox <dir|file> | --source <name>) (--template <file> | --pod <podId>) [--match <substr>] [--max-concurrent <n>] [--project <dir>]";
+        "Usage: agents-pod listener add (--inbox <dir|file> | --source <name>) (--template <file> | --pod <podId>) [--match <substr>] [--chat <chat_id> ...] [--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;
@@ -2250,6 +2606,18 @@ async function listenerCmd(
         return 2;
       }
 
+      // A filter reads the item's group, and a directory item has none, so a rule
+      // it could never satisfy is refused here rather than shipped (ADR 0034).
+      const chats = routingChats(multiFlags.chat);
+      if (chats !== undefined && inbox !== undefined) {
+        const info = await stat(inbox).catch(() => undefined);
+        if (info?.isDirectory()) {
+          err(`--chat filters on a group, and a directory item carries none: ${inbox}`);
+          err("      filter a Source, or a JSONL inbox whose items carry chat_id");
+          return 2;
+        }
+      }
+
       let maxConcurrent = 1;
       if (flags["max-concurrent"] !== undefined) {
         const parsed = Number(flags["max-concurrent"]);
@@ -2270,6 +2638,7 @@ async function listenerCmd(
         seen: [],
       };
       if (flags.match !== undefined) listener.match = flags.match;
+      if (chats !== undefined) listener.chats = chats;
 
       if (flags.template !== undefined) {
         // Read once to prove the reference, store the path (ADR 0007): the
@@ -2327,6 +2696,98 @@ async function listenerCmd(
       return 0;
     }
 
+    case "edit": {
+      // Claims live in the Listener record (ADR 0034), so re-creating one forgets
+      // the ids it served and the replay window hands them back as new work. The
+      // rule changes in place instead; the target and the claims do not move.
+      const clearChats = rest.includes("--no-chat");
+      const { flags, multiFlags, rest: words } = parseFlags(
+        rest.filter((word) => word !== "--no-chat"),
+        ["match", "chat", "max-concurrent", "project"],
+        ["chat"],
+      );
+      const id = words.find((word) => !word.startsWith("--"));
+      const usage =
+        "Usage: agents-pod listener edit <listenerId> [--match <substr>] [--chat <chat_id> ... | --no-chat] [--max-concurrent <n>] [--project <dir>]";
+      if (id === undefined) {
+        err(usage);
+        return 2;
+      }
+      if (
+        flags.match === undefined &&
+        multiFlags.chat === undefined &&
+        !clearChats &&
+        flags.project === undefined &&
+        flags["max-concurrent"] === undefined
+      ) {
+        err(`listener edit needs at least one rule. ${usage}`);
+        return 2;
+      }
+      const found = (await readListeners()).find((candidate) => candidate.id === id);
+      if (found === undefined) {
+        err(`Unknown listener ${id}`);
+        return 2;
+      }
+      const cwd = deps.cwd ?? process.cwd();
+      let targetProject: string | undefined;
+      if (flags.project !== undefined) {
+        if (found.mode !== "template") {
+          err(`--project needs a template listener: a bound standing Pod keeps its own project. ${usage}`);
+          return 2;
+        }
+        targetProject = resolve(cwd, flags.project);
+        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;
+        }
+      }
+      let maxConcurrent: number | undefined;
+      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 chats = clearChats ? [] : routingChats(multiFlags.chat);
+      if (chats !== undefined && chats.length > 0 && found.inbox !== undefined) {
+        const info = await stat(found.inbox).catch(() => undefined);
+        if (info?.isDirectory()) {
+          err(`--chat filters on a group, and a directory item carries none: ${found.inbox}`);
+          return 2;
+        }
+      }
+      const edited = await withRegistryLock(async () => {
+        const current = await readListeners();
+        const listener = current.find((candidate) => candidate.id === id);
+        if (listener === undefined) return false;
+        if (flags.match !== undefined) {
+          if (flags.match === "") delete listener.match;
+          else listener.match = flags.match;
+        }
+        if (chats !== undefined) {
+          if (chats.length === 0) delete listener.chats;
+          else listener.chats = chats;
+        }
+        if (targetProject !== undefined) listener.project = targetProject;
+        if (maxConcurrent !== undefined) listener.maxConcurrent = maxConcurrent;
+        await writeListeners(current);
+        return true;
+      });
+      if (edited === undefined) {
+        err("registry lock unavailable: listener not edited");
+        return 2;
+      }
+      if (!edited) {
+        err(`Unknown listener ${id}`);
+        return 2;
+      }
+      out(id);
+      return 0;
+    }
+
     case "rm": {
       const id = rest.find((word) => !word.startsWith("--"));
       if (!id) {
@@ -2371,7 +2832,7 @@ async function listenerCmd(
     }
 
     default:
-      err(`Unknown listener command: ${sub ?? "(none)"}. Try: add | list | rm`);
+      err(`Unknown listener command: ${sub ?? "(none)"}. Try: add | edit | list | rm`);
       return 2;
   }
 }
@@ -2435,7 +2896,7 @@ export async function main(argv: string[], deps: CliDeps = {}): Promise<number>
     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("pods        spawn | list [--all] | status <id> | logs <id> | wake <id> | cancel <id> | rm <id>");
     out("records     agent | listener | source | deliver | adapter | project | reconcile");
     return 0;
   }
@@ -2446,13 +2907,15 @@ export async function main(argv: string[], deps: CliDeps = {}): Promise<number>
     case "status":
       return statusCmd(rest, out, err);
     case "list":
-      return listCmd(out);
+      return listCmd(rest, out, err);
     case "logs":
       return logsCmd(rest, out, err);
     case "wake":
       return wakeCmd(rest, out, err);
     case "cancel":
       return cancelCmd(rest, out, err);
+    case "rm":
+      return removeCmd(rest, out, err);
     case "reconcile":
       return reconcileCmd(deps);
     case "agent":
@@ -2470,7 +2933,7 @@ export async function main(argv: string[], deps: CliDeps = {}): Promise<number>
     case "doctor":
       return doctorCmd(rest, deps, out, err);
     default:
-      err(`Unknown command: ${cmd ?? "(none)"}. Try: doctor | spawn | list | status | logs | wake | cancel | reconcile | agent | listener | source | deliver | project`);
+      err(`Unknown command: ${cmd ?? "(none)"}. Try: doctor | spawn | list | status | logs | wake | cancel | rm | reconcile | agent | listener | source | deliver | project`);
       return 2;
   }
 }