agents-pod 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -4,6 +4,160 @@ 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).
 
+## [0.3.7] — 2026-11-05
+
+One Feishu app, many groups, one group per project: intake could not say which
+group an item belonged to, so one channel could only serve one project. While
+designing the filter, two intake bugs surfaced that any partition would have
+spread: a capacity-deferred claim lost its item when the cursor moved (#47), and
+a claim was pruned while the overlap was still re-emitting it, so the same
+message came back as a second pod (#46). ADR 0034 answers all three: a Source
+claim owns its item, re-emission (not a generation count) prunes it, and a
+Listener filters on the group. Alongside it, the list stops carrying what can no
+longer act: terminal pods are hidden, and `rm` discards the ones nothing owns.
+
+### Added
+
+- `listener add|edit --chat <chat_id>` — a routing filter over the item's
+  `chat_id`, ANDed with `--match`; one Source feeds N Listeners, so one channel
+  routes each group to its own project (#45, ADR 0034). A directory inbox is
+  refused with exit `2`: its items carry no group.
+- `listener edit <id>` changing `--match`, `--chat`, `--project` and
+  `--max-concurrent` in place, claims included; `rm` + `add` stays a fresh claim
+  namespace and replays the overlap window.
+- `source rewind <name> --to <cursor|"">` — re-read past the cursor after an
+  unrouted batch or a route fixed too late; claims dedupe what returns.
+- `lastDrainUnrouted` recorded per Source, printed by `source list` and `doctor`,
+  and one `cron.log` line per pass with a non-zero count — a group nobody
+  listens to is legitimate, a group nothing wants is not silent.
+- `list` hides `done` and `cancelled` pods by default (`--all` brings them back,
+  the footer counts them), and `rm <podId>` discards a pod no wake-up owns — its
+  record and its workspace (ADR 0035). `rm` refuses a live pod, a bound Listener,
+  a dependent's `after`, and an undelivered Outbox entry.
+
+### Fixed
+
+- A capacity-deferred Source claim carries its item, so it materializes when
+  capacity frees instead of vanishing with the drain that produced it (#47).
+- A claim is pruned by re-emission, not by a two-generation count, so a quiet
+  chat's re-delivered last message no longer returns as a second pod (#46).
+- `parseFlags` keeps every value of a repeatable flag; before, `--chat a --chat b`
+  silently dropped `a`.
+
+## [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

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,36 +144,67 @@ 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)
+                              [--dormant]                       # write the record and launch nothing (ADR 0033)
 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 list [--all] [--json]                             # live pods; --all includes terminal ones
 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 cancel <podId>
+agents-pod wake <podId> [--agent <id>] [--warm] [--over-budget]
+                                                    # fresh by default; --warm resumes a lost wake-up's session
+agents-pod cancel <podId>                           # signals a live wake-up
+agents-pod rm <podId>                               # discard a pod no wake-up owns, with its workspace (ADR 0035)
 agents-pod reconcile                                # the cron entry point; idempotent
 agents-pod agent add <id> --type <pi|claude|codex> [--model <id>] [--instructions <file>]
 agents-pod agent edit <id>                          # $EDITOR on the stored definition
 agents-pod agent rm <id>                            # pods left referencing it park at reconcile (ADR 0012)
 agents-pod agent list [--json]                      # named agents: type, model, role
 agents-pod listener add (--inbox <dir|file> | --source <name>) (--pod <podId> | --template <file>)
-                         [--match <substr>] [--max-concurrent <n>] [--project <dir>]
+                         [--match <substr>] [--chat <chat_id> ...] [--max-concurrent <n>] [--project <dir>]
+agents-pod listener edit <listenerId> [--match <substr>] [--chat <chat_id> ... | --no-chat]
+                         [--max-concurrent <n>] [--project <dir>]
 agents-pod listener list [--json]
 agents-pod listener rm <listenerId>
 agents-pod source add <name> --cmd <path> [--timeout <s>]
 agents-pod source list [--json]
 agents-pod source rm <name>
+agents-pod source rewind <name> --to <cursor|"">   # re-read past the cursor (ADR 0034)
 agents-pod deliver add <name> --cmd <path> [--timeout <s>]
 agents-pod deliver list [--json]
 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.
+With `--dormant` the record, the workspace and the owner are written and
+**nothing is launched**: the first wake-up belongs to the owner, which is what a
+hybrid pod needs so the schedule owns every firing, including the first one
+([ADR 0033 amendment](docs/adr/0033-a-hybrid-ask-decomposes-on-two-axes.md)).
+`--dormant` is refused with `admission: self` — the tick admits an idle pod on
+its next pass, so the stop would last a minute and the flag would lie. A manual
+`wake` starts a dormant pod of any owner: the human is the override, not a
+fourth admission owner, and the wake-up records `trigger: wake` rather than
+claiming a batch arrived.
+
+`list` shows the pods that are still live work: `done` and `cancelled` records
+are hidden unless `--all` is passed, and the footer says how many are hidden.
+`rm` is the record's end, not a stop ([ADR
+0035](docs/adr/0035-removal-is-garbage-collection.md)): it refuses `active` and
+`spawning` pods (`cancel` first), and deletes the record plus
+`<project>/.agents/pods/<podId>/` — documents, log and wake-up sessions
+included. It refuses while a Listener is bound to the pod, while another pod's
+`after` names it, or while its Outbox still holds an undelivered entry; clear
+those first, because each would be left dangling.
 Exit codes follow the house rule: `0` success
 or nothing to do, `1` at least one pod failed (or `doctor` found something
 that blocks a channel), `2` configuration or storage error.
@@ -179,7 +214,7 @@ first, record before exiting.
 
 The Pi extension has two planes, gated by the env the wrapper injects
 ([ADR 0010](docs/adr/0010-two-extension-planes.md)). The **management
-plane** (`/pod list|status|logs|spawn|wake|cancel|agents|listeners` and the
+plane** (`/pod list|status|logs|spawn|wake|cancel|rm|agents|listeners` and the
 `spawn_pod` tool) registers only in an interactive session: inside a pod
 those tools and commands are not registered at all, so fan-out is
 structurally impossible rather than forbidden. The **self plane** registers
@@ -198,22 +233,40 @@ 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, `idle (dormant: no wake-up yet)` when none has run | 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 terminal pod is not deleted by reaching its state: it stays visible to
+`status`, `list --all` and its documents until `rm` discards it, and it is never
+re-woken (ADR 0035). `rm` accepts `done`, `cancelled` and `idle` — a pod that no
+wake-up owns — and refuses `active`/`spawning`, a bound Listener, a dependent's
+`after`, and an undelivered Outbox entry.
+
+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 +274,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;
@@ -253,6 +313,16 @@ placeholders: `{{id}}` `{{title}}` `{{body}}` `{{path}}` and `{{reply_to}}`.
 The last placeholder carries the Delivery Address consumed by the outbound
 contract below (ADRs 0013, 0026).
 
+One Source may feed several Listeners, so one channel can serve many
+groups: `--chat <chat_id>` (repeatable) is a routing filter over the item's
+`chat_id`, ANDed with `--match`, and the first Listener in `listeners.json`
+order that holds claims the item (ADR 0034). A Source drained once, its items
+split by their group to as many projects as there are Listeners. What no
+Listener claims is counted, not silently dropped: `source list`/`doctor`
+report `lastDrainUnrouted` and the pass writes one `cron.log` line. A
+`--chat` filter needs an item that carries a group, so `listener add --chat`
+against a directory inbox exits `2`; JSONL and Source items are filterable.
+
 For a standing pod, claimed items land in its `TASKS.md` `## Inbox`
 section — below the agent-owned `## Waiting`, and appended only while no
 wake-up is live, then one batch, one wake on the ordinary wake path; the
@@ -262,6 +332,49 @@ 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.
+
+The handover's first firing needs one more promise: `spawn --dormant` (or
+`spawn_pod`'s `dormant: true`). A hybrid pod is written without its spawn
+wake-up, so the schedule owns every firing and the first Inbox Item — or the
+first `agents-pod wake` — is wake-up 1. `status` shows such a pod as
+`idle (dormant: no wake-up yet)`, derived from an empty wake-up list rather than
+stored: nothing has run, so nothing has to be cleared when it does.
+
+### 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 +400,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
@@ -335,6 +450,9 @@ name, removing an in-use Source, or adding a second deliverer returns `2`.
 `--pod <podId>`. With `--template`, `--project <dir>` selects the new Pods'
 project and defaults to the reconcile invocation's cwd; with `--pod` it is a
 configuration error (exit `2`), because the bound Pod keeps its own project.
+`--chat` may repeat and replaces the whole filter; `listener edit` changes a
+rule in place, claims included — `rm` + `add` is a fresh claim namespace and
+the replay window hands the old ids back (ADR 0034).
 
 ### Writing a Source drain
 

package/examples/feishu/README.md

@@ -31,6 +31,29 @@ behaviour alone cannot report it. A file you edited yourself is reported as a
 local edit and kept; `--force` is the only way to replace it. Plain `cp` still
 works; it just leaves nothing for `doctor` to compare against.
 
+## One app, one drain, many groups
+
+A tenant usually runs several groups, one per project. That needs **one**
+drain and one Listener per group — the drain already walks every chat the bot
+sits in, and every item carries its `chat_id` (ADR 0034):
+
+```bash
+agents-pod source add feishu --cmd ~/.agents/pods/adapters/feishu_drain.py --timeout 60
+agents-pod listener add --source feishu --chat oc_aaaa --template ~/work/app-a/TASK.md --project ~/work/app-a
+agents-pod listener add --source feishu --chat oc_bbbb --template ~/work/app-b/TASK.md --project ~/work/app-b
+```
+
+One cursor, one poll per pass, one Pod per group's message; a reply goes back to
+the group it came from because the Delivery Address travels with the item. A
+group no Listener names is **counted as `unrouted`** and printed by `doctor` —
+the bot is reading it and nothing wants it, which is worth being told. Add
+`--chat` to an existing Listener with `listener edit`, never `rm` + `add`: the
+claims live in the record, and re-adding replays the overlap window as new work.
+
+`FEISHU_CHATS` is a different axis: the adapter-level allowlist limits what the
+**drain** reads at all (and gives each group its own cursor if you run one copy
+per group). Use it for hard isolation, `--chat` for routing.
+
 ## The one thing this cannot do for you: the app
 
 Feishu's console is a human surface. In order:
@@ -160,3 +183,45 @@ message is still subject to `FEISHU_REQUIRE_MENTION`.
 The pair shares a client file and nothing else. A different platform is a
 second pair of commands and needs nothing from core; a second Feishu app needs
 nothing from this directory but another `.env`.
+
+## Limits the code meets, and the road not taken (push)
+
+Facts from Feishu's own docs, recorded because they bound the *next* change
+rather than this one. Every claim names the page it came from; none of them is
+in the code yet.
+
+**Frequency.** Error `230020` is the rate limit: **5 QPS to one group**, shared
+by every bot in it, and 5 QPS to one user. A chat walk is one call per chat, so
+the per-group cap — not the per-tenant one — is what a wide `FEISHU_CHATS`
+meets first. ([message list](https://open.feishu.cn/document/server-docs/im-v1/message/list))
+
+**Reply payloads** (what `feishu_deliver.py` may send): `content` is a
+*serialized JSON string* whose shape follows `msg_type`; text is capped at
+150 KB, cards and rich text at 30 KB; `uuid` is ≤50 characters with one hour of
+idempotency. `reply_in_thread` refuses with `230071` (the group does not support
+topic replies) and `230072` (aggregated messages). ([reply message](https://open.feishu.cn/document/server-docs/im-v1/message/reply))
+
+**Message-list parameters** the drain does not pass yet: `sort_type`
+(`ByCreateTimeAsc` default, fixed once paging starts), `page_size` 1–50
+(default 20), `card_msg_content_type`, `only_thread_root_messages`,
+`with_sender_name`. ([message list](https://open.feishu.cn/document/server-docs/im-v1/message/list))
+
+**Push, if anyone ever wants it** (ADR 0024 leaves the door open; core stays
+pull-only). The two transports share the at-least-once contract and the retry
+schedule — 15 s, 5 min, 1 h, 6 h, at most four retries, ≈7 h — and differ in
+everything else:
+
+- *Webhook* needs a **public IPv4** URL, must echo `url_verification` within
+  **1 s** before the URL can even be saved, and must return HTTP 200 within
+  **3 s** (TCP connect 2 s + callback 3 s). A laptop that sleeps or changes
+  network fails that ack, and the retry window is the only recovery.
+- *Long connection* (outbound WebSocket) needs no public address — only
+  outbound internet — and is **enterprise self-built apps only**. Success is the
+  handler returning within **3 s** without throwing. The hard limits: **at most
+  50 connections per app**, each initialized client being one connection, and
+  delivery is **cluster mode with no broadcast** — with several clients of one
+  app, only one randomly chosen client receives each message. A shim is
+  therefore one connection, never a pool.
+
+That last fact is why "push" here can only be a single resident process with a
+file inbox behind it: any fan-out is the platform's, not ours.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-pod",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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",
+  ];
+}