catherd-cli 0.2.1 → 1.0.0

package/src/infra/supervisor.ts

@@ -0,0 +1,257 @@
+import type { Subprocess } from "bun";
+import { appendFileSync, closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
+import { z } from "zod";
+import { errorMessage } from "../domain/errors.ts";
+import type { ExitInfo, ExitReason } from "../domain/record.ts";
+import { dispatchPaths, supervisorLockTarget } from "./dispatch-dir.ts";
+import { tryLock } from "./filelock.ts";
+import { log } from "./log.ts";
+import { killGroup, processStartTime } from "./proc.ts";
+import { PRIVATE_FILE, writeJsonAtomic } from "./store.ts";
+
+export const SuperviseSpecSchema = z.looseObject({
+  schema: z.literal(1),
+  backend: z.string(),
+  dispatchDir: z.string(),
+  cmd: z.string(),
+  args: z.array(z.string()),
+  env: z.record(z.string(), z.string()),
+  cwd: z.string(),
+  stdinPath: z.string().nullable(),
+  idleMs: z.number().positive(),
+  wallMs: z.number().positive(),
+  killGraceMs: z.number().nonnegative(),
+  graceAfterFinalMs: z.number().nonnegative().nullable(),
+  pollMs: z.number().positive(),
+});
+export type SuperviseSpec = z.infer<typeof SuperviseSpecSchema>;
+
+/** What one stream line tells the supervisor: the terminal event, the thread, a tool call opening or closing. */
+interface LineInfo {
+  final?: boolean;
+  thread?: string;
+  /** a tool call the CLI started (`open`) or finished: while one is open the run is busy, however quiet */
+  item?: { id: string; open: boolean };
+}
+
+export interface SuperviseHooks {
+  onLine?(line: string): LineInfo;
+  /** `sinceMs`: when this run started, so a backend can ignore what an earlier run on the thread left */
+  isBusy?(thread: string | null, sinceMs: number): Promise<boolean>;
+  interrupt?(thread: string | null): Promise<void>;
+}
+
+/** Reads whatever the child appended to `file` since `offset`, as complete lines. */
+function readNew(file: string, state: { offset: number; rest: string; decoder: TextDecoder }): string[] {
+  if (!existsSync(file)) return [];
+  const size = statSync(file).size;
+  if (size <= state.offset) return [];
+  const fd = openSync(file, "r");
+  try {
+    const buf = Buffer.alloc(size - state.offset);
+    readSync(fd, buf, 0, buf.length, state.offset);
+    state.offset = size;
+    // stream: a multi-byte character split across two polls waits in the decoder for its tail.
+    const text = state.rest + state.decoder.decode(buf, { stream: true });
+    const lines = text.split("\n");
+    state.rest = lines.pop() ?? "";
+    return lines.filter((l) => l.trim());
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** A hook's answer, or `fallback` when it throws, rejects or takes longer than `ms`. */
+async function bounded<T>(call: () => Promise<T> | undefined, ms: number, fallback: T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const answer = call();
+    if (!answer) return fallback;
+    const late = new Promise<T>((resolve) => {
+      timer = setTimeout(() => resolve(fallback), ms);
+    });
+    return await Promise.race([answer, late]);
+  } catch {
+    return fallback;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function groupAlive(pgid: number): boolean {
+  try {
+    process.kill(-pgid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** SIGTERM the group, give it `graceMs` to leave, then SIGKILL whatever is left of it. */
+async function stopGroup(pgid: number, graceMs: number, pollMs: number): Promise<void> {
+  killGroup(pgid, "SIGTERM");
+  const end = Date.now() + graceMs;
+  while (Date.now() < end && groupAlive(pgid))
+    await Bun.sleep(Math.max(1, Math.min(pollMs, end - Date.now())));
+  // Always, not only when the leader lingers: a member that ignores SIGTERM outlives its leader.
+  // The group only, never the bare pid: once the leader is gone its pid may belong to someone else.
+  try {
+    process.kill(-pgid, "SIGKILL");
+  } catch {
+    // the group is gone
+  }
+}
+
+/**
+ * Supervises one dispatch's worker, as the dispatch's only supervisor: it first takes the dispatch's
+ * supervisor lock (a dead holder's is reclaimed) and holds it for its whole life. A supervisor that finds
+ * a live one holding it returns null at once, before opening events or stderr (opened with "w") and
+ * without exit.json, so a relaunch (recovery after a collector died between spawn and launch.json) never
+ * starts a second worker.
+ */
+export async function supervise(spec: SuperviseSpec, hooks: SuperviseHooks = {}): Promise<ExitInfo | null> {
+  const release = tryLock(supervisorLockTarget(spec.dispatchDir));
+  if (!release) {
+    log("info", "supervise", { dispatch: spec.dispatchDir, skipped: "another supervisor holds it" });
+    return null;
+  }
+  try {
+    return await superviseHeld(spec, hooks);
+  } finally {
+    release();
+  }
+}
+
+async function superviseHeld(spec: SuperviseSpec, hooks: SuperviseHooks): Promise<ExitInfo> {
+  const p = dispatchPaths(spec.dispatchDir);
+  const finish = (info: ExitInfo): ExitInfo => {
+    writeJsonAtomic(p.exit, { schema: 1, ...info });
+    return info;
+  };
+  const fds: number[] = [];
+  let child: Subprocess;
+  try {
+    const stdin = spec.stdinPath ? openSync(spec.stdinPath, "r") : "ignore";
+    if (typeof stdin === "number") fds.push(stdin);
+    const stdout = openSync(p.events, "w", PRIVATE_FILE);
+    fds.push(stdout);
+    const stderr = openSync(p.stderr, "w", PRIVATE_FILE);
+    fds.push(stderr);
+    child = Bun.spawn([spec.cmd, ...spec.args], {
+      cwd: spec.cwd,
+      env: spec.env,
+      stdin,
+      stdout,
+      stderr,
+      detached: true,
+    });
+    log("info", "spawn", {
+      backend: spec.backend,
+      dispatch: spec.dispatchDir,
+      argv: [spec.cmd, ...spec.args],
+      env: spec.env,
+      cwd: spec.cwd,
+      pid: child.pid,
+    });
+  } catch (e) {
+    try {
+      appendFileSync(p.stderr, `catherd: could not start ${spec.cmd}: ${errorMessage(e)}\n`, {
+        mode: PRIVATE_FILE,
+      });
+    } catch {
+      // exit.json below still records that the worker never ran
+    }
+    return finish({ code: null, signal: null, reason: "lost", endedAt: new Date().toISOString() });
+  } finally {
+    for (const fd of fds) closeSync(fd);
+  }
+
+  const hookMs = Math.min(10_000, spec.idleMs);
+  let reason: ExitReason | null = null;
+  let thread: string | null = null;
+  let failure: { error: unknown } | null = null;
+  let done = false;
+  void child.exited.then(() => {
+    done = true;
+  });
+
+  try {
+    writeJsonAtomic(p.proc, {
+      schema: 1,
+      pid: child.pid,
+      pgid: child.pid, // the detached child leads its own group
+      startTime: processStartTime(child.pid),
+      supervisorPid: process.pid,
+      supervisorStartTime: processStartTime(process.pid),
+      startedAt: new Date().toISOString(),
+    });
+
+    const started = Date.now();
+    let lastActivity = started;
+    let finalAt: number | null = null;
+    const open = new Set<string>();
+    const stream = { offset: 0, rest: "", decoder: new TextDecoder("utf-8") };
+
+    while (!done && reason === null) {
+      await Bun.sleep(spec.pollMs);
+      const lines = readNew(p.events, stream);
+      if (lines.length) lastActivity = Date.now();
+      for (const line of lines) {
+        let d: LineInfo | undefined;
+        try {
+          d = hooks.onLine?.(line);
+        } catch {
+          continue; // one line the hook cannot read must not end supervision
+        }
+        if (d?.thread) thread = d.thread;
+        if (d?.final) finalAt ??= Date.now();
+        if (d?.item) {
+          if (d.item.open) open.add(d.item.id);
+          else open.delete(d.item.id);
+        }
+      }
+      // a worker that ended on its own is recorded as it ended, even if a cancel or a limit arrived meanwhile
+      if (done) break;
+      const now = Date.now();
+      if (existsSync(p.cancel)) reason = "cancelled";
+      else if (now - started >= spec.wallMs) reason = "wall-timeout";
+      else if (finalAt !== null && spec.graceAfterFinalMs !== null && now - finalAt >= spec.graceAfterFinalMs)
+        reason = "after-final";
+      else if (now - lastActivity >= spec.idleMs) {
+        const busy = open.size > 0 || (await bounded(() => hooks.isBusy?.(thread, started), hookMs, false));
+        // the busy check can take up to hookMs: a worker that ended meanwhile is recorded as it ended, read
+        // from the child itself too, since `done` is set by a callback that may not have run yet
+        if (done || child.exitCode !== null || child.signalCode !== null) break;
+        if (busy) lastActivity = Date.now();
+        else reason = "idle-timeout";
+      }
+    }
+  } catch (e) {
+    failure = { error: e };
+    reason = "lost";
+  }
+
+  let stopped = false;
+  if (reason !== null && !done) {
+    if (reason !== "after-final" && failure === null && hooks.interrupt) {
+      await bounded(() => hooks.interrupt?.(thread), hookMs, undefined);
+      // a server-side stop lets the CLI end on its own: it gets the kill grace before any signal
+      await Promise.race([child.exited, Bun.sleep(spec.killGraceMs)]);
+    }
+    if (!done) {
+      await stopGroup(child.pid, spec.killGraceMs, spec.pollMs);
+      stopped = true;
+    }
+  }
+  const code = await child.exited;
+  // On every path: a worker that ends on its own may leave members of its group behind.
+  if (!stopped && groupAlive(child.pid)) await stopGroup(child.pid, spec.killGraceMs, spec.pollMs);
+  const info = finish({
+    code: child.signalCode ? null : code,
+    signal: child.signalCode ?? null,
+    reason: reason ?? "exited",
+    endedAt: new Date().toISOString(),
+  });
+  if (failure) throw failure.error;
+  return info;
+}

package/src/infra/version.ts

@@ -0,0 +1,6 @@
+import { readFileSync } from "node:fs";
+
+/** The package version; the MCP server reports it and every run folder records it. */
+export const VERSION: string = (
+  JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")) as { version: string }
+).version;

package/src/services/admission.ts

@@ -0,0 +1,277 @@
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { BackendAdapter } from "../adapters/backend.ts";
+import { budgetStatus, formatBudget } from "../domain/budget.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { assertId, formatRung, newDispatchId, parseRung } from "../domain/ids.ts";
+import { overlaps, parseLaneHeader } from "../domain/lane.ts";
+import type { Role } from "../domain/roles.ts";
+import { dispatchPaths, markForCollect } from "../infra/dispatch-dir.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { statusSnapshot } from "../infra/git.ts";
+import { launchSupervisor } from "../infra/launch.ts";
+import { processStartTime } from "../infra/proc.ts";
+import { ensurePrivateDir, PRIVATE_FILE, writeJsonAtomic, writeTextAtomic } from "../infra/store.ts";
+import { readyAdapter, standInFor } from "./backends.ts";
+import { spendOf } from "./budget.ts";
+import {
+  type Admit,
+  admitPath,
+  type Dispatch,
+  launchPath,
+  type LiveDispatch,
+  listDispatches,
+  pendingDispatches,
+  roleDir,
+  setLatest,
+} from "./dispatches.ts";
+import { finalizeDispatch } from "./finalize.ts";
+import type { Deps } from "./ports.ts";
+import { readRecords, recordsOnThread, type Run, runPaths } from "./run-store.ts";
+
+export interface AdmitInput {
+  role: Role;
+  name: string;
+  brief: string;
+  rung: string;
+  thread: string | null;
+  lane: string | null;
+  failoverFrom: string | null;
+  /** the dispatch id of the limited dispatch this stand-in replaces */
+  failoverOf?: string;
+}
+
+/** Spec §3.3: SIGTERM, then SIGKILL this long after. */
+export const KILL_GRACE_MS = 10_000;
+
+export const laneFile = (run: Run, lane: string): string => join(runPaths(run.dir).lanes, `${lane}.md`);
+
+function laneOwns(run: Run, lane: string): string[] {
+  const file = laneFile(run, lane);
+  if (!existsSync(file))
+    throw new CatherdError("E_LANE_INVALID", `no lane file lanes/${lane}.md`, {
+      fix: "write it with write_run_file first",
+    });
+  const owns = parseLaneHeader(readFileSync(file, "utf8")).owns;
+  if (owns.length === 0)
+    throw new CatherdError("E_LANE_INVALID", `lanes/${lane}.md has no Owns: line`, {
+      fix: "add `Owns: <paths>` below the lane's title",
+    });
+  return owns;
+}
+
+/**
+ * Records each finished dispatch of the run that has none yet, as reconcile does, so one whose waiter died
+ * never blocks its name or lane. Before the admission lock: a finalize may wait on another's claim. One that
+ * throws is skipped and stays pending, so the refusal still names it.
+ */
+async function finalizeFinished(run: Run, now: number): Promise<void> {
+  for (const d of pendingDispatches(run, now)) {
+    if (d.state !== "finished") continue;
+    try {
+      await finalizeDispatch(run, d);
+    } catch {
+      // stays pending: admission refuses its name and lane, and names it
+    }
+  }
+}
+
+/**
+ * The cap on an adapter's prepare. Each CLI call in it is bounded already (15 s); this covers the slowest
+ * bounded path (opencode: a reload, then two listings) so only a prepare that is truly stuck is refused.
+ */
+export const prepareLimits = { timeoutMs: 60_000 };
+
+/** The adapter's prepare, refused with E_IO_UNEXPECTED when it has not settled within the limit. */
+async function prepared(adapter: BackendAdapter, req: Parameters<NonNullable<BackendAdapter["prepare"]>>[0]) {
+  if (!adapter.prepare) return;
+  const ms = prepareLimits.timeoutMs;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () =>
+        reject(
+          new CatherdError("E_IO_UNEXPECTED", `${adapter.id} did not get ready within ${ms} ms`, {
+            fix: `check that the ${adapter.id} CLI starts and answers, then dispatch again`,
+          }),
+        ),
+      ms,
+    );
+  });
+  try {
+    await Promise.race([adapter.prepare(req), late]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Spec §4.4 step 1. The checks that read shared state and the write that makes the dispatch live
+ * happen under the run's admission lock, so parallel dispatches always see each other (audit C1).
+ */
+export async function admit(deps: Deps, run: Run, i: AdmitInput): Promise<{ d: Dispatch; specPath: string }> {
+  assertId("role name", i.name);
+  if (i.lane !== null) assertId("lane", i.lane);
+  const rung = parseRung(i.rung);
+  const profile = deps.profiles.forRepo(run.meta.repo);
+  const rc = profile.roles[i.role];
+  if (!rc?.enabled)
+    throw new CatherdError("E_ADMIT_RUNG", `the ${i.role} role is off in profile ${profile.name}`, {
+      fix: "skip the role, or turn it on with profile_set",
+    });
+  if (rung.backend === "claude")
+    throw new CatherdError("E_ADMIT_RUNG", `${i.rung} is a native Claude rung`, {
+      fix: `run it as Agent(subagent_type: "${deps.profiles.agentFor(run.meta.repo, i.role, i.rung)}"), then record_agent_run`,
+    });
+  const allowed = new Set([
+    ...rc.rungs,
+    ...rc.rungs.flatMap((r) => standInFor(profile.failover, r, run.meta.repo) ?? []),
+  ]);
+  if (!allowed.has(formatRung(rung)))
+    throw new CatherdError(
+      "E_ADMIT_RUNG",
+      `${i.rung} is not on the ${i.role} ladder of profile ${profile.name}`,
+      {
+        fix: `use the rung route returned; the ladder is ${rc.rungs.join(", ") || "empty"}`,
+      },
+    );
+  const { adapter, probe } = await readyAdapter(rung.backend);
+  if (i.thread !== null && !(adapter.resume.supported && adapter.resume.threadPattern.test(i.thread)))
+    throw new CatherdError("E_ADMIT_THREAD", `"${i.thread}" is not a ${adapter.id} thread id`, {
+      fix: "pass the thread from the role's earlier record, or none for a fresh thread",
+    });
+  const owns = i.lane === null ? [] : laneOwns(run, i.lane);
+  const id = newDispatchId();
+  const dir = join(roleDir(run, i.name), id);
+  const p = dispatchPaths(dir);
+  // a resumed thread lives in the home it started in (CODEX_HOME), whatever the profile says now
+  const started = i.thread === null ? undefined : recordsOnThread(run, rung.backend, i.thread).at(-1);
+  const isolated = started?.isolated ?? profile.isolated[rung.backend] ?? false;
+  await prepared(adapter, { rung, access: rc.access, isolated, repo: run.meta.repo });
+  const plan = adapter.plan({
+    rung,
+    access: rc.access,
+    thread: i.thread,
+    isolated,
+    repo: run.meta.repo,
+    briefPath: p.brief,
+    replyPath: p.reply,
+    dispatchDir: dir,
+  });
+
+  await finalizeFinished(run, deps.now());
+  return withFileLock(runPaths(run.dir).admission, async () => {
+    // A dispatch blocks until its record is written, not only while it runs: its finalizer diffs the
+    // tree after the exit, so a later dispatch's writes must not land in between. A finished one here
+    // could not be recorded just now. The records and the pending dispatches are one snapshot, taken
+    // under the lock appendRecord writes under, so no record lands between the two reads.
+    const { records, pending } = await withFileLock(runPaths(run.dir).runs, () => {
+      const records = readRecords(run).records;
+      return { records, pending: pendingDispatches(run, deps.now(), records) };
+    });
+    const doing = (d: LiveDispatch): string => (d.state === "finished" ? "finished, unrecorded," : "running");
+    const same = pending.find((d) => d.admit.name === i.name);
+    if (same)
+      throw new CatherdError(
+        "E_ADMIT_DUPLICATE",
+        `${i.name} is already ${doing(same)} on ${same.admit.rung}`,
+        {
+          fix:
+            same.state === "finished"
+              ? `its record could not be written; see ${same.dir}, and retry`
+              : `wait for it, or cancel(run, "${i.name}")`,
+        },
+      );
+    for (const d of pending) {
+      const shared = overlaps(owns, d.admit.owns);
+      if (shared.length)
+        throw new CatherdError(
+          "E_ADMIT_OVERLAP",
+          `${i.name} owns ${shared.join(", ")}, which ${d.admit.name} (${doing(d)}) owns`,
+          {
+            fix: `dispatch it after ${d.admit.name} finishes`,
+          },
+        );
+    }
+    // a finished dispatch not yet recorded still spent its tokens: every pending one counts
+    const budget = budgetStatus(spendOf(run, records, pending, deps.now()), profile.budget);
+    if (budget && budget.fraction >= 1)
+      throw new CatherdError("E_RUN_BUDGET", `the run budget is spent: ${formatBudget(budget)}`, {
+        fix: "ask the user to raise profile.budget, or finish the run with what landed",
+      });
+    const admitted: Admit = {
+      schema: 1,
+      runId: run.id,
+      dispatchId: id,
+      name: i.name,
+      role: i.role,
+      lane: i.lane,
+      owns,
+      rung: formatRung(rung),
+      backend: rung.backend,
+      thread: i.thread,
+      attempt: listDispatches(run).filter((d) => d.admit.name === i.name).length + 1,
+      failoverFrom: i.failoverFrom,
+      ...(i.failoverOf ? { failoverOf: i.failoverOf } : {}),
+      access: rc.access,
+      isolated,
+      cliVersion: probe.version,
+      admittedAt: new Date(deps.now()).toISOString(),
+      repo: run.meta.repo,
+      before: await statusSnapshot(run.meta.repo),
+    };
+    ensurePrivateDir(dir);
+    writeTextAtomic(p.brief, i.brief);
+    // Spec §10.4: the adapter's overrides only; the supervisor adds its own inherited env at spawn
+    // time (src/entry/supervise-command.ts), so no credential is ever written to disk. 0600 all the same.
+    writeJsonAtomic(
+      p.spec,
+      {
+        schema: 1,
+        backend: rung.backend,
+        dispatchDir: dir,
+        cmd: plan.cmd,
+        args: plan.args,
+        env: { ...plan.env, PWD: plan.cwd },
+        cwd: plan.cwd,
+        stdinPath: plan.stdinPath,
+        idleMs: profile.timeouts.idleMin * 60_000,
+        wallMs: profile.timeouts.wallMin * 60_000,
+        killGraceMs: KILL_GRACE_MS,
+        graceAfterFinalMs: adapter.graceAfterFinalMs,
+        pollMs: deps.pollMs,
+      },
+      { mode: 0o600 },
+    );
+    // the collect mark before admit.json: no admitted dispatch ever exists without it, so a process that
+    // dies before launching it still leaves a record (lost, once its start grace passes) for a `wait`
+    markForCollect(dir);
+    writeJsonAtomic(admitPath(dir), admitted);
+    setLatest(run, i.name, id);
+    return { d: { dir, admit: admitted }, specPath: p.spec };
+  });
+}
+
+/** Starts the dispatch's supervisor and records who it is; a supervisor that cannot start ends the dispatch as lost. */
+export function launch(d: Dispatch, specPath: string): void {
+  try {
+    const pid = launchSupervisor(specPath);
+    writeJsonAtomic(launchPath(d.dir), {
+      schema: 1,
+      supervisorPid: pid,
+      supervisorStartTime: processStartTime(pid),
+    });
+  } catch (e) {
+    const p = dispatchPaths(d.dir);
+    appendFileSync(p.stderr, `catherd: could not start the supervisor: ${(e as Error).message}\n`, {
+      mode: PRIVATE_FILE,
+    });
+    writeJsonAtomic(p.exit, {
+      schema: 1,
+      code: null,
+      signal: null,
+      reason: "lost",
+      endedAt: new Date().toISOString(),
+    });
+  }
+}

package/src/services/agent-links.ts

@@ -0,0 +1,139 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { basename, join, sep } from "node:path";
+import { type AgentFile, agentFiles } from "../domain/agents.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { claudeAgentsDir } from "../infra/paths.ts";
+import { ensurePrivateDir, writeTextAtomic } from "../infra/store.ts";
+import { VERSION } from "../infra/version.ts";
+import { activeName, agentsRoot, getProfile, profileExists, readProjects } from "./profile-store.ts";
+
+// Spec §7.3: the agent files and their links in Claude Code's agents dir. Only profile-service.ts writes
+// them, under its profiles lock.
+
+const lstatOrNull = (p: string) => {
+  try {
+    return lstatSync(p);
+  } catch {
+    return null;
+  }
+};
+const ours = (): string => `${agentsRoot()}${sep}`;
+/** A link catherd made: a symlink into `<config>/agents/`. Nothing else in the agents dir is ever touched. */
+const isOurLink = (path: string): boolean => {
+  const st = lstatOrNull(path);
+  return st !== null && st.isSymbolicLink() && readlinkSync(path).startsWith(ours());
+};
+
+/** Spec §7.3: the active profile and every repo-bound one are linked at once. */
+export function linkedProfiles(): string[] {
+  const names = new Set([activeName(), ...Object.values(readProjects().bindings)]);
+  return [...names].filter(profileExists).sort();
+}
+
+export interface Planned {
+  files: Map<string, AgentFile[]>;
+  links: Map<string, string>;
+}
+
+export function plan(extra: string[] = []): Planned {
+  const files = new Map<string, AgentFile[]>();
+  for (const name of new Set([...linkedProfiles(), ...extra.filter(profileExists)]))
+    files.set(name, agentFiles(getProfile(name), VERSION));
+  const links = new Map<string, string>();
+  for (const name of linkedProfiles())
+    for (const f of files.get(name) ?? [])
+      links.set(join(claudeAgentsDir(), `${f.name}.md`), join(agentsRoot(), name, `${f.name}.md`));
+  return { files, links };
+}
+
+/** Refuses before anything is written when a planned link would replace a file catherd does not own. */
+function assertNoConflict(p: Planned): void {
+  for (const link of p.links.keys())
+    if (lstatOrNull(link) && !isOurLink(link))
+      throw new CatherdError("E_CONFIG_INVALID", `${link} exists and is not catherd's`, {
+        fix: `move ${link} away, then run the command again`,
+      });
+}
+
+export interface Synced {
+  linked: string[];
+  pruned: string[];
+  /** agents whose link is new or whose file changed: Claude Code reads them only at a session's start */
+  newSessionNeededFor: string[];
+}
+
+/**
+ * Writes the planned agent files and links, prunes catherd's stale ones, and says what changed. The
+ * ownership check runs before the first write, so no caller can replace a file catherd does not own.
+ */
+export function apply(p: Planned, removed: string[] = []): Synced {
+  assertNoConflict(p);
+  const changed = new Set<string>();
+  for (const [name, files] of p.files) {
+    const dir = join(agentsRoot(), name);
+    ensurePrivateDir(dir);
+    const keep = new Set(files.map((f) => `${f.name}.md`));
+    for (const f of files) {
+      const path = join(dir, `${f.name}.md`);
+      if (!existsSync(path) || readFileSync(path, "utf8") !== f.text) {
+        writeTextAtomic(path, f.text);
+        changed.add(path);
+      }
+    }
+    for (const f of readdirSync(dir)) if (!keep.has(f)) rmSync(join(dir, f), { force: true });
+  }
+  for (const name of removed) rmSync(join(agentsRoot(), name), { recursive: true, force: true });
+
+  const target = claudeAgentsDir();
+  const newSession: string[] = [];
+  if (p.links.size > 0) mkdirSync(target, { recursive: true });
+  for (const [link, file] of p.links) {
+    const fresh = !isOurLink(link) || readlinkSync(link) !== file;
+    if (fresh) {
+      rmSync(link, { force: true });
+      symlinkSync(file, link);
+    }
+    if (fresh || changed.has(file)) newSession.push(basename(link, ".md"));
+  }
+  const pruned: string[] = [];
+  if (existsSync(target))
+    for (const entry of readdirSync(target)) {
+      const link = join(target, entry);
+      if (isOurLink(link) && !p.links.has(link)) {
+        rmSync(link, { force: true });
+        pruned.push(entry);
+      }
+    }
+  return {
+    linked: [...p.links.keys()].map((l) => basename(l, ".md")).sort(),
+    pruned: pruned.sort(),
+    // a removed agent is still loaded in the running Claude Code session until a new one starts
+    newSessionNeededFor: [...newSession, ...pruned.map((e) => basename(e, ".md"))].sort(),
+  };
+}
+
+/** What `doctor` compares: each link that should exist, and whether it and its file are current. */
+export function agentLinkState(): { missing: string[]; stale: string[]; ok: string[] } {
+  const p = plan();
+  const out = { missing: [] as string[], stale: [] as string[], ok: [] as string[] };
+  for (const [name, files] of p.files)
+    for (const f of files) {
+      const link = join(claudeAgentsDir(), `${f.name}.md`);
+      if (!p.links.has(link)) continue;
+      const file = join(agentsRoot(), name, `${f.name}.md`);
+      if (!isOurLink(link)) out.missing.push(f.name);
+      else if (readlinkSync(link) !== file || !existsSync(file) || readFileSync(file, "utf8") !== f.text)
+        out.stale.push(f.name);
+      else out.ok.push(f.name);
+    }
+  return out;
+}