agents-pod 0.3.5 → 0.3.7

package/src/cli.ts

@@ -14,6 +14,14 @@ import {
 } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
+import {
+  ADMISSIONS,
+  admissionOf,
+  clockPhrase,
+  clockRefusal,
+  isAdmission,
+} from "./admission.ts";
+import { DAY_MS, duration, inWindow, medianIntervalMs, stamped } from "./cadence.ts";
 import {
   agentTypeRefusal,
   isAgentType,
@@ -32,6 +40,7 @@ import {
   newListenerId,
   readListeners,
   writeListeners,
+  type ClaimRecord,
   type ListenerRecord,
 } from "./listeners.ts";
 import { acquireLock, readLock, releaseLock, sleep } from "./locks.ts";
@@ -57,7 +66,13 @@ import {
   type AdapterFileState,
   type AdapterSyncPlan,
 } from "./adapters.ts";
-import type { PodRecord } from "./registry.ts";
+import {
+  DEFAULT_WAKE_BUDGET_PER_DAY,
+  type Admission,
+  type PodRecord,
+  type WakePolicy,
+  type WakeUpEntry,
+} from "./registry.ts";
 import { readPods, withRegistryLock, writePods } from "./registry.ts";
 import {
   commitSourceCursors,
@@ -97,28 +112,64 @@ function launchWrapperDetached(podId: string, agentId?: string, warm = false): v
 }
 
 /**
- * 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.
+ * Flags may appear anywhere among the words (README's CLI surface), and the
+ * words that are not flags compose the goal. Every flag in `allowed` takes a
+ * 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[] } {
+  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 };
+  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). */
@@ -126,6 +177,69 @@ function backoffMs(streak: number): number {
   return Math.min(60_000 * 2 ** (streak - 1), 900_000);
 }
 
+/**
+ * One outcome's effect on the record's policy (ADR 0031): the single place that
+ * decides when the *next* wake-up may happen, and the reason it takes the owner.
+ *
+ * **An outcome never schedules a wake-up its owner would not have made.** `more`
+ * means "the goal needs another wake-up"; for a Pod the tick owns that is "on the
+ * next pass", and for a Pod a Listener feeds or an outside clock wakes, the next
+ * wake-up is its owner's decision — a `nextWakeAt` written here would be a second,
+ * invisible owner, which is how a goal re-armed itself at 41 wake-ups in five
+ * hours (issue #31, #34). `cancelled` says nothing about the schedule: a human
+ * stopped a window, not the work.
+ *
+ * The failure streak is *not* owner-dependent: park obeys it, and park is about
+ * money, not about who wakes the Pod.
+ */
+function applyOutcome(
+  policy: WakePolicy,
+  owner: Admission,
+  wake: WakeUpEntry,
+  now: number,
+): void {
+  // `quiet` (ADR 0011 amendment, #36): the window is satisfied and nothing is
+  // scheduled. It is a clean exit — the streak resets, the batch it was admitted
+  // for was served — and the difference from `more` is that it asks for nothing:
+  // no clock, and the tick stops admitting the Pod until work arrives.
+  if (wake.outcome === "quiet") {
+    policy.failureStreak = 0;
+    delete policy.nextWakeAt;
+    delete policy.intakePending;
+    policy.awaiting = true;
+    return;
+  }
+  if (wake.outcome === "more" || wake.outcome === "done") {
+    policy.failureStreak = 0;
+    delete policy.nextWakeAt; // `self`: due on the next pass, at once
+    // A clean exit served the batch it was woken for, so the debt is paid
+    // (ADR 0026 amendment).
+    delete policy.intakePending;
+    // Another wake-up is the work again, so a previous "nothing scheduled" is
+    // spent: the Pod is wake-eligible by its owner's ordinary rule.
+    delete policy.awaiting;
+    return;
+  }
+  // Anything not named here is recorded and ignored, never counted as a failure:
+  // `cancelled` (a human stopped a window, not the work) and any outcome a later
+  // version adds must not park a Pod by falling through (ADR 0031 — #36's `quiet`
+  // is exactly such a value).
+  if (wake.outcome !== "failed" && wake.outcome !== "lost") return;
+  // Only the tick's own Pod is put on a clock; an intake Pod is re-admitted by
+  // the batch it still owes, and an `external` one by its own wake — both
+  // bounded by the streak and the park below, not by this field.
+  policy.failureStreak += 1;
+  // A window that ran and failed was not satisfied by its own account, so the
+  // "nothing scheduled" claim is spent too — the streak machinery decides from
+  // here, and a parked Pod is skipped before admission is even asked.
+  delete policy.awaiting;
+  if (owner === "self") {
+    policy.nextWakeAt = now + backoffMs(policy.failureStreak);
+  } else {
+    delete policy.nextWakeAt;
+  }
+}
+
 /**
  * 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
@@ -324,6 +438,18 @@ async function reconcilePass(
   const pods = await readPods();
   const agents = await readAgents();
   const now = Date.now();
+  // The owner is resolved per Pod below from the bindings as this pass begins.
+  // A `listener add` from another process can still land during the Pod loop,
+  // and the derivation would then read that Pod as the tick's — which is why the
+  // wake phase reads the bindings again (see wakeDuePods) and why `nextWakeAt`,
+  // the one field such a stale answer could write, gates nothing but a `self`
+  // Pod. A wrong answer here can delay nothing; a wrong answer there would wake
+  // a Pod that had just been bound.
+  const intakeBound = new Set(
+    (await readListeners()).flatMap((listener) =>
+      listener.mode === "pod" && listener.podId !== undefined ? [listener.podId] : [],
+    ),
+  );
   let changed = false;
   const pending: PodNotification[] = [];
 
@@ -348,7 +474,13 @@ async function reconcilePass(
       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.wakeUps.push({
+          n,
+          outcome: "lost",
+          detail: lostDetail(facts),
+          at: now,
+          ...(pod.admitted === undefined ? {} : { trigger: pod.admitted }),
+        });
         pod.state = "idle";
         delete pod.wedgedAt; // a lost wake-up spends any wedged observation
         changed = true;
@@ -390,6 +522,8 @@ async function reconcilePass(
             detail: trusted
               ? "wedged wrapper killed by reconcile"
               : "wedged wrapper signal withheld (recorded process is gone)",
+            at: now,
+            ...(pod.admitted === undefined ? {} : { trigger: pod.admitted }),
           });
           pod.state = "idle";
           delete pod.wedgedAt;
@@ -425,6 +559,8 @@ async function reconcilePass(
               n: wrapper.wakeup,
               outcome: "failed",
               detail: PROGRESSLESS_DETAIL,
+              at: now,
+              ...(pod.admitted === undefined ? {} : { trigger: pod.admitted }),
             });
             pod.state = "idle";
             changed = true;
@@ -438,28 +574,21 @@ async function reconcilePass(
     // two-event notification inventory (ADRs 0021, 0025).
 
     // 2. Policy derivation from outcome facts the wrapper (or step 1) recorded.
+    // The owner is resolved once here and handed to the derivation, so a new
+    // outcome cannot reach the schedule without answering "who wakes this Pod?"
+    // (ADR 0031).
+    const owner = admissionOf(pod, intakeBound);
     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;
-      }
-      // A clean exit served the batch it was woken for, so the debt is paid
-      // (ADR 0026 amendment). `failed` and `lost` leave it standing: the next
-      // admitted wake-up is the retry, and it is bounded by backoff and park
-      // exactly like any other failure. `cancelled` leaves it too — a human
-      // stopped a window, not the work.
-      if (wake.outcome === "more" || wake.outcome === "done") {
-        delete pod.policy.intakePending;
+      applyOutcome(pod.policy, owner, wake, now);
+      // 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, and
+      // it holds for every owner — a stop is about money, not about scheduling.
+      const failed = wake.outcome === "failed" || wake.outcome === "lost";
+      if (failed && pod.policy.failureStreak >= 3 && !pod.policy.parked) {
+        pod.policy.parked = true;
+        pod.policy.parkedBy = "failures";
+        announcePark();
       }
       pod.policy.appliedOutcomes += 1;
       changed = true;
@@ -467,6 +596,23 @@ async function reconcilePass(
 
     const goalOpen = pod.state !== "done" && pod.state !== "cancelled";
 
+    // 2b. The daily ceiling (ADR 0032). The one defence against a loop nobody
+    // predicted: the storm's own round 41 set `parked` by hand, and this is that
+    // manoeuvre promoted to machinery. Park is reused rather than invented, so
+    // exactly one notification is sent (ADR 0021) and only a human `wake`
+    // lifts it (ADR 0011).
+    const budget = pod.policy.wakeBudgetPerDay ?? DEFAULT_WAKE_BUDGET_PER_DAY;
+    const today = inWindow(pod.wakeUps, now, DAY_MS).length;
+    if (goalOpen && !pod.policy.parked && today > budget) {
+      pod.policy.parked = true;
+      // A budget stop is not the failure stop: `wake` lifts the latter freely
+      // (ADR 0011) but must not lift this one, or an outside clock re-opens the
+      // ceiling on every tick and every re-park announces itself (ADR 0032).
+      pod.policy.parkedBy = "budget";
+      announcePark(`${today} wake-ups in 24 h — over the budget of ${budget} (ADR 0032)`);
+      changed = true;
+    }
+
     // 3. Terminal observation (ADR 0021): done is announced once, however many
     // passes later find the record. The marker is what makes it once.
     if (
@@ -494,6 +640,7 @@ async function reconcilePass(
     if (!agentKnown && goalOpen && pod.state !== "active") {
       if (!pod.policy.parked) {
         pod.policy.parked = true;
+        pod.policy.parkedBy = "agent";
         announcePark(`agent "${agentId}" no longer resolves (ADR 0012)`);
         changed = true;
       }
@@ -528,6 +675,19 @@ async function reconcilePass(
  * inbox burned one whole agent run per tick — the shape that got the first
  * router pod cancelled. An unbound pod has no inbox to check, so ADR 0011's
  * optimistic rule stays its whole policy.
+ *
+ * ADR 0030 makes the owner a recorded fact with three values: `intake` (the debt
+ * gate below), `external` (never launched here — an outside clock or a human
+ * calls `wake`), `self` (the tick, for a goal that reaches `done`). A Listener
+ * binding outranks the record, because binding *is* an intake declaration, and
+ * an unrecorded owner falls back to `self` — the old rule, now named and
+ * reported by `doctor` rather than silently assumed.
+ *
+ * The bindings are read here, not handed down from the top of the pass: a
+ * `listener add` can land while a pass spawns pods, retries outboxes, and
+ * drains sources, and a set read seconds earlier would let this phase tick-wake
+ * a pod that had just been bound — the storm's own unit, reintroduced as a race.
+ * The derivation reads its own copy for the same reason, closest to its use.
  */
 async function wakeDuePods(now: number): Promise<void> {
   const pods = await readPods();
@@ -538,20 +698,47 @@ async function wakeDuePods(now: number): Promise<void> {
     ),
   );
   let changed = false;
+  const toLaunch: Array<{ id: string; agent: string }> = [];
+  const lines: string[] = [];
   for (const pod of pods) {
     if (pod.state !== "idle" || pod.policy?.parked) continue;
-    if (intakeBound.has(pod.id) && !pod.policy?.intakePending) continue;
-    if (pod.policy?.nextWakeAt !== undefined && pod.policy.nextWakeAt > now) continue;
+    // `quiet`: the window said it was satisfied and scheduled nothing (#36).
+    // No owner admits it until work arrives — a new intake batch or a human
+    // `wake`, both of which clear the flag.
+    if (pod.policy?.awaiting) continue;
+    // Admission first (ADR 0030): the tick is one owner among three, and it
+    // reads the owner from the record instead of inferring it. An `external`
+    // Pod is somebody else's to wake at every tick of every day.
+    const owner = admissionOf(pod, intakeBound);
+    if (owner === "external") continue;
+    if (owner === "intake" && !pod.policy?.intakePending) continue;
+    // A backoff is the tick's own delay, written only for its own Pod (ADR 0031):
+    // letting it gate an `intake` Pod would be a second owner again — a record
+    // that failed before it was bound, or one written before ADR 0031, would
+    // hold a batch back for up to fifteen minutes.
+    if (owner === "self" && 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.admitted = "tick";
     pod.state = "active";
+    toLaunch.push({ id: pod.id, agent: pod.policy?.agent ?? "default" });
+    lines.push(`wake ${pod.id} tick (admission ${owner})`);
     changed = true;
   }
+  // Record, then launch (ADR 0032). A crash between the two leaves a ghost the
+  // next pass adjudicates as `lost` — recoverable; a launch nobody recorded is
+  // the same Pod woken twice.
   if (changed) await writePods(pods);
+  for (const launch of toLaunch) launchWrapperDetached(launch.id, launch.agent);
+  // The storm left no trace a single command could read (issue #35): every
+  // launch now says which launcher it was, next to the sources and listeners
+  // that already write here (ADR 0032).
+  for (const line of lines) await appendCronLog(line);
 }
 
 /** One Pod's state as the registry holds it now, read without any lock (ADR 0025). */
@@ -566,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 }),
+  };
 }
 
 /**
@@ -587,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>>();
@@ -659,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
@@ -670,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;
@@ -687,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);
 
@@ -718,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(
@@ -736,12 +998,12 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
         materialized = true;
         continue;
       }
+      // A template Pod is spawned per Inbox Item and exists to finish it: the
+      // tick's own rule is its owner (ADR 0030), and `done` is its end.
       const record = await spawnPodRecord(
         rendered.goal,
         listener.project ?? project,
-        "default",
-        undefined,
-        undefined,
+        { agentId: "default", admission: "self" },
         true,
       );
       claim.spawnedPodId = record.id;
@@ -758,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,
     );
@@ -774,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(
@@ -812,6 +1074,9 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
     // leaves the count standing, so the next pass is the retry.
     pod.policy ??= { failureStreak: 0, appliedOutcomes: 0 };
     pod.policy.intakePending = (pod.policy.intakePending ?? 0) + batch.length;
+    // Work arrived, so a window that had declared itself satisfied is over
+    // (ADR 0011 amendment, #36) — the debt below is what admits the wake.
+    delete pod.policy.awaiting;
     await writePods(pods);
     appended = true;
   }
@@ -822,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(
@@ -845,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);
 }
 
@@ -934,33 +1210,125 @@ async function statusCmd(
   const last = pod.wakeUps.at(-1);
   out(pod.id);
   out(`  goal: ${goalHeadline(pod.goal)}`);
-  out(`  state: ${pod.state}`);
+  // Who admits this Pod (ADR 0030) — the fact that decides whether the tick
+  // 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
+        ? " (derived: no owner recorded)"
+        : pod.admission !== owner
+          ? ` (a listener is bound: intake wins over ${pod.admission})`
+          : ""
+    }`,
+  );
   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})`);
+    // Three stops, three sentences (ADR 0011, 0012, 0032): a park that reads
+    // "consecutive failures: 0" tells the operator nothing true.
+    const budget = pod.policy.wakeBudgetPerDay ?? DEFAULT_WAKE_BUDGET_PER_DAY;
+    const today = inWindow(pod.wakeUps, Date.now(), DAY_MS).length;
+    out(
+      pod.policy.parkedBy === "budget"
+        ? `  parked (over the daily budget: ${today} in 24h, budget ${budget}; agents-pod wake ${pod.id} --over-budget)`
+        : pod.policy.parkedBy === "agent"
+          ? `  parked (agent "${pod.policy.agent ?? "default"}" no longer resolves; agents-pod agent add ${pod.policy.agent ?? "default"} …)`
+          : `  parked (consecutive failures: ${pod.policy.failureStreak})`,
+    );
   }
   out(`  agent: ${resolveAgentBinary(process.env)}`);
   out(`  wake-ups: ${pod.wakeUps.length} (last outcome: ${last?.outcome ?? "none"})`);
+  out(`  cadence: ${cadenceLine(pod, Date.now())}`);
   return 0;
 }
 
+/**
+ * The cadence, in the words a storm is recognised by (ADR 0032): how many ran
+ * recently, how tight the rhythm was, and who admitted the last one. A record
+ * written before provenance existed says so instead of showing an invented zero.
+ */
+function cadenceLine(pod: PodRecord, now: number): string {
+  const timed = stamped(pod.wakeUps);
+  if (timed.length === 0) {
+    return "not recorded (this Pod's wake-ups predate provenance, ADR 0032)";
+  }
+  const day = inWindow(pod.wakeUps, now, DAY_MS).length;
+  const median = medianIntervalMs(pod.wakeUps);
+  const rhythm = median === undefined ? "interval n/a (fewer than two timed)" : `median interval ${duration(median)}`;
+  const trigger = pod.wakeUps.at(-1)?.trigger ?? "unknown";
+  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";
@@ -970,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;
 }
 
@@ -1045,11 +1416,13 @@ async function wakeCmd(
   err: (line: string) => void,
 ): Promise<number> {
   const { flags, rest } = parseFlags(words, ["agent"]);
-  // `--warm` carries no value, so parseFlags leaves it among the words.
+  // `--warm` and `--over-budget` carry no value, so parseFlags leaves them among
+  // the words.
   const warm = rest.includes("--warm");
+  const overBudget = rest.includes("--over-budget");
   const podId = rest.find((word) => !word.startsWith("--"));
   if (!podId) {
-    err("Usage: agents-pod wake <podId> [--agent <id>] [--warm]");
+    err("Usage: agents-pod wake <podId> [--agent <id>] [--warm] [--over-budget]");
     return 2;
   }
   const pods = await readPods();
@@ -1061,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") {
@@ -1068,6 +1442,21 @@ async function wakeCmd(
     return 0;
   }
 
+  // The human override lifts park and backoff (ADR 0011) — except the daily
+  // ceiling, which exists precisely because some launcher keeps firing. Lifting
+  // it silently made a cron-driven Pod re-park and re-announce on every pass;
+  // one more window is still available, but it has to be asked for (ADR 0032).
+  if (pod.policy?.parked && pod.policy.parkedBy === "budget" && !overBudget) {
+    const budget = pod.policy.wakeBudgetPerDay ?? DEFAULT_WAKE_BUDGET_PER_DAY;
+    const today = inWindow(pod.wakeUps, Date.now(), DAY_MS).length;
+    err(
+      `Pod ${pod.id} is parked over its daily budget (${today} wake-ups in 24 h, budget ${budget})`,
+    );
+    err(`      one more window, deliberately: agents-pod wake ${pod.id} --over-budget`);
+    err("      or spawn the work again with a ceiling that fits: --wake-budget <n>");
+    return 2;
+  }
+
   // 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);
@@ -1129,13 +1518,18 @@ async function wakeCmd(
       if (target.policy) {
         target.policy.failureStreak = 0;
         delete target.policy.nextWakeAt;
+        // A human wake is the other answer to "wake me when work arrives" (#36).
+        delete target.policy.awaiting;
         delete target.policy.parked;
+        delete target.policy.parkedBy;
       }
       delete target.notifiedAt;
     }
-    launchWrapperDetached(target.id, agentId, warm);
+    target.admitted = "wake";
     target.state = "active";
     await writePods(current);
+    // Recorded first, launched second (ADR 0032): see wakeDuePods.
+    launchWrapperDetached(target.id, agentId, warm);
     return true;
   });
   if (!woke) {
@@ -1161,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);
@@ -1187,33 +1586,154 @@ 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`
  * and a listener's template materialization both walk it (ADR 0007).
+ *
+ * The owner is written into the record here (ADR 0030), always: a Pod whose
+ * owner nobody declared is a Pod the tick will guess about.
  */
+export interface SpawnOptions {
+  agentId: string;
+  admission: Admission;
+  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(
   goal: string,
   project: string,
-  agentId: string,
-  model?: string,
-  after?: string,
+  options: SpawnOptions,
   registryHeld = false,
 ): Promise<PodRecord> {
+  const { agentId, admission, model, after, wakeBudgetPerDay, dormant } = options;
   const record: PodRecord = {
     id: newPodId(),
     goal,
     state: "spawning",
     project: resolve(project),
+    admission,
     ...(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).
+    // the definition's model, which beats the adapter default (ADR 0012). The
+    // daily ceiling rides here too (ADR 0032).
     policy: {
       failureStreak: 0,
       appliedOutcomes: 0,
       agent: agentId,
       ...(model === undefined ? {} : { model }),
+      ...(wakeBudgetPerDay === undefined ? {} : { wakeBudgetPerDay }),
     },
   };
   await createPodWorkspace(record);
@@ -1235,6 +1755,17 @@ 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);
     record.state = "active";
@@ -1254,10 +1785,82 @@ async function spawnCmd(
   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();
+  const { flags, rest, dangling } = parseFlags(words, [
+    "agent",
+    "model",
+    "cwd",
+    "project",
+    "after",
+    "admission",
+    "wake-budget",
+  ]);
+  // `--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 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>] [--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>] [--dormant]");
+    return 2;
+  }
+
+  // The daily ceiling is a guardrail, so its value is validated like any other
+  // surface flag: a typo must not silently disable it (ADR 0032).
+  let wakeBudgetPerDay: number | undefined;
+  if (flags["wake-budget"] !== undefined) {
+    const parsed = Number(flags["wake-budget"]);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+      err(`--wake-budget must be a positive integer, got ${flags["wake-budget"]}`);
+      return 2;
+    }
+    wakeBudgetPerDay = parsed;
+  }
+
+  // Admission is decided before anything is written (ADR 0030): who may wake
+  // this Pod is the fact the incident was missing, and a refused spawn leaves
+  // no record, no workspace, and no wake-up behind.
+  if (flags.admission !== undefined && !isAdmission(flags.admission)) {
+    err(`Unknown admission ${flags.admission}: one of ${ADMISSIONS.join(" | ")}`);
+    return 2;
+  }
+  if (external && flags.admission !== undefined && flags.admission !== "external") {
+    err(`--external means --admission external; not ${flags.admission}`);
+    return 2;
+  }
+  const declared: Admission | undefined = flags.admission ?? (external ? "external" : undefined);
+  // A goal that names a clock under the tick's own rule is the incident: every
+  // `more` re-arms it, so the clock fires as fast as the passes do. The clock
+  // belongs to a schedule; an `external` or `intake` owner makes it context.
+  const clock = clockPhrase(goal);
+  if (clock !== undefined && declared !== "external" && declared !== "intake") {
+    for (const line of clockRefusal(clock)) err(line);
+    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;
   }
 
@@ -1285,13 +1888,14 @@ async function spawnCmd(
     }
   }
 
-  const record = await spawnPodRecord(
-    goal,
-    flags.project ?? flags.cwd ?? deps.cwd ?? process.cwd(),
+  const record = await spawnPodRecord(goal, flags.project ?? flags.cwd ?? deps.cwd ?? process.cwd(), {
     agentId,
-    flags.model,
-    flags.after,
-  );
+    admission,
+    ...(flags.model === undefined ? {} : { model: flags.model }),
+    ...(flags.after === undefined ? {} : { after: flags.after }),
+    ...(wakeBudgetPerDay === undefined ? {} : { wakeBudgetPerDay }),
+    ...(dormant ? { dormant: true } : {}),
+  });
   out(record.id);
   return 0;
 }
@@ -1667,6 +2271,8 @@ async function sourceCmd(
               cmd: source.cmd,
               timeoutMs: source.timeoutMs,
               cursor: source.cursor ?? null,
+              lastDrainItems: source.lastDrainItems ?? null,
+              unrouted: source.lastDrainUnrouted ?? null,
             })),
           ),
         );
@@ -1677,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;
@@ -1754,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;
   }
 }
@@ -1875,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,
@@ -1896,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;
@@ -1953,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"]);
@@ -1973,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
@@ -1989,6 +2655,19 @@ async function listenerCmd(
           err(`Unknown pod ${flags.pod}`);
           return 2;
         }
+        // Binding is an intake declaration (ADR 0030): a Pod recorded as
+        // `external` is woken from outside, so binding it would silently drop
+        // that owner — and a Pod that owes a batch *and* an outside clock has
+        // two owners, which is zero owners when both fire.
+        if (pod.admission === "external") {
+          err(
+            `Pod ${pod.id} is admitted from outside (--admission external): a listener cannot bind it`,
+          );
+          err(
+            "      bind a Pod spawned with --admission intake, or spawn a new one for this inbox",
+          );
+          return 2;
+        }
         listener.mode = "pod";
         listener.podId = pod.id;
       }
@@ -2017,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) {
@@ -2025,10 +2796,28 @@ async function listenerCmd(
       }
       const removed = await withRegistryLock(async () => {
         const listeners = await readListeners();
+        const gone = listeners.find((listener) => listener.id === id);
         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);
+        // A `quiet` window's promise is made to a Listener ("wake me when work
+        // arrives"), so removing that Listener removes the claimant: the Pod
+        // falls back to the tick, which would otherwise skip it forever and say
+        // nothing (ADR 0011 amendment, #36).
+        const stillBound = new Set(
+          remaining.flatMap((listener) =>
+            listener.mode === "pod" && listener.podId !== undefined ? [listener.podId] : [],
+          ),
+        );
+        if (gone?.mode === "pod" && gone.podId !== undefined && !stillBound.has(gone.podId)) {
+          const pods = await readPods();
+          const pod = pods.find((candidate) => candidate.id === gone.podId);
+          if (pod?.policy?.awaiting) {
+            delete pod.policy.awaiting;
+            await writePods(pods);
+          }
+        }
         return true;
       });
       if (removed === undefined) {
@@ -2043,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;
   }
 }
@@ -2107,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;
   }
@@ -2118,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":
@@ -2142,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;
   }
 }