catherd-cli 1.3.0 → 1.5.0

package/src/services/gate-env.ts

@@ -0,0 +1,218 @@
+import { existsSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { CatherdError } from "../domain/errors.ts";
+import { ROLE_ENV } from "../domain/role-scope.ts";
+import { isCatherdSecret } from "../infra/env.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { gitToplevel } from "../infra/git.ts";
+import { DISPATCH_ID_ENV } from "../infra/lock-activity.ts";
+import { repoDir } from "../infra/paths.ts";
+import { ensurePrivateDir, readVersioned, writeJsonAtomic } from "../infra/store.ts";
+import { knowledgeFor } from "./run-store.ts";
+
+// Plan 23: the gate environment a repo's verifier and preflight need (DOCKER_HOST, HTTPS_PROXY, a
+// TESTCONTAINERS_* setting), kept beside the repo's knowledge.md, so no verifier sets it up by hand. A value is
+// stored as is; a secret is stored by reference only: the name of the env var that holds it, read when a
+// role or a check starts, never written to disk.
+
+const GATE_ENV_SCHEMA = 1;
+
+const EntrySchema = z.union([z.strictObject({ value: z.string() }), z.strictObject({ from: z.string() })]);
+export type GateEnvEntry = z.infer<typeof EntrySchema>;
+
+const GateEnvSchema = z.looseObject({
+  schema: z.literal(GATE_ENV_SCHEMA),
+  vars: z.record(z.string(), EntrySchema),
+});
+type GateEnvFile = z.infer<typeof GateEnvSchema>;
+
+/** `<data>/repos/<repo key>/gate-env.json`: where a toplevel keyed it (before 1.5, and with no origin). */
+export const gateEnvFile = (toplevel: string): string => join(repoDir(toplevel), "gate-env.json");
+
+/**
+ * Spec 1.5 "Knowledge keyed by git origin": the gate-env.json beside the repo's knowledge.md, which every
+ * worktree and clone of one repository shares. A toplevel-keyed file this worktree left before is migrated on
+ * read: its variables join the shared file (the shared file's own win), and it is renamed `.migrated`.
+ */
+export async function gateEnvFor(toplevel: string): Promise<string> {
+  const file = join(dirname(await knowledgeFor(toplevel)), "gate-env.json");
+  const legacy = gateEnvFile(toplevel);
+  if (file === legacy || !existsSync(legacy)) return file;
+  ensurePrivateDir(dirname(file));
+  await withFileLock(file, () => {
+    if (!existsSync(legacy)) return;
+    const vars = { ...readVarsAt(legacy), ...readVarsAt(file) };
+    writeJsonAtomic(file, { schema: GATE_ENV_SCHEMA, vars } satisfies GateEnvFile);
+    renameSync(legacy, `${legacy}.migrated`);
+  });
+  return file;
+}
+
+function readVarsAt(file: string): Record<string, GateEnvEntry> {
+  if (!existsSync(file)) return {};
+  return readVersioned<GateEnvFile>(file, GateEnvSchema, GATE_ENV_SCHEMA).vars;
+}
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A name a secret goes by: such a variable is set by reference (--from), never by value. */
+const SECRET_NAME = /KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL|AUTH/i;
+
+/**
+ * The names catherd sets in a dispatch itself: the role's identity, dispatch id, testcontainers session, scratch
+ * and working dir, the process basics, catherd's own dirs, and the homes an isolated CLI is moved to (codex,
+ * grok, cursor, agy, opencode, claude). A gate env entry under one would take the role's identity or isolation.
+ */
+const RESERVED = new Set([
+  ROLE_ENV,
+  DISPATCH_ID_ENV,
+  "TESTCONTAINERS_SESSION_ID",
+  "TMPDIR",
+  "PWD",
+  "PATH",
+  "HOME",
+  "CATHERD_HOME",
+  "CATHERD_CONFIG_DIR",
+  "CATHERD_DATA_DIR",
+  "CODEX_HOME",
+  "GROK_HOME",
+  "CLAUDE_CONFIG_DIR",
+  "CURSOR_CONFIG_DIR",
+  "CURSOR_DATA_DIR",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+]);
+
+/** The repo's gate environment, by name; empty when none is set. */
+export async function readGateEnv(toplevel: string): Promise<Record<string, GateEnvEntry>> {
+  return readVarsAt(await gateEnvFor(toplevel));
+}
+
+async function top(repo: string): Promise<string> {
+  const t = await gitToplevel(repo);
+  if (!t)
+    throw new CatherdError("E_IO_PATH", `${repo} is not inside a git repository`, {
+      fix: "pass the path of the repository",
+    });
+  return t;
+}
+
+function assertName(name: string): void {
+  if (!NAME.test(name))
+    throw new CatherdError("E_INPUT_INVALID", `"${name}" is not an env var name`, {
+      fix: "use letters, digits and _, not starting with a digit, e.g. DOCKER_HOST",
+    });
+}
+
+async function update(
+  repo: string,
+  change: (vars: Record<string, GateEnvEntry>) => void,
+): Promise<{ repo: string; vars: Record<string, GateEnvEntry> }> {
+  const t = await top(repo);
+  const file = await gateEnvFor(t);
+  ensurePrivateDir(dirname(file));
+  return withFileLock(file, () => {
+    const vars = { ...readVarsAt(file) };
+    change(vars);
+    writeJsonAtomic(file, { schema: GATE_ENV_SCHEMA, vars } satisfies GateEnvFile);
+    return { repo: t, vars };
+  });
+}
+
+/**
+ * Sets one variable of the repo's gate environment: a value, or `from`, the name of the env var that holds a
+ * secret. A secret-looking name (…KEY, …TOKEN, …PASSWORD) takes `from` only, so no secret lands on disk.
+ */
+export async function setGateEnv(
+  repo: string,
+  name: string,
+  entry: GateEnvEntry,
+): Promise<{ repo: string; vars: Record<string, GateEnvEntry> }> {
+  assertName(name);
+  if (RESERVED.has(name))
+    throw new CatherdError("E_INPUT_INVALID", `${name} is set by catherd for every role`, {
+      fix: "the gate environment holds what a gate needs (DOCKER_HOST, a proxy, a TESTCONTAINERS_* setting), not a role's identity, scratch or home",
+    });
+  if ("from" in entry) {
+    assertName(entry.from);
+    if (isCatherdSecret(entry.from))
+      throw new CatherdError("E_INPUT_INVALID", `${entry.from} is catherd's own secret: no role gets it`, {
+        fix: "reference the env var that holds the gate's own secret",
+      });
+  } else if (SECRET_NAME.test(name))
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      `${name} looks like a secret: catherd stores it by reference only`,
+      {
+        fix: `export it in your shell, then: catherd knowledge env set ${name} --from <the env var that holds it>`,
+      },
+    );
+  return update(repo, (vars) => {
+    vars[name] = entry;
+  });
+}
+
+/** Removes one variable; refused when it is not set. */
+export function removeGateEnv(
+  repo: string,
+  name: string,
+): Promise<{ repo: string; vars: Record<string, GateEnvEntry> }> {
+  return update(repo, (vars) => {
+    if (!(name in vars))
+      throw new CatherdError("E_INPUT_INVALID", `${name} is not in the gate environment`, {
+        fix: "catherd knowledge env list shows what is set",
+      });
+    delete vars[name];
+  });
+}
+
+/** The variables as briefs show them: `NAME=value`, a reference as `NAME=$FROM`. */
+export const gateEnvLines = (vars: Record<string, GateEnvEntry>): string[] =>
+  Object.entries(vars)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, e]) => ("from" in e ? `${k}=$${e.from}` : `${k}=${e.value}`));
+
+/** The literal values, for a spec written to disk; references stay names (`refs`), resolved at spawn. */
+export function gateEnvParts(vars: Record<string, GateEnvEntry>): {
+  values: Record<string, string>;
+  refs: Record<string, string>;
+} {
+  const values: Record<string, string> = {};
+  const refs: Record<string, string> = {};
+  for (const [k, e] of Object.entries(vars)) {
+    if ("from" in e) refs[k] = e.from;
+    else values[k] = e.value;
+  }
+  return { values, refs };
+}
+
+/**
+ * The env the gate environment adds to `base`: its values, and each reference read from `base`, else from
+ * `fallback` (the login env); a reference neither holds is left out, and named in `missing`.
+ */
+export function resolveGateEnv(
+  vars: Record<string, GateEnvEntry>,
+  base: Record<string, string | undefined>,
+  fallback: () => Record<string, string | undefined> = () => ({}),
+): { env: Record<string, string>; missing: string[] } {
+  const { values, refs } = gateEnvParts(vars);
+  return resolveRefs(values, refs, base, fallback);
+}
+
+/** `values` plus each of `refs` (name → the env var holding it) read from `base`, else `fallback`. */
+export function resolveRefs(
+  values: Record<string, string>,
+  refs: Record<string, string>,
+  base: Record<string, string | undefined>,
+  fallback: () => Record<string, string | undefined> = () => ({}),
+): { env: Record<string, string>; missing: string[] } {
+  const env = { ...values };
+  const missing: string[] = [];
+  let login: Record<string, string | undefined> | null = null;
+  for (const [k, from] of Object.entries(refs)) {
+    const v = base[from] ?? (login ??= fallback())[from];
+    if (v === undefined) missing.push(k);
+    else env[k] = v;
+  }
+  return { env, missing };
+}

package/src/services/gate-service.ts

@@ -1,19 +1,12 @@
-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";
 
@@ -35,6 +28,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 +43,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 +146,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 +180,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 +296,153 @@ 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[]): Promise<GatePass | undefined> {
+  const { hash } = await contentHash(repo, 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)) !== 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);
+  const pass = await carryingPass(run.meta.repo, i.command, paths);
   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";
+  const { hash, dirty } = await contentHash(run.meta.repo, paths);
+  const head = (await gitHead(run.meta.repo)) ?? "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) }));