catherd-cli 1.3.0 → 1.5.0

package/src/domain/errors.ts

@@ -17,9 +17,12 @@ export type ErrorCode =
   | "E_ADMIT_OVERLAP"
   | "E_ADMIT_ID"
   | "E_ADMIT_THREAD"
+  | "E_ADMIT_PAUSED"
+  | "E_ADMIT_ORDER"
   | "E_LANE_INVALID"
   | "E_LAND_GATE"
   | "E_CLIMB_DESIGN"
+  | "E_CLIMB_ENV"
   | "E_JEV_KEY"
   | "E_JEV_NETWORK"
   | "E_JEV_RESPONSE"
@@ -28,6 +31,7 @@ export type ErrorCode =
   | "E_IO_PATH"
   | "E_IO_UNEXPECTED"
   | "E_INPUT_INVALID"
+  | "E_ROLE_SCOPE"
   | "E_RUNTIME_TOO_OLD";
 
 /**

package/src/domain/failover.ts

@@ -45,10 +45,18 @@ export function barDims(c: Catalog, rung: string): Dim[] {
  * well: no downgrade.
  */
 export function downgradeDims(c: Catalog, rung: string, standIn: string): Dim[] {
-  const a = valuesOf(c, rung);
+  return downgradeAgainst(valuesOf(c, rung), barDims(c, rung), valuesOf(c, standIn));
+}
+
+/** downgradeDims with the rung's values and bar dims computed once, for a pool of stand-ins. */
+function downgradeAgainst(
+  a: Partial<Record<Dim, number>> | null,
+  dims: Dim[],
+  standIn: Partial<Record<Dim, number>> | null,
+): Dim[] {
   if (!a) return [];
-  const b = valuesOf(c, standIn) ?? {};
-  return barDims(c, rung).filter((d) => (b[d] ?? Number.NEGATIVE_INFINITY) < (a[d] as number));
+  const b = standIn ?? {};
+  return dims.filter((d) => (b[d] ?? Number.NEGATIVE_INFINITY) < (a[d] as number));
 }
 
 /**
@@ -85,11 +93,15 @@ export function rankStandIns(
 ): string[] {
   const from = tryParseRung(rung);
   if (!from) return [];
+  // the rung's own values and bar dims, once for the whole pool
+  const own = valuesOf(c, rung);
+  const dims = barDims(c, rung);
   const fits = [...new Set(pool)].filter((x) => {
     const r = tryParseRung(x);
-    if (!r || r.backend === "claude" || quotaOf(r) === quotaOf(from) || !valuesOf(c, x)) return false;
+    const values = r ? valuesOf(c, x) : null;
+    if (!r || r.backend === "claude" || quotaOf(r) === quotaOf(from) || !values) return false;
     if (costFor(c, billing, x).tier === 1) return false;
-    return downgradeDims(c, rung, x).length === 0;
+    return downgradeAgainst(own, dims, values).length === 0;
   });
   const gap = (x: string) => effortGap(from.effort, tryParseRung(x)?.effort ?? "");
   return fits.sort(

package/src/domain/gate-brief.ts

@@ -0,0 +1,52 @@
+// Plan 23: how a verifier runs a gate, which every verifier gets (its agent file, or its dispatch brief), and
+// the run's own facts a dispatched verifier's brief adds: the items already recorded, the failed ones to
+// re-check first, and the repo's gate environment.
+
+/** A re-check's cap on each command, in minutes: a hung command fails its item, not the verifier. */
+export const RECHECK_COMMAND_MIN = 10;
+
+/** The rules of the gate, one paragraph each. */
+export const VERIFIER_GATE_RULES = [
+  "Run the root gate (the milestone's full check) as one gate item and each per-service acceptance suite as its own item, never as one command: a failure then names its item, and a re-check reruns only that item. Acceptance that builds from HEAD (git archive, a commit's image) is yours: workers do not commit, so they never run it.",
+  "Stay in the foreground until your verdict: no background watcher, and never end your turn while a command runs.",
+  `When the machine, not the work, stops an item (a VPN filter, a Docker client proxy, a dead registry, no DNS), probe it directly, twice, 5 s apart, and if it still fails, reply VERDICT: BLOCKED: environment — <the probe and its output>. That is a blocker for the owner, not a FAIL.`,
+  "Last, when you built Docker images, run docker image prune -f, so the gates of later milestones do not fill the disk.",
+];
+
+/** The marker a verifier brief's catherd section starts with: added once. */
+export const GATE_NOTES_HEADING = "## The gate (catherd)";
+
+/** The run's facts for one verifier dispatch. */
+export interface GateNotes {
+  milestone: string | null;
+  /** the milestone's recorded items, with whether each passed */
+  recorded: { item: string; passed: boolean }[];
+  /** the repo's gate environment, as `NAME=value` or `NAME=$FROM` */
+  env: string[];
+}
+
+/** The section a dispatched verifier's brief ends with (before the reply contract). */
+export function gateNotes(n: GateNotes): string {
+  const failed = n.recorded.filter((r) => !r.passed).map((r) => r.item);
+  const lines = [GATE_NOTES_HEADING, "", ...VERIFIER_GATE_RULES.map((r) => `- ${r}`)];
+  if (n.milestone && n.recorded.length) {
+    lines.push(
+      `- Items already recorded for ${n.milestone}; reuse these names in gate_check, so what passed is carried over: ${n.recorded.map((r) => r.item).join(", ")}.`,
+    );
+    if (failed.length)
+      lines.push(
+        `- This is a re-check. Run the failed items first: ${failed.join(", ")}. Cap each command at ${RECHECK_COMMAND_MIN} minutes; a command that runs longer fails its item (say so), it never holds the gate.`,
+      );
+  }
+  if (n.env.length)
+    lines.push(
+      `- The repo's gate environment is already set in your env (a secret as $NAME of where it came from): ${n.env.join(", ")}.`,
+    );
+  return lines.join("\n");
+}
+
+/** `brief` with the gate notes appended, once: a brief that already has them is kept. */
+export function withGateNotes(brief: string, n: GateNotes): string {
+  if (brief.includes(GATE_NOTES_HEADING)) return brief;
+  return `${brief.trimEnd()}\n\n${gateNotes(n)}\n`;
+}

package/src/domain/hints.ts

@@ -3,11 +3,22 @@ import type { RunRecord } from "./record.ts";
 /** Spec §4.4: what the orchestrator does next, read off one finished record. `dir` is the dispatch folder, relative to the run. */
 export function dispatchHints(r: RunRecord, owns: string[], dir: string): string[] {
   const h: string[] = [];
-  if (r.status === "limit") h.push(`limit: ${r.backend} hit a usage limit on ${r.rung}`);
+  if (r.status === "limit")
+    h.push(
+      r.error?.code === "provider-unavailable"
+        ? `limit: ${r.rung}'s provider is unavailable (${r.error.message}); it fails over as on a usage limit`
+        : `limit: ${r.backend} hit a usage limit on ${r.rung}`,
+    );
   if (r.status === "cli-too-old") h.push(`cli-too-old: ${r.error?.message ?? `upgrade ${r.backend}`}`);
   if (r.status === "failed") h.push(`failed: read ${dir}/stderr`);
   if (r.gitUnavailable) h.push("git-unavailable: changed files unknown");
-  if (r.replyStatus === "refused" || r.replyStatus === "blocked") h.push(`climb: ${r.replyStatus}`);
+  // plan 23: the environment stopped it, and a higher rung would stop the same way: fix it or surface it
+  if (r.environment) h.push(`environment: ${r.environment}`);
+  else if (r.replyStatus === "flaky")
+    h.push(
+      `flaky: ${r.replyWhy || "a check failed, then passed alone"}; rerun it alone, accept it, or climb: your call`,
+    );
+  else if (r.replyStatus === "refused" || r.replyStatus === "blocked") h.push(`climb: ${r.replyStatus}`);
   else if (
     r.status === "ok" &&
     !r.gitUnavailable &&

package/src/domain/host.ts

@@ -0,0 +1,17 @@
+export type OrchestrationHost = "claude-code" | "codex" | "unknown";
+export type KnownHost = Exclude<OrchestrationHost, "unknown">;
+export interface HostSessionRef {
+  host: KnownHost;
+  sessionId: string;
+  hostSessionId: string | null;
+  name: string | null;
+}
+export interface HostContext {
+  host: OrchestrationHost;
+  session: HostSessionRef | null;
+  conflict: string | null;
+}
+export function sessionKey(s: Pick<HostSessionRef, "host" | "sessionId">): string {
+  // a Codex thread is a UUID, whatever its casing: an owner stored before normalization still matches
+  return JSON.stringify([s.host, s.host === "codex" ? s.sessionId.toLowerCase() : s.sessionId]);
+}

package/src/domain/lane.ts

@@ -11,18 +11,47 @@ export interface LaneHeader {
   fastCheck: string | null;
   kind: Kind | null;
   difficulty: Difficulty | null;
+  /** `After: M1.L1, M1.L2`: lanes that must finish first (protocol.next and admission keep the order) */
+  after: string[];
+  /** `Allow: path[:line], …` under the check: hits of the lane's absence check that are allowed exceptions */
+  allow: string[];
 }
 
+/** A lane id in an After: line: Mx.Ly, the shape lanes/<id>.md takes. */
+const LANE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*\.[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** An Allow: entry: a repo-relative path, optionally `:<line>`. */
+const ALLOW_ENTRY = /^([^\s:]+)(?::(\d+))?$/;
+
 const unquote = (s: string) =>
   s
     .trim()
     .replace(/^`+|`+$/g, "")
     .trim();
 
-/** The value of the first `Label:` line, allowing `**Label:**` and `_Label_:` emphasis. */
+/**
+ * The lane's header block, as [start, end) line indexes: the lines under the `# ` title (blank lines right
+ * after it skipped) up to the first blank line or heading. Header lines are read only here, so a body's prose
+ * (`After: the handler returns 404`) is never a header value.
+ */
+export function headerBlock(lines: string[]): [number, number] {
+  const title = lines.findIndex((l) => /^#\s+/.test(l));
+  let start = title + 1;
+  while (start < lines.length && (lines[start] ?? "").trim() === "") start++;
+  let end = start;
+  while (end < lines.length && (lines[end] ?? "").trim() !== "" && !(lines[end] ?? "").startsWith("#")) end++;
+  return [start, end];
+}
+
+/** A header line `Label:`, allowing `**Label:**` and `_Label_:` emphasis; group 1 is its value. */
+export const headerLine = (label: string) => new RegExp(`^\\s*[*_]*${label}[*_]*\\s*:[*_]*\\s*(.*)$`, "i");
+
+/** The value of the first `Label:` line of the header block. */
 function field(text: string, label: string): string | null {
-  const re = new RegExp(`^\\s*[*_]*${label}[*_]*\\s*:[*_]*\\s*(.*)$`, "i");
-  for (const line of text.split("\n")) {
+  const re = headerLine(label);
+  const lines = text.split("\n");
+  const [start, end] = headerBlock(lines);
+  for (const line of lines.slice(start, end)) {
     const m = re.exec(line);
     if (m) return (m[1] ?? "").trim();
   }
@@ -51,15 +80,81 @@ export function parseLaneHeader(text: string): LaneHeader {
   const title = /^#\s+(.+)$/m.exec(text)?.[1]?.trim() ?? null;
   const owns = (field(text, "owns") ?? "").split(",").map(unquote).filter(Boolean).map(normalizeOwned);
   const check = field(text, "fast check");
+  const list = (label: string) => (field(text, label) ?? "").split(",").map(unquote).filter(Boolean);
   return {
     title,
     owns,
     fastCheck: check ? unquote(check) || null : null,
     kind: oneOf(field(text, "kind"), KINDS),
     difficulty: oneOf(field(text, "difficulty"), DIFFICULTIES),
+    after: list("after"),
+    allow: list("allow"),
   };
 }
 
+/** What is wrong with the After: and Allow: entries, one line each; none when they are well formed. */
+function orderProblems(h: LaneHeader): string[] {
+  const out: string[] = [];
+  for (const a of h.after) if (!LANE_ID.test(a)) out.push(`After "${a}" is not a lane id like M1.L1`);
+  for (const a of h.allow) {
+    const m = ALLOW_ENTRY.exec(a);
+    try {
+      if (!m) throw new Error();
+      normalizeOwned(m[1] as string);
+    } catch {
+      out.push(`Allow "${a}" is not a repo path, or path:line`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Spec 1.5 "Lane editing": `write_run_file` refuses a lane whose header values are present but wrong (a Kind
+ * or Difficulty the catalog does not know, an Owns path that leaves the repo, a malformed After: or Allow:),
+ * so a typo is caught when the lane is written, not at preflight. A missing line is left to routing.
+ */
+export function assertLaneValues(text: string, where: string): LaneHeader {
+  let h: LaneHeader;
+  try {
+    h = parseLaneHeader(text);
+  } catch (e) {
+    throw new CatherdError("E_LANE_INVALID", `${where}: ${(e as Error).message}`, {
+      fix: "write Owns: paths like src/foo/ or src/bar.ts",
+    });
+  }
+  const problems: string[] = [];
+  const kind = field(text, "kind");
+  const difficulty = field(text, "difficulty");
+  if (kind !== null && h.kind === null) problems.push(`Kind "${unquote(kind)}" is not one the catalog knows`);
+  if (difficulty !== null && h.difficulty === null)
+    problems.push(`Difficulty "${unquote(difficulty)}" is not one the catalog knows`);
+  problems.push(...orderProblems(h));
+  if (problems.length)
+    throw new CatherdError("E_LANE_INVALID", `${where}: ${problems.join("; ")}`, {
+      fix: `${LANE_HEADER_FIX}; After: M1.L1, M1.L2; Allow: path or path:line`,
+    });
+  return h;
+}
+
+/**
+ * Whether every line a failing check printed is a `path:line` hit its lane allows: an absence check (a grep
+ * that must find nothing) whose only hits are the lane's declared exceptions has passed.
+ */
+export function onlyAllowedHits(lines: string[], allow: string[]): boolean {
+  const hits = lines.map((l) => /^([^\s:]+):(\d+)(?::|$)/.exec(l.trim()));
+  if (allow.length === 0 || hits.length === 0 || hits.some((m) => !m)) return false;
+  return hits.every((m) =>
+    allow.some((entry) => {
+      const [, path, line] = ALLOW_ENTRY.exec(entry) ?? [];
+      if (!path) return false;
+      const file = (m as RegExpExecArray)[1] as string;
+      const at = (m as RegExpExecArray)[2];
+      const inPath = file === path || (path.endsWith("/") && file.startsWith(path));
+      return inPath && (line === undefined || line === at);
+    }),
+  );
+}
+
 /** The fix every lane-header refusal carries: the values the catalog knows. */
 export const LANE_HEADER_FIX = `write the lane's header lines as Kind: ${KINDS.join("|")} and Difficulty: ${DIFFICULTIES.join("|")}`;
 
@@ -78,6 +173,7 @@ export function assertLaneHeader(text: string, where: string): LaneHeader {
   };
   check("Kind", field(text, "kind"), h.kind !== null);
   check("Difficulty", field(text, "difficulty"), h.difficulty !== null);
+  problems.push(...orderProblems(h));
   if (problems.length)
     throw new CatherdError("E_LANE_INVALID", `${where}: ${problems.join("; ")}`, { fix: LANE_HEADER_FIX });
   return h;

package/src/domain/notice.ts

@@ -9,6 +9,7 @@ export type NoticePriority = "later" | "next";
 /** One role's news: it finished (`record`), or an event while it runs (`stall`). */
 export interface Notice {
   kind: "finished" | "stalled";
+  eventId: string;
   runId: string;
   runTitle: string;
   dispatchId: string;
@@ -16,6 +17,8 @@ export interface Notice {
   role: string;
   /** the lane it worked, when it had one: the multi-role preview names it */
   lane: string | null;
+  /** the role's thread, so a fix round resumes it without reading runs.jsonl; null before the CLI named one */
+  thread: string | null;
   rung: string;
   /** the record's status, or for a limit what failover did ("limit on X; failed over to Y"), or the event */
   status: string;
@@ -33,15 +36,19 @@ export const REPLY_CAP = 2_000;
 
 const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
 
+/** `thread: <id>`, or `thread: none` before the CLI named one: every message's first line carries it. */
+const threadWord = (n: Notice): string => `thread: ${n.thread ?? "none"}`;
+
 /** The first line of one role's block: it must stand alone, since the Desktop preview shows only it. */
 export function noticeHeader(n: Notice): string {
   const head = `catherd · ${n.runTitle} · ${n.name} ${n.role} · ${n.rung} · ${n.status}`;
-  if (n.kind === "stalled") return `${head} · running ${n.secs}s`;
+  if (n.kind === "stalled") return `${head} · running ${n.secs}s · ${threadWord(n)}`;
   return [
     head,
     n.replyStatus ? `STATUS: ${n.replyStatus}` : "no STATUS",
     `${n.secs}s`,
     plural(n.changedOwned, "owned file changed", "owned files changed"),
+    threadWord(n),
   ].join(" · ");
 }
 
@@ -62,9 +69,11 @@ const neutral = (s: string) => s.replace(/(cross)-(session)-(message)/gi, "$1 $2
 
 function block(n: Notice): string {
   const call = `run: "${n.runId}", name: "${n.name}"`;
-  if (n.kind === "stalled") return `${noticeHeader(n)}\nPeek: peek(${call})`;
+  if (n.kind === "stalled") return `${noticeHeader(n)}\nPeek: peek(${call})\nEvent: ${n.eventId}`;
   const reply = capNoticeReply(n.reply);
-  return [noticeHeader(n), ...(reply ? [reply] : []), `Record: result(${call})`].join("\n");
+  return [noticeHeader(n), ...(reply ? [reply] : []), `Record: result(${call})`, `Event: ${n.eventId}`].join(
+    "\n",
+  );
 }
 
 /** The preview line of a message that carries several roles: `catherd · <title> · 3 roles finished: …`. */
@@ -75,7 +84,8 @@ function previewOf(ns: Notice[]): string {
     ? `${ns.length} roles finished`
     : `${plural(ns.length, "role", "roles")} to look at`;
   const each = ns.map(
-    (n) => `${n.lane ?? n.name} ${n.kind === "stalled" ? "stalled" : n.status.split(";")[0]}`,
+    (n) =>
+      `${n.lane ?? n.name} ${n.kind === "stalled" ? "stalled" : n.status.split(";")[0]} (${threadWord(n)})`,
   );
   return `catherd · ${where} · ${what}: ${each.join(", ")}`;
 }

package/src/domain/profile-rules.ts

@@ -1,3 +1,4 @@
+import type { OrchestrationHost } from "./host.ts";
 import {
   type Catalog,
   type Dim,
@@ -20,10 +21,25 @@ import { tryParseRung } from "./ids.ts";
 import { DIFFICULTIES, KINDS } from "./lane.ts";
 import { type Profile, type ProfileDoc, unknownValues } from "./profile.ts";
 import { DEFAULT_ACCESS, ROLES, type Role } from "./roles.ts";
-import { candidates, clearsBar, type RoutingProfile } from "./select.ts";
+import {
+  type Candidate,
+  candidates,
+  clearsBar,
+  defaultLadder,
+  type RoutingProfile,
+  select,
+} from "./select.ts";
 
 export { quotaOf };
 
+/**
+ * `reach`: also warn about the kinds and difficulties no worker rung clears (spec 1.5 plan 24), which only an
+ * explicit `profile validate` asks for.
+ */
+export interface ValidateOptions {
+  reach?: boolean;
+}
+
 /** One finding of `validate`: where in the profile, what is wrong, and the action that fixes it. */
 export interface Issue {
   path: string;
@@ -113,7 +129,8 @@ export const routingProfileOf = (p: Profile, role: Role): RoutingProfile => ({
 /**
  * Whether a rung's scores are catherd's guess: borrowed through a treat-like, filled by an inferred stand-in
  * (spec 1.2 §6.1), or only `inferred` ones. `note` says what a treat-like lends: "scores borrowed from X"
- * when the rung has no value of its own, else the dimensions it borrows (a rung a sync scored on some).
+ * when every value is borrowed, else the dimensions it borrows (a rung a sync scored on some); and (1.2
+ * minor) what each inferred stand-in lends: "honesty inferred from Y".
  */
 export function inferredScores(
   c: Catalog,
@@ -124,9 +141,17 @@ export function inferredScores(
   const records = Object.values(s.records);
   const guessed =
     s.via !== null || s.inferred.length > 0 || records.every((r) => r.confidence === "inferred");
-  const all = s.borrowed.length + s.inferred.length === records.length;
-  const note = s.via ? `${all ? "scores" : s.borrowed.join(", ")} borrowed from ${s.via}` : null;
-  return { inferred: guessed, via: s.via, note };
+  const all = s.borrowed.length === records.length;
+  const byStandIn = new Map<string, Dim[]>();
+  for (const d of s.inferred) {
+    const like = s.standIns[d] as string;
+    byStandIn.set(like, [...(byStandIn.get(like) ?? []), d]);
+  }
+  const parts = [
+    ...(s.via ? [`${all ? "scores" : s.borrowed.join(", ")} borrowed from ${s.via}`] : []),
+    ...[...byStandIn].map(([like, dims]) => `${dims.join(", ")} inferred from ${like}`),
+  ];
+  return { inferred: guessed, via: s.via, note: parts.length ? parts.join("; ") : null };
 }
 
 /**
@@ -145,6 +170,8 @@ export function validateProfile(
   c: Catalog,
   backends: readonly string[],
   doc?: ProfileDoc,
+  host: OrchestrationHost = "unknown",
+  o: ValidateOptions = {},
 ): Validation {
   const errors: Issue[] = [];
   const warnings: Issue[] = [];
@@ -170,7 +197,16 @@ export function validateProfile(
         message: `${role} runs ${rc.access}; catherd's default for it is ${DEFAULT_ACCESS[role]}`,
       });
     if (!rc.enabled) continue;
+    // spec §5: network: false takes a workspace-write role's network grants; read-only and full have none to take
+    if (rc.network === false && rc.access !== "workspace-write")
+      warnings.push({
+        path: `${at}.network`,
+        message: `network: false does nothing here: it applies to workspace-write roles, and ${role} runs ${rc.access}`,
+        fix: `catherd profile set ${at}.network null`,
+      });
     for (const rung of rc.rungs) {
+      const native = nativeClaudeIssue(rung, host, `${at}.rungs`);
+      if (native) errors.push(native);
       const r = tryParseRung(rung);
       if (!r) {
         errors.push({
@@ -214,7 +250,7 @@ export function validateProfile(
       if (!scoresOf(c, info.canonical))
         warnings.push({
           path: `${at}.rungs`,
-          message: `${rung} is unscored and no rung is near enough to stand in for it: routing skips it`,
+          message: `${rung} is unscored and no rung is near enough to stand in for it: routing skips it${rung === rc.defaultRung ? `; it is the ${role}'s default rung, so ${defaultFallback(c, p, role)}` : ""}`,
           fix: TREAT_LIKE_FIX(rung),
         });
     }
@@ -253,27 +289,53 @@ export function validateProfile(
             path: `${at}.rungs`,
             message: `${x.rung} clears no routing bar, so a lane starts on it only as the role's default rung and never climbs onto it`,
           });
-    // spec 1.2 §5.2: the logic and hard bars sit at the 60th and 75th percentiles, which a cost-minded ladder
-    // may never reach, and those lanes start at the default rung and climb; only a kind whose every bar the
-    // ladder misses routes blind (plan 14 Ruling 12)
+    // spec 1.5 plan 24: every kind and difficulty no worker rung clears, in one warning; those lanes start at the
+    // default rung (or an easier difficulty's start) and climb only onto rungs at least as strong. Only an
+    // explicit validate says it (Ruling 3): the shipped bars put logic and hard above every Sol rung, the
+    // owner's call, so every save and doctor would repeat it
+    if (o.reach && role === "worker" && usable.length > 1) {
+      const unreached = unreachable(c, usable);
+      if (unreached.length)
+        warnings.push({
+          path: `${at}.rungs`,
+          message: `no worker rung clears ${unreached.join("; ")}: those lanes start at the default rung and climb only onto rungs at least as strong (route names the closest)`,
+        });
+    }
+    // spec 1.5 plan 24: a quota whose rungs never start a lane sits idle but for climbs (the identity run's Go).
+    // Only the worker routes lanes and climbs (Ruling 9); another role routes lane-less to one rung, so a rung
+    // on a second quota is a deliberate spare there, not an idle quota (final review Important 4, Ruling 8)
     if (role === "worker" && usable.length > 1) {
-      const blind = KINDS.filter((k) => !DIFFICULTIES.some((d) => usable.some((x) => clearsBar(c, x, k, d))));
-      if (blind.length)
+      const idle = idleQuotas(c, p, role, usable);
+      for (const [q, rungs] of idle) {
+        // the billing key, not the quota, is what billing is set on (`claude:` and `claude-code:` share one)
+        const keys = [...new Set(usable.filter((x) => rungs.includes(x.rung)).map((x) => x.info.key))];
         warnings.push({
           path: `${at}.rungs`,
-          message: `no worker rung clears any bar for ${blind.join(", ")}; those lanes always start at the default rung`,
+          message: `${q} never starts a ${role} lane: ${rungs.join(", ")} ${rungs.length > 1 ? "run" : "runs"} only on a climb, since another rung starts every lane`,
+          fix: `check ${keys.map((k) => `billing.${k}`).join(" and ")} (a metered rung starts only where nothing paid from a plan clears the bar), or order ${at}.rungs so its rungs come first among equals`,
         });
+      }
     }
   }
 
   const ladders = new Set(ROLES.filter((r) => p.roles[r].enabled).flatMap((r) => p.roles[r].rungs));
-  // the stand-ins catherd could run here, for the fixes below
+  // the stand-ins the fixes below may suggest: on a backend catherd runs and the profile already names (a
+  // ladder or a failover entry), never one this machine may not have (Cursor on a machine without it); a
+  // native claude: rung names claude-code too, the same Claude Code CLI
+  const named = new Set(
+    [...ladders, ...Object.keys(p.failover), ...Object.values(p.failover)].flatMap((x) => {
+      const b = tryParseRung(x)?.backend;
+      return b === undefined ? [] : b === "claude" ? [b, "claude-code"] : [b];
+    }),
+  );
   const pool = catalogRungs(c).filter((x) => {
     const r = tryParseRung(x);
-    return r !== null && backends.includes(r.backend);
+    return r !== null && backends.includes(r.backend) && named.has(r.backend);
   });
   for (const [from, to] of Object.entries(p.failover)) {
     const at = `failover.${from}`;
+    const native = ladders.has(from) ? nativeClaudeIssue(to, host, at) : null;
+    if (native) errors.push(native);
     const a = tryParseRung(from);
     const b = tryParseRung(to);
     if (!a || !b) {
@@ -288,7 +350,8 @@ export function validateProfile(
       errors.push({ path: at, message: `stand-in ${to}: catherd cannot run ${b.backend} yet` });
       continue;
     }
-    if (!scoresOf(c, rungInfo(c, to).canonical))
+    const unscored = !scoresOf(c, rungInfo(c, to).canonical);
+    if (unscored)
       warnings.push({
         path: at,
         message: `stand-in ${to} is unscored and no rung is near enough to stand in for it`,
@@ -301,7 +364,8 @@ export function validateProfile(
         fix: "name a stand-in on another backend or plan",
       });
     const ranked = rankStandIns(c, p.billing, from, pool);
-    const down = downgradeDims(c, from, to);
+    // an unscored stand-in has its own warning above: no "downgrade" on every bar dim besides
+    const down = unscored ? [] : downgradeDims(c, from, to);
     if (down.length)
       warnings.push({
         path: at,
@@ -327,3 +391,52 @@ export function validateProfile(
     warnings.push({ path: x.path, message: standInMessage(x), fix: SUGGEST_FIX(x.rungs[0] as string) });
   return { errors, warnings };
 }
+
+/** The role's default rung when it is unscored: what routing starts on instead. */
+function defaultFallback(c: Catalog, p: Profile, role: Role): string {
+  try {
+    return `routing falls back to ${defaultLadder(c, routingProfileOf(p, role), role).rung}`;
+  } catch {
+    return "routing has no rung to fall back to";
+  }
+}
+
+/** `repo_code logic, hard` per kind: the kinds and difficulties no rung of `usable` clears. */
+function unreachable(c: Catalog, usable: Candidate[]): string[] {
+  return KINDS.flatMap((k) => {
+    const ds = DIFFICULTIES.filter((d) => !usable.some((x) => clearsBar(c, x, k, d)));
+    return ds.length ? [`${k} ${ds.join(", ")}`] : [];
+  });
+}
+
+/**
+ * Spec 1.5 plan 24: each quota of the role's usable rungs that no kind and difficulty (nor a lane-less route)
+ * ever starts on, whichever quota the run has used least, with its rungs.
+ */
+function idleQuotas(c: Catalog, p: Profile, role: Role, usable: Candidate[]): [string, string[]][] {
+  const quotas = [...new Set(usable.map((x) => quotaOf(x.info.parsed)))];
+  if (quotas.length < 2) return [];
+  const starts = new Set<string>();
+  // every quota gets its turn as the least used, so a tie it could win counts as a start
+  for (const fresh of [null, ...quotas]) {
+    const usage = Object.fromEntries(quotas.map((q) => [q, q === fresh ? 0 : 1]));
+    const rp = { ...routingProfileOf(p, role), usage };
+    starts.add(defaultLadder(c, rp, role).rung);
+    for (const k of KINDS) for (const d of DIFFICULTIES) starts.add(select(c, rp, role, k, d).rung);
+  }
+  const started = new Set(usable.filter((x) => starts.has(x.rung)).map((x) => quotaOf(x.info.parsed)));
+  return quotas
+    .filter((q) => !started.has(q))
+    .map((q) => [q, usable.filter((x) => quotaOf(x.info.parsed) === q).map((x) => x.rung)]);
+}
+
+export function nativeClaudeIssue(rung: string, host: OrchestrationHost, path: string): Issue | null {
+  const r = tryParseRung(rung);
+  return host !== "claude-code" && r?.backend === "claude"
+    ? {
+        path,
+        message: `${rung}: native Claude subagents require the claude-code orchestration host`,
+        fix: `use claude-code:${r.model}#${r.effort} for headless execution, or --host claude-code`,
+      }
+    : null;
+}