catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/domain/profile.ts

@@ -1,10 +1,12 @@
 import type { OrchestrationHost } from "./host.ts";
 import { z } from "zod";
 import type { Budget } from "./budget.ts";
+import type { Bars } from "./bars.ts";
 import { BILLING_KEYS, type BillingKey } from "./catalog.ts";
 import { BILLING_MODES, type BillingMode, DEFAULT_BILLING } from "./cost.ts";
 import { CatherdError } from "./errors.ts";
-import { ADAPTER_IDS, parseRung, tryParseRung } from "./ids.ts";
+import { ADAPTER_IDS, EFFORT_ORDER, type EffortWord, effortRank, parseRung, tryParseRung } from "./ids.ts";
+import { DIFFICULTIES } from "./lane.ts";
 import { ACCESS, type Access } from "./record.ts";
 import { DEFAULT_ACCESS, ROLES, type Role } from "./roles.ts";
 import { isPlain, slug } from "./util.ts";
@@ -45,6 +47,9 @@ const RoleDocSchema = z.looseObject({
   rungs: z.array(z.string()).optional(),
   defaultRung: z.string().optional(),
   network: z.boolean().optional(),
+  timeouts: z.looseObject({ idleMin: positive.optional(), wallMin: positive.optional() }).optional(),
+  // plan 33: unknown, so a hand edit never makes the file unreadable; resolveProfile reads what it can
+  bars: z.unknown().optional(),
 });
 
 export const ProfileDocSchema = z.looseObject({
@@ -56,6 +61,9 @@ export const ProfileDocSchema = z.looseObject({
   roles: z.record(z.string(), RoleDocSchema).optional(),
   harness: z.record(z.string(), z.looseObject({ isolated: z.boolean().optional() })).optional(),
   failover: z.record(z.string(), z.string()).optional(),
+  // unknown values, like `bars`: an entry that is no effort word never makes the file unreadable
+  maxEffort: z.record(z.string(), z.unknown()).optional(),
+  bars: z.unknown().optional(),
   budget: z
     .looseObject({ minutes: positive.optional(), tokens: positive.optional(), usd: positive.optional() })
     .optional(),
@@ -65,9 +73,20 @@ export const ProfileDocSchema = z.looseObject({
     .looseObject({ heavy: z.union([z.number().int().positive(), z.literal("cpus/2")]).optional() })
     .optional(),
   notify: z.array(z.string()).optional(),
+  // plan 35: unknown, so a hand edit never makes the file unreadable; resolveProfile reads what it can
+  limits: z.unknown().optional(),
 });
 export type ProfileDoc = z.infer<typeof ProfileDocSchema>;
 
+/** plan 35: the profile's memory numbers for starting milestones side by side (megabytes). */
+const MEMORY_KEYS = ["reserveMb", "perMilestoneMb", "floorMb"] as const;
+type MemoryKey = (typeof MEMORY_KEYS)[number];
+const positiveInt = (v: unknown): v is number => typeof v === "number" && Number.isInteger(v) && v > 0;
+const storedMemory = (doc: ProfileDoc): Record<string, unknown> => {
+  const memory = isPlain(doc.limits) ? doc.limits.memory : undefined;
+  return isPlain(memory) ? memory : {};
+};
+
 const OBJECTIVES = ["cost", "speed"] as const;
 const JEV_USES = ["auto", "off"] as const;
 const known = <T extends string>(values: readonly T[], v: string | undefined): v is T =>
@@ -85,6 +104,16 @@ const STORED_FALLBACK = {
   billing: (key: string): BillingMode => DEFAULT_BILLING[key as BillingKey] ?? "metered",
 } as const;
 
+const barOk = (k: string, v: unknown): boolean =>
+  (DIFFICULTIES as readonly string[]).includes(k) && typeof v === "number" && v >= 0 && v <= 100;
+
+const isEffort = (v: unknown): v is EffortWord => typeof v === "string" && effortRank(v) >= 0;
+
+/** The entries of a stored `bars` this catherd can read; anything else is not a bar. */
+function readBars(v: unknown): Bars {
+  return isPlain(v) ? (Object.fromEntries(Object.entries(v).filter((e) => barOk(e[0], e[1]))) as Bars) : {};
+}
+
 /** A stored value this catherd does not know, with what it is read as. */
 export interface UnknownValue {
   path: string;
@@ -102,9 +131,25 @@ export function unknownValues(doc: ProfileDoc): UnknownValue[] {
   check("jev.use", JEV_USES, doc.jev?.use, STORED_FALLBACK.jevUse);
   for (const [k, v] of Object.entries(doc.billing ?? {}))
     check(`billing.${k}`, BILLING_MODES, v, STORED_FALLBACK.billing(k));
+  for (const [k, v] of Object.entries(doc.maxEffort ?? {}))
+    if (!isEffort(v)) {
+      const value = typeof v === "string" ? v : JSON.stringify(v);
+      out.push({ path: `maxEffort.${k}`, value, readAs: "no ceiling" });
+    }
+  const checkBars = (path: string, v: unknown, readAs: string) => {
+    if (v === undefined) return;
+    if (!isPlain(v)) return void out.push({ path, value: JSON.stringify(v), readAs });
+    for (const [k, x] of Object.entries(v))
+      if (!barOk(k, x)) out.push({ path: `${path}.${k}`, value: String(x), readAs });
+  };
+  checkBars("bars", doc.bars, "the shipped percentile");
+  for (const role of ROLES) checkBars(`roles.${role}.bars`, doc.roles?.[role]?.bars, "the profile's bar");
   for (const role of ROLES)
     check(`roles.${role}.access`, ACCESS, doc.roles?.[role]?.access, STORED_FALLBACK.access);
   for (const n of doc.notify ?? []) check("notify", NOTIFY, n, "skipped");
+  for (const [k, v] of Object.entries(storedMemory(doc)))
+    if (!(MEMORY_KEYS as readonly string[]).includes(k) || !positiveInt(v))
+      out.push({ path: `limits.memory.${k}`, value: JSON.stringify(v), readAs: "the default" });
   return out;
 }
 
@@ -117,8 +162,21 @@ export type RoleConfig = {
   defaultRung?: string;
   /** spec §5: false drops a workspace-write role's network, loopback and Docker grants; absent means granted */
   network?: false;
+  /** plan 23: this role's own idle and wall timeouts, over the profile's `timeouts` (a long gate, a slow model) */
+  timeouts?: { idleMin?: number; wallMin?: number };
+  /** plan 33: this role's own bar percentiles, over the profile's `bars` (decision 11) */
+  bars?: Bars;
 };
 
+/** The idle and wall timeouts a role runs under: its own `timeouts`, else the profile's. */
+export const roleTimeouts = (
+  profile: { timeouts: { idleMin: number; wallMin: number } },
+  role: { timeouts?: { idleMin?: number; wallMin?: number } } | undefined,
+): { idleMin: number; wallMin: number } => ({
+  idleMin: role?.timeouts?.idleMin ?? profile.timeouts.idleMin,
+  wallMin: role?.timeouts?.wallMin ?? profile.timeouts.wallMin,
+});
+
 /** A profile with every default filled in: what the run engine, the CLI and the agent files read. */
 export interface Profile {
   name: string;
@@ -128,11 +186,17 @@ export interface Profile {
   roles: Record<Role, RoleConfig>;
   harness: Record<string, { isolated: boolean }>;
   failover: Record<string, string>;
+  /** plan 33: `<backend>:<model>` → the highest effort routing starts it at; a model not named has no ceiling */
+  maxEffort: Record<string, EffortWord>;
+  /** plan 33: bar percentiles per difficulty, over the shipped ones (`percentilesOf`) */
+  bars: Bars;
   budget: Budget;
   timeouts: { idleMin: number; wallMin: number };
   preflight: { confirm: boolean };
   lock: { heavy: number | "cpus/2" };
   notify: NotifyMoment[];
+  /** plan 35: only the memory numbers the profile sets; the defaults are `MEMORY_LIMITS` */
+  limits: { memory: Partial<Record<MemoryKey, number>> };
 }
 
 const LUNA_HIGH = "codex:gpt-6-luna#high";
@@ -156,14 +220,15 @@ export const BUILTIN_ROLES: Record<Role, RoleConfig> = {
   artist: { enabled: true, access: DEFAULT_ACCESS.artist, rungs: [SOL("medium")] },
   writer: { enabled: true, access: DEFAULT_ACCESS.writer, rungs: [LUNA_HIGH] },
   researcher: { enabled: true, access: DEFAULT_ACCESS.researcher, rungs: [LUNA_HIGH] },
+  judge: { enabled: true, access: DEFAULT_ACCESS.judge, rungs: ["claude-code:claude-opus-5-5#medium"] },
 };
 
 /**
- * Spec 1.1 §11: each shipped worker rung fails over to the best stand-in the shipped catalog offers
- * (`rankStandIns` over `catalogRungs`, pinned by test/domain/failover.test.ts): on another quota, paid
- * from a plan, and no downgrade on the dims the rung's bars use. Go serves GPT-6 Luna itself; Kimi K3
- * borrows Sol medium's scores (a shipped treat-like). Sol high and xhigh have no such stand-in on the
- * owner's plans, so they have none: a limit on them pauses the lane instead of dropping it a tier.
+ * Spec 1.1 §11: each shipped worker rung fails over to the best stand-in the Slopalytics index offers
+ * (`rankStandIns` over `catalogPairs`, pinned by test/domain/failover.test.ts): on another quota, paid from a
+ * plan, and at least as intelligent. Go serves GPT-6 Luna itself; Kimi K3 stands on its own index, above Sol
+ * medium. Sol high and xhigh have no such stand-in on the owner's plans, so they have none: a limit on them
+ * pauses the lane instead of dropping it a tier.
  */
 export const DEFAULT_FAILOVER: Record<string, string> = {
   [LUNA_HIGH]: "opencode:opencode-go/gpt-6-luna#high",
@@ -171,63 +236,22 @@ export const DEFAULT_FAILOVER: Record<string, string> = {
 };
 
 /**
- * Cursor's live slug and efforts for a paired family (`cursor-agent models`, 2026-10-01). Empty efforts means the
- * bare slug.
+ * Plan 33 Ruling 8: t3herd's effort caps under the shipped catalog's ids, on every backend that lists the model.
+ * The default profile writes them, so a failover to any backend can never start a `#max` Opus; a profile without
+ * the key has no ceiling.
  */
-const CURSOR_PAIR: Record<string, { id: string; efforts: readonly string[] }> = {
-  "grok-4.7": { id: "grok-4.7", efforts: ["low", "medium", "high", "xhigh"] },
-  "grok-4.6": { id: "cursor-grok-4.6", efforts: ["low", "medium", "high", "xhigh"] },
-  "grok-4.5": { id: "cursor-grok-4.5", efforts: ["low", "medium", "high"] },
-  "gemini-3.8-flash": { id: "gemini-3.8-flash", efforts: ["low", "medium", "high"] },
-  "gemini-3.7-flash": { id: "gemini-3.7-flash", efforts: ["low", "medium", "high"] },
-  "gemini-3.6-flash": { id: "gemini-3.6-flash", efforts: ["minimal", "low", "medium", "high"] },
-  "gemini-3.1-pro": { id: "gemini-3.1-pro", efforts: [] },
+export const DEFAULT_MAX_EFFORT: Readonly<Record<string, EffortWord>> = {
+  "claude:claude-opus-5-5": "high",
+  "claude-code:claude-opus-5-5": "high",
+  "opencode:opencode/claude-opus-5-5": "high",
+  "cursor:claude-opus-5-5": "high",
+  "claude:claude-sonnet-5-5": "high",
+  "claude-code:claude-sonnet-5-5": "high",
+  "opencode:opencode/claude-sonnet-5-5": "high",
+  "codex:gpt-6.1-sol": "xhigh",
 };
 
-/** The Cursor effort a paired rung can actually run: the same one when listed, else `high`, else the bare slug. */
-function cursorPairEffort(model: string, effort: string): string {
-  const list = CURSOR_PAIR[model]?.efforts ?? [];
-  if (list.length === 0) return "default";
-  if (effort !== "default" && list.includes(effort)) return effort;
-  return list.includes("high") ? "high" : (list[0] as string);
-}
-
-/**
- * Spec 1.3 §7.3: the same model through two backends bills two pools, so each stands in for the other on a
- * limit, at the same effort where both list it. Otherwise the stand-in runs at `high`: Grok 4.5 `xhigh` at Cursor
- * `high`, Cursor's Gemini 3.6 `minimal` at agy `high`; Gemini 3.1 Pro's bare Cursor slug pairs with agy `high`.
- * Grok and Gemini are paired with Cursor. Consulted after the profile's own failover and never written into a
- * profile, where a pair whose rung is on no ladder would warn "never runs"; never a stand-in for a shipped Codex,
- * Claude or opencode rung.
- */
-export const PAIRED_FAILOVER: Record<string, string> = Object.fromEntries(
-  (
-    [
-      ["grok", ["grok-4.7", "grok-4.6", "grok-4.5"], ["low", "medium", "high", "xhigh"]],
-      [
-        "antigravity",
-        ["gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash"],
-        ["low", "medium", "high"],
-      ],
-      ["antigravity", ["gemini-3.1-pro"], ["low", "high"]],
-    ] as const
-  ).flatMap(([backend, models, efforts]) =>
-    models.flatMap((m) => {
-      const cursor = CURSOR_PAIR[m] as { id: string; efforts: readonly string[] };
-      const back = ["default", ...efforts].map(
-        (e) => [`${backend}:${m}#${e}`, `cursor:${cursor.id}#${cursorPairEffort(m, e)}`] as const,
-      );
-      // `#default` too, as on the other side: a Cursor rung with no effort flag fails over the same way
-      const fore = [...new Set(["default", ...cursor.efforts])].map((e) => {
-        const there = e !== "default" && (efforts as readonly string[]).includes(e) ? e : "high";
-        return [`cursor:${cursor.id}#${e}`, `${backend}:${m}#${there}`] as const;
-      });
-      return [...back, ...fore];
-    }),
-  ),
-);
-
-/** The five billing keys spec §7.1 writes out; cursor and grok arrive with their backends. */
+/** The five billing keys spec §7.1 writes out; the rest default. */
 const WRITTEN_BILLING: BillingKey[] = ["codex", "claude", "claude-code", "opencode-go", "opencode"];
 
 /** Stored defaults for init/new; architect/verifier rungs resolve from the current host. */
@@ -245,6 +269,7 @@ export function defaultProfileDoc(name = "default"): ProfileDoc {
       opencode: { isolated: false },
     },
     failover: { ...DEFAULT_FAILOVER },
+    maxEffort: { ...DEFAULT_MAX_EFFORT },
     budget: {},
     timeouts: { idleMin: 15, wallMin: 90 },
     preflight: { confirm: false },
@@ -253,10 +278,10 @@ export function defaultProfileDoc(name = "default"): ProfileDoc {
   };
 }
 
-/** Remove only the four architect/verifier execution choices, preserving other stored fields. */
+/** Remove only the architect, verifier and judge execution choices, preserving other stored fields. */
 export function hostDefaultsDoc(doc: ProfileDoc): ProfileDoc {
   const next = structuredClone(doc);
-  for (const role of ["architect", "verifier"] as const) {
+  for (const role of ["architect", "verifier", "judge"] as const) {
     const r = next.roles?.[role];
     if (r) {
       delete r.rungs;
@@ -285,6 +310,9 @@ export function resolveProfile(doc: ProfileDoc, name: string, host: Orchestratio
             ? []
             : b.rungs;
     }
+    // the judge is Opus by default; on a Codex host it follows the host like the architect and the verifier do
+    if (role === "judge" && d?.rungs === undefined && host === "codex")
+      omitted = ["codex:gpt-6.1-sol#medium"];
     // a role that lists its own rungs never inherits the built-in default rung, which may not be among them
     const defaultRung = d?.defaultRung ?? (d?.rungs === undefined ? b.defaultRung : undefined);
     roles[role] = {
@@ -298,6 +326,15 @@ export function resolveProfile(doc: ProfileDoc, name: string, host: Orchestratio
       rungs: [...(d?.rungs ?? omitted)],
       ...(defaultRung ? { defaultRung } : {}),
       ...(d?.network === false ? { network: false as const } : {}),
+      ...(d?.timeouts?.idleMin !== undefined || d?.timeouts?.wallMin !== undefined
+        ? {
+            timeouts: {
+              ...(d.timeouts.idleMin !== undefined ? { idleMin: d.timeouts.idleMin } : {}),
+              ...(d.timeouts.wallMin !== undefined ? { wallMin: d.timeouts.wallMin } : {}),
+            },
+          }
+        : {}),
+      ...(Object.keys(readBars(d?.bars)).length > 0 ? { bars: readBars(d?.bars) } : {}),
     };
   }
   const harness: Profile["harness"] = {};
@@ -320,11 +357,23 @@ export function resolveProfile(doc: ProfileDoc, name: string, host: Orchestratio
     roles,
     harness,
     failover: { ...doc.failover },
+    maxEffort: Object.fromEntries(
+      Object.entries(doc.maxEffort ?? {}).filter((e): e is [string, EffortWord] => isEffort(e[1])),
+    ),
+    bars: readBars(doc.bars),
     budget,
     timeouts: { idleMin: doc.timeouts?.idleMin ?? 15, wallMin: doc.timeouts?.wallMin ?? 90 },
     preflight: { confirm: doc.preflight?.confirm ?? false },
     lock: { heavy: doc.lock?.heavy ?? "cpus/2" },
     notify: doc.notify === undefined ? [...NOTIFY] : doc.notify.filter((n) => known(NOTIFY, n)),
+    limits: {
+      memory: Object.fromEntries(
+        MEMORY_KEYS.flatMap((k) => {
+          const v = storedMemory(doc)[k];
+          return positiveInt(v) ? [[k, v]] : [];
+        }),
+      ),
+    },
   };
 }
 
@@ -337,6 +386,10 @@ export function agentName(profile: string, role: Role, rung: string): string {
 // Patches: what profile_set and `catherd profile set` accept. Strict at every level, so a misspelt key is
 // refused with E_INPUT_INVALID instead of dropped (plan-2 review m9). `null` removes a map entry or a nullable
 // field (a role's `network` among them: absent means granted).
+const BarsPatchSchema = z
+  .partialRecord(z.enum(DIFFICULTIES), z.number().min(0).max(100).nullable())
+  .nullable();
+
 const RolePatchSchema = z
   .strictObject({
     enabled: z.boolean(),
@@ -344,6 +397,11 @@ const RolePatchSchema = z
     rungs: z.array(RungSchema),
     defaultRung: RungSchema.nullable(),
     network: z.boolean().nullable(),
+    timeouts: z
+      .strictObject({ idleMin: positive.nullable(), wallMin: positive.nullable() })
+      .partial()
+      .nullable(),
+    bars: BarsPatchSchema,
   })
   .partial();
 
@@ -354,6 +412,13 @@ export const ProfilePatchSchema = z.strictObject({
   roles: z.partialRecord(z.enum(ROLES), RolePatchSchema).optional(),
   harness: z.partialRecord(z.enum(HARNESS_KEYS), z.strictObject({ isolated: z.boolean() })).optional(),
   failover: z.record(RungSchema, RungSchema.nullable()).optional(),
+  maxEffort: z
+    .record(
+      z.string().refine((k) => tryParseRung(`${k}#x`) !== null, "a key is <backend>:<model>"),
+      z.enum(EFFORT_ORDER).nullable(),
+    )
+    .optional(),
+  bars: BarsPatchSchema.optional(),
   budget: z
     .strictObject({ minutes: positive.nullable(), tokens: positive.nullable(), usd: positive.nullable() })
     .partial()
@@ -362,6 +427,18 @@ export const ProfilePatchSchema = z.strictObject({
   preflight: z.strictObject({ confirm: z.boolean() }).optional(),
   lock: z.strictObject({ heavy: z.union([z.number().int().positive(), z.literal("cpus/2")]) }).optional(),
   notify: z.array(z.enum(NOTIFY)).optional(),
+  limits: z
+    .strictObject({
+      memory: z
+        .strictObject({
+          reserveMb: z.number().int().positive().nullable(),
+          perMilestoneMb: z.number().int().positive().nullable(),
+          floorMb: z.number().int().positive().nullable(),
+        })
+        .partial(),
+    })
+    .partial()
+    .optional(),
 });
 export type ProfilePatch = z.infer<typeof ProfilePatchSchema>;
 
@@ -382,7 +459,7 @@ export function applyPatch(doc: ProfileDoc, patch: ProfilePatch): ProfileDoc {
 }
 
 /** Map fields whose keys are rungs or billing keys, which may hold dots: the rest of the path is one key. */
-const MAP_FIELDS = new Set(["failover", "billing"]);
+const MAP_FIELDS = new Set(["failover", "billing", "maxEffort"]);
 const LIST_FIELDS = (keys: string[]) =>
   (keys[0] === "roles" && keys[2] === "rungs") || (keys[0] === "notify" && keys.length === 1);
 

package/src/domain/record.ts

@@ -3,10 +3,11 @@ import { z } from "zod";
 export const ACCESS = ["read-only", "workspace-write", "full"] as const;
 export type Access = (typeof ACCESS)[number];
 
-const RUN_STATUSES = ["ok", "failed", "limit", "cli-too-old", "timeout", "cancelled"] as const;
+export const RUN_STATUSES = ["ok", "failed", "limit", "cli-too-old", "timeout", "cancelled"] as const;
 export type RunStatus = (typeof RUN_STATUSES)[number];
 
-const REPLY_STATUSES = ["complete", "partial", "blocked", "refused"] as const;
+/** plan 23: `flaky`, a worker's word for a check that failed, then passed when run alone */
+export const REPLY_STATUSES = ["complete", "partial", "blocked", "refused", "flaky"] as const;
 export type ReplyStatus = (typeof REPLY_STATUSES)[number];
 
 export interface Tokens {
@@ -27,6 +28,8 @@ export const EXIT_REASONS = [
   "wall-timeout",
   "cancelled",
   "lost",
+  /** plan 23: the provider kept failing (retries with no progress); failover treats it as a usage limit */
+  "provider-unavailable",
 ] as const;
 export type ExitReason = (typeof EXIT_REASONS)[number];
 export interface ExitInfo {
@@ -65,6 +68,19 @@ export const RunRecordSchema = z.looseObject({
   gitUnavailable: z.boolean().optional(),
   replyStatus: z.enum(REPLY_STATUSES).nullable(),
   replyWhy: z.string().nullable(),
+  /** plan 23: the reply's ENV: line, when the environment stopped the role; absent otherwise */
+  environment: z.string().optional(),
+  /** a verifier's `HEAD: <sha>` line: the commit it checked (lower-case hex, 7-64 characters) */
+  head: z
+    .string()
+    .regex(/^[0-9a-f]{7,64}$/)
+    .optional(),
+  /** a worker's `EXTRA: <path> — <why>` lines: files outside its lane it had to change */
+  extras: z.array(z.object({ path: z.string(), why: z.string() })).optional(),
+  /** a fix-round worker's `REJECTED: <finding> — <why>` lines */
+  rejected: z.array(z.object({ finding: z.string(), why: z.string() })).optional(),
+  /** a worker's `DESIGN:` lines: where its plan task conflicts with the code */
+  design: z.array(z.string()).optional(),
   threadHeavy: z.boolean(),
   access: z.enum(ACCESS),
   isolated: z.boolean(),
@@ -79,7 +95,16 @@ export const RunRecordSchema = z.looseObject({
 });
 export type RunRecord = z.infer<typeof RunRecordSchema>;
 
-const STATUS_LINE = /^STATUS:\s*(complete|partial|blocked|refused)\s*(?:—|–|-)\s*(.*)$/;
+const STATUS_LINE = /^STATUS:\s*(complete|partial|blocked|refused|flaky)\s*(?:—|–|-)\s*(.*)$/;
+
+/**
+ * Plan 23: what stopped the role, when the environment did: an `ENV: <what>` line of its reply (a VPN, no
+ * Docker, a dead registry); null without one.
+ */
+export function parseReplyEnvironment(reply: string): string | null {
+  const m = /^[ \t]*ENV:[ \t]*(\S.*?)[ \t]*$/m.exec(reply);
+  return m ? (m[1] as string) : null;
+}
 
 /** The role's claim about its own work: the reply's last line, `STATUS: <s> — <why>`. */
 export function parseReplyStatus(reply: string): { status: ReplyStatus | null; why: string | null } {
@@ -87,3 +112,43 @@ export function parseReplyStatus(reply: string): { status: ReplyStatus | null; w
   const m = STATUS_LINE.exec(last);
   return m ? { status: m[1] as ReplyStatus, why: (m[2] ?? "").trim() } : { status: null, why: null };
 }
+
+/** The last `HEAD: <hex>` line of a reply outside code fences, lower-cased: the commit a verifier says it checked. */
+export function parseReplyHead(reply: string): string | null {
+  let fenced = false;
+  let head: string | null = null;
+  for (const line of reply.split("\n")) {
+    if (/^\s*(```|~~~)/.test(line)) fenced = !fenced;
+    else if (!fenced) {
+      const m = /^[ \t]*HEAD:[ \t]*([0-9a-fA-F]{7,64})[ \t]*$/.exec(line);
+      if (m) head = (m[1] as string).toLowerCase();
+    }
+  }
+  return head;
+}
+
+/** `<LABEL>: <a> — <b>` lines (optional bullet; the separator is `—`, `–` or `-` with whitespace around it). */
+function labelled(reply: string, label: string): [string, string][] {
+  const re = new RegExp(
+    `^[ \\t]*(?:[-*][ \\t]*)?${label}:[ \\t]*(\\S.*?)(?:[ \\t]+(?:—|–|-)[ \\t]+(.*?))?[ \\t]*$`,
+    "gm",
+  );
+  return [...reply.matchAll(re)].map((m) => [m[1] as string, m[2] ?? ""]);
+}
+
+/** Every `EXTRA: <path> — <why>` line: a file outside the lane the worker had to change. */
+export function parseReplyExtras(reply: string): { path: string; why: string }[] {
+  return labelled(reply, "EXTRA").map(([path, why]) => ({ path: path.replace(/`/g, ""), why }));
+}
+
+/** Every `REJECTED: <finding> — <why>` line of a fix round. */
+export function parseReplyRejections(reply: string): { finding: string; why: string }[] {
+  return labelled(reply, "REJECTED").map(([finding, why]) => ({ finding, why }));
+}
+
+/** The trimmed value of every `DESIGN:` line: a conflict between a plan task and the code. */
+export function parseReplyDesign(reply: string): string[] {
+  return [...reply.matchAll(/^[ \t]*(?:[-*][ \t]*)?DESIGN:[ \t]*(\S.*?)[ \t]*$/gm)].map(
+    (m) => m[1] as string,
+  );
+}

package/src/domain/reply.ts

@@ -0,0 +1,29 @@
+import { parseReplyStatus } from "./record.ts";
+
+/**
+ * Plan 22: a final reply never overwrites the report. `finals` are the messages that ended each of the run's
+ * turns, in order (a background command's notification can start another turn after the report); `last` is the
+ * reply the CLI kept, the last of them. With more than one, the reply is the longest STATUS-bearing message, the
+ * later ones after it under `later:`, and the report's STATUS line last, so the record's STATUS is the report's.
+ * Otherwise `last` is the reply, unchanged.
+ */
+export function composeReply(finals: string[], last: string): string {
+  if (finals.length < 2) return last;
+  let report = -1;
+  for (const [i, f] of finals.entries())
+    if (
+      parseReplyStatus(f).status !== null &&
+      (report < 0 || f.trim().length >= finals[report]!.trim().length)
+    )
+      report = i;
+  if (report < 0 || report === finals.length - 1) return last;
+  const lines = finals[report]!.trimEnd().split("\n");
+  const status = lines.pop() as string;
+  const later = finals
+    .slice(report + 1)
+    .map((f) => f.trim())
+    .filter(Boolean);
+  if (!later.length) return last;
+  const body = lines.join("\n").trimEnd();
+  return [...(body ? [body, ""] : []), "later:", later.join("\n\n"), "", status.trim(), ""].join("\n");
+}