agents-pod 0.3.5 → 0.3.7

package/src/doctor.ts

@@ -14,7 +14,9 @@ import {
   reconcileLockPath,
   storeRoot,
 } from "./paths.ts";
-import { readPods, type PodRecord } from "./registry.ts";
+import { admissionOf, clockPhrase, openEnded } from "./admission.ts";
+import { HOUR_MS, duration, inWindow, medianIntervalMs } from "./cadence.ts";
+import { readPods, type Admission, type PodRecord } from "./registry.ts";
 import { readSources, type SourceRecord } from "./sources.ts";
 
 /**
@@ -63,6 +65,8 @@ const PROBE_OUTPUT_CAP = 8 * 1024;
 const PROBE_LINES = 6;
 /** A pass lock older than this is what the next pass steals (ADR 0018). */
 const LOCK_STALE_MS = 5 * 60_000;
+/** A Pod above this many wake-ups in an hour is worth a line (ADR 0032). */
+const WAKE_RATE_CEILING_PER_HOUR = 6;
 
 export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport> {
   const now = options.now ?? Date.now();
@@ -77,13 +81,24 @@ export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport>
   const notify = await loadNotifyConfig(undefined, (message) => warnings.push(message));
   const lastPass = await readLastPass();
 
+  // The first run is where a defaulted owner is most likely (nothing else is
+  // configured yet), so admission is reported before the recipe can swallow it.
+  const sections: DoctorSection[] = [];
+  if (registry.error === undefined && registry.pods.length > 0) {
+    sections.push({ title: "wake", lines: wakeLines(registry.pods, listeners, now) });
+  }
+
   const firstRun =
     sources.length === 0 && deliverer === undefined && notify.channels.length === 0;
   if (firstRun) {
-    return { store: root, sections: [], recipe: recipeFor(sources, listeners, deliverer, notify, lastPass), healthy: false };
+    return {
+      store: root,
+      sections,
+      recipe: recipeFor(sources, listeners, deliverer, notify, lastPass),
+      healthy: false,
+    };
   }
 
-  const sections: DoctorSection[] = [];
   const storeLines: DoctorLine[] = [];
   if (registry.error !== undefined) {
     storeLines.push({ mark: "bad", text: `pods.json is unreadable: ${registry.error}` });
@@ -204,6 +219,120 @@ async function passLines(
   return [{ mark: "ok", text: `last pass ${age(now - lastPass)} ago` }];
 }
 
+/**
+ * Admission, and the two shapes that cost money (ADR 0030, issue #31): a Pod on
+ * the tick whose goal names a clock is re-armed after every `more`, and a Pod on
+ * the tick whose goal is open-ended is woken with nothing new to work on. Both
+ * are legal records and broken intent, so they are named here rather than
+ * rewritten: the fix is an owner, and only the operator knows which one.
+ */
+function wakeLines(pods: PodRecord[], listeners: ListenerRecord[], now: number): DoctorLine[] {
+  const bound = new Set(
+    listeners.flatMap((listener) =>
+      listener.mode === "pod" && listener.podId !== undefined ? [listener.podId] : [],
+    ),
+  );
+  const counts: Record<Admission, number> = { intake: 0, external: 0, self: 0 };
+  const findings: DoctorLine[] = [];
+  for (const pod of pods) {
+    if (pod.state === "done" || pod.state === "cancelled") continue;
+    const owner = admissionOf(pod, bound);
+    counts[owner] += 1;
+    // The mirror of `external` (ADR 0030): a Pod owned by intake with no
+    // Listener bound to it can never be given work — nothing writes the debt.
+    if (owner === "intake" && !bound.has(pod.id)) {
+      findings.push({
+        mark: "bad",
+        text: `pod ${pod.id}: admission intake but no listener is bound to it — nothing will ever give it work`,
+        detail: [`next: agents-pod listener add --inbox <dir> --pod ${pod.id}`],
+      });
+      continue;
+    }
+    if (owner !== "self") continue;
+    // A Pod that declared itself satisfied and scheduled nothing is not a Pod
+    // the tick loops on (ADR 0011 amendment, #36): `awaiting` is the honest
+    // shape of a standing goal, and naming it as a problem would teach exactly
+    // the wrong lesson. But a satisfied Pod with nothing that can deliver work
+    // has stopped for good — "wake me when work arrives" with no arrival path
+    // is the one silence this report exists to break.
+    if (pod.policy?.awaiting) {
+      if (!bound.has(pod.id)) {
+        findings.push({
+          mark: "note",
+          text: `pod ${pod.id}: awaiting — its last window was satisfied and nothing can deliver work to it`,
+          detail: [
+            `      bind an inbox: agents-pod listener add --inbox <dir> --pod ${pod.id}`,
+            `      or wake it by hand: agents-pod wake ${pod.id}`,
+          ],
+        });
+      }
+      continue;
+    }
+    const clock = clockPhrase(pod.goal);
+    if (clock !== undefined) {
+      findings.push({
+        mark: "bad",
+        text: `pod ${pod.id}: its goal names a clock ("${clock}") and the tick admits it — every handoff re-arms it at the speed of the passes`,
+        detail: [
+          `next: spawn the work again with --admission external (an outside clock calls \`agents-pod wake\`)`,
+          "      or move the clock to schedule_task and let the schedule hand the work over",
+        ],
+      });
+      continue;
+    }
+    if (openEnded(pod.goal)) {
+      findings.push({
+        mark: "bad",
+        text: `pod ${pod.id}: admission self with an open-ended goal — the tick admits it after every handoff, with nothing new to work on`,
+        detail: [
+          `      if a listener feeds it: agents-pod listener add --inbox <dir> --pod ${pod.id}`,
+          "      if an outside clock wakes it: a Pod spawned with --admission external (ADR 0030)",
+        ],
+      });
+    }
+  }
+  // The rate line (ADR 0032): a Pod the tick re-arms shows up as a rhythm, not
+  // as a single failure, and the storm was 41 wake-ups in five hours with no
+  // line anywhere that said so.
+  for (const pod of pods) {
+    if (pod.state === "done" || pod.state === "cancelled") continue;
+    const hour = inWindow(pod.wakeUps, now, HOUR_MS).length;
+    if (hour <= WAKE_RATE_CEILING_PER_HOUR) continue;
+    const median = medianIntervalMs(pod.wakeUps);
+    const rhythm = median === undefined ? "" : `, median interval ${duration(median)}`;
+    const clock = clockPhrase(pod.goal);
+    const owner = admissionOf(pod, bound);
+    findings.push({
+      mark: "note",
+      text: `pod ${pod.id}: ${hour} wake-ups in the last hour${rhythm} — above the ${WAKE_RATE_CEILING_PER_HOUR}/h ceiling`,
+      detail:
+        clock === undefined
+          ? [
+              `      the goal names no clock: check who admits it (agents-pod status ${pod.id})`,
+              "      and its daily budget (agents-pod spawn --wake-budget, ADR 0032)",
+            ]
+          : owner === "self"
+            ? [
+                `      its goal names a clock ("${clock}") and the tick admits it — that is the #31 shape`,
+                "      next: agents-pod spawn … --admission external, or move the clock to schedule_task",
+              ]
+            : [
+                `      its goal names a clock ("${clock}") and ${owner} admits it — the rhythm is that clock's`,
+                `      next: check the schedule that calls agents-pod wake ${pod.id}`,
+              ],
+    });
+  }
+
+  const census = `${counts.intake} intake, ${counts.external} external, ${counts.self} self`;
+  return [
+    {
+      mark: findings.length > 0 ? "note" : "ok",
+      text: `admission by owner: ${census}`,
+    },
+    ...findings,
+  ];
+}
+
 async function intakeLines(
   sources: SourceRecord[],
   listeners: ListenerRecord[],
@@ -268,6 +397,19 @@ async function intakeLines(
     }
     lines.push({ mark: "ok", text: `source ${source.name}: ${source.cmd}` });
     lines.push({ mark: "ok", text: `  ${drained}, ${cursor}` });
+    // Routing leaves items behind on purpose (ADR 0034), so the count is a
+    // question and not a failure: a group nobody listens to is legitimate, a
+    // group nobody wanted is what the operator has to see.
+    if ((source.lastDrainUnrouted ?? 0) > 0) {
+      lines.push({
+        mark: "note",
+        text: `source ${source.name}: ${source.lastDrainUnrouted} item(s) of the last drain matched no listener — unrouted`,
+        detail: [
+          `      the cursor passed them; a route added now applies to what arrives next`,
+          `next: agents-pod listener add --source ${source.name} --chat <chat_id> --template <file> [--project <dir>]`,
+        ],
+      });
+    }
   }
   if (sources.length === 0) {
     lines.push({

package/src/extension/handoff.ts

@@ -1,13 +1,18 @@
 /**
  * The Handoff document, rendered once and written once (ADR 0008, 0010).
  *
- * The only machine surface is the first line — `status: rotating` or
- * `status: done` — because outcome classification greps it and the wrapper's
- * `freshDeclaration()` refuses anything else. Everything after it is free
+ * The only machine surface is the first line — `status: rotating`, `status:
+ * quiet`, or `status: done` — because outcome classification greps it and the
+ * wrapper's `freshDeclaration()` refuses anything else. Everything after it is free
  * markdown for the successor, so the sections are the ones CONTEXT.md names:
  * goal restated, decisions and reasons, done, next, pointers.
  */
-export type HandoffStatus = "rotating" | "done";
+/**
+ * `rotating` — the goal is open and the next wake-up is the work; `quiet` — the
+ * window is satisfied, nothing is scheduled, wake me when work arrives (#36);
+ * `done` — the goal is reached and the Pod ends.
+ */
+export type HandoffStatus = "rotating" | "quiet" | "done";
 
 export interface HandoffInput {
   status: HandoffStatus;
@@ -44,12 +49,18 @@ export function renderHandoff(input: HandoffInput, now: Date = new Date()): stri
   lines.push(...section("## Decisions and reasons", input.decisions));
   lines.push(...section("## Done", input.done));
   // Next is the one section a successor cannot live without, so it is always
-  // present — an empty one says so instead of disappearing.
+  // present — an empty one says so instead of disappearing, and the two legal
+  // "nothing to do" answers say why they are empty, because the difference
+  // between them is the difference between an ended goal and a waiting one.
   lines.push(
     ...section(
       "## Next",
       input.next,
-      input.status === "done" ? "(nothing — the goal is reached)" : "(unstated)",
+      input.status === "done"
+        ? "(nothing — the goal is reached)"
+        : input.status === "quiet"
+          ? "(nothing scheduled — the next window starts when work arrives)"
+          : "(unstated)",
     ),
   );
   lines.push(...section("## Pointers", input.pointers));

package/src/extension/management.ts

@@ -49,6 +49,7 @@ const POD_HELP = [
   "/pod spawn <goal…>       spawn a pod in this project",
   "/pod wake <podId>        wake an idle pod now",
   "/pod cancel <podId>      cancel a live wake-up",
+  "/pod rm <podId>          discard a pod that no wake-up owns, with its workspace",
   "/pod agents              named agents",
   "/pod listeners           listeners and their claims",
 ].join("\n");
@@ -67,7 +68,7 @@ export function registerManagementCommands(pi: ExtensionAPI): void {
         ctx.ui.notify(POD_HELP, "info");
         return;
       }
-      const needsPodId = ["status", "logs", "wake", "cancel", "spawn"].includes(action);
+      const needsPodId = ["status", "logs", "wake", "cancel", "rm", "spawn"].includes(action);
       if (needsPodId && rest.length === 0) {
         ctx.ui.notify(POD_HELP, "info");
         return;
@@ -93,17 +94,26 @@ export function registerManagementCommands(pi: ExtensionAPI): void {
  * pod, and the guardrails that make fan-out safe — the per-project cap and the
  * `--after` dependency — are the same ones the CLI enforces, because it is the
  * CLI doing the enforcing.
+ *
+ * The model-facing text is also where a hybrid ask is decomposed (ADR 0033):
+ * trigger × work give three shapes, the middle one is a schedule that hands over
+ * to a pod, and the rewrite is stated in one line — naming both units and the
+ * admission owner — before the first tool call, because the tie-break it
+ * replaces is what put a clock inside a pod's goal (issue #31).
  */
 export function registerManagementTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "spawn_pod",
     label: "Spawn Pod",
     description:
-      "Spawn a pod: a standing unit that outlives this session and wakes fresh agents inside it, one context window per wake-up, for as long as its goal stays open. A pod does not finish on its own — cancel it, or retire the goal, to end it: a router, a watcher, an inbox server, a multi-day refactor are all one pod. A pod is fed from a chat or an inbox (a source, e.g. feishu, plus a listener bound to it), sleeps between batches, and routes work to other pods by writing inbox items — a pod never spawns pods. A pod has NO CLOCK: it never runs at 9:00 or every 30 minutes, it wakes when it has work. Returns the pod id.",
+      "Spawn a pod: a standing unit that outlives this session and wakes fresh agents inside it, one context window per wake-up, for as long as its goal stays open. A pod does not finish on its own — cancel it, or retire the goal, to end it: a router, a watcher, an inbox server, a multi-day refactor are all one pod. A pod is fed from a chat or an inbox (a source, e.g. feishu, plus a listener bound to it), sleeps between batches, and routes work to other pods by writing inbox items — a pod never spawns pods. A pod has NO CLOCK: a time rule belongs to schedule_task (agents-cron), so an ask that has both a clock and memory across firings is a schedule that hands the work over to a pod, never a pod that reads the clock. Returns the pod id.",
     promptSnippet: "Spawn a standing pod for work that outlives this session",
     promptGuidelines: [
-      "Decide by the signal. A TIME rule — 每天, 每小时, 每 30 分钟, 到点, 明天提醒我 — is a schedule: use schedule_task / agents-cron, which owns when work starts. A MESSAGE or a ROLE that must stay alive — 常驻, 一直跑, 监听, 收消息, 路由, 服务某个 inbox, 直到我说停, one job spanning days — is a pod: call spawn_pod as your FIRST tool call, without surveying the repo or the plugin first.",
-      "Never put a clock in a pod's goal. If the ask needs 09:00, the schedule owns the time and a pod owns the work it hands over; a pod is woken by intake, never by the clock.",
+      "Read two axes before you call anything, because one ask can carry both signals, and a trigger alone does not decide — `time` without memory is a schedule (agents-cron / `schedule_task`), `message` or `role alive` is a pod (`spawn_pod`), and only the work axis separates the hybrid. trigger: `time` — 每天, 每小时, 每 30 分钟, 到点, 明天提醒我, 09:00; `message` — 收消息, 服务某个 inbox, 有活就干; `role alive` — 常驻, 监听, 路由, 直到我说停, or one job that spans days. work: `stateless` — one firing produces one answer and keeps nothing; `memory` — it needs what an earlier firing learned (跨天对比, 累计, 记得上次, 一份持续更新的报告).",
+      "Three shapes fall out of those two axes, and there is no fourth. (1) time + stateless → `schedule_task` alone: agents-cron owns the clock and the work, and a pod here is the incident. (2) time + memory → `schedule_task` owns the clock and hands the work over, `spawn_pod` owns it: bind the pod to the inbox the task appends to (`agents-pod listener add --inbox <file> --pod <podId>`) and give it `admission: intake`, or — when no batch has to be queued — let the task call `agents-pod wake <podId>` with `admission: external`. Spawn it with `dormant: true`: the record exists and nothing runs, so the clock owns every firing including the first, and the handover's first batch or `wake` is wake-up 1. Never a pod alone, never `self`, and never a spawn wake-up the clock did not order. (3) message / role alive → one pod via `spawn_pod`, `intake` when a listener or an inbox feeds it and `self` only when the goal reaches done, with no clock anywhere in its goal — call it as your FIRST tool call, without surveying the repo or the plugin first.",
+      "Say the rewrite in one line before the first tool call, naming every unit the ask actually has — and, whenever a pod is involved, its admission owner: 「这句我拆成：09:00 由 schedule_task 写 ci-daily.jsonl → pod X 被 intake 唤醒；pod X 负责汇总与跨天对比」. A schedule-only ask names no pod. If your line comes out as a pod plus a hand-written `crontab wake`, as a clock inside the pod's goal, or as a pod on `self`, that is the illegal combination (#31): say so and fix the shape instead of proceeding.",
+      "Never put a clock in a pod's goal: the phrases the guard recognises — 09:00, 每天, 每 30 分钟, 9 点, every 30 minutes, daily, 到点 — are refused at spawn when the pod's owner is the tick, and a pod re-armed on every pass is the storm. The clock belongs to the schedule; a pod is woken by its admission owner — a listener's batch, an outside wake, or the tick — never by a time rule written inside the goal.",
+      "Say who admits the pod's wake-ups (`admission`), because the tick is only one of three owners and it is the wrong one for a standing pod: `intake` when a listener or inbox feeds it (the router/watcher/inbox-server shape), `external` when an outside clock or a human wakes it with `agents-pod wake`, `self` only for a bounded goal the tick may re-wake until done. Left unstated it defaults to `self`, which wakes a standing pod every tick — the incident #31 exists to prevent.",
       "A pod is the right shape for a role, not only for a big job: a router that judges incoming messages, a watcher, an inbox server.",
       "A pod's agents share documents, not this conversation: put everything the successor must know into the goal text.",
       "spawn_pod returns a pod id; report that id back to the user so they can run /pod status on it. The pod owns the work from there — do not start doing its work in this session.",
@@ -122,6 +132,18 @@ export function registerManagementTools(pi: ExtensionAPI): void {
       cwd: Type.Optional(
         Type.String({ description: "Working directory for wake-ups, relative to this project." }),
       ),
+      admission: Type.Optional(
+        Type.Union([Type.Literal("intake"), Type.Literal("external"), Type.Literal("self")], {
+          description:
+            "Who admits this pod's wake-ups (ADR 0030): `intake` — a listener feeds it (the standing/inbox shape); `external` — an outside clock or a human calls `agents-pod wake`; `self` — the tick, legal only for a bounded goal that reaches done. Default is `self`; a standing pod left there is woken on every tick.",
+        }),
+      ),
+      dormant: Type.Optional(
+        Type.Boolean({
+          description:
+            "Write the pod and launch nothing, so its first wake-up belongs to its owner (ADR 0033 amendment, #43). Required for the hybrid shape: a schedule owns every firing including the first one. Needs `admission: intake` or `external` — with `self` the tick would wake it on its next pass, so the flag is refused there.",
+        }),
+      ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) {
       const argv = ["spawn", params.goal, "--project", ctx.cwd];
@@ -129,6 +151,8 @@ export function registerManagementTools(pi: ExtensionAPI): void {
       if (params.model !== undefined) argv.push("--model", params.model);
       if (params.after !== undefined) argv.push("--after", params.after);
       if (params.cwd !== undefined) argv.push("--cwd", params.cwd);
+      if (params.admission !== undefined) argv.push("--admission", params.admission);
+      if (params.dormant === true) argv.push("--dormant");
 
       const outcome = await runCli(argv, ctx.cwd);
       const podId = outcome.lines.join("\n").trim();
@@ -141,10 +165,13 @@ export function registerManagementTools(pi: ExtensionAPI): void {
         content: [
           {
             type: "text" as const,
-            text: `Spawned pod ${podId}. Wake-ups run detached; /pod status ${podId} shows progress.`,
+            text:
+              params.dormant === true
+                ? `Spawned pod ${podId} dormant: the record exists and no wake-up has run, so its first window belongs to its owner. The first handover starts it — an inbox item for \`intake\`, or \`agents-pod wake ${podId}\` for \`external\`. /pod status ${podId} shows it as "dormant: no wake-up yet".`
+                : `Spawned pod ${podId}. Wake-ups run detached; /pod status ${podId} shows progress.`,
           },
         ],
-        details: { podId },
+        details: { podId, ...(params.dormant === true ? { dormant: true } : {}) },
       };
     },
   });

package/src/extension/self.ts

@@ -10,9 +10,9 @@ import { renderHandoff, type HandoffStatus } from "./handoff.ts";
 export const DOCS_DIR_ENV = "AGENTS_POD_DOCS_DIR";
 
 const handoffSchema = Type.Object({
-  status: StringEnum(["rotating", "done"] as const, {
+  status: StringEnum(["rotating", "quiet", "done"] as const, {
     description:
-      "rotating: the goal is open, a successor continues. done: the goal is reached and the pod ends.",
+      "rotating: the goal is open and the next wake-up is the work. quiet: this window is satisfied, nothing is scheduled — wake me when work arrives (the honest ending for a standing goal). done: the goal is reached and the pod ends.",
   }),
   goal: Type.Optional(Type.String({ description: "The goal as this wake-up understood it." })),
   decisions: Type.Optional(
@@ -47,7 +47,7 @@ export function registerSelf(pi: ExtensionAPI): void {
     promptSnippet: "Write the pod handoff and end this wake-up",
     promptGuidelines: [
       "Call pod_handoff as the last action of a wake-up, after the work is recorded in the documents.",
-      "Use pod_handoff with status done only when the pod's goal is reached; rotating means the goal is open and the next wake-up continues from the handoff.",
+      "Use pod_handoff with status done only when the pod's goal is reached; rotating means the goal is open and the next wake-up continues from the handoff; quiet means this window is satisfied and nothing is scheduled — the honest ending for a standing goal, which must not say rotating to stay alive.",
       "An exit without a fresh pod_handoff is classified as failed — pod_handoff is the clean exit, not a summary you may skip.",
     ],
     parameters: handoffSchema,
@@ -59,9 +59,12 @@ export function registerSelf(pi: ExtensionAPI): void {
         throw new Error(`pod_handoff requires ${DOCS_DIR_ENV}: this session is not a pod wake-up`);
       }
       const file = join(docsDir, "HANDOFF.md");
-      // The schema admits exactly these two words; narrowing here keeps the
+      // The schema admits exactly these three words; narrowing here keeps the
       // hard line legal even if a provider reorders the enum.
-      const status: HandoffStatus = params.status === "done" ? "done" : "rotating";
+      const status: HandoffStatus =
+        params.status === "done" || params.status === "quiet"
+          ? (params.status as HandoffStatus)
+          : "rotating";
       const body = renderHandoff({ ...params, status });
       // The agent may be editing HANDOFF.md in the same turn: one queue per file.
       await withFileMutationQueue(file, () => writeFile(file, body));

package/src/listeners.ts

@@ -17,13 +17,19 @@ export type ListenerMode = "template" | "pod";
  * `blocked` is a reason materialization will not happen
  * (a configuration error, or an item that vanished). `appended` is ADR 0014's
  * one boolean for a bound standing pod: the block is in the pod's `## Inbox`.
- * Beyond that the document is the truth — there is no per-item lifecycle.
+ * The item copy lets a Source claim outlive the drain that produced it (ADR
+ * 0034). Beyond that the document is the truth — there is no per-item lifecycle.
  */
 export interface ClaimRecord {
   inbox: string;
   item: string;
-  /** Source claims retain the current and previous successful drain (ADR 0024). */
+  /** The successful drain that made the claim; re-emission, not age, is its horizon (ADR 0034). */
   claimedAt?: number;
+  title?: string;
+  body?: string;
+  chatId?: string;
+  rootId?: string;
+  threadId?: string;
   spawnedPodId?: string;
   blocked?: string;
   appended?: boolean;
@@ -43,6 +49,12 @@ export interface ListenerRecord {
   source?: string;
   /** P0's rule: a plain substring; absent means every item matches. */
   match?: string;
+  /**
+   * Routing filter (ADR 0034): the groups this Listener claims, by the item's
+   * `chat_id`. Absent means every group. A filter is ANDed with `match`, and the
+   * first Listener in registry order that holds claims the item.
+   */
+  chats?: string[];
   mode: ListenerMode;
   /** Template mode: the goal template file. */
   template?: string;

package/src/registry.ts

@@ -10,12 +10,39 @@ import { podsFile, registryLockPath } from "./paths.ts";
  */
 export type PodState = "spawning" | "active" | "idle" | "done" | "cancelled";
 
-export type WakeUpOutcome = "more" | "done" | "failed" | "lost" | "cancelled";
+/**
+ * `more` — the goal needs another wake-up now; `quiet` — this window is
+ * satisfied and nothing is scheduled (ADR 0011 amendment, #36); `done` — the
+ * goal is reached; the rest are failures of the window, not of the Pod.
+ */
+export type WakeUpOutcome = "more" | "quiet" | "done" | "failed" | "lost" | "cancelled";
+
+/**
+ * Who may wake this Pod (ADR 0030): `intake` — the batch a Listener owes;
+ * `external` — an outside clock or a human (`wake`); `self` — the tick. Absent
+ * on a record written before ADR 0030, where the listener binding was the only
+ * thing that could say it (src/admission.ts derives that answer, never writes it).
+ */
+export type Admission = "intake" | "external" | "self";
+
+/**
+ * What admitted a wake-up (ADR 0032). Three launchers existed and were
+ * indistinguishable after the fact; a storm of 41 wake-ups could not be
+ * attributed to any of them from the record.
+ */
+export type WakeTrigger = "spawn" | "tick" | "wake";
+
+/** The default daily ceiling (ADR 0032): the storm ran at 41 in five hours. */
+export const DEFAULT_WAKE_BUDGET_PER_DAY = 24;
 
 export interface WakeUpEntry {
   n: number;
   outcome: WakeUpOutcome;
   detail?: string;
+  /** When the outcome was recorded, epoch ms. Absent on records written before ADR 0032. */
+  at?: number;
+  /** What admitted this wake-up; absent on records written before ADR 0032. */
+  trigger?: WakeTrigger;
 }
 
 export interface PodRecord {
@@ -26,6 +53,15 @@ export interface PodRecord {
   project: string;
   /** The upstream Pod whose done state admits this Pod's first wake-up (ADR 0022). */
   after?: string;
+  /** Decided at spawn, one of three (ADR 0030); the tick reads it before it launches. */
+  admission?: Admission;
+  /**
+   * What admitted the wake-up that is live now (ADR 0032). Written by whichever
+   * launcher ran under the registry lock, read when the outcome is recorded, so
+   * every entry can say who woke it — including the ones reconcile records on a
+   * wrapper's behalf (`lost`, wedged, progressless).
+   */
+  admitted?: WakeTrigger;
   wakeUps: WakeUpEntry[];
   policy?: WakePolicy;
   /** When a pass first observed a wedged wrapper (ADR 0017's two-pass rule). */
@@ -49,6 +85,13 @@ export interface WakePolicy {
   failureStreak: number;
   nextWakeAt?: number;
   parked?: boolean;
+  /**
+   * Which stop parked it (ADR 0032): three different facts that read
+   * identically as `parked`. Only `failures` is lifted by an ordinary `wake`;
+   * a `budget` stop needs `wake --over-budget`, and an `agent` stop needs the
+   * definition back. Absent on records written before ADR 0032.
+   */
+  parkedBy?: "failures" | "budget" | "agent";
   /** How many wake-up outcomes the policy has already taken into account. */
   appliedOutcomes: number;
   /**
@@ -59,10 +102,23 @@ export interface WakePolicy {
    * wake — the tick does not (ADR 0011 stays the rule for unbound pods).
    */
   intakePending?: number;
+  /**
+   * The window declared itself satisfied with nothing scheduled (`quiet`). The
+   * tick stops admitting it; a new intake batch or a human `wake` lifts it
+   * (ADR 0011 amendment, #36). Redundant for a Pod nobody else wakes, and
+   * visible in `status` where a standing goal used to be forced into `more`.
+   */
+  awaiting?: boolean;
   /** The agent every wake-up resolves to unless one wake names another (ADR 0012). */
   agent?: string;
   /** The pod's model pin: it beats the definition's model (ADR 0012). */
   model?: string;
+  /**
+   * The daily ceiling on wake-ups (ADR 0032), from `spawn --wake-budget`;
+   * `DEFAULT_WAKE_BUDGET_PER_DAY` when unset. Exceeding it parks the Pod, which
+   * is the one notification path that already exists (ADR 0021).
+   */
+  wakeBudgetPerDay?: number;
 }
 
 export async function readPods(): Promise<PodRecord[]> {

package/src/sources.ts

@@ -3,7 +3,7 @@ import { randomBytes } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import type { BadInboxLine, InboxItem } from "./inbox.ts";
-import type { ListenerRecord } from "./listeners.ts";
+import type { ClaimRecord, ListenerRecord } from "./listeners.ts";
 import { sourcesFile } from "./paths.ts";
 
 /** A Source outlives its Listeners; its opaque cursor lives beside them (ADR 0024). */
@@ -12,13 +12,19 @@ export interface SourceRecord {
   cmd: string;
   timeoutMs: number;
   cursor?: string;
-  /** The previous successful drain is the claim-retention horizon (ADR 0024). */
+  /** The last successful drain's timestamp; the cursor, not its age, bounds claims (ADR 0034). */
   lastDrainAt?: number;
   /**
    * That drain's yield (ADR 0027): zero is a fact, not a gap — a pull that runs
    * and delivers nothing is the shape of a conversation that never reaches it.
    */
   lastDrainItems?: number;
+  /**
+   * How many of that drain's items no Listener claimed (ADR 0034). A group nobody
+   * listens to is legitimate; a group being drained into nothing is the number an
+   * operator needs, and `doctor` prints it as a question rather than a failure.
+   */
+  lastDrainUnrouted?: number;
   /** A failed drain's fact (ADR 0027): a report cannot say `ok` while every pass fails. */
   lastFailureAt?: number;
   lastError?: string;
@@ -29,9 +35,10 @@ export interface SourceDrain {
   items: InboxItem[];
   bad: BadInboxLine[];
   cursor?: string;
-  /** Successful drains carry their generation and the preceding one's boundary. */
+  /** A successful drain's timestamp, retained for its Source and claim records. */
   drainedAt?: number;
-  previousDrainAt?: number;
+  /** Items this drain delivered that no Listener claimed (ADR 0034). */
+  unrouted?: number;
   /** A failed drain contributes nothing and leaves the cursor untouched. */
   error?: string;
 }
@@ -202,13 +209,12 @@ async function drainOne(source: SourceRecord, project: string): Promise<SourceDr
     });
   });
   if (result.error !== undefined) return { ...empty, error: result.error };
-  // Distinct generations need distinct boundaries even when two local drains
-  // finish within one wall-clock millisecond.
+  // Distinct drains need distinct timestamps even when two local drains finish
+  // within one wall-clock millisecond.
   const drainedAt = Math.max(Date.now(), (source.lastDrainAt ?? 0) + 1);
   return {
     ...parseDrainOutput(source.name, result.stdout ?? ""),
     drainedAt,
-    ...(source.lastDrainAt === undefined ? {} : { previousDrainAt: source.lastDrainAt }),
   };
 }
 
@@ -232,30 +238,39 @@ export async function drainSources(
 }
 
 /**
- * Two generations are enough: after this drain, anything older than the prior
- * successful one is behind the committed cursor and cannot arrive again. The
- * store is transformed without I/O; the caller writes it inside the registry
- * lock before advancing the Source records (ADR 0024). Legacy claims without a
- * timestamp are retained because their generation cannot be proven.
+ * A successful drain is the claim's horizon (ADRs 0024, 0034): an id it did not
+ * re-emit is behind the cursor, while an id it keeps re-emitting stays claimed
+ * for any number of passes. Failed drains and other inbox kinds have no say.
+ * Legacy claims without `claimedAt` stay because their provenance is unproven.
+ *
+ * Claims that began this pass unserved are sheltered until the next one. Their
+ * own item copy must get a chance to materialize, and a legacy miss must remain
+ * `blocked` long enough to be observed; pruning either here would recreate the
+ * silent loss this rule is meant to end. The caller writes the transformed store
+ * inside the registry lock before advancing the Source records.
  */
 export function pruneSourceClaims(
   listeners: ListenerRecord[],
   drained: SourceDrain[],
+  deferredClaims: ReadonlySet<ClaimRecord> = new Set(),
 ): { listeners: ListenerRecord[]; changed: boolean } {
-  const horizons = new Map<string, number>();
+  const reemitted = new Map<string, Set<string>>();
   for (const drain of drained) {
-    if (drain.error === undefined && drain.previousDrainAt !== undefined) {
-      horizons.set(`source:${drain.name}`, drain.previousDrainAt);
+    if (drain.error === undefined) {
+      reemitted.set(`source:${drain.name}`, new Set(drain.items.map((item) => item.id)));
     }
   }
-  if (horizons.size === 0) return { listeners, changed: false };
+  if (reemitted.size === 0) return { listeners, changed: false };
 
   let changed = false;
   const pruned = listeners.map((listener) => {
     const claimed = listener.claimed.filter((claim) => {
-      const horizon = horizons.get(claim.inbox);
+      const emitted = reemitted.get(claim.inbox);
       return (
-        horizon === undefined || claim.claimedAt === undefined || claim.claimedAt >= horizon
+        emitted === undefined ||
+        claim.claimedAt === undefined ||
+        deferredClaims.has(claim) ||
+        emitted.has(claim.item)
       );
     });
     if (claimed.length === listener.claimed.length) return listener;
@@ -265,7 +280,7 @@ export function pruneSourceClaims(
   return { listeners: pruned, changed };
 }
 
-/** Claims and pruning land before this cursor/retention-horizon write (ADR 0024). */
+/** Claims and pruning land before this cursor write (ADRs 0024, 0034). */
 export async function commitSourceCursors(drained: SourceDrain[]): Promise<void> {
   const sources = await readSources();
   let changed = false;
@@ -287,6 +302,12 @@ export async function commitSourceCursors(drained: SourceDrain[]): Promise<void>
       source.lastDrainItems = drain.items.length;
       changed = true;
     }
+    // What the filters left behind is a fact of this drain (ADR 0034), recorded
+    // whether it is zero or not for the same reason the yield is.
+    if (drain.unrouted !== undefined && source.lastDrainUnrouted !== drain.unrouted) {
+      source.lastDrainUnrouted = drain.unrouted;
+      changed = true;
+    }
     // A success clears the failure it disproved (ADR 0027).
     if (source.lastError !== undefined) {
       delete source.lastError;