catherd-cli 1.2.1 → 1.4.0

package/src/infra/cli.ts

@@ -0,0 +1,65 @@
+import { scrubSecrets } from "./env.ts";
+import { log } from "./log.ts";
+import { killGroup } from "./proc.ts";
+
+export interface CliResult {
+  ok: boolean;
+  out: string;
+  err: string;
+}
+
+/** Process groups of CLI calls still running: an exiting catherd (Ctrl-C is exit 130) kills them. */
+const live = new Set<number>();
+let hooked = false;
+function track(pid: number): void {
+  live.add(pid);
+  if (hooked) return;
+  hooked = true;
+  // a detached group gets no terminal SIGINT, and process.exit skips the timeout, so kill it on the way out
+  process.on("exit", () => {
+    for (const g of live) killGroup(g, "SIGKILL");
+  });
+}
+
+/**
+ * Runs `bin <args>` without catherd's secrets and with no stdin; null when `bin` is not on PATH. A call
+ * past `timeoutMs` is killed with every process it started (it runs in its own process group) and is
+ * reported as failed, so neither a wedged CLI nor a child holding its pipes stalls the caller.
+ */
+export async function runCli(
+  bin: string,
+  args: string[],
+  o: { timeoutMs: number; env?: Record<string, string>; cwd?: string; logArgs?: string[] },
+): Promise<CliResult | null> {
+  if (!Bun.which(bin, { PATH: process.env.PATH ?? "" })) return null;
+  const logArgs = o.logArgs ?? args;
+  log("debug", "spawn", { argv: [bin, ...logArgs], env: scrubSecrets(o.env ?? {}) });
+  const p = Bun.spawn([bin, ...args], {
+    cwd: o.cwd,
+    env: scrubSecrets({ ...process.env, ...o.env }),
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    detached: true,
+  });
+  track(p.pid);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), o.timeoutMs);
+  });
+  try {
+    const done = await Promise.race([
+      Promise.all([p.exited, new Response(p.stdout).text(), new Response(p.stderr).text()]),
+      late,
+    ]);
+    if (!done) {
+      killGroup(p.pid, "SIGKILL");
+      return { ok: false, out: "", err: `${bin} ${logArgs.join(" ")} timed out after ${o.timeoutMs} ms` };
+    }
+    const [code, out, err] = done;
+    return { ok: code === 0, out, err };
+  } finally {
+    clearTimeout(timer);
+    live.delete(p.pid);
+  }
+}

package/src/infra/codex-queue.ts

@@ -0,0 +1,165 @@
+import type { HostSessionRef } from "../domain/host.ts";
+import { runCli } from "./cli.ts";
+import { scrubSecrets } from "./env.ts";
+
+export interface QueueCapability {
+  cli: boolean;
+  server: "supported" | "unsupported" | "unverified";
+  reason: string | null;
+  /** false when nothing was probed yet: `cli` then says nothing about the CLI */
+  checked?: false;
+}
+export type QueueSendResult =
+  | { outcome: "accepted"; msgId: string }
+  | { outcome: "not-submitted"; reason: string }
+  | { outcome: "ambiguous"; reason: string };
+
+const UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const uuid = new RegExp(`^${UUID}$`, "i");
+const receipt = new RegExp(`^Queued message (${UUID}) for thread (${UUID})\\.$`);
+const TIMEOUT_MS = 10000;
+
+export async function queueCapability(
+  env: Record<string, string | undefined>,
+  run: typeof runCli = runCli,
+): Promise<QueueCapability> {
+  try {
+    const help = await run("codex", ["queue", "--help"], {
+      timeoutMs: TIMEOUT_MS,
+      env: scrubSecrets({ ...process.env, ...env }),
+    });
+    if (
+      !help?.ok ||
+      !/\bqueue\b/.test(help.out) ||
+      !["--thread", "--message", "--remote"].every((flag) => new RegExp(`${flag}\\s`).test(help.out))
+    )
+      return {
+        cli: false,
+        server: "unverified",
+        reason: "Native codex queue with --remote is unavailable; update Codex and use peek/result.",
+      };
+    return {
+      cli: true,
+      server: "unverified",
+      reason: "Native server queue method enumeration is unavailable; help proves CLI support only.",
+    };
+  } catch {
+    return {
+      cli: false,
+      server: "unverified",
+      reason: "Could not inspect native codex queue; use peek/result.",
+    };
+  }
+}
+
+const PROBE_TTL_MS = 60_000;
+let known: { at: number; capability: QueueCapability } | null = null;
+let probing: Promise<void> | null = null;
+
+/** The capability a one-shot command reports without probing: it never waits, and doctor checks it. */
+export const UNCHECKED_QUEUE: QueueCapability = {
+  cli: false,
+  server: "unverified",
+  reason: "Native codex queue is not checked by this command; catherd doctor checks it.",
+  checked: false,
+};
+
+/**
+ * The last known queue capability, without waiting on the Codex CLI: peek and status never wait (spec §3.7).
+ * A missing or stale answer starts one probe in the background; until it lands the capability reads unchecked.
+ */
+export function knownQueueCapability(
+  env: Record<string, string | undefined>,
+  run: typeof runCli = runCli,
+  now: number = Date.now(),
+): QueueCapability {
+  if (!probing && (!known || now - known.at >= PROBE_TTL_MS))
+    probing = queueCapability(env, run)
+      .then((capability) => {
+        known = { at: now, capability };
+      })
+      .finally(() => {
+        probing = null;
+      });
+  return (
+    known?.capability ?? {
+      cli: false,
+      server: "unverified",
+      reason: "Native codex queue is being checked; peek again for the result.",
+      checked: false,
+    }
+  );
+}
+
+/** Settles the background probe knownQueueCapability started, if any (a test seam). */
+export async function queueProbeSettled(): Promise<void> {
+  await probing;
+}
+
+/** Settles any background probe and forgets its answer (a test seam). */
+export async function resetQueueProbe(): Promise<void> {
+  await probing;
+  known = null;
+}
+
+export async function sendToCodexQueue(
+  target: HostSessionRef,
+  content: string,
+  env: Record<string, string | undefined>,
+  run: typeof runCli = runCli,
+): Promise<QueueSendResult> {
+  if (target.host !== "codex" || target.sessionId.length !== 36 || !uuid.test(target.sessionId))
+    return {
+      outcome: "not-submitted",
+      reason: "Queue requires a validated original Codex thread UUID; use peek/result.",
+    };
+  if (!content.trim()) return { outcome: "not-submitted", reason: "Queue message is empty." };
+  const capability = await queueCapability(env, run);
+  if (!capability.cli || capability.server === "unsupported")
+    return {
+      outcome: "not-submitted",
+      reason: capability.reason ?? "Native queue is unavailable; use peek/result.",
+    };
+  try {
+    const args = ["queue", "--remote", "unix://", "--thread", target.sessionId, "--message", content];
+    const result = await run("codex", args, {
+      timeoutMs: TIMEOUT_MS,
+      env: scrubSecrets({ ...process.env, ...env }),
+      logArgs: [...args.slice(0, -1), "[redacted]"],
+    });
+    if (result === null)
+      return { outcome: "not-submitted", reason: "Codex executable is unavailable; use peek/result." };
+    const match = result.ok ? receipt.exec(result.out.trim()) : null;
+    if (match && match[2]?.toLowerCase() === target.sessionId.toLowerCase())
+      return { outcome: "accepted", msgId: match[1]! };
+    if (
+      !result.ok &&
+      !result.out.trim() &&
+      (/^Error: the remote app server does not support thread\/queue\/add; update or restart the remote app server(?:\n|$)/.test(
+        result.err,
+      ) ||
+        /^error: (?:unrecognized subcommand 'queue'|unexpected argument '--remote' found)(?:\n|$)/.test(
+          result.err,
+        ) ||
+        /^Error: failed to connect to remote app server at `unix:\/\/[^`\n]+`: [^\n]+(?:\n|$)/.test(
+          result.err,
+        ))
+    )
+      return {
+        outcome: "not-submitted",
+        reason:
+          "Native queue refused before submission; check CLI/server support and the existing native endpoint, then use peek/result.",
+      };
+    return {
+      outcome: "ambiguous",
+      reason:
+        "Native queue invocation has no verified receipt; use peek/result. Retrying may duplicate input.",
+    };
+  } catch {
+    return {
+      outcome: "ambiguous",
+      reason:
+        "Native queue invocation failed without a verified receipt; use peek/result. Retrying may duplicate input.",
+    };
+  }
+}

package/src/infra/delivery.ts

@@ -0,0 +1,83 @@
+import { existsSync } from "node:fs";
+import { z } from "zod";
+import { CatherdError } from "../domain/errors.ts";
+import { sessionKey, type HostSessionRef } from "../domain/host.ts";
+import { awaitsCollect, dispatchPaths } from "./dispatch-dir.ts";
+import { withFileLockSync } from "./filelock.ts";
+import { readVersioned, writeJsonAtomic } from "./store.ts";
+
+const AttemptSchema = z
+  .looseObject({
+    attemptId: z.string().min(1),
+    target: z.object({
+      host: z.enum(["codex", "claude-code"]),
+      sessionId: z.string().min(1),
+      hostSessionId: z.string().nullable(),
+      name: z.string().nullable(),
+    }),
+    eventIds: z.array(z.string().min(1)).min(1),
+    at: z.iso.datetime(),
+    status: z.enum(["submitting", "accepted", "ambiguous", "failed"]),
+    msgId: z.string().nullable(),
+    reason: z.string().nullable(),
+  })
+  .refine((a) => a.status !== "accepted" || Boolean(a.msgId?.trim()), "accepted attempt needs a receipt");
+const DeliverySchema = z.looseObject({ schema: z.literal(1), attempts: z.array(AttemptSchema) });
+export type DeliveryAttempt = z.infer<typeof AttemptSchema>;
+export type DeliveryState = "pending" | "enqueue-accepted" | "ambiguous" | "collected";
+
+export function readDelivery(dir: string): DeliveryAttempt[] {
+  const file = dispatchPaths(dir).delivery;
+  return existsSync(file)
+    ? readVersioned(file, DeliverySchema, 1, {
+        fix: "Use peek/result; delivery evidence is unreadable and retry may duplicate input.",
+      }).attempts
+    : [];
+}
+
+/** Short shared lock: distinct stalled/finished event claims must not lose each other's updates. */
+export function writeDeliveryAttempt(dir: string, attempt: DeliveryAttempt): void {
+  const parsed = AttemptSchema.safeParse(attempt);
+  if (!parsed.success) throw new CatherdError("E_INPUT_INVALID", "Invalid delivery attempt");
+  const file = dispatchPaths(dir).delivery;
+  withFileLockSync(file, () => {
+    const document = existsSync(file)
+      ? readVersioned(file, DeliverySchema, 1)
+      : { schema: 1 as const, attempts: [] as DeliveryAttempt[] };
+    const prior = document.attempts.findIndex((a) => a.attemptId === attempt.attemptId);
+    if (prior < 0) document.attempts.push(parsed.data);
+    else {
+      const sent = document.attempts[prior]!;
+      if (
+        JSON.stringify(sent.target) !== JSON.stringify(parsed.data.target) ||
+        JSON.stringify(sent.eventIds) !== JSON.stringify(attempt.eventIds) ||
+        sent.at !== attempt.at
+      )
+        throw new CatherdError(
+          "E_INPUT_INVALID",
+          "Delivery target, events and submission time are immutable",
+        );
+      document.attempts[prior] = { ...sent, ...parsed.data };
+    }
+    writeJsonAtomic(file, document);
+  });
+}
+
+export function deliveryState(dir: string, target: HostSessionRef, eventId: string): DeliveryState {
+  try {
+    const event = JSON.parse(eventId) as unknown;
+    if (Array.isArray(event) && event[2] === "finished" && !awaitsCollect(dir)) return "collected";
+  } catch {
+    /* Invalid event text cannot imply collection. */
+  }
+  try {
+    const attempts = readDelivery(dir).filter(
+      (a) => sessionKey(a.target) === sessionKey(target) && a.eventIds.includes(eventId),
+    );
+    if (attempts.some((a) => a.status === "accepted")) return "enqueue-accepted";
+    if (attempts.some((a) => a.status === "submitting" || a.status === "ambiguous")) return "ambiguous";
+    return "pending";
+  } catch {
+    return "ambiguous";
+  }
+}

package/src/infra/dispatch-dir.ts

@@ -40,6 +40,7 @@ export function dispatchPaths(dir: string) {
     failover: join(dir, "failover.json"),
     /** the message that announced this dispatch's record to its session, once sent (plan 10) */
     notified: join(dir, "notified.json"),
+    delivery: join(dir, "delivery.json"),
     /** written once by the supervisor when the worker went quiet for half its idle timeout, not busy (spec §3.6) */
     stall: join(dir, "stall.json"),
     /** the message that announced the stall, once sent */

package/src/infra/env.ts

@@ -5,6 +5,9 @@
  * runs, a headless claude-code worker would inherit it): no process catherd starts gets them.
  */
 const SECRET_ENV = new Set([
+  "CODEX_THREAD_ID",
+  "CODEX_SESSION_ID",
+  "CATHERD_ORCHESTRATION_HOST",
   "TYPESAFE_API_KEY",
   // spec 1.2 §9: the user's Artificial Analysis key reads scores for catherd alone
   "ARTIFICIAL_ANALYSIS_API_KEY",
@@ -39,7 +42,7 @@ export function workerEnv(
   overrides: Record<string, string>,
   cwd: string,
 ): Record<string, string> {
-  return { ...scrubSecrets(base), ...overrides, PWD: cwd };
+  return { ...scrubSecrets({ ...base, ...overrides }), PWD: cwd };
 }
 
 /** What a preflight check may see; everything else, credentials included, stays out (spec §4.7). */

package/src/infra/host-context.ts

@@ -0,0 +1,58 @@
+import type { HostContext, KnownHost, OrchestrationHost } from "../domain/host.ts";
+import { readSessionEnv, sessionFileFor } from "./claude-session.ts";
+
+export function resolveHost(e: {
+  clientName?: string;
+  env: Record<string, string | undefined>;
+  terminalHost?: OrchestrationHost;
+}): HostContext {
+  const conflict = (message: string): HostContext => ({ host: "unknown", session: null, conflict: message });
+  const hosts = new Set<KnownHost>();
+  const client = e.clientName;
+  if (client === "codex-mcp-client") hosts.add("codex");
+  if (client === "claude-code") hosts.add("claude-code");
+  const launcher = e.env.CATHERD_ORCHESTRATION_HOST;
+  if (launcher === "codex" || launcher === "claude-code") hosts.add(launcher);
+  const claude = readSessionEnv(e.env);
+  if (claude) hosts.add("claude-code");
+  // UUIDs are case-insensitive: one spelling, so the launcher's and a request's casing name the same thread
+  const thread = e.env.CODEX_THREAD_ID?.toLowerCase();
+  const session = e.env.CODEX_SESSION_ID?.toLowerCase();
+  const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (thread !== undefined || session !== undefined) {
+    hosts.add("codex");
+    if ((thread !== undefined && !uuid.test(thread)) || (session !== undefined && !uuid.test(session)))
+      return conflict("Codex session IDs must be UUIDs; remove invalid CODEX_THREAD_ID / CODEX_SESSION_ID");
+    if (thread && session && thread !== session)
+      return conflict("CODEX_THREAD_ID and CODEX_SESSION_ID disagree; correct the launcher environment");
+  }
+  if (hosts.size > 1)
+    return conflict(
+      "Initialized client and launcher session evidence disagree; remove the other host's environment",
+    );
+  const host = [...hosts][0] ?? e.terminalHost ?? "unknown";
+  if (host === "codex")
+    return {
+      host,
+      session:
+        thread || session ? { host, sessionId: thread || session!, hostSessionId: null, name: null } : null,
+      conflict: null,
+    };
+  if (host === "claude-code" && claude) {
+    const file = sessionFileFor(claude);
+    const id = file?.sessionId ?? claude.sessionId;
+    return {
+      host,
+      session: id
+        ? {
+            host,
+            sessionId: id,
+            hostSessionId: file?.hostSessionId ?? claude.hostSessionId,
+            name: file?.name ?? null,
+          }
+        : null,
+      conflict: null,
+    };
+  }
+  return { host, session: null, conflict: null };
+}

package/src/infra/paths.ts

@@ -2,8 +2,10 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 function root(kind: "config" | "data"): string {
-  // set for an isolated worker whose XDG_CONFIG_HOME points elsewhere, so its `catherd lock` reads this config
+  // set for an isolated worker whose XDG_CONFIG_HOME or HOME points elsewhere, so its `catherd lock` reads
+  // this config and takes this lock dir
   if (kind === "config" && process.env.CATHERD_CONFIG_DIR) return process.env.CATHERD_CONFIG_DIR;
+  if (kind === "data" && process.env.CATHERD_DATA_DIR) return process.env.CATHERD_DATA_DIR;
   const home = process.env.CATHERD_HOME;
   if (home) return join(home, kind);
   if (kind === "config") return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "catherd");

package/src/infra/peer-inbox.ts

@@ -51,10 +51,12 @@ export function sendToInbox(
   const socketPath = target.socketPath;
   return new Promise<SendResult>((resolve) => {
     let settled = false;
+    // once the frame is being written a failure may still have delivered it: such a result carries its msg_id
+    let writing = false;
     const done = (r: SendResult) => {
       if (settled) return;
       settled = true;
-      resolve(r);
+      resolve(writing && r.outcome === "error" ? { ...r, msgId } : r);
     };
     let s: ReturnType<typeof createConnection>;
     try {
@@ -77,6 +79,7 @@ export function sendToInbox(
     });
     s.on("connect", () => {
       clearTimeout(timer);
+      writing = true;
       s.write(frameText(content, priority, target.token, msgId), (err) => {
         if (err) {
           s.destroy();

package/src/infra/supervisor.ts

@@ -1,3 +1,4 @@
+import { scrubSecrets } from "./env.ts";
 import type { Subprocess } from "bun";
 import { appendFileSync, closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
 import { z } from "zod";
@@ -139,7 +140,7 @@ async function superviseHeld(spec: SuperviseSpec, hooks: SuperviseHooks): Promis
     fds.push(stderr);
     child = Bun.spawn([spec.cmd, ...spec.args], {
       cwd: spec.cwd,
-      env: spec.env,
+      env: scrubSecrets(spec.env),
       stdin,
       stdout,
       stderr,
@@ -149,7 +150,7 @@ async function superviseHeld(spec: SuperviseSpec, hooks: SuperviseHooks): Promis
       backend: spec.backend,
       dispatch: spec.dispatchDir,
       argv: [spec.cmd, ...spec.args],
-      env: spec.env,
+      env: scrubSecrets(spec.env),
       cwd: spec.cwd,
       pid: child.pid,
     });

package/src/services/admission.ts

@@ -1,3 +1,4 @@
+import type { KnownHost } from "../domain/host.ts";
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { BackendAdapter } from "../adapters/backend.ts";
@@ -45,6 +46,7 @@ export interface AdmitInput {
   failoverOf?: string;
   /** the dispatching session (spec §3.3); absent means the session this process serves */
   sessionId?: string | null;
+  host?: KnownHost;
 }
 
 /** Spec §3.3: SIGTERM, then SIGKILL this long after. */
@@ -162,18 +164,40 @@ export async function admit(
     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",
     });
+  // 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 network = rc.network !== false;
+  // spec 1.3 §3.2: a backend that fixes a thread's access when it starts it refuses another on resume
+  if (started && adapter.resume.sameAccessOnly && started.access !== rc.access)
+    throw new CatherdError(
+      "E_ADMIT_THREAD",
+      `${adapter.id} keeps the access a thread started with: ${i.thread} ran ${started.access}, and the ${i.role} role runs ${rc.access}`,
+      { fix: "dispatch a fresh thread (omit `thread`)" },
+    );
+  // and the network grant: grok keeps a session's sandbox profile, agy's isolated homes differ by it.
+  // A record from before 1.3 carries no grant to compare.
+  if (started?.network !== undefined && adapter.resume.sameAccessOnly && started.network !== network)
+    throw new CatherdError(
+      "E_ADMIT_THREAD",
+      `${adapter.id} keeps the network grant a thread started with: ${i.thread} ran ${started.network ? "with" : "without"} the network, and the ${i.role} role runs ${network ? "with" : "without"} it`,
+      { fix: "dispatch a fresh thread (omit `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 });
+  await prepared(adapter, {
+    rung,
+    access: rc.access,
+    isolated,
+    repo: run.meta.repo,
+    network,
+  });
   const plan = adapter.plan({
     rung,
     access: rc.access,
-    network: rc.network !== false,
+    network,
     thread: i.thread,
     isolated,
     repo: run.meta.repo,
@@ -183,7 +207,6 @@ export async function admit(
   });
 
   await finalizeFinished(run, deps.now(), onRecorded);
-  const sessionId = i.sessionId !== undefined ? i.sessionId : (currentSession(deps)?.sessionId ?? null);
   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
@@ -223,6 +246,9 @@ export async function admit(
       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 before = await statusSnapshot(run.meta.repo);
+    const session = currentSession(deps);
+    const sessionId = i.sessionId !== undefined ? i.sessionId : (session?.sessionId ?? null);
     const admitted: Admit = {
       schema: 1,
       runId: run.id,
@@ -239,11 +265,12 @@ export async function admit(
       ...(i.failoverOf ? { failoverOf: i.failoverOf } : {}),
       access: rc.access,
       isolated,
+      network,
       cliVersion: probe.version,
       admittedAt: new Date(deps.now()).toISOString(),
       repo: run.meta.repo,
-      before: await statusSnapshot(run.meta.repo),
-      ...(sessionId ? { sessionId } : {}),
+      before,
+      ...(sessionId ? { sessionId, host: i.host ?? session?.host ?? "claude-code" } : {}),
     };
     ensurePrivateDir(dir);
     // spec 1.1 §6: every brief ends with its role's reply contract, failover stand-ins' included

package/src/services/agent-links.ts

@@ -1,3 +1,4 @@
+import type { OrchestrationHost } from "../domain/host.ts";
 import {
   existsSync,
   lstatSync,
@@ -44,10 +45,10 @@ export interface Planned {
   links: Map<string, string>;
 }
 
-export function plan(extra: string[] = []): Planned {
+export function plan(host: OrchestrationHost, extra: string[] = [], selected?: 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));
+  for (const name of new Set(selected ?? [...linkedProfiles(), ...extra.filter(profileExists)]))
+    files.set(name, agentFiles(getProfile(name, host), VERSION));
   const links = new Map<string, string>();
   for (const name of linkedProfiles())
     for (const f of files.get(name) ?? [])
@@ -71,6 +72,27 @@ export interface Synced {
   newSessionNeededFor: string[];
 }
 
+export function pruneProfileAgents(name: string): Synced {
+  const dir = join(agentsRoot(), name);
+  const pruned: string[] = [];
+  const target = claudeAgentsDir();
+  if (existsSync(target))
+    for (const entry of readdirSync(target)) {
+      const link = join(target, entry);
+      if (isOurLink(link) && readlinkSync(link).startsWith(`${dir}${sep}`)) {
+        rmSync(link);
+        pruned.push(entry);
+      }
+    }
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  pruned.sort();
+  return {
+    linked: [],
+    pruned,
+    newSessionNeededFor: pruned.map((entry) => basename(entry, ".md")),
+  };
+}
+
 /**
  * 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.
@@ -122,8 +144,11 @@ export function apply(p: Planned, removed: string[] = []): Synced {
 }
 
 /** 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();
+export function agentLinkState(
+  host: OrchestrationHost,
+  selected?: string[],
+): { missing: string[]; stale: string[]; ok: string[] } {
+  const p = plan(host, [], selected);
   const out = { missing: [] as string[], stale: [] as string[], ok: [] as string[] };
   for (const [name, files] of p.files)
     for (const f of files) {