catherd-cli 1.4.0 → 1.5.0

package/src/services/protocol.ts

@@ -2,18 +2,24 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { RunRecord } from "../domain/record.ts";
 import type { RouteRow } from "../domain/route.ts";
+import { parseLaneHeader } from "../domain/lane.ts";
 import { ensurePrivateDir, readJsonl, writeTextAtomic } from "../infra/store.ts";
 import { type Dispatch, listDispatches, liveDispatches } from "./dispatches.ts";
-import type { VerifierStep } from "./gate-service.ts";
+import { RECHECK_COMMAND_MIN } from "../domain/gate-brief.ts";
+import { failedItems, type VerifierStep } from "./gate-service.ts";
 import {
+  countFindings,
+  FINDING,
   landedMilestones,
   milestoneReviewer,
   milestoneVerifier,
   milestoneStart,
   namesMilestone,
+  openFindings,
+  partialReviewer,
   reviewerPassed,
-  verifierPassed,
 } from "./milestones.ts";
+import { openQuestions } from "./questions.ts";
 import { readAgentRuns, readRecords, readRoutes, type Run, runPaths } from "./run-store.ts";
 
 // Spec 1.1 §10: the protocol's next step, derived from the run's own files so a session that lost its
@@ -44,30 +50,48 @@ function laneIds(run: Run): string[] {
     .sort(byNumber);
 }
 
+/** What laneDone reads of the run, read once for every lane of the milestone. */
+interface LaneEvidence {
+  routes: RouteRow[];
+  live: Dispatch[];
+  records: Map<string, RunRecord>;
+  dispatches: Dispatch[];
+  agents: ReturnType<typeof readAgentRuns>;
+}
+
+function laneEvidence(run: Run, routes: RouteRow[], live: Dispatch[]): LaneEvidence {
+  return {
+    routes,
+    live,
+    records: new Map(readRecords(run).records.map((r) => [r.dispatchId, r])),
+    dispatches: listDispatches(run),
+    agents: readAgentRuns(run),
+  };
+}
+
 /**
  * Whether `lane` needs no dispatch now: its latest dispatch or native agent run since its latest climb is
  * still running, or ended ok with no blocked or refused reply. A lane whose last try failed, hit a limit,
  * was blocked, or was climbed since goes back to dispatch; a plain re-route leaves an ok try standing.
  */
-function laneDone(run: Run, lane: string, routes: RouteRow[], live: Dispatch[]): boolean {
+function laneDone(lane: string, e: LaneEvidence): boolean {
   const from = Math.max(
-    ...routes.filter((r) => r.lane === lane && r.source === "climb").map((r) => Date.parse(r.at)),
+    ...e.routes.filter((r) => r.lane === lane && r.source === "climb").map((r) => Date.parse(r.at)),
   );
   // a dispatch routes its lane first, so a try at the route's own time counts as after it
   const after = (t: string) => !(Date.parse(t) < from);
-  const records = new Map(readRecords(run).records.map((r) => [r.dispatchId, r]));
-  const running = new Set(live.map((d) => d.admit.dispatchId));
+  const running = new Set(e.live.map((d) => d.admit.dispatchId));
   const tries = [
-    ...listDispatches(run)
+    ...e.dispatches
       .filter((d) => d.admit.lane === lane && after(d.admit.admittedAt))
       .map((d) => {
-        const r = records.get(d.admit.dispatchId);
+        const r = e.records.get(d.admit.dispatchId);
         const ok = r
           ? r.status === "ok" && r.replyStatus !== "blocked" && r.replyStatus !== "refused"
           : running.has(d.admit.dispatchId);
         return { at: Date.parse(d.admit.admittedAt), ok };
       }),
-    ...readAgentRuns(run)
+    ...e.agents
       .filter((a) => a.lane === lane && after(a.at))
       .map((a) => ({ at: Date.parse(a.at), ok: a.status === "ok" })),
   ];
@@ -78,6 +102,27 @@ function laneDone(run: Run, lane: string, routes: RouteRow[], live: Dispatch[]):
   return latest?.ok ?? false;
 }
 
+/** The lane's After: lanes, from its file; none when it has none or cannot be read. */
+function afterOf(run: Run, lane: string): string[] {
+  try {
+    return parseLaneHeader(readFileSync(join(runPaths(run.dir).lanes, `${lane}.md`), "utf8")).after;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Spec 1.5 "Lane editing": the lanes `lane`'s After: line names that have not finished: their milestone has
+ * not landed and their latest try since the latest climb is still running, or did not end ok.
+ */
+export function unfinishedAfter(run: Run, lane: string, routes: RouteRow[] = readRoutes(run)): string[] {
+  const landed = new Set(landedMilestones(run));
+  const after = afterOf(run, lane).filter((a) => !landed.has(milestoneOf(a)));
+  if (after.length === 0) return [];
+  const evidence = laneEvidence(run, routes, []);
+  return after.filter((a) => !laneDone(a, evidence));
+}
+
 /**
  * The step the milestone loop is at: the first milestone neither landed nor parked, and within it the
  * first of route, dispatch, collect, reviewer, verifier and land that is still to do.
@@ -98,20 +143,49 @@ export function protocolNext(run: Run, parked: string[], now = Date.now()): stri
   const routed = new Set(routes.map((r) => r.lane));
   if (mine.some((l) => !routed.has(l))) return `route and preflight ${m}'s lanes`;
   const live = liveDispatches(run, now);
-  const notDone = mine.filter((l) => !laneDone(run, l, routes, live));
+  const evidence = laneEvidence(run, routes, live);
+  const notDone = mine.filter((l) => !laneDone(l, evidence));
   // spec 1.1 §9: a climb past the top rung (from === rung) leaves nothing to climb to; that is a decision
   const spent = notDone.filter((l) => {
     const last = routes.findLast((r) => r.lane === l);
     return last?.source === "climb" && last.from === last.rung;
   });
   const waiting = notDone.filter((l) => !spent.includes(l));
-  if (waiting.length) return `dispatch ${waiting.join(", ")}`;
+  // an After: line keeps a lane back until the lanes it names have finished
+  const held = new Map(waiting.map((l) => [l, unfinishedAfter(run, l, routes)]));
+  const ready = waiting.filter((l) => held.get(l)?.length === 0);
+  const order = waiting
+    .filter((l) => !ready.includes(l))
+    .map((l) => `${l} after ${held.get(l)?.join(", ")}`)
+    .join("; ");
+  if (ready.length) return `dispatch ${ready.join(", ")}${order ? `; then ${order}` : ""}`;
   if (spent.length) return `${spent.join(", ")}: out of rungs — ask finding, then the architect or park ${m}`;
   const running = live.filter((d) => d.admit.lane !== null && mine.includes(d.admit.lane));
-  if (running.length) return `${m}: lanes running (${running.map((d) => d.admit.name).join(", ")})`;
+  if (running.length)
+    return `${m}: lanes running (${running.map((d) => d.admit.name).join(", ")})${order ? `; then ${order}` : ""}`;
+  if (order) return `${m}: ${order} (After:), not done: finish those lanes first`;
   const start = milestoneStart(run, m);
-  if (!reviewerPassed(run, m, start)) return `${m}: reviewer`;
-  if (!verifierPassed(run, m, start)) return `${m}: verifier`;
+  if (!reviewerPassed(run, m, start)) {
+    // plan 23: a partial review is not the review: a second pass, scoped to what it did not read
+    const partial = partialReviewer(run, m, start);
+    return partial
+      ? `${m}: ${partial.name} stopped partial: a scoped second pass (reviewer-${m}-2) over the files it did not read`
+      : `${m}: reviewer`;
+  }
+  // plan 23: open BLOCKER and BUG lines go to the fix round before the verifier
+  const open = openFindings(run, m, start);
+  if (open)
+    return `${m}: fix round for ${open.name}'s findings (${open.blocker} BLOCKER, ${open.bug} BUG), then the verifier`;
+  const verdict = milestoneVerifier(run, m, start);
+  if (!verdict) return `${m}: verifier`;
+  // plan 23: the machine, not the work: the owner hears of it, and no fix round runs
+  if (verdict.blocked !== null)
+    return `${m}: ${verdict.name} is blocked by the environment${verdict.blocked ? ` (${verdict.blocked})` : ""}: surface it to the owner (park ${m}), not a fix round`;
+  if (!verdict.passed) {
+    // plan 23: a resumed verifier can hang; a re-check goes to a fresh one, told what failed
+    const failed = failedItems(run, m);
+    return `${m}: ${verdict.name} failed: the owning lanes fix it, then a fresh verifier (not a resume) re-checks ${failed.length ? failed.join(", ") : "the failed items"}, each command capped at ${RECHECK_COMMAND_MIN} min`;
+  }
   return `land ${m}`;
 }
 
@@ -121,21 +195,24 @@ export const protocolView = (run: Run, parked: string[], now?: number) => ({
   checklist: PROTOCOL_CHECKLIST,
 });
 
-const FINDING = /^\s*(?:[-*]\s*)?(BLOCKER|BUG|NIT)\b/;
-
 function findingCounts(run: Run, r: RunRecord | undefined): string {
   if (!r?.replyPath) return "no reply";
-  const file = join(run.dir, r.replyPath);
-  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
-  const n = { BLOCKER: 0, BUG: 0, NIT: 0 };
-  for (const line of text.split("\n")) {
-    const k = FINDING.exec(line)?.[1] as keyof typeof n | undefined;
-    if (k) n[k]++;
-  }
+  const n = countFindings(run, r) ?? { BLOCKER: 0, BUG: 0, NIT: 0 };
   const total = n.BLOCKER + n.BUG + n.NIT;
   return `${total} finding(s): ${n.BLOCKER} BLOCKER, ${n.BUG} BUG, ${n.NIT} NIT`;
 }
 
+/** The reviewer's BLOCKER and BUG lines, as it wrote them: what the digest lists as findings. */
+function findingLines(run: Run, r: RunRecord | null | undefined): string[] {
+  if (!r?.replyPath) return [];
+  const file = join(run.dir, r.replyPath);
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  return text
+    .split("\n")
+    .filter((l) => /^(BLOCKER|BUG)$/.test(FINDING.exec(l)?.[1] ?? ""))
+    .map((l) => l.trim().replace(/^[-*]\s*/, ""));
+}
+
 const k = (x: number) => (x >= 1000 ? `${Math.round(x / 1000)}k` : String(x));
 
 /**
@@ -145,7 +222,18 @@ const k = (x: number) => (x >= 1000 ? `${Math.round(x / 1000)}k` : String(x));
  */
 export function writeDigest(
   run: Run,
-  i: { milestone: string; what: string; commit: string; evidence: string; minutes: number; at: string },
+  i: {
+    milestone: string;
+    what: string;
+    commit: string;
+    evidence: string;
+    minutes: number;
+    at: string;
+    /** spec 1.5: the commits the milestone landed, `<hash> <subject>`, oldest first */
+    commits?: string[];
+    /** spec 1.5: the parked and paused minutes `minutes` leaves out */
+    pausedMinutes?: number;
+  },
 ): string {
   const m = i.milestone;
   const start = milestoneStart(run, m);
@@ -163,6 +251,9 @@ export function writeDigest(
   const records = readRecords(run).records;
   // the reviewer the gate counted: since the milestone's lanes started, a dispatch or a native subagent
   const reviewer = milestoneReviewer(run, m, start);
+  // spec 1.5: the review's BLOCKER and BUG lines, and the owner questions still open in the run
+  const findings = findingLines(run, reviewer?.record);
+  const open = openQuestions(run);
   const agents = readAgentRuns(run);
   // the verdict the gate counted: the latest attempt, native or headless, a FAIL shown as such
   const verdict = milestoneVerifier(run, m, start);
@@ -193,7 +284,8 @@ export function writeDigest(
   const text = [
     `# ${m} — ${i.what}`,
     "",
-    `Commit ${i.commit} · ${i.minutes} min · landed ${i.at}`,
+    `Commit ${i.commit} · ${i.minutes} min${i.pausedMinutes ? ` (${i.pausedMinutes} min parked or paused left out)` : ""} · landed ${i.at}`,
+    ...(i.commits?.length ? [`Commits: ${i.commits.join("; ")}`] : []),
     `A-lines: ${aLines.length ? aLines.join("; ") : "none named in what or evidence"}`,
     "",
     "Lanes:",
@@ -201,6 +293,8 @@ export function writeDigest(
     "",
     `Reviewer: ${reviewer ? `${reviewer.name} · ${reviewer.record ? findingCounts(run, reviewer.record) : "a Claude subagent (findings in its reply)"}` : "none"}`,
     `Verifier: ${verdict ? `${verdict.passed ? "PASS" : `FAIL: ${verdict.verdict}`} (${verdict.name}${verdict.headless ? ", headless" : ""})` : "none"}${steps.length ? ` · carried: ${steps.map((s) => `${s.item}${s.commit ? ` from ${s.commit}` : ""}`).join(", ")}` : ""}`,
+    `Findings: ${findings.length ? findings.join(" · ") : "no BLOCKER or BUG lines"}`,
+    `Open: ${open.length ? open.map((q) => `${q.milestone} parked: ${q.question}`).join(" · ") : "none"}`,
     `Evidence: ${i.evidence}`,
     `Tokens: ${k(tokens.input)} in (${k(tokens.cached)} cached) · ${k(tokens.output)} out · Claude subagents ${k(reported)} (reported)`,
     "",

package/src/services/provenance.ts

@@ -17,6 +17,8 @@ export interface ValueUsed {
   inferred: boolean;
   /** the rung the value belongs to, when it is not this one */
   from: string | null;
+  /** what lent it: a treat-like (a mapping, `like X`) or an inferred stand-in (a guess); null for its own */
+  lent: "treat-like" | "stand-in" | null;
 }
 
 /** Spec 1.2 §5.3: one threshold of the lane's bar, the value used against it, and whether it clears. */
@@ -40,8 +42,11 @@ export interface Provenance {
   /** facts that never carry a bar (spec 1.2 §4.1): `<source>.<field>` → value */
   speed: Record<string, number>;
   cost: Cost;
-  /** spec 1.2 §8: its runs for the lane's kind (or every kind) and over every kind; never used for routing */
-  evidence: { kind: string | null; all: string | null };
+  /**
+   * spec 1.2 §8: its runs for the lane's kind (or every kind) and over every kind; never used for routing;
+   * null when the runs could not be read
+   */
+  evidence: { kind: string | null; all: string | null } | null;
 }
 
 /** Spec 1.2 §5.3: each value a canonical rung has, with its confidence and source, borrowed ones marked. */
@@ -51,7 +56,8 @@ export function valuesUsed(c: Catalog, canonical: string): ValueUsed[] {
   return DIMS.flatMap((dim) => {
     const r = s.records[dim];
     if (!r) return [];
-    const from = s.borrowed.includes(dim) ? s.via : (s.standIns[dim] ?? null);
+    const borrowed = s.borrowed.includes(dim);
+    const from = borrowed ? s.via : (s.standIns[dim] ?? null);
     return [
       {
         dim,
@@ -63,6 +69,7 @@ export function valuesUsed(c: Catalog, canonical: string): ValueUsed[] {
         url: r.url,
         inferred: from !== null,
         from,
+        lent: from === null ? null : borrowed ? "treat-like" : "stand-in",
       },
     ];
   });
@@ -75,7 +82,7 @@ export function provenanceOf(
   kind: Kind | null,
   difficulty: Difficulty | null,
   billing: Partial<Record<string, BillingMode>>,
-  evidence: EvidenceTable,
+  evidence: EvidenceTable | null,
 ): Provenance {
   const info = rungInfo(c, rung);
   const values = valuesUsed(c, info.canonical);
@@ -90,7 +97,10 @@ export function provenanceOf(
         min,
         used,
         clears: used !== null && used.value >= min,
-        why: c.barsWhy[dim]?.[difficulty] ?? null,
+        // a threshold the user's override set is theirs, whatever the default's why says (1.2 minor)
+        why: c.userBars?.includes(`${kind}/${difficulty}/${dim}`)
+          ? "your override"
+          : (c.barsWhy[dim]?.[difficulty] ?? null),
       },
     ];
   });
@@ -101,15 +111,9 @@ export function provenanceOf(
     values,
     speed: info.family?.speed ?? {},
     cost: costOf(info.family, info.parsed.effort, billing[info.key] ?? DEFAULT_BILLING[info.key]),
-    evidence: {
+    evidence: evidence && {
       kind: evidenceLine(evidenceOf(evidence, info.canonical, kind)),
       all: evidenceLine(evidenceOf(evidence, info.canonical)),
     },
   };
 }
-
-/** A value as one line: `repo_code 66.6 (adjacent, shipped DeepSWE 1.1, 2026-09-22)`, marking a guess. */
-export function valueWords(v: ValueUsed): string {
-  const lent = v.inferred ? `, inferred from ${v.from}` : "";
-  return `${v.dim} ${v.value} (${v.confidence}, ${v.source} ${v.benchmark}, ${v.date}${lent})`;
-}

package/src/services/questions.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { CatherdError } from "../domain/errors.ts";
 import { assertId } from "../domain/ids.ts";
+import type { Span } from "../domain/util.ts";
 import { appendJsonl, ensureJsonlHeader, readJsonl } from "../infra/store.ts";
 import type { Deps } from "./ports.ts";
 import { findRun, type Run } from "./run-store.ts";
@@ -38,6 +39,20 @@ export function openQuestions(run: Run): OpenQuestion[] {
   return [...open.values()];
 }
 
+/** Spec 1.5 "The ledger": when `milestone` was parked, question to answer; the last one open while unanswered. */
+export function parkedSpans(run: Run, milestone: string): Span[] {
+  const out: Span[] = [];
+  for (const r of rows(run)) {
+    if (r.milestone !== milestone) continue;
+    const at = Date.parse(r.at);
+    if (Number.isNaN(at)) continue;
+    const open = out.at(-1);
+    if (r.kind === "question" && (!open || open.to !== null)) out.push({ from: at, to: null });
+    else if (r.kind === "answer" && open && open.to === null) open.to = at;
+  }
+  return out;
+}
+
 function append(run: Run, row: QuestionRow): void {
   const file = questionsFile(run);
   ensureJsonlHeader(file, "questions");

package/src/services/reconcile.ts

@@ -3,7 +3,7 @@ import { errorMessage } from "../domain/errors.ts";
 import { dispatchPaths } from "../infra/dispatch-dir.ts";
 import { log } from "../infra/log.ts";
 import { writeJsonAtomic } from "../infra/store.ts";
-import { settle, stallPoll, unsettledLimits, watching } from "./dispatch-service.ts";
+import { recoverOwned, settle, stallPoll, unsettledLimits, watching } from "./dispatch-service.ts";
 import { type Dispatch, listDispatches, pendingDispatches } from "./dispatches.ts";
 import { finalizeDispatch, waitForFinish } from "./finalize.ts";
 import type { Deps } from "./ports.ts";
@@ -57,6 +57,27 @@ async function watchAndFinalize(deps: Deps, run: Run, d: Dispatch): Promise<void
   }
 }
 
+/**
+ * Plan 22, final-review I2: a server that does not lead the boot still watches the live roles of the runs its
+ * own session owns, so a coordinator's server that restarts mid-run (an /mcp reconnect, a crash) while another
+ * session's server holds the boot lock still finalizes and announces them. It also records and announces the
+ * roles of those runs that finished while it was away (no live process, no record: PR #47 P1), as a claim
+ * does. A second watcher of a dispatch the lead also watches is harmless: finalize and failover run once, and
+ * a role another live process is finalizing is left to it. A run that cannot be read is skipped, logged.
+ */
+export function adoptOwned(deps: Deps): void {
+  for (const run of listRuns().runs) {
+    try {
+      if (!ownsRun(deps, run)) continue;
+      recoverOwned(deps, run, { background: true }).catch((e: unknown) =>
+        log("warn", "reconcile", { run: run.id, error: errorMessage(e) }),
+      );
+    } catch (e) {
+      log("warn", "reconcile", { run: run.id, error: errorMessage(e) });
+    }
+  }
+}
+
 /**
  * Spec §4.7: on server start, finalize and settle each finished dispatch that has no record, settle each
  * unread usage limit that was never failed over (its server died between the two), and watch each live one

package/src/services/reentry.ts

@@ -1,8 +1,8 @@
-import { latestVerifierStep, type VerifierStep } from "./gate-service.ts";
 import { protocolView } from "./protocol.ts";
 import { type OpenQuestion, openQuestions } from "./questions.ts";
 import type { Run } from "./run-store.ts";
-import { readNotes } from "./state.ts";
+import { type Notes, readNotes } from "./state.ts";
+import { verifierStepView, type VerifierStepView } from "./verifier-step.ts";
 
 // Spec 1.1 §8, §7 and §10: what a session re-entering a run needs first, as peek returns it: the owner questions still open, the protocol's next step with its checklist,
 // and the verifier's latest step.
@@ -10,13 +10,14 @@ import { readNotes } from "./state.ts";
 export interface Reentry {
   questions: OpenQuestion[];
   protocol: { next: string; checklist: string[] };
-  verifier: VerifierStep | null;
+  verifier: VerifierStepView | null;
 }
 
-export function reentry(run: Run, now?: number): Reentry {
+/** `notes`: state.json as the caller already read it (peek), so it is read once. */
+export function reentry(run: Run, now?: number, notes: Notes = readNotes(run)): Reentry {
   return {
     questions: openQuestions(run),
-    protocol: protocolView(run, readNotes(run).parked ?? [], now),
-    verifier: latestVerifierStep(run),
+    protocol: protocolView(run, notes.parked ?? [], now),
+    verifier: verifierStepView(run, now ?? Date.now()),
   };
 }

package/src/services/role-access.ts

@@ -0,0 +1,27 @@
+import { CatherdError } from "../domain/errors.ts";
+import type { RoleScope } from "../domain/role-scope.ts";
+import { roleMcpTools } from "../domain/role-tools.ts";
+import { latestDispatch } from "./dispatches.ts";
+import { findRun } from "./run-store.ts";
+
+/**
+ * Spec 1.5 plan 21: what the role server lets a role do, for the CLI forms any role can run
+ * (`catherd run-file`, `catherd gate`). Outside a role (`scope` null: the user's own terminal) everything is
+ * allowed. In a role, only its own run, and only the operations its role server would list (`tool`).
+ */
+export function assertRoleMay(scope: RoleScope | null, run: string, tool: string): void {
+  if (!scope) return;
+  if (scope.run !== run)
+    throw new CatherdError(
+      "E_ROLE_SCOPE",
+      `this process runs ${scope.name} of run ${scope.run}, not of run ${run}`,
+      { fix: `use run ${scope.run}` },
+    );
+  const role = latestDispatch(findRun(run), scope.name)?.admit.role;
+  if (!role || !roleMcpTools(role).includes(tool))
+    throw new CatherdError(
+      "E_ROLE_SCOPE",
+      `${scope.name} ${role ? `is a ${role}, which has no ${tool}` : `is no dispatch of run ${run}`}`,
+      { fix: "report it in your reply; the orchestrator does it" },
+    );
+}