catherd-cli 1.2.1 → 1.4.0

package/src/services/backends.ts

@@ -1,8 +1,11 @@
+import type { OrchestrationHost } from "../domain/host.ts";
+import { nativeClaudeIssue } from "../domain/profile-rules.ts";
 import type { BackendAdapter, Probe } from "../adapters/backend.ts";
 import { adapterFor } from "../adapters/registry.ts";
 import "../adapters/all.ts";
 import { CatherdError } from "../domain/errors.ts";
 import { formatRung, tryParseRung } from "../domain/ids.ts";
+import { PAIRED_FAILOVER } from "../domain/profile.ts";
 
 const READY_TTL_MS = 10 * 60_000;
 const ready = new Map<string, { at: number; probe: Probe }>();
@@ -10,6 +13,41 @@ const ready = new Map<string, { at: number; probe: Probe }>();
 /** Forget every cached probe (tests, and after the user fixes a backend). */
 export const resetReadiness = (): void => ready.clear();
 
+/** Spec 1.3 §3.3: what Bun's spawn throws for a binary built for another OS (a Linux build on macOS). */
+function execFormatError(e: unknown): string | null {
+  if (!(e instanceof Error)) return null;
+  if ((e as { code?: unknown }).code !== "ENOEXEC" && !/exec format error/i.test(e.message)) return null;
+  // macOS names the path (posix_spawn '/…/grok'), Linux only the command (uv_spawn 'grok')
+  const bin = /spawn '([^']+)'/.exec(e.message)?.[1];
+  return bin ? (Bun.which(bin, { PATH: process.env.PATH ?? "" }) ?? bin) : "exec format error";
+}
+
+/**
+ * The adapter's probe, with a CLI on PATH that the OS cannot execute reported as installed but unable to run
+ * (spec 1.3 §3.3), with the reinstall command; any other failure of the probe is thrown.
+ */
+export async function probeBackend(adapter: BackendAdapter): Promise<Probe> {
+  try {
+    return await adapter.probe();
+  } catch (e) {
+    const why = execFormatError(e);
+    if (why === null) throw e;
+    return {
+      installed: true,
+      version: null,
+      versionOk: false,
+      loggedIn: null,
+      problems: [
+        {
+          code: "E_BACKEND_CANNOT_RUN",
+          message: `${adapter.id} is installed but cannot run on this OS: ${why}`,
+          fix: adapter.install ?? `reinstall ${adapter.id} for this OS`,
+        },
+      ],
+    };
+  }
+}
+
 /**
  * Spec §4.4: the adapter for `backend` once its last probe says it is ready. A ready probe is kept
  * for 10 minutes; a failing one is never kept, so a fixed backend works on the next dispatch.
@@ -23,22 +61,29 @@ export async function readyAdapter(backend: string): Promise<{ adapter: BackendA
     });
   const hit = ready.get(backend);
   if (hit && now - hit.at < READY_TTL_MS) return { adapter, probe: hit.probe };
-  const probe = await adapter.probe();
+  const probe = await probeBackend(adapter);
   const problem = probe.problems[0];
+  // spec 1.3 §3.3: a probe that finds the CLI logged out lists E_BACKEND_NOT_LOGGED_IN, so a dispatch never
+  // reaches it (agy opens a browser and waits); logged out alone is no problem where a CLI runs without a login
   if (problem) throw new CatherdError(problem.code, problem.message, { fix: problem.fix });
   ready.set(backend, { at: now, probe });
   return { adapter, probe };
 }
 
 /**
- * Spec §4.5: a rung's stand-in on a usage limit: the profile's, else its backend's default (for `repo`,
- * when given), else none.
+ * Spec §4.5: a rung's stand-in on a usage limit: the profile's, else the same model on its paired backend
+ * (spec 1.3 §7.3), else its backend's default (for `repo`, when given), else none.
  */
 export function standInFor(failover: Record<string, string>, rung: string, repo?: string): string | null {
-  const own = failover[rung];
+  const own = failover[rung] ?? PAIRED_FAILOVER[rung];
   if (own) return own;
   const r = tryParseRung(rung);
   if (!r) return null;
   const byAdapter = adapterFor(r.backend)?.failoverFor?.(r, repo) ?? null;
   return byAdapter && formatRung(byAdapter);
 }
+
+export function assertNativeHost(rung: string, host: OrchestrationHost): void {
+  const issue = nativeClaudeIssue(rung, host, "rung");
+  if (issue) throw new CatherdError("E_CONFIG_INVALID", `${issue.message}; ${issue.fix}`, { fix: issue.fix });
+}

package/src/services/capture.ts

@@ -1,7 +1,7 @@
 import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
-import type { BackendAdapter, FinishedRun } from "../adapters/backend.ts";
+import type { BackendAdapter, FinishedRun, Outcome, RunRequest } from "../adapters/backend.ts";
 import { isCatherdError } from "../domain/errors.ts";
 import { parseRung } from "../domain/ids.ts";
 import type { Access } from "../domain/record.ts";
@@ -21,14 +21,26 @@ interface CaptureCase {
   rung: string;
   access: Access;
   brief: string;
+  /** a second brief that resumes the first run's thread in the same repo; the resumed run is captured */
+  resume?: string;
 }
 
 const SAY_HELLO =
   "Reply with the single word hello. The last line of your reply is exactly: STATUS: complete — said hello";
 const TRY_WRITE =
   "Create a file named out.txt containing the word hi. If you cannot, say why. The last line of your reply is: STATUS: complete|blocked — <one line why>";
+const WORK =
+  "Create a file named notes.txt containing hi, read it back, then run the shell command `git status --short`. The last line of your reply is exactly: STATUS: complete — wrote notes.txt";
+const RECALL =
+  "Which single word did you reply with earlier in this chat? Reply with it. The last line of your reply is exactly: STATUS: complete — recalled";
 const HAIKU = "claude-code:claude-haiku-4-5-20251001#default";
+/** spec 1.3 §4.6: `auto` has no family; only the live kit and the capture run it */
+const AUTO = "cursor:auto#default";
 const BUNNY = "opencode:opencode/space-bunny-free#default";
+/** spec 1.3 §5.6: grok 1.0.44's default model (research §3.4) at its cheapest effort */
+const GROK = "grok:grok-4.6#low";
+/** spec 1.3 §6.6: the cheapest Gemini effort; capture runs isolated, on GEMINI_API_KEY */
+const FLASH_LOW = "antigravity:gemini-3.8-flash#low";
 
 /** Spec §11.7–8: one cheap run per backend, plus a read-only role trying to write where enforcement is advisory. */
 const CAPTURE_CASES: CaptureCase[] = [
@@ -37,6 +49,26 @@ const CAPTURE_CASES: CaptureCase[] = [
   { backend: "claude-code", name: "read-only-write", rung: HAIKU, access: "read-only", brief: TRY_WRITE },
   { backend: "opencode", name: "ok", rung: BUNNY, access: "read-only", brief: SAY_HELLO },
   { backend: "opencode", name: "read-only-write", rung: BUNNY, access: "read-only", brief: TRY_WRITE },
+  // spec 1.3 §4.7: a read, a write and a shell call; a resumed chat (research §2.5); ask mode trying to write
+  { backend: "cursor", name: "ok", rung: AUTO, access: "workspace-write", brief: WORK },
+  { backend: "cursor", name: "resume", rung: AUTO, access: "read-only", brief: SAY_HELLO, resume: RECALL },
+  { backend: "cursor", name: "read-only-write", rung: AUTO, access: "read-only", brief: TRY_WRITE },
+  // spec 1.3 §5.6: the same three on grok; its read-only is the kernel profile, or the read tools on a Mac
+  // with a symlinked docker socket
+  { backend: "grok", name: "ok", rung: GROK, access: "workspace-write", brief: WORK },
+  { backend: "grok", name: "resume", rung: GROK, access: "read-only", brief: SAY_HELLO, resume: RECALL },
+  { backend: "grok", name: "read-only-write", rung: GROK, access: "read-only", brief: TRY_WRITE },
+  // spec 1.3 §6.6: the same three on agy; read-only runs under catherd's deny rules (research §8 agy 2, 5, 6)
+  { backend: "antigravity", name: "ok", rung: FLASH_LOW, access: "workspace-write", brief: WORK },
+  {
+    backend: "antigravity",
+    name: "resume",
+    rung: FLASH_LOW,
+    access: "read-only",
+    brief: SAY_HELLO,
+    resume: RECALL,
+  },
+  { backend: "antigravity", name: "read-only-write", rung: FLASH_LOW, access: "read-only", brief: TRY_WRITE },
 ];
 export const CAPTURE_BACKENDS = [...new Set(CAPTURE_CASES.map((c) => c.backend))];
 
@@ -79,12 +111,71 @@ function cleanStrings(v: unknown, clean: (s: string) => string): unknown {
   return v;
 }
 
+/** One run as an isolated dispatch would start it (plan, the worker env), without the supervisor. */
+async function runOnce(
+  adapter: BackendAdapter,
+  request: RunRequest,
+  timeoutMs: number,
+): Promise<{ run: FinishedRun; events: string; stderr: string; o: Outcome }> {
+  const plan = adapter.plan(request);
+  const startedAtMs = Date.now();
+  const p = Bun.spawn([plan.cmd, ...plan.args], {
+    cwd: plan.cwd,
+    env: workerEnv(process.env, plan.env, plan.cwd),
+    // spec 1.3 §3.3: the brief goes on stdin only to a CLI whose plan reads it there (grok reads a file)
+    stdin: plan.stdinPath ? Bun.file(plan.stdinPath) : "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    // its own group, so a timeout stops whatever the CLI started too, as the supervisor does
+    detached: true,
+  });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    killGroup(p.pid, "SIGKILL");
+  }, timeoutMs);
+  // as preflight does: a process the CLI left behind (in its own session) may hold the pipes open
+  const out = collect(p.stdout);
+  const err = collect(p.stderr);
+  const code = await p.exited;
+  clearTimeout(timer);
+  const drained = await Promise.race([
+    Promise.all([out.done, err.done]).then(() => true),
+    Bun.sleep(DRAIN_MS).then(() => false),
+  ]);
+  if (!drained) killGroup(p.pid, "SIGKILL"); // leftovers still in the CLI's group
+  out.stop();
+  err.stop();
+  const events = out.text();
+  const stderr = err.text();
+  const run: FinishedRun = {
+    request,
+    eventLines: events.split("\n").filter((l) => l.trim()),
+    reply: "",
+    stderr,
+    exit: {
+      code: p.signalCode ? null : code,
+      signal: p.signalCode ?? null,
+      reason: timedOut ? "wall-timeout" : "exited",
+      endedAt: new Date().toISOString(),
+    },
+    startedAtMs,
+  };
+  // as a dispatch records it: the backend's own totals and limits, on a fresh thread (nothing prior)
+  const o = await settled(adapter, adapter.finalize(run), run, () => ({
+    tokens: { input: 0, cached: 0, output: 0 },
+    costUsd: 0,
+  }));
+  return { run, events, stderr, o };
+}
+
 /**
  * Runs one case the way an isolated dispatch would (prepare, plan, the worker env), without the
  * supervisor. Isolated, so the stream names none of the owner's own hooks, plugins, MCP servers or config:
- * the fixtures are committed.
+ * the fixtures are committed. A case with `resume` runs its brief, then resumes that thread in the same
+ * scratch repo with `resume`, and captures the resumed run.
  */
-async function captureOne(
+export async function captureOne(
   adapter: BackendAdapter,
   version: string,
   c: CaptureCase,
@@ -96,8 +187,8 @@ async function captureOne(
     const briefPath = join(work, "brief.md");
     writeFileSync(briefPath, c.brief);
     const rung = parseRung(c.rung);
-    await adapter.prepare?.({ rung, access: c.access, isolated: true, repo });
-    const request = {
+    await adapter.prepare?.({ rung, access: c.access, isolated: true, repo, network: true });
+    const request: RunRequest = {
       rung,
       access: c.access,
       thread: null,
@@ -107,54 +198,20 @@ async function captureOne(
       replyPath: join(work, "reply.md"),
       dispatchDir: work,
     };
-    const plan = adapter.plan(request);
-    const startedAtMs = Date.now();
-    const p = Bun.spawn([plan.cmd, ...plan.args], {
-      cwd: plan.cwd,
-      env: workerEnv(process.env, plan.env, plan.cwd),
-      stdin: Bun.file(briefPath),
-      stdout: "pipe",
-      stderr: "pipe",
-      // its own group, so a timeout stops whatever the CLI started too, as the supervisor does
-      detached: true,
-    });
-    let timedOut = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
-      killGroup(p.pid, "SIGKILL");
-    }, timeoutMs);
-    // as preflight does: a process the CLI left behind (in its own session) may hold the pipes open
-    const out = collect(p.stdout);
-    const err = collect(p.stderr);
-    const code = await p.exited;
-    clearTimeout(timer);
-    const drained = await Promise.race([
-      Promise.all([out.done, err.done]).then(() => true),
-      Bun.sleep(DRAIN_MS).then(() => false),
-    ]);
-    if (!drained) killGroup(p.pid, "SIGKILL"); // leftovers still in the CLI's group
-    out.stop();
-    err.stop();
-    const events = out.text();
-    const stderr = err.text();
-    const run: FinishedRun = {
-      request,
-      eventLines: events.split("\n").filter((l) => l.trim()),
-      reply: "",
-      stderr,
-      exit: {
-        code: p.signalCode ? null : code,
-        signal: p.signalCode ?? null,
-        reason: timedOut ? "wall-timeout" : "exited",
-        endedAt: new Date().toISOString(),
-      },
-      startedAtMs,
-    };
-    // as a dispatch records it: the backend's own totals and limits, on a fresh thread (nothing prior)
-    const o = await settled(adapter, adapter.finalize(run), run, () => ({
-      tokens: { input: 0, cached: 0, output: 0 },
-      costUsd: 0,
-    }));
+    let captured = await runOnce(adapter, request, timeoutMs);
+    const resumed = c.resume === undefined ? null : captured.o.thread;
+    if (c.resume !== undefined) {
+      if (!resumed)
+        return {
+          backend: c.backend,
+          name: c.name,
+          status: "skipped",
+          reason: `the first run left no thread to resume (${captured.o.error?.message ?? captured.o.status})`,
+        };
+      writeFileSync(briefPath, c.resume);
+      captured = await runOnce(adapter, { ...request, thread: resumed }, timeoutMs);
+    }
+    const { run, events, stderr, o } = captured;
     const scrub: Scrub = {
       secrets: secretEnvValues(process.env),
       paths: [
@@ -180,7 +237,8 @@ async function captureOne(
           rung: c.rung,
           access: c.access,
           isolated: true,
-          brief: c.brief,
+          brief: c.resume ?? c.brief,
+          ...(resumed ? { resumed } : {}),
           exitCode: run.exit.code,
           reason: run.exit.reason,
           capturedAt: new Date().toISOString(),

package/src/services/catalog-refresh.ts

@@ -12,7 +12,7 @@ import {
   scoresOf,
 } from "../domain/catalog.ts";
 import { DIFFICULTIES, type Difficulty, KINDS, type Kind } from "../domain/lane.ts";
-import type { SourcesFile } from "../domain/sources.ts";
+import { defaultEffortOf, type SourcesFile } from "../domain/sources.ts";
 import type { SourceTransport } from "../infra/sources/http.ts";
 import { adjacent, derive, type RawAnswers } from "./source-derive.ts";
 import { cachedAnswers, syncSources } from "./source-sync.ts";
@@ -72,6 +72,7 @@ export function rebuildShipped(
     direct.filter((s) => s.confidence !== "inferred"),
     new Set(),
     ctx.now,
+    (f) => defaultEffortOf(ctx.sources, f),
   );
   const scores = best([...direct, ...spread], ctx.now);
   const benchmark = (d: Dim) => {

package/src/services/dispatch-service.ts

@@ -1,3 +1,4 @@
+import { assertNativeHost } from "./backends.ts";
 import { existsSync, readFileSync } from "node:fs";
 import { CatherdError, errorMessage, isCatherdError } from "../domain/errors.ts";
 import { assertId, parseRung } from "../domain/ids.ts";
@@ -34,7 +35,7 @@ import { finalizeDispatch, finalizingElsewhere, waitForFinish } from "./finalize
 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 { claimRun, ownsRun, runOwner } from "./sessions.ts";
 import { type NotesPatch, refreshState } from "./state.ts";
 
 export interface DispatchInput {
@@ -101,17 +102,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 });
@@ -294,6 +299,8 @@ export async function dispatch(deps: Deps, i: DispatchInput): Promise<DispatchSt
       hints.push(`${i.rung} is not on ${i.lane}'s routed ladder: dispatched at ${routed.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,
@@ -493,6 +500,8 @@ async function failover(deps: Deps, run: Run, d: Dispatch, limited: RunRecord):
   // 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);
   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 +526,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

@@ -27,6 +27,8 @@ const AdmitSchema = z.looseObject({
   failoverOf: z.string().optional(),
   access: z.enum(ACCESS),
   isolated: z.boolean(),
+  /** the role's network grant (1.1 §5) when admitted; absent before 1.3 */
+  network: z.boolean().optional(),
   cliVersion: z.string().nullable(),
   admittedAt: z.string(),
   repo: z.string(),
@@ -34,6 +36,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>;
 
@@ -63,7 +66,7 @@ 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 {
         // admission never finished writing this folder
       }
@@ -172,3 +175,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

@@ -1,5 +1,5 @@
 import { realTmpdir } from "../adapters/access.ts";
-import type { AccessShell } from "../adapters/backend.ts";
+import type { AccessProbeId, AccessShell } from "../adapters/backend.ts";
 import { adapterFor } from "../adapters/registry.ts";
 import "../adapters/all.ts";
 import { tryParseRung } from "../domain/ids.ts";
@@ -12,7 +12,7 @@ import type { Check } from "./doctor-checks.ts";
 // Spec §5 and §12: the five access probes doctor runs per backend that serves a workspace-write role, each
 // in that backend's worker shell with the grants a worker gets, and the rows that report them.
 
-export type ProbeId = "lock" | "temp" | "loopback" | "https" | "docker";
+export type ProbeId = AccessProbeId;
 
 /**
  * What the probes reach: npm's ping, through HTTPS_PROXY when it is set (Bun's fetch honours it), and
@@ -131,8 +131,13 @@ export async function runProbes(shell: AccessShell, network: boolean): Promise<P
   return out;
 }
 
-/** The fix for a failed probe, per backend: Codex's sandbox holds catherd's grants; the others run unsandboxed. */
-function fixFor(backend: string, id: ProbeId): string {
+/**
+ * The fix for a failed probe: the sandbox's own when its shell names one; Codex's sandbox holds catherd's grants;
+ * the others run unsandboxed.
+ */
+function fixFor(backend: string, id: ProbeId, shell: AccessShell): string {
+  const own = shell.fixes?.[id];
+  if (own) return own;
   if (backend === "codex") {
     const override =
       "catherd passes this grant to Codex itself (with your top-level [sandbox_workspace_write] writable_roots added): check that no --profile or managed requirements.toml overrides it";
@@ -173,7 +178,7 @@ export async function accessChecks(profiles: Profile[], installed: ReadonlySet<s
   const checks: Check[] = [];
   for (const [id, network] of workspaceWriteNetwork(profiles)) {
     const a = adapterFor(id);
-    if (!a?.accessShell) continue;
+    if (!a) continue;
     if (!installed.has(id)) {
       checks.push({
         id: `access:${id}`,
@@ -184,7 +189,9 @@ export async function accessChecks(profiles: Profile[], installed: ReadonlySet<s
       });
       continue;
     }
-    const shell = await a.accessShell({ network }).catch((e: unknown) => String(e));
+    const shell = a.accessShell
+      ? await a.accessShell({ network }).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(
         typeof shell === "string"
@@ -217,7 +224,7 @@ export async function accessChecks(profiles: Profile[], installed: ReadonlySet<s
             state: "warn",
             word: "blocked",
             detail: `in ${shell.how}, a worker cannot: ${failed.map((r) => `${r.label} (${r.why})`).join("; ")}`,
-            fix: failed.map((r) => `${r.label}: ${fixFor(id, r.id)}`).join("\n"),
+            fix: failed.map((r) => `${r.label}: ${fixFor(id, r.id, shell)}`).join("\n"),
           }
         : {
             ...base,

package/src/services/doctor-backends.ts

@@ -1,11 +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 { 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.
 
@@ -21,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;
 }
@@ -30,6 +37,7 @@ const PROBLEM_WORD: Record<string, string> = {
   E_BACKEND_MISSING: "missing",
   E_BACKEND_TOO_OLD: "too old",
   E_BACKEND_NOT_LOGGED_IN: "not logged in",
+  E_BACKEND_CANNOT_RUN: "cannot run",
 };
 
 /**
@@ -50,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)
@@ -85,13 +99,24 @@ 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 a.probe().catch((e: unknown) => ({
+    const probe: Probe = await probeBackend(a).catch((e: unknown) => ({
       installed: false,
       version: null,
       versionOk: false,
@@ -101,6 +126,9 @@ export async function backendChecks(
       ],
     }));
     if (probe.installed) installed?.add(id);
+    // spec 1.3 §4.7: what the probe found worth knowing, nothing to fix (an `agent` on PATH that is not Cursor)
+    for (const i of probe.info ?? [])
+      checks.push({ id: i.id, label: i.label, state: "info", word: "info", detail: i.detail });
     const problem = probe.problems[0];
     const use = used.get(id);
     if (!problem) {
@@ -119,10 +147,14 @@ 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 },
       );
+      // spec 1.3 §6.6: asked only of a logged-in CLI (a logged-out agy -p would open a browser)
+      const quota = probe.loggedIn && a.quota ? await a.quota().catch(() => null) : null;
+      if (quota)
+        checks.push({ id: `quota:${id}`, label: `${id} quota`, state: "info", word: "quota", detail: quota });
       continue;
     }
     checks.push({
@@ -138,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>> = [];