catherd-cli 0.2.1 → 1.1.0

package/src/services/finalize.ts

@@ -0,0 +1,377 @@
+import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { relative } from "node:path";
+import type { BackendAdapter, FinishedRun, Outcome, Spent } from "../adapters/backend.ts";
+import { adapterFor } from "../adapters/registry.ts";
+import "../adapters/all.ts";
+import { changedPaths, type Snapshot, splitChanges } from "../domain/changes.ts";
+import { isCatherdError } from "../domain/errors.ts";
+import { parseRung } from "../domain/ids.ts";
+import {
+  type ExitInfo,
+  parseReplyStatus,
+  type RunRecord,
+  THREAD_HEAVY_INPUT,
+  ZERO_TOKENS,
+} from "../domain/record.ts";
+import { dispatchPaths, readClaimant, readExit, tryClaim } from "../infra/dispatch-dir.ts";
+import { isAlive } from "../infra/proc.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { gitLimits, statusSnapshot } from "../infra/git.ts";
+import {
+  appendJsonl,
+  ensureJsonlHeader,
+  makePrivate,
+  nonBlankLines,
+  writeTextAtomic,
+} from "../infra/store.ts";
+import { type Dispatch, dispatchState, listDispatches, readProc } from "./dispatches.ts";
+import { tail } from "./run-debug.ts";
+import { appendRecord, readRecords, recordsOnThread, type Run, runPaths } from "./run-store.ts";
+
+const text = (file: string): string => {
+  try {
+    return readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+};
+
+function claimAgeMs(dir: string): number {
+  try {
+    return Date.now() - statSync(dispatchPaths(dir).claim).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Whether another finalizer's claim may be taken over: its claimant is dead, or the claim is older than
+ * the longest a live claimant can take: every bounded step of `compute` (the adapter's settle, the one
+ * `git status` snapshot, each at its own timeout) plus the margin for its unbounded file work. A claim
+ * that names no one (an older build's) is judged by its age alone.
+ */
+function claimStale(dir: string): boolean {
+  const who = readClaimant(dir);
+  if (who && !isAlive(who.pid, who.startTime)) return true;
+  return claimAgeMs(dir) > settleLimits.timeoutMs + gitLimits.timeoutMs + settleLimits.claimMarginMs;
+}
+
+/**
+ * Whether another live process holds this dispatch's finalizer claim (not yet stale): that process writes its
+ * record and settles it, so a recovery pass (`claim`) leaves it alone rather than wait on it.
+ */
+export function finalizingElsewhere(dir: string): boolean {
+  const who = readClaimant(dir);
+  return who !== null && who.pid !== process.pid && !claimStale(dir);
+}
+
+/** The owned paths of the run's other dispatches whose lifetime overlapped [start, end]. */
+function othersOwns(run: Run, self: Dispatch, start: number, end: number): string[] {
+  const ended = new Map(readRecords(run).records.map((r) => [r.dispatchId, Date.parse(r.endedAt)]));
+  return listDispatches(run)
+    .filter((d) => d.admit.dispatchId !== self.admit.dispatchId)
+    .filter((d) => {
+      const from = Date.parse(d.admit.admittedAt);
+      const to = ended.get(d.admit.dispatchId) ?? (Date.parse(readExit(d.dir)?.endedAt ?? "") || Date.now());
+      return from <= end && to >= start;
+    })
+    .flatMap((d) => d.admit.owns);
+}
+
+/** The tree after the run, or null when git cannot say: the record is still written, its changes unknown. */
+async function snapshotOrNull(repo: string): Promise<Snapshot | null> {
+  try {
+    return await statusSnapshot(repo);
+  } catch (e) {
+    if (isCatherdError(e) && e.code === "E_IO_UNEXPECTED") return null;
+    throw e;
+  }
+}
+
+/**
+ * How long a backend may take to settle a finished session before its stream's own figures stand, and
+ * how much longer than that and the git snapshot's timeout (gitLimits) a finalizer's claim may live (its file
+ * work and the append) before a second finalizer takes it over.
+ */
+export const settleLimits = { timeoutMs: 20_000, claimMarginMs: 10_000 };
+
+/**
+ * What earlier records on `thread` already counted: a resumed session's totals repeat them. Every run's,
+ * since a role may resume a thread an earlier catherd run started.
+ */
+function priorOn(run: Run, backend: string, thread: string, self: string): Spent {
+  const earlier = recordsOnThread(run, backend, thread).filter((r) => r.dispatchId !== self);
+  return {
+    tokens: {
+      input: earlier.reduce((n, r) => n + r.tokens.input, 0),
+      cached: earlier.reduce((n, r) => n + r.tokens.cached, 0),
+      output: earlier.reduce((n, r) => n + r.tokens.output, 0),
+    },
+    costUsd: earlier.reduce((n, r) => n + (r.costUsd ?? 0), 0),
+  };
+}
+
+/** The adapter's settled outcome, or `o` unchanged when it has none, throws, or is slower than the limit. */
+export async function settled(
+  adapter: BackendAdapter,
+  o: Outcome,
+  finished: FinishedRun,
+  prior: () => Spent,
+): Promise<Outcome> {
+  if (!adapter.settle || o.thread === null) return o;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const late = new Promise<Outcome>((resolve) => {
+      timer = setTimeout(() => resolve(o), settleLimits.timeoutMs);
+    });
+    return await Promise.race([adapter.settle(o, finished, prior()), late]);
+  } catch {
+    return o;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function compute(run: Run, d: Dispatch): Promise<RunRecord> {
+  const a = d.admit;
+  const p = dispatchPaths(d.dir);
+  // no exit.json: its supervisor died. A cancel asked for before that ended it; anything else is lost.
+  const exit: ExitInfo = readExit(d.dir) ?? {
+    code: null,
+    signal: null,
+    reason: existsSync(p.cancel) ? "cancelled" : "lost",
+    endedAt: new Date().toISOString(),
+  };
+  const startedAt = readProc(d.dir)?.startedAt ?? a.admittedAt;
+  const reply = text(p.reply);
+  const finished: FinishedRun = {
+    request: {
+      rung: parseRung(a.rung),
+      access: a.access,
+      thread: a.thread,
+      isolated: a.isolated,
+      repo: a.repo,
+      briefPath: p.brief,
+      replyPath: p.reply,
+      dispatchDir: d.dir,
+    },
+    eventLines: nonBlankLines(p.events),
+    reply,
+    stderr: text(p.stderr),
+    exit,
+    startedAtMs: Date.parse(startedAt),
+  };
+  const adapter = adapterFor(a.backend);
+  const first: Outcome = adapter
+    ? adapter.finalize(finished)
+    : {
+        status: "failed",
+        thread: a.thread,
+        tokens: { ...ZERO_TOKENS },
+        costUsd: null,
+        images: [],
+        error: { code: "E_BACKEND_MISSING", message: `catherd has no ${a.backend} adapter` },
+      };
+  const o = adapter
+    ? await settled(adapter, first, finished, () => priorOn(run, a.backend, first.thread ?? "", a.dispatchId))
+    : first;
+  // A CLI that streams its reply (claude, opencode) leaves reply.md to catherd.
+  if (o.reply !== undefined && o.reply !== reply) writeTextAtomic(p.reply, o.reply);
+  // one the CLI wrote itself (codex) has the CLI's mode
+  else makePrivate(p.reply);
+  const replyText = o.reply ?? reply;
+  const start = Date.parse(startedAt);
+  const end = Date.parse(exit.endedAt);
+  const after = await snapshotOrNull(a.repo);
+  const { changedOwned, violations } = after
+    ? splitChanges(
+        changedPaths(a.before, after),
+        a.owns,
+        // from admission, when the before-snapshot was taken, not from the worker's start
+        othersOwns(run, d, Date.parse(a.admittedAt), end),
+        a.lane !== null || a.access === "read-only",
+      )
+    : { changedOwned: [], violations: [] };
+  const reported = parseReplyStatus(replyText);
+  return {
+    schema: 1,
+    runId: run.id,
+    dispatchId: a.dispatchId,
+    name: a.name,
+    role: a.role,
+    lane: a.lane,
+    backend: a.backend,
+    rung: a.rung,
+    attempt: a.attempt,
+    failoverFrom: a.failoverFrom,
+    thread: o.thread,
+    status: o.status,
+    startedAt,
+    endedAt: exit.endedAt,
+    secs: Math.max(0, Math.round((end - start) / 1000)),
+    exitCode: exit.code,
+    signal: exit.signal,
+    cliVersion: a.cliVersion,
+    tokens: o.tokens,
+    costUsd: o.costUsd,
+    changedOwned,
+    violations,
+    ...(after ? {} : { gitUnavailable: true }),
+    replyStatus: reported.status,
+    replyWhy: reported.why,
+    threadHeavy: o.tokens.input >= THREAD_HEAVY_INPUT,
+    access: a.access,
+    isolated: a.isolated,
+    images: o.images,
+    error: o.error,
+    replyPath: relative(run.dir, p.reply),
+    ...(a.sessionId ? { sessionId: a.sessionId } : {}),
+  };
+}
+
+/**
+ * A fresh thread's first-turn input, for the harness-cost line of runs_summary: its first model request's
+ * input, from a backend whose stream reports usage per request. Codex reports it per exec: no row.
+ */
+function recordHarness(run: Run, d: Dispatch, r: RunRecord): void {
+  const a = adapterFor(d.admit.backend);
+  if (d.admit.thread !== null || !a) return;
+  for (const line of nonBlankLines(dispatchPaths(d.dir).events)) {
+    let input;
+    try {
+      input = a.parse(line).requestInput;
+    } catch {
+      continue;
+    }
+    if (input === undefined) continue;
+    const file = runPaths(run.dir).harness;
+    ensureJsonlHeader(file, "harness");
+    appendJsonl(file, {
+      at: r.endedAt,
+      name: r.name,
+      backend: r.backend,
+      isolated: r.isolated,
+      firstTurnInput: input,
+    });
+    return;
+  }
+}
+
+/**
+ * Spec §3.3: the first finalizer claims the dispatch and writes its record; any other waits for that
+ * record and returns it. If the claimer died before appending, the late finalizer appends instead;
+ * appendRecord's per-dispatch dedupe keeps that to one record either way (audit C2). A claimer that throws
+ * releases its claim.
+ *
+ * In this process, a second finalizer (`cancel` beside the dispatch's watcher) joins the first one's
+ * promise. Across processes it waits for the claimant's record, and takes over only once the claim is
+ * stale (claimant dead, or past its settle window): never while a live claimant may still be settling.
+ */
+export function finalizeDispatch(run: Run, d: Dispatch): Promise<RunRecord> {
+  const id = d.admit.dispatchId;
+  const joined = inFlight.get(id);
+  if (joined) return joined;
+  const p = finalizeOnce(run, d).finally(() => inFlight.delete(id));
+  inFlight.set(id, p);
+  return p;
+}
+
+/** This process's finalizes in flight, by dispatch id. */
+const inFlight = new Map<string, Promise<RunRecord>>();
+
+const recordOf = (run: Run, id: string): RunRecord | undefined =>
+  readRecords(run).records.find((r) => r.dispatchId === id);
+
+/** Test seam: runs after a finalizer judged a claim stale, before it takes the lock to take it over. */
+export const claimSeams = { beforeTakeover: async (_dir: string): Promise<void> => {} };
+
+/**
+ * Takes over a stale claim, serialized by a lock on the claim: under it, reads the claim again, removes it
+ * only if it is still stale, and claims it. True for the one caller that now holds the claim; a caller that
+ * finds it live (another took it over, or its claimant woke) or loses the claim to a fresh claimant gets
+ * false and goes back to waiting for the record. A claim is removed only here and by its own claimant, and
+ * here only right before claiming it, so there is never a second live computer, and never none for long:
+ * a claim that vanished is claimed by the next finalizer's poll.
+ */
+export async function takeOverStaleClaim(dir: string): Promise<boolean> {
+  const claim = dispatchPaths(dir).claim;
+  return withFileLock(claim, () => {
+    if (existsSync(claim)) {
+      if (!claimStale(dir)) return false;
+      rmSync(claim, { force: true });
+    }
+    return tryClaim(dir);
+  });
+}
+
+async function finalizeOnce(run: Run, d: Dispatch): Promise<RunRecord> {
+  for (;;) {
+    const existing = recordOf(run, d.admit.dispatchId);
+    if (existing) return existing;
+    // a claim released by a claimer that threw is gone: this claims it
+    if (tryClaim(d.dir)) break;
+    if (existsSync(dispatchPaths(d.dir).claim) && claimStale(d.dir)) {
+      await claimSeams.beforeTakeover(d.dir);
+      if (await takeOverStaleClaim(d.dir)) break;
+      continue;
+    }
+    await Bun.sleep(50);
+  }
+  let saved: RunRecord;
+  let mine: RunRecord;
+  try {
+    mine = await compute(run, d);
+    saved = await appendRecord(run, mine);
+  } catch (e) {
+    // no record: let the next finalizer try at once rather than wait on this claim; ours only, since a
+    // claim held past its window may have been taken over
+    if (readClaimant(d.dir)?.pid === process.pid) rmSync(dispatchPaths(d.dir).claim, { force: true });
+    throw e;
+  }
+  if (saved === mine) recordHarness(run, d, mine);
+  return saved;
+}
+
+/** How much of a role's last event `peek` and the runs page show (spec §3.7). */
+export const LAST_EVENT_CHARS = 160;
+
+const oneLine = (s: string): string => {
+  const line = s.split("\n").find((l) => l.trim()) ?? "";
+  return line.length > LAST_EVENT_CHARS ? `${line.slice(0, LAST_EVENT_CHARS - 1)}…` : line;
+};
+
+/**
+ * Spec §3.7: what a live role is doing, from the end of its events.jsonl: the last line its adapter reads as an
+ * activity (a command, a file edit, a message line), else the last event's name; null before any event.
+ */
+export function lastActivity(d: Dispatch): string | null {
+  const a = adapterFor(d.admit.backend);
+  if (!a) return null;
+  let name: string | null = null;
+  for (const line of tail(dispatchPaths(d.dir).events, 200).toReversed()) {
+    let delta;
+    try {
+      delta = a.parse(line);
+    } catch {
+      continue;
+    }
+    if (delta.activity) return oneLine(delta.activity);
+    name ??= delta.lastEvent ?? null;
+  }
+  return name;
+}
+
+/** Waits until the dispatch finishes, polling every `pollMs`; `onPoll` runs at each poll, and never ends the wait. */
+export async function waitForFinish(
+  d: Dispatch,
+  o: { pollMs: number; now: () => number; onPoll?: () => void },
+): Promise<void> {
+  while (dispatchState(d, o.now()) !== "finished") {
+    await Bun.sleep(o.pollMs);
+    try {
+      o.onPoll?.();
+    } catch {
+      // a report on the way must never stop the wait
+    }
+  }
+}

package/src/services/gate-service.ts

@@ -0,0 +1,288 @@
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readlinkSync,
+  realpathSync,
+  type Stats,
+  statSync,
+} from "node:fs";
+import { 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 type { Deps } from "./ports.ts";
+import { findRun, type Run } from "./run-store.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.
+
+const GatePassSchema = z.looseObject({
+  at: z.string(),
+  run: z.string(),
+  item: z.string(),
+  command: z.string(),
+  paths: z.array(z.string()),
+  hash: z.string(),
+  commit: z.string(),
+  evidence: z.string(),
+});
+type GatePass = z.infer<typeof GatePassSchema>;
+
+export interface VerifierStep {
+  at: string;
+  item: string;
+  carried: boolean;
+  /** a carried item: the commit its pass was recorded on */
+  commit?: string;
+  /** the milestone the verifier checks, when gate_check named it: the digest lists only that milestone's items */
+  milestone?: string;
+}
+
+/** `<data>/repos/<repo key>/gates.jsonl`, beside the repo's knowledge.md. */
+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. */
+function cleanPaths(paths: string[]): string[] {
+  try {
+    return [...new Set(paths.map((p) => (p.trim() === "." ? "." : normalizeOwned(p))))].sort();
+  } catch (e) {
+    if (isCatherdError(e))
+      throw new CatherdError("E_INPUT_INVALID", e.message.replace("owned path", "gate path"), {
+        fix: "pass repo-relative paths, like src/ or package.json, or . for the whole repo",
+      });
+    throw e;
+  }
+}
+
+const sha = (b: string | Uint8Array) => new Bun.CryptoHasher("sha256").update(b).digest("hex");
+
+const tooMany = (p: string) =>
+  new CatherdError("E_INPUT_INVALID", `gate path ${p} holds more than ${GATE_WALK_MAX} files to hash`, {
+    fix: "name narrower paths: the files or directories under it that the gate item reads",
+  });
+
+/** How many files one gate path's hash has read so far, against GATE_WALK_MAX, and the realpaths it walked. */
+interface Budget {
+  path: string;
+  files: number;
+  seen: Set<string>;
+}
+
+const count = (b: Budget): void => {
+  if (++b.files > GATE_WALK_MAX) throw tooMany(b.path);
+};
+
+/**
+ * What a symlink points at, by content only (never its path, which may be outside the repo): a file by its
+ * type, exec bit and bytes; a directory walked, names relative to it; "dangling" when nothing is there; and
+ * "cycle" for a realpath this hash already walked.
+ */
+async function targetEntry(link: string, b: Budget): Promise<string> {
+  let real: string;
+  try {
+    real = realpathSync(link);
+  } catch {
+    return "dangling";
+  }
+  if (b.seen.has(real)) return "cycle";
+  b.seen.add(real);
+  const s = statSync(real);
+  if (s.isFile()) return `${s.mode & 0o111 ? "exec" : "file"} ${sha(await Bun.file(real).bytes())}`;
+  if (!s.isDirectory()) return "other";
+  const h = new Bun.CryptoHasher("sha256");
+  const visit = async (rel: string): Promise<void> => {
+    for (const name of readdirSync(join(real, rel)).sort()) {
+      const r = rel ? `${rel}/${name}` : name;
+      let e: Stats;
+      try {
+        e = lstatSync(join(real, r));
+      } catch {
+        continue;
+      }
+      if (e.isDirectory()) {
+        await visit(r);
+        continue;
+      }
+      count(b);
+      h.update(`${r}=${await diskEntry(join(real, r), b)}\n`);
+    }
+  };
+  await visit("");
+  return `dir ${h.digest("hex")}`;
+}
+
+/**
+ * One path on disk as git would store it: its type and exec bit as well as its bytes, so a lost exec bit or a
+ * file turned symlink is new content; a symlink by its link text and by what it points at (targetEntry), so
+ * editing a link's target is new content too.
+ */
+async function diskEntry(file: string, b: Budget): Promise<string> {
+  let s: Stats;
+  try {
+    s = lstatSync(file);
+  } catch {
+    return "gone";
+  }
+  if (s.isSymbolicLink()) return `link ${sha(readlinkSync(file))} -> ${await targetEntry(file, b)}`;
+  if (!s.isFile()) return s.isDirectory() ? "dir" : "other";
+  return `${s.mode & 0o111 ? "exec" : "file"} ${sha(await Bun.file(file).bytes())}`;
+}
+
+/** One dirty path's entry, with its own budget and cycle guard. */
+const dirtyEntry = (file: string, path: string): Promise<string> =>
+  diskEntry(file, { path, files: 0, seen: new Set() });
+
+/** Whether `file` is a symlink on disk. */
+const isLink = (file: string): boolean => {
+  try {
+    return lstatSync(file).isSymbolicLink();
+  } catch {
+    return false;
+  }
+};
+
+/** 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";
+}
+
+/** The most files a gate path's on-disk walk hashes. */
+export const GATE_WALK_MAX = 10_000;
+
+/**
+ * The files under `p` on disk (itself when it is not a directory), repo-relative and sorted; a symlink is
+ * an entry, not followed. More than GATE_WALK_MAX is refused, not hashed in part.
+ */
+function walk(repo: string, p: string): string[] {
+  const out: string[] = [];
+  const visit = (rel: string): void => {
+    let s: Stats;
+    try {
+      s = lstatSync(join(repo, rel));
+    } catch {
+      return;
+    }
+    if (!s.isDirectory()) {
+      out.push(rel);
+      if (out.length > GATE_WALK_MAX) throw tooMany(p);
+      return;
+    }
+    for (const name of readdirSync(join(repo, rel))) visit(`${rel}/${name}`);
+  };
+  visit(p.replace(/\/$/, ""));
+  return out.sort();
+}
+
+/**
+ * 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.
+ */
+async function contentHash(repo: string, paths: string[]): Promise<string> {
+  const h = new Bun.CryptoHasher("sha256");
+  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)))
+      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)",
+        },
+      );
+    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)))) {
+      // 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`);
+    }
+  }
+  const dirty = Object.keys(await statusSnapshot(repo))
+    .filter((f) => paths.includes(".") || 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");
+}
+
+const readPasses = (repo: string): GatePass[] =>
+  readJsonl<unknown>(gatesFile(repo)).rows.flatMap((row) => {
+    const r = GatePassSchema.safeParse(row);
+    return r.success ? [r.data] : [];
+  });
+
+function recordStep(run: Run, step: VerifierStep): void {
+  const file = stepsFile(run);
+  ensureJsonlHeader(file, "verifier");
+  appendJsonl(file, step);
+}
+
+/** The verifier's latest step in this run, for `status` and `peek`; null before its first gate_check. */
+export function latestVerifierStep(run: Run): VerifierStep | null {
+  return (readJsonl<VerifierStep>(stepsFile(run))
+    .rows.filter((r) => typeof r?.item === "string")
+    .at(-1) ?? null) as VerifierStep | null;
+}
+
+/**
+ * `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.
+ */
+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 }> {
+  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);
+  recordStep(run, {
+    at: new Date(deps.now()).toISOString(),
+    item: i.item,
+    carried: pass !== undefined,
+    ...(pass ? { commit: pass.commit } : {}),
+    ...(i.milestone ? { milestone: i.milestone } : {}),
+  });
+  return pass ? { carried: true, passedAt: pass.at, commit: pass.commit } : { carried: false };
+}
+
+/** `gate_pass`: records that `command` passed on the current content of `paths`, with its evidence. */
+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";
+  const file = gatesFile(run.meta.repo);
+  ensureJsonlHeader(file, "gates");
+  appendJsonl(file, {
+    at: new Date(deps.now()).toISOString(),
+    run: run.id,
+    item: i.item,
+    command: i.command,
+    paths,
+    hash,
+    commit,
+    evidence: i.evidence,
+  } satisfies GatePass);
+  return { recorded: true, hash, commit };
+}