agents-pod 0.1.0 → 0.3.0

package/src/doctor.ts

@@ -0,0 +1,551 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access, readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { readListeners, type ListenerRecord } from "./listeners.ts";
+import { readLock } from "./locks.ts";
+import { loadNotifyConfig } from "./notify/config.ts";
+import type { NotificationsConfig } from "./notify/types.ts";
+import { readDeliverer, type DelivererRecord } from "./outbox.ts";
+import {
+  lastPassFile,
+  notifyConfigFile,
+  reconcileLockPath,
+  storeRoot,
+} from "./paths.ts";
+import { readPods, type PodRecord } from "./registry.ts";
+import { readSources, type SourceRecord } from "./sources.ts";
+
+/**
+ * Doctor is a read-only Health Report over the store (ADR 0027): what is
+ * missing for a conversation to reach a Pod and a reply to leave one, and the
+ * one command that fixes each gap. It reads records only — never a platform,
+ * never a credential — because ADRs 0024/0025 keep both inside the operator's
+ * commands. It prints; it never writes.
+ */
+export type DoctorMark = "ok" | "bad" | "note";
+
+export interface DoctorLine {
+  mark: DoctorMark;
+  text: string;
+  /** The one command that fixes a `bad` line (ADR 0027). */
+  detail?: string[];
+}
+
+export interface DoctorSection {
+  title: string;
+  lines: DoctorLine[];
+}
+
+export interface DoctorReport {
+  store: string;
+  sections: DoctorSection[];
+  /** Present when nothing is configured: the ordered first run (ADR 0027). */
+  recipe: string[];
+  healthy: boolean;
+}
+
+export interface DoctorOptions {
+  /** `--probe`: run each operator command's `--check` (ADR 0027). Never default. */
+  probe?: boolean;
+  cwd?: string;
+  /** The environment password probes read; defaults to the process's own. */
+  env?: Record<string, string | undefined>;
+  now?: number;
+}
+
+/** A probe's own budget: the delivery and drain budget, unchanged (ADR 0021). */
+const PROBE_TIMEOUT_MS = 10_000;
+/** A command that does not implement `--check` says so with this code (ADR 0027). */
+const NO_SELF_CHECK = 3;
+const PROBE_OUTPUT_CAP = 8 * 1024;
+const PROBE_LINES = 6;
+/** A pass lock older than this is what the next pass steals (ADR 0018). */
+const LOCK_STALE_MS = 5 * 60_000;
+
+export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport> {
+  const now = options.now ?? Date.now();
+  const env = options.env ?? process.env;
+  const root = storeRoot();
+
+  const registry = await readRegistry();
+  const sources = await readSources().catch(() => [] as SourceRecord[]);
+  const listeners = await readListeners();
+  const deliverer = await readDeliverer();
+  const warnings: string[] = [];
+  const notify = await loadNotifyConfig(undefined, (message) => warnings.push(message));
+  const lastPass = await readLastPass();
+
+  const firstRun =
+    sources.length === 0 && deliverer === undefined && notify.channels.length === 0;
+  if (firstRun) {
+    return { store: root, sections: [], recipe: recipeFor(sources, listeners, deliverer, notify, lastPass), healthy: false };
+  }
+
+  const sections: DoctorSection[] = [];
+  const storeLines: DoctorLine[] = [];
+  if (registry.error !== undefined) {
+    storeLines.push({ mark: "bad", text: `pods.json is unreadable: ${registry.error}` });
+  } else {
+    const active = registry.pods.filter((pod) => pod.state === "active").length;
+    storeLines.push({ mark: "ok", text: `${registry.pods.length} pods, ${active} active` });
+  }
+  const lock = await readLock(reconcileLockPath());
+  if (lock !== undefined) {
+    storeLines.push(
+      now - lock.startedAt > LOCK_STALE_MS
+        ? { mark: "note", text: `a pass lock has been held for ${age(now - lock.startedAt)} (the next pass steals it)` }
+        : { mark: "note", text: `a pass is running (pid ${lock.pid})` },
+    );
+  }
+  sections.push({ title: "store", lines: storeLines });
+
+  sections.push({ title: "pass", lines: await passLines(lastPass, now, sources, listeners, registry.pods) });
+  sections.push({ title: "intake", lines: await intakeLines(sources, listeners, now) });
+  sections.push({ title: "listeners", lines: await listenerLines(listeners, sources, registry.pods) });
+  sections.push({ title: "outbound", lines: await outboundLines(deliverer, registry.pods) });
+  sections.push({ title: "notify", lines: notifyLines(notify, warnings, env) });
+
+  if (options.probe) {
+    sections.push({
+      title: "checks",
+      lines: [
+        ...(await probeAll(sources, listeners, deliverer, options.cwd ?? process.cwd(), env)),
+      ],
+    });
+  }
+
+  const recipe = firstRun
+    ? []
+    : recipeFor(sources, listeners, deliverer, notify, lastPass);
+  const healthy = sections.every((section) => section.lines.every((line) => line.mark !== "bad"));
+  return { store: root, sections, recipe, healthy };
+}
+
+async function readRegistry(): Promise<{ pods: PodRecord[]; error?: string }> {
+  try {
+    return { pods: await readPods() };
+  } catch (error) {
+    return { pods: [], error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * The pass marker (ADR 0027) exists because "cron is not installed" and "cron
+ * runs and finds nothing" are the same silence without it.
+ */
+async function readLastPass(): Promise<number | undefined> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(lastPassFile(), "utf8"));
+    const at = (parsed as { at?: unknown }).at;
+    return typeof at === "number" ? at : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function passLines(
+  lastPass: number | undefined,
+  now: number,
+  sources: SourceRecord[],
+  listeners: ListenerRecord[],
+  pods: PodRecord[],
+): Promise<DoctorLine[]> {
+  const expected = sources.length > 0 || listeners.length > 0 || pods.length > 0;
+  if (lastPass === undefined) {
+    return [
+      expected
+        ? {
+            mark: "bad",
+            text: "no pass has ever run — nothing is woken, no Source is drained",
+            detail: ["next: crontab -e", "      * * * * * cd <project> && agents-pod reconcile >> ~/.agents/pods/cron.log 2>&1"],
+          }
+        : { mark: "note", text: "no pass has run yet" },
+    ];
+  }
+  return [{ mark: "ok", text: `last pass ${age(now - lastPass)} ago` }];
+}
+
+async function intakeLines(
+  sources: SourceRecord[],
+  listeners: ListenerRecord[],
+  now: number,
+): Promise<DoctorLine[]> {
+  const lines: DoctorLine[] = [];
+  const consumed = new Set(listeners.flatMap((listener) => listener.source ?? []));
+  for (const source of sources) {
+    const consumer = consumed.has(source.name);
+    const executable = await isExecutable(source.cmd);
+    if (!executable) {
+      lines.push({
+        mark: "bad",
+        text: `source ${source.name}: ${source.cmd} is not an executable file`,
+        detail: [
+          `next: agents-pod source rm ${source.name}`,
+          `      agents-pod source add ${source.name} --cmd <path> --timeout ${source.timeoutMs / 1000}`,
+        ],
+      });
+      continue;
+    }
+    const drained =
+      source.lastDrainAt === undefined
+        ? "never drained successfully"
+        : `last success ${age(now - source.lastDrainAt)} ago, ${
+            source.lastDrainItems === undefined
+              ? "yield not recorded"
+              : `${source.lastDrainItems} items`
+          }`;
+    const cursor = source.cursor === undefined ? "no cursor" : `cursor ${source.cursor}`;
+    // A Source that fails every pass is the loudest thing a report can say; the
+    // cursor never moving is otherwise indistinguishable from a quiet chat.
+    if (source.lastError !== undefined) {
+      const failed = source.lastFailureAt === undefined ? "the last drain" : `the last drain (${age(now - source.lastFailureAt)} ago)`;
+      lines.push({
+        mark: "bad",
+        text: `source ${source.name}: ${failed} failed — ${source.lastError}`,
+        detail: [
+          `      ${drained}; ${cursor} (neither moves until a drain succeeds)`,
+          "      run: agents-pod doctor --probe",
+        ],
+      });
+      continue;
+    }
+    if (!consumer) {
+      lines.push({
+        mark: "note",
+        text: `source ${source.name}: ${drained}, ${cursor} — no listener consumes it, so no pass runs it`,
+        detail: ["next: agents-pod listener add --source " + source.name + " --template <file> [--project <dir>]"],
+      });
+      continue;
+    }
+    // Zero items is a quiet chat, not a failure — but it is the exact shape of
+    // "the pull is pointed at nothing", so it never hides (ADR 0027).
+    if (source.lastDrainItems === 0) {
+      lines.push({
+        mark: "note",
+        text: `source ${source.name}: ${drained} — nothing arrives; the command runs, the conversation does not reach it`,
+        detail: [`      ${cursor}; run: agents-pod doctor --probe`],
+      });
+      continue;
+    }
+    lines.push({ mark: "ok", text: `source ${source.name}: ${source.cmd}` });
+    lines.push({ mark: "ok", text: `  ${drained}, ${cursor}` });
+  }
+  if (sources.length === 0) {
+    lines.push({
+      mark: "note",
+      text: "no Source: nothing from outside this machine becomes an Inbox Item",
+      detail: ['next: agents-pod source add <name> --cmd <path> (README "Writing a Source drain")'],
+    });
+  }
+  return lines;
+}
+
+async function listenerLines(
+  listeners: ListenerRecord[],
+  sources: SourceRecord[],
+  pods: PodRecord[],
+): Promise<DoctorLine[]> {
+  const lines: DoctorLine[] = [];
+  for (const listener of listeners) {
+    const problems: string[] = [];
+    const origin =
+      listener.source !== undefined
+        ? `source ${listener.source}`
+        : `inbox ${listener.inbox ?? "(none)"}`;
+    if (listener.source !== undefined && !sources.some((source) => source.name === listener.source)) {
+      problems.push(`its Source ${listener.source} is not registered`);
+    }
+    if (listener.source === undefined && !(await exists(listener.inbox ?? ""))) {
+      problems.push(`its inbox ${listener.inbox ?? "(none)"} does not exist`);
+    }
+    if (listener.mode === "template") {
+      if (!(await exists(listener.template ?? ""))) {
+        problems.push(`its template ${listener.template ?? "(none)"} does not exist`);
+      }
+      if (listener.project !== undefined && !(await exists(listener.project))) {
+        problems.push(`its project ${listener.project} does not exist`);
+      }
+    } else if (!pods.some((pod) => pod.id === listener.podId)) {
+      problems.push(`its Pod ${listener.podId ?? "(none)"} is not in the registry`);
+    }
+    if (problems.length > 0) {
+      lines.push({
+        mark: "bad",
+        text: `${listener.id}: ${problems.join("; ")}`,
+        detail: [`next: agents-pod listener rm ${listener.id}`, "      then add it again with a path that exists"],
+      });
+      continue;
+    }
+    const target =
+      listener.mode === "template" ? `template ${listener.template ?? "(none)"}` : `pod ${listener.podId}`;
+    const project = listener.project !== undefined ? ` → ${listener.project}` : "";
+    lines.push({ mark: "ok", text: `${listener.id}: ${origin} → ${target}${project}` });
+  }
+  if (listeners.length === 0) {
+    lines.push({
+      mark: "note",
+      text: "no Listener: a Source is drained only for a Listener that consumes it",
+      detail: ["next: agents-pod listener add --source <name> --template <file> [--project <dir>]"],
+    });
+  }
+  return lines;
+}
+
+async function outboundLines(deliverer: DelivererRecord | undefined, pods: PodRecord[]): Promise<DoctorLine[]> {
+  const lines: DoctorLine[] = [];
+  const { pending, dead } = await outboxFacts(pods);
+  if (deliverer === undefined) {
+    lines.push({
+      mark: "bad",
+      text:
+        pending > 0
+          ? `no deliverer: ${pending} entries in Pod outboxes are never sent`
+          : "no deliverer: a Pod's outbox is never sent",
+      detail: [
+        "next: agents-pod deliver add <name> --cmd <path> --timeout <s>",
+        "      the command owns the platform credentials (ADR 0025)",
+      ],
+    });
+  } else if (!(await isExecutable(deliverer.cmd))) {
+    lines.push({
+      mark: "bad",
+      text: `deliverer ${deliverer.name}: ${deliverer.cmd} is not an executable file`,
+      detail: [`next: agents-pod deliver rm ${deliverer.name}, then deliver add with a real path`],
+    });
+  } else {
+    lines.push({ mark: "ok", text: `deliverer ${deliverer.name}: ${deliverer.cmd}` });
+  }
+  if (pending > 0) lines.push({ mark: "note", text: `${pending} entries waiting in Pod outboxes` });
+  if (dead > 0) {
+    lines.push({
+      mark: "note",
+      text: `${dead} dead entries retained (older than an hour or malformed; kept, never retried)`,
+    });
+  }
+  return lines;
+}
+
+/** Outbox entries are facts of the Pod's workspace, not of the registry (ADR 0025). */
+async function outboxFacts(pods: PodRecord[]): Promise<{ pending: number; dead: number }> {
+  let pending = 0;
+  let dead = 0;
+  for (const pod of pods) {
+    const dir = join(pod.project, ".agents", "pods", pod.id, "outbox");
+    let names: string[];
+    try {
+      names = await readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (name.endsWith(".dead")) dead += 1;
+      else if (name.endsWith(".json")) pending += 1;
+    }
+  }
+  return { pending, dead };
+}
+
+function notifyLines(
+  notify: NotificationsConfig,
+  warnings: string[],
+  env: Record<string, string | undefined>,
+): DoctorLine[] {
+  const lines: DoctorLine[] = warnings.map((warning) => ({ mark: "bad" as const, text: warning }));
+  if (notify.channels.length === 0) {
+    lines.push({
+      mark: "note",
+      text: "no notification channels: parks and dones stay silent",
+      detail: [`next: add channels to ${notifyConfigFile()} (README "Notifications")`],
+    });
+    return lines;
+  }
+  lines.push({ mark: "ok", text: `${notify.channels.length} channels (on: ${notify.on})` });
+  if (notify.on === "never") {
+    lines.push({ mark: "note", text: "notifications.on is never: every channel is ignored" });
+  }
+  for (const channel of notify.channels) {
+    if (channel.type !== "email" || channel.user === undefined) continue;
+    const passwordEnv = channel.passwordEnv ?? "AGENTS_POD_SMTP_PASSWORD";
+    if (!env[passwordEnv]) {
+      lines.push({
+        mark: "bad",
+        text: `channel ${channel.id}: ${passwordEnv} is not set in this environment`,
+        detail: ["      an authenticated SMTP send will fail; core reads no credentials (ADR 0021)"],
+      });
+    }
+  }
+  return lines;
+}
+
+/**
+ * `--check` is the only way core can learn about a credential it must not hold
+ * (ADR 0027): exit 0 healthy, exit 3 no self-check, anything else unhealthy
+ * with the command's own words quoted.
+ */
+async function probeAll(
+  sources: SourceRecord[],
+  listeners: ListenerRecord[],
+  deliverer: DelivererRecord | undefined,
+  cwd: string,
+  env: Record<string, string | undefined>,
+): Promise<DoctorLine[]> {
+  const lines: DoctorLine[] = [];
+  const consumed = new Set(listeners.flatMap((listener) => listener.source ?? []));
+  for (const source of sources) {
+    lines.push(
+      ...(await trace(`source ${source.name}`, source.cmd, {
+        ...env,
+        AGENTS_POD_SOURCE_ID: source.name,
+        AGENTS_POD_CURSOR: source.cursor ?? "",
+      }, cwd)),
+    );
+    if (!consumed.has(source.name)) {
+      lines.push({ mark: "note", text: `source ${source.name}: no listener consumes it, so no pass runs it` });
+    }
+  }
+  if (deliverer !== undefined) {
+    lines.push(...(await trace(`deliverer ${deliverer.name}`, deliverer.cmd, env, cwd)));
+  }
+  if (lines.length === 0) {
+    lines.push({ mark: "note", text: "nothing to probe: no Source and no deliverer configured" });
+  }
+  return lines;
+}
+
+async function trace(
+  label: string,
+  cmd: string,
+  env: Record<string, string | undefined>,
+  cwd: string,
+): Promise<DoctorLine[]> {
+  if (!(await isExecutable(cmd))) {
+    return [{ mark: "bad", text: `${label}: ${cmd} is not an executable file` }];
+  }
+  const { code, signal, text } = await runCheck(cmd, env, cwd);
+  const quoted = text
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "")
+    .slice(0, PROBE_LINES)
+    .map((line) => `      ${line}`);
+  if (code === 0) {
+    return [{ mark: "ok", text: `${label}: self-check passed`, ...(quoted.length ? { detail: quoted } : {}) }];
+  }
+  if (code === NO_SELF_CHECK) {
+    return [
+      {
+        mark: "note",
+        text: `${label}: no self-check (exit ${NO_SELF_CHECK}) — core cannot verify anything it owns`,
+        detail: ["      add `--check` to the command (exit 0 healthy, 3 unsupported) to have it verified here"],
+      },
+    ];
+  }
+  const why = signal !== null ? `terminated by ${signal}` : `exit ${code ?? "unknown"}`;
+  return [
+    { mark: "bad", text: `${label}: self-check failed (${why})`, detail: quoted.length ? quoted : undefined },
+  ];
+}
+
+function runCheck(
+  cmd: string,
+  env: Record<string, string | undefined>,
+  cwd: string,
+): Promise<{ code: number | null; signal: NodeJS.Signals | null; text: string }> {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, ["--check"], { cwd, env: env as NodeJS.ProcessEnv, detached: true });
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    const collect = (chunk: Buffer): void => {
+      if (bytes >= PROBE_OUTPUT_CAP) return;
+      bytes += chunk.length;
+      chunks.push(chunk);
+    };
+    const timer = setTimeout(() => {
+      try {
+        process.kill(-child.pid!, "SIGKILL");
+      } catch {
+        child.kill("SIGKILL");
+      }
+    }, PROBE_TIMEOUT_MS);
+    child.stdout.on("data", collect);
+    child.stderr.on("data", collect);
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({ code: null, signal: null, text: error.message });
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      resolve({ code, signal, text: Buffer.concat(chunks).toString("utf8") });
+    });
+  });
+}
+
+/**
+ * The first run, in order (ADR 0027): each line is one command, and the last
+ * one is the report that says every line is `✓`.
+ */
+function recipeFor(
+  sources: SourceRecord[],
+  listeners: ListenerRecord[],
+  deliverer: DelivererRecord | undefined,
+  notify: NotificationsConfig,
+  lastPass: number | undefined,
+): string[] {
+  const steps: string[][] = [];
+  if (sources.length === 0) {
+    steps.push([
+      'write a Source command: one JSONL item per message, then {"cursor":"…"}',
+      '   README "Writing a Source drain"; a worked Feishu pair: examples/feishu/',
+      "   agents-pod source add <name> --cmd <path> --timeout <s>",
+    ]);
+  }
+  if (listeners.length === 0) {
+    steps.push(["agents-pod listener add --source <name> --template <file> [--project <dir>]"]);
+  }
+  if (deliverer === undefined) {
+    steps.push(["agents-pod deliver add <name> --cmd <path> --timeout <s>"]);
+  }
+  if (notify.channels.length === 0) {
+    steps.push([`add notification channels to ${notifyConfigFile()} (README "Notifications")`]);
+  }
+  if (lastPass === undefined) {
+    steps.push([
+      "crontab: * * * * * cd <project> && agents-pod reconcile >> ~/.agents/pods/cron.log 2>&1",
+    ]);
+  }
+  steps.push(["agents-pod doctor --probe — until every line is ✓"]);
+  return steps.flatMap((lines, index) =>
+    lines.map((line, position) => (position === 0 ? `${index + 1}. ${line}` : `   ${line}`)),
+  );
+}
+
+async function exists(path: string): Promise<boolean> {
+  if (!path) return false;
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isExecutable(path: string): Promise<boolean> {
+  if (!path) return false;
+  try {
+    const info = await stat(path);
+    if (!info.isFile()) return false;
+    await access(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Ages are read at a glance: seconds, minutes, hours, days, never an epoch. */
+function age(ms: number): string {
+  if (ms < 60_000) return `${Math.max(0, Math.round(ms / 1000))}s`;
+  if (ms < 3_600_000) return `${Math.round(ms / 60_000)}m`;
+  if (ms < 86_400_000) return `${Math.round(ms / 3_600_000)}h`;
+  return `${Math.round(ms / 86_400_000)}d`;
+}

package/src/inbox.ts

@@ -1,18 +1,58 @@
 import { readFile, readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 /**
- * An Inbox Item (ADR 0013): one positional id, the four values a Pod Template
+ * 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: the filename. File: the line number. Never content (ADR 0013). */
+  /** 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). */
@@ -74,8 +114,10 @@ async function scanDirectory(dir: string): Promise<InboxScan> {
 
 /**
  * A file inbox is JSONL only (ADR 0013): `body` is required, `title` optional,
- * extra keys ignored. A line that does not parse, or carries no string body, is
- * skipped and reported — never claimed, never fatal to the pass.
+ * `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);
@@ -101,7 +143,13 @@ async function scanJsonl(file: string): Promise<InboxScan> {
       bad.push({ line, reason: "invalid JSON (not an object)" });
       continue;
     }
-    const record = parsed as { body?: unknown; title?: unknown };
+    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;
@@ -110,6 +158,9 @@ async function scanJsonl(file: string): Promise<InboxScan> {
       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,
@@ -117,6 +168,9 @@ async function scanJsonl(file: string): Promise<InboxScan> {
       path: `${file}#${line}`,
       mtimeMs: info.mtimeMs,
       size: info.size,
+      ...(chatId === undefined ? {} : { chatId }),
+      ...(rootId === undefined ? {} : { rootId }),
+      ...(threadId === undefined ? {} : { threadId }),
     });
   }
   return { items, bad };
@@ -129,8 +183,19 @@ export async function scanInbox(inbox: string): Promise<InboxScan> {
   return info.isDirectory() ? scanDirectory(inbox) : scanJsonl(inbox);
 }
 
-/** The exactly-four template placeholders (ADR 0013). */
-const PLACEHOLDERS = new Set(["id", "title", "body", "path"]);
+/**
+ * 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
@@ -144,11 +209,12 @@ export function renderTemplate(
   const unknown: string[] = [];
   const goal = template.replace(/\{\{([^{}]*)\}\}/g, (whole: string, raw: string) => {
     const name = raw.trim();
-    if (!PLACEHOLDERS.has(name)) {
+    const render = PLACEHOLDERS[name];
+    if (render === undefined) {
       unknown.push(name);
       return whole;
     }
-    return item[name as "id" | "title" | "body" | "path"];
+    return render(item);
   });
   if (unknown.length > 0) return { error: `unknown placeholder {{${unknown[0]}}}` };
   return { goal };