catherd-cli 1.0.0 → 1.1.0

package/src/services/doctor.ts

@@ -1,13 +1,14 @@
 import { existsSync, statSync } from "node:fs";
 import { adapterFor } from "../adapters/registry.ts";
 import "../adapters/all.ts";
-import type { Profile } from "../domain/profile.ts";
-import { ROLES } from "../domain/roles.ts";
+import { BUILTIN_ROLES, type Profile } from "../domain/profile.ts";
+import { DEFAULT_ACCESS, ROLES } from "../domain/roles.ts";
 import { bunTooOld, MIN_BUN } from "../domain/runtime.ts";
 import type { JevTransport } from "../infra/jev-client.ts";
-import { locksDir } from "../infra/paths.ts";
 import { linkedProfiles } from "./agent-links.ts";
-import { backendChecks, usedBackends, workspaceWriteBackends } from "./doctor-backends.ts";
+import { accessChecks } from "./doctor-access.ts";
+import { backendChecks, usedBackends } from "./doctor-backends.ts";
+import { type PushProbe, pushCheck } from "./doctor-push.ts";
 import {
   agentsCheck,
   type Check,
@@ -15,6 +16,7 @@ import {
   fixOf,
   guarded,
   locksCheck,
+  mcpCheck,
   pluginCheck,
 } from "./doctor-checks.ts";
 import { credentialsPath, jevKey, savedJevKey, testJevKey } from "./jev-service.ts";
@@ -40,14 +42,18 @@ export interface Handshake {
   ok: boolean;
   tools: string[];
   error?: string;
+  /** the tail of what the server (or its launcher) wrote to stderr */
+  stderr?: string;
 }
 
 export interface DoctorDeps {
   bunVersion: string;
   /** the package version, which the Claude Code plugin must pin */
   version: string;
-  /** starts `catherd mcp` over stdio and asks it for tools/list */
+  /** starts the MCP server as the plugin does (its launcher) over stdio and asks it for tools/list */
   handshake: () => Promise<Handshake>;
+  /** spec §3.9: sends this Claude Code session a test message; without it (the dashboard) there is no `push` row */
+  push?: () => Promise<PushProbe>;
   jev?: JevTransport;
 }
 
@@ -145,7 +151,8 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
   }
 
   const used = usedBackends(profiles);
-  checks.push(...(await backendChecks(used, profiles)));
+  const installed = new Set<string>();
+  checks.push(...(await backendChecks(used, profiles, installed)));
 
   if (active && [active, ...profiles].every((p) => p.jev.use === "off"))
     checks.push({
@@ -200,88 +207,59 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
   const h = await d
     .handshake()
     .catch((e: unknown): Handshake => ({ ok: false, tools: [], error: errText(e) }));
-  checks.push(
-    h.ok && h.tools.includes("status")
-      ? {
-          id: "mcp",
-          label: "MCP server",
-          state: "ok",
-          word: "ready",
-          detail: `answers tools/list with ${h.tools.length} tools`,
-        }
-      : {
-          id: "mcp",
-          label: "MCP server",
-          state: "fail",
-          word: "no answer",
-          detail: h.error ?? "tools/list has no status tool",
-          fix: "run catherd mcp to see why it does not start",
-        },
-  );
+  checks.push(mcpCheck(h, d.version));
 
-  checks.push(locksCheck());
-  for (const id of workspaceWriteBackends(profiles)) {
-    const a = adapterFor(id);
-    if (!a?.canWrite) continue;
-    const r = await a.canWrite(locksDir()).catch(() => null);
-    const base = { id: `sandbox:${id}`, label: `heavy-lock dir from ${id}'s sandbox` };
+  if (d.push)
     checks.push(
-      r === null
-        ? {
-            ...base,
-            state: "skip",
-            word: "not tested",
-            detail: `no ${id} sandbox to test with on this machine`,
-          }
-        : r.ok
-          ? {
-              ...base,
-              state: "ok",
-              word: "ready",
-              detail: "a workspace-write worker can take the heavy lock",
-            }
-          : {
-              ...base,
-              state: "warn",
-              word: "not writable",
-              detail: `a workspace-write ${id} worker cannot write ${locksDir()}, so catherd lock fails inside it`,
-              ...(r.fix ? { fix: r.fix } : {}),
-            },
+      pushCheck(await d.push().catch((e: unknown): PushProbe => ({ outcome: "failed", detail: errText(e) }))),
     );
-  }
 
-  const full: string[] = [];
-  const advisory: string[] = [];
+  checks.push(locksCheck());
+  // spec §5 and §12: which codex sandbox form runs, and the five access probes per workspace-write backend
+  checks.push(...(await accessChecks(profiles, installed)));
+
+  // spec 1.1 §13: what the shipped defaults do is info; a warning only for what a profile changed
+  const full = { changed: [] as string[], shipped: [] as string[] };
+  const advisory = { changed: [] as string[], shipped: [] as string[] };
+  const backendOf = (r: string) => r.slice(0, r.indexOf(":"));
   for (const p of profiles)
     for (const role of ROLES) {
       const rc = p.roles[role];
       if (!rc.enabled) continue;
-      if (rc.access === "full") full.push(`${role} (${p.name})`);
+      const asShipped = rc.access === DEFAULT_ACCESS[role];
+      if (rc.access === "full") (asShipped ? full.shipped : full.changed).push(`${role} (${p.name})`);
       const soft = [
-        ...new Set(
-          rc.rungs
-            .filter((r) => enforcementOf(r, rc.access) === "advisory")
-            .map((r) => r.slice(0, r.indexOf(":"))),
-        ),
+        ...new Set(rc.rungs.filter((r) => enforcementOf(r, rc.access) === "advisory").map(backendOf)),
       ];
-      if (soft.length) advisory.push(`${role} on ${soft.join(", ")} (${p.name})`);
+      const shippedOn = new Set(BUILTIN_ROLES[role].rungs.map(backendOf));
+      const ours = soft.filter((b) => asShipped && shippedOn.has(b));
+      const theirs = soft.filter((b) => !ours.includes(b));
+      if (ours.length) advisory.shipped.push(`${role} on ${ours.join(", ")} (${p.name})`);
+      if (theirs.length) advisory.changed.push(`${role} on ${theirs.join(", ")} (${p.name})`);
     }
-  if (full.length)
-    checks.push({
-      id: "access:full",
-      label: "full access",
-      state: "warn",
-      word: "warning",
-      detail: `no sandbox for: ${full.join(", ")}`,
-    });
-  if (advisory.length)
-    checks.push({
-      id: "access:advisory",
-      label: "advisory access",
-      state: "warn",
-      word: "warning",
-      detail: `the backend asks but cannot force: ${advisory.join(", ")}`,
-    });
+  const accessRow = (
+    id: string,
+    label: string,
+    rows: { changed: string[]; shipped: string[] },
+    what: string,
+  ): Check | null => {
+    if (!rows.changed.length && !rows.shipped.length) return null;
+    const shipped = rows.shipped.join(", ");
+    return rows.changed.length
+      ? {
+          id,
+          label,
+          state: "warn",
+          word: "warning",
+          detail: `${what}: ${rows.changed.join(", ")}${shipped ? `; as shipped: ${shipped}` : ""}`,
+        }
+      : { id, label, state: "info", word: "default", detail: `${what}: ${shipped}` };
+  };
+  for (const row of [
+    accessRow("access:full", "full access", full, "no sandbox for"),
+    accessRow("access:advisory", "advisory access", advisory, "the backend asks but cannot force"),
+  ])
+    if (row) checks.push(row);
   for (const id of used.keys()) {
     const note = adapterFor(id)?.isolationNote;
     if (note)
@@ -322,13 +300,15 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
     );
   }
 
-  if (!Bun.which("bunx", { PATH: process.env.PATH ?? "" }))
+  // the plugin's launcher needs bunx only when no global catherd is installed
+  const onPath = (bin: string) => Bun.which(bin, { PATH: process.env.PATH ?? "" });
+  if (!onPath("bunx") && !onPath("catherd"))
     checks.push({
       id: "bunx",
       label: "bunx",
       state: "warn",
       word: "missing",
-      detail: "the plugin starts the MCP server with bunx",
+      detail: "the plugin's MCP launcher runs bunx when no global catherd is installed",
       fix: "put Bun's bin folder (~/.bun/bin) on PATH",
     });
   let corrupt: ReturnType<typeof listRuns>["corrupt"] = [];

package/src/services/finalize.ts

@@ -25,6 +25,7 @@ import {
   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 => {
@@ -55,6 +56,15 @@ function claimStale(dir: string): boolean {
   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)]));
@@ -215,6 +225,7 @@ async function compute(run: Run, d: Dispatch): Promise<RunRecord> {
     images: o.images,
     error: o.error,
     replyPath: relative(run.dir, p.reply),
+    ...(a.sessionId ? { sessionId: a.sessionId } : {}),
   };
 }
 
@@ -252,7 +263,7 @@ function recordHarness(run: Run, d: Dispatch, r: RunRecord): void {
  * 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 (a `wait` beside the dispatch's watcher) joins the first one's
+ * 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.
  */
@@ -321,39 +332,46 @@ async function finalizeOnce(run: Run, d: Dispatch): Promise<RunRecord> {
   return saved;
 }
 
-/** The last event of a running dispatch worth showing in a progress line, if any. */
-export function lastEvent(d: Dispatch): string | null {
+/** 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);
-  const line = nonBlankLines(dispatchPaths(d.dir).events).at(-1);
-  if (!a || !line) return null;
-  try {
-    return a.parse(line).lastEvent ?? null;
-  } catch {
-    return null;
+  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, calling `onTick` every `tickMs`; a throwing onTick never ends the wait. */
+/** 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;
-    tickMs: number;
-    now: () => number;
-    onTick?: (secs: number, lastEvent: string | null) => void;
-  },
+  o: { pollMs: number; now: () => number; onPoll?: () => void },
 ): Promise<void> {
-  const started = Date.now();
-  let ticked = started;
   while (dispatchState(d, o.now()) !== "finished") {
     await Bun.sleep(o.pollMs);
-    if (o.onTick && Date.now() - ticked >= o.tickMs) {
-      ticked = Date.now();
-      try {
-        o.onTick(Math.round((ticked - started) / 1000), lastEvent(d));
-      } catch {
-        // a progress report must never stop the wait
-      }
+    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 };
+}