catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/domain/failover.ts

@@ -1,8 +1,6 @@
-import { billingKeyOf, type Catalog, DIMS, type Dim, rungInfo, scoresOf } from "./catalog.ts";
+import { billingKeyOf, type Catalog, pairOf, rungInfo } from "./catalog.ts";
 import { type BillingMode, compareCost, type Cost, costOf, DEFAULT_BILLING } from "./cost.ts";
 import { type Rung, tryParseRung } from "./ids.ts";
-import { DIFFICULTIES, KINDS } from "./lane.ts";
-import { EFFORT_ORDER } from "./sources.ts";
 
 /**
  * Spec §7.1 and §4.5: a stand-in on the same quota would be out of quota too. The billing key names the
@@ -16,66 +14,35 @@ export function claudeBilled(rung: string): boolean {
   return r !== null && quotaOf(r) === "claude-code";
 }
 
-/** A rung's scores by dim, its own or borrowed through a treat-like; null when unscored or not a rung. */
-export function valuesOf(c: Catalog, rung: string): Partial<Record<Dim, number>> | null {
-  try {
-    return scoresOf(c, rungInfo(c, rung).canonical)?.values ?? null;
-  } catch {
-    return null;
-  }
-}
+/** A rung's intelligence index; null when it is not a rung or not indexed. */
+export const intelligenceOf = (c: Catalog, rung: string): number | null =>
+  pairOf(c, rung)?.intelligence ?? null;
 
-/** The dims used by the routing bars (kind × difficulty) the rung clears: what makes it fit its lanes. */
-export function barDims(c: Catalog, rung: string): Dim[] {
-  const v = valuesOf(c, rung);
-  if (!v) return [];
-  const used = new Set<Dim>();
-  for (const kind of KINDS)
-    for (const d of DIFFICULTIES) {
-      const bar = Object.entries(c.bars[kind][d]).filter(([, min]) => min !== undefined) as [Dim, number][];
-      if (bar.every(([dim, min]) => (v[dim] ?? Number.NEGATIVE_INFINITY) >= min))
-        for (const [dim] of bar) used.add(dim);
-    }
-  return DIMS.filter((d) => used.has(d));
+/** Spec 1.1 §11: `standIn` is a downgrade when the rung is indexed and the stand-in is not, or is less intelligent. */
+export function downgrade(c: Catalog, rung: string, standIn: string): boolean {
+  const a = intelligenceOf(c, rung);
+  const b = intelligenceOf(c, standIn);
+  return a !== null && (b === null || b < a);
 }
 
-/**
- * Spec 1.1 §11: the dims, among those the rung's bars use, on which `standIn` scores below `rung` (a
- * missing score counts as below). Empty means the stand-in clears every bar the rung clears, at least as
- * well: no downgrade.
- */
-export function downgradeDims(c: Catalog, rung: string, standIn: string): Dim[] {
-  const a = valuesOf(c, rung);
-  if (!a) return [];
-  const b = valuesOf(c, standIn) ?? {};
-  return barDims(c, rung).filter((d) => (b[d] ?? Number.NEGATIVE_INFINITY) < (a[d] as number));
-}
-
-/**
- * Spec 1.1 §11 "the ladder goes down": the dims both rungs are scored on where `upper` (the later rung)
- * scores below `lower`, when it scores above it on none of them. Empty when it does not go down.
- */
-export function ladderDropDims(c: Catalog, lower: string, upper: string): Dim[] {
-  const a = valuesOf(c, lower);
-  const b = valuesOf(c, upper);
-  if (!a || !b) return [];
-  const shared = DIMS.filter((d) => a[d] !== undefined && b[d] !== undefined);
-  if (shared.some((d) => (b[d] as number) > (a[d] as number))) return [];
-  return shared.filter((d) => (b[d] as number) < (a[d] as number));
+/** Spec 1.1 §11 "the ladder goes down": the later rung (`upper`) is less intelligent than `lower`. */
+export function ladderDrop(c: Catalog, lower: string, upper: string): boolean {
+  const a = intelligenceOf(c, lower);
+  const b = intelligenceOf(c, upper);
+  return a !== null && b !== null && b < a;
 }
 
 const costFor = (c: Catalog, billing: Partial<Record<string, BillingMode>>, rung: string): Cost => {
   const info = rungInfo(c, rung);
-  return costOf(info.family, info.parsed.effort, billing[info.key] ?? DEFAULT_BILLING[info.key]);
+  return costOf(info.family, info.pair, info.parsed.effort, billing[info.key] ?? DEFAULT_BILLING[info.key]);
 };
 
 /**
  * Spec 1.1 §11: the rungs of `pool` that can stand in for `rung`, best first. A stand-in is on another
- * quota, scored, paid from a plan or subscription under `billing` (a metered one spends money nobody chose
- * to), startable by `dispatch` (not a native `claude:` subagent), and no downgrade on the rung's bar dims.
- * Claude-billed stand-ins rank last, then the effort nearest the rung's own (a model's efforts carry one
- * another's values as `adjacent`, spec 1.2 §4.3, so the cheapest would otherwise be its lowest effort; plan 14
- * Ruling 4), then the cheapest.
+ * quota, indexed, paid from a plan or subscription under `billing` (a metered one spends money nobody chose
+ * to), startable by `dispatch` (not a native `claude:` subagent), and never less intelligent than the rung
+ * (a rung with no index of its own keeps every stand-in). Claude-billed stand-ins rank last, then the
+ * nearest intelligence above the rung's own, then the cheapest.
  */
 export function rankStandIns(
   c: Catalog,
@@ -85,13 +52,15 @@ export function rankStandIns(
 ): string[] {
   const from = tryParseRung(rung);
   if (!from) return [];
+  const own = intelligenceOf(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 i = r ? intelligenceOf(c, x) : null;
+    if (!r || r.backend === "claude" || quotaOf(r) === quotaOf(from) || i === null) return false;
     if (costFor(c, billing, x).tier === 1) return false;
-    return downgradeDims(c, rung, x).length === 0;
+    return own === null || i >= own;
   });
-  const gap = (x: string) => effortGap(from.effort, tryParseRung(x)?.effort ?? "");
+  const gap = (x: string) => (own === null ? 0 : (intelligenceOf(c, x) as number) - own);
   return fits.sort(
     (a, b) =>
       Number(claudeBilled(a)) - Number(claudeBilled(b)) ||
@@ -101,35 +70,28 @@ export function rankStandIns(
   );
 }
 
-/** How many effort steps apart two efforts are; an effort that is no effort word (`default`) is far from all. */
-function effortGap(a: string, b: string): number {
-  const i = (EFFORT_ORDER as readonly string[]).indexOf(a);
-  const j = (EFFORT_ORDER as readonly string[]).indexOf(b);
-  if (a === b) return 0;
-  return i < 0 || j < 0 ? EFFORT_ORDER.length : Math.abs(i - j);
-}
-
-/** How a family's `on` key or a model id's prefix maps to the backend that runs it. */
+/** How a family's `on` key maps to the backend that runs it. */
 const BACKEND_OF_KEY: Record<string, string> = { "opencode-go": "opencode" };
 
 /**
- * Every rung the catalog knows how to name: each shipped family's model on each backend at each effort (at
- * `#default` when it has none),
- * each listed model at each effort, and each treat-like whose model is an opencode id (`opencode-go/…`,
- * `opencode/…`), such as the shipped Kimi K3 stand-in. Sorted, without duplicates.
+ * Every indexed rung catherd can name: each shipped family's model on each backend at each effort the index
+ * (or the backend's listing) gives it, and each listed model at each listed effort. Sorted, without duplicates.
  */
-export function catalogRungs(c: Catalog): string[] {
+export function catalogPairs(c: Catalog): string[] {
   const out = new Set<string>();
+  const add = (backend: string, model: string, efforts: readonly string[]) => {
+    for (const e of [...efforts, "default"]) {
+      const rung = `${backend}:${model}#${e}`;
+      if (pairOf(c, rung)) out.add(rung);
+    }
+  };
   for (const f of c.families)
     for (const [key, m] of Object.entries(f.on)) {
       if (!m) continue;
-      // a model with no effort has one rung, #default (Claude Code's Haiku, Cursor's Composer; spec 1.3 §7.1)
-      for (const e of m.efforts.length ? m.efforts : ["default"])
-        out.add(`${BACKEND_OF_KEY[key] ?? key}:${m.id}#${e}`);
+      const backend = BACKEND_OF_KEY[key] ?? key;
+      add(backend, m.id, rungInfo(c, `${backend}:${m.id}#default`).efforts);
     }
   for (const [backend, l] of Object.entries(c.listed))
-    for (const m of l.models) for (const e of m.efforts) out.add(`${backend}:${m.id}#${e}`);
-  for (const canonical of Object.keys(c.treatLike))
-    if (/^opencode(-go)?\//.test(canonical)) out.add(`opencode:${canonical}`);
+    for (const m of l.models) add(backend, m.id, m.efforts);
   return [...out].sort();
 }

package/src/domain/findings.ts

@@ -0,0 +1,47 @@
+import type { Finding } from "./run-events.ts";
+
+const LINE = /^\s*(?:[-*]\s+|\d+[.)]\s+)?\**(BLOCKER|BUG|NIT)\b\**\s*:?\s*(.*)$/;
+/** What a reviewer writes where it has nothing to report: `BUG: none`, `NIT n/a`, a lone dash. */
+const NOTHING = /^(?:none|n\/a|nil|no findings?|clean|[-—–]+)\.?\**$/i;
+const PATH = /^[`'"(]*((?:\.{0,2}\/)?[\w@~.+-]+(?:\/[\w@~.+-]+)*)(?::\d+(?:[-:]\d+)?)?[`'"),;:]*$/;
+
+/**
+ * The first `path:line` or `path` token of a finding's first words (a reviewer writes
+ * `BLOCKER file:line — problem — fix`), or null: a path has a `/` or an extension.
+ */
+export function fileOf(text: string): string | null {
+  for (const tok of text.trim().split(/\s+/).slice(0, 4)) {
+    if (/^[—–-]+$/.test(tok)) return null;
+    const p = PATH.exec(tok)?.[1];
+    if (p && (p.includes("/") || /\.[A-Za-z]\w*$/.test(p))) return p;
+  }
+  return null;
+}
+
+/** A reviewer's reply as findings, in order: its BLOCKER, BUG and NIT lines, as written; "none" lines left out. */
+export function parseFindings(reply: string): Finding[] {
+  const out: Finding[] = [];
+  for (const line of reply.split("\n")) {
+    const m = LINE.exec(line);
+    if (!m) continue;
+    const rest = (m[2] ?? "").trim();
+    if (!rest || NOTHING.test(rest)) continue;
+    out.push({ label: m[1] as Finding["label"], text: line.trim(), file: fileOf(rest) });
+  }
+  return out;
+}
+
+/** The lines a failing verifier lists below its VERDICT line, as BLOCKERs: what the next fix round starts from. */
+export function parseFailLines(reply: string, max = 12): Finding[] {
+  const lines = reply.split("\n").map((l) => l.trim());
+  const at = lines.findIndex((l) => l !== "");
+  return lines
+    .slice(at + 1)
+    .filter((l) => l !== "" && !/^STATUS:/i.test(l))
+    .slice(0, max)
+    .map((l) => ({
+      label: "BLOCKER" as const,
+      text: l.replace(/^(?:[-*]\s+|\d+[.)]\s+)/, ""),
+      file: fileOf(l.replace(/^(?:[-*]\s+|\d+[.)]\s+)/, "").replace(/^\**FAIL\**:?\s*/i, "")),
+    }));
+}

package/src/domain/gate-brief.ts

@@ -0,0 +1,53 @@
+// 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.",
+  "Run the milestone's full check with gate_run (or catherd gate run), on the committed HEAD, never by hand: catherd runs it detached under the verifier lock, reruns a failure with new lines once, scans the run's commits for secrets and records the result, and land reads that record. If it answers running, call it again. When it fails and no baseline exists, it says how to record the base's own failures from a checkout of the base.",
+  "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/ids.ts

@@ -11,8 +11,8 @@ export function assertId(kind: string, value: string): string {
   return value;
 }
 
-/** The backends that run as a process through a `BackendAdapter` (spec 1.3: cursor, grok and antigravity). */
-export const ADAPTER_IDS = ["codex", "claude-code", "opencode", "cursor", "grok", "antigravity"] as const;
+/** The backends that run as a process through a `BackendAdapter`. */
+export const ADAPTER_IDS = ["codex", "claude-code", "opencode", "cursor"] as const;
 
 /** `claude` is the native Claude Code subagent path (no process); the rest are adapters. */
 const RUNG_BACKENDS = [...ADAPTER_IDS, "claude"] as const;
@@ -56,8 +56,19 @@ export function tryParseRung(s: string): Rung | null {
   }
 }
 
+/** Reasoning efforts from least to most; a rung's effort that is none of these (`default`) cannot be ranked. */
+export const EFFORT_ORDER = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"] as const;
+export type EffortWord = (typeof EFFORT_ORDER)[number];
+
+/** Index in `EFFORT_ORDER`; -1 when `e` is not an effort word. */
+export const effortRank = (e: string): number => (EFFORT_ORDER as readonly string[]).indexOf(e);
+
 export const formatRung = (r: Rung): string => `${r.backend}:${r.model}#${r.effort}`;
 
+/** Spec 2.0 decision 12: the daemon runs every role headless, so a native `claude:` rung runs as `claude-code:`. */
+export const headlessRung = (rung: string): string =>
+  rung.startsWith("claude:") ? `claude-code:${rung.slice("claude:".length)}` : rung;
+
 const B32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 
 let lastTime = -1;

package/src/domain/jev.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { BLOCKED_REASONS } from "./blocked.ts";
 import { type Difficulty, KINDS, type Kind, parseLaneHeader } from "./lane.ts";
 import { scrubKeyShapes, scrubSecretAssignments } from "./secrets.ts";
 
@@ -29,6 +30,12 @@ const RouteRuleSchema = z.object({
   /** exactly two levels each, in order: copy then build, logic then hard */
   trackA: z.array(z.string()).length(2),
   trackB: z.array(z.string()).length(2),
+  /** a noul answer at or above this is a yes */
+  noulMin: z.number().min(0).max(1),
+  /** a yes to any of these lifts the lane to at least logic */
+  floorLogic: z.array(z.string()),
+  /** a yes to any of these holds the lane at build; the floor wins */
+  capBuild: z.array(z.string()),
 });
 export type RouteRule = z.infer<typeof RouteRuleSchema>;
 const VerdictRuleSchema = z.object({ min: z.number().min(0).max(1), fallback: z.string() });
@@ -38,9 +45,16 @@ export const JevFileSchema = z.looseObject({
   schema: z.literal(1),
   model: z.string(),
   sets: z.object({
-    "route-v2": z.object({ questions: z.record(z.string(), QuestionSchema), rule: RouteRuleSchema }),
+    "route-v2": z
+      .object({ questions: z.record(z.string(), QuestionSchema), rule: RouteRuleSchema })
+      .superRefine((set, ctx) => {
+        for (const id of [...set.rule.floorLogic, ...set.rule.capBuild])
+          if (set.questions[id]?.type !== "noul")
+            ctx.addIssue({ code: "custom", message: `${id} is no noul question of route-v2` });
+      }),
     finding: z.object({ questions: z.record(z.string(), QuestionSchema), rule: VerdictRuleSchema }),
     "same-defect": z.object({ questions: z.record(z.string(), QuestionSchema), rule: VerdictRuleSchema }),
+    stop: z.object({ questions: z.record(z.string(), QuestionSchema), rule: VerdictRuleSchema }),
   }),
 });
 export type JevFile = z.infer<typeof JevFileSchema>;
@@ -50,6 +64,7 @@ export type SetName = keyof JevFile["sets"];
 export const VERDICT_OPTIONS = {
   finding: ["design", "code", "unclear"],
   "same-defect": ["yes", "no"],
+  stop: [...BLOCKED_REASONS, "other"],
 } as const;
 
 /** JSON with object keys sorted at every depth, so equal data always hashes the same. */
@@ -199,7 +214,7 @@ export interface RouteJudgement {
  * different option counts; the rule reads probabilities instead: the kind at p_max ≥ kindMin, the track
  * when the summed probability of its levels reaches trackMin, and neither in between (the dead band).
  */
-export function judgeRoute(rule: RouteRule, answers: JevAnswers): RouteJudgement {
+function decideRoute(rule: RouteRule, answers: JevAnswers): RouteJudgement {
   const k = answers.kind;
   const d = answers.difficulty;
   const nouls: Record<string, number> = {};
@@ -252,6 +267,36 @@ export function judgeRoute(rule: RouteRule, answers: JevAnswers): RouteJudgement
   };
 }
 
+/**
+ * `decideRoute`, then Jev's yes/no answers (decision 11): a yes to a `floorLogic` question lifts the lane
+ * to logic (hard stays hard), else a yes to a `capBuild` question holds it at build (copy stays copy). The
+ * floor wins, and both apply in the dead band. The reason names the answer only when the difficulty moved.
+ */
+export function judgeRoute(rule: RouteRule, answers: JevAnswers): RouteJudgement {
+  const j = decideRoute(rule, answers);
+  const yes = (ids: string[]) => ids.find((id) => (j.nouls[id] ?? 0) >= rule.noulMin);
+  const lift = yes(rule.floorLogic);
+  const hold = lift === undefined ? yes(rule.capBuild) : undefined;
+  const now: Difficulty | null =
+    lift !== undefined
+      ? j.difficulty === "hard"
+        ? "hard"
+        : "logic"
+      : hold !== undefined
+        ? j.difficulty === "copy"
+          ? "copy"
+          : "build"
+        : j.difficulty;
+  if (now === j.difficulty) return j;
+  const [what, id] = lift !== undefined ? ["floor logic", lift] : ["cap build", hold ?? ""];
+  return {
+    ...j,
+    track: now === "logic" || now === "hard" ? "B" : "A",
+    difficulty: now,
+    rule: `${j.rule}; ${what}: ${id} ${j.nouls[id]}`,
+  };
+}
+
 export interface Verdict<T extends string> {
   value: T;
   /** the chosen answer's probability, when Jev answered */

package/src/domain/judge.ts

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import { BLOCKED_LINE } from "./blocked.ts";
+
+export const JUDGE_KINDS = ["triage", "question", "unexpected", "rules"] as const;
+export type JudgeKind = (typeof JUDGE_KINDS)[number];
+
+/** What a judge call is given: its kind, the unit it is about, a context text and the numbered findings. */
+export interface JudgeInput {
+  id: string;
+  kind: JudgeKind;
+  unit: string;
+  context: string;
+  findings: string[];
+  lanes: { id: string; owns: string[] }[];
+}
+
+const why = z.string();
+
+/** A finished run's rules review proposes at most this many changes to the standing rules (plan 34). */
+export const MAX_RULE_CHANGES = 5;
+export const RuleChangeSchema = z.object({ op: z.enum(["add", "remove"]), text: z.string().min(1), why });
+export type RuleChange = z.infer<typeof RuleChangeSchema>;
+
+export const JudgeDecisionSchema = z.discriminatedUnion("verb", [
+  z.object({
+    verb: z.literal("route"),
+    routes: z.array(z.object({ finding: z.number().int().min(1), to: z.string(), why })),
+  }),
+  z.object({ verb: z.literal("answer"), answer: z.string() }),
+  z.object({ verb: z.literal("ask_owner"), question: z.string() }),
+  z.object({ verb: z.literal("park"), question: z.string() }),
+  z.object({ verb: z.literal("retry"), why }),
+  z.object({ verb: z.literal("climb"), why }),
+  z.object({ verb: z.literal("skip"), why }),
+  z.object({ verb: z.literal("rules"), changes: z.array(RuleChangeSchema) }),
+]);
+export type JudgeDecision = z.infer<typeof JudgeDecisionSchema>;
+
+export const judgeName = (id: string): string => `judge-${id}`;
+
+/** The judge's reply contract, appended to every judge brief (spec 2.0 decision 3). */
+export const JUDGE_CONTRACT = [
+  "Your first line is DECISION: <verb>, one of the verbs your brief lists. Then, by verb:",
+  "- route: one line per finding, ROUTE <n> -> <lane id>|architect|dismiss — <why>",
+  "- answer: ANSWER: <the answer the worker needs, from the plan and the code>",
+  "- ask_owner or park: QUESTION: <one question only the owner can answer>",
+  "- retry, climb or skip: WHY: <one line>",
+  "- rules: up to five lines, ADD <a one-line rule, with a [role, …] tag when it is not for every role> — <the event it comes from>, or REMOVE <the text of one line of knowledge.md> — <why>; no line when nothing should change",
+  `Decide only from what the brief and the run's files show. The last line of your reply is: STATUS: complete — <one line why>. ${BLOCKED_LINE}`,
+].join("\n");
+
+/** The verbs each kind of call may answer with. */
+export const JUDGE_VERBS: Record<JudgeKind, readonly JudgeDecision["verb"][]> = {
+  triage: ["route"],
+  question: ["answer", "ask_owner"],
+  unexpected: ["retry", "climb", "skip", "park"],
+  rules: ["rules"],
+};
+
+/** A line without the emphasis a model puts around it (`**DECISION: retry**`, backticks). */
+const plain = (l: string): string => l.trim().replace(/^[*_`\s]+|[*_`\s]+$/g, "");
+const STATUS = /^STATUS:\s*(complete|partial|blocked|refused|flaky)\b/i;
+const RULE_LINE = /^\s*(?:[-*]|\d+[.)])?\s*\**(ADD|REMOVE)\**:?\s+(.+)$/;
+const ROUTE = /^[-*\s]*ROUTE\s+(\d+)\s*(?:->|→)\s*(\S+)\s*(?:—|–|-|:)?\s*(.*)$/;
+
+/** The text after `label:` on its line and the lines under it, up to the STATUS line. */
+function section(lines: string[], label: string): string | null {
+  const at = lines.findIndex((l) => new RegExp(`^${label}:`, "i").test(plain(l)));
+  if (at < 0) return null;
+  const rest = [plain(lines[at] as string).slice(label.length + 1)];
+  for (const l of lines.slice(at + 1)) {
+    if (STATUS.test(plain(l))) break;
+    rest.push(l.trim());
+  }
+  return rest.join("\n").trim();
+}
+
+/** The judge's decision, or null when the reply is not one its kind allows (the daemon asks once more). */
+export function parseJudgeReply(reply: string, kind: JudgeKind): JudgeDecision | null {
+  const lines = reply.split("\n");
+  const first = lines.map(plain).find(Boolean) ?? "";
+  const verb = /^DECISION:\s*(\w+)\s*$/i.exec(first)?.[1]?.toLowerCase();
+  if (!verb || !(JUDGE_VERBS[kind] as readonly string[]).includes(verb)) return null;
+  const decision = ((): unknown => {
+    switch (verb) {
+      case "route": {
+        const routes = lines.flatMap((l) => {
+          const m = ROUTE.exec(plain(l));
+          return m ? [{ finding: Number(m[1]), to: m[2] as string, why: (m[3] ?? "").trim() }] : [];
+        });
+        return routes.length ? { verb, routes } : null;
+      }
+      case "answer": {
+        const answer = section(lines, "ANSWER");
+        return answer ? { verb, answer } : null;
+      }
+      case "ask_owner":
+      case "park": {
+        const question = section(lines, "QUESTION");
+        return question ? { verb, question } : null;
+      }
+      case "rules": {
+        const changes = lines.flatMap((l) => {
+          const m = RULE_LINE.exec(l);
+          if (!m) return [];
+          const rest = (m[2] as string).trim();
+          const at = rest.lastIndexOf(" — ");
+          return [
+            {
+              op: (m[1] as string).toLowerCase(),
+              text: (at < 0 ? rest : rest.slice(0, at)).trim(),
+              why: at < 0 ? "" : rest.slice(at + 3).trim(),
+            },
+          ];
+        });
+        return { verb, changes: changes.slice(0, MAX_RULE_CHANGES) };
+      }
+      default:
+        return { verb, why: section(lines, "WHY") ?? "" };
+    }
+  })();
+  const parsed = JudgeDecisionSchema.safeParse(decision);
+  return parsed.success ? parsed.data : null;
+}