catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/services/gate-service.ts

@@ -1,21 +1,15 @@
-import {
-  existsSync,
-  lstatSync,
-  readdirSync,
-  readlinkSync,
-  realpathSync,
-  type Stats,
-  statSync,
-} from "node:fs";
-import { join } from "node:path";
+import { lstatSync, readdirSync, readlinkSync, realpathSync, type Stats, statSync } from "node:fs";
+import { basename, join } from "node:path";
 import { z } from "zod";
 import { CatherdError, isCatherdError } from "../domain/errors.ts";
 import { normalizeOwned, overlaps } from "../domain/lane.ts";
 import { git, gitHead, statusSnapshot } from "../infra/git.ts";
 import { repoDir } from "../infra/paths.ts";
 import { appendJsonl, ensureJsonlHeader, readJsonl } from "../infra/store.ts";
+import { gateEnvLines, readGateEnv } from "./gate-env.ts";
 import type { Deps } from "./ports.ts";
 import { findRun, type Run } from "./run-store.ts";
+import { treeOf } from "./tree-path.ts";
 
 // Spec 1.1 §7: the verifier's gate ledger. A gate item that passed on the same content, with the same
 // command, is carried over instead of run again; every check is a verifier step `peek` and `status` show.
@@ -35,6 +29,10 @@ type GatePass = z.infer<typeof GatePassSchema>;
 export interface VerifierStep {
   at: string;
   item: string;
+  /** the item's command; steps written before 1.5 lack it */
+  command?: string;
+  /** the item's paths, cleaned (plan 23); steps written before it lack them */
+  paths?: string[];
   carried: boolean;
   /** a carried item: the commit its pass was recorded on */
   commit?: string;
@@ -46,10 +44,11 @@ export interface VerifierStep {
 export const gatesFile = (toplevel: string): string => join(repoDir(toplevel), "gates.jsonl");
 const stepsFile = (run: Run): string => join(run.dir, "verifier.jsonl");
 
-/** Repo-relative paths, `.` for the whole repo; anything that leaves the repo is refused. */
+/** Repo-relative paths, `.` (or `./`) for the whole repo; anything that leaves the repo is refused. */
 function cleanPaths(paths: string[]): string[] {
+  const whole = (p: string) => p.trim() === "." || p.trim() === "./";
   try {
-    return [...new Set(paths.map((p) => (p.trim() === "." ? "." : normalizeOwned(p))))].sort();
+    return [...new Set(paths.map((p) => (whole(p) ? "." : normalizeOwned(p))))].sort();
   } catch (e) {
     if (isCatherdError(e))
       throw new CatherdError("E_INPUT_INVALID", e.message.replace("owned path", "gate path"), {
@@ -148,7 +147,10 @@ const isLink = (file: string): boolean => {
 
 /** Whether git ignores `p` (a tracked file never is). */
 async function ignored(repo: string, p: string): Promise<boolean> {
-  return (await git(repo, ["check-ignore", "-q", "--", p.replace(/\/$/, "")])).kind === "ok";
+  const bare = p.replace(/\/$/, "");
+  const asked = async (q: string) => (await git(repo, ["check-ignore", "-q", "--", q])).kind === "ok";
+  // a directory pattern (`dist/`) matches a path that is not on disk yet only through a child of it
+  return (await asked(bare)) || (!onDisk(join(repo, bare)) && (await asked(`${bare}/.catherd`)));
 }
 
 /** The most files a gate path's on-disk walk hashes. */
@@ -179,47 +181,101 @@ function walk(repo: string, p: string): string[] {
 }
 
 /**
- * The content hash of `paths`: each one's tree entry at HEAD (mode, type and object id), plus the content of every
- * uncommitted change under them, so a verifier checking a tree not yet committed gets a hash of what it ran.
- * A path git ignores, or one not at HEAD, is also hashed file by file from disk; ignored files under `.` or
- * under a tracked directory are not, so an ignored input is covered only when it is named.
+ * The lockfiles a gate item's dependencies come from, wherever the repo tracks them: they stand in for
+ * `node_modules` and the toolchain caches, which a gate path never needs to name (plan 23).
  */
-async function contentHash(repo: string, paths: string[]): Promise<string> {
+export const LOCKFILES = [
+  "bun.lock",
+  "bun.lockb",
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "go.sum",
+  "Cargo.lock",
+  "poetry.lock",
+  "uv.lock",
+  "Gemfile.lock",
+  "composer.lock",
+];
+
+/** `git ls-files -s -z` for `pathspecs`: each tracked file's mode, object id, stage and path, as the index holds them. */
+async function tracked(repo: string, pathspecs: string[]): Promise<string> {
+  const r = await git(repo, ["ls-files", "-s", "-z", "--", ...pathspecs]);
+  if (r.kind !== "ok")
+    throw new CatherdError(
+      "E_IO_UNEXPECTED",
+      `git ls-files ${r.kind === "timed-out" ? "timed out" : "failed"} in ${repo}`,
+      { fix: `check that git works in ${repo}` },
+    );
+  return r.out;
+}
+
+/** Whether anything is at `file` on disk, a dangling symlink included. */
+const onDisk = (file: string): boolean => {
+  try {
+    lstatSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The content hash of `paths` (plan 23, a monorepo gate): the tracked files under each one, from `git ls-files -s`
+ * (mode, object id and path, so a committed chmod -x is new content), the repo's tracked lockfiles, and the
+ * content of every uncommitted change under them, so a verifier checking a tree not yet committed gets a hash of
+ * what it ran. An ignored path named explicitly (a `.env`, a build output, a `node_modules` folder) is hashed
+ * from disk, file by file within GATE_WALK_MAX, and as "absent" while it is not there; ignored files under `.`
+ * or under a tracked directory are never walked. A named symlink is hashed by what it points at too.
+ */
+async function contentHash(repo: string, paths: string[]): Promise<{ hash: string; dirty: boolean }> {
   const h = new Bun.CryptoHasher("sha256");
+  // a dependency bump reaches every gate item through its lockfile
+  h.update(
+    `locks=${sha(
+      await tracked(
+        repo,
+        LOCKFILES.map((l) => `:(glob)**/${l}`),
+      ),
+    )}\n`,
+  );
   for (const p of paths) {
-    // the tree entry, mode and type with the object id (`100755 blob <sha>`), so a committed chmod -x is new
-    // content; a directory's tree id already covers its children's modes
-    const entry = await git(
-      repo,
-      p === "."
-        ? ["rev-parse", "HEAD^{tree}"]
-        : ["ls-tree", "--full-tree", "HEAD", "--", p.replace(/\/$/, "")],
-    );
-    const at = entry.kind === "ok" ? entry.out.trim() : "";
-    // a mistyped path (or a glob) would hash as a constant and carry a pass forever
-    if (!at && !existsSync(join(repo, p)))
+    const bare = p.replace(/\/$/, "");
+    const listed = await tracked(repo, [p === "." ? "." : bare]);
+    const there = p === "." || onDisk(join(repo, bare));
+    const isIgnored = p !== "." && listed === "" && (await ignored(repo, p));
+    // a mistyped path (or a glob) would hash as a constant and carry a pass forever; an ignored output that
+    // is not built yet is part of the content, as "absent"
+    if (listed === "" && !there && !isIgnored)
       throw new CatherdError(
         "E_INPUT_INVALID",
         `gate path ${p} exists neither at HEAD nor in the working tree`,
         {
-          fix: "check the spelling: pass repo-relative files or directories that exist, like src/ or package.json (no globs)",
+          fix: "check the spelling: pass repo-relative files or directories that exist, like src/ or package.json (no globs); a git-ignored output not built yet is fine",
         },
       );
-    h.update(`${p}=${at || "missing"}\n`);
-    // git status leaves ignored files out, so an ignored path (.env, a build output) or one not at HEAD is
-    // hashed by what is on disk; "." keeps to HEAD and the not-ignored status. A symlink's HEAD entry is only
-    // its link text, so a named symlink is hashed from disk too, by what it points at
-    if (p !== "." && (!at || isLink(join(repo, p)) || (await ignored(repo, p)))) {
+    h.update(`${p}=${listed ? sha(listed) : there ? "untracked" : "absent"}\n`);
+    // git status leaves ignored files out, so an ignored path named here is hashed by what is on disk; "."
+    // keeps to the index and the not-ignored status. A tracked symlink's index entry is only its link text,
+    // so a named symlink is hashed from disk too, by what it points at
+    if (p !== "." && there && (isIgnored || isLink(join(repo, bare)))) {
       // one budget per gate path: its walk and every symlink target it follows count against GATE_WALK_MAX
       const budget: Budget = { path: p, files: 0, seen: new Set() };
       for (const f of walk(repo, p)) h.update(`disk ${f}=${await diskEntry(join(repo, f), budget)}\n`);
     }
   }
+  // an uncommitted lockfile change (a worker's `bun add`) reaches every item, as a committed one does
   const dirty = Object.keys(await statusSnapshot(repo))
-    .filter((f) => paths.includes(".") || overlaps([f], paths).length > 0)
+    .filter(
+      (f) =>
+        paths.includes(".") ||
+        LOCKFILES.includes(basename(f.replace(/\/$/, ""))) ||
+        overlaps([f], paths).length > 0,
+    )
     .sort();
   for (const f of dirty) h.update(`dirty ${f}=${await dirtyEntry(join(repo, f), f)}\n`);
-  return h.digest("hex");
+  return { hash: h.digest("hex"), dirty: dirty.length > 0 };
 }
 
 const readPasses = (repo: string): GatePass[] =>
@@ -241,37 +297,167 @@ export function latestVerifierStep(run: Run): VerifierStep | null {
     .at(-1) ?? null) as VerifierStep | null;
 }
 
+/** One item the verifier checked for a milestone in this run: its name, its command, and whether it passed. */
+export interface RecordedItem {
+  item: string;
+  command: string | null;
+  /** gate_check would carry it now: its last check's command has a pass on the current content of its paths */
+  passed: boolean;
+}
+
+const milestoneSteps = (run: Run, m: string): VerifierStep[] =>
+  readJsonl<VerifierStep>(stepsFile(run)).rows.filter(
+    (s) => typeof s?.item === "string" && s.milestone === m,
+  );
+
+/** Each item's last step, in the order the items were first checked. */
+const lastSteps = (steps: VerifierStep[]): VerifierStep[] =>
+  [...new Set(steps.map((s) => s.item))].map(
+    (item) => steps.findLast((s) => s.item === item) as VerifierStep,
+  );
+
+/** The pass gate_check carries for `command` on `paths` as the tree is now, if any. */
+async function carryingPass(
+  repo: string,
+  command: string,
+  paths: string[],
+  cwd: string = repo,
+): Promise<GatePass | undefined> {
+  const { hash } = await contentHash(cwd, paths);
+  return readPasses(repo).findLast((p) => p.command === command && p.hash === hash);
+}
+
+/**
+ * The items checked for milestone `m` in this run, in the order they were first checked (plan 23): a new
+ * verifier reuses their names, so the ledger carries what passed, and a re-check starts from the failed ones.
+ * An item counts as passed only when gate_check would carry it now, by the same rule: its last check's command
+ * has a pass on the current content of its paths, so a fix round that changed what it reads opens it again.
+ */
+export async function recordedItems(run: Run, m: string): Promise<RecordedItem[]> {
+  const repo = run.meta.repo;
+  const passes = readPasses(repo);
+  return Promise.all(
+    lastSteps(milestoneSteps(run, m)).map(async (last) => {
+      const command = last.command ?? null;
+      // a step written before its paths were recorded: those of this run's latest pass of the item stand in
+      const paths =
+        last.paths ??
+        passes.findLast((p) => p.run === run.id && p.item === last.item && p.command === command)?.paths;
+      let passed = false;
+      if (command !== null && paths !== undefined) {
+        try {
+          passed = (await carryingPass(repo, command, paths, treeOf(run, m))) !== undefined;
+        } catch (e) {
+          // a path gone from the tree carries no pass
+          if (!isCatherdError(e)) throw e;
+        }
+      }
+      return { item: last.item, command, passed };
+    }),
+  );
+}
+
+/**
+ * The milestone's checked items with no pass recorded since their last check, from the step history alone
+ * (sync, for the protocol's next step); the verifier's listing and brief use recordedItems, which also re-opens
+ * a pass whose content has changed since.
+ */
+export function failedItems(run: Run, m: string): string[] {
+  const passes = readPasses(run.meta.repo).filter((p) => p.run === run.id);
+  return lastSteps(milestoneSteps(run, m))
+    .filter(
+      (last) =>
+        !last.carried && !passes.some((p) => p.item === last.item && Date.parse(p.at) >= Date.parse(last.at)),
+    )
+    .map((last) => last.item);
+}
+
 /**
  * `gate_check`: carried when this repo has a pass with the same command on the same content of `paths`;
- * records "verifier step: <item>" either way.
+ * records "verifier step: <item>" either way. With `milestone` it also lists the milestone's recorded items
+ * (plan 23), so a verifier reuses the names an earlier one checked.
  */
 export async function gateCheck(
   deps: Deps,
   i: { run: string; item: string; command: string; paths: string[]; milestone?: string },
-): Promise<{ carried: true; passedAt: string; commit: string } | { carried: false }> {
+): Promise<
+  ({ carried: true; passedAt: string; commit: string } | { carried: false }) & { recorded?: RecordedItem[] }
+> {
   const run = findRun(i.run);
   const paths = cleanPaths(i.paths);
-  const hash = await contentHash(run.meta.repo, paths);
-  const pass = readPasses(run.meta.repo).findLast((p) => p.command === i.command && p.hash === hash);
+  if (run.meta.base && !i.milestone)
+    throw new CatherdError("E_INPUT_INVALID", "a base run's gate_check names its milestone", {
+      fix: "pass milestone",
+    });
+  const pass = await carryingPass(run.meta.repo, i.command, paths, treeOf(run, i.milestone ?? null));
   recordStep(run, {
     at: new Date(deps.now()).toISOString(),
     item: i.item,
+    command: i.command,
+    paths,
     carried: pass !== undefined,
     ...(pass ? { commit: pass.commit } : {}),
     ...(i.milestone ? { milestone: i.milestone } : {}),
   });
-  return pass ? { carried: true, passedAt: pass.at, commit: pass.commit } : { carried: false };
+  const carried = pass
+    ? { carried: true as const, passedAt: pass.at, commit: pass.commit }
+    : { carried: false as const };
+  return i.milestone ? { ...carried, recorded: await recordedItems(run, i.milestone) } : carried;
+}
+
+/**
+ * `gate_check` with a milestone and no item: the milestone's recorded items, recording no step, and the
+ * repo's gate environment as `NAME=value` lines (a secret as `NAME=$FROM`), which a native verifier exports.
+ */
+export async function gateList(i: {
+  run: string;
+  milestone: string;
+}): Promise<{ recorded: RecordedItem[]; env: string[] }> {
+  const run = findRun(i.run);
+  return {
+    recorded: await recordedItems(run, i.milestone),
+    env: gateEnvLines(await readGateEnv(run.meta.repo)),
+  };
 }
 
-/** `gate_pass`: records that `command` passed on the current content of `paths`, with its evidence. */
+/** `gate_check` as both MCP servers expose it: item, command and paths together check an item; none of them,
+ * with a milestone, lists the milestone's recorded items. */
+export async function gateCheckOrList(
+  deps: Deps,
+  a: { run: string; item?: string; command?: string; paths?: string[]; milestone?: string },
+): Promise<unknown> {
+  if (a.item === undefined && a.command === undefined && a.paths === undefined) {
+    if (!a.milestone)
+      throw new CatherdError("E_INPUT_INVALID", "gate_check needs an item, or a milestone to list", {
+        fix: "pass item, command and paths to check an item, or only run and milestone to list the recorded items",
+      });
+    return gateList({ run: a.run, milestone: a.milestone });
+  }
+  if (a.item === undefined || a.command === undefined || a.paths === undefined)
+    throw new CatherdError("E_INPUT_INVALID", "gate_check needs item, command and paths together", {
+      fix: "pass all three to check an item, or none of them (with milestone) to list the recorded items",
+    });
+  return gateCheck(deps, { ...a, item: a.item, command: a.command, paths: a.paths });
+}
+
+/**
+ * `gate_pass`: records that `command` passed on the current content of `paths`, with its evidence. A pass on
+ * uncommitted changes under `paths` names its commit `<HEAD>+uncommitted`: HEAD alone is not what it ran on.
+ */
 export async function gatePass(
   deps: Deps,
   i: { run: string; item: string; command: string; paths: string[]; evidence: string },
 ): Promise<{ recorded: true; hash: string; commit: string }> {
   const run = findRun(i.run);
   const paths = cleanPaths(i.paths);
-  const hash = await contentHash(run.meta.repo, paths);
-  const commit = (await gitHead(run.meta.repo)) ?? "none";
+  // a base run's milestone has its own tree: the one of the latest step that checked this item with this command
+  const step = readJsonl<VerifierStep>(stepsFile(run)).rows.findLast(
+    (s) => s?.item === i.item && s.command === i.command,
+  );
+  const cwd = treeOf(run, step?.milestone ?? null);
+  const { hash, dirty } = await contentHash(cwd, paths);
+  const head = (await gitHead(cwd)) ?? "none";
+  const commit = dirty ? `${head}+uncommitted` : head;
   const file = gatesFile(run.meta.repo);
   ensureJsonlHeader(file, "gates");
   appendJsonl(file, {

package/src/services/global-install.ts

@@ -23,25 +23,51 @@ export type GlobalInstall =
   | { state: "shadowed"; onPath: string | null }
   | { state: "failed"; reason: string };
 
-async function run(cmd: string[]): Promise<{ ok: boolean; stdout: string; output: string }> {
+/** How long `bun add -g` may take: a blackholed or proxied registry would otherwise hold `init` for as long as Bun retries. */
+export const installLimits = { timeoutMs: 120_000 };
+
+/** How long a `catherd --version` probe may take before its version counts as unknown. */
+export const versionLimits = { timeoutMs: 10_000 };
+
+/**
+ * `cmd` with its output. Past `timeoutMs` it is killed and reported as failed with the reason; its output is
+ * not awaited then, since a child it started may still hold the pipes open.
+ */
+export async function run(
+  cmd: string[],
+  timeoutMs?: number,
+): Promise<{ ok: boolean; stdout: string; output: string }> {
   const p = Bun.spawn(cmd, {
     env: scrubSecrets(process.env),
     stdin: "ignore",
     stdout: "pipe",
     stderr: "pipe",
   });
-  const [out, err, code] = await Promise.all([
-    new Response(p.stdout).text(),
-    new Response(p.stderr).text(),
-    p.exited,
-  ]);
-  return { ok: code === 0, stdout: out, output: `${err}${out}` };
+  const out = new Response(p.stdout).text().catch(() => "");
+  const err = new Response(p.stderr).text().catch(() => "");
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<"late">((resolve) => {
+    if (timeoutMs !== undefined) timer = setTimeout(() => resolve("late"), timeoutMs);
+  });
+  const code = await Promise.race([p.exited, late]).finally(() => clearTimeout(timer));
+  if (code === "late") {
+    p.kill("SIGKILL");
+    const what = cmd.slice(1).join(" ");
+    return {
+      ok: false,
+      stdout: "",
+      output: `${what} timed out after ${Math.round((timeoutMs ?? 0) / 1000)} s`,
+    };
+  }
+  const [stdout, stderr] = await Promise.all([out, err]);
+  return { ok: code === 0, stdout, output: `${stderr}${stdout}` };
 }
 
 /** what `bin --version` prints on stdout (a warning on stderr must not make it look like another version) */
 async function versionOf(bin: string | null): Promise<string | null> {
   if (!bin) return null;
-  const r = await run([bin, "--version"]).catch(() => null);
+  // a wedged `catherd` on PATH must not hold `init`: past the limit its version is unknown
+  const r = await run([bin, "--version"], versionLimits.timeoutMs).catch(() => null);
   return r?.ok ? r.stdout.trim() || null : null;
 }
 
@@ -71,10 +97,12 @@ export const realGlobalInstall: GlobalInstallDeps = {
     return versionOf(Bun.which("catherd", { PATH }));
   },
   install: (version) =>
-    run([process.execPath, "add", "-g", `catherd-cli@${version}`]).catch((e: unknown) => ({
-      ok: false,
-      output: errorMessage(e),
-    })),
+    run([process.execPath, "add", "-g", `catherd-cli@${version}`], installLimits.timeoutMs).catch(
+      (e: unknown) => ({
+        ok: false,
+        output: errorMessage(e),
+      }),
+    ),
 };
 
 /**
@@ -86,7 +114,12 @@ export async function ensureGlobal(
   deps: GlobalInstallDeps,
   installing: () => void,
 ): Promise<GlobalInstall> {
-  if ((await deps.globalVersion()) === version) return { state: "current" };
+  if ((await deps.globalVersion()) === version) {
+    // current, but the launcher runs the catherd PATH finds first: another version there (or none) still
+    // makes it fall back to bunx, so say so as after an install
+    const onPath = await deps.pathVersion().catch(() => null);
+    return onPath === version ? { state: "current" } : { state: "shadowed", onPath };
+  }
   installing();
   // never rejects: a failed install is reported, and init goes on
   const r = await deps.install(version).catch((e: unknown) => ({ ok: false, output: errorMessage(e) }));

package/src/services/jev-service.ts

@@ -16,7 +16,7 @@ import { assetPath } from "../infra/assets.ts";
 import { type JevTransport, jevRequest } from "../infra/jev-client.ts";
 import { addSecret, log } from "../infra/log.ts";
 import { appendJsonl, ensureJsonlHeader, readJsonl, readVersioned } from "../infra/store.ts";
-import { aaKey, credentialsPath, saveCredential, savedCredential } from "./credentials.ts";
+import { credentialsPath, saveCredential, savedCredential } from "./credentials.ts";
 
 export { credentialsPath };
 
@@ -26,12 +26,10 @@ export const jevQuestions = (): JevFile =>
   (file ??= readVersioned(assetPath("catalog/jev.json"), JevFileSchema, 1));
 
 /**
- * Registers the saved keys (Jev's and Artificial Analysis's) with the redactor, for a process that reads
- * logs without ever using them.
+ * Registers the saved key (Jev's) with the redactor, for a process that reads logs without ever using it.
  */
 export function registerSavedSecrets(): void {
   addSecret(jevKey());
-  addSecret(aaKey());
 }
 
 /** The key saved in credentials.json, or why that file cannot be read (unparsable, newer schema). */

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 [];
+  }
+}