agents-pod 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,344 @@
-# 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.1.0` — first release.** The CLI runs (spawn, wake, cancel,
+> logs, reconcile, listeners, notifications) and the Pi extension ships its two
+> planes. 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. Nothing
+crosses wake-ups except documents — agents in a pod share its documents,
+never one another's windows. 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> [--pod <podId> | --template <file>]
+                         [--match <substr>] [--max-concurrent <n>]
+agents-pod listener list [--json]
+agents-pod listener rm <listenerId>
+```
+
+`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: 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 or wake the bound standing
+pod — bounded by `--max-concurrent` and the per-project pod cap.
+
+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; malformed lines skipped with a warning). Item ids are
+filenames or line numbers — never content — claimed per inbox; templates
+bind `{{id}}` `{{title}}` `{{body}}` `{{path}}` (ADR 0013).
+
+For a standing pod, claimed items land in its `TASKS.md` `## Inbox`
+section — 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 (ADR 0014).
+
+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).
+
+## 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
+├── 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 — the only cross-wake state (ADR 0008)
+    ├── 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 timeout anywhere — liveness is heartbeat-based or it is nothing.
+
+**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;

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "agents-pod",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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",
+  "bin": {
+    "agents-pod": "bin/agents-pod.mjs"
+  },
+  "pi": {
+    "extensions": [
+      "./index.mjs"
+    ]
+  },
+  "files": [
+    "bin",
+    "src",
+    "index.mjs",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test \"tests/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^1.5.0",
+    "@earendil-works/pi-coding-agent": "^1.5.0",
+    "@types/node": "^24.0.0",
+    "typebox": "^1.4.3",
+    "typescript": "^5.9.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}

package/src/agents-store.ts

@@ -0,0 +1,88 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { agentsFile } from "./paths.ts";
+
+/** Adapter types are types, not agents: every wake-up names an agent (ADR 0012). */
+export type AgentType = "pi" | "claude" | "codex";
+
+/**
+ * A definition is five fields and nothing else in P0 (ADR 0012): id, type,
+ * optional model, inline role instructions, optional display name. Role
+ * instructions are text, never a live path — a standing pod must not starve
+ * because a file moved.
+ */
+export interface AgentDefinition {
+  id: string;
+  type: AgentType;
+  model?: string;
+  instructions: string;
+  displayName?: string;
+}
+
+/**
+ * `default` is a pre-seeded ordinary row, not a reserved word (ADR 0012): the
+ * user may edit or delete it, and a missing row falls back to this built-in.
+ */
+export const BUILTIN_DEFAULT: AgentDefinition = {
+  id: "default",
+  type: "pi",
+  instructions: "",
+};
+
+export function isAgentType(value: string): value is AgentType {
+  return value === "pi" || value === "claude" || value === "codex";
+}
+
+/**
+ * Adapter coverage is Pi-only in 0.1.0, and the type is a promise the wrapper
+ * has to keep: it launches one command line — pi's `--print --mode json
+ * --session` — whatever the definition says. Accepting `--type claude` and
+ * then running pi would be a silent wrong agent, so the type is refused at the
+ * surface and again at launch, where a store written by an older build or by
+ * hand cannot slip through (ADR 0023).
+ */
+export const UNSUPPORTED_AGENT_TYPE =
+  "0.1.0 wakes pods with pi only: claude and codex adapters land in a later release";
+
+export function agentTypeRefusal(type: AgentType): string | undefined {
+  return type === "pi" ? undefined : UNSUPPORTED_AGENT_TYPE;
+}
+
+/**
+ * The one resolution rule (ADR 0012): an exact id match in the store; a
+ * missing `default` falls back to the built-in; anything else is unknown.
+ */
+export function resolveAgentDefinition(
+  agents: AgentDefinition[],
+  id: string,
+): AgentDefinition | undefined {
+  const found = agents.find((agent) => agent.id === id);
+  if (found) return found;
+  return id === BUILTIN_DEFAULT.id ? { ...BUILTIN_DEFAULT } : undefined;
+}
+
+export async function readAgents(): Promise<AgentDefinition[]> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(agentsFile(), "utf8"));
+    return Array.isArray(parsed) ? (parsed as AgentDefinition[]) : [];
+  } catch (error) {
+    // A store that has never been written is seeded here — the init-time
+    // pre-seed, observable without a separate init command (ADR 0012).
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      const seeded = [{ ...BUILTIN_DEFAULT }];
+      await writeAgents(seeded);
+      return seeded;
+    }
+    throw error;
+  }
+}
+
+/** Atomic 0600 write: a crash mid-write never leaves a half-written store. */
+export async function writeAgents(agents: AgentDefinition[]): Promise<void> {
+  const file = agentsFile();
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(agents, null, 2)}\n`, { mode: 0o600 });
+  await rename(tmp, file);
+}