agents-pod 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -4,7 +4,133 @@ All notable changes to agents-pod. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.6] — 2026-11-05
+
+One pod woke 41 times in five hours, and the store could not say why. Every
+layer held one fact and named none of them: nothing recorded *who may wake this
+pod* (`more` re-armed it, the tick obeyed, and a hand-written `crontab` line
+raced both), nothing recorded *when* a wake-up happened or *what* woke it, and a
+standing goal whose last word could not be `done` had no honest way to say
+"this window is satisfied" — so it lied `more`, which means "now". Six issues,
+four ADRs: the owner is a field (#33, ADR 0030), the derivation is told the
+owner (#34, ADR 0031), every wake-up says when and who (#35, ADR 0032), a
+satisfied window has a word (#36, ADR 0011 amendment), the incident is a fixture
+(#37), and a hybrid ask decomposes on two axes (#32, ADR 0033).
+
+### Added
+
+- **A pod has one admission owner, decided at spawn and recorded** (issue #33,
+  ADR 0030). `admission: intake | external | self` — `intake` is the batch a
+  Listener owes it, `external` is an outside clock or a human calling
+  `agents-pod wake`, `self` is the tick, legal only for a goal that reaches
+  `done`. `spawn --admission <owner>` states it and `--external` is the
+  shorthand; the default is `self`, which is what the tick used to assume for
+  every pod. A Listener binding *is* an intake declaration, so a bound pod reads
+  as `intake` without a second flag, and a pod recorded `external` refuses to be
+  bound — two owners is zero owners when both fire. `status` prints the owner;
+  `doctor` names the two shapes that cost money (a tick-owned pod whose goal
+  names a clock, a tick-owned pod whose goal is open-ended) and their mirror (an
+  `intake` pod no Listener is bound to, which can never be given work). Records
+  written before this release keep their old behaviour and are named, never
+  rewritten.
+- **A goal that names a clock is refused at the surface** (issue #33, ADR 0030).
+  `spawn` — and so `spawn_pod` — exits 2 when the goal carries a time rule
+  (`09:00`, `每天`, `每 30 分钟`, `every 30 minutes`, `daily`) and no outside
+  owner is declared; the refusal names `schedule_task` and the three owners. With
+  `--admission external` or `intake` the clock is context and the goal is
+  accepted; with `self` it is refused, because that is precisely the incident.
+- **Every wake-up says when, and who admitted it** (issue #35, ADR 0032).
+  `WakeUpEntry` gains `at` and `trigger: "spawn" | "tick" | "wake"`, and the
+  launcher writes `admitted` and `active` in one registry-locked write *before*
+  it launches, so a crash leaves an adjudicable `lost` instead of an invisible
+  launch. `status` prints the rhythm — `cadence: 3 in 24h, median interval 2m,
+  last trigger tick` — and a record written before provenance says `not
+  recorded` instead of inventing a timestamp. `doctor` prints a rate line for a
+  pod above 6 wake-ups an hour and names the shape it found; `cron.log` records
+  each launch as `wake <id> tick (admission self)`. This is the sentence the
+  incident needed in round 1 and reconstructed from 41 rounds of its own logs.
+- **A daily ceiling on wake-ups, with a stop that a launcher cannot re-open**
+  (issue #35, ADR 0032). `policy.wakeBudgetPerDay` (default 24, `spawn
+  --wake-budget <n>`) counts the stamped wake-ups in the last 24 h; above it,
+  reconcile parks the pod with `parkedBy: "budget"` and — same park, one
+  notification (ADR 0021) — `status` says *over the daily budget* rather than
+  *consecutive failures: 0*. An ordinary `wake` refuses (exit 2, naming the
+  count, the budget and both ways forward); one more window costs a deliberate
+  `wake --over-budget`, because a ceiling any launcher can re-open is not a
+  ceiling.
+- **A satisfied window has a word: `quiet`** (issue #36, ADR 0009 and ADR 0011
+  amendments). The handoff's first line takes a third declaration — `status:
+  quiet` → outcome `quiet` — for a standing goal whose goal forbids `done`: this
+  window is satisfied and nothing is scheduled. It is a clean exit (the streak
+  resets, the batch it was admitted for is paid) that sets
+  `policy.awaiting = true` and writes no clock; the wake phase skips an awaiting
+  pod before it even asks who owns it, and `status` prints `state: idle
+  (awaiting)`. A new intake batch, a human `wake`, or the removal of the last
+  Listener lifts it — a satisfied pod nobody can feed is reported by `doctor`,
+  never fixed.
+- **A hybrid ask decomposes on two axes, and the clock's unit hands over**
+  (issue #32, ADR 0033). 「每天早上 9:00 汇总 CI，直到我说停」 carries both signals;
+  a tie-break applied to a two-signal sentence is a coin flip, and this one
+  landed on 41 wake-ups. The prompt side now reads `trigger` (`time` ·
+  `message` · `role alive`) and `work` (`stateless per firing` · `needs memory
+  across firings`) and produces exactly three shapes — `schedule_task` alone, a
+  schedule that **hands over** to a pod admitted `intake` or `external`, or a
+  `spawn_pod` with no clock anywhere in the goal — stated as one line before the
+  first tool call. The handover's durable form is the Inbox Item and its minimal
+  form is `agents-pod wake`; neither surface may reimplement the other, so
+  `spawn_pod`'s guidelines and the scheduler skill each name the other. The
+  incident's own ask is now a fixture: a `hybrid` class in
+  `scripts/first-turn-check.sh` (with `--replay`, so the judgement is
+  model-independent) fails a clock inside a `spawn_pod` goal, a missing
+  `schedule_task`, and a schedule with no handover named
+  (`tests/fixtures/first-turn/`, six cases, `tests/first-turn-check.test.ts`).
+
+### Changed
+
+- **An outcome never schedules a wake-up its owner would not have made** (issue
+  #34, ADR 0031). One function, `applyOutcome(policy, owner, wake, now)`, is now
+  the only writer of `nextWakeAt`, and it is told the owner resolved once per pod
+  per pass. `more` re-arms a `self` pod on the next pass, as before; for an
+  `intake` or `external` pod it writes nothing, because the next wake-up is its
+  owner's decision and a `nextWakeAt` there was a second, invisible owner. The
+  backoff follows the same rule (three failures still park any owner — a stop is
+  about money, not scheduling); `cancelled`, `quiet` and any outcome a later
+  version adds are recorded and ignored rather than counting as failures. The
+  two phases still read the Listener bindings at their own moment: sharing one
+  read let a `listener add` that landed mid-pass wake the just-bound pod at the
+  end of that same pass.
+- **`spawn_pod` takes the owner as a parameter** (ADR 0030, ADR 0033), so a
+  model decomposing a standing ask names who wakes the pod while it spawns,
+  instead of leaving the tick to guess.
+
+### Fixed
+
+- **A flag that arrives with no value is a usage error, not a word in the goal**
+  (issue #35). `spawn fix it --wake-budget` used to compose a goal containing the
+  literal flag and run on the default budget — a guardrail whose typo silently
+  disables it is not a guardrail. `parseFlags` now reports every value-taking
+  flag that arrived dangling.
+- **The package no longer ships compiled Python.** `examples/feishu/__pycache__/*.pyc`
+  was in the published tarball and is now ignored.
+
+Known gap, owned by #43: `spawn` still launches one wake-up immediately, so a
+hybrid pod spawned at 15:00 does its first round at 15:00 and its next at 09:00.
+One run is not a storm and the ceiling bounds what follows, so the guideline says
+it out loud rather than claiming the clock owned the first one.
+
+## [0.3.5] — 2026-11-04
+
+### Fixed
+
+- **A reload no longer leaves the extension inert** (issue #28). `/reload`,
+  `/new`, `/resume` and `/fork` replace the whole extension runtime: Pi
+  re-imports the module in the same process and rebuilds every command and tool
+  registry from scratch, while `globalThis` — and with it the `Symbol.for` guard
+  that keeps a second installed copy inert — survives. The reloaded copy saw a
+  claimed process, returned early, and `/pod`, `spawn_pod` and `pod_handoff`
+  vanished until Pi restarted. The guard is now released on `session_shutdown`,
+  so it claims a runtime instead of a process; a second copy in one runtime is
+  still kept out (ADR 0010).
 
 ## [0.3.4] — 2026-11-04
 

package/README.md

@@ -37,7 +37,11 @@ Sibling of [agents-cron](https://pi.dev/packages/agents-cron): **cron owns when
 work starts; pod owns keeping work alive.** Use agents-cron for recurring short
 tasks ("check CI every 30 minutes"). Use agents-pod for standing work
 ("refactor the auth layer — this may take days", "keep watching this incident",
-"serve this inbox — wake an agent per dropped task").
+"serve this inbox — wake an agent per dropped task"). An ask that carries both
+(「每天早上 9:00 汇总 CI，直到我说停」) is neither alone: cron owns the clock and
+**hands the work over** — one Inbox Item when a per-firing input has to be
+queued, or `agents-pod wake` when nothing does — and the pod's goal carries no
+time rule ([ADR 0033](docs/adr/0033-a-hybrid-ask-decomposes-on-two-axes.md)).
 
 ## Why a separate plugin
 
@@ -140,12 +144,15 @@ package until both plugins demonstrably need one.
 agents-pod doctor [--probe] [--json]                     # what is missing, and the command that fixes it
 agents-pod spawn <goal prompt> [--project <dir>] [--agent <id>] [--model <id>] [--cwd <dir>]
                               [--after <podId>]                 # wait for the upstream pod to reach done
+                              [--admission intake|external|self | --external]   # who may wake it (ADR 0030)
+                              [--wake-budget <n>]               # daily ceiling, default 24 (ADR 0032)
 agents-pod project cap [n|unlimited] [--project <dir>]          # per-project live wake-up cap
 agents-pod project move <old> <new> [--apply] [--move-artifacts]  # the tree was renamed: relocate records (ADR 0028)
 agents-pod list [--json]
 agents-pod status <podId>
 agents-pod logs <podId> [--follow]
-agents-pod wake <podId> [--agent <id>] [--warm]     # fresh by default; --warm resumes a lost wake-up's session
+agents-pod wake <podId> [--agent <id>] [--warm] [--over-budget]
+                                                    # fresh by default; --warm resumes a lost wake-up's session
 agents-pod cancel <podId>
 agents-pod reconcile                                # the cron entry point; idempotent
 agents-pod agent add <id> --type <pi|claude|codex> [--model <id>] [--instructions <file>]
@@ -165,8 +172,12 @@ agents-pod deliver rm <name>
 agents-pod adapter sync <name> [--dest <dir>] [--apply] [--force]  # copy the package's adapter, record its provenance (ADR 0029)
 ```
 
-`spawn` claims a pod id, writes the pod record, wakes the first agent, and
-returns immediately with the id. With `--after`, the first wake waits for the
+`spawn` claims a pod id, writes the pod record (including who admits its
+wake-ups — `--admission`, ADR 0030), wakes the first agent, and returns
+immediately with the id. A goal that names a clock (`09:00`, `每天`, `每 30
+分钟`) is refused with exit 2 unless an outside owner is declared: starting work
+at a time is a schedule's job, and a pod carrying a clock is the incident
+([`tests/reconcile.test.ts`](tests/reconcile.test.ts) replays it). With `--after`, the first wake waits for the
 upstream pod's `done`; a cancelled upstream never releases it. When the
 project's cap is full, the new pod likewise waits idle with its document store
 ready. Manual `wake` overrides park/backoff, never dependencies or capacity.
@@ -198,22 +209,34 @@ tool is a guarantee on top of that contract, never a replacement for it.
 | --- | --- | --- |
 | `spawning` | record created, first wake-up not yet confirmed | `spawn` |
 | `active` | a wake-up is live: wrapper alive, heartbeat fresh | wake / reconcile |
-| `idle` | goal open, nothing live; documents current | wrapper / reconcile |
+| `idle` | goal open, nothing live; documents current — `idle (awaiting)` when the last window declared itself satisfied | wrapper / reconcile |
 | `done` | goal reached; terminal | wrapper |
 | `cancelled` | user cancel completed; terminal | wrapper |
 
-A pod never exits — its wake-ups do. Wake-up outcomes: `more` (the goal
-needs another wake-up), `done` (goal reached), `failed`, `lost` (crash,
-reboot, orphan), `cancelled`. Outcomes are adjudicated in three layers —
+A pod never exits — its wake-ups do. Wake-up outcomes — declared in the
+handoff's first line, in this order of preference: `more` (`status: rotating`,
+the goal needs another wake-up now), `quiet` (`status: quiet`, this window is
+satisfied and nothing is scheduled: wake me when work arrives), `done`
+(`status: done`, goal reached) — plus `failed`, `lost` (crash, reboot, orphan)
+and `cancelled`. `quiet` is what a standing goal says instead of lying `more` to
+stay alive (ADR 0011 amendment, #36). Outcomes are adjudicated in three layers —
 the agent's HANDOFF.md declaration over the wrapper's event observation
 over OS exit facts — and a clean exit with no fresh handoff is `failed`
 ([ADR 0009](docs/adr/0009-wake-up-outcome-classification.md)). The wake
 policy turns outcomes into next actions
-([ADR 0011](docs/adr/0011-minimal-wake-policy.md)): `more` re-wakes
-immediately; `failed` and `lost` back off exponentially (1m ×2, cap 15m,
-one streak, reset on `more`); three consecutive failures park the pod —
-still `idle`, auto-wake suspended — until a human wakes it. Reconcile
-policy, per record:
+([ADR 0011](docs/adr/0011-minimal-wake-policy.md), and [ADR 0031](docs/adr/0031-outcomes-do-not-schedule.md)
+for the part that depends on the owner): a clean `more` re-wakes a pod **the
+tick owns** immediately and schedules nothing for a pod somebody else wakes;
+`failed` and `lost` back off exponentially (1m ×2, cap 15m, one streak, reset on
+`more`) — again only for the tick's own pod, since a backoff would admit a pod
+without its owner; three consecutive failures park the pod — still `idle`,
+auto-wake suspended — until a human wakes it, whatever its owner. A **daily
+ceiling** (`policy.wakeBudgetPerDay`, default 24, `spawn --wake-budget`) parks it
+the same way — the same single notification — when the last 24 h hold more
+wake-ups than that, and that stop is not lifted by an ordinary `wake` (only by a
+deliberate `wake --over-budget`), because a ceiling any launcher can re-open is
+not a ceiling ([ADR 0032](docs/adr/0032-provenance-and-a-daily-ceiling.md)).
+Reconcile policy, per record:
 
 - active + wrapper alive + heartbeat fresh → no-op;
 - active + nothing alive (crash, reboot — boot-time mismatch means lost,
@@ -221,13 +244,20 @@ policy, per record:
   (death notifications in P1); the wake policy's backoff applies;
 - agent alive but wrapper dead (orphan) → kill the recorded process group,
   wake-up `lost`, pod → idle;
-- idle + goal open + not parked + wake eligible (past backoff) → wake the
-  pod's default agent — which agent, which model, after how much backoff,
-  is pod-record policy, written by reconcile from outcomes
+- `admission: self` + idle + goal open + not parked + wake eligible (past
+  backoff — the only owner for which an outcome writes one) → wake the pod's default agent — which agent, which model, after how
+  much backoff, is pod-record policy, written by reconcile from outcomes
   ([ADR 0011](docs/adr/0011-minimal-wake-policy.md));
-- idle + **bound by a listener** + nothing owed → no-op. An intake-driven pod
-  is woken on the batch it owes (`policy.intakePending`), never on the tick, so
-  a standing router with an empty inbox costs nothing
+- **awaiting** (the last word was `quiet`) → no-op until work arrives: a new
+  intake batch, a human `wake`, or the removal of the Listener the claim was made
+  to ([ADR 0011 amendment](docs/adr/0011-minimal-wake-policy.md)). `status`
+  prints `idle (awaiting)`, and `doctor` notes an awaiting pod with no Listener,
+  because nothing can ever deliver work to it;
+- `admission: external` → no-op, always: an outside clock or a human calls
+  `wake`, and the tick never launches it ([ADR 0030](docs/adr/0030-wake-admission-owners.md));
+- `admission: intake` + nothing owed → no-op. An intake-driven pod is woken on
+  the batch it owes (`policy.intakePending`), never on the tick, so a standing
+  router with an empty inbox costs nothing
   ([ADR 0026 amendment](docs/adr/0026-affinity-root-message-and-delivery-address.md));
 - idle + parked (consecutive-failure stop) → no-op until a human `wake`
   clears it;
@@ -262,6 +292,42 @@ the copied body (ADRs 0014, 0026). Between batches the pod is not merely idle
 but **asleep**: the tick alone does not wake a bound pod, which is what makes
 "serve this inbox" a shape that can stand for days (ADR 0026 amendment).
 
+### Who admits a wake-up
+
+A pod record carries one owner ([ADR 0030](docs/adr/0030-wake-admission-owners.md)),
+decided at spawn, printed by `status`, and read by the wake phase before it
+launches anything. There are three shapes, and picking one is the operator's
+decision — not a policy the tick guesses:
+
+| `admission` | who wakes it | the shape |
+| --- | --- | --- |
+| `self` | the tick, after every `more` | a goal that reaches `done`: a refactor, an audit, a migration. Default when nobody says. |
+| `intake` | the batch it owes — `listener add --pod` | a standing inbox server or router: idle between batches, and an empty inbox costs nothing |
+| `external` | `agents-pod wake` — an outside clock or a human | a `crontab` line, a webhook, a CI trigger: the clock lives outside core |
+
+`--external` is shorthand for `--admission external`. A Listener binding is
+itself an intake declaration, so `spawn` → `listener add --inbox <dir> --pod
+<id>` needs no flag; a pod recorded `external` refuses to be bound, because two
+owners is zero owners when both fire. `doctor` names the two shapes that cost
+money: a pod the tick owns whose goal names a clock, and a pod the tick owns
+whose goal is open-ended (`常驻`, `监听`, `我说停才停`) — the record is legal,
+the intent is not, and only the operator knows which owner it should have had.
+
+A goal that names a clock is a misroute, not a pod: the schedule owns the time
+and hands the work over. The canonical example is replayed in
+[`tests/reconcile.test.ts`](tests/reconcile.test.ts) and
+[`tests/fixtures/first-turn/`](tests/fixtures/first-turn/), where the incident's
+own ask is the fixture.
+
+### Reading a rate
+
+Every wake-up records `at` and `trigger` (`spawn` / `tick` / `wake`, ADR 0032), so
+the question the incident could not answer — *why did this pod wake 41 times?* —
+is one command per layer: `status <id>` prints `cadence: 41 in 24h, median
+interval 2m, last trigger tick`; `doctor` prints a rate line for any pod above
+6 wake-ups an hour; `cron.log` records each launch as `wake <id> tick (admission
+self)`. The daily ceiling parks the pod before a rhythm becomes a storm.
+
 Overlapping passes: one TTL'd single-flight lock (`reconcile.lock`, stale
 after 5 minutes by wall clock — never PID liveness) skips fresh-held ticks
 with exit 0 and steals stale ones with an audit line; correctness lives in
@@ -287,6 +353,8 @@ a Source command, `source add`, `listener add`, `deliver add`, the cron line,
 ```text
 store     ✓ 1 pods, 0 active
 pass      ✓ last pass 41s ago
+wake      ? pod-c1329c: 41 wake-ups in the last hour, median interval 2m — above the 6/h ceiling
+                its goal names a clock ("9:00") and the tick admits it — that is the #31 shape
 intake    ✗ source feishu: the last drain (2s ago) failed — exit 1
                   run: agents-pod doctor --probe
 listeners ✓ listener-4f1a: source feishu → template triage.md → /work/app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-pod",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Supervision for long-running coding agents: detached pods, heartbeat liveness, cron-ticked reconcile, and a Pi extension for spawning and handoff",
   "license": "AGPL-3.0-or-later",
   "type": "module",

package/src/admission.ts

@@ -0,0 +1,102 @@
+import type { Admission, PodRecord } from "./registry.ts";
+
+/**
+ * Who admits a Pod's wake-up (ADR 0030). ADR 0011's single wake rule —
+ * idle + goal open + not parked + due — is right for a bounded goal and an
+ * unbounded money pit for a standing one: the tick cannot tell "nobody feeds me"
+ * from "a crontab line feeds me at 09:00", so it assumed the second and woke a
+ * router 41 times in five hours. The missing fact was ownership, not a policy
+ * knob, so it is recorded as a fact on the Pod Record and read from there.
+ *
+ * Three owners, exactly one per Pod:
+ *   intake   — a Listener-bound Pod; the batch it owes (`policy.intakePending`)
+ *              is its only admission. An empty inbox costs nothing.
+ *   external — an outside clock or a human calls `agents-pod wake`; the tick
+ *              never launches it.
+ *   self     — the tick admits it. Legal for a goal that reaches `done`, never
+ *              for a standing one (`more` re-arms it on every pass).
+ */
+export const ADMISSIONS = ["intake", "external", "self"] as const;
+
+export function isAdmission(value: string): value is Admission {
+  return (ADMISSIONS as readonly string[]).includes(value);
+}
+
+/**
+ * Who admits this record. A Listener binding is itself an intake declaration —
+ * binding a Pod says "this is fed from an inbox", and it is the act the operator
+ * performs, not a state we ask them to restate. An unbound Pod is owned by the
+ * owner recorded at spawn, or by the tick when nobody recorded one (a record
+ * written before ADR 0030). The binding therefore never rewrites a record: it
+ * outranks it, and `listener add --pod` refuses a Pod recorded as `external`
+ * rather than quietly contradicting it.
+ */
+export function admissionOf(
+  pod: Pick<PodRecord, "id" | "admission">,
+  intakeBound: ReadonlySet<string>,
+): Admission {
+  if (intakeBound.has(pod.id)) return "intake";
+  return pod.admission ?? "self";
+}
+
+/**
+ * The phrase that makes a goal a time rule, or `undefined` (issue #37: "a goal
+ * that names a clock is a misroute, not a pod"). Deliberately narrow — every
+ * match refuses a spawn on the creation side, so a false positive costs an
+ * operator a rejected command. `每天` / `每小时` / `每 N 分钟` / `HH:MM` are the
+ * shapes the incident was written in; `crontab` is NOT here, because "fix the
+ * crontab line" is a legitimate goal about a clock, not a goal with one.
+ */
+const CLOCKS: ReadonlyArray<RegExp> = [
+  /\d{1,2}[:：]\d{2}/, // 09:00, 9：30
+  /(?:每天|每日|每晚|每早|每周|每月|每年|每小时)/,
+  /每\s*\d+\s*(?:分钟|分|小时|钟头|天|日|周|星期|月|秒)/, // 每 30 分钟
+  /(?:早上|上午|中午|下午|晚上|凌晨|深夜)\s*\d{1,2}\s*点/,
+  /\d{1,2}\s*点(?:半|整|钟|\d{2})?/, // 9点, 9点30
+  /到点/,
+  /\bevery\s+(?:\d+\s*)?(?:minute|min|hour|hr|day|week|month|morning|night)/i,
+  /\b(?:daily|hourly|weekly|monthly|nightly)\b/i,
+  /\bat\s+\d{1,2}:\d{2}\b/i, // at 9:30 — a bare "at 3" is not a time ("look at 3 tests")
+  /\d{1,2}\s*(?:am|pm)\b/i,
+];
+
+export function clockPhrase(goal: string): string | undefined {
+  for (const pattern of CLOCKS) {
+    const found = pattern.exec(goal);
+    if (found !== null) return found[0].trim();
+  }
+  return undefined;
+}
+
+/**
+ * Standing language: a goal that describes a role rather than a finish line
+ * (`常驻`, `监听`, `我说停才停`). Only `doctor` and the spawn warning read it, and
+ * only to name the shape — a Pod on `self` with an open-ended goal is woken
+ * after every `more`, with nothing new to work on.
+ */
+const OPEN_ENDED: ReadonlyArray<RegExp> = [
+  /(?:常驻|长期|永久|无限期|永远|一直|监听|盯着|盯住|轮询|说停|直到.{0,6}停)/,
+  /\b(?:forever|indefinitely|standing)\b/i,
+  /\buntil\s+\w+\s+(?:says?|asks?)\s+(?:stop|enough)/i,
+  /\bkeep\s+(?:it\s+)?(?:running|watching|going)\b/i,
+];
+
+export function openEnded(goal: string): boolean {
+  return OPEN_ENDED.some((pattern) => pattern.test(goal));
+}
+
+/**
+ * The refusal `spawn` prints when a goal carries a clock and nobody has said who
+ * admits the wake-ups: the schedule already owns the time, and the incident's
+ * pod was born exactly here (ADR 0030, issue #37).
+ */
+export function clockRefusal(phrase: string): string[] {
+  return [
+    `a goal that names a clock is a misroute, not a pod: "${phrase}"`,
+    "starting work at a time is a schedule's job: call schedule_task (agents-cron) for the clock, and let the schedule hand the work to a pod",
+    "if this pod really is admitted from elsewhere, say so (exactly one owner, ADR 0030):",
+    "  --admission external   an outside clock or a human calls `agents-pod wake`",
+    "  --admission intake     a listener feeds it: listener add --inbox <dir> --pod <id>",
+    "  --admission self       the tick admits it — for a bounded goal that reaches done, never for a standing one",
+  ];
+}

package/src/cadence.ts

@@ -0,0 +1,67 @@
+import type { WakeUpEntry } from "./registry.ts";
+
+/**
+ * Cadence: what the wake-up record says about *when* a Pod woke, read the same
+ * way by `status` (one Pod), `doctor` (the fleet's rate) and the daily ceiling
+ * (ADR 0032). One module because the three must agree on what counts, and
+ * because "41 wake-ups in 5 h" was the whole incident and nothing in the store
+ * could say it in one command (issue #35).
+ *
+ * A record written before ADR 0032 carries no `at`: those wake-ups are counted
+ * (they are history) but never timed, and every reader says so rather than
+ * inventing a timestamp.
+ */
+
+export const HOUR_MS = 3_600_000;
+export const DAY_MS = 24 * HOUR_MS;
+
+/** A wake-up entry that knows when it happened — the only kind a rate counts. */
+export interface StampedWakeUp extends WakeUpEntry {
+  at: number;
+}
+
+export function stamped(wakeUps: readonly WakeUpEntry[]): StampedWakeUp[] {
+  return wakeUps.filter(
+    (wake): wake is StampedWakeUp => typeof wake.at === "number" && Number.isFinite(wake.at),
+  );
+}
+
+/**
+ * The stamped wake-ups inside a window ending now (half-open: `(now - ms, now]`).
+ * Every outcome counts, `lost` included: a wake-up whose wrapper died still
+ * spent an attempt, and a flapping machine that is called busy is exactly the
+ * report this is meant to prevent.
+ */
+export function inWindow(
+  wakeUps: readonly WakeUpEntry[],
+  now: number,
+  windowMs: number,
+): StampedWakeUp[] {
+  const from = now - windowMs;
+  return stamped(wakeUps).filter((wake) => wake.at > from && wake.at <= now);
+}
+
+/**
+ * The median interval between consecutive stamped wake-ups, in ms — the one
+ * number that separates "it works when asked" from "it is re-arming itself".
+ * `undefined` when fewer than two wake-ups are timed.
+ */
+export function medianIntervalMs(wakeUps: readonly WakeUpEntry[]): number | undefined {
+  const times = stamped(wakeUps)
+    .map((wake) => wake.at)
+    .sort((left, right) => left - right);
+  if (times.length < 2) return undefined;
+  const gaps: number[] = [];
+  for (let index = 1; index < times.length; index += 1) gaps.push(times[index]! - times[index - 1]!);
+  gaps.sort((left, right) => left - right);
+  const middle = Math.floor(gaps.length / 2);
+  return gaps.length % 2 === 1 ? gaps[middle]! : Math.round((gaps[middle - 1]! + gaps[middle]!) / 2);
+}
+
+/** Ages and intervals are read at a glance, never as an epoch (ADR 0027's habit). */
+export function duration(ms: number): string {
+  if (ms < 1_000) return `${Math.max(0, Math.round(ms))}ms`;
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
+  if (ms < HOUR_MS) return `${Math.round(ms / 60_000)}m`;
+  return `${Math.round((ms / HOUR_MS) * 10) / 10}h`;
+}