catherd-cli 1.4.0 → 1.5.0

package/src/services/lane-edit.ts

@@ -0,0 +1,154 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CatherdError } from "../domain/errors.ts";
+import { assertId } from "../domain/ids.ts";
+import {
+  assertLaneValues,
+  headerBlock,
+  headerLine,
+  type LaneHeader,
+  normalizeOwned,
+  overlaps,
+  parseLaneHeader,
+} from "../domain/lane.ts";
+import { cell } from "../domain/util.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { writeTextAtomic } from "../infra/store.ts";
+import { pendingDispatches } from "./dispatches.ts";
+import type { Deps } from "./ports.ts";
+import { findRun, type Run, runPaths } from "./run-store.ts";
+
+/** lanes/<lane>.md in the run folder (admission's laneFile, kept here so finalize can import this module). */
+const laneFile = (run: Run, lane: string): string => join(runPaths(run.dir).lanes, `${lane}.md`);
+
+// Spec 1.5 "Lane editing": one header line at a time, validated, instead of `sed` on the run folder; and an
+// Owns list that can grow mid-lane, with the overlap re-checked.
+
+/** The header lines lane_set writes, and their labels in the lane file. */
+export const LANE_FIELDS = {
+  owns: "Owns",
+  fast_check: "Fast check",
+  kind: "Kind",
+  difficulty: "Difficulty",
+  after: "After",
+  allow: "Allow",
+} as const;
+export type LaneField = keyof typeof LANE_FIELDS;
+
+/** `text` with `label`'s header line set to `value`: replaced where it is, else added atop the header block. */
+export function setHeaderLine(text: string, label: string, value: string): string {
+  const line = `${label}: ${value}`;
+  const lines = text.split("\n");
+  const [start, end] = headerBlock(lines);
+  const re = headerLine(label);
+  const at = lines.slice(start, end).findIndex((l) => re.test(l));
+  if (at >= 0) lines[start + at] = line;
+  else lines.splice(start, 0, line);
+  return lines.join("\n");
+}
+
+function readLane(run: Run, lane: string): { file: string; text: string } {
+  assertId("lane", lane);
+  const file = laneFile(run, lane);
+  if (!existsSync(file))
+    throw new CatherdError("E_LANE_INVALID", `no lane file lanes/${lane}.md`, {
+      fix: "write it with write_run_file first",
+    });
+  return { file, text: readFileSync(file, "utf8") };
+}
+
+/**
+ * Paths of `owns` another running lane owns: refused as admission refuses them. Other lanes' Owns lines
+ * that overlap come back as hints: they are not running, so nothing collides yet.
+ */
+function overlapCheck(deps: Deps, run: Run, lane: string, owns: string[]): string[] {
+  for (const d of pendingDispatches(run, deps.now())) {
+    if (d.admit.lane === lane) continue;
+    // a running lane holds what an earlier owns_add granted it, too
+    const held = d.admit.lane ? [...d.admit.owns, ...currentOwns(run, d.admit.lane)] : d.admit.owns;
+    const shared = overlaps(owns, held);
+    if (shared.length)
+      throw new CatherdError(
+        "E_ADMIT_OVERLAP",
+        `${lane} would own ${shared.join(", ")}, which ${d.admit.name} (running) owns`,
+        { fix: `add it once ${d.admit.name} finishes, or give the work to ${d.admit.lane ?? d.admit.name}` },
+      );
+  }
+  const dir = runPaths(run.dir).lanes;
+  const hints: string[] = [];
+  for (const f of existsSync(dir) ? readdirSync(dir) : []) {
+    const other = f.endsWith(".md") ? f.slice(0, -3) : null;
+    if (!other || other === lane) continue;
+    try {
+      const shared = overlaps(owns, parseLaneHeader(readFileSync(join(dir, f), "utf8")).owns);
+      if (shared.length) hints.push(`lanes/${f} also owns ${shared.join(", ")}: do not run the two together`);
+    } catch {
+      // an unreadable lane is preflight's to report
+    }
+  }
+  return hints;
+}
+
+/**
+ * `lane_set(run, lane, field, value)`: one header line, validated as `write_run_file` validates a lane; an
+ * Owns line also re-checks overlap with the running lanes. Returns the line and the header as it now reads.
+ */
+export async function laneSet(
+  deps: Deps,
+  i: { run: string; lane: string; field: LaneField; value: string },
+): Promise<{ lane: string; line: string; header: LaneHeader; hints?: string[] }> {
+  const run = findRun(i.run);
+  const label = LANE_FIELDS[i.field];
+  if (!label)
+    throw new CatherdError("E_INPUT_INVALID", `no lane field "${i.field}"`, {
+      fix: `one of ${Object.keys(LANE_FIELDS).join(", ")}`,
+    });
+  const value = i.value.replace(/\s*\n\s*/g, " ").trim();
+  const { file } = readLane(run, i.lane);
+  return withFileLock(file, () => {
+    const next = setHeaderLine(readLane(run, i.lane).text, label, value);
+    const header = assertLaneValues(next, `lanes/${i.lane}.md`);
+    const hints = i.field === "owns" ? overlapCheck(deps, run, i.lane, header.owns) : [];
+    writeTextAtomic(file, next);
+    return { lane: i.lane, line: `${label}: ${value}`, header, ...(hints.length ? { hints } : {}) };
+  });
+}
+
+/**
+ * `owns_add(run, lane, paths, why)`: grows a lane's Owns mid-lane (a test file the plan's grep missed, a clone
+ * found after the gate ran), refused when a running lane owns one of them. The why is kept in the lane file.
+ * A running dispatch of the lane is held to the new list when it finishes.
+ */
+export async function ownsAdd(
+  deps: Deps,
+  i: { run: string; lane: string; paths: string[]; why: string },
+): Promise<{ lane: string; owns: string[]; added: string[]; hints?: string[] }> {
+  const run = findRun(i.run);
+  if (!i.why.trim())
+    throw new CatherdError("E_INPUT_INVALID", "owns_add needs a why", {
+      fix: "say what made the lane need the paths, in one line",
+    });
+  const paths = i.paths.map(normalizeOwned);
+  const { file } = readLane(run, i.lane);
+  return withFileLock(file, () => {
+    const text = readLane(run, i.lane).text;
+    const owns = parseLaneHeader(text).owns;
+    const added = paths.filter((p) => !owns.includes(p));
+    const merged = [...owns, ...added];
+    const hints = overlapCheck(deps, run, i.lane, added);
+    const note = `\nOwns added ${new Date(deps.now()).toISOString()}: ${added.join(", ")} — ${cell(i.why)}\n`;
+    const next = setHeaderLine(text, "Owns", merged.join(", "));
+    assertLaneValues(next, `lanes/${i.lane}.md`);
+    if (added.length) writeTextAtomic(file, `${next.replace(/\n*$/, "\n")}${note}`);
+    return { lane: i.lane, owns: merged, added, ...(hints.length ? { hints } : {}) };
+  });
+}
+
+/** The lane's Owns as its file reads now: a finishing dispatch is held to what owns_add granted since. */
+export function currentOwns(run: Run, lane: string): string[] {
+  try {
+    return parseLaneHeader(readFileSync(laneFile(run, lane), "utf8")).owns;
+  } catch {
+    return [];
+  }
+}

package/src/services/lane-service.ts

@@ -1,22 +1,33 @@
 import { existsSync, readFileSync } from "node:fs";
-import { relative, sep } from "node:path";
+import { join, relative, sep } from "node:path";
 import { CatherdError } from "../domain/errors.ts";
 import { assertId, ID_PATTERN, parseRung } from "../domain/ids.ts";
-import { assertLaneHeader, type Difficulty, type Kind } from "../domain/lane.ts";
+import { quotaUsage } from "../domain/select.ts";
+import { assertLaneHeader } from "../domain/lane.ts";
 import type { Role } from "../domain/roles.ts";
-import { cell } from "../domain/util.ts";
+import { cell, coveredMs } from "../domain/util.ts";
 import {
   type ClimbReason,
   currentRoute,
   laneOutcome,
   nextRung,
-  type RouteJev,
-  type RouteSource,
+  type OutcomeRow,
+  outcomeRouteRow,
+  type RouteRow,
 } from "../domain/route.ts";
 import { withFileLock } from "../infra/filelock.ts";
 import { commitExists } from "../infra/git.ts";
 import { laneFile } from "./admission.ts";
 import { budgetOf } from "./budget.ts";
+import { pendingDispatches } from "./dispatches.ts";
+import { workspaceBudget } from "./workspace-admission.ts";
+import {
+  findWorkspace,
+  WORKSPACE_LOCK_WAIT_MS,
+  workspaceChildren,
+  workspaceDirectory,
+  workspacePaths,
+} from "./workspace-store.ts";
 import {
   isDocPath,
   isSourcePath,
@@ -24,7 +35,9 @@ import {
   fullCommit,
   milestoneFiles,
   milestoneStart,
+  partialReviewer,
   reviewerPassed,
+  milestoneCommits,
   milestoneVerifier,
 } from "./milestones.ts";
 import type { Deps, Verdict } from "./ports.ts";
@@ -34,31 +47,35 @@ import {
   appendOutcome,
   appendRoute,
   findRun,
+  readAgentRuns,
+  readRecords,
   readRoutes,
   type Run,
   runFile,
   runPaths,
 } from "./run-store.ts";
 import { writeDigest } from "./protocol.ts";
-import { openQuestions } from "./questions.ts";
-import { type Notes, type NotesPatch, refreshState } from "./state.ts";
+import { pauseSpans } from "./pause.ts";
+import { openQuestions, parkedSpans } from "./questions.ts";
+import { runProfile } from "./run-pin.ts";
+import { type Notes, type NotesPatch, patchNotes, refreshState } from "./state.ts";
 
 const withHints = (hints: string[]) => (hints.length ? { hints } : {});
 
+/**
+ * Spec 1.5 plan 24: what `route` returns: little, since every call lands in the coordinator's context. The
+ * decision's source, kind, difficulty, Jev's answer and the provenance go to routes.jsonl.
+ */
 export interface RouteResult {
   lane: string | null;
   role: Role;
   rung: string;
   ladder: string[];
-  source: RouteSource;
-  kind: Kind | null;
-  difficulty: Difficulty | null;
   backend: string;
   /** the native agent to run a `claude:` rung as */
   agent: string | null;
-  /** the Jev question set asked, and what it said, when Jev was asked */
-  questionSet: string | null;
-  jev: RouteJev | null;
+  /** the decision in one line */
+  why: string;
 }
 
 function readLaneFile(run: Run, path: string): { lane: string; text: string } {
@@ -79,15 +96,51 @@ function readLaneFile(run: Run, path: string): { lane: string; text: string } {
   return { lane, text };
 }
 
-/** Spec §5.4 through the routing port; a lane's route is recorded in routes.jsonl. */
+/**
+ * Spec 1.5 plan 24: the run's dispatches per quota, plus each lane routed but not dispatched yet at its current
+ * rung, so a tie between quotas goes to the one the run will have used least.
+ */
+function runUsage(run: Run): Record<string, number> {
+  const records = readRecords(run).records;
+  const dispatched = new Set(records.flatMap((r) => (r.lane ? [r.lane] : [])));
+  const routes = readRoutes(run);
+  const waiting = [...new Set(routes.map((r) => r.lane))]
+    .filter((l) => !dispatched.has(l))
+    .flatMap((l) => currentRoute(routes, l)?.rung ?? []);
+  return quotaUsage([...records.map((r) => r.rung), ...waiting]);
+}
+
+/** Spec §5.4 through the routing port; every decision is recorded in routes.jsonl. */
 export async function route(
   deps: Deps,
   i: { run: string; laneFile?: string; role: Role },
 ): Promise<RouteResult> {
+  const [one] = await routeLanes(deps, { run: i.run, laneFiles: [i.laneFile], role: i.role });
+  return one as RouteResult;
+}
+
+/**
+ * Spec 1.5 plan 24, batch `route`: several lanes of one role in one call (Jev asked about all at once), each
+ * recorded as `route` records one. `laneFiles` holds `undefined` for a role routed without a lane.
+ */
+export async function routeLanes(
+  deps: Deps,
+  i: { run: string; laneFiles: (string | undefined)[]; role: Role },
+): Promise<RouteResult[]> {
   const run = findRun(i.run);
-  const lane = i.laneFile === undefined ? null : readLaneFile(run, i.laneFile);
-  const profile = deps.profiles.forRepo(run.meta.repo);
-  const a = await deps.routing.route({
+  const lanes = i.laneFiles.map((f) => (f === undefined ? null : readLaneFile(run, f)));
+  const dup = lanes.find((l, n) => l && lanes.findIndex((x) => x?.lane === l.lane) !== n);
+  if (dup)
+    throw new CatherdError("E_INPUT_INVALID", `route: lane ${dup.lane} is named twice`, {
+      fix: "name each lane file once",
+    });
+  // spec 1.5: the run's pinned profile, whatever the repo runs on now
+  const profile = runProfile(deps, run);
+  const spentFraction = Math.max(
+    budgetOf(run, profile.budget, deps.now())?.fraction ?? 0,
+    (await workspaceBudget(run, deps.now()))?.fraction ?? 0,
+  );
+  const reqs = lanes.map((lane) => ({
     host: deps.host.host,
     runDir: run.dir,
     repo: run.meta.repo,
@@ -95,13 +148,37 @@ export async function route(
     role: i.role,
     lane: lane?.lane ?? null,
     laneText: lane?.text ?? null,
-    spentFraction: budgetOf(run, profile.budget, deps.now())?.fraction ?? 0,
-  });
+    usage: runUsage(run),
+    spentFraction,
+  }));
+  const answers =
+    reqs.length === 1
+      ? [await deps.routing.route(reqs[0] as (typeof reqs)[number])]
+      : await deps.routing.routeMany(reqs);
+  return answers.map((a, n) => record(deps, run, i.role, lanes[n] ?? null, a));
+}
+
+/** One decision into routes.jsonl (spec 1.5 plan 24: every role's, with its source, ladder and provenance). */
+function record(
+  deps: Deps,
+  run: Run,
+  role: Role,
+  lane: { lane: string } | null,
+  a: Awaited<ReturnType<Deps["routing"]["route"]>>,
+): RouteResult {
+  const at = new Date(deps.now()).toISOString();
+  const detail = {
+    why: a.why,
+    ...(a.jevSaid ? { jevSaid: a.jevSaid } : {}),
+    ...(a.noClear ? { noClear: a.noClear } : {}),
+    ...(a.tie ? { tie: a.tie } : {}),
+    ...(a.provenance ? { provenance: a.provenance } : {}),
+  };
   if (lane)
     appendRoute(run, {
-      at: new Date(deps.now()).toISOString(),
+      at,
       lane: lane.lane,
-      role: i.role,
+      role,
       rung: a.rung,
       ladder: a.ladder,
       source: "route",
@@ -112,18 +189,38 @@ export async function route(
       difficulty: a.difficulty,
       questionSet: a.questionSet,
       jev: a.jev,
+      ...detail,
+    });
+  else
+    appendRoute(run, {
+      at,
+      lane: null,
+      role,
+      name: null,
+      rung: a.rung,
+      ladder: a.ladder,
+      source: "route",
+      decidedBy: a.source,
+      ...detail,
     });
   return {
     lane: lane?.lane ?? null,
-    role: i.role,
-    ...a,
+    role,
+    rung: a.rung,
+    ladder: a.ladder,
     backend: parseRung(a.rung).backend,
-    agent: deps.profiles.agentFor(run.meta.repo, i.role, a.rung),
+    agent: deps.profiles.agentFor(run.meta.repo, role, a.rung),
+    why: a.why,
   };
 }
 
-/** Evidence that the lane's own ownership is the problem: a design question, never a capability one. */
-const OWNERSHIP = /outside (the )?lane('s)? ownership|owned by/i;
+/**
+ * Evidence that the lane's own ownership is the problem: a design question, never a capability one. "owned by"
+ * counts only for a lane (another lane, lane X, Mx.Ly), never for a user or a process: a socket "owned by root"
+ * is the environment's.
+ */
+const OWNERSHIP =
+  /outside (the )?lane('s)? ownership|owned by (?:another |a different |the other )?lane\b|owned by [A-Za-z0-9_-]+\.L\d+\b/i;
 
 const CLIMB_DESIGN_FIX = "send it to the architect (ask/architect delta), not up the ladder";
 
@@ -156,6 +253,15 @@ async function refuseDesign(
     });
 }
 
+/**
+ * A lane's final outcome: its outcomes.jsonl row (spec §5.6) and, beside Jev's answer, its routes.jsonl row
+ * (spec 1.5 plan 24). Called under the routes lock.
+ */
+function writeOutcome(run: Run, routes: RouteRow[], o: OutcomeRow): void {
+  appendOutcome(run, o);
+  appendRoute(run, outcomeRouteRow(routes, o));
+}
+
 /** Spec §4.5: one rung up the lane's ladder, on a fresh thread; the reason goes to routes.jsonl. */
 export async function climb(
   deps: Deps,
@@ -176,6 +282,18 @@ export async function climb(
     });
   // an unrouted lane is refused before Jev is asked about its evidence (no call, no jev.jsonl row)
   if (!currentRoute(readRoutes(run), i.lane)) throw unrouted();
+  // plan 23: a reply that named the environment (ENV: …) would stop a higher rung the same way
+  const last = readRecords(run)
+    .records.filter((r) => r.lane === i.lane)
+    .at(-1);
+  if (last?.environment)
+    throw new CatherdError(
+      "E_CLIMB_ENV",
+      `climb ${i.lane}: ${last.name} was stopped by the environment (${last.environment}), which a higher rung cannot fix`,
+      {
+        fix: `fix the environment (doctor; catherd knowledge env set for the gate environment) and dispatch ${i.lane} again at the same rung, or park the milestone when only the owner can fix it`,
+      },
+    );
   await refuseDesign(deps, run, i);
   const { cur, next } = await withFileLock(runPaths(run.dir).routes, () => {
     const cur = currentRoute(readRoutes(run), i.lane);
@@ -192,8 +310,9 @@ export async function climb(
     });
     // spec §5.6: a climb past the top rung ends the lane open
     if (!next) {
-      const o = laneOutcome(readRoutes(run), i.lane, false, new Date(deps.now()).toISOString());
-      if (o) appendOutcome(run, o);
+      const routes = readRoutes(run);
+      const o = laneOutcome(routes, i.lane, false, new Date(deps.now()).toISOString());
+      if (o) writeOutcome(run, routes, o);
     }
     return { cur, next };
   });
@@ -264,8 +383,27 @@ async function gate(run: Run, m: string, commit: string, skip: LandSkip | undefi
     );
   }
   const start = milestoneStart(run, m);
+  // plan 23: a reviewer that stopped partial read part of the diff; that is not the milestone's review
+  const partial = partialReviewer(run, m, start);
+  if (partial)
+    throw new CatherdError(
+      "E_LAND_GATE",
+      `land ${m}: ${partial.name} replied STATUS: partial, which is not the milestone's review`,
+      {
+        fix: `dispatch a scoped second pass, reviewer-${m}-2, over the files ${partial.name} did not read (its reply names them), then land again`,
+      },
+    );
   // the latest verifier attempt, passed or not: a FAIL after a PASS undoes it
   const verdict = milestoneVerifier(run, m, start);
+  // plan 23: a verdict on the machine is a blocker for the owner, never a fix round
+  if (verdict?.blocked != null)
+    throw new CatherdError(
+      "E_LAND_GATE",
+      `land ${m}: ${verdict.name} is blocked by the environment${verdict.blocked ? `: ${verdict.blocked}` : ""}`,
+      {
+        fix: `surface it to the owner: park(run, "${m}", <the blocker and its probe>); once the environment is fixed, run a fresh verifier on ${m}. A fix round or a climb cannot help`,
+      },
+    );
   const missing = [
     ...(reviewerPassed(run, m, start)
       ? []
@@ -275,15 +413,20 @@ async function gate(run: Run, m: string, commit: string, skip: LandSkip | undefi
     ...(verdict?.passed
       ? []
       : [
-          `a verifier verdict (record_agent_run with role verifier and a name holding ${m}, status ok; a headless verifier's reply opening VERDICT: PASS)${verdict ? `: the latest, ${verdict.name}${verdict.headless ? " (headless)" : ""}, is ${verdict.verdict}` : ""}`,
+          `a verifier verdict (record_agent_run with role verifier named exactly verifier-${m}, status ok; a headless verifier-${m}'s reply opening VERDICT: PASS)${verdict ? `: the latest, ${verdict.name}${verdict.headless ? " (headless)" : ""}, is ${verdict.verdict}` : ""}`,
         ]),
   ];
+  // a headless verifier that wrapped its verdict in markdown (**VERDICT: PASS**) gave no verdict: fail safe, and say why
+  const marked =
+    verdict?.headless === true && !verdict.passed && /VERDICT:\s*PASS\b/.test(verdict.verdict)
+      ? `the reply's first line must be the bare VERDICT: PASS, and ${verdict.name}'s is "${verdict.verdict}", which counts as no verdict (markdown around it, or text before it): dispatch the verifier again; otherwise `
+      : "";
   if (missing.length)
     throw new CatherdError(
       "E_LAND_GATE",
       `land ${m}: missing ${missing.join(" and ")}, since its lanes started`,
       {
-        fix: `run reviewer-${m} (a dispatch, or a Claude subagent recorded with record_agent_run(name: "reviewer-${m}")) and the verifier on ${m}, recording it with record_agent_run(name: "verifier-${m}") (a FAIL with status "failed"), then land again; a docs-only milestone passes skip: "docs-only"`,
+        fix: `${marked}run reviewer-${m} (a dispatch, or a Claude subagent recorded with record_agent_run(name: "reviewer-${m}")) and the verifier on ${m}, recording it with record_agent_run(name: "verifier-${m}") (a FAIL with status "failed"), then land again; a docs-only milestone passes skip: "docs-only"`,
       },
     );
 }
@@ -292,20 +435,72 @@ async function gate(run: Run, m: string, commit: string, skip: LandSkip | undefi
  * Spec §4.7: the full five-column ledger row, with the minutes since the previous landing (or the
  * run's start), and `learned` appended to the repo's knowledge.md.
  */
-export async function land(
-  deps: Deps,
-  i: {
-    run: string;
-    milestone: string;
-    what: string;
-    commit: string;
-    evidence: string;
-    next: string;
-    learned?: string;
-    skip?: LandSkip;
-  },
-): Promise<{ ledger: string; minutes: number; digest: string; hints?: string[] }> {
+type LandInput = {
+  run: string;
+  milestone: string;
+  what: string;
+  commit: string;
+  evidence: string;
+  next: string;
+  learned?: string;
+  skip?: LandSkip;
+};
+
+type LandResult = { ledger: string; minutes: number; digest: string; digestPath: string; hints?: string[] };
+
+export async function land(deps: Deps, i: LandInput): Promise<LandResult> {
   const run = findRun(i.run);
+  const link = run.meta.workspace;
+  if (!link) return landRun(deps, i, run);
+  const workspace = findWorkspace(link.id);
+  const step = workspace.steps.find((s) => s.id === link.step);
+  if (!step || !workspaceChildren(workspace).some((child) => child.dir === run.dir))
+    throw new CatherdError("E_RUN_CORRUPT", "the run is not a member of its workspace execution");
+  // #43 finding 3: only the step's completion milestone waits for the child's dispatches
+  if (i.milestone !== step.milestone) {
+    const landed = await landRun(deps, i, run);
+    if (i.milestone.toLowerCase() !== step.milestone.toLowerCase()) return landed;
+    // #43 finding 7: m1 is not M1; the dependents wait on the step's own milestone
+    const hint = `${i.milestone} is not ${step.milestone}, the milestone workspace step ${step.id} completes on: its dependents still wait`;
+    return { ...landed, hints: [...(landed.hints ?? []), hint] };
+  }
+  // An unreadable newer native verdict must not leave an older PASS standing.
+  readAgentRuns(run, true);
+  // Completion and dispatch admission share a boundary, held only for the check and the ledger row: the git
+  // work runs outside it (#43 finding 5). Landing remains available at a spent budget.
+  return landRun(deps, i, run, (write) =>
+    withFileLock(
+      workspacePaths(workspaceDirectory(workspace.id)).admission,
+      async () => {
+        const pending = await withFileLock(runPaths(run.dir).runs, () => {
+          const { records, corrupt } = readRecords(run);
+          if (corrupt)
+            throw new CatherdError("E_RUN_CORRUPT", "workspace completion has unreadable dispatch records", {
+              fix: "repair the child's dispatch records before landing its milestone",
+            });
+          return pendingDispatches(run, deps.now(), records, true);
+        });
+        if (pending.length)
+          throw new CatherdError("E_LAND_GATE", "workspace completion waits for all admitted dispatches", {
+            fix: "finish and collect the child's dispatches before landing its milestone",
+          });
+        return write();
+      },
+      { timeoutMs: WORKSPACE_LOCK_WAIT_MS },
+    ),
+  );
+}
+
+/**
+ * The checks (commit, gate) first, then the ledger row and the notes, inside `critical` (a workspace
+ * completion's lock), with no git; then state.md, the lane outcomes, knowledge and the digest.
+ */
+async function landRun(
+  deps: Deps,
+  i: LandInput,
+  run: Run,
+  critical: (write: () => Promise<Notes>) => Promise<Notes> = (write) => write(),
+): Promise<LandResult> {
   // the digest is named after the milestone: an id, checked before anything is written
   assertId("milestone", i.milestone);
   // commitExists throws E_IO_UNEXPECTED on a timeout, which reaches the caller as is
@@ -314,20 +509,27 @@ export async function land(
       fix: "commit the milestone first, then pass its hash",
     });
   await gate(run, i.milestone, i.commit, i.skip);
+  // read before the ledger row: the range runs from the previous landing to this commit
+  const commits = await milestoneCommits(run, i.commit);
   const now = new Date(deps.now());
   let row = "";
   let minutes = 0;
+  let pausedMinutes = 0;
+  // spec 1.5 "The ledger": the minutes leave out the time the milestone was parked and any machine or
+  // workspace pause, so a night parked on a question does not count
+  const paused = [...parkedSpans(run, i.milestone), ...pauseSpans(run)];
   const landRow = (notes: Notes): NotesPatch => {
-    minutes = Math.max(
-      0,
-      Math.round((now.getTime() - Date.parse(notes.lastLandedAt ?? run.meta.createdAt)) / 60_000),
-    );
+    const from = Date.parse(notes.lastLandedAt ?? run.meta.createdAt);
+    const left = coveredMs(from, now.getTime(), paused);
+    pausedMinutes = Math.round(left / 60_000);
+    minutes = Math.max(0, Math.round((now.getTime() - from - left) / 60_000));
     row = [i.milestone, i.what, i.commit, String(minutes), i.evidence].map(cell).join(" | ");
     appendLedger(run, row);
     return { lastCheck: cell(i.evidence), next: i.next, lastLandedAt: now.toISOString() };
   };
-  // on a failed refresh the notes still reach state.json, so the next landing counts its minutes from this one
-  const { hints } = await refreshState(run, landRow);
+  // the notes reach state.json first, with no git: the next landing counts its minutes from this one
+  await critical(() => patchNotes(run, landRow));
+  const { hints } = await refreshState(run);
   // spec §5.6: every routed lane of the milestone lands with it
   // under the routes lock, so a racing climb cannot slip between the read and the rows
   let routed: string[] = [];
@@ -339,7 +541,7 @@ export async function land(
       if (lane.startsWith(`${i.milestone}.`)) {
         landed++;
         const o = laneOutcome(routes, lane, true, now.toISOString());
-        if (o) appendOutcome(run, o);
+        if (o) writeOutcome(run, routes, o);
       }
   });
   // a milestone name no routed lane starts with is most likely a typo: say so rather than record nothing
@@ -347,7 +549,7 @@ export async function land(
     hints.push(
       `land: no routed lane is in milestone "${i.milestone}" (routed: ${routed.slice(0, 5).join(", ")}${routed.length > 5 ? ", …" : ""}); check its name: no lane outcome was recorded`,
     );
-  if (i.learned) appendKnowledge(run.meta.repo, now, `${run.meta.title} ${i.milestone}`, i.learned);
+  if (i.learned) await appendKnowledge(run.meta.repo, now, `${run.meta.title} ${i.milestone}`, i.learned);
   // spec 1.1 §10: the milestone's digest, which the milestone push links
   const digest = writeDigest(run, {
     milestone: i.milestone,
@@ -356,8 +558,11 @@ export async function land(
     evidence: i.evidence,
     minutes,
     at: now.toISOString(),
+    commits,
+    pausedMinutes,
   });
-  return { ledger: row, minutes, digest, ...withHints(hints) };
+  // spec 1.5: the digest's full path, for the milestone push to link
+  return { ledger: row, minutes, digest, digestPath: join(run.dir, digest), ...withHints(hints) };
 }
 
 /** Jev's `finding` or `same-defect` answer, through the routing port. */