catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

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,9 +35,12 @@ import {
   fullCommit,
   milestoneFiles,
   milestoneStart,
+  partialReviewer,
   reviewerPassed,
+  milestoneCommits,
   milestoneVerifier,
 } from "./milestones.ts";
+import { machineGate } from "./milestone-check.ts";
 import type { Deps, Verdict } from "./ports.ts";
 import {
   appendKnowledge,
@@ -34,31 +48,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 +97,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 +149,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 +190,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 +254,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 +283,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 +311,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 };
   });
@@ -220,7 +340,7 @@ export type LandSkip = (typeof LAND_SKIPS)[number];
  * Spec 1.1 §6: a milestone lands only with a reviewer record and a verifier verdict since its lanes
  * started, or with a `skip` the commit range bears out. Throws E_LAND_GATE naming what is missing.
  */
-async function gate(run: Run, m: string, commit: string, skip: LandSkip | undefined): Promise<void> {
+async function gate(run: Run, m: string, commit: string, skip: LandSkip | undefined): Promise<string[]> {
   // spec 1.1 §8: a parked milestone waits on the owner, whatever else it has
   const question = openQuestions(run).find((q) => q.milestone === m);
   if (question)
@@ -255,7 +375,7 @@ async function gate(run: Run, m: string, commit: string, skip: LandSkip | undefi
     }
     const against =
       skip === "docs-only" ? files.filter((f) => !isDocPath(f)) : files.filter((f) => isSourcePath(f));
-    if (against.length === 0) return;
+    if (against.length === 0) return [];
     const shown = `${against.slice(0, 5).join(", ")}${against.length > 5 ? `, and ${against.length - 5} more` : ""}`;
     throw new CatherdError(
       "E_LAND_GATE",
@@ -264,8 +384,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,37 +414,123 @@ 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"`,
       },
     );
+  // plan 30b: the verdict must be about the commit being landed, and catherd's own check must have run on it
+  const landed = await fullCommit(run, commit);
+  const checked = verdict?.head ?? null;
+  if (verdict && checked === null)
+    throw new CatherdError(
+      "E_LAND_GATE",
+      `land ${m}: ${verdict.name}'s PASS names no HEAD, so it cannot be told to cover ${landed.slice(0, 12)}`,
+      {
+        fix: `a headless verifier's reply ends with HEAD: <sha>; run a fresh verifier-${m} on the committed milestone (${landed.slice(0, 7)})`,
+      },
+    );
+  if (verdict && checked !== null && !landed.startsWith(checked))
+    throw new CatherdError(
+      "E_LAND_GATE",
+      `land ${m}: ${verdict.name} checked ${checked.slice(0, 12)}, and the commit being landed is ${landed.slice(0, 12)}: a PASS from before a later commit does not count`,
+      {
+        fix: `run a fresh ${verdict.name} on ${landed.slice(0, 7)}: what passed is carried over by gate_check`,
+      },
+    );
+  const machine = await machineGate(run, m, landed);
+  if (machine.missing.length)
+    throw new CatherdError(
+      "E_LAND_GATE",
+      `land ${m}: the machine gate on ${landed.slice(0, 12)}: ${machine.missing.join("; ")}`,
+      {
+        fix: `run the full check with gate_run(run, "${m}", <command>) on ${landed.slice(0, 7)}; fix what fails, commit, and verify again`,
+      },
+    );
+  return machine.audit;
 }
 
 /**
  * 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
@@ -313,21 +538,29 @@ export async function land(
     throw new CatherdError("E_RUN_COMMIT", `no commit ${i.commit} in ${run.meta.repo}`, {
       fix: "commit the milestone first, then pass its hash",
     });
-  await gate(run, i.milestone, i.commit, i.skip);
+  const audit = 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);
+  hints.push(...audit);
   // 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 +572,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 +580,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 +589,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. */