catherd-cli 1.3.0 → 1.5.0

package/src/services/dispatch-service.ts

@@ -1,4 +1,6 @@
+import { assertNativeHost } from "./backends.ts";
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { CatherdError, errorMessage, isCatherdError } from "../domain/errors.ts";
 import { assertId, parseRung } from "../domain/ids.ts";
 import type { RunRecord } from "../domain/record.ts";
@@ -15,8 +17,9 @@ import {
 import { lockHeld, withFileLock } from "../infra/filelock.ts";
 import { log } from "../infra/log.ts";
 import { isAlive, isSurelyAlive, killGroup } from "../infra/proc.ts";
+import { groupAlive, stopGroup } from "../infra/supervisor.ts";
 import { writeJsonAtomic } from "../infra/store.ts";
-import { admit, KILL_GRACE_MS, laneFile, launch } from "./admission.ts";
+import { admit, KILL_GRACE_MS, laneFile, laneOwns, launch } from "./admission.ts";
 import { standInFor } from "./backends.ts";
 import {
   type Dispatch,
@@ -33,8 +36,11 @@ import {
 import { finalizeDispatch, finalizingElsewhere, waitForFinish } from "./finalize.ts";
 import type { Deps } from "./ports.ts";
 import { route } from "./lane-service.ts";
-import { findRun, readRecords, readRoutes, type Run } from "./run-store.ts";
-import { claimRun, ownsRun } from "./sessions.ts";
+import { currentRoute } from "../domain/route.ts";
+import { appendRoute, findRun, readRecords, readRoleRoutes, readRoutes, type Run } from "./run-store.ts";
+import { sessionKey } from "../domain/host.ts";
+import { claimRun, currentSession, ownsRun, runOwner, type SessionRef } from "./sessions.ts";
+import { pinChanges, runProfile } from "./run-pin.ts";
 import { type NotesPatch, refreshState } from "./state.ts";
 
 export interface DispatchInput {
@@ -42,7 +48,8 @@ export interface DispatchInput {
   role: Role;
   name: string;
   brief: string;
-  rung: string;
+  /** spec 1.5 plan 24: optional with `lane` (the lane's current rung); required without one */
+  rung?: string;
   thread?: string;
   lane?: string;
   next?: string;
@@ -101,17 +108,21 @@ export interface Stalled {
 export const stallHooks = new Set<(s: Stalled) => void>();
 
 /** A watcher's poll: the first time the dispatch's stall.json is there, every stall hook hears of it. */
+/** A stall's quiet time; 0 when stall.json is being written or damaged, so one bad file never blocks a notice. */
+export function readStallQuietMs(dir: string): number {
+  try {
+    return Number(JSON.parse(readFileSync(dispatchPaths(dir).stall, "utf8")).quietMs) || 0;
+  } catch {
+    return 0;
+  }
+}
+
 export function stallPoll(run: Run, d: Dispatch): () => void {
   let seen = false;
   return () => {
     if (seen || !existsSync(dispatchPaths(d.dir).stall)) return;
     seen = true;
-    let quietMs = 0;
-    try {
-      quietMs = Number(JSON.parse(readFileSync(dispatchPaths(d.dir).stall, "utf8")).quietMs) || 0;
-    } catch {
-      // being written: the stall is reported without its length
-    }
+    const quietMs = readStallQuietMs(d.dir);
     for (const hook of stallHooks) {
       try {
         hook({ run, d, quietMs });
@@ -169,9 +180,19 @@ export async function watchersSettled(): Promise<void> {
  */
 export function watch(deps: Deps, run: Run, d: Dispatch): void {
   watching.add(d.admit.dispatchId);
+  // the session this watcher started under, kept apart from its live identity: an MCP connection that closes
+  // invalidates the scoped host (no session), yet the watcher still came from that session (PR #47 P1)
+  const origin = currentSession(deps);
   const w = (async () => {
     await waitForFinish(d, { pollMs: deps.pollMs, now: deps.now, onPoll: stallPoll(run, d) });
-    const s = await settle(deps, run, d, await finalizeDispatch(run, d));
+    const record = await finalizeDispatch(run, d);
+    // a session that lost the run since it dispatched leaves a limit to the owner's claim (1.1 push minors):
+    // only the run's owner starts a stand-in. A process with no session (a terminal) settles as before.
+    if (record.status === "limit" && !limitIsMine(deps, run, origin)) {
+      log("info", "dispatch", { run: run.id, name: d.admit.name, limit: "left to the run's owner" });
+      return;
+    }
+    const s = await settle(deps, run, d, record);
     if (s.stateHints[0]) log("warn", "dispatch", { run: run.id, name: d.admit.name, hint: s.stateHints[0] });
   })()
     .catch((e: unknown) =>
@@ -184,6 +205,18 @@ export function watch(deps: Deps, run: Run, d: Dispatch): void {
   watchers.add(w);
 }
 
+/**
+ * Whether a watcher settles a limit (fails it over): a watcher with no session, then or now (a terminal, a
+ * test), always does; one that started under a session does only while that session, or its live one, owns
+ * the run.
+ */
+function limitIsMine(deps: Deps, run: Run, origin: SessionRef | null): boolean {
+  if (origin === null && currentSession(deps) === null) return true;
+  if (ownsRun(deps, run)) return true;
+  const owner = runOwner(run);
+  return origin !== null && owner !== null && sessionKey(owner) === sessionKey(origin);
+}
+
 /**
  * Spec §3.3: a run this session has just taken over may have roles another session's server launched. This
  * process watches each live one it is not already watching, so it settles them and its notifier announces them
@@ -209,6 +242,16 @@ export function adopt(deps: Deps, run: Run): void {
  */
 export async function claim(deps: Deps, run: Run, o: { background?: boolean } = {}): Promise<void> {
   if (!(await claimRun(deps, run)) && !ownsRun(deps, run)) return;
+  await recoverOwned(deps, run, o);
+}
+
+/**
+ * What `claim` does for a run this session already owns, without taking it: watch its live roles, record and
+ * settle what finished unrecorded, settle its unsettled limits and unannounced records. A server that does not
+ * lead the boot runs it for each run its session owns (PR #47 P1: a role that finished while that server was
+ * away has no live process to watch and no record to scan).
+ */
+export async function recoverOwned(deps: Deps, run: Run, o: { background?: boolean } = {}): Promise<void> {
   adopt(deps, run);
   let r = recovering.get(run.id);
   if (!r) {
@@ -276,24 +319,140 @@ function unannounced(run: Run): { d: Dispatch; record: RunRecord }[] {
   });
 }
 
+/** How long a dispatch waits for another dispatch's route of the same lane (Jev may take tens of seconds). */
+const ROUTE_LOCK_MS = 120_000;
+
+/**
+ * What admission would refuse anyway, refused before a lane is routed, so a refused dispatch asks Jev nothing
+ * and writes no route row: the role off, the lane file missing or with no Owns:, the name or the lane already
+ * running. Admission checks them again under its lock.
+ */
+function refuseBeforeRouting(deps: Deps, run: Run, i: DispatchInput & { lane: string }): void {
+  const profile = runProfile(deps, run);
+  if (!profile.roles[i.role]?.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",
+    });
+  laneOwns(run, i.lane);
+  // live only: a finished, unrecorded dispatch is recorded by admission (finalizeFinished), not refused here
+  const pending = liveDispatches(run, deps.now());
+  const same = pending.find((d) => d.admit.name === i.name);
+  if (same)
+    throw new CatherdError("E_ADMIT_DUPLICATE", `${i.name} is already running on ${same.admit.rung}`, {
+      fix: `its record is announced when it finishes; or cancel(run, "${i.name}")`,
+    });
+  const lane = pending.find((d) => d.admit.lane === i.lane);
+  if (lane)
+    throw new CatherdError("E_ADMIT_OVERLAP", `lane ${i.lane} is already running as ${lane.admit.name}`, {
+      fix: `dispatch it after ${lane.admit.name} finishes`,
+    });
+}
+
+/**
+ * Plan 22: the thread a dispatch resumes. `"latest"` is the name's last recorded thread; any other id must be one
+ * the name's records in this run hold (`runs.jsonl`), in any case, so a wrong id is refused before a CLI starts
+ * and fails on it. Null for a fresh thread.
+ */
+function threadFor(run: Run, name: string, thread: string | undefined): string | null {
+  if (thread === undefined) return null;
+  assertId("role name", name);
+  const mine = readRecords(run)
+    .records.filter((r) => r.name === name && r.thread !== null)
+    .map((r) => r.thread as string);
+  const last = mine.at(-1);
+  if (thread === "latest") {
+    if (last) return last;
+    throw new CatherdError("E_ADMIT_THREAD", `${name} has no earlier thread in this run`, {
+      fix: "omit thread for a fresh thread",
+    });
+  }
+  const known = mine.findLast((t) => t.toLowerCase() === thread.toLowerCase());
+  if (known) return known;
+  throw new CatherdError("E_ADMIT_THREAD", `${thread} is not a thread of ${name} in this run`, {
+    fix: last
+      ? `pass thread: "latest" for ${name}'s last thread (${last}), or omit thread for a fresh one`
+      : "omit thread for a fresh thread",
+  });
+}
+
+/**
+ * Plan 22, resume hygiene: what an earlier turn on `thread` left running in its process group (a server, a
+ * watcher, a background command) is stopped before the thread is resumed, so it never ends the resumed CLI
+ * (exit 143). Only a dispatch whose supervisor and group leader are both gone is touched (with or without
+ * exit.json: a supervisor killed before it stopped the group writes none): a live group with no process of the
+ * leader's pid can only be that dispatch's leftovers (a pid is never reused while its group lives), and a pid
+ * that answers belongs to someone else by now. Returns a hint per group stopped.
+ */
+async function stopLeftovers(deps: Deps, run: Run, thread: string): Promise<string[]> {
+  const records = new Map(readRecords(run).records.map((r) => [r.dispatchId, r]));
+  const hints: string[] = [];
+  for (const d of listDispatches(run)) {
+    const on = d.admit.thread ?? records.get(d.admit.dispatchId)?.thread ?? null;
+    if (on?.toLowerCase() !== thread.toLowerCase()) continue;
+    const proc = readProc(d.dir);
+    const pgid = proc?.pgid ?? proc?.pid;
+    if (!proc || pgid === undefined || pgid !== proc.pid) continue;
+    // a live supervisor stops its own group when its worker ends; exit.json is not the test, since a supervisor
+    // killed (SIGKILL, OOM) before it stopped the group never writes one
+    if (isAlive(proc.supervisorPid, proc.supervisorStartTime)) continue;
+    if (isAlive(proc.pid, null) || !groupAlive(pgid)) continue;
+    await stopGroup(pgid, orphanLimits.killGraceMs, deps.pollMs);
+    log("info", "dispatch", { run: run.id, name: d.admit.name, thread, stoppedGroup: pgid });
+    hints.push(`resume: stopped what ${d.admit.name}'s earlier turn left running on thread ${thread}`);
+  }
+  return hints;
+}
+
 /**
  * Spec §4.4, plan 9 ruling 1: admit and launch one role, start its watcher, then refresh state.md with
  * `next` (after the launch, so nothing delays it). Returns at once; catherd announces the record (spec §3).
  */
 export async function dispatch(deps: Deps, i: DispatchInput): Promise<DispatchStarted> {
   const run = findRun(i.run);
+  // refused before the claim, so a wrong thread changes nothing
+  const thread = threadFor(run, i.name, i.thread);
   await claim(deps, run);
   const hints: string[] = [];
-  let rung = i.rung;
-  // spec 1.1 §6: a lane is routed before its first dispatch; a rung off the routed ladder starts at the routed one
-  if (i.lane !== undefined && !readRoutes(run).some((r) => r.lane === i.lane)) {
-    assertId("lane", i.lane);
-    const routed = await route(deps, { run: i.run, laneFile: `lanes/${i.lane}.md`, role: i.role });
-    if (!routed.ladder.includes(i.rung)) {
+  if (thread !== null) hints.push(...(await stopLeftovers(deps, run, thread)));
+  let rung: string;
+  if (i.lane !== undefined) {
+    const lane = i.lane;
+    assertId("lane", lane);
+    // spec 1.1 §6: a lane is routed before its first dispatch; a rung off the routed ladder starts at the routed one
+    let current = currentRoute(readRoutes(run), lane);
+    let routed: Awaited<ReturnType<typeof route>> | null = null;
+    if (!current) {
+      refuseBeforeRouting(deps, run, { ...i, lane });
+      // one route per lane: a second dispatch of the lane waits for the first's route and takes it
+      const got = await withFileLock(
+        join(run.dir, `route-${lane}`),
+        async () => {
+          const now = currentRoute(readRoutes(run), lane);
+          return now
+            ? { current: now, routed: null }
+            : {
+                current: null,
+                routed: await route(deps, { run: i.run, laneFile: `lanes/${lane}.md`, role: i.role }),
+              };
+        },
+        { timeoutMs: ROUTE_LOCK_MS },
+      );
+      current = got.current;
+      routed = got.routed;
+    }
+    // spec 1.5 plan 24: without a rung, a lane runs at its current rung (its route, after any climb)
+    rung = i.rung ?? routed?.rung ?? (current?.rung as string);
+    if (routed && i.rung !== undefined && !routed.ladder.includes(i.rung)) {
       rung = routed.rung;
-      hints.push(`${i.rung} is not on ${i.lane}'s routed ladder: dispatched at ${routed.rung}`);
+      hints.push(`${i.rung} is not on ${lane}'s routed ladder: dispatched at ${routed.rung}`);
     }
-  }
+  } else if (i.rung === undefined)
+    throw new CatherdError("E_INPUT_INVALID", `dispatch ${i.name}: a role outside a lane needs a rung`, {
+      fix: `route(run, role: "${i.role}") gives the role's rung; pass it as rung`,
+    });
+  else rung = i.rung;
+  // the rung that runs, after routing: an off-ladder native rung routing replaced is never launched
+  assertNativeHost(rung, deps.host.host);
   const { d, specPath } = await admit(
     deps,
     run,
@@ -302,7 +461,7 @@ export async function dispatch(deps: Deps, i: DispatchInput): Promise<DispatchSt
       name: i.name,
       brief: i.brief,
       rung,
-      thread: i.thread ?? null,
+      thread,
       lane: i.lane ?? null,
       failoverFrom: null,
     },
@@ -317,10 +476,46 @@ export async function dispatch(deps: Deps, i: DispatchInput): Promise<DispatchSt
     // a launch that failed is still watched: its record (lost, after the start grace) is announced
     watch(deps, run, d);
   }
-  await refresh(run, i.next ? { next: i.next } : {}, hints);
+  if (i.lane === undefined) recordRoleDispatch(deps, run, i.role, i.name, rung);
+  // spec 1.5: a change since the run's pin is logged in state.md each time a role starts
+  const changes = pinChanges(deps, run);
+  if (changes.length)
+    hints.push(
+      `dispatched on the run's pinned values: ${changes.join("; ")}; run_pin(run) re-pins to the repo's now`,
+    );
+  await refresh(run, { ...(i.next ? { next: i.next } : {}), pinChanges: changes }, hints);
   return { dispatched: dispatchedOf(d), hints };
 }
 
+/**
+ * Spec 1.5 plan 24: a lane-less dispatch's rung in routes.jsonl, so every role's decision can be audited:
+ * `route` when it is the rung the role's last `route` gave (with that ladder), else the coordinator's own pick.
+ * A failed write is logged, never a failed dispatch: the role is already running.
+ */
+function recordRoleDispatch(deps: Deps, run: Run, role: Role, name: string, rung: string): void {
+  try {
+    const last = readRoleRoutes(run).findLast((r) => r.role === role && r.source === "route");
+    const routed = last?.rung === rung;
+    appendRoute(run, {
+      at: new Date(deps.now()).toISOString(),
+      lane: null,
+      role,
+      name,
+      rung,
+      ladder: last?.ladder ?? [rung],
+      source: "dispatch",
+      decidedBy: routed ? last.decidedBy : "orchestrator",
+      why: routed
+        ? `the rung route gave the ${role}`
+        : last
+          ? `the coordinator's rung; route gave the ${role} ${last.rung}`
+          : `the coordinator's rung; the ${role} was never routed`,
+    });
+  } catch (e) {
+    log("warn", "dispatch", { run: run.id, name, routes: errorMessage(e) });
+  }
+}
+
 /** How long a settle waits for another process's failover of the same dispatch (a test seam). */
 export const failoverLock = { timeoutMs: 120_000 };
 
@@ -491,8 +686,10 @@ async function failover(deps: Deps, run: Run, d: Dispatch, limited: RunRecord):
     return failedOver(already.admit.rung, already);
   }
   // else that stand-in never ran and is over (recorded as lost, or past its start grace): admit a new one
-  const standIn = standInFor(deps.profiles.forRepo(run.meta.repo).failover, limited.rung, run.meta.repo);
+  const standIn = standInFor(runProfile(deps, run).failover, limited.rung, run.meta.repo);
   if (!standIn) return { hints, started: null, pause: paused };
+  // the stand-in answers to whoever owns the run now, which a claim from another host may have changed
+  assertNativeHost(standIn, runOwner(run)?.host ?? deps.host.host);
   if (parseRung(standIn).backend === "claude") {
     const agent = deps.profiles.agentFor(run.meta.repo, d.admit.role, standIn);
     return {
@@ -517,6 +714,7 @@ async function failover(deps: Deps, run: Run, d: Dispatch, limited: RunRecord):
       failoverOf: d.admit.dispatchId,
       // the stand-in answers to the session that dispatched the limited role, whoever fails it over
       sessionId: d.admit.sessionId ?? null,
+      host: d.admit.host,
     });
   } catch (e) {
     if (!isCatherdError(e)) throw e;

package/src/services/dispatches.ts

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { z } from "zod";
+import { CatherdError } from "../domain/errors.ts";
 import { dispatchHints } from "../domain/hints.ts";
 import { ACCESS, type RunRecord } from "../domain/record.ts";
 import { ROLES } from "../domain/roles.ts";
@@ -18,6 +19,11 @@ const AdmitSchema = z.looseObject({
   role: z.enum(ROLES),
   lane: z.string().nullable(),
   owns: z.array(z.string()),
+  /**
+   * spec 1.5 plan 21: a laneless writer's implicit Owns (its brief's Owns: line, else docs/** and *.md), so its
+   * edits are its own and never a concurrent lane's violation; admission never refuses an overlap with it
+   */
+  ownsImplicit: z.array(z.string()).optional(),
   rung: z.string(),
   backend: z.string(),
   thread: z.string().nullable(),
@@ -36,6 +42,7 @@ const AdmitSchema = z.looseObject({
   before: z.record(z.string(), z.string()),
   /** the Claude Code session that dispatched it (spec §3.3); absent on 1.0 dispatches and outside Claude Code */
   sessionId: z.string().optional(),
+  host: z.enum(["claude-code", "codex"]).optional(),
 });
 export type Admit = z.infer<typeof AdmitSchema>;
 
@@ -53,9 +60,11 @@ export const startLimits = { graceMs: STARTING_GRACE_MS };
 export const admitPath = (dir: string): string => join(dir, "admit.json");
 export const launchPath = (dir: string): string => join(dir, "launch.json");
 export const roleDir = (run: Run, name: string): string => join(runPaths(run.dir).roles, name);
+/** Spec 1.5 plan 21: the role's TMPDIR, `<run>/scratch/<name>/`, removed with the run's scratch. */
+export const scratchDir = (run: Run, name: string): string => join(runPaths(run.dir).scratch, name);
 
 /** Every admitted dispatch of the run, oldest first; a folder whose admit.json cannot be read is skipped. */
-export function listDispatches(run: Run): Dispatch[] {
+export function listDispatches(run: Run, strict = false): Dispatch[] {
   const roles = runPaths(run.dir).roles;
   const out: Dispatch[] = [];
   if (!existsSync(roles)) return out;
@@ -65,8 +74,10 @@ export function listDispatches(run: Run): Dispatch[] {
       if (!id.isDirectory()) continue;
       const dir = join(roles, name.name, id.name);
       try {
-        out.push({ dir, admit: readVersioned(admitPath(dir), AdmitSchema, 1) });
+        out.push({ dir, admit: decodeAdmit(readVersioned(admitPath(dir), AdmitSchema, 1)) });
       } catch {
+        if (strict && existsSync(admitPath(dir)))
+          throw new CatherdError("E_RUN_CORRUPT", `run ${run.id} has unreadable admission evidence: ${dir}`);
         // admission never finished writing this folder
       }
     }
@@ -123,9 +134,10 @@ export function pendingDispatches(
   run: Run,
   now = Date.now(),
   records: RunRecord[] = readRecords(run).records,
+  strict = false,
 ): LiveDispatch[] {
   const recorded = new Set(records.map((r) => r.dispatchId));
-  return listDispatches(run)
+  return listDispatches(run, strict)
     .filter((d) => !recorded.has(d.admit.dispatchId))
     .map((d) => ({ ...d, state: dispatchState(d, now) }));
 }
@@ -133,6 +145,23 @@ export function pendingDispatches(
 export const liveDispatches = (run: Run, now = Date.now()): LiveDispatch[] =>
   pendingDispatches(run, now).filter((d) => d.state !== "finished");
 
+/** The thread the supervisor saw the role's CLI name (thread.json), else null. */
+export function readThread(dir: string): string | null {
+  const t = readJson<{ thread?: unknown }>(dispatchPaths(dir).thread)?.thread;
+  return typeof t === "string" && t ? t : null;
+}
+
+/**
+ * Spec 1.5 plan 21: the role whose thread `thread` is, in this run: a recorded thread, a resumed one, or the one
+ * a live role's supervisor wrote down. Null for any other thread, the orchestrator's among them.
+ */
+export function roleThreadOf(run: Run, thread: string): string | null {
+  const recorded = readRecords(run).records.find((r) => r.thread === thread);
+  if (recorded) return recorded.name;
+  const d = listDispatches(run).find((x) => x.admit.thread === thread || readThread(x.dir) === thread);
+  return d ? d.admit.name : null;
+}
+
 /** Spec §4.1: `roles/<name>/latest` names the newest dispatch of a role. */
 export function setLatest(run: Run, name: string, dispatchId: string): void {
   writeTextAtomic(join(roleDir(run, name), "latest"), dispatchId);
@@ -174,3 +203,7 @@ export function readFailover(dir: string): FailoverFile | null {
 export function recordHints(run: Run, d: Dispatch, r: RunRecord): string[] {
   return readFailover(d.dir)?.hints ?? dispatchHints(r, d.admit.owns, relative(run.dir, d.dir));
 }
+
+function decodeAdmit(a: Admit): Admit {
+  return a.sessionId && !a.host ? { ...a, host: "claude-code" } : a;
+}

package/src/services/doctor-access.ts

@@ -172,9 +172,14 @@ export function workspaceWriteNetwork(profiles: Profile[]): Map<string, boolean>
 
 /**
  * The `sandbox:codex` row (which `codex sandbox` form runs) and one `access:<backend>` row per backend; a
- * backend not in `installed` (its CLI is not on PATH) is skipped without running a probe.
+ * backend not in `installed` (its CLI is not on PATH) is skipped without running a probe. `repos`: where
+ * workers run (doctor's repo and every bound one), for a sandbox set per repo.
  */
-export async function accessChecks(profiles: Profile[], installed: ReadonlySet<string>): Promise<Check[]> {
+export async function accessChecks(
+  profiles: Profile[],
+  installed: ReadonlySet<string>,
+  repos: string[] = [],
+): Promise<Check[]> {
   const checks: Check[] = [];
   for (const [id, network] of workspaceWriteNetwork(profiles)) {
     const a = adapterFor(id);
@@ -190,7 +195,7 @@ export async function accessChecks(profiles: Profile[], installed: ReadonlySet<s
       continue;
     }
     const shell = a.accessShell
-      ? await a.accessShell({ network }).catch((e: unknown) => String(e))
+      ? await a.accessShell({ network, repos }).catch((e: unknown) => String(e))
       : `no way to run a shell in ${id}'s sandbox without a model turn; the live kit (docs/dev/live-verification.md) runs the five probes as one worker turn`;
     if (id === "codex")
       checks.push(

package/src/services/doctor-backends.ts

@@ -1,12 +1,13 @@
+import type { OrchestrationHost } from "../domain/host.ts";
 import type { Probe } from "../adapters/backend.ts";
 import { adapterFor } from "../adapters/registry.ts";
 import "../adapters/all.ts";
 import { ADAPTER_IDS, tryParseRung } from "../domain/ids.ts";
 import type { Profile } from "../domain/profile.ts";
 import { ROLES, type Role } from "../domain/roles.ts";
-import { probeBackend } from "./backends.ts";
+import { standInFor, probeBackend } from "./backends.ts";
 import { refreshDiscovery } from "./catalog-service.ts";
-import { type Check, errText, fixOf } from "./doctor-checks.ts";
+import { type Check, errText, fixOf, hostFlag } from "./doctor-checks.ts";
 
 // The backend rows of `catherd doctor` (spec §10.3) and the backends the linked profiles use.
 
@@ -22,7 +23,12 @@ export function usedBackends(profiles: Profile[]): Map<string, "role" | "failove
   };
   for (const p of profiles) {
     for (const role of ROLES) if (p.roles[role].enabled) for (const r of p.roles[role].rungs) note(r, "role");
-    for (const to of Object.values(p.failover)) note(to, "failover");
+    for (const role of ROLES)
+      if (p.roles[role].enabled)
+        for (const r of p.roles[role].rungs) {
+          const to = standInFor(p.failover, r);
+          if (to) note(to, "failover");
+        }
   }
   return used;
 }
@@ -52,10 +58,16 @@ const shellWord = (w: string): string => (/^[\w./:=@,+-]+$/.test(w) ? w : `'${w.
  * each linked profile, any default rung the new ladder would not hold reset first. The artist draws, which only Codex does, so
  * off Codex it is turned off instead.
  */
-export function moveRolesFix(install: string, id: string, to: string, profiles: Profile[]): string {
+export function moveRolesFix(
+  install: string,
+  id: string,
+  to: string,
+  profiles: Profile[],
+  host: OrchestrationHost = "unknown",
+): string {
   const onIt = (r: string | undefined) => r !== undefined && backendOf(r) === id;
   const set = (p: Profile, path: string, v: string) =>
-    `catherd profile set ${path} ${shellWord(v)} --profile ${shellWord(p.name)}`;
+    `catherd profile set ${path} ${shellWord(v)} --profile ${shellWord(p.name)}${hostFlag(host)}`;
   const stuck = new Set<Role>();
   const commands: string[] = [];
   for (const p of profiles)
@@ -87,10 +99,21 @@ export async function backendChecks(
   used: Map<string, "role" | "failover">,
   profiles: Profile[],
   installed?: Set<string>,
+  host: OrchestrationHost = "unknown",
 ): Promise<Check[]> {
   const checks: Check[] = [];
   const ready: string[] = [];
   for (const id of ADAPTER_IDS) {
+    if (host === "codex" && id === "claude-code" && !used.has(id)) {
+      checks.push({
+        id: `backend:${id}`,
+        label: id,
+        state: "skip",
+        word: "not required",
+        detail: "not probed: the selected profile has no headless Claude role or reachable failover",
+      });
+      continue;
+    }
     const a = adapterFor(id);
     if (!a) continue;
     const probe: Probe = await probeBackend(a).catch((e: unknown) => ({
@@ -124,7 +147,7 @@ export async function backendChecks(
               state: "warn",
               word: "billing",
               detail: `${detail} · profile ${billed.name} bills ${id} as ${billed.billing[id]}, but this login is ${probe.billing}`,
-              fix: `catherd profile set billing.${id} ${probe.billing} --profile ${billed.name}`,
+              fix: `catherd profile set billing.${id} ${probe.billing} --profile ${billed.name}${hostFlag(host)}`,
             }
           : { id: `backend:${id}`, label: id, state: "ok", word: "ready", detail },
       );
@@ -147,7 +170,7 @@ export async function backendChecks(
   for (const c of checks) {
     const id = c.id.slice("backend:".length);
     if (to && c.state === "fail" && c.word === PROBLEM_WORD.E_BACKEND_MISSING && c.fix && id !== to)
-      c.fix = moveRolesFix(c.fix, id, to, profiles);
+      c.fix = moveRolesFix(c.fix, id, to, profiles, host);
   }
   // spec §5.2: doctor refreshes discovery; a listing that fails keeps the last one
   let refreshed: Awaited<ReturnType<typeof refreshDiscovery>> = [];

package/src/services/doctor-checks.ts

@@ -1,3 +1,4 @@
+import type { OrchestrationHost } from "../domain/host.ts";
 import { readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { errorMessage, isCatherdError } from "../domain/errors.ts";
@@ -131,9 +132,13 @@ export function locksCheck(): Check {
   }
 }
 
-export function agentsCheck(): Check {
+export function agentsCheck(
+  host: OrchestrationHost,
+  selected?: string[],
+  relink = `catherd profile use ${activeName()}`,
+): Check {
   const base = { id: "agents", label: "Claude agents" };
-  const links = agentLinkState();
+  const links = agentLinkState(host, selected);
   const broken = [...links.missing, ...links.stale];
   if (broken.length)
     return {
@@ -141,13 +146,19 @@ export function agentsCheck(): Check {
       state: "fail",
       word: links.missing.length ? "missing" : "stale",
       detail: broken.join(", "),
-      fix: `catherd profile use ${activeName()}`,
+      fix: relink,
     };
   return links.ok.length
     ? { ...base, state: "ok", word: "ready", detail: `${links.ok.length} linked` }
     : { ...base, state: "skip", word: "none", detail: "no profile uses a native Claude rung" };
 }
 
+/**
+ * ` --host <host>` for a fix doctor prints, when it judged on a known host: run from a plain terminal, the fix
+ * must judge the profile the same way (omitted architect/verifier rungs resolve per host).
+ */
+export const hostFlag = (host: OrchestrationHost): string => (host === "unknown" ? "" : ` --host ${host}`);
+
 /** The browser CLI the ui-reviewer's prompt takes its screenshots with. */
 const UI_BROWSER = "agent-browser";
 
@@ -155,7 +166,11 @@ const UI_BROWSER = "agent-browser";
  * The ui-reviewer takes screenshots with agent-browser: a profile that turns it on, on a machine without it,
  * dispatches a role that cannot do its job. Nothing to say when it is on PATH or no profile turns the role on.
  */
-export function uiBrowserCheck(profiles: Profile[], onPath: (bin: string) => string | null): Check | null {
+export function uiBrowserCheck(
+  profiles: Profile[],
+  onPath: (bin: string) => string | null,
+  host: OrchestrationHost = "unknown",
+): Check | null {
   const on = profiles.filter((p) => p.roles["ui-reviewer"].enabled).map((p) => p.name);
   if (!on.length || onPath(UI_BROWSER)) return null;
   return {
@@ -167,7 +182,7 @@ export function uiBrowserCheck(profiles: Profile[], onPath: (bin: string) => str
     fix: [
       `npm i -g ${UI_BROWSER}`,
       "or turn the role off:",
-      ...on.map((n) => `catherd profile set roles.ui-reviewer.enabled false --profile ${n}`),
+      ...on.map((n) => `catherd profile set roles.ui-reviewer.enabled false --profile ${n}${hostFlag(host)}`),
     ].join("\n"),
   };
 }