catherd-cli 1.4.0 → 1.5.0

package/src/services/routing-service.ts

@@ -13,11 +13,13 @@ import {
 import { type Difficulty, type Kind, parseLaneHeader } from "../domain/lane.ts";
 import type { Role } from "../domain/roles.ts";
 import type { RouteJev } from "../domain/route.ts";
+import type { Catalog } from "../domain/catalog.ts";
 import {
   candidates,
   defaultDifficulty,
   defaultLadder,
   type Pick,
+  quotaUsage,
   type RoutingProfile,
   select,
 } from "../domain/select.ts";
@@ -26,11 +28,17 @@ import { catalogQuery, freshenDiscovery, loadCatalog } from "./catalog-service.t
 import { type Asked, askJev, type JevOpts, jevQuestions, logJev } from "./jev-service.ts";
 import type { ProfileView, RouteAnswer, RouteRequest, RoutingPort, Verdict } from "./ports.ts";
 import { provenanceOf } from "./provenance.ts";
-import { runEvidence } from "./run-evidence.ts";
+import { type EvidenceTable, runEvidence } from "./run-evidence.ts";
 
-function routingProfile(v: ProfileView, role: Role, spentFraction: number): RoutingProfile {
+function routingProfile(
+  v: ProfileView,
+  role: Role,
+  spentFraction: number,
+  usage: Record<string, number> = {},
+): RoutingProfile {
   const rc = v.roles[role];
   return {
+    usage,
     // spec §4.6: from 80 % of the budget on, start at the cheapest rung that clears the bar
     objective: spentFraction >= BUDGET_CHEAP_AT ? "cost" : v.objective,
     billing: v.billing,
@@ -50,14 +58,60 @@ const answer = (
   asked: Asked | null,
   jev: RouteJev | null,
 ): RouteAnswer => ({
-  ...pick,
+  rung: pick.rung,
+  ladder: pick.ladder,
   source,
   kind,
   difficulty,
   questionSet: asked?.answers ? asked.meta.questionSet : null,
   jev,
+  jevSaid: null,
+  why: "",
+  ...(pick.noClear ? { noClear: pick.noClear } : {}),
+  ...(pick.tie ? { tie: pick.tie } : {}),
 });
 
+/** Spec 1.5 plan 24: what Jev said when it differs from the kind and difficulty the route used, else null. */
+function jevSaid(
+  judged: ReturnType<typeof judgeRoute> | null,
+  kind: Kind | null,
+  difficulty: Difficulty | null,
+): string | null {
+  if (!judged) return null;
+  const k = judged.kind;
+  const d = judged.track ? judged.difficulty : null;
+  if ((k === null || k === kind) && (d === null || d === difficulty)) return null;
+  return `Jev said ${k ?? "no sure kind"}/${d ?? "no sure difficulty"}`;
+}
+
+/** Spec 1.5 plan 24: the route's one-line why, for the coordinator; the provenance goes to routes.jsonl. */
+function whyOf(a: RouteAnswer, hasLane: boolean): string {
+  const what = `${a.kind}/${a.difficulty}`;
+  const head =
+    a.source === "lane"
+      ? `the lane's Kind/Difficulty, ${what}`
+      : a.source === "jev"
+        ? `Jev: ${what}`
+        : a.source === "jev-kind"
+          ? `Jev's kind with ${what}`
+          : hasLane
+            ? "the role's default rung: neither Jev nor the lane file gave a kind and difficulty"
+            : "the role's default rung";
+  const start =
+    a.noClear ?? (a.source === "default" ? null : "the first rung in objective order that clears it");
+  return [head, a.jevSaid, start, a.tie].filter((x): x is string => Boolean(x)).join("; ");
+}
+
+/** Spec 1.2 §8 evidence is display only: an unreadable run on this machine never fails a route. */
+function evidenceOrNone(c: Catalog): EvidenceTable | null {
+  try {
+    return runEvidence(c);
+  } catch (e) {
+    log("debug", "route", { evidence: errorMessage(e) });
+    return null;
+  }
+}
+
 /** How long `route` waits on the daily discovery refresh before routing on the cached listing. */
 const DISCOVERY_BUDGET_MS = 5_000;
 
@@ -79,53 +133,77 @@ async function freshenWithin(rungs: string[], repo: string, ms: number): Promise
   clearTimeout(timer);
 }
 
+/** What every route of one call shares: the role's routing profile and the catalog. */
+interface Prepared {
+  p: RoutingProfile;
+  c: Catalog;
+}
+
+async function prepare(req: RouteRequest, o: RoutingOpts): Promise<Prepared> {
+  const p = routingProfile(req.profile, req.role, req.spentFraction, req.usage);
+  await freshenWithin(p.role.rungs, req.repo, o.discoveryBudgetMs ?? DISCOVERY_BUDGET_MS);
+  return { p, c: loadCatalog({ repo: req.repo }) };
+}
+
+/** Jev's answer about a lane; null when the route reads no lane, empty when it asks nothing (Jev off, one usable rung). */
+interface Judged {
+  asked: Asked | null;
+  judged: ReturnType<typeof judgeRoute> | null;
+}
+
+async function judge(req: RouteRequest, { p, c }: Prepared, o: RoutingOpts): Promise<Judged | null> {
+  if (req.laneText === null) return null;
+  // one usable rung: nothing for Jev to choose, but the lane's header still names its kind and difficulty
+  if (req.profile.jev.use === "off" || candidates(c, p, req.role).length <= 1)
+    return { asked: null, judged: null };
+  const asked = await askJev(req.runDir, "route-v2", laneState(req.laneText), o);
+  const judged = asked.answers ? judgeRoute(jevQuestions().sets["route-v2"].rule, asked.answers) : null;
+  return { asked, judged };
+}
+
 /**
- * Spec §5.4: kind and difficulty from Jev (§5.5's rule), else the lane file's `Kind:`/`Difficulty:`,
- * else the role's default rung. A kind Jev is sure of survives a difficulty in the dead band: the
- * difficulty then comes from the lane, else the role's default difficulty (`jev-kind`). A role with one
- * usable rung never asks Jev.
+ * Spec §5.4: kind and difficulty from the lane file's `Kind:`/`Difficulty:` when it declares both (spec 1.5
+ * plan 24: a declared header wins, and `jevSaid` names where Jev disagreed), else from Jev (§5.5's rule), else
+ * the role's default rung. A kind Jev is sure of survives a difficulty in the dead band: the difficulty then
+ * comes from the lane, else the role's default difficulty (`jev-kind`). A role with one usable rung never asks
+ * Jev.
  */
-async function route(req: RouteRequest, o: RoutingOpts): Promise<RouteAnswer> {
-  const p = routingProfile(req.profile, req.role, req.spentFraction);
-  await freshenWithin(p.role.rungs, req.repo, o.discoveryBudgetMs ?? DISCOVERY_BUDGET_MS);
-  const c = loadCatalog({ repo: req.repo });
+function decide(req: RouteRequest, { p, c }: Prepared, j: Judged | null): RouteAnswer {
   const fallback = () => defaultLadder(c, p, req.role);
-  if (req.laneText === null || candidates(c, p, req.role).length <= 1) {
-    const out = answer(fallback(), "default", null, null, null, null);
-    return { ...out, provenance: provenanceOf(c, out.rung, null, null, p.billing, runEvidence(c)) };
-  }
+  const finish = (out: RouteAnswer): RouteAnswer => {
+    out.why = whyOf(out, req.laneText !== null);
+    out.provenance = provenanceOf(c, out.rung, out.kind, out.difficulty, p.billing, evidenceOrNone(c));
+    return out;
+  };
+  if (req.laneText === null || j === null)
+    return finish(answer(fallback(), "default", null, null, null, null));
   const lane = parseLaneHeader(req.laneText);
-  let asked: Asked | null = null;
-  let judged: ReturnType<typeof judgeRoute> | null = null;
-  if (req.profile.jev.use !== "off") {
-    asked = await askJev(req.runDir, "route-v2", laneState(req.laneText), o);
-    if (asked.answers) judged = judgeRoute(jevQuestions().sets["route-v2"].rule, asked.answers);
-  }
+  const { asked, judged } = j;
   const jev: RouteJev | null = judged
     ? { pKind: judged.pKind, pA: judged.pA, pB: judged.pB, nouls: judged.nouls }
     : null;
   let out: RouteAnswer;
-  if (judged?.track && judged.difficulty) {
-    const kind = judged.kind ?? lane.kind ?? "repo_code";
-    out = answer(select(c, p, req.role, kind, judged.difficulty), "jev", kind, judged.difficulty, asked, jev);
-  } else if (judged?.kind) {
-    const difficulty = lane.difficulty ?? defaultDifficulty(c, p, req.role, judged.kind);
+  if (lane.kind && lane.difficulty) {
     out = answer(
-      select(c, p, req.role, judged.kind, difficulty),
-      "jev-kind",
-      judged.kind,
-      difficulty,
+      select(c, p, req.role, lane.kind, lane.difficulty),
+      "lane",
+      lane.kind,
+      lane.difficulty,
       asked,
       jev,
     );
+  } else if (judged?.track && judged.difficulty) {
+    const kind = lane.kind ?? judged.kind ?? "repo_code";
+    out = answer(select(c, p, req.role, kind, judged.difficulty), "jev", kind, judged.difficulty, asked, jev);
+  } else if (judged?.kind || (judged && lane.kind)) {
+    const kind = (lane.kind ?? judged.kind) as Kind;
+    const difficulty = lane.difficulty ?? defaultDifficulty(c, p, req.role, kind);
+    out = answer(select(c, p, req.role, kind, difficulty), "jev-kind", kind, difficulty, asked, jev);
   } else {
-    const kind = lane.kind;
-    out =
-      kind && lane.difficulty
-        ? answer(select(c, p, req.role, kind, lane.difficulty), "lane", kind, lane.difficulty, asked, jev)
-        : answer(fallback(), "default", null, null, asked, jev);
+    out = answer(fallback(), "default", null, null, asked, jev);
   }
-  out.provenance = provenanceOf(c, out.rung, out.kind, out.difficulty, p.billing, runEvidence(c));
+  out.jevSaid = out.source === "default" ? null : jevSaid(judged, out.kind, out.difficulty);
+  finish(out);
   if (asked) {
     logJev(req.runDir, {
       ...asked.meta,
@@ -143,6 +221,31 @@ async function route(req: RouteRequest, o: RoutingOpts): Promise<RouteAnswer> {
   return out;
 }
 
+async function route(req: RouteRequest, o: RoutingOpts): Promise<RouteAnswer> {
+  const prep = await prepare(req, o);
+  return decide(req, prep, await judge(req, prep, o));
+}
+
+/**
+ * Spec 1.5 plan 24, batch `route`: the lanes of one role (one run, one profile) share one discovery refresh and
+ * one catalog, and Jev is asked about all of them at once (Ruling 6: one request per lane, all in flight
+ * together, so each keeps its own cache key and jev.jsonl row). Then each lane is decided in order, every
+ * routed start counting as a use of its quota, so lanes that tie spread over the quotas.
+ */
+async function routeMany(reqs: RouteRequest[], o: RoutingOpts): Promise<RouteAnswer[]> {
+  const first = reqs[0];
+  if (!first) return [];
+  const prep = await prepare(first, o);
+  const judged = await Promise.all(reqs.map((r) => judge(r, prep, o)));
+  const usage: Record<string, number> = { ...first.usage };
+  return reqs.map((req, i) => {
+    const out = decide(req, { ...prep, p: { ...prep.p, usage: { ...usage } } }, judged[i] ?? null);
+    const q = quotaUsage([out.rung]);
+    for (const [k, n] of Object.entries(q)) usage[k] = (usage[k] ?? 0) + n;
+    return out;
+  });
+}
+
 async function verdict<T extends string>(
   runDir: string,
   set: Extract<SetName, "finding" | "same-defect">,
@@ -177,6 +280,11 @@ export function routingService(o: RoutingOpts = {}): RoutingPort {
       assertNativeHost(result.rung, req.host ?? "unknown");
       return result;
     },
+    routeMany: async (reqs) => {
+      const results = await routeMany(reqs, o);
+      results.forEach((r, i) => assertNativeHost(r.rung, reqs[i]?.host ?? "unknown"));
+      return results;
+    },
     finding: (runDir, laneText, finding, use) =>
       verdict(
         runDir,

package/src/services/run-pin.ts

@@ -0,0 +1,125 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { errorMessage } from "../domain/errors.ts";
+import { ACCESS } from "../domain/record.ts";
+import { ROLES } from "../domain/roles.ts";
+import { readVersioned, writeJsonAtomic } from "../infra/store.ts";
+import type { Deps, ProfileView } from "./ports.ts";
+import { findRun, type Run } from "./run-store.ts";
+import { refreshState } from "./state.ts";
+
+// Spec 1.5 "Pinned per run": run_start records the profile the run started on, each role's access and each
+// backend's isolation. A later change (another active profile, a toggled isolation, a version that changed a
+// default) is logged in state.md and status, and dispatch keeps the pinned values until the owner re-pins.
+
+const PinSchema = z.looseObject({
+  schema: z.literal(1),
+  at: z.string(),
+  profile: z.string(),
+  access: z.partialRecord(z.enum(ROLES), z.enum(ACCESS)),
+  isolated: z.record(z.string(), z.boolean()),
+});
+export type Pin = z.infer<typeof PinSchema>;
+
+export const pinFile = (run: Run): string => join(run.dir, "pin.json");
+
+/** The run's pin, or null: a run from before 1.5, or a pin that cannot be read (the profile then rules). */
+export function readPin(run: Run): Pin | null {
+  if (!existsSync(pinFile(run))) return null;
+  try {
+    return readVersioned(pinFile(run), PinSchema, 1);
+  } catch {
+    return null;
+  }
+}
+
+const pinOf = (view: ProfileView, at: string): Pin => ({
+  schema: 1,
+  at,
+  profile: view.name,
+  access: Object.fromEntries(
+    Object.entries(view.roles).flatMap(([role, rc]) => (rc ? [[role, rc.access]] : [])),
+  ),
+  isolated: Object.fromEntries(Object.entries(view.isolated).map(([k, v]) => [k, v === true])),
+});
+
+/** Records what the run runs on now: the profile its repo runs on, each role's access, each backend's isolation. */
+export function writePin(deps: Deps, run: Run): Pin {
+  const pin = pinOf(deps.profiles.forRepo(run.meta.repo), new Date(deps.now()).toISOString());
+  writeJsonAtomic(pinFile(run), pin);
+  return pin;
+}
+
+/** The pinned profile's view, or null with why when it can no longer be read (deleted, invalid). */
+function pinnedView(deps: Deps, run: Run, pin: Pin): { view: ProfileView | null; why: string | null } {
+  const current = deps.profiles.forRepo(run.meta.repo);
+  if (current.name === pin.profile) return { view: current, why: null };
+  try {
+    return { view: deps.profiles.get(pin.profile, run.meta.repo).profile, why: null };
+  } catch (e) {
+    return { view: null, why: errorMessage(e) };
+  }
+}
+
+/**
+ * The profile a run's dispatch, routing and failover read: its pinned profile, with its pinned access and
+ * isolation laid over it. A run with no pin, or whose pinned profile is gone, reads its repo's profile.
+ */
+export function runProfile(deps: Deps, run: Run): ProfileView {
+  const pin = readPin(run);
+  if (!pin) return deps.profiles.forRepo(run.meta.repo);
+  const view = pinnedView(deps, run, pin).view ?? deps.profiles.forRepo(run.meta.repo);
+  const roles: ProfileView["roles"] = {};
+  for (const [role, rc] of Object.entries(view.roles) as [
+    keyof ProfileView["roles"],
+    NonNullable<ProfileView["roles"][keyof ProfileView["roles"]]>,
+  ][])
+    roles[role] = { ...rc, access: pin.access[role] ?? rc.access };
+  // a backend the pin does not name ran with no isolation when the run started
+  const backends = new Set([...Object.keys(view.isolated), ...Object.keys(pin.isolated)]);
+  const isolated = Object.fromEntries([...backends].map((k) => [k, pin.isolated[k] === true]));
+  return { ...view, roles, isolated };
+}
+
+/** What changed since the pin, one line each, in words; none while the run's repo still runs as pinned. */
+export function pinChanges(deps: Deps, run: Run): string[] {
+  const pin = readPin(run);
+  if (!pin) return [];
+  let now: ProfileView;
+  try {
+    now = deps.profiles.forRepo(run.meta.repo);
+  } catch {
+    // a profile that cannot be read is doctor's and profile validate's to report, not a pin change
+    return [];
+  }
+  const out: string[] = [];
+  if (now.name !== pin.profile) {
+    const { why } = pinnedView(deps, run, pin);
+    out.push(
+      `profile: pinned ${pin.profile}, the repo now runs on ${now.name}${why ? ` (${pin.profile} cannot be read: ${why}; dispatch reads ${now.name})` : ""}`,
+    );
+  }
+  for (const [role, access] of Object.entries(pin.access)) {
+    const was = now.roles[role as keyof ProfileView["roles"]]?.access;
+    if (was !== undefined && was !== access) out.push(`${role} access: pinned ${access}, now ${was}`);
+  }
+  for (const backend of new Set([...Object.keys(pin.isolated), ...Object.keys(now.isolated)])) {
+    const isolated = pin.isolated[backend] === true;
+    const was = now.isolated[backend] === true;
+    if (was !== isolated) out.push(`${backend} isolated: pinned ${isolated}, now ${was}`);
+  }
+  return out;
+}
+
+/** `run_pin`: the owner re-pins the run to what its repo runs on now. Returns the new pin and what it changed. */
+export async function repin(
+  deps: Deps,
+  i: { run: string },
+): Promise<{ pin: Pin; changed: string[]; hints?: string[] }> {
+  const run = findRun(i.run);
+  const changed = pinChanges(deps, run);
+  const pin = writePin(deps, run);
+  const { hints } = await refreshState(run, { pinChanges: [] });
+  return { pin, changed, ...(hints.length ? { hints } : {}) };
+}

package/src/services/run-service.ts

@@ -1,17 +1,20 @@
 import { existsSync, readFileSync } from "node:fs";
-import { relative } from "node:path";
+import { relative, sep } from "node:path";
 import { CatherdError } from "../domain/errors.ts";
 import { assertId, parseRung } from "../domain/ids.ts";
+import { assertLaneValues } from "../domain/lane.ts";
 import type { RunRecord } from "../domain/record.ts";
 import type { Role } from "../domain/roles.ts";
 import { awaitsCollect, dispatchPaths, endCollect, tryCollect } from "../infra/dispatch-dir.ts";
-import { gitToplevel } from "../infra/git.ts";
-import { writeTextAtomic } from "../infra/store.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { git, gitToplevel } from "../infra/git.ts";
+import { writeJsonAtomic, writeTextAtomic } from "../infra/store.ts";
 import {
   dispatchState,
   type DispatchState,
   latestDispatch,
   listDispatches,
+  liveDispatches,
   recordHints,
 } from "./dispatches.ts";
 import type { Deps } from "./ports.ts";
@@ -22,17 +25,91 @@ import {
   appendKnowledge,
   createRun,
   findRun,
-  knowledgeFile,
+  knowledgeFor,
   readRecords,
   runFile,
+  type Run,
+  runPaths,
+  supersededBy,
+  supersededFile,
 } from "./run-store.ts";
-import { protocolView } from "./protocol.ts";
+import { protocolNext, protocolView } from "./protocol.ts";
+import { writePin } from "./run-pin.ts";
 import { claimRun, currentSession } from "./sessions.ts";
-import { refreshState } from "./state.ts";
+import { readNotes, refreshState } from "./state.ts";
+
+/** The run `id` was superseded by, or undefined: an open run, or one that cannot be found. */
+function nextInChain(id: string): string | undefined {
+  try {
+    return supersededBy(findRun(id))?.by;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `runs supersede <run> --by <run>`: closes `run` with a pointer to the run that took it over (a planning
+ * run handed to the execution run in a worktree). Status hides it; dispatch refuses it. A run with live
+ * roles is refused: cancel them, or let them finish, first.
+ */
+export async function supersedeRun(
+  deps: Deps,
+  i: { run: string; by: string },
+): Promise<{ run: string; by: string; at: string; hints?: string[] }> {
+  const run = findRun(i.run);
+  const by = findRun(i.by);
+  if (run.id === by.id)
+    throw new CatherdError("E_INPUT_INVALID", `run ${run.id} cannot supersede itself`, {
+      fix: "pass the run that took over as --by",
+    });
+  // walk the chain the new pointer would join: any run it reaches back to `run` closes a cycle
+  const seen = new Set<string>([by.id]);
+  for (let hop = supersededBy(by)?.by; hop !== undefined && !seen.has(hop);) {
+    if (hop === run.id)
+      throw new CatherdError("E_INPUT_INVALID", `run ${by.id} is itself superseded by ${run.id}`, {
+        fix: "supersede the older run by the newer one",
+      });
+    seen.add(hop);
+    hop = nextInChain(hop);
+  }
+  // under the run's admission lock: a dispatch admitted meanwhile is either live here, or sees the pointer
+  const at = await withFileLock(runPaths(run.dir).admission, () => {
+    assertNoLiveRoles(
+      deps,
+      run,
+      `cancel them (cancel(run, name)) or let them finish, then supersede ${run.id}`,
+    );
+    return writeSuperseded(deps, run, by.id);
+  });
+  return { run: run.id, by: by.id, at, ...(await supersededHints(run, by.id)) };
+}
+
+/** Held under `run`'s admission lock: no role of it may be live when it closes. */
+function assertNoLiveRoles(deps: Deps, run: Run, fix: string): void {
+  const live = liveDispatches(run, deps.now());
+  if (live.length)
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      `run ${run.id} still has live roles: ${live.map((d) => d.admit.name).join(", ")}`,
+      { fix },
+    );
+}
+
+/** Held under `run`'s admission lock: the pointer to the run that took it over; its time. */
+function writeSuperseded(deps: Deps, run: Run, by: string): string {
+  const when = new Date(deps.now()).toISOString();
+  writeJsonAtomic(supersededFile(run), { schema: 1, by, at: when });
+  return when;
+}
+
+async function supersededHints(run: Run, by: string): Promise<{ hints?: string[] }> {
+  const { hints } = await refreshState(run, { next: `superseded by ${by}: continue there` });
+  return hints.length ? { hints } : {};
+}
 
 export async function startRun(
   deps: Deps,
-  i: { repo: string; title: string; aLines: string[] },
+  i: { repo: string; title: string; aLines: string[]; from?: string },
 ): Promise<{
   run: string;
   dir: string;
@@ -44,17 +121,39 @@ export async function startRun(
     throw new CatherdError("E_IO_PATH", `${i.repo} is not inside a git repository`, {
       fix: "pass the path of the repository to work in",
     });
-  const run = createRun({
-    repo: top,
-    title: i.title,
-    aLines: i.aLines,
-    version: deps.version,
-    now: new Date(deps.now()),
-    startedBy: currentSession(deps),
-  });
-  await claimRun(deps, run);
+  // where the first milestone's commit range starts; a repo with no commit yet has none
+  const head = await git(top, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+  const open = async (): Promise<Run> => {
+    const run = createRun({
+      repo: top,
+      title: i.title,
+      aLines: i.aLines,
+      version: deps.version,
+      startHead: head.kind === "ok" ? head.out.trim() || null : null,
+      now: new Date(deps.now()),
+      startedBy: currentSession(deps),
+    });
+    // spec 1.5 "Pinned per run": what the run starts on stays what it dispatches on
+    writePin(deps, run);
+    await claimRun(deps, run);
+    return run;
+  };
+  // the run this one takes over must be free to close before anything is created, and stay so until its pointer
+  // is written: its admission lock is held from the check to the pointer, so no dispatch gets in between and
+  // leaves the new run open beside it (PR #50). It is the only lock taken first: the new run's are uncontended.
+  const from = i.from === undefined ? null : findRun(i.from);
+  const run = from
+    ? await withFileLock(runPaths(from.dir).admission, async () => {
+        assertNoLiveRoles(deps, from, `cancel them or let them finish, then run_start with from: ${from.id}`);
+        const opened = await open();
+        writeSuperseded(deps, from, opened.id);
+        return opened;
+      })
+    : await open();
+  const superseded = from ? await supersededHints(from, run.id) : {};
   // a failed state.md refresh never fails the start: the run exists and is usable, so a retry would orphan it
   const { hints } = await refreshState(run);
+  hints.push(...(superseded.hints ?? []));
   // spec 1.1 §10: the milestone loop, so the orchestrator starts on the protocol
   return { run: run.id, dir: run.dir, protocol: protocolView(run, []), ...(hints.length ? { hints } : {}) };
 }
@@ -63,7 +162,11 @@ export function writeRunFile(i: { run: string; path: string; content: string }):
   path: string;
   bytes: number;
 } {
-  const file = runFile(findRun(i.run), i.path, "write");
+  const run = findRun(i.run);
+  const file = runFile(run, i.path, "write");
+  // spec 1.5 "Lane editing": a lane's header values are checked when it is written, not first at preflight
+  const lane = /^lanes\/([^/]+)\.md$/.exec(relative(run.dir, file).split(sep).join("/"));
+  if (lane) assertLaneValues(i.content, `lanes/${lane[1]}.md`);
   writeTextAtomic(file, i.content);
   return { path: file, bytes: Buffer.byteLength(i.content) };
 }
@@ -99,6 +202,28 @@ function capReply(reply: string, path: string): string {
   return `${head.slice(0, CAP_CHARS)}\n[capped: the full reply is ${path}]`;
 }
 
+/** Whether `text` names `token` (a role name or lane id) as a whole word, a full stop after it allowed. */
+export function names(text: string, token: string): boolean {
+  const t = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?<![\\w.-])${t}(?![\\w-]|\\.\\w)`).test(text);
+}
+
+/**
+ * Plan 22: state.md's Next never outlives the step it names. When it names a role whose record `result` returns
+ * (by its name or its lane), it moves on to the protocol's next step. A refresh that fails comes back as hints.
+ */
+async function advanceNext(run: Run, record: RunRecord): Promise<string[]> {
+  const stale = (next: string) =>
+    names(next, record.name) || (record.lane !== null && names(next, record.lane));
+  if (!stale(readNotes(run).next)) return [];
+  const { hints } = await refreshState(run, (n) =>
+    stale(n.next)
+      ? { next: `after ${record.name} (${record.status}): ${protocolNext(run, n.parked ?? [])}` }
+      : {},
+  );
+  return hints;
+}
+
 /**
  * A role's latest dispatch: its record once finished, its capped reply and its hints. Spec §3.7: reading a
  * finished record marks it read, with the collect lease (each record is marked read once, whoever reads it);
@@ -134,6 +259,7 @@ export async function result(
     if (x.admit.dispatchId !== d.admit.dispatchId) hints.push(...recordHints(run, x, r));
   }
   if (record) for (const h of recordHints(run, d, record)) if (!hints.includes(h)) hints.push(h);
+  if (record) for (const h of await advanceNext(run, record)) if (!hints.includes(h)) hints.push(h);
   const reply = dispatchPaths(d.dir).reply;
   const text = existsSync(reply) ? readFileSync(reply, "utf8") : "";
   return {
@@ -159,6 +285,10 @@ export function recordAgentRun(
     durationMs?: number;
     status?: AgentRun["status"];
     lane?: string;
+    /** plan 23: a native verifier's first reply line, so a VERDICT: BLOCKED: environment is told from a FAIL */
+    verdict?: string;
+    /** plan 23: the STATUS word of the subagent's reply */
+    replyStatus?: NonNullable<AgentRun["replyStatus"]>;
   },
 ): AgentRun {
   const run = findRun(i.run);
@@ -180,6 +310,8 @@ export function recordAgentRun(
     secs: i.durationMs === undefined ? null : Math.round(i.durationMs / 1000),
     status: i.status ?? "ok",
     lane: i.lane ?? null,
+    ...(i.verdict ? { verdict: i.verdict.trim().split("\n")[0] } : {}),
+    ...(i.replyStatus ? { replyStatus: i.replyStatus } : {}),
   };
   appendAgentRun(run, row);
   return row;
@@ -197,7 +329,7 @@ async function repoTop(repo: string): Promise<string> {
 
 /** What past runs of the repo learned; `repo` may be any path inside it. */
 export async function readKnowledge(repo: string): Promise<string> {
-  const file = knowledgeFile(await repoTop(repo));
+  const file = await knowledgeFor(await repoTop(repo));
   const text = existsSync(file) ? readFileSync(file, "utf8") : "";
   return text.trim() ? text : "catherd: no knowledge recorded yet for this repo";
 }
@@ -205,7 +337,7 @@ export async function readKnowledge(repo: string): Promise<string> {
 /** Where the repo's knowledge.md is (it may not exist yet); `repo` may be any path inside it. */
 export async function knowledgePath(repo: string): Promise<{ repo: string; path: string }> {
   const top = await repoTop(repo);
-  return { repo: top, path: knowledgeFile(top) };
+  return { repo: top, path: await knowledgeFor(top) };
 }
 
 /** The repo's knowledge.md as its lines, none when it is missing or blank; `repo` may be any path inside it. */