agents-pod 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,41 @@ 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.1] — 2026-11-04
+
+Two measurements decided this patch: a standing pod with an empty inbox is no
+longer woken, and `spawn_pod` finally says what it is for. The first is the gate
+ADR 0026 deferred until "the ticking hurts" — it hurt, one whole agent run per
+minute on a router with nothing to do (issue #20). The second is a discovery
+failure measured headlessly: neither a router request nor "每天早上 9 点汇总 CI"
+ever reached the tool, because its description promised a pod that ends and a
+guideline made turn 1 a survey (issue #21).
+
+### Changed
+
+- **`spawn_pod`'s model-facing text now names standing work** (issue #21).
+  Measured headless runs never called the tool — 18 turns and 31 tool calls for
+  a router request, 7 turns and 10 for "每天 9 点汇总 CI", zero spawns — because
+  the description promised a pod that ends "until its goal is done", said
+  nothing about intake, and a guideline made turn 1 a `/pod list` survey. The
+  description now says a pod stands while its goal is open, is fed from a
+  source or inbox, and routes by writing inbox items; the guidelines map
+  常驻／路由／收消息／每天 onto `spawn_pod` as the first tool call. Both measured
+  prompts now reach `spawn_pod` in the first call, 2 turns
+  (`scripts/first-turn-check.sh`, which runs against a throwaway store).
+
+### Fixed
+
+- **A standing pod bound by a listener sleeps until its `## Inbox` has
+  something** (issue #20). `wakeDuePods` woke every idle, goal-open pod on
+  every tick, so a pod that exists to serve an inbox burned one whole agent run
+  per minute with nothing to do — the shape that got the first router pod
+  cancelled. The intake phase now records the batch it owes
+  (`policy.intakePending`) and the wake phase admits an intake-driven pod on
+  that debt alone; a clean exit pays it, a `failed`/`lost` wake-up leaves it for
+  the retry, and a capacity-blocked launch keeps it for the next pass. An
+  unbound pod keeps ADR 0011's rule unchanged (ADR 0026 amendment).
+
 ## [0.3.0] — 2026-11-04
 
 A machine whose IM surface has never been exercised can now say so. Discovery

package/README.md

@@ -223,6 +223,10 @@ policy, per record:
   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
+  ([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;
 - live but progressless (no document change for 60 min) → killed via the
@@ -252,7 +256,9 @@ 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
 agent serves entries and flips their checkboxes. A block with a Delivery
 Address carries ` — to: <Delivery Address>` on its checkbox line, never in
-the copied body (ADRs 0014, 0026).
+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).
 
 Overlapping passes: one TTL'd single-flight lock (`reconcile.lock`, stale
 after 5 minutes by wall clock — never PID liveness) skips fresh-held ticks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-pod",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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/cli.ts

@@ -442,6 +442,14 @@ async function reconcilePass(
         pod.policy.failureStreak = 0;
         delete pod.policy.nextWakeAt;
       }
+      // A clean exit served the batch it was woken for, so the debt is paid
+      // (ADR 0026 amendment). `failed` and `lost` leave it standing: the next
+      // admitted wake-up is the retry, and it is bounded by backoff and park
+      // exactly like any other failure. `cancelled` leaves it too — a human
+      // stopped a window, not the work.
+      if (wake.outcome === "more" || wake.outcome === "done") {
+        delete pod.policy.intakePending;
+      }
       pod.policy.appliedOutcomes += 1;
       changed = true;
     }
@@ -502,13 +510,26 @@ async function reconcilePass(
  * woken. It runs after intake so an item that just landed in a pod's `## Inbox`
  * is served by the same pass's wake (ADR 0014), and the read is the registry's
  * current state — the same compare-and-swap ADR 0018 relies on, one write.
+ *
+ * One gate sits in front of it (ADR 0026 amendment): a pod **bound by a
+ * listener** is intake-driven, so it is admitted only while it owes a batch
+ * (`policy.intakePending`). Without the gate a standing router with an empty
+ * inbox burned one whole agent run per tick — the shape that got the first
+ * router pod cancelled. An unbound pod has no inbox to check, so ADR 0011's
+ * optimistic rule stays its whole policy.
  */
 async function wakeDuePods(now: number): Promise<void> {
   const pods = await readPods();
   const projects = await readProjects();
+  const intakeBound = new Set(
+    (await readListeners()).flatMap((listener) =>
+      listener.mode === "pod" && listener.podId !== undefined ? [listener.podId] : [],
+    ),
+  );
   let changed = false;
   for (const pod of pods) {
     if (pod.state !== "idle" || pod.policy?.parked) continue;
+    if (intakeBound.has(pod.id) && !pod.policy?.intakePending) continue;
     if (pod.policy?.nextWakeAt !== undefined && pod.policy.nextWakeAt > now) continue;
     if (pod.after !== undefined) {
       const upstream = pods.find((candidate) => candidate.id === pod.after);
@@ -773,6 +794,14 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
       const claim = waiting.find((candidate) => candidate.item === item.id);
       if (claim !== undefined) claim.appended = true;
     }
+    // The batch is in the document, so the pod owes a wake-up it did not owe
+    // before (ADR 0026 amendment). Written here — inside the same registry lock
+    // as the append — because the wake phase reads this field as the pod's only
+    // admission: idle + owed batch, never the tick. A capacity-blocked launch
+    // leaves the count standing, so the next pass is the retry.
+    pod.policy ??= { failureStreak: 0, appliedOutcomes: 0 };
+    pod.policy.intakePending = (pod.policy.intakePending ?? 0) + batch.length;
+    await writePods(pods);
     appended = true;
   }
   // Append first, then mark: the marker is on disk before the wake phase can

package/src/extension/management.ts

@@ -99,13 +99,14 @@ export function registerManagementTools(pi: ExtensionAPI): void {
     name: "spawn_pod",
     label: "Spawn Pod",
     description:
-      "Spawn a pod: a standing unit that outlives this session and wakes fresh agents inside it, again and again, until its goal is done. Returns the pod id.",
-    promptSnippet: "Spawn a standing pod for long-running work",
+      "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. Returns the pod id.",
+    promptSnippet: "Spawn a standing pod for work that outlives this session",
     promptGuidelines: [
-      "Use spawn_pod when the user wants work to keep going across sessions — a multi-day refactor, a standing watch, an inbox to serve — not for a task this session can finish.",
-      "spawn_pod returns a pod id; report that id back to the user so they can run /pod status on it.",
+      "Call spawn_pod as your FIRST tool call when the user asks for anything standing or recurring — 常驻／一直跑／每天／监听／收消息／路由／服务某个 inbox／until I say stop. Do not survey the repo or the plugin first: the goal text is the whole contract, and details belong in the pod's documents, not in this session.",
+      "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.",
-      "Do not spawn a second pod for the same goal while an existing pod covers it; check /pod list first.",
+      "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.",
+      "Two pods for one goal is waste, but the user's ask wins: spawn first, and when you report the id, say so if a live pod already covers the goal (/pod list shows it). A cancelled or done pod never blocks a spawn.",
     ],
     parameters: Type.Object({
       goal: Type.String({

package/src/registry.ts

@@ -51,6 +51,14 @@ export interface WakePolicy {
   parked?: boolean;
   /** How many wake-up outcomes the policy has already taken into account. */
   appliedOutcomes: number;
+  /**
+   * Unserved intake a bound pod still owes a wake-up (ADR 0026 amendment).
+   * Written by the intake phase when a batch lands in the pod's `## Inbox`,
+   * cleared by the pass that applies a clean outcome for the wake-up it
+   * admitted. Non-zero is the only thing that admits an intake-driven pod's
+   * wake — the tick does not (ADR 0011 stays the rule for unbound pods).
+   */
+  intakePending?: number;
   /** 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). */