agents-pod 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,531 @@
-# Temporary Holding Version
+# agents-pod
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Supervision for long-running coding agents: spawn a **pod** — a standing
+unit that outlives every context window — and wake **agents** inside it,
+again and again, each wake-up fresh, documents carrying the work across.
+
+> **Status: `0.2.0` — IM intake and outbound.** The CLI runs (spawn, wake,
+> cancel, logs, reconcile, listeners, sources, deliverers, notifications) and the
+> Pi extension ships its two planes. A pod can now be fed from a chat and answer
+> into it, through operator commands that keep credentials and sockets out of
+> core. Wake-ups are **Pi only** in this release. Interfaces may still move
+> before `1.0`. The design lives in `CONTEXT.md` and `docs/adr/`; a reader's
+> companion — the design principles and an explained vocabulary — in
+> [docs/DESIGN.md](docs/DESIGN.md).
+
+## Install
+
+```bash
+npm install -g agents-pod          # CLI; needs Node >= 22.19.0
+pi install npm:agents-pod          # Pi extension: /pod and spawn_pod
+```
+
+```bash
+agents-pod spawn "refactor the auth layer — this may take days"
+agents-pod status <podId>
+```
+
+Then put one line on a crontab so idle pods get woken (see [Storage](#storage)):
+
+```cron
+* * * * * agents-pod reconcile >> "$HOME/.agents/pods/cron.log" 2>&1
+```
+
+The package ships TypeScript and runs it as-is — no build step, no `dist/`.
+
+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").
+
+## Why a separate plugin
+
+agents-cron runs each task as a short, synchronous headless run: the runner
+process waits for the agent to exit while holding a project-wide run lock,
+output is buffered in memory, a 30-minute timeout reclaims stuck runs, and a
+dead run restarts from zero. That model is right for cron-scale work and wrong
+for multi-day agents:
+
+- one long run holds the lock for days and starves every other task in its
+  project;
+- a reboot (or, on WSL, any Windows restart) orphans the agent and loses the
+  work — nothing can watch, cancel, or resume a live run;
+- recurring schedules and long runs are semantically incompatible
+  (`nextRunAt` only advances after a run finishes, so "every 30m" silently
+  becomes "every 2 days").
+
+The decision, its alternatives, and the reuse plan are recorded in
+[ADR 0001](docs/adr/0001-separate-plugin-not-an-agents-cron-extension.md).
+
+## Design
+
+**No daemon. Time is cron's; lifetime is ours.** Nothing in agents-pod stays
+resident — not even intake: a listener is a record the pass materializes. A
+pod is an OS-detached process tree; supervision is `agents-pod reconcile`, an
+idempotent pass ticked by cron once a minute. Any tick can be lost — the next
+tick sees the same world
+([ADR 0002](docs/adr/0002-no-daemon-detached-pods-and-cron-ticked-reconcile.md)).
+
+**A pod outlives its agents.** The pod is the standing unit: one **Goal**,
+one workspace, one **document store**, one supervision identity. Agents are
+workers woken inside it — and a pod accepts different **types and roles** of
+agent (planner, coder, reviewer; pi, claude, codex) across its life
+([ADR 0006](docs/adr/0006-agents-are-woken-pods-outlive-them.md)).
+
+**Wake-ups are the context unit; the pod isolates them.** One **wake-up** =
+one agent, one fresh context window: read the pod documents first, work,
+record (handoff, decisions, task state), exit with an outcome. Agents in a
+pod share its documents, never one another's windows; pending Outbox entries
+are files, not context. Context exhaustion ends a wake-up, never the pod;
+waking again is routine, not recovery. The store's contract is three slots,
+two hard lines ([ADR 0008](docs/adr/0008-document-store-contract.md)).
+
+**A wrapper owns each wake-up's liveness.** Every wake-up gets a tiny
+**wrapper** — detached, session and process-group leader — that spawns the
+agent CLI, streams stdout/stderr to the pod log, touches a heartbeat, and
+records the outcome. Between wake-ups the pod is **idle**: a registry fact,
+not a process. The agent runtime never knows it is supervised
+([ADR 0003](docs/adr/0003-wrapper-process-owns-liveness.md), scope narrowed
+by ADR 0006).
+
+**The record follows reality, not heuristics.** Liveness is a pid plus a
+heartbeat written by our own wrapper — never "started N minutes ago". A
+record that says active while nothing is alive is a **ghost record**, and
+reconcile marks the wake-up lost and the pod idle. An agent process alive
+with no wrapper is an **orphan**, and reconcile reaps it. Kubernetes
+vocabulary on purpose: desired state, observed state, reconcile.
+
+**Standing intake is a record, not a process.** A **listener** is a registry
+entry: an inbox (a directory or file anyone — human, CI, a crontab line —
+may write), a target (a pod template, or a bound standing pod), and bounds.
+Each pass scans inboxes, claims new items by id, and materializes work. A
+pod whose goal is "serve this inbox" is a resident agent with no resident
+process ([ADR 0007](docs/adr/0007-listeners-standing-intake-without-a-daemon.md)).
+
+**Cancel and logs are first-class.** `cancel` signals the live wake-up's
+whole process group, then kills it after a grace period; the wrapper records
+the cancellation. `logs --follow` tails the stream the wrappers have been
+writing since spawn — every wake-up, in order, never buffered in memory.
+
+**Borrow, don't link.** The agent adapter layer, registry and locking
+patterns, notifications, and the packaging story are copied from agents-cron
+and adapted (spawn returns a pid and streams; nothing buffers). No shared
+package until both plugins demonstrably need one.
+
+```text
+  you (or a Pi session)           one pod, standing for days           cron, every minute
+  ──────────────────────────      ───────────────────────────────      ───────────────────────
+  agents-pod spawn <goal>   →     Pod: Goal · documents · wake-ups     agents-pod reconcile
+  agents-pod status | logs        │                                       │  per pod record:
+  agents-pod wake <podId>         ▼ wake: an agent (type · role)        │   active: pid? beat?
+  agents-pod cancel               Wrapper + agent CLI, fresh window     │   idle + goal open?
+                                   ├─ streams stdout/stderr → output.log │     → wake next agent
+                                   ├─ writes into the document store    │   listener inbox:
+                                   └─ outcome → pod idle, or done       │     route or spawn
+                                                                        ▼
+                                                                  no-op · mark lost ·
+  ┌───────────────────────────────────────────────────────────────┐  reap orphan · wake next
+  │  ~/.agents/pods/pods.json          pods: state + wake-ups     │
+  │  ~/.agents/pods/projects.json      per-project wake-up caps   │
+  │  ~/.agents/pods/agents.json        named agents: type · role  │
+  │  ~/.agents/pods/listeners.json     listeners + claimed ids    │
+  │  <project>/.agents/pods/<podId>/   docs · log · wake sessions │
+  └───────────────────────────────────────────────────────────────┘
+```
+
+## CLI
+
+```text
+agents-pod spawn <goal prompt> [--project <dir>] [--agent <id>] [--model <id>] [--cwd <dir>]
+                              [--after <podId>]                 # wait for the upstream pod to reach done
+agents-pod project cap [n|unlimited] [--project <dir>]          # per-project live wake-up cap
+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 cancel <podId>
+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>]
+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 deliver add <name> --cmd <path> [--timeout <s>]
+agents-pod deliver list [--json]
+agents-pod deliver rm <name>
+```
+
+`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
+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.
+Exit codes follow the house rule: `0` success
+or nothing to do, `1` at least one pod failed, `2` configuration or storage
+error.
+
+Every goal prompt carries the wake-up protocol: read the pod documents
+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
+`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
+only inside a pod — `pod_handoff`, which writes `docs/HANDOFF.md` from the
+template with the `status:` first line guaranteed and returns
+`terminate: true`, making write-then-exit one call instead of a ritual the
+agent can skip. The gate is `AGENTS_POD_POD_ID`, with `AGENTS_POD_WAKEUP_N`
+and `AGENTS_POD_DOCS_DIR` beside it; a `Symbol.for` flag keeps a second
+installed copy of the extension inert. Claude and Codex wake-ups are not
+shipped in `0.1.0`, so the file convention is the contract there: the
+tool is a guarantee on top of that contract, never a replacement for it.
+
+## Pod lifecycle
+
+| State | Meaning | Written by |
+| --- | --- | --- |
+| `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 |
+| `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 —
+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:
+
+- active + wrapper alive + heartbeat fresh → no-op;
+- active + nothing alive (crash, reboot — boot-time mismatch means lost,
+  no pid probed, ADR 0020) → wake-up `lost`, pod → idle
+  (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
+  ([ADR 0011](docs/adr/0011-minimal-wake-policy.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
+  cancel path, recorded `failed — progressless`, feeding the streak like
+  any failure (ADR 0019, P1);
+- terminal → no-op (terminal is terminal: `wake` refuses; continuation is
+  a new pod).
+
+After pods, the same pass materializes listeners: use each Source's drained
+items or scan each inbox, claim new items by id (registry-first, so a lost tick
+cannot double-claim), then either spawn a pod from the listener's template —
+bounded by `--max-concurrent` and the per-project pod cap — or append a batch
+to the bound standing pod and use the ordinary capacity-checked wake path.
+
+An inbox is a directory (one item per top-level non-dot file; claimable once
+its mtime and size hold across two passes) or one append-only JSONL file
+(`body` required, `title` optional; malformed lines skipped with a warning).
+A JSONL line may also carry the routing fields `chat_id`, `root_id` and
+`thread_id`; any other key is ignored. Item ids are filenames or line
+numbers — never content — claimed per inbox; templates bind five
+placeholders: `{{id}}` `{{title}}` `{{body}}` `{{path}}` and `{{reply_to}}`.
+The last placeholder carries the Delivery Address consumed by the outbound
+contract below (ADRs 0013, 0026).
+
+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
+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).
+
+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
+registry-lock CAS on every state transition, so two passes — or a human
+`wake` and a pass — can never double-wake a pod (ADR 0018).
+
+Notifications (P1): two events only — park (with the failure verdict)
+and done — through the copied channels (webhook/email/system) in
+`~/.agents/pods/config.json`; once per episode; individual outcomes
+never notify (ADR 0021).
+
+## IM intake and outbound
+
+The operator owns platform I/O. A **Source** is an executable pull drain; the
+single **deliverer** is an executable push command. Source definitions and
+their committed cursors live in `~/.agents/pods/sources.json`; Listener claims
+live in `~/.agents/pods/listeners.json`; the deliverer lives in
+`~/.agents/pods/deliverer.json`. `source add` and `deliver add` resolve `--cmd`
+against the add command's cwd and require an executable regular file.
+`--timeout` is a positive number of seconds, default `10`. Their add/list/rm
+commands return `0` on success; invalid arguments, an unknown or duplicate
+name, removing an in-use Source, or adding a second deliverer returns `2`.
+
+`listener add --source <name>` takes either `--template <file>` or
+`--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.
+
+### Writing a Source drain
+
+Each reconcile pass invokes every distinct Source consumed by a Listener once,
+before any Pod work and before taking the registry lock. The command receives
+no arguments. Its cwd is the reconcile invocation's project (its cwd, not a
+Listener's `--project`), and it inherits that invocation's environment plus:
+
+- `AGENTS_POD_SOURCE_ID` — the registered Source name;
+- `AGENTS_POD_CURSOR` — the last committed cursor, or the empty string when no
+  cursor has been committed.
+
+The command writes JSONL to stdout; stdin is closed and stderr is ignored. A
+successful stream contains zero or more items followed by an optional cursor
+as the last non-empty line:
+
+```jsonl
+{"id":"message-123","body":"Please review this","title":"Review request","chat_id":"chat-1","root_id":"root-1","thread_id":"thread-1"}
+{"cursor":"next-page-token"}
+```
+
+- `id` is a non-empty string and `body` is a string; both are required. The id
+  is the platform's stable deduplication key.
+- `title` is optional. A missing or blank title defaults to the trimmed first
+  line of `body`.
+- `chat_id`, `root_id` and `thread_id` are optional routing strings. Non-empty
+  values are trimmed; blank or non-string values are ignored. They feed
+  `{{reply_to}}`. Source items have no filesystem path, so `{{path}}` is empty.
+  Unknown keys are ignored.
+- The final `{"cursor":"…"}` line takes a string. Omitting it leaves the
+  stored cursor unchanged. Blank lines are ignored. A malformed JSON line, an
+  invalid item, or an invalid final cursor is skipped with one
+  `~/.agents/pods/cron.log` warning and is not claimed; other valid lines still
+  count.
+
+Exit `0` commits the successful drain. Claims use `source:<name>` as their
+inbox namespace and the item's platform id, shared by every Listener on that
+Source. Claims are written to `listeners.json` before the Source's cursor is
+atomically written to `sources.json`, so a crash between those writes replays
+into id deduplication. A committed drain also advances the record's
+`lastDrainAt`; claims from the current and previous successful drain
+generations are retained and older timestamped claims are pruned. Claims with
+no generation timestamp are retained. For a Source bound to a standing Pod,
+the claimed batch must also be appended to `TASKS.md` before cursor and
+`lastDrainAt` commit; a live wake-up holds that append, so the next pass drains
+from the unchanged cursor again.
+
+A non-zero exit, termination by a signal, spawn failure, timeout, or total
+stdout larger than **1 MiB** abandons the whole drain: no items are claimed,
+neither cursor nor `lastDrainAt` moves, no claims are pruned, and exactly one
+`cron.log` line records the failure. Reconcile still exits `0`; the next pass
+retries the whole drain from the same cursor (ADR 0024).
+
+### Writing the deliverer
+
+Exactly one deliverer may be configured; remove it before adding a replacement.
+A Wake-up writes one JSON file per outgoing message in its own Pod:
+
+```text
+<project>/.agents/pods/<podId>/outbox/<wakeup>-<seq>-<name>.json
+```
+
+`<wakeup>` is the positive integer wake-up number, `<seq>` is a zero-padded
+increasing sequence such as `001`, `002`, and `<name>` is a filename-safe slug.
+Files are delivered serially in filename order. Each file contains a JSON
+object with a non-empty string `to` and a string `text`:
+
+```json
+{"to":"<Delivery Address>","text":"The reply text"}
+```
+
+`to` is the **Delivery Address** rendered by `{{reply_to}}` or carried on a
+standing Pod's Inbox checkbox line. The worker copies it verbatim; the
+deliverer parses it; core never reads it back. Its shape is:
+
+```text
+chat=<chat_id>;affinity=<root_id ?? item id>[;thread=<thread_id>]
+```
+
+An item with no `chat_id` renders the empty string, which is not a valid `to`
+and cannot be delivered. When `thread` is present, the deliverer can use it to
+reply in that thread.
+
+The Wrapper invokes the deliverer once per current-wake-up entry after the
+agent exits and before the Pod becomes idle. Reconcile retries entries for
+every non-active Pod, outside the registry lock. Each invocation receives the
+entry file's bytes verbatim on stdin, takes no arguments, runs with the Pod's
+project as cwd, and ignores stdout and stderr. It inherits the operator
+environment plus exactly these core-provided values:
+
+- `AGENTS_POD_POD_ID` — the owning Pod id;
+- `AGENTS_POD_WAKEUP_N` — the wake-up number parsed from the filename;
+- `AGENTS_POD_OUTBOX_ENTRY` — the entry filename, not its full path;
+- `AGENTS_POD_OUTBOX_UUID` — the 50-character lowercase hexadecimal idempotency
+  key derived from Pod id, wake-up number, and filename. Pass this same value
+  to the platform on every retry.
+
+One flush per Pod makes at most **10 delivery attempts** within a shared
+**10-second budget**, in filename order. The configured per-invocation timeout
+defaults to 10 seconds and is additionally capped by the flush's remaining
+budget. Entries left beyond either bound wait for a later pass.
+
+Exit `0` is the only acknowledgement: core deletes the entry and writes no
+completion marker. A non-zero exit, signal, spawn failure, or timeout leaves
+the file unchanged, writes one `cron.log` line, and lets the next pass retry
+with the same uuid. Delivery failure does not change the Wake-up outcome,
+failure streak, or notifications.
+
+An entry whose mtime is more than **one hour** old is not delivered: core
+renames it by appending `.dead`, logs one line, and keeps its contents
+unchanged. A malformed entry, a filename with no valid leading wake-up number,
+or a future-wake-up entry seen by a Wrapper is likewise dead-lettered on first
+sight. `*.dead` files are never scanned again or automatically removed. With
+no deliverer configured, the Wrapper flush is a no-op; each reconcile pass
+writes one `cron.log` line per Pod with waiting entries, and the same one-hour
+aging still applies (ADR 0025).
+
+### Role Instructions for replying agents
+
+Save the following as the replying Agent's instructions file and pass it to
+`agent add --instructions <file>`:
+
+```text
+When you reply to a Conversation, write one JSON file per reply into your own
+Pod's outbox at .agents/pods/$AGENTS_POD_POD_ID/outbox/ under the Pod project.
+Name each file $AGENTS_POD_WAKEUP_N-<seq>-<name>.json, using a zero-padded
+increasing <seq> (001, 002, ...) and a filename-safe <name>. Write
+{"to":"<Delivery Address>","text":"<reply>"}; copy the address verbatim from
+Reply-To in the Goal or from "to:" on the item's TASKS.md Inbox checkbox line.
+Do not write an entry when that address is empty.
+
+If you ask a question in a thread, reply in that same thread by reusing its
+Delivery Address, including the thread component. Ask at most two clarification
+rounds per uncertainty; then proceed on a stated assumption and record that
+assumption in HANDOFF.md.
+
+Core deletes an entry only after the deliverer exits 0. A failed delivery keeps
+the file, logs one line, and is retried on the next pass with the same uuid; an
+entry older than one hour is renamed with a .dead suffix and kept. Do not
+rename, delete, or rewrite pending or dead entries yourself.
+```
+
+## Storage
+
+```text
+~/.agents/pods/
+├── pods.json          # global pod registry: definitions + state, 0600
+├── agents.json        # named agents: adapter type, model, role instructions, 0600
+├── listeners.json     # listeners, bounds, claimed item ids, 0600
+├── sources.json       # named drain commands, committed cursors, lastDrainAt
+├── deliverer.json     # the single outbound delivery command
+├── inboxes/<id>/      # default listener inboxes; any dir/file may serve instead
+└── registry.lock      # short-lived registry write lock, 0600
+
+<project>/.agents/pods/
+└── <podId>/
+    ├── docs/          # HANDOFF.md · DECISIONS.md · TASKS.md — cross-wake work memory (ADR 0008)
+    ├── outbox/        # pending <wakeup>-<seq>-<name>.json replies and retained *.dead entries
+    ├── output.log     # every wake-up, append-only, wake-up delimited; trimmed idle by
+    │                   # reconcile: cap 10 MB, keep 2 MB, oldest sections dropped (ADR 0016), 0600
+    ├── heartbeat      # touched by the live wake-up's wrapper every 30s; mtime = last beat;
+    │                   # stale 3m = lost signal, live-but-stale 2 passes = wedged (ADR 0017), 0600
+    └── wakeups/<n>/   # per wake-up: events.jsonl, handoff snapshot, session file, resolved agent
+                       # snapshot (type, model, instructions hash — ADR 0012), outcome detail
+```
+
+Wake-ups inherit reconcile's (cron) environment unchanged except a
+propped `PATH`; `AGENTS_POD_PI_BIN`-style overrides resolve first; HOME is
+never scrubbed — CLI credentials live there (ssh-agent sockets do not
+survive cron: use HTTPS + credential helper for private repos). No per-pod
+env files (ADR 0015).
+
+agents-pod never reads or writes `.agents/cron/`
+([ADR 0004](docs/adr/0004-own-store.md)). Both plugins install side by side,
+and one crontab line can tick both:
+
+```cron
+* * * * * AGENTS_POD_PI_BIN=/absolute/path/to/pi agents-cron run-due --all && agents-pod reconcile >> "$HOME/.agents/pods/cron.log" 2>&1
+```
+
+## Non-goals
+
+- **No scheduling.** Starting work at a time is agents-cron's job (or a plain
+  crontab line calling `spawn`). Pods have no `nextRunAt`; a listener's
+  trigger is an event already recorded as data, never a time
+  ([ADR 0005](docs/adr/0005-boundary-with-agents-cron.md),
+  [ADR 0007](docs/adr/0007-listeners-standing-intake-without-a-daemon.md)).
+- **No daemon, no resident watcher.** A standing pod idles as a registry
+  record; a listener is materialized by the pass. An HTTP inbox would be a
+  daemon — rejected.
+- **No shared context.** Agents in a pod share documents, never windows;
+  isolation between agents is the product, not a limitation.
+- **No arbitrary shell supervision.** Wake-ups run agent CLIs through
+  adapters — Pi in `0.1.0`, Claude Code and Codex copied next — never raw
+  shell commands. An adapter that is not installed is refused at the surface
+  and again at launch, never approximated by running Pi in its name.
+- **No in-session orchestration.** Subagents inside a live Pi session are
+  [pi-subagents](https://pi.dev)' job; agents-pod supervises OS processes that
+  outlive any session.
+
+## Roadmap
+
+**Shipped in `0.1.0`.** spawn/claim/detach; the idle → wake → outcome loop;
+wrapper per wake-up (heartbeat, streaming, outcome recording); document store
+with the HANDOFF.md convention; named agents; reconcile (ghost records,
+orphans, idle → wake per the policy: backoff after `failed`/`lost`,
+consecutive-failure stop, manual `wake` as the human override); `logs
+--follow`; `cancel`; reboot reconciliation; progress signals with forced
+re-wake of live-but-progressless wake-ups; death notifications (notify layer
+adapted from agents-cron); listeners — inbox directory and JSONL file
+sources, per-item pods from templates, bound standing pods; wake admission
+honouring `--after` dependencies and the per-project cap; the Pi extension's
+two planes (ADR 0010) — `/pod` commands, `spawn_pod`, and `pod_handoff`.
+No default Wake-up timeout — liveness is heartbeat-based or it is nothing.
+
+**Shipped in `0.2.0`.** Chat as an intake and an outlet, both as operator
+commands rather than a daemon: sources (`source add|list|rm`) drained once per
+pass with a committed cursor and claim-before-cursor ordering; source-fed
+Listeners, batched `## Inbox` delivery to a standing pod, and `## Waiting` above
+it; outbox delivery (`deliver add|list|rm`) at wake-up exit and in every pass,
+with stable uuids, one-hour dead-lettering and retained `*.dead` entries; the
+Affinity Key and the `{{reply_to}}` Delivery Address riding the Goal or an Inbox
+line; `listener add --project` for tuning intake and workers apart. A wrapper's
+outcome is now recorded under the registry lock, so a concurrent pass or wrapper
+cannot overwrite it and force the same wake-up to run twice (ADR 0018).
+
+**Next.** The Claude Code and Codex adapters (`--type` is refused today, not
+silently downgraded). Default pod expiry and guarded fan-out — the
+load-bearing guardrails for standing pods, shipped only together with
+fan-out. Dashboard (adapted). Richer listener sources (git refs).
+Wake-policy sequences across roles.
+
+## License
+
+AGPL-3.0-or-later. See [LICENSE](LICENSE). Running agents-pod as a network
+service means the source of that service is available to its users.
+
+## Development
+
+The packaging story is copied from agents-cron: TypeScript shipped and
+executed as-is (erasable syntax only, `erasableSyntaxOnly` in tsconfig), a bin
+loader hook for files under `node_modules`, `npm run check` = typecheck +
+tests including a packed-tarball smoke test. `src/agents-store.ts` holds the
+named-agent definitions and the adapter vocabulary; the launch itself is
+`src/wrapper.ts` — in `0.1.0` it always runs Pi, and an unsupported `--type`
+is refused at the surface and at launch. The extension lives in
+`src/extension/` (one module per plane, plus `handoff.ts` for the document
+rendering), with `index.mjs` at the package root as Pi's entry so the footer
+label stays `agents-pod`.

package/bin/agents-pod.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point. Cron invokes this with a bare `node`, and the CLI itself is
+ * TypeScript, so register the stripping loader before importing it: Node will
+ * not strip types for files under `node_modules`, where an installed package
+ * lives. There is no build and no `dist/`; the published package ships the
+ * sources it runs.
+ */
+import { register } from "node:module";
+
+register("./ts-loader.mjs", import.meta.url);
+
+const { main } = await import("../src/cli.ts");
+
+process.exitCode = await main(process.argv.slice(2));

package/bin/ts-loader.mjs

@@ -0,0 +1,66 @@
+/**
+ * Type-stripping loader for this package's own `.ts` sources.
+ *
+ * Node strips types for `.ts` files everywhere except under `node_modules`,
+ * which is exactly where an installed package lives. Pi's extension loader
+ * does not care (it compiles TypeScript itself through jiti), but the CLI
+ * runs under a bare `node` from cron, so it needs this hook to run the same
+ * sources.
+ *
+ * Two rules keep this hook polite:
+ *
+ * - It only touches `.ts` files inside this package's own directory, resolved
+ *   through the symlink a package manager may put in front of `bin/`. Every
+ *   other specifier — including any other package's TypeScript — falls through
+ *   to Node and to whatever hooks the host process registered.
+ * - Stripping is `mode: "strip"`, so the sources must stay erasable;
+ *   `erasableSyntaxOnly` in `tsconfig.json` enforces that at typecheck time,
+ *   which is what keeps this loader from being a runtime surprise.
+ */
+import { readFile, realpath } from "node:fs/promises";
+import { stripTypeScriptTypes } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// This package's root directory as a `file:` URL with a trailing slash, so a
+// plain startsWith() decides whether a URL belongs to us.
+const packageRoot = `${pathToFileURL(
+  await realpath(fileURLToPath(new URL("../", import.meta.url))),
+).href}/`;
+
+/**
+ * `stripTypeScriptTypes` is experimental and warns on first use. The warning
+ * would come from this hook, so mute exactly that one and only while
+ * stripping — harnesses that spawn this CLI read its stderr, and a stray
+ * ExperimentalWarning reads like a failure. Everything else keeps Node's
+ * default treatment, and the override never outlives the call.
+ */
+function strip(source, url) {
+  const emitWarning = process.emitWarning;
+  try {
+    process.emitWarning = (warning, ...rest) =>
+      String(warning).includes("stripTypeScriptTypes")
+        ? undefined
+        : emitWarning.call(process, warning, ...rest);
+    return stripTypeScriptTypes(source, { mode: "strip", sourceUrl: url });
+  } finally {
+    process.emitWarning = emitWarning;
+  }
+}
+
+/** @type {import("node:module").LoadHook} */
+export async function load(url, context, nextLoad) {
+  if (
+    !url.startsWith("file:") ||
+    !url.endsWith(".ts") ||
+    !url.startsWith(packageRoot)
+  ) {
+    return nextLoad(url, context);
+  }
+
+  const source = await readFile(new URL(url), "utf8");
+  return {
+    format: "module",
+    source: strip(source, url),
+    shortCircuit: true,
+  };
+}

package/bin/wrapper.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Wrapper entry point: same loader trick as the CLI — the wrapper runs under a
+ * bare `node`, detached by the CLI, and its sources are TypeScript.
+ */
+import { register } from "node:module";
+
+register("./ts-loader.mjs", import.meta.url);
+
+const { runWrapper } = await import("../src/wrapper.ts");
+
+process.exit(await runWrapper(process.argv.slice(2)));

package/index.mjs

@@ -0,0 +1,11 @@
+/**
+ * Pi loads this file as the package's extension entry (package.json `pi`).
+ * The entry file must be named `index.*` at the package root: pi's compact
+ * label logic only drops the file path when the entry basename is `index`,
+ * otherwise the footer shows `agents-pod:extension.mjs` instead of just
+ * `agents-pod`. The planes themselves live in `src/extension/`; this file only
+ * re-exports them.
+ */
+import extension from "./src/extension/index.ts";
+
+export default extension;