catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/domain/lane.ts

@@ -1,4 +1,5 @@
 import { CatherdError } from "./errors.ts";
+import { TASK_REF } from "./plan-doc.ts";
 
 export const KINDS = ["repo_code", "terminal", "ui", "prose", "research"] as const;
 export type Kind = (typeof KINDS)[number];
@@ -11,18 +12,49 @@ export interface LaneHeader {
   fastCheck: string | null;
   kind: Kind | null;
   difficulty: Difficulty | null;
+  /** `After: M1.L1, M1.L2`: lanes that must finish first (protocol.next and admission keep the order) */
+  after: string[];
+  /** `Allow: path[:line], …` under the check: hits of the lane's absence check that are allowed exceptions */
+  allow: string[];
+  /** `Tasks: 3, plan.md#4`: the plan tasks the lane implements (catherd inlines them into its worker's brief) */
+  tasks: string[];
 }
 
+/** An After: entry: a lane id (Mx.Ly, the shape lanes/<id>.md takes) or a whole milestone (Mx). */
+const LANE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*(\.[A-Za-z0-9][A-Za-z0-9._-]*)?$/;
+
+/** An Allow: entry: a repo-relative path, optionally `:<line>`. */
+const ALLOW_ENTRY = /^([^\s:]+)(?::(\d+))?$/;
+
 const unquote = (s: string) =>
   s
     .trim()
     .replace(/^`+|`+$/g, "")
     .trim();
 
-/** The value of the first `Label:` line, allowing `**Label:**` and `_Label_:` emphasis. */
+/**
+ * The lane's header block, as [start, end) line indexes: the lines under the `# ` title (blank lines right
+ * after it skipped) up to the first blank line or heading. Header lines are read only here, so a body's prose
+ * (`After: the handler returns 404`) is never a header value.
+ */
+export function headerBlock(lines: string[]): [number, number] {
+  const title = lines.findIndex((l) => /^#\s+/.test(l));
+  let start = title + 1;
+  while (start < lines.length && (lines[start] ?? "").trim() === "") start++;
+  let end = start;
+  while (end < lines.length && (lines[end] ?? "").trim() !== "" && !(lines[end] ?? "").startsWith("#")) end++;
+  return [start, end];
+}
+
+/** A header line `Label:`, allowing `**Label:**` and `_Label_:` emphasis; group 1 is its value. */
+export const headerLine = (label: string) => new RegExp(`^\\s*[*_]*${label}[*_]*\\s*:[*_]*\\s*(.*)$`, "i");
+
+/** The value of the first `Label:` line of the header block. */
 function field(text: string, label: string): string | null {
-  const re = new RegExp(`^\\s*[*_]*${label}[*_]*\\s*:[*_]*\\s*(.*)$`, "i");
-  for (const line of text.split("\n")) {
+  const re = headerLine(label);
+  const lines = text.split("\n");
+  const [start, end] = headerBlock(lines);
+  for (const line of lines.slice(start, end)) {
     const m = re.exec(line);
     if (m) return (m[1] ?? "").trim();
   }
@@ -51,15 +83,97 @@ export function parseLaneHeader(text: string): LaneHeader {
   const title = /^#\s+(.+)$/m.exec(text)?.[1]?.trim() ?? null;
   const owns = (field(text, "owns") ?? "").split(",").map(unquote).filter(Boolean).map(normalizeOwned);
   const check = field(text, "fast check");
+  const list = (label: string) => (field(text, label) ?? "").split(",").map(unquote).filter(Boolean);
   return {
     title,
     owns,
     fastCheck: check ? unquote(check) || null : null,
     kind: oneOf(field(text, "kind"), KINDS),
     difficulty: oneOf(field(text, "difficulty"), DIFFICULTIES),
+    after: list("after"),
+    allow: list("allow"),
+    tasks: list("tasks"),
   };
 }
 
+/** The milestones, other than `m`, that `m`'s lanes wait on (After: entries, lane or milestone), in numeric order. */
+export function milestoneAfter(lanes: { id: string; after: string[] }[], m: string): string[] {
+  const out = new Set<string>();
+  for (const l of lanes)
+    if (l.id.split(".")[0] === m)
+      for (const a of l.after) {
+        const dep = a.split(".")[0] as string;
+        if (dep !== m) out.add(dep);
+      }
+  return [...out].sort((a, b) => a.localeCompare(b, "en", { numeric: true }));
+}
+
+/** What is wrong with the After: and Allow: entries, one line each; none when they are well formed. */
+function orderProblems(h: LaneHeader): string[] {
+  const out: string[] = [];
+  for (const a of h.after)
+    if (!LANE_ID.test(a)) out.push(`After "${a}" is not a lane or milestone id like M1.L1 or M1`);
+  for (const t of h.tasks)
+    if (!TASK_REF.test(t)) out.push(`Tasks "${t}" is not a task number like 3 or plan.md#3`);
+  for (const a of h.allow) {
+    const m = ALLOW_ENTRY.exec(a);
+    try {
+      if (!m) throw new Error();
+      normalizeOwned(m[1] as string);
+    } catch {
+      out.push(`Allow "${a}" is not a repo path, or path:line`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Spec 1.5 "Lane editing": `write_run_file` refuses a lane whose header values are present but wrong (a Kind
+ * or Difficulty the catalog does not know, an Owns path that leaves the repo, a malformed After: or Allow:),
+ * so a typo is caught when the lane is written, not at preflight. A missing line is left to routing.
+ */
+export function assertLaneValues(text: string, where: string): LaneHeader {
+  let h: LaneHeader;
+  try {
+    h = parseLaneHeader(text);
+  } catch (e) {
+    throw new CatherdError("E_LANE_INVALID", `${where}: ${(e as Error).message}`, {
+      fix: "write Owns: paths like src/foo/ or src/bar.ts",
+    });
+  }
+  const problems: string[] = [];
+  const kind = field(text, "kind");
+  const difficulty = field(text, "difficulty");
+  if (kind !== null && h.kind === null) problems.push(`Kind "${unquote(kind)}" is not one the catalog knows`);
+  if (difficulty !== null && h.difficulty === null)
+    problems.push(`Difficulty "${unquote(difficulty)}" is not one the catalog knows`);
+  problems.push(...orderProblems(h));
+  if (problems.length)
+    throw new CatherdError("E_LANE_INVALID", `${where}: ${problems.join("; ")}`, {
+      fix: `${LANE_HEADER_FIX}; After: M1.L1, M1.L2; Allow: path or path:line`,
+    });
+  return h;
+}
+
+/**
+ * Whether every line a failing check printed is a `path:line` hit its lane allows: an absence check (a grep
+ * that must find nothing) whose only hits are the lane's declared exceptions has passed.
+ */
+export function onlyAllowedHits(lines: string[], allow: string[]): boolean {
+  const hits = lines.map((l) => /^([^\s:]+):(\d+)(?::|$)/.exec(l.trim()));
+  if (allow.length === 0 || hits.length === 0 || hits.some((m) => !m)) return false;
+  return hits.every((m) =>
+    allow.some((entry) => {
+      const [, path, line] = ALLOW_ENTRY.exec(entry) ?? [];
+      if (!path) return false;
+      const file = (m as RegExpExecArray)[1] as string;
+      const at = (m as RegExpExecArray)[2];
+      const inPath = file === path || (path.endsWith("/") && file.startsWith(path));
+      return inPath && (line === undefined || line === at);
+    }),
+  );
+}
+
 /** The fix every lane-header refusal carries: the values the catalog knows. */
 export const LANE_HEADER_FIX = `write the lane's header lines as Kind: ${KINDS.join("|")} and Difficulty: ${DIFFICULTIES.join("|")}`;
 
@@ -78,6 +192,7 @@ export function assertLaneHeader(text: string, where: string): LaneHeader {
   };
   check("Kind", field(text, "kind"), h.kind !== null);
   check("Difficulty", field(text, "difficulty"), h.difficulty !== null);
+  problems.push(...orderProblems(h));
   if (problems.length)
     throw new CatherdError("E_LANE_INVALID", `${where}: ${problems.join("; ")}`, { fix: LANE_HEADER_FIX });
   return h;

package/src/domain/milestone-memory.ts

@@ -0,0 +1,53 @@
+/**
+ * Plan 35 D6: how many milestones of a base run may work side by side. A new one starts when none is working,
+ * else when the memory the machine has free, less a reserve and less what the ramping milestones are still to take,
+ * stays above a floor. The three megabyte numbers are the run profile's `limits.memory`.
+ */
+export const MEMORY_LIMITS = {
+  reserveMb: 2048,
+  perMilestoneMb: 3072,
+  floorMb: 3072,
+  /** a milestone counts at `perMilestoneMb` for this long after its tree is ready: its lanes have not reached their memory yet */
+  rampMs: 300_000,
+  recheckMs: 120_000,
+} as const;
+
+export type MemoryLimits = {
+  reserveMb: number;
+  perMilestoneMb: number;
+  floorMb: number;
+  rampMs: number;
+  recheckMs: number;
+};
+
+/** The profile's own memory limits over the defaults. */
+export function memoryLimitsOf(p: {
+  limits?: { memory?: Partial<Pick<MemoryLimits, "reserveMb" | "perMilestoneMb" | "floorMb">> };
+}): MemoryLimits {
+  return { ...MEMORY_LIMITS, ...p.limits?.memory };
+}
+
+/** Milestones working (a tree, not landed, merged or parked) and those of them still ramping up. */
+export function memoryLoad(
+  ms: { tree: string | null; status: string; treeAt: string | null }[],
+  nowMs: number,
+  l: MemoryLimits = MEMORY_LIMITS,
+): { working: number; ramping: number } {
+  const working = ms.filter((m) => m.tree !== null && !["landed", "merged", "parked"].includes(m.status));
+  return {
+    working: working.length,
+    ramping: working.filter((m) => m.treeAt !== null && Date.parse(m.treeAt) > nowMs - l.rampMs).length,
+  };
+}
+
+/** The memory a deferral waits for: the reserve, what the ramping milestones will take, and the floor. */
+export const neededMb = (ramping: number, l: MemoryLimits = MEMORY_LIMITS): number =>
+  l.reserveMb + ramping * l.perMilestoneMb + l.floorMb;
+
+/** Whether one more milestone may start: always when none is working, so a run always moves. */
+export function mayStartMilestone(
+  i: { availableMb: number; working: number; ramping: number },
+  l: MemoryLimits = MEMORY_LIMITS,
+): boolean {
+  return i.working === 0 || i.availableMb - l.reserveMb - i.ramping * l.perMilestoneMb >= l.floorMb;
+}

package/src/domain/notice.ts

@@ -6,9 +6,12 @@
 /** Spec §3.6: `later` waits for the receiver's turn to end, `next` drains at its next tool round. Never `now`. */
 export type NoticePriority = "later" | "next";
 
-/** One role's news: it finished (`record`), or an event while it runs (`stall`). */
+/**
+ * One role's news: it finished (`record`), or an event while it runs (`stall`); of a 2.0 run, one of its
+ * reports (`report`: `name` is the unit, `status` the report's kind, `reply` its text).
+ */
 export interface Notice {
-  kind: "finished" | "stalled";
+  kind: "finished" | "stalled" | "report";
   eventId: string;
   runId: string;
   runTitle: string;
@@ -17,6 +20,8 @@ export interface Notice {
   role: string;
   /** the lane it worked, when it had one: the multi-role preview names it */
   lane: string | null;
+  /** the role's thread, so a fix round resumes it without reading runs.jsonl; null before the CLI named one */
+  thread: string | null;
   rung: string;
   /** the record's status, or for a limit what failover did ("limit on X; failed over to Y"), or the event */
   status: string;
@@ -34,15 +39,20 @@ export const REPLY_CAP = 2_000;
 
 const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
 
+/** `thread: <id>`, or `thread: none` before the CLI named one: every message's first line carries it. */
+const threadWord = (n: Notice): string => `thread: ${n.thread ?? "none"}`;
+
 /** The first line of one role's block: it must stand alone, since the Desktop preview shows only it. */
 export function noticeHeader(n: Notice): string {
+  if (n.kind === "report") return `catherd · ${n.runTitle} · ${n.status} · ${n.name}`;
   const head = `catherd · ${n.runTitle} · ${n.name} ${n.role} · ${n.rung} · ${n.status}`;
-  if (n.kind === "stalled") return `${head} · running ${n.secs}s`;
+  if (n.kind === "stalled") return `${head} · running ${n.secs}s · ${threadWord(n)}`;
   return [
     head,
     n.replyStatus ? `STATUS: ${n.replyStatus}` : "no STATUS",
     `${n.secs}s`,
     plural(n.changedOwned, "owned file changed", "owned files changed"),
+    threadWord(n),
   ].join(" · ");
 }
 
@@ -62,6 +72,15 @@ export function capNoticeReply(reply: string, cap = REPLY_CAP): string {
 const neutral = (s: string) => s.replace(/(cross)-(session)-(message)/gi, "$1 $2 $3");
 
 function block(n: Notice): string {
+  if (n.kind === "report")
+    return [
+      noticeHeader(n),
+      ...(n.reply ? [n.reply] : []),
+      n.status === "parked"
+        ? `Answer: answer(run: "${n.runId}", unit: "${n.name}", answer: "<your answer>")`
+        : `Status: status(run: "${n.runId}")`,
+      `Event: ${n.eventId}`,
+    ].join("\n");
   const call = `run: "${n.runId}", name: "${n.name}"`;
   if (n.kind === "stalled") return `${noticeHeader(n)}\nPeek: peek(${call})\nEvent: ${n.eventId}`;
   const reply = capNoticeReply(n.reply);
@@ -74,11 +93,16 @@ function block(n: Notice): string {
 function previewOf(ns: Notice[]): string {
   const titles = [...new Set(ns.map((n) => n.runTitle))];
   const where = titles.length === 1 ? titles[0] : plural(titles.length, "run", "runs");
-  const what = ns.every((n) => n.kind === "finished")
-    ? `${ns.length} roles finished`
-    : `${plural(ns.length, "role", "roles")} to look at`;
-  const each = ns.map(
-    (n) => `${n.lane ?? n.name} ${n.kind === "stalled" ? "stalled" : n.status.split(";")[0]}`,
+  const reports = ns.every((n) => n.kind === "report");
+  const what = reports
+    ? plural(ns.length, "report", "reports")
+    : ns.every((n) => n.kind === "finished")
+      ? `${ns.length} roles finished`
+      : `${plural(ns.length, "role", "roles")} to look at`;
+  const each = ns.map((n) =>
+    n.kind === "report"
+      ? `${n.name} ${n.status}`
+      : `${n.lane ?? n.name} ${n.kind === "stalled" ? "stalled" : n.status.split(";")[0]} (${threadWord(n)})`,
   );
   return `catherd · ${where} · ${what}: ${each.join(", ")}`;
 }

package/src/domain/notify.ts

@@ -0,0 +1,32 @@
+import type { NotifyMoment } from "./profile.ts";
+
+export interface NotifyMessage {
+  title: string;
+  message: string;
+  tags: string[];
+}
+
+/**
+ * The phone message of a moment (spec 2.0): the run, the unit and the command that answers it, nothing else.
+ * Never the question's text, never code or secrets: the owner opens catherd to read it.
+ */
+export function notifyMessage(i: {
+  runId: string;
+  runTitle: string;
+  unit: string;
+  moment: NotifyMoment;
+}): NotifyMessage {
+  const title = `catherd · ${i.runTitle}`;
+  switch (i.moment) {
+    case "blocked":
+      return {
+        title,
+        message: `${i.unit} needs your answer. Answer: catherd answer ${i.runId} ${i.unit} "<your answer>"`,
+        tags: ["question"],
+      };
+    case "milestone":
+      return { title, message: `${i.unit} landed.`, tags: ["white_check_mark"] };
+    case "finish":
+      return { title, message: `The run finished: catherd status ${i.runId}`, tags: ["checkered_flag"] };
+  }
+}

package/src/domain/plan-doc.ts

@@ -0,0 +1,198 @@
+/** Plan files as a preamble and tasks (plan 32): what a lane's `Tasks:` line points at, and what an approval reads. */
+
+export interface PlanTask {
+  doc: string;
+  id: string;
+  title: string;
+  text: string;
+  signature: boolean;
+  test: boolean;
+}
+export interface PlanDoc {
+  name: string;
+  preamble: string;
+  tasks: PlanTask[];
+  /** the whole file, for the section checks (a section may follow the tasks) */
+  text: string;
+}
+
+export const TASK_HEADING = /^#{2,4}[ \t]+Task[ \t]+(\d+[a-z]?)\b[ \t]*[:.—–-]?[ \t]*(.*)$/gim;
+export const TASK_REF = /^(?:([^\s#,]+)#)?(\d+[a-z]?)$/;
+
+const SIGNATURE = [
+  /^[ \t]*(?:[-*][ \t]*)?\**(?:Interfaces|Produces|Signatures?)\**[ \t]*:/im,
+  /^[ \t]*```/m,
+  /`[^`\n]*\w\([^`\n]*\)[^`\n]*`/,
+];
+const TEST = [
+  /^[ \t]*(?:[-*][ \t]*)?\**Tests?\**[ \t]*:/im,
+  /[\w./-]*(?:\.test\.|_test\.|\.spec\.|\btest_)[\w.]*/,
+  /\b(?:it|test|describe)\(\s*["'`]|\bfunc Test\w+|\bdef test_\w+|#\[test\]/,
+  /^[ \t]*(?:[-*][ \t]*)?\**Expected\**[ \t]*:/im,
+];
+
+export function parsePlanDoc(name: string, text: string): PlanDoc {
+  const heads = [...text.matchAll(TASK_HEADING)];
+  const tasks: PlanTask[] = heads.map((m, i) => {
+    const next = heads[i + 1]?.index ?? text.length;
+    const body = text.slice(m.index, next);
+    const nl = body.indexOf("\n");
+    // a task ends at the next task heading, or at the next `## ` heading after its own line
+    const rest = nl < 0 ? -1 : body.slice(nl).search(/^##[ \t]+(?!#)/m);
+    const taskText = rest < 0 ? body : body.slice(0, nl + rest);
+    return {
+      doc: name,
+      id: m[1] as string,
+      title: (m[2] ?? "").trim(),
+      text: taskText,
+      signature: SIGNATURE.some((r) => r.test(taskText)),
+      test: TEST.some((r) => r.test(taskText)),
+    };
+  });
+  const milestone = /^##[ \t]+M\d+\b/m.exec(text)?.index ?? text.length;
+  return { name, preamble: text.slice(0, Math.min(milestone, heads[0]?.index ?? text.length)), tasks, text };
+}
+
+const and = (names: string[]) =>
+  names.length === 2 ? names.join(" and ") : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+
+/** The task a lane's `Tasks:` ref names, or why it names none. */
+export function resolveTask(docs: PlanDoc[], ref: string): PlanTask | string {
+  const m = TASK_REF.exec(ref);
+  if (!m) return `${ref} is not a task number like 3 or plan.md#3`;
+  const file = m[1];
+  const id = m[2] as string;
+  if (file !== undefined) {
+    const doc = docs.find((d) => d.name === file);
+    if (!doc) return `no plan file ${file}`;
+    return pick(doc, id) ?? `no task ${id} in ${file}`;
+  }
+  const owners = docs.filter((d) => d.tasks.some((t) => t.id === id));
+  if (owners.length === 0) return `no task ${id} in ${docs.map((d) => d.name).join(", ")}`;
+  if (owners.length > 1) {
+    const names = owners.map((d) => d.name);
+    return `task ${id} is in ${and(names)}: write ${names[0]}#${id}`;
+  }
+  return pick(owners[0] as PlanDoc, id) as PlanTask | string;
+}
+
+/** The one task `id` names in `doc`, or why it names none: a file that holds a number twice cannot say which. */
+function pick(doc: PlanDoc, id: string): PlanTask | string | undefined {
+  const held = doc.tasks.filter((t) => t.id === id);
+  return held.length > 1 ? `${doc.name} holds Task ${id} twice: renumber one of them` : held[0];
+}
+
+/** What is wrong between a milestone's lanes and the plan: a lane with no task, a bad ref, a task with nothing to build or test. */
+export function coverageProblems(
+  docs: PlanDoc[],
+  lanes: { id: string; tasks: string[] }[],
+): { lane: string; note: string }[] {
+  const out: { lane: string; note: string }[] = [];
+  const named = new Set<PlanTask>();
+  for (const l of lanes) {
+    if (l.tasks.length === 0) {
+      out.push({
+        lane: l.id,
+        note: `lanes/${l.id}.md has no Tasks: line: name the plan tasks it implements`,
+      });
+      continue;
+    }
+    for (const ref of l.tasks) {
+      const r = resolveTask(docs, ref);
+      if (typeof r === "string") out.push({ lane: l.id, note: `lanes/${l.id}.md: Tasks: ${ref} — ${r}` });
+      else named.add(r);
+    }
+  }
+  // only a task a lane builds needs something to build or test: the rest of the plan is the owner's
+  for (const t of named)
+    if (!t.signature && !t.test)
+      out.push({
+        lane: "",
+        note: `${t.doc} Task ${t.id} has neither a signature nor a test: add its signatures (a code block or an Interfaces: line) or a Test: line`,
+      });
+  return out;
+}
+
+export const DEPTH_SECTIONS = ["What already exists", "Contracts", "Decisions"] as const;
+
+/** The text under a `## <name>` heading (case-insensitive prefix), up to the next `## ` heading; null when absent. */
+function section(text: string, name: string): string | null {
+  const lines = text.split("\n");
+  const at = lines.findIndex((l) => new RegExp(`^##[ \\t]+${name}`, "i").test(l));
+  if (at < 0) return null;
+  const end = lines.findIndex((l, i) => i > at && /^##[ \t]+(?!#)/.test(l));
+  return lines.slice(at + 1, end < 0 ? undefined : end).join("\n");
+}
+
+const DECISION = /^[ \t]*(?:[-*][ \t]*)?\**(D\d+)\b/;
+
+/** What a plan the architect wrote lacks, to the depth the owner reviews: one line per gap. */
+export function depthProblems(doc: PlanDoc): string[] {
+  const out: string[] = [];
+  const full = doc.text;
+  for (const s of DEPTH_SECTIONS) if (section(full, s) === null) out.push(`plan.md has no "## ${s}" section`);
+  if (doc.tasks.length === 0) out.push('plan.md has no "### Task <n>:" heading');
+  for (const t of doc.tasks)
+    if (!t.test) out.push(`plan.md Task ${t.id} has no test: add a Test: line naming its test file and case`);
+  for (const line of (section(full, "Decisions") ?? "").split("\n")) {
+    const id = DECISION.exec(line)?.[1];
+    if (id && !/rejected/i.test(line))
+      out.push(
+        `plan.md ${id} names no rejected alternative: write ${id} — <choice> — rejected: <alternative> — <why>`,
+      );
+  }
+  const exists = section(full, "What already exists");
+  if (exists !== null && !/`[^`\n]*(?:\/|\.\w+)[^`\n]*`/.test(exists))
+    out.push("plan.md's What already exists lists no path");
+  return out;
+}
+
+export const APPROVE_WORDS = ["approve", "approved", "yes", "ok", "lgtm"] as const;
+
+/** A bare approving word, case and a trailing `.`/`!` ignored; "ok but rename X" is a change request. */
+export function isApproval(answer: string): boolean {
+  const w = answer
+    .trim()
+    .toLowerCase()
+    .replace(/[.!]+$/, "");
+  return (APPROVE_WORDS as readonly string[]).includes(w);
+}
+
+export const approvalQuestion = (runId: string) =>
+  `The architect's plan is ready for your review: catherd run-file read ${runId} plan.md. Answer approve, or say what to change.`;
+
+export const reapprovalQuestion = (runId: string, ids: string[]) =>
+  `The architect changed approved decisions ${ids.join(", ")} of plan.md: catherd run-file read ${runId} plan.md. Answer approve, or say what to change.`;
+
+/** Each `D<n>` line of the Decisions section, keyed by its id, whitespace collapsed. */
+export function decisionLines(text: string): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const line of (section(text, "Decisions") ?? "").split("\n")) {
+    const id = DECISION.exec(line)?.[1];
+    if (id) out.set(id, line.trim().replace(/\s+/g, " "));
+  }
+  return out;
+}
+
+/** The `D<n>` ids added, removed or edited between two plan texts, in number order. */
+export function changedDecisions(approved: string, now: string): string[] {
+  const a = decisionLines(approved);
+  const b = decisionLines(now);
+  return [...new Set([...a.keys(), ...b.keys()])]
+    .filter((id) => a.get(id) !== b.get(id))
+    .sort((x, y) => Number(x.slice(1)) - Number(y.slice(1)));
+}
+
+/** The copies' file names: basenames, a repeat numbered `-2` before its extension. */
+export function planInputNames(paths: string[]): string[] {
+  const used = new Set<string>();
+  return paths.map((p) => {
+    const base = p.split("/").at(-1) as string;
+    const dot = base.lastIndexOf(".");
+    const [stem, ext] = dot > 0 ? [base.slice(0, dot), base.slice(dot)] : [base, ""];
+    let name = base;
+    for (let n = 2; used.has(name); n++) name = `${stem}-${n}${ext}`;
+    used.add(name);
+    return name;
+  });
+}

package/src/domain/plan-lint.ts

@@ -0,0 +1,141 @@
+import { type LaneHeader, parseLaneHeader } from "./lane.ts";
+
+export interface PlanLint {
+  /** advice only: preflight reports it and goes on */
+  warnings: string[];
+  /** an `After:` that can never finish: the lane (or the cycle's first lane) never starts */
+  stuck: { lane: string; note: string }[];
+}
+
+const milestoneOf = (id: string): string => id.split(".")[0] as string;
+const isFolder = (p: string): boolean => p.endsWith("/");
+
+/**
+ * Lint of the lanes in scope. `known` is every lane id of the run (a bare milestone `Mx` is known when one of its lanes is), the landed milestones' too, so an `After:` on a
+ * lane that already landed is no error. `finished` is the milestones that landed (merged, in a base run): an `After:`
+ * on a lane of any other milestone can never finish, as that milestone does not start before this one is done. Never throws: a lane whose header cannot be read is left out.
+ */
+export function lintLanes(
+  lanes: { id: string; text: string }[],
+  known: string[],
+  finished: string[] = [],
+): PlanLint {
+  const warnings: string[] = [];
+  const stuck: PlanLint["stuck"] = [];
+  const headers = new Map<string, LaneHeader>();
+  for (const l of lanes) {
+    try {
+      headers.set(l.id, parseLaneHeader(l.text));
+    } catch {
+      // a header that cannot be read is preflight's refusal to make, not lint's
+    }
+  }
+  const inScope = lanes.filter((l) => headers.has(l.id));
+  const milestones = new Set(known.map(milestoneOf));
+
+  for (const { id } of inScope) {
+    const h = headers.get(id) as LaneHeader;
+    const folders = h.owns.filter(isFolder);
+    if (folders.length)
+      warnings.push(
+        `${id}: Owns names whole folders (${folders.join(", ")}): name the files, unless the lane creates the folder`,
+      );
+    for (const a of h.after) {
+      if (a === id) stuck.push({ lane: id, note: `${id}: After: names the lane itself` });
+      else if (!a.includes(".") && a === milestoneOf(id))
+        stuck.push({ lane: id, note: `${id}: After: ${a} is its own milestone: this lane never starts` });
+      else if (a.includes(".") ? !known.includes(a) : !milestones.has(a))
+        stuck.push({ lane: id, note: `${id}: After: ${a} has no lane file` });
+      else if (milestoneOf(a) !== milestoneOf(id) && !finished.includes(milestoneOf(a)))
+        stuck.push({
+          lane: id,
+          note: `${id}: After: ${a} is in milestone ${milestoneOf(a)}, which has not finished: this lane never starts`,
+        });
+      else {
+        const other = headers.get(a);
+        if (
+          other &&
+          h.kind !== "research" &&
+          other.kind !== "research" &&
+          h.owns.length &&
+          other.owns.length &&
+          !h.owns.some(isFolder) &&
+          !other.owns.some(isFolder) &&
+          !h.owns.some((p) => other.owns.includes(p))
+        )
+          warnings.push(
+            `${id}: After: ${a} shares no file with it: drop it unless ${id} needs ${a}'s output`,
+          );
+      }
+    }
+  }
+
+  const edges = (id: string): string[] =>
+    (headers.get(id)?.after ?? []).filter((a) => a !== id && headers.has(a));
+
+  const state = new Map<string, "visiting" | "done">();
+  const path: string[] = [];
+  const visit = (id: string): void => {
+    state.set(id, "visiting");
+    path.push(id);
+    for (const a of edges(id)) {
+      if (state.get(a) === "visiting") {
+        const loop = [...path.slice(path.indexOf(a)), a];
+        stuck.push({ lane: a, note: `After: cycle ${loop.join(" → ")}: these lanes never start` });
+      } else if (!state.has(a)) visit(a);
+    }
+    path.pop();
+    state.set(id, "done");
+  };
+  for (const { id } of inScope) if (!state.has(id)) visit(id);
+
+  const depth = new Map<string, number>();
+  const depthOf = (id: string): number => {
+    const seen = depth.get(id);
+    if (seen !== undefined) return seen;
+    depth.set(id, 1);
+    const d =
+      1 +
+      Math.max(
+        0,
+        ...edges(id)
+          .filter((a) => milestoneOf(a) === milestoneOf(id))
+          .map(depthOf),
+      );
+    depth.set(id, d);
+    return d;
+  };
+  const byMilestone = new Map<string, string[]>();
+  for (const { id } of inScope)
+    byMilestone.set(milestoneOf(id), [...(byMilestone.get(milestoneOf(id)) ?? []), id]);
+  for (const [m, ids] of byMilestone) {
+    if (ids.length < 2 || !ids.some((id) => edges(id).some((a) => milestoneOf(a) === m))) continue;
+    const k = Math.max(...ids.map(depthOf));
+    warnings.push(
+      `info: ${m} critical path ${k} of ${ids.length} lanes${k === ids.length ? ": fully serial" : ""}`,
+    );
+  }
+  return { warnings, stuck };
+}
+
+/** What keeps the milestones from ever starting: an `after` naming no milestone of the plan, or a wait cycle. */
+export function milestoneProblems(milestones: { id: string; after: string[] }[]): string[] {
+  const after = new Map(milestones.map((m) => [m.id, m.after]));
+  const out: string[] = [];
+  for (const m of milestones)
+    for (const a of m.after) if (!after.has(a)) out.push(`${m.id}: After: ${a} is no milestone of the plan`);
+  const done = new Set<string>();
+  const path: string[] = [];
+  const visit = (id: string): void => {
+    path.push(id);
+    for (const a of after.get(id) ?? []) {
+      if (path.includes(a))
+        out.push(`milestones wait on each other (cycle ${[...path.slice(path.indexOf(a)), a].join(" → ")})`);
+      else if (!done.has(a) && after.has(a)) visit(a);
+    }
+    path.pop();
+    done.add(id);
+  };
+  for (const m of milestones) if (!done.has(m.id)) visit(m.id);
+  return out;
+}