catherd-cli 1.4.0 → 1.5.0

package/src/domain/brief.ts

@@ -0,0 +1,91 @@
+import { replyContract } from "./role-prompts.ts";
+import { ROLE_MCP_SERVER, roleMcpTools } from "./role-tools.ts";
+import type { Role } from "./roles.ts";
+
+/** What admission adds to a role's brief, besides its reply contract (spec 1.5 plan 21). */
+export interface BriefContext {
+  run: string;
+  name: string;
+  role: Role;
+  /** the lane file as it stands at admission, header and body */
+  lane: { id: string; text: string } | null;
+  /** the role's scratch folder, its TMPDIR, on a backend that grants it */
+  scratch: string | null;
+  /** whether the role's harness lists the catherd_role tools */
+  roleServer: boolean;
+}
+
+/** The CLI form of each role server tool, which any role can run from its shell. */
+function cliForm(tool: string, run: string): string {
+  switch (tool) {
+    case "read_run_file":
+      return `catherd run-file read ${run} <path>`;
+    case "write_run_file":
+      return `catherd run-file write ${run} <path> (the content on stdin)`;
+    case "read_knowledge":
+      return "catherd knowledge show";
+    case "gate_check":
+      return `catherd gate check ${run} --milestone <M> --item <item> --command <command> --paths <path,…>`;
+    case "gate_pass":
+      return `catherd gate pass ${run} --item <item> --command <command> --paths <path,…> --evidence <evidence>`;
+    default:
+      return tool;
+  }
+}
+
+const LANE_OPEN = (id: string) => `<lane-file path="lanes/${id}.md">`;
+const LANE_CLOSE = "</lane-file>";
+
+/**
+ * The lane file inlined (spec 1.5 plan 21): an isolated headless worker cannot read the run folder, so its Owns,
+ * fast check and body travel in the brief itself.
+ */
+export function laneBlock(id: string, text: string): string {
+  return [
+    `Your lane file, lanes/${id}.md, as it stood when you were dispatched:`,
+    LANE_OPEN(id),
+    text.trimEnd(),
+    LANE_CLOSE,
+  ].join("\n");
+}
+
+/** Who the role is, where its temp files go, and how it reaches its run's files and gate. */
+export function roleNotes(c: BriefContext): string {
+  const tools = roleMcpTools(c.role);
+  const lines = [`catherd: you are ${c.name} of run ${c.run}.`];
+  if (c.scratch)
+    lines.push(
+      `Your scratch folder is ${c.scratch}, which is your $TMPDIR: put temporary files, logs and builds there, never in /tmp. catherd removes it with the run, so anything the orchestrator must keep goes in your reply.`,
+    );
+  const cli = tools.map((t) => cliForm(t, c.run)).join("; ");
+  lines.push(
+    c.roleServer
+      ? `Your catherd tools: ${tools.map((t) => `mcp__${ROLE_MCP_SERVER}__${t}`).join(", ")}. If they are not listed, run the same from your shell: ${cli}.`
+      : `Your catherd commands, from your shell: ${cli}.`,
+  );
+  return lines.join("\n");
+}
+
+/**
+ * The brief admission writes: the orchestrator's text, the lane file, the role's notes, then its reply contract,
+ * each once. A failover stand-in that reruns an earlier brief gets the lane file as it stands now and its own notes,
+ * never two copies.
+ */
+export function composeBrief(brief: string, c: BriefContext): string {
+  const contract = replyContract(c.role);
+  let body = brief.trimEnd();
+  if (body.endsWith(contract)) body = body.slice(0, -contract.length).trimEnd();
+  if (c.lane) {
+    const open = LANE_OPEN(c.lane.id);
+    const start = body.lastIndexOf(open);
+    const end = body.indexOf(LANE_CLOSE, start);
+    if (start >= 0 && end >= 0) {
+      const lead = body.lastIndexOf("\n\n", start);
+      body = `${body.slice(0, lead >= 0 ? lead : start)}${body.slice(end + LANE_CLOSE.length)}`.trimEnd();
+    }
+  }
+  const notesStart = body.lastIndexOf("\n\ncatherd: you are ");
+  if (notesStart >= 0) body = body.slice(0, notesStart).trimEnd();
+  const parts = [body, ...(c.lane ? [laneBlock(c.lane.id, c.lane.text)] : []), roleNotes(c), contract];
+  return `${parts.filter(Boolean).join("\n\n")}\n`;
+}

package/src/domain/calibration.ts

@@ -34,6 +34,13 @@ export const DIM_SOURCES: Record<Dim, { anchor: FieldRef | "shipped"; others: Fi
         benchmark: "Artificial Analysis Coding Index",
       },
       { source: "epoch", field: "frontiercode", benchmark: "FrontierCode (Epoch AI)" },
+      // spec 1.5 plan 24: per model and effort, it scores a new release the day it ships (the identity run's
+      // GPT-6.1 Sol: medium 47.8, about Astra low)
+      {
+        source: "artificial-analysis",
+        field: "artificial_analysis_intelligence_index",
+        benchmark: "Artificial Analysis Intelligence Index",
+      },
     ],
   },
   // plan 14 Ruling C-2: the vendors' Terminal-Bench 4.0 values, not Epoch's Terminal-Bench 2.0, which shares

package/src/domain/catalog.ts

@@ -84,6 +84,11 @@ const FamilySchema = z.looseObject({
   notes: z.record(z.string(), z.string()).default({}),
   /** the day the vendor released it (models.dev), a stand-in feature (spec 1.2 §6.3) */
   releaseDate: z.iso.date().optional(),
+  /**
+   * spec 1.5 plan 24: the family this one succeeds in the same line (GPT-6.1 Sol after GPT-6 Sol): until a
+   * value of its own arrives, a rung takes at least its predecessor's value at the same effort
+   */
+  predecessor: z.string().min(1).optional(),
   /** a sync's speed facts (spec 1.2 §4.1), `<source>.<field>` → value; they never carry a bar */
   speed: z.record(z.string(), z.number()).optional(),
 });
@@ -211,6 +216,8 @@ export interface Catalog {
    * whose value it uses as `inferred` (spec 1.2 §6.1); filled by the stand-in ranking (services/standins.ts)
    */
   inferred: Record<string, Partial<Record<Dim, InferredStandIn>>>;
+  /** the thresholds the user's override set or removed, as `<kind>/<difficulty>/<dim>` (route says "your override") */
+  userBars?: string[];
 }
 
 /**
@@ -317,11 +324,14 @@ export function buildCatalog(o: {
   for (const [rung, like] of Object.entries(o.override?.treatLike ?? {}))
     treatLike[rung] = { like, source: "user" };
   const bars = structuredClone(o.scores.bars) as Bars;
+  const userBars: string[] = [];
   for (const kind of KINDS)
     for (const d of DIFFICULTIES)
-      for (const [dim, min] of Object.entries(o.override?.bars[kind]?.[d] ?? {}) as [Dim, number | null][])
+      for (const [dim, min] of Object.entries(o.override?.bars[kind]?.[d] ?? {}) as [Dim, number | null][]) {
+        userBars.push(`${kind}/${d}/${dim}`);
         if (min === null) delete bars[kind][d][dim];
         else bars[kind][d][dim] = min;
+      }
   return {
     families: o.facts ? applyFacts(o.models.families, o.facts) : o.models.families,
     backends: o.models.backends,
@@ -333,6 +343,7 @@ export function buildCatalog(o: {
     secs: o.secs ?? {},
     features: o.features ?? {},
     inferred: {},
+    userBars,
   };
 }
 

package/src/domain/changes.ts

@@ -33,6 +33,28 @@ export function changedPaths(before: Snapshot, after: Snapshot): string[] {
     .sort();
 }
 
+/** Spec 1.5 plan 21: a writer's implicit docs lane, when its brief names no Owns. */
+export const DOCS_OWNS = ["docs/**", "*.md"];
+
+/** The paths of an `Owns:` line in a brief (as a lane file writes it), or null when it has none. */
+export function briefOwns(brief: string): string[] | null {
+  const line = /^Owns:\s*(.+)$/m.exec(brief)?.[1];
+  const paths = line
+    ?.split(",")
+    .map((p) => p.trim().replace(/^`|`$/g, ""))
+    .filter(Boolean);
+  return paths?.length ? paths : null;
+}
+
+/**
+ * Whether `path` is inside an Owns entry: a path covers what is under it, and the other way round (as lanes'
+ * Owns always did); `dir/**` covers what is under dir; `*.ext` (no slash) is any file with that extension.
+ */
+export function ownsPath(path: string, entry: string): boolean {
+  if (entry.startsWith("*.") && !entry.includes("/")) return path.endsWith(entry.slice(1));
+  return overlaps([path], [entry.replace(/\/\*\*$/, "")]).length > 0;
+}
+
 /**
  * Spec §4.4: `changedOwned` are the changes inside the lane's Owns; `violations` the ones outside it
  * that no overlapping dispatch owns either. `strict` is false for a laneless dispatch that may write
@@ -44,7 +66,7 @@ export function splitChanges(
   others: string[],
   strict: boolean,
 ): { changedOwned: string[]; violations: string[] } {
-  const inside = (p: string, paths: string[]) => overlaps([p], paths).length > 0;
+  const inside = (p: string, paths: string[]) => paths.some((entry) => ownsPath(p, entry));
   return {
     changedOwned: changed.filter((p) => inside(p, owns)),
     violations: strict ? changed.filter((p) => !inside(p, owns) && !inside(p, others)) : [],

package/src/domain/cost.ts

@@ -51,19 +51,24 @@ export const CHATGPT_UNIT_USD = 0.019;
 export interface Cost {
   /** 0: paid from a subscription; 1: metered. Every tier-0 rung ranks before any tier-1 rung. */
   tier: 0 | 1;
-  /** comparable across billing modes, in list-price dollars per task; null when unknown */
+  /**
+   * comparable across billing modes, in list-price dollars per task; 0 for an unpriced rung paid from a plan or
+   * subscription (it spends nothing beyond the flat fee); null for an unpriced metered one
+   */
   value: number | null;
   mode: BillingMode;
 }
 
 /**
- * Spec §5.3. Every mode yields list-price dollars per task, so plans compare with each other:
+ * Spec §5.3. Every mode yields list-price dollars per task, so plans compare with each other. Spec 1.5 plan 24:
+ * a rung catherd has no price for costs 0 within its tier when a plan or subscription pays for it, so it can
+ * start a lane (the profile's ladder order then breaks the tie); a metered one stays unknown, last in its tier.
  * chatgpt-plan scales the official quota weight (Luna 1, Sol 20, Astra 60) by the effort factor;
  * claude-plan uses API prices as the proxy, with Fable metered (catherd cannot tell Pro from Max);
  * Go's share of its monthly dollar limit is dollars / limit, which orders the same as dollars.
  */
 export function costOf(family: Family | null, effort: string, mode: BillingMode): Cost {
-  if (!family) return { tier: mode === "metered" ? 1 : 0, value: null, mode };
+  if (!family) return mode === "metered" ? { tier: 1, value: null, mode } : { tier: 0, value: 0, mode };
   const usd = taskUsd(family.price, effort);
   switch (mode) {
     case "chatgpt-plan":

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/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

@@ -17,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;
@@ -34,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(" · ");
 }
 
@@ -78,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(", ")}`;
 }