agents-pod 0.3.5 → 0.3.6

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[],

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

@@ -93,17 +93,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`. Its spawn wake-up runs once immediately; every firing after that belongs to the handover. Never a pod alone, and never `self`. (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 +131,12 @@ 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.",
+        }),
+      ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) {
       const argv = ["spawn", params.goal, "--project", ctx.cwd];
@@ -129,6 +144,7 @@ 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);
 
       const outcome = await runCli(argv, ctx.cwd);
       const podId = outcome.lines.join("\n").trim();

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/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/wrapper.ts

@@ -28,6 +28,7 @@ import {
   withRegistryLock,
   writePods,
   type PodRecord,
+  type WakeUpEntry,
   type WakeUpOutcome,
 } from "./registry.ts";
 import { snapshotDocs } from "./workspace.ts";
@@ -70,7 +71,7 @@ export function composePrompt(goal: string, docsDir: string, roleInstructions =
     `1. ${join(docsDir, "HANDOFF.md")} — your predecessor's handoff; start where it ended.`,
     `2. ${join(docsDir, "TASKS.md")} — the plan and its checkboxes.`,
     `3. ${join(docsDir, "DECISIONS.md")} — the why behind the plan.`,
-    "When this window's work is done, end with pod_handoff (status: rotating or done) so your successor starts clean. Write-then-exit is the protocol: an exit without a fresh handoff counts as a failure.",
+    "When this window's work is done, end with pod_handoff so your successor starts clean: status rotating (the goal is open and the next wake-up continues), quiet (this window is satisfied, nothing is scheduled — wake me when work arrives), or done (the goal is reached and the pod ends). Write-then-exit is the protocol: an exit without a fresh handoff counts as a failure.",
   ].join("\n");
   const goalBlock = `Goal: ${goal}`;
   const sections = [preamble, roleInstructions.trim(), goalBlock].filter(
@@ -170,14 +171,19 @@ export interface Adjudication {
 async function freshDeclaration(
   docsDir: string,
   wakeStart: number,
-): Promise<"more" | "done" | undefined> {
+): Promise<"more" | "quiet" | "done" | undefined> {
   const handoff = join(docsDir, "HANDOFF.md");
   const info = await stat(handoff).catch(() => undefined);
   if (!info || info.mtimeMs <= wakeStart) return undefined;
   const firstLine = (await readFile(handoff, "utf8")).split("\n", 1)[0]!.trim();
-  const declared = /^status:\s*(rotating|done)\s*$/.exec(firstLine);
+  // Three words, and no fourth (ADR 0009 amendment, #36): `rotating` — another
+  // wake-up is the work; `quiet` — this window is satisfied and nothing is
+  // scheduled; `done` — terminal. Anything else is not a declaration.
+  const declared = /^status:\s*(rotating|quiet|done)\s*$/.exec(firstLine);
   if (!declared) return undefined;
-  return declared[1] === "done" ? "done" : "more";
+  const word = declared[1];
+  if (word === "done") return "done";
+  return word === "quiet" ? "quiet" : "more";
 }
 
 /**
@@ -265,7 +271,13 @@ async function recordUnresolved(
   what: string,
 ): Promise<boolean> {
   return updatePodRecord(podId, podRoot, n, (record) => {
-    record.wakeUps.push({ n, outcome: "failed", detail: what });
+    record.wakeUps.push({
+      n,
+      outcome: "failed",
+      detail: what,
+      at: Date.now(),
+      ...(record.admitted === undefined ? {} : { trigger: record.admitted }),
+    });
     record.state = "idle";
   });
 }
@@ -493,11 +505,13 @@ export async function runWrapper(argv: string[]): Promise<number> {
       // a wedged kill. A human cancel has no intent and records exactly as
       // before.
       if (record.killIntent?.n !== n) {
-        record.wakeUps.push(
-          killedAfterGrace
-            ? { n, outcome: "cancelled", detail: "killed after grace" }
-            : { n, outcome: "cancelled" },
-        );
+        record.wakeUps.push({
+          n,
+          outcome: "cancelled",
+          ...(killedAfterGrace ? { detail: "killed after grace" } : {}),
+          at: Date.now(),
+          ...(record.admitted === undefined ? {} : { trigger: record.admitted }),
+        });
         record.state = "cancelled";
       }
     });
@@ -518,7 +532,17 @@ export async function runWrapper(argv: string[]): Promise<number> {
   // (ADR 0025). Failures are logged inside the flush and never change outcome.
   await flushOutbox(podId, pod.project, n);
   const recorded = await updatePodRecord(podId, podRoot, n, (record) => {
-    record.wakeUps.push(detail === undefined ? { n, outcome } : { n, outcome, detail });
+    // Provenance (ADR 0032): when, and what admitted the window. `admitted` is
+    // written by the launcher under the registry lock, so a wake-up the tick
+    // started and one a human started stop looking identical after the fact.
+    const entry: WakeUpEntry = {
+      n,
+      outcome,
+      ...(detail === undefined ? {} : { detail }),
+      at: Date.now(),
+      ...(record.admitted === undefined ? {} : { trigger: record.admitted }),
+    };
+    record.wakeUps.push(entry);
     record.state = outcome === "done" ? "done" : "idle";
   });
   if (!recorded) return 1;