agents-pod 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-pod",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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",

package/src/adapters.ts

@@ -0,0 +1,303 @@
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { adaptersFile, storeRoot } from "./paths.ts";
+
+/**
+ * Adapter copies are the operator's files, outside the repository (ADRs 0023,
+ * 0024): core ships an example, the operator copies it beside their
+ * credentials. The gap this module closes is *provenance*: `--check` proves an
+ * adapter answers, never that it is current, so a copy can sit a release behind
+ * and every `doctor` line still reads ✓ (issue #26).
+ *
+ * Nothing here writes into a copy unless a human ran `adapter sync`: a package
+ * update must not silently change a command that holds live credentials.
+ */
+export interface AdapterFile {
+  name: string;
+  sha256: string;
+}
+
+/** One registered copy: where it lives, and the package state it came from. */
+export interface AdapterRecord {
+  name: string;
+  dir: string;
+  packageVersion: string;
+  files: AdapterFile[];
+}
+
+/**
+ * Files a copy owns but the package must never overwrite: credentials and the
+ * caches a platform writes for itself. Enforced even though `examples/` ships
+ * none of them — a future example that did would otherwise leak a credential
+ * over an operator's real one.
+ */
+const RUNTIME_ONLY = new Set([".env", ".token.json", ".bot.json", "state.json"]);
+
+/** `same` needs no action; `update` is a pristine copy one version behind. */
+export type AdapterFileState = "same" | "update" | "missing-in-copy" | "local-edit";
+
+export interface AdapterFilePlan {
+  name: string;
+  state: AdapterFileState;
+}
+
+export interface AdapterSyncPlan {
+  name: string;
+  dir: string;
+  packageDir: string;
+  packageVersion: string;
+  files: AdapterFilePlan[];
+  /** Package entries that are not files an operator copy can take. */
+  skipped: string[];
+}
+
+/** A fact for `doctor`; the caller decides how to print it (ADR 0027). */
+export interface AdapterFact {
+  mark: "ok" | "bad" | "note";
+  text: string;
+  next?: string;
+}
+
+/**
+ * The installed package root, derived from this module's own location: `src/`
+ * and `examples/` are siblings there, which is what makes the copy source the
+ * *installed* package rather than whatever working tree is nearby.
+ */
+export function packageRoot(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+export async function readPackageVersion(root = packageRoot()): Promise<string> {
+  try {
+    const parsed = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as {
+      version?: string;
+    };
+    return parsed.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export function adapterPackageDir(name: string, root = packageRoot()): string {
+  return join(root, "examples", name);
+}
+
+export async function readAdapters(): Promise<AdapterRecord[]> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(adaptersFile(), "utf8"));
+    return Array.isArray(parsed) ? (parsed as AdapterRecord[]) : [];
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+/** Atomic like every other store write: a crash never leaves half a manifest. */
+export async function writeAdapters(records: AdapterRecord[]): Promise<void> {
+  const file = adaptersFile();
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(records, null, 2)}\n`);
+  await rename(tmp, file);
+}
+
+export function sha256(content: Buffer | string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function fileSha(path: string): Promise<string | undefined> {
+  try {
+    return sha256(await readFile(path));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+/**
+ * The files a copy takes: regular files at the top of the package's example
+ * directory. `__pycache__` and a `.pyc` would be the package's build residue,
+ * not the adapter; runtime caches are excluded by name in `RUNTIME_ONLY`.
+ */
+async function packageFiles(packageDir: string): Promise<{ files: string[]; skipped: string[] }> {
+  const entries = await readdir(packageDir, { withFileTypes: true });
+  const files: string[] = [];
+  const skipped: string[] = [];
+  for (const entry of entries) {
+    if (RUNTIME_ONLY.has(entry.name) || entry.name === "__pycache__" || entry.name.endsWith(".pyc")) {
+      skipped.push(entry.name);
+      continue;
+    }
+    if (!entry.isFile()) {
+      skipped.push(entry.name);
+      continue;
+    }
+    files.push(entry.name);
+  }
+  files.sort();
+  return { files, skipped };
+}
+
+/**
+ * What a sync would do, without doing it. A file whose copy matches the
+ * manifest but not the package is one version behind (`update`); a file that
+ * matches neither is the operator's own edit (`local-edit`) and is reported,
+ * never overwritten without `--force`.
+ */
+export async function planAdapterSync(
+  name: string,
+  options: { root?: string; dest?: string } = {},
+): Promise<AdapterSyncPlan> {
+  const root = options.root ?? packageRoot();
+  const packageDir = adapterPackageDir(name, root);
+  const info = await stat(packageDir).catch(() => undefined);
+  if (info === undefined || !info.isDirectory()) {
+    throw new Error(`the package ships no adapter named ${name} (${packageDir})`);
+  }
+  // The store root, not $HOME: a test store and a secondary install must not
+  // sync into the machine-wide copy (ADR 0004).
+  const dir = resolve(options.dest ?? join(storeRoot(), "adapters"));
+  const packageVersion = await readPackageVersion(root);
+  const { files, skipped } = await packageFiles(packageDir);
+  const recorded = (await readAdapters()).find((record) => record.name === name);
+
+  const plan: AdapterFilePlan[] = [];
+  for (const file of files) {
+    const wanted = await fileSha(join(packageDir, file));
+    const present = await fileSha(join(dir, file));
+    if (present === undefined) {
+      plan.push({ name: file, state: "missing-in-copy" });
+      continue;
+    }
+    if (present === wanted) {
+      plan.push({ name: file, state: "same" });
+      continue;
+    }
+    const known = recorded?.files.find((entry) => entry.name === file)?.sha256;
+    plan.push({ name: file, state: known !== undefined && known === present ? "update" : "local-edit" });
+  }
+  return { name, dir, packageDir, packageVersion, files: plan, skipped };
+}
+
+/** Writes the copy and records its provenance; returns what it changed. */
+export async function applyAdapterSync(
+  plan: AdapterSyncPlan,
+  options: { force?: boolean } = {},
+): Promise<{ copied: string[]; kept: string[]; manifest: string }> {
+  await mkdir(plan.dir, { recursive: true });
+  const copied: string[] = [];
+  const kept: string[] = [];
+  const files: AdapterFile[] = [];
+
+  for (const file of plan.files) {
+    const from = join(plan.packageDir, file.name);
+    const to = join(plan.dir, file.name);
+    if (file.state === "local-edit" && options.force !== true) {
+      kept.push(file.name);
+    } else if (file.state !== "same") {
+      await copyFile(from, to);
+      copied.push(file.name);
+    }
+    // The manifest records the *package* hash, never what a kept local edit
+    // happens to be: otherwise a kept file would later read as "stale" instead
+    // of "the operator edited this", which is the fact worth reporting.
+    files.push({ name: file.name, sha256: sha256(await readFile(from)) });
+  }
+
+  const records = await readAdapters();
+  const record: AdapterRecord = {
+    name: plan.name,
+    dir: plan.dir,
+    packageVersion: plan.packageVersion,
+    files: files.sort((left, right) => left.name.localeCompare(right.name)),
+  };
+  const remaining = records.filter((entry) => entry.name !== plan.name);
+  remaining.push(record);
+  await writeAdapters(remaining);
+  return { copied, kept, manifest: adaptersFile() };
+}
+
+/**
+ * Provenance facts for `doctor` (ADR 0027). Only registered copies are
+ * reported: an unregistered directory is not something core was asked to
+ * watch, and guessing would put a platform name into core.
+ */
+export async function adapterFacts(
+  records: AdapterRecord[],
+  root = packageRoot(),
+): Promise<AdapterFact[]> {
+  const facts: AdapterFact[] = [];
+  const version = await readPackageVersion(root);
+
+  for (const record of records) {
+    const dirInfo = await stat(record.dir).catch(() => undefined);
+    if (dirInfo === undefined || !dirInfo.isDirectory()) {
+      facts.push({
+        mark: "bad",
+        text: `adapters ${record.name}: ${record.dir} is gone (a registered copy)`,
+        next: `next: agents-pod adapter sync ${record.name}`,
+      });
+      continue;
+    }
+
+    if (record.files.length === 0) {
+      // A record without hashes cannot be compared, so it must not read as ✓:
+      // an empty manifest is the shape of "registered before hashes were kept".
+      facts.push({
+        mark: "note",
+        text: `adapters ${record.name}: no file hashes recorded, so nothing can be compared`,
+        next: `next: agents-pod adapter sync ${record.name} --apply`,
+      });
+      continue;
+    }
+
+    const stale: string[] = [];
+    const edited: string[] = [];
+    const absent: string[] = [];
+    for (const file of record.files) {
+      const wanted = await fileSha(join(adapterPackageDir(record.name, root), file.name));
+      const present = await fileSha(join(record.dir, file.name));
+      if (present === undefined) {
+        absent.push(file.name);
+        continue;
+      }
+      if (wanted === undefined) {
+        // The package stopped shipping it: the copy's file is now the only one.
+        continue;
+      }
+      if (present === wanted) continue;
+      if (present === file.sha256) stale.push(file.name);
+      else edited.push(file.name);
+    }
+
+    if (absent.length > 0) {
+      facts.push({
+        mark: "bad",
+        text: `adapters ${record.name}: ${absent.join(", ")} missing from ${record.dir}`,
+        next: `next: agents-pod adapter sync ${record.name}`,
+      });
+    }
+    if (stale.length > 0) {
+      facts.push({
+        mark: "bad",
+        text:
+          `adapters ${record.name}: ${stale.join(", ")} is from ${record.packageVersion}, ` +
+          `the package ships ${version}`,
+        next: `next: agents-pod adapter sync ${record.name}`,
+      });
+    }
+    if (edited.length > 0) {
+      facts.push({
+        mark: "note",
+        text: `adapters ${record.name}: ${edited.join(", ")} differs from the package (kept: a local edit)`,
+        next: `      agents-pod adapter sync ${record.name} --dry-run names it; --force overwrites it`,
+      });
+    }
+    if (absent.length === 0 && stale.length === 0 && edited.length === 0) {
+      facts.push({ mark: "ok", text: `adapters ${record.name}: matches package ${version}` });
+    }
+  }
+  return facts;
+}

package/src/cli.ts

@@ -46,6 +46,17 @@ import {
   readProjects,
   writeProjects,
 } from "./projects.ts";
+import {
+  applyProjectMove,
+  planProjectMove,
+  type ProjectMovePlan,
+} from "./relocate.ts";
+import {
+  applyAdapterSync,
+  planAdapterSync,
+  type AdapterFileState,
+  type AdapterSyncPlan,
+} from "./adapters.ts";
 import type { PodRecord } from "./registry.ts";
 import { readPods, withRegistryLock, writePods } from "./registry.ts";
 import {
@@ -1285,7 +1296,169 @@ async function spawnCmd(
   return 0;
 }
 
-/** Per-project wake-up capacity: a small persistent guardrail, not a scheduler. */
+const PROJECT_USAGE =
+  "Usage: agents-pod project cap [n|unlimited] [--project <dir>]\n" +
+  "       agents-pod project move <old> <new> [--apply] [--move-artifacts]";
+
+function printProjectMove(
+  plan: ProjectMovePlan,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): void {
+  for (const pod of plan.pods) {
+    if (pod.artifact === "missing") continue; // its refusal below is the pod's line
+    const artifact =
+      pod.artifact === "present"
+        ? `artifacts at ${pod.to}`
+        : `move artifacts from ${pod.from}`;
+    out(`✓ relocate ${pod.id}  ${plan.oldPath} → ${plan.newPath}  (${artifact})`);
+  }
+  for (const listener of plan.listeners) {
+    out(`✓ relocate ${listener.id} (template)  ${plan.oldPath} → ${plan.newPath}`);
+  }
+  for (const project of plan.projects) {
+    out(
+      `✓ relocate capacity record ${plan.oldPath} → ${plan.newPath}  (maxActive ${project.maxActive})`,
+    );
+  }
+  for (const refusal of plan.refusals) err(`✗ ${refusal.reason}`);
+}
+
+/** Relocate records after the operator moved the tree; identity stays put (ADR 0028). */
+async function projectMoveCmd(
+  words: string[],
+  deps: CliDeps,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const apply = words.includes("--apply");
+  const moveArtifacts = words.includes("--move-artifacts");
+  const positional = words.filter((word) => word !== "--apply" && word !== "--move-artifacts");
+  if (
+    positional.length !== 2 ||
+    positional.some((word) => word.startsWith("--")) ||
+    positional[0] === undefined ||
+    positional[1] === undefined
+  ) {
+    err(PROJECT_USAGE);
+    return 2;
+  }
+
+  const cwd = deps.cwd ?? process.cwd();
+  const oldPath = resolve(cwd, positional[0]);
+  const newPath = resolve(cwd, positional[1]);
+  if (oldPath === newPath) {
+    err("old and new paths are the same; nothing to move");
+    err(PROJECT_USAGE);
+    return 2;
+  }
+
+  const plan = await planProjectMove(oldPath, newPath, { moveArtifacts });
+  if (plan.matched === 0) {
+    out(`no record is bound to ${oldPath}`);
+    if (apply) out("nothing to do");
+    return 0;
+  }
+  printProjectMove(plan, out, err);
+  if (plan.refusals.length > 0) return 1;
+  if (!apply) {
+    out("run again with --apply to write");
+    return 0;
+  }
+
+  try {
+    const result = await applyProjectMove(plan);
+    if (result.files.length === 0) {
+      out("nothing to do");
+      return 0;
+    }
+    for (const file of result.files) {
+      out(`wrote ${file.name}: ${file.changed} record${file.changed === 1 ? "" : "s"} changed`);
+    }
+    return 0;
+  } catch (error) {
+    err(`project move failed: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+const ADAPTER_USAGE =
+  "Usage: agents-pod adapter sync <name> [--dest <dir>] [--apply] [--force]";
+
+/** One mark per file, so a dry run reads like a diff (ADR 0029). */
+const ADAPTER_MARKS: Record<AdapterFileState, string> = {
+  same: "=",
+  update: "↑",
+  "missing-in-copy": "+",
+  "local-edit": "!",
+};
+
+function printAdapterPlan(plan: AdapterSyncPlan, out: (line: string) => void): void {
+  out(`adapter ${plan.name}  ${plan.packageDir} → ${plan.dir}  (package ${plan.packageVersion})`);
+  for (const file of plan.files) {
+    const kept = file.state === "local-edit" ? "  (kept: a local edit; --force overwrites)" : "";
+    out(`  ${ADAPTER_MARKS[file.state]} ${file.name}  ${file.state}${kept}`);
+  }
+}
+
+/**
+ * The package ships, the operator copies, `doctor` reports drift (ADR 0029).
+ * Dry run by default: nothing writes into a directory that holds a live
+ * credential unless a human asked for it in this invocation.
+ */
+async function adapterCmd(
+  words: string[],
+  deps: CliDeps,
+  out: (line: string) => void,
+  err: (line: string) => void,
+): Promise<number> {
+  const [sub, ...rest] = words;
+  if (sub !== "sync") {
+    err(`Unknown adapter command: ${sub ?? "(none)"}. Try: sync`);
+    err(ADAPTER_USAGE);
+    return 2;
+  }
+  const apply = rest.includes("--apply");
+  const force = rest.includes("--force");
+  const { flags, rest: positional } = parseFlags(
+    rest.filter((word) => word !== "--apply" && word !== "--force"),
+    ["dest"],
+  );
+  const name = positional[0];
+  if (positional.length !== 1 || name === undefined) {
+    err(ADAPTER_USAGE);
+    return 2;
+  }
+
+  let plan: AdapterSyncPlan;
+  try {
+    plan = await planAdapterSync(name, {
+      dest: flags.dest === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), flags.dest),
+    });
+  } catch (error) {
+    err((error as Error).message);
+    return 2;
+  }
+
+  printAdapterPlan(plan, out);
+  const pending = plan.files.filter((file) => file.state !== "same").length;
+  if (pending === 0) {
+    out(`already matches package ${plan.packageVersion}`);
+    return 0;
+  }
+  if (!apply) {
+    out("run again with --apply to write");
+    return 0;
+  }
+
+  const result = await applyAdapterSync(plan, { force });
+  if (result.copied.length > 0) out(`copied ${result.copied.join(", ")}`);
+  if (result.kept.length > 0) out(`kept ${result.kept.join(", ")} (local edits; --force overwrites)`);
+  out(`recorded package ${plan.packageVersion} in ${result.manifest}`);
+  return 0;
+}
+
+/** Per-project capacity and project-location record maintenance (ADR 0022, 0028). */
 async function projectCmd(
   words: string[],
   deps: CliDeps,
@@ -1293,10 +1466,17 @@ async function projectCmd(
   err: (line: string) => void,
 ): Promise<number> {
   const [sub, ...rest] = words;
+  if (sub === "move") return projectMoveCmd(rest, deps, out, err);
+  if (sub !== "cap") {
+    err(`Unknown project command: ${sub ?? "(none)"}. Try: cap | move`);
+    err(PROJECT_USAGE);
+    return 2;
+  }
+
   const { flags, rest: positional } = parseFlags(rest, ["project"]);
   const project = resolve(flags.project ?? deps.cwd ?? process.cwd());
-  if (sub !== "cap" || positional.length > 1) {
-    err("Usage: agents-pod project cap [n|unlimited] [--project <dir>]");
+  if (positional.length > 1) {
+    err(PROJECT_USAGE);
     return 2;
   }
 
@@ -1928,7 +2108,7 @@ export async function main(argv: string[], deps: CliDeps = {}): Promise<number>
     out("");
     out("start here  agents-pod doctor   what is missing on this machine, and the command that fixes it");
     out("pods        spawn | list | status <id> | logs <id> | wake <id> | cancel <id>");
-    out("records     agent | listener | source | deliver | project | reconcile");
+    out("records     agent | listener | source | deliver | adapter | project | reconcile");
     return 0;
   }
 
@@ -1955,6 +2135,8 @@ export async function main(argv: string[], deps: CliDeps = {}): Promise<number>
       return sourceCmd(rest, deps, out, err);
     case "deliver":
       return deliverCmd(rest, deps, out, err);
+    case "adapter":
+      return adapterCmd(rest, deps, out, err);
     case "project":
       return projectCmd(rest, deps, out, err);
     case "doctor":

package/src/doctor.ts

@@ -2,6 +2,7 @@ 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 { adapterFacts, readAdapters, type AdapterRecord } from "./adapters.ts";
 import { readListeners, type ListenerRecord } from "./listeners.ts";
 import { readLock } from "./locks.ts";
 import { loadNotifyConfig } from "./notify/config.ts";
@@ -89,6 +90,20 @@ export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport>
   } else {
     const active = registry.pods.filter((pod) => pod.state === "active").length;
     storeLines.push({ mark: "ok", text: `${registry.pods.length} pods, ${active} active` });
+    // A Pod Record bound to no Listener has no other line to carry its path
+    // (ADR 0028): terminal Pods are exempt, they block no conversation.
+    const bound = new Set(
+      listeners.filter((listener) => listener.mode === "pod").map((listener) => listener.podId),
+    );
+    for (const pod of registry.pods) {
+      if (pod.state === "done" || pod.state === "cancelled" || bound.has(pod.id)) continue;
+      if (await exists(pod.project)) continue;
+      storeLines.push({
+        mark: "bad",
+        text: `pod ${pod.id}: its project ${pod.project} does not exist`,
+        detail: [`next: agents-pod project move ${pod.project} <new>`],
+      });
+    }
   }
   const lock = await readLock(reconcileLockPath());
   if (lock !== undefined) {
@@ -102,6 +117,29 @@ export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport>
 
   sections.push({ title: "pass", lines: await passLines(lastPass, now, sources, listeners, registry.pods) });
   sections.push({ title: "intake", lines: await intakeLines(sources, listeners, now) });
+  // A corrupt provenance file is a fact, not silence: swallowing it would
+  // restore exactly the blindness adapters.json exists to end (ADR 0029).
+  let adapters: AdapterRecord[] = [];
+  let adaptersError: string | undefined;
+  try {
+    adapters = await readAdapters();
+  } catch (error) {
+    adaptersError = (error as Error).message;
+  }
+  if (adaptersError !== undefined) {
+    sections.push({
+      title: "adapters",
+      lines: [
+        {
+          mark: "note",
+          text: `adapters.json is unreadable: ${adaptersError}`,
+          detail: ["next: agents-pod adapter sync <name> --apply rewrites it"],
+        },
+      ],
+    });
+  } else if (adapters.length > 0) {
+    sections.push({ title: "adapters", lines: await adapterLines(adapters) });
+  }
   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) });
@@ -249,6 +287,8 @@ async function listenerLines(
   const lines: DoctorLine[] = [];
   for (const listener of listeners) {
     const problems: string[] = [];
+    /** The path a `project move` would fix; `undefined` means "not a path problem". */
+    let deadPath: string | undefined;
     const origin =
       listener.source !== undefined
         ? `source ${listener.source}`
@@ -265,15 +305,32 @@ async function listenerLines(
       }
       if (listener.project !== undefined && !(await exists(listener.project))) {
         problems.push(`its project ${listener.project} does not exist`);
+        deadPath = listener.project;
       }
     } else if (!pods.some((pod) => pod.id === listener.podId)) {
       problems.push(`its Pod ${listener.podId ?? "(none)"} is not in the registry`);
+    } else {
+      // #24: a bound Pod's project is what a wake-up starts in, so a renamed
+      // directory makes the whole channel inert while this line used to read ✓.
+      const pod = pods.find((candidate) => candidate.id === listener.podId)!;
+      if (!(await exists(pod.project))) {
+        problems.push(`its Pod ${pod.id} project ${pod.project} does not exist`);
+        deadPath = pod.project;
+      } else if (!(await exists(join(pod.project, ".agents", "pods", pod.id)))) {
+        problems.push(`its Pod ${pod.id} workspace is missing under ${pod.project}`);
+      }
     }
     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"],
+        detail:
+          deadPath === undefined
+            ? ["next: agents-pod listener rm " + listener.id, "      then add it again with a path that exists"]
+            : [
+                `next: agents-pod project move ${deadPath} <new>`,
+                "      a renamed repository carries <project>/.agents/pods/<id> with it (ADR 0028)",
+              ],
       });
       continue;
     }
@@ -292,6 +349,23 @@ async function listenerLines(
   return lines;
 }
 
+/**
+ * Provenance, not behaviour (issue #26): an adapter's `--check` proves it
+ * answers, never that the package's fix reached the copy. Only registered
+ * copies appear — an unregistered directory is not something core watches.
+ */
+async function adapterLines(adapters: AdapterRecord[]): Promise<DoctorLine[]> {
+  const lines: DoctorLine[] = [];
+  for (const fact of await adapterFacts(adapters)) {
+    lines.push({
+      mark: fact.mark,
+      text: fact.text,
+      ...(fact.next === undefined ? {} : { detail: [fact.next] }),
+    });
+  }
+  return lines;
+}
+
 async function outboundLines(deliverer: DelivererRecord | undefined, pods: PodRecord[]): Promise<DoctorLine[]> {
   const lines: DoctorLine[] = [];
   const { pending, dead } = await outboxFacts(pods);

package/src/paths.ts

@@ -36,6 +36,11 @@ export function sourcesFile(): string {
   return join(storeRoot(), "sources.json");
 }
 
+/** Registered adapter copies and their provenance (issue #26): beside, not inside. */
+export function adaptersFile(): string {
+  return join(storeRoot(), "adapters.json");
+}
+
 /** The single outbound delivery command, beside the Source records (ADR 0025). */
 export function delivererFile(): string {
   return join(storeRoot(), "deliverer.json");