agents-pod 0.0.0-stage → 0.2.0

package/src/extension/handoff.ts

@@ -0,0 +1,57 @@
+/**
+ * The Handoff document, rendered once and written once (ADR 0008, 0010).
+ *
+ * The only machine surface is the first line — `status: rotating` or
+ * `status: done` — because outcome classification greps it and the wrapper's
+ * `freshDeclaration()` refuses anything else. Everything after it is free
+ * markdown for the successor, so the sections are the ones CONTEXT.md names:
+ * goal restated, decisions and reasons, done, next, pointers.
+ */
+export type HandoffStatus = "rotating" | "done";
+
+export interface HandoffInput {
+  status: HandoffStatus;
+  /** The goal as this wake-up understood it, not as the registry spelled it. */
+  goal?: string;
+  /** Why, one line each — the part a successor cannot re-derive. */
+  decisions?: string[];
+  done?: string[];
+  next?: string[];
+  /** Files, commands, links worth opening first. */
+  pointers?: string[];
+}
+
+function bulletList(items: string[] | undefined): string[] {
+  const lines = (items ?? []).map((item) => item.trim()).filter((item) => item.length > 0);
+  return lines.map((item) => (item.startsWith("- ") ? item : `- ${item}`));
+}
+
+function section(heading: string, items: string[] | undefined, empty?: string): string[] {
+  const lines = bulletList(items);
+  if (lines.length === 0) return empty === undefined ? [] : [heading, "", empty, ""];
+  return [heading, "", ...lines, ""];
+}
+
+/**
+ * The hard line first, always: an agent that passes nothing but a status still
+ * produces a legal (if thin) handoff, and the successor is told so rather than
+ * waking up to a half-written template it cannot tell from a real one.
+ */
+export function renderHandoff(input: HandoffInput, now: Date = new Date()): string {
+  const lines = [`status: ${input.status}`, "", "# Handoff", "", `written: ${now.toISOString()}`, ""];
+  const goal = input.goal?.trim();
+  lines.push("## Goal", "", goal && goal.length > 0 ? goal : "(not restated)", "");
+  lines.push(...section("## Decisions and reasons", input.decisions));
+  lines.push(...section("## Done", input.done));
+  // Next is the one section a successor cannot live without, so it is always
+  // present — an empty one says so instead of disappearing.
+  lines.push(
+    ...section(
+      "## Next",
+      input.next,
+      input.status === "done" ? "(nothing — the goal is reached)" : "(unstated)",
+    ),
+  );
+  lines.push(...section("## Pointers", input.pointers));
+  return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+}

package/src/extension/index.ts

@@ -0,0 +1,34 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerManagementCommands, registerManagementTools } from "./management.ts";
+import { registerSelf } from "./self.ts";
+
+/**
+ * The gate is wrapper-injected env, not a flag and not a config file
+ * (ADR 0010, 0015): the wrapper sets `AGENTS_POD_POD_ID` for every wake-up,
+ * and nothing else on the machine does. Present → this process is an agent
+ * inside a pod → self plane only. Absent → an interactive session → the
+ * management plane.
+ */
+export const POD_ID_ENV = "AGENTS_POD_POD_ID";
+
+/**
+ * Set by whichever copy of this extension loads first in a process. `pi
+ * install` and a project-local install can both resolve here, and pi would
+ * then load two copies that fight over the same tool and command names;
+ * `Symbol.for` is shared across module instances, so the second copy sees the
+ * flag and stays inert no matter which path loaded first.
+ */
+const LOADED_FLAG = Symbol.for("agents-pod.extension.loaded");
+
+export default function (pi: ExtensionAPI): void {
+  const scope = globalThis as Record<symbol, boolean>;
+  if (scope[LOADED_FLAG]) return;
+  scope[LOADED_FLAG] = true;
+
+  if (process.env[POD_ID_ENV] !== undefined) {
+    registerSelf(pi);
+    return;
+  }
+  registerManagementCommands(pi);
+  registerManagementTools(pi);
+}

package/src/extension/management.ts

@@ -0,0 +1,149 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { main } from "../cli.ts";
+
+/**
+ * The management plane (ADR 0010): supervising other people's work — spawn,
+ * wake, cancel, listeners, and reading the registry. Registered only in an
+ * interactive session; the factory does not call this when pod env is present,
+ * so inside a pod these tools and commands do not exist at all (ADR 0005: an
+ * unregistered tool answers "no such tool" instead of inviting a workaround).
+ *
+ * Everything here is the CLI called in-process: one implementation, one set of
+ * exit codes, and no second opinion about what `spawn` means.
+ */
+
+export interface CliOutcome {
+  code: number;
+  lines: string[];
+}
+
+const LOG_TAIL_LINES = 200;
+
+function clip(lines: string[], limit = LOG_TAIL_LINES): string[] {
+  if (lines.length <= limit) return lines;
+  const dropped = lines.length - limit;
+  return [`… ${dropped} earlier line(s) omitted`, ...lines.slice(dropped)];
+}
+
+export async function runCli(argv: string[], cwd: string): Promise<CliOutcome> {
+  const lines: string[] = [];
+  const code = await main(argv, {
+    cwd,
+    stdout: (line) => lines.push(line),
+    stderr: (line) => lines.push(line),
+  });
+  return { code, lines };
+}
+
+function show(ctx: Pick<ExtensionContext, "ui">, outcome: CliOutcome): void {
+  const text = outcome.lines.length === 0 ? "(no output)" : clip(outcome.lines).join("\n");
+  ctx.ui.notify(text, outcome.code === 0 ? "info" : "error");
+}
+
+const POD_HELP = [
+  "/pod                     list pods (needs-human first)",
+  "/pod status <podId>      state, liveness, wake-up trail",
+  "/pod logs <podId>        the tail of the pod log",
+  "/pod spawn <goal…>       spawn a pod in this project",
+  "/pod wake <podId>        wake an idle pod now",
+  "/pod cancel <podId>      cancel a live wake-up",
+  "/pod agents              named agents",
+  "/pod listeners           listeners and their claims",
+].join("\n");
+
+/** The `/pod <action> …` command: the human's side of the management plane. */
+export function registerManagementCommands(pi: ExtensionAPI): void {
+  pi.registerCommand("pod", {
+    description: "Supervise pods — /pod help shows usage",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const words = args.trim().split(/\s+/).filter((word) => word.length > 0);
+      const action = words[0] ?? "list";
+      const rest = words.slice(1);
+      const cwd = ctx.cwd;
+
+      if (action === "help") {
+        ctx.ui.notify(POD_HELP, "info");
+        return;
+      }
+      const needsPodId = ["status", "logs", "wake", "cancel", "spawn"].includes(action);
+      if (needsPodId && rest.length === 0) {
+        ctx.ui.notify(POD_HELP, "info");
+        return;
+      }
+
+      const argv =
+        action === "spawn"
+          ? ["spawn", ...rest, "--project", cwd]
+          : action === "logs"
+            ? ["logs", ...rest]
+            : action === "agents"
+              ? ["agent", "list"]
+              : action === "listeners"
+                ? ["listener", "list"]
+                : [action, ...rest];
+      show(ctx, await runCli(argv, cwd));
+    },
+  });
+}
+
+/**
+ * `spawn_pod` is the whole fan-out surface (ADR 0010): the model can start a
+ * pod, and the guardrails that make fan-out safe — the per-project cap and the
+ * `--after` dependency — are the same ones the CLI enforces, because it is the
+ * CLI doing the enforcing.
+ */
+export function registerManagementTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "spawn_pod",
+    label: "Spawn Pod",
+    description:
+      "Spawn a pod: a standing unit that outlives this session and wakes fresh agents inside it, again and again, until its goal is done. Returns the pod id.",
+    promptSnippet: "Spawn a standing pod for long-running work",
+    promptGuidelines: [
+      "Use spawn_pod when the user wants work to keep going across sessions — a multi-day refactor, a standing watch, an inbox to serve — not for a task this session can finish.",
+      "spawn_pod returns a pod id; report that id back to the user so they can run /pod status on it.",
+      "A pod's agents share documents, not this conversation: put everything the successor must know into the goal text.",
+      "Do not spawn a second pod for the same goal while an existing pod covers it; check /pod list first.",
+    ],
+    parameters: Type.Object({
+      goal: Type.String({
+        description:
+          "The standing goal, in the user's terms. This is the only context a wake-up gets, so make it self-contained.",
+      }),
+      agent: Type.Optional(Type.String({ description: "Named agent id to wake; default is `default`." })),
+      model: Type.Optional(Type.String({ description: "Model id pinned for this pod's wake-ups." })),
+      after: Type.Optional(
+        Type.String({ description: "Pod id whose `done` releases this pod's first wake-up." }),
+      ),
+      cwd: Type.Optional(
+        Type.String({ description: "Working directory for wake-ups, relative to this project." }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) {
+      const argv = ["spawn", params.goal, "--project", ctx.cwd];
+      if (params.agent !== undefined) argv.push("--agent", params.agent);
+      if (params.model !== undefined) argv.push("--model", params.model);
+      if (params.after !== undefined) argv.push("--after", params.after);
+      if (params.cwd !== undefined) argv.push("--cwd", params.cwd);
+
+      const outcome = await runCli(argv, ctx.cwd);
+      const podId = outcome.lines.join("\n").trim();
+      if (outcome.code !== 0 || podId.length === 0) {
+        // Throwing is the error signal the model can act on (a bad agent id is
+        // a configuration error, exactly as the CLI reports it).
+        throw new Error(outcome.lines.join("\n") || `spawn failed with exit ${outcome.code}`);
+      }
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Spawned pod ${podId}. Wake-ups run detached; /pod status ${podId} shows progress.`,
+          },
+        ],
+        details: { podId },
+      };
+    },
+  });
+}

package/src/extension/self.ts

@@ -0,0 +1,80 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { renderHandoff, type HandoffStatus } from "./handoff.ts";
+
+/** The wrapper's gate var for the docs directory (ADR 0010, 0015). */
+export const DOCS_DIR_ENV = "AGENTS_POD_DOCS_DIR";
+
+const handoffSchema = Type.Object({
+  status: StringEnum(["rotating", "done"] as const, {
+    description:
+      "rotating: the goal is open, a successor continues. done: the goal is reached and the pod ends.",
+  }),
+  goal: Type.Optional(Type.String({ description: "The goal as this wake-up understood it." })),
+  decisions: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "One entry per decision, each with its reason.",
+    }),
+  ),
+  done: Type.Optional(Type.Array(Type.String(), { description: "What this wake-up finished." })),
+  next: Type.Optional(
+    Type.Array(Type.String(), { description: "What the next wake-up should do, in order." }),
+  ),
+  pointers: Type.Optional(
+    Type.Array(Type.String(), { description: "Files, commands, or links to open first." }),
+  ),
+});
+
+/**
+ * The self plane (ADR 0010): one tool, live only inside a pod. It can end the
+ * calling agent's own wake-up well; it can never create, destroy, or
+ * reconfigure work — the management plane is not registered here at all.
+ *
+ * The write is the whole guarantee: a fresh HANDOFF.md with a legal first line
+ * is what the wrapper's adjudication believes (ADR 0009), so this tool makes
+ * "write-then-exit" one call instead of a ritual the agent can skip.
+ */
+export function registerSelf(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "pod_handoff",
+    label: "Pod Handoff",
+    description:
+      "Write this wake-up's handoff to docs/HANDOFF.md and end the wake-up cleanly. Call it as the last action of every wake-up.",
+    promptSnippet: "Write the pod handoff and end this wake-up",
+    promptGuidelines: [
+      "Call pod_handoff as the last action of a wake-up, after the work is recorded in the documents.",
+      "Use pod_handoff with status done only when the pod's goal is reached; rotating means the goal is open and the next wake-up continues from the handoff.",
+      "An exit without a fresh pod_handoff is classified as failed — pod_handoff is the clean exit, not a summary you may skip.",
+    ],
+    parameters: handoffSchema,
+    async execute(_toolCallId, params) {
+      const docsDir = process.env[DOCS_DIR_ENV]?.trim();
+      if (!docsDir) {
+        // Escaping a pod by unsetting the env would make the tool lie; a hard
+        // error is the honest answer, and it never writes outside the pod.
+        throw new Error(`pod_handoff requires ${DOCS_DIR_ENV}: this session is not a pod wake-up`);
+      }
+      const file = join(docsDir, "HANDOFF.md");
+      // The schema admits exactly these two words; narrowing here keeps the
+      // hard line legal even if a provider reorders the enum.
+      const status: HandoffStatus = params.status === "done" ? "done" : "rotating";
+      const body = renderHandoff({ ...params, status });
+      // The agent may be editing HANDOFF.md in the same turn: one queue per file.
+      await withFileMutationQueue(file, () => writeFile(file, body));
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Handoff written to ${file} (status: ${status}). The wake-up ends here.`,
+          },
+        ],
+        details: { status, path: file },
+        terminate: true,
+      };
+    },
+  });
+}

package/src/inbox.ts

@@ -0,0 +1,221 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * An Inbox Item (ADR 0013): one positional id, the values a Pod Template
+ * binds, and the facts the two-pass stability guard compares. `{{path}}` is the
+ * item file's absolute path (directory inbox) or the JSONL path plus line.
+ *
+ * The optional routing fields are the platform's passengers (ADR 0026): they
+ * never join the id or the body, they only feed the Delivery Address.
+ */
+export interface InboxItem {
+  /** Directory: filename. File: line number. Source: the platform's id (ADRs 0013, 0024). */
+  id: string;
+  title: string;
+  body: string;
+  /** Empty for a Source item, which has no filesystem attachment (ADR 0024). */
+  path: string;
+  /** Inbox stability facts only; placeholders are zero for a Source item. */
+  mtimeMs: number;
+  size: number;
+  /** The chat a reply has to land in; without it there is no address. */
+  chatId?: string;
+  /** The root message: the Conversation's key, propagated by the platform. */
+  rootId?: string;
+  /** The topic thread, when the platform gave the message one. */
+  threadId?: string;
+}
+
+/**
+ * The Delivery Address (ADR 0026): the Conversation's key, the chat, and the
+ * optional thread as one opaque token — the string an outbox entry's `to`
+ * takes verbatim and a deliverer parses. Core never reads it back. An item with
+ * no chat has nowhere to be answered, so it renders the empty string rather
+ * than a token with a `chat=` hole; root and thread are passengers, never a
+ * substitute for the chat.
+ *
+ * The affinity is `root_id ?? item id`, exactly as ADR 0026 states it. For a
+ * directory or JSONL inbox the id is the item's position, not a platform
+ * message id; a Source (ADR 0024) is what makes the id the platform's, and
+ * therefore the fallback usable by a deliverer.
+ */
+export function deliveryAddress(
+  item: Pick<InboxItem, "id" | "chatId" | "rootId" | "threadId">,
+): string {
+  if (item.chatId === undefined) return "";
+  const affinity = item.rootId ?? item.id;
+  const thread = item.threadId === undefined ? "" : `;thread=${item.threadId}`;
+  return `chat=${item.chatId};affinity=${affinity}${thread}`;
+}
+
+/** A routing field is a non-empty, trimmed string; anything else is as ignored as an unknown key. */
+function routingField(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+/** A malformed JSONL line: skipped, unclaimed, warned on every pass (ADR 0013). */
+export interface BadInboxLine {
+  line: number;
+  reason: string;
+}
+
+export interface InboxScan {
+  items: InboxItem[];
+  bad: BadInboxLine[];
+  /** Set when the inbox itself cannot be read; the pass degrades, never throws. */
+  error?: string;
+}
+
+/** The body's first line is the default title (ADR 0013). */
+function firstLine(body: string): string {
+  return body.split("\n", 1)[0]!.trim();
+}
+
+/** Filename without extension: "notes.md" → "notes" (ADR 0013). */
+function titleFromFilename(name: string): string {
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(0, dot) : name;
+}
+
+/**
+ * A directory inbox holds one item per top-level non-dot regular file, any
+ * extension. Subdirectories (writers' WIP parking), dotfiles and symlinks are
+ * ignored — `isFile()` is false for a dirent that is a symlink.
+ */
+async function scanDirectory(dir: string): Promise<InboxScan> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    return { items: [], bad: [], error: (error as NodeJS.ErrnoException).code ?? "unreadable" };
+  }
+  const items: InboxItem[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || entry.name.startsWith(".")) continue;
+    const file = join(dir, entry.name);
+    const info = await stat(file).catch(() => undefined);
+    if (info === undefined || !info.isFile()) continue;
+    const body = await readFile(file, "utf8").catch(() => "");
+    items.push({
+      id: entry.name,
+      title: titleFromFilename(entry.name),
+      body,
+      path: file,
+      mtimeMs: info.mtimeMs,
+      size: info.size,
+    });
+  }
+  // Arrival order is the writer's priority; filename breaks mtime ties (ADR 0013).
+  items.sort((a, b) => a.mtimeMs - b.mtimeMs || a.id.localeCompare(b.id));
+  return { items, bad: [] };
+}
+
+/**
+ * A file inbox is JSONL only (ADR 0013): `body` is required, `title` optional,
+ * `chat_id`/`root_id`/`thread_id` are read as the item's routing fields
+ * (ADR 0026), and every other key is ignored. A line that does not parse, or
+ * carries no string body, is skipped and reported — never claimed, never fatal
+ * to the pass.
+ */
+async function scanJsonl(file: string): Promise<InboxScan> {
+  const info = await stat(file).catch(() => undefined);
+  if (info === undefined) return { items: [], bad: [], error: "ENOENT" };
+  const text = await readFile(file, "utf8").catch(() => undefined);
+  if (text === undefined) return { items: [], bad: [], error: "unreadable" };
+
+  const items: InboxItem[] = [];
+  const bad: BadInboxLine[] = [];
+  const lines = text.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index]!;
+    if (raw.trim() === "") continue; // a trailing newline is not an item
+    const line = index + 1;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      bad.push({ line, reason: "invalid JSON" });
+      continue;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      bad.push({ line, reason: "invalid JSON (not an object)" });
+      continue;
+    }
+    const record = parsed as {
+      body?: unknown;
+      title?: unknown;
+      chat_id?: unknown;
+      root_id?: unknown;
+      thread_id?: unknown;
+    };
+    if (typeof record.body !== "string") {
+      bad.push({ line, reason: "no body" });
+      continue;
+    }
+    const title =
+      typeof record.title === "string" && record.title.trim() !== ""
+        ? record.title
+        : firstLine(record.body);
+    const chatId = routingField(record.chat_id);
+    const rootId = routingField(record.root_id);
+    const threadId = routingField(record.thread_id);
+    items.push({
+      id: String(line),
+      title,
+      body: record.body,
+      path: `${file}#${line}`,
+      mtimeMs: info.mtimeMs,
+      size: info.size,
+      ...(chatId === undefined ? {} : { chatId }),
+      ...(rootId === undefined ? {} : { rootId }),
+      ...(threadId === undefined ? {} : { threadId }),
+    });
+  }
+  return { items, bad };
+}
+
+/** Shape follows the path's own `stat`: a directory or a JSONL file (ADR 0013). */
+export async function scanInbox(inbox: string): Promise<InboxScan> {
+  const info = await stat(inbox).catch(() => undefined);
+  if (info === undefined) return { items: [], bad: [], error: "ENOENT" };
+  return info.isDirectory() ? scanDirectory(inbox) : scanJsonl(inbox);
+}
+
+/**
+ * The five template placeholders (ADR 0013, amended by ADR 0026), each one a
+ * renderer: adding a sixth is one row, not a set plus two casts.
+ */
+const PLACEHOLDERS: Record<string, (item: InboxItem) => string> = {
+  id: (item) => item.id,
+  title: (item) => item.title,
+  body: (item) => item.body,
+  path: (item) => item.path,
+  // The address is derived, not a field: an item without routing fields
+  // renders empty, so a template stays valid for both kinds of item.
+  reply_to: deliveryAddress,
+};
+
+/**
+ * Render a Pod Template against one item. An unknown `{{...}}` is a
+ * configuration error: the caller fails this item's materialization, keeps the
+ * claim (already written), warns to cron.log, and the pass carries on.
+ */
+export function renderTemplate(
+  template: string,
+  item: InboxItem,
+): { goal: string } | { error: string } {
+  const unknown: string[] = [];
+  const goal = template.replace(/\{\{([^{}]*)\}\}/g, (whole: string, raw: string) => {
+    const name = raw.trim();
+    const render = PLACEHOLDERS[name];
+    if (render === undefined) {
+      unknown.push(name);
+      return whole;
+    }
+    return render(item);
+  });
+  if (unknown.length > 0) return { error: `unknown placeholder {{${unknown[0]}}}` };
+  return { goal };
+}

package/src/listeners.ts

@@ -0,0 +1,84 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { listenersFile } from "./paths.ts";
+
+/**
+ * A Listener is a registry record, never a process (ADR 0007): an inbox, an
+ * optional match rule, one target, and a bound on concurrent wake-ups. The pass
+ * scans it; nothing ever runs on its behalf between passes.
+ */
+export type ListenerMode = "template" | "pod";
+
+/**
+ * A consumed item, by position for an inbox or platform id for a Source
+ * (ADRs 0013, 0024): the claim namespace is the origin, so `inbox` + `item` is
+ * the key across listeners. `spawnedPodId` is what the template materialized;
+ * `blocked` is a reason materialization will not happen
+ * (a configuration error, or an item that vanished). `appended` is ADR 0014's
+ * one boolean for a bound standing pod: the block is in the pod's `## Inbox`.
+ * Beyond that the document is the truth — there is no per-item lifecycle.
+ */
+export interface ClaimRecord {
+  inbox: string;
+  item: string;
+  /** Source claims retain the current and previous successful drain (ADR 0024). */
+  claimedAt?: number;
+  spawnedPodId?: string;
+  blocked?: string;
+  appended?: boolean;
+}
+
+/** The two-pass stability guard's memory: last scan's mtime and size (ADR 0013). */
+export interface SeenFact {
+  item: string;
+  mtimeMs: number;
+  size: number;
+}
+
+export interface ListenerRecord {
+  id: string;
+  /** Exactly one origin: an absolute inbox path or a Source name (ADR 0024). */
+  inbox?: string;
+  source?: string;
+  /** P0's rule: a plain substring; absent means every item matches. */
+  match?: string;
+  mode: ListenerMode;
+  /** Template mode: the goal template file. */
+  template?: string;
+  /** Template mode: materialize under this project instead of the tick's cwd (ADR 0007). */
+  project?: string;
+  /** Pod mode: the standing pod whose `## Inbox` the items join (ADR 0014). */
+  podId?: string;
+  maxConcurrent: number;
+  claimed: ClaimRecord[];
+  seen: SeenFact[];
+}
+
+export function newListenerId(): string {
+  return `listener-${randomBytes(3).toString("hex")}`;
+}
+
+/** The claim key is inbox + position, never the listener (ADR 0013). */
+export function claimKey(inbox: string, item: string): string {
+  return `${inbox}\u0000${item}`;
+}
+
+export async function readListeners(): Promise<ListenerRecord[]> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(listenersFile(), "utf8"));
+    return Array.isArray(parsed) ? (parsed as ListenerRecord[]) : [];
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+/** Atomic write, one unique temp name per writer (the pods.json rule). */
+export async function writeListeners(listeners: ListenerRecord[]): Promise<void> {
+  const file = listenersFile();
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(listeners, null, 2)}\n`);
+  await rename(tmp, file);
+}