agents-pod 0.3.5 → 0.3.6

package/src/cli.ts

@@ -14,6 +14,14 @@ import {
 } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
+import {
+  ADMISSIONS,
+  admissionOf,
+  clockPhrase,
+  clockRefusal,
+  isAdmission,
+} from "./admission.ts";
+import { DAY_MS, duration, inWindow, medianIntervalMs, stamped } from "./cadence.ts";
 import {
   agentTypeRefusal,
   isAgentType,
@@ -57,7 +65,13 @@ import {
   type AdapterFileState,
   type AdapterSyncPlan,
 } from "./adapters.ts";
-import type { PodRecord } from "./registry.ts";
+import {
+  DEFAULT_WAKE_BUDGET_PER_DAY,
+  type Admission,
+  type PodRecord,
+  type WakePolicy,
+  type WakeUpEntry,
+} from "./registry.ts";
 import { readPods, withRegistryLock, writePods } from "./registry.ts";
 import {
   commitSourceCursors,
@@ -97,16 +111,19 @@ function launchWrapperDetached(podId: string, agentId?: string, warm = false): v
 }
 
 /**
- * Flags may appear anywhere among the goal words (README's CLI surface), and
- * the words that are not flags compose the goal. A flag without a value is
- * left unset and surfaces through the command's own validation.
+ * Flags may appear anywhere among the words (README's CLI surface), and the
+ * words that are not flags compose the goal. Every flag in `allowed` takes a
+ * value; one that arrives without a value is reported as `dangling` — left in
+ * `rest` it would become part of a goal (`spawn fix it --wake-budget`) and the
+ * command would proceed with the flag silently unset.
  */
 function parseFlags(
   words: string[],
   allowed: readonly string[],
-): { flags: Record<string, string>; rest: string[] } {
+): { flags: Record<string, string>; rest: string[]; dangling: string[] } {
   const flags: Record<string, string> = {};
   const rest: string[] = [];
+  const dangling: string[] = [];
   for (let index = 0; index < words.length; index += 1) {
     const word = words[index]!;
     const name = word.startsWith("--") ? word.slice(2) : undefined;
@@ -115,10 +132,11 @@ function parseFlags(
       flags[name] = value;
       index += 1;
     } else {
+      if (name !== undefined && allowed.includes(name)) dangling.push(`--${name}`);
       rest.push(word);
     }
   }
-  return { flags, rest };
+  return { flags, rest, dangling };
 }
 
 /** Exponential backoff after `failed`/`lost`: 1m ×2, capped at 15m (ADR 0011). */
@@ -126,6 +144,69 @@ function backoffMs(streak: number): number {
   return Math.min(60_000 * 2 ** (streak - 1), 900_000);
 }
 
+/**
+ * One outcome's effect on the record's policy (ADR 0031): the single place that
+ * decides when the *next* wake-up may happen, and the reason it takes the owner.
+ *
+ * **An outcome never schedules a wake-up its owner would not have made.** `more`
+ * means "the goal needs another wake-up"; for a Pod the tick owns that is "on the
+ * next pass", and for a Pod a Listener feeds or an outside clock wakes, the next
+ * wake-up is its owner's decision — a `nextWakeAt` written here would be a second,
+ * invisible owner, which is how a goal re-armed itself at 41 wake-ups in five
+ * hours (issue #31, #34). `cancelled` says nothing about the schedule: a human
+ * stopped a window, not the work.
+ *
+ * The failure streak is *not* owner-dependent: park obeys it, and park is about
+ * money, not about who wakes the Pod.
+ */
+function applyOutcome(
+  policy: WakePolicy,
+  owner: Admission,
+  wake: WakeUpEntry,
+  now: number,
+): void {
+  // `quiet` (ADR 0011 amendment, #36): the window is satisfied and nothing is
+  // scheduled. It is a clean exit — the streak resets, the batch it was admitted
+  // for was served — and the difference from `more` is that it asks for nothing:
+  // no clock, and the tick stops admitting the Pod until work arrives.
+  if (wake.outcome === "quiet") {
+    policy.failureStreak = 0;
+    delete policy.nextWakeAt;
+    delete policy.intakePending;
+    policy.awaiting = true;
+    return;
+  }
+  if (wake.outcome === "more" || wake.outcome === "done") {
+    policy.failureStreak = 0;
+    delete policy.nextWakeAt; // `self`: due on the next pass, at once
+    // A clean exit served the batch it was woken for, so the debt is paid
+    // (ADR 0026 amendment).
+    delete policy.intakePending;
+    // Another wake-up is the work again, so a previous "nothing scheduled" is
+    // spent: the Pod is wake-eligible by its owner's ordinary rule.
+    delete policy.awaiting;
+    return;
+  }
+  // Anything not named here is recorded and ignored, never counted as a failure:
+  // `cancelled` (a human stopped a window, not the work) and any outcome a later
+  // version adds must not park a Pod by falling through (ADR 0031 — #36's `quiet`
+  // is exactly such a value).
+  if (wake.outcome !== "failed" && wake.outcome !== "lost") return;
+  // Only the tick's own Pod is put on a clock; an intake Pod is re-admitted by
+  // the batch it still owes, and an `external` one by its own wake — both
+  // bounded by the streak and the park below, not by this field.
+  policy.failureStreak += 1;
+  // A window that ran and failed was not satisfied by its own account, so the
+  // "nothing scheduled" claim is spent too — the streak machinery decides from
+  // here, and a parked Pod is skipped before admission is even asked.
+  delete policy.awaiting;
+  if (owner === "self") {
+    policy.nextWakeAt = now + backoffMs(policy.failureStreak);
+  } else {
+    delete policy.nextWakeAt;
+  }
+}
+
 /**
  * Signal a pod's process group — never our own. The pgid comes from store
  * data only (wrapper.json, ADR 0003), and the guards make a corrupt record a
@@ -324,6 +405,18 @@ async function reconcilePass(
   const pods = await readPods();
   const agents = await readAgents();
   const now = Date.now();
+  // The owner is resolved per Pod below from the bindings as this pass begins.
+  // A `listener add` from another process can still land during the Pod loop,
+  // and the derivation would then read that Pod as the tick's — which is why the
+  // wake phase reads the bindings again (see wakeDuePods) and why `nextWakeAt`,
+  // the one field such a stale answer could write, gates nothing but a `self`
+  // Pod. A wrong answer here can delay nothing; a wrong answer there would wake
+  // a Pod that had just been bound.
+  const intakeBound = new Set(
+    (await readListeners()).flatMap((listener) =>
+      listener.mode === "pod" && listener.podId !== undefined ? [listener.podId] : [],
+    ),
+  );
   let changed = false;
   const pending: PodNotification[] = [];
 
@@ -348,7 +441,13 @@ async function reconcilePass(
       const facts = await livenessFacts(pod);
       if (facts.quadrant === "lost") {
         const n = facts.wrapper?.wakeup ?? (await maxWakeupNumber(pod)) ?? 1;
-        pod.wakeUps.push({ n, outcome: "lost", detail: lostDetail(facts) });
+        pod.wakeUps.push({
+          n,
+          outcome: "lost",
+          detail: lostDetail(facts),
+          at: now,
+          ...(pod.admitted === undefined ? {} : { trigger: pod.admitted }),
+        });
         pod.state = "idle";
         delete pod.wedgedAt; // a lost wake-up spends any wedged observation
         changed = true;
@@ -390,6 +489,8 @@ async function reconcilePass(
             detail: trusted
               ? "wedged wrapper killed by reconcile"
               : "wedged wrapper signal withheld (recorded process is gone)",
+            at: now,
+            ...(pod.admitted === undefined ? {} : { trigger: pod.admitted }),
           });
           pod.state = "idle";
           delete pod.wedgedAt;
@@ -425,6 +526,8 @@ async function reconcilePass(
               n: wrapper.wakeup,
               outcome: "failed",
               detail: PROGRESSLESS_DETAIL,
+              at: now,
+              ...(pod.admitted === undefined ? {} : { trigger: pod.admitted }),
             });
             pod.state = "idle";
             changed = true;
@@ -438,28 +541,21 @@ async function reconcilePass(
     // two-event notification inventory (ADRs 0021, 0025).
 
     // 2. Policy derivation from outcome facts the wrapper (or step 1) recorded.
+    // The owner is resolved once here and handed to the derivation, so a new
+    // outcome cannot reach the schedule without answering "who wakes this Pod?"
+    // (ADR 0031).
+    const owner = admissionOf(pod, intakeBound);
     const fresh = pod.wakeUps.slice(pod.policy.appliedOutcomes);
     for (const wake of fresh) {
-      if (wake.outcome === "failed" || wake.outcome === "lost") {
-        pod.policy.failureStreak += 1;
-        pod.policy.nextWakeAt = now + backoffMs(pod.policy.failureStreak);
-        // Backoff without a stop is a money pit: streak 3 parks the pod, and
-        // only a human wake lifts it (ADR 0011). Park is policy data, not a state.
-        if (pod.policy.failureStreak >= 3 && !pod.policy.parked) {
-          pod.policy.parked = true;
-          announcePark();
-        }
-      } else if (wake.outcome === "more" || wake.outcome === "done") {
-        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;
+      applyOutcome(pod.policy, owner, wake, now);
+      // Backoff without a stop is a money pit: streak 3 parks the pod, and only
+      // a human wake lifts it (ADR 0011). Park is policy data, not a state, and
+      // it holds for every owner — a stop is about money, not about scheduling.
+      const failed = wake.outcome === "failed" || wake.outcome === "lost";
+      if (failed && pod.policy.failureStreak >= 3 && !pod.policy.parked) {
+        pod.policy.parked = true;
+        pod.policy.parkedBy = "failures";
+        announcePark();
       }
       pod.policy.appliedOutcomes += 1;
       changed = true;
@@ -467,6 +563,23 @@ async function reconcilePass(
 
     const goalOpen = pod.state !== "done" && pod.state !== "cancelled";
 
+    // 2b. The daily ceiling (ADR 0032). The one defence against a loop nobody
+    // predicted: the storm's own round 41 set `parked` by hand, and this is that
+    // manoeuvre promoted to machinery. Park is reused rather than invented, so
+    // exactly one notification is sent (ADR 0021) and only a human `wake`
+    // lifts it (ADR 0011).
+    const budget = pod.policy.wakeBudgetPerDay ?? DEFAULT_WAKE_BUDGET_PER_DAY;
+    const today = inWindow(pod.wakeUps, now, DAY_MS).length;
+    if (goalOpen && !pod.policy.parked && today > budget) {
+      pod.policy.parked = true;
+      // A budget stop is not the failure stop: `wake` lifts the latter freely
+      // (ADR 0011) but must not lift this one, or an outside clock re-opens the
+      // ceiling on every tick and every re-park announces itself (ADR 0032).
+      pod.policy.parkedBy = "budget";
+      announcePark(`${today} wake-ups in 24 h — over the budget of ${budget} (ADR 0032)`);
+      changed = true;
+    }
+
     // 3. Terminal observation (ADR 0021): done is announced once, however many
     // passes later find the record. The marker is what makes it once.
     if (
@@ -494,6 +607,7 @@ async function reconcilePass(
     if (!agentKnown && goalOpen && pod.state !== "active") {
       if (!pod.policy.parked) {
         pod.policy.parked = true;
+        pod.policy.parkedBy = "agent";
         announcePark(`agent "${agentId}" no longer resolves (ADR 0012)`);
         changed = true;
       }
@@ -528,6 +642,19 @@ async function reconcilePass(
  * 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.
+ *
+ * ADR 0030 makes the owner a recorded fact with three values: `intake` (the debt
+ * gate below), `external` (never launched here — an outside clock or a human
+ * calls `wake`), `self` (the tick, for a goal that reaches `done`). A Listener
+ * binding outranks the record, because binding *is* an intake declaration, and
+ * an unrecorded owner falls back to `self` — the old rule, now named and
+ * reported by `doctor` rather than silently assumed.
+ *
+ * The bindings are read here, not handed down from the top of the pass: a
+ * `listener add` can land while a pass spawns pods, retries outboxes, and
+ * drains sources, and a set read seconds earlier would let this phase tick-wake
+ * a pod that had just been bound — the storm's own unit, reintroduced as a race.
+ * The derivation reads its own copy for the same reason, closest to its use.
  */
 async function wakeDuePods(now: number): Promise<void> {
   const pods = await readPods();
@@ -538,20 +665,47 @@ async function wakeDuePods(now: number): Promise<void> {
     ),
   );
   let changed = false;
+  const toLaunch: Array<{ id: string; agent: string }> = [];
+  const lines: string[] = [];
   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;
+    // `quiet`: the window said it was satisfied and scheduled nothing (#36).
+    // No owner admits it until work arrives — a new intake batch or a human
+    // `wake`, both of which clear the flag.
+    if (pod.policy?.awaiting) continue;
+    // Admission first (ADR 0030): the tick is one owner among three, and it
+    // reads the owner from the record instead of inferring it. An `external`
+    // Pod is somebody else's to wake at every tick of every day.
+    const owner = admissionOf(pod, intakeBound);
+    if (owner === "external") continue;
+    if (owner === "intake" && !pod.policy?.intakePending) continue;
+    // A backoff is the tick's own delay, written only for its own Pod (ADR 0031):
+    // letting it gate an `intake` Pod would be a second owner again — a record
+    // that failed before it was bound, or one written before ADR 0031, would
+    // hold a batch back for up to fifteen minutes.
+    if (owner === "self" && pod.policy?.nextWakeAt !== undefined && pod.policy.nextWakeAt > now) {
+      continue;
+    }
     if (pod.after !== undefined) {
       const upstream = pods.find((candidate) => candidate.id === pod.after);
       if (upstream?.state !== "done") continue;
     }
     if (!projectHasCapacity(pod.project, pods, projects)) continue;
-    launchWrapperDetached(pod.id, pod.policy?.agent ?? "default");
+    pod.admitted = "tick";
     pod.state = "active";
+    toLaunch.push({ id: pod.id, agent: pod.policy?.agent ?? "default" });
+    lines.push(`wake ${pod.id} tick (admission ${owner})`);
     changed = true;
   }
+  // Record, then launch (ADR 0032). A crash between the two leaves a ghost the
+  // next pass adjudicates as `lost` — recoverable; a launch nobody recorded is
+  // the same Pod woken twice.
   if (changed) await writePods(pods);
+  for (const launch of toLaunch) launchWrapperDetached(launch.id, launch.agent);
+  // The storm left no trace a single command could read (issue #35): every
+  // launch now says which launcher it was, next to the sources and listeners
+  // that already write here (ADR 0032).
+  for (const line of lines) await appendCronLog(line);
 }
 
 /** One Pod's state as the registry holds it now, read without any lock (ADR 0025). */
@@ -736,12 +890,12 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
         materialized = true;
         continue;
       }
+      // A template Pod is spawned per Inbox Item and exists to finish it: the
+      // tick's own rule is its owner (ADR 0030), and `done` is its end.
       const record = await spawnPodRecord(
         rendered.goal,
         listener.project ?? project,
-        "default",
-        undefined,
-        undefined,
+        { agentId: "default", admission: "self" },
         true,
       );
       claim.spawnedPodId = record.id;
@@ -812,6 +966,9 @@ async function listenersPass(project: string, drained: SourceDrain[]): Promise<v
     // 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;
+    // Work arrived, so a window that had declared itself satisfied is over
+    // (ADR 0011 amendment, #36) — the debt below is what admits the wake.
+    delete pod.policy.awaiting;
     await writePods(pods);
     appended = true;
   }
@@ -934,20 +1091,68 @@ async function statusCmd(
   const last = pod.wakeUps.at(-1);
   out(pod.id);
   out(`  goal: ${goalHeadline(pod.goal)}`);
-  out(`  state: ${pod.state}`);
+  // The suffix qualifies a resting pod: `awaiting` says why the tick leaves it
+  // alone, and a live wake-up is a different answer to the same question.
+  const awaiting = pod.policy?.awaiting === true && pod.state === "idle";
+  out(`  state: ${pod.state}${awaiting ? " (awaiting)" : ""}`);
+  // Who admits this Pod (ADR 0030) — the fact that decides whether the tick
+  // wakes it at all, so `status` says it before it says anything about liveness.
+  const bound = new Set(
+    (await readListeners()).flatMap((listener) =>
+      listener.mode === "pod" && listener.podId !== undefined ? [listener.podId] : [],
+    ),
+  );
+  const owner = admissionOf(pod, bound);
+  out(
+    `  admission: ${owner}${
+      pod.admission === undefined
+        ? " (derived: no owner recorded)"
+        : pod.admission !== owner
+          ? ` (a listener is bound: intake wins over ${pod.admission})`
+          : ""
+    }`,
+  );
   if (pod.after !== undefined) {
     const upstream = (await readPods()).find((candidate) => candidate.id === pod.after);
     out(`  after: ${pod.after} (${upstream?.state ?? "missing"})`);
   }
   out(`  liveness: ${await livenessOf(pod)}`);
   if (pod.policy?.parked) {
-    out(`  parked (consecutive failures: ${pod.policy.failureStreak})`);
+    // Three stops, three sentences (ADR 0011, 0012, 0032): a park that reads
+    // "consecutive failures: 0" tells the operator nothing true.
+    const budget = pod.policy.wakeBudgetPerDay ?? DEFAULT_WAKE_BUDGET_PER_DAY;
+    const today = inWindow(pod.wakeUps, Date.now(), DAY_MS).length;
+    out(
+      pod.policy.parkedBy === "budget"
+        ? `  parked (over the daily budget: ${today} in 24h, budget ${budget}; agents-pod wake ${pod.id} --over-budget)`
+        : pod.policy.parkedBy === "agent"
+          ? `  parked (agent "${pod.policy.agent ?? "default"}" no longer resolves; agents-pod agent add ${pod.policy.agent ?? "default"} …)`
+          : `  parked (consecutive failures: ${pod.policy.failureStreak})`,
+    );
   }
   out(`  agent: ${resolveAgentBinary(process.env)}`);
   out(`  wake-ups: ${pod.wakeUps.length} (last outcome: ${last?.outcome ?? "none"})`);
+  out(`  cadence: ${cadenceLine(pod, Date.now())}`);
   return 0;
 }
 
+/**
+ * The cadence, in the words a storm is recognised by (ADR 0032): how many ran
+ * recently, how tight the rhythm was, and who admitted the last one. A record
+ * written before provenance existed says so instead of showing an invented zero.
+ */
+function cadenceLine(pod: PodRecord, now: number): string {
+  const timed = stamped(pod.wakeUps);
+  if (timed.length === 0) {
+    return "not recorded (this Pod's wake-ups predate provenance, ADR 0032)";
+  }
+  const day = inWindow(pod.wakeUps, now, DAY_MS).length;
+  const median = medianIntervalMs(pod.wakeUps);
+  const rhythm = median === undefined ? "interval n/a (fewer than two timed)" : `median interval ${duration(median)}`;
+  const trigger = pod.wakeUps.at(-1)?.trigger ?? "unknown";
+  return `${day} in 24h, ${rhythm}, last trigger ${trigger}`;
+}
+
 /**
  * The attention ruler's first use (DESIGN Part 1): a healthy pod takes one
  * quiet line at the bottom; the pods that need a human lead. Read-only.
@@ -1045,11 +1250,13 @@ async function wakeCmd(
   err: (line: string) => void,
 ): Promise<number> {
   const { flags, rest } = parseFlags(words, ["agent"]);
-  // `--warm` carries no value, so parseFlags leaves it among the words.
+  // `--warm` and `--over-budget` carry no value, so parseFlags leaves them among
+  // the words.
   const warm = rest.includes("--warm");
+  const overBudget = rest.includes("--over-budget");
   const podId = rest.find((word) => !word.startsWith("--"));
   if (!podId) {
-    err("Usage: agents-pod wake <podId> [--agent <id>] [--warm]");
+    err("Usage: agents-pod wake <podId> [--agent <id>] [--warm] [--over-budget]");
     return 2;
   }
   const pods = await readPods();
@@ -1068,6 +1275,21 @@ async function wakeCmd(
     return 0;
   }
 
+  // The human override lifts park and backoff (ADR 0011) — except the daily
+  // ceiling, which exists precisely because some launcher keeps firing. Lifting
+  // it silently made a cron-driven Pod re-park and re-announce on every pass;
+  // one more window is still available, but it has to be asked for (ADR 0032).
+  if (pod.policy?.parked && pod.policy.parkedBy === "budget" && !overBudget) {
+    const budget = pod.policy.wakeBudgetPerDay ?? DEFAULT_WAKE_BUDGET_PER_DAY;
+    const today = inWindow(pod.wakeUps, Date.now(), DAY_MS).length;
+    err(
+      `Pod ${pod.id} is parked over its daily budget (${today} wake-ups in 24 h, budget ${budget})`,
+    );
+    err(`      one more window, deliberately: agents-pod wake ${pod.id} --over-budget`);
+    err("      or spawn the work again with a ceiling that fits: --wake-budget <n>");
+    return 2;
+  }
+
   // Only a crash has a session worth resuming (ADR 0011): a `failed` wake-up
   // ended cleanly, and a fresh window is the honest continuation for it.
   const last = pod.wakeUps.at(-1);
@@ -1129,13 +1351,18 @@ async function wakeCmd(
       if (target.policy) {
         target.policy.failureStreak = 0;
         delete target.policy.nextWakeAt;
+        // A human wake is the other answer to "wake me when work arrives" (#36).
+        delete target.policy.awaiting;
         delete target.policy.parked;
+        delete target.policy.parkedBy;
       }
       delete target.notifiedAt;
     }
-    launchWrapperDetached(target.id, agentId, warm);
+    target.admitted = "wake";
     target.state = "active";
     await writePods(current);
+    // Recorded first, launched second (ADR 0032): see wakeDuePods.
+    launchWrapperDetached(target.id, agentId, warm);
     return true;
   });
   if (!woke) {
@@ -1191,29 +1418,42 @@ async function cancelCmd(
  * The one spawn path: record, workspace, then wake admission (ADR 0022). An
  * admitted pod gets its detached wrapper; a blocked one waits idle. `spawn`
  * and a listener's template materialization both walk it (ADR 0007).
+ *
+ * The owner is written into the record here (ADR 0030), always: a Pod whose
+ * owner nobody declared is a Pod the tick will guess about.
  */
+export interface SpawnOptions {
+  agentId: string;
+  admission: Admission;
+  model?: string;
+  after?: string;
+  wakeBudgetPerDay?: number;
+}
+
 async function spawnPodRecord(
   goal: string,
   project: string,
-  agentId: string,
-  model?: string,
-  after?: string,
+  options: SpawnOptions,
   registryHeld = false,
 ): Promise<PodRecord> {
+  const { agentId, admission, model, after, wakeBudgetPerDay } = options;
   const record: PodRecord = {
     id: newPodId(),
     goal,
     state: "spawning",
     project: resolve(project),
+    admission,
     ...(after === undefined ? {} : { after }),
     wakeUps: [],
     // The policy names the agent and the optional model pin; `--model` beats
-    // the definition's model, which beats the adapter default (ADR 0012).
+    // the definition's model, which beats the adapter default (ADR 0012). The
+    // daily ceiling rides here too (ADR 0032).
     policy: {
       failureStreak: 0,
       appliedOutcomes: 0,
       agent: agentId,
       ...(model === undefined ? {} : { model }),
+      ...(wakeBudgetPerDay === undefined ? {} : { wakeBudgetPerDay }),
     },
   };
   await createPodWorkspace(record);
@@ -1235,6 +1475,7 @@ async function spawnPodRecord(
       return record;
     }
 
+    record.admitted = "spawn";
     await writePods(pods);
     launchWrapperDetached(record.id, agentId);
     record.state = "active";
@@ -1254,12 +1495,68 @@ async function spawnCmd(
   out: (line: string) => void,
   err: (line: string) => void,
 ): Promise<number> {
-  const { flags, rest } = parseFlags(words, ["agent", "model", "cwd", "project", "after"]);
-  const goal = rest.join(" ").trim();
+  const { flags, rest, dangling } = parseFlags(words, [
+    "agent",
+    "model",
+    "cwd",
+    "project",
+    "after",
+    "admission",
+    "wake-budget",
+  ]);
+  // `--external` carries no value, so parseFlags leaves it among the words: it
+  // is the shorthand ADR 0030 documents for `--admission external`, and it is
+  // taken out before the remaining words compose the goal.
+  const external = rest.includes("--external");
+  const goal = rest.filter((word) => word !== "--external").join(" ").trim();
+  if (dangling.length > 0) {
+    // A flag with no value would otherwise compose the goal and leave its own
+    // setting at the default — a typo that silently disables a guardrail is not
+    // a guardrail (ADR 0032).
+    err(`${dangling[0]} needs a value`);
+    err("Usage: agents-pod spawn <goal prompt> [--agent <id>] [--model <id>] [--cwd <dir>] [--after <podId>]");
+    err("                            [--admission intake|external|self | --external] [--wake-budget <n>]");
+    return 2;
+  }
   if (!goal) {
     err("Usage: agents-pod spawn <goal prompt> [--agent <id>] [--model <id>] [--cwd <dir>] [--after <podId>]");
+    err("                            [--admission intake|external|self | --external] [--wake-budget <n>]");
+    return 2;
+  }
+
+  // The daily ceiling is a guardrail, so its value is validated like any other
+  // surface flag: a typo must not silently disable it (ADR 0032).
+  let wakeBudgetPerDay: number | undefined;
+  if (flags["wake-budget"] !== undefined) {
+    const parsed = Number(flags["wake-budget"]);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+      err(`--wake-budget must be a positive integer, got ${flags["wake-budget"]}`);
+      return 2;
+    }
+    wakeBudgetPerDay = parsed;
+  }
+
+  // Admission is decided before anything is written (ADR 0030): who may wake
+  // this Pod is the fact the incident was missing, and a refused spawn leaves
+  // no record, no workspace, and no wake-up behind.
+  if (flags.admission !== undefined && !isAdmission(flags.admission)) {
+    err(`Unknown admission ${flags.admission}: one of ${ADMISSIONS.join(" | ")}`);
+    return 2;
+  }
+  if (external && flags.admission !== undefined && flags.admission !== "external") {
+    err(`--external means --admission external; not ${flags.admission}`);
     return 2;
   }
+  const declared: Admission | undefined = flags.admission ?? (external ? "external" : undefined);
+  // A goal that names a clock under the tick's own rule is the incident: every
+  // `more` re-arms it, so the clock fires as fast as the passes do. The clock
+  // belongs to a schedule; an `external` or `intake` owner makes it context.
+  const clock = clockPhrase(goal);
+  if (clock !== undefined && declared !== "external" && declared !== "intake") {
+    for (const line of clockRefusal(clock)) err(line);
+    return 2;
+  }
+  const admission: Admission = declared ?? "self";
 
   // Fail fast at the surface (ADR 0012): an unknown id is an exit-2
   // configuration error, before any pod record or workspace exists. An
@@ -1285,13 +1582,13 @@ async function spawnCmd(
     }
   }
 
-  const record = await spawnPodRecord(
-    goal,
-    flags.project ?? flags.cwd ?? deps.cwd ?? process.cwd(),
+  const record = await spawnPodRecord(goal, flags.project ?? flags.cwd ?? deps.cwd ?? process.cwd(), {
     agentId,
-    flags.model,
-    flags.after,
-  );
+    admission,
+    ...(flags.model === undefined ? {} : { model: flags.model }),
+    ...(flags.after === undefined ? {} : { after: flags.after }),
+    ...(wakeBudgetPerDay === undefined ? {} : { wakeBudgetPerDay }),
+  });
   out(record.id);
   return 0;
 }
@@ -1989,6 +2286,19 @@ async function listenerCmd(
           err(`Unknown pod ${flags.pod}`);
           return 2;
         }
+        // Binding is an intake declaration (ADR 0030): a Pod recorded as
+        // `external` is woken from outside, so binding it would silently drop
+        // that owner — and a Pod that owes a batch *and* an outside clock has
+        // two owners, which is zero owners when both fire.
+        if (pod.admission === "external") {
+          err(
+            `Pod ${pod.id} is admitted from outside (--admission external): a listener cannot bind it`,
+          );
+          err(
+            "      bind a Pod spawned with --admission intake, or spawn a new one for this inbox",
+          );
+          return 2;
+        }
         listener.mode = "pod";
         listener.podId = pod.id;
       }
@@ -2025,10 +2335,28 @@ async function listenerCmd(
       }
       const removed = await withRegistryLock(async () => {
         const listeners = await readListeners();
+        const gone = listeners.find((listener) => listener.id === id);
         const remaining = listeners.filter((listener) => listener.id !== id);
         if (remaining.length === listeners.length) return false;
         // Claims go with the record: re-adding is a fresh claim namespace (ADR 0013).
         await writeListeners(remaining);
+        // A `quiet` window's promise is made to a Listener ("wake me when work
+        // arrives"), so removing that Listener removes the claimant: the Pod
+        // falls back to the tick, which would otherwise skip it forever and say
+        // nothing (ADR 0011 amendment, #36).
+        const stillBound = new Set(
+          remaining.flatMap((listener) =>
+            listener.mode === "pod" && listener.podId !== undefined ? [listener.podId] : [],
+          ),
+        );
+        if (gone?.mode === "pod" && gone.podId !== undefined && !stillBound.has(gone.podId)) {
+          const pods = await readPods();
+          const pod = pods.find((candidate) => candidate.id === gone.podId);
+          if (pod?.policy?.awaiting) {
+            delete pod.policy.awaiting;
+            await writePods(pods);
+          }
+        }
         return true;
       });
       if (removed === undefined) {