catherd-cli 0.2.1 → 1.1.0

package/src/infra/filelock.ts

@@ -0,0 +1,159 @@
+import { closeSync, openSync, readFileSync, rmSync, statSync, writeSync } from "node:fs";
+import { CatherdError } from "../domain/errors.ts";
+import { isAlive, isValidPid, selfIdentity } from "./proc.ts";
+import { PRIVATE_FILE } from "./store.ts";
+
+interface Holder {
+  pid: number;
+  startTime: string | null;
+}
+
+/** A lock or reclaim marker this old whose owner cannot be identified was left by a crash. */
+const STALE_MS = 5_000;
+
+const me = (): Holder => selfIdentity();
+
+/** The holder recorded in `lock`, or null when it is missing, empty, unparsable or malformed. */
+function readHolder(lock: string): Holder | null {
+  let v: unknown;
+  try {
+    v = JSON.parse(readFileSync(lock, "utf8"));
+  } catch {
+    return null;
+  }
+  const h = v as Partial<Holder> | null;
+  if (typeof h !== "object" || h === null || !isValidPid(h.pid)) return null;
+  if (h.startTime !== null && typeof h.startTime !== "string") return null;
+  return { pid: h.pid, startTime: h.startTime };
+}
+
+function olderThan(file: string, ms: number): boolean {
+  try {
+    return statSync(file).mtimeMs < Date.now() - ms;
+  } catch {
+    return false;
+  }
+}
+
+/** Creates `file` exclusively with `content`; false when it already exists. */
+function tryCreate(file: string, content: string): boolean {
+  try {
+    const fd = openSync(file, "wx", PRIVATE_FILE);
+    try {
+      writeSync(fd, content);
+    } finally {
+      closeSync(fd);
+    }
+    return true;
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+    return false;
+  }
+}
+
+const tryTake = (lock: string, self: Holder): boolean => tryCreate(lock, JSON.stringify(self));
+
+/** Whether `lock` is abandoned: its holder is dead, or it names no valid holder and is older than STALE_MS. */
+function abandoned(lock: string, h: Holder | null): boolean {
+  return h ? !isAlive(h.pid, h.startTime) : olderThan(lock, STALE_MS);
+}
+
+const sameHolder = (a: Holder | null, b: Holder | null): boolean =>
+  a === b || (a !== null && b !== null && a.pid === b.pid && a.startTime === b.startTime);
+
+/**
+ * Removes an abandoned lock. Reclaims are serialised by `${lock}.reclaim`, and the reclaimer
+ * re-reads the lock while holding it and removes it only if it still names the same abandoned
+ * holder, so a waiter can never delete a lock that a live process took in the meantime.
+ */
+function reclaimIfDead(lock: string): void {
+  const seen = readHolder(lock);
+  if (!abandoned(lock, seen)) return;
+  const marker = `${lock}.reclaim`;
+  if (!tryCreate(marker, String(process.pid))) {
+    // A reclaim takes milliseconds; a marker this old was left by a reclaimer that crashed.
+    if (olderThan(marker, STALE_MS)) rmSync(marker, { force: true });
+    return;
+  }
+  try {
+    const now = readHolder(lock);
+    if (sameHolder(now, seen) && abandoned(lock, now)) rmSync(lock, { force: true });
+  } finally {
+    rmSync(marker, { force: true });
+  }
+}
+
+const timedOut = (target: string, lock: string) =>
+  new CatherdError("E_IO_LOCK", `timed out waiting for the lock on ${target}`, {
+    fix: `if no catherd process is running, delete ${lock}`,
+  });
+
+function release(lock: string, self: Holder): void {
+  const h = readHolder(lock);
+  if (h?.pid === self.pid && h.startTime === self.startTime) rmSync(lock, { force: true });
+}
+
+export async function withFileLock<T>(
+  target: string,
+  fn: () => T | Promise<T>,
+  o: { timeoutMs?: number; pollMs?: number } = {},
+): Promise<T> {
+  const lock = `${target}.lock`;
+  const self = me();
+  const deadline = Date.now() + (o.timeoutMs ?? 10_000);
+  while (!tryTake(lock, self)) {
+    reclaimIfDead(lock);
+    if (Date.now() > deadline) throw timedOut(target, lock);
+    await Bun.sleep(o.pollMs ?? 25);
+  }
+  try {
+    return await fn();
+  } finally {
+    release(lock, self);
+  }
+}
+
+/**
+ * `withFileLock` for a synchronous critical section, waiting with a blocking sleep. For writers whose
+ * callers are synchronous (`withProfilesLock` in the profile service); the lock is held for milliseconds.
+ * Not reentrant: a section must not take the same lock again.
+ */
+export function withFileLockSync<T>(
+  target: string,
+  fn: () => T,
+  o: { timeoutMs?: number; pollMs?: number } = {},
+): T {
+  const lock = `${target}.lock`;
+  const self = me();
+  const deadline = Date.now() + (o.timeoutMs ?? 10_000);
+  while (!tryTake(lock, self)) {
+    reclaimIfDead(lock);
+    if (Date.now() > deadline) throw timedOut(target, lock);
+    Bun.sleepSync(o.pollMs ?? 25);
+  }
+  try {
+    return fn();
+  } finally {
+    release(lock, self);
+  }
+}
+
+/**
+ * One attempt at the lock on `target`, reclaiming it first from a dead holder. Returns its release,
+ * or null while a live holder keeps it. For locks held for a long time, like the heavy-command slots.
+ */
+export function tryLock(target: string): (() => void) | null {
+  const lock = `${target}.lock`;
+  const self = me();
+  if (!tryTake(lock, self)) {
+    reclaimIfDead(lock);
+    if (!tryTake(lock, self)) return null;
+  }
+  return () => release(lock, self);
+}
+
+/** Whether a live process holds the lock on `target` (an unreadable holder counts as none). */
+export function lockHeld(target: string): boolean {
+  const h = readHolder(`${target}.lock`);
+  return h !== null && isAlive(h.pid, h.startTime);
+}

package/src/infra/git.ts

@@ -0,0 +1,91 @@
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { parsePorcelainZ, type Snapshot } from "../domain/changes.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { scrubSecrets } from "./env.ts";
+
+/** How one git command ended: its stdout, a failure (exit null when git could not start), or a timeout. */
+export type GitResult =
+  | { kind: "ok"; out: string }
+  | { kind: "failed"; exit: number | null }
+  | { kind: "timed-out" };
+
+/** How long one git command may run by default; finalize's claim window counts it (tests shorten it). */
+export const gitLimits = { timeoutMs: 15_000 };
+
+/**
+ * `git -C repo <args>` with a timeout. GIT_OPTIONAL_LOCKS=0 keeps `status` from taking index.lock,
+ * which would fail a worker's own git command running at the same moment. On a timeout git is killed
+ * and its stdout is not awaited, since a grandchild may still hold the pipe open.
+ */
+export async function git(repo: string, args: string[], timeoutMs = gitLimits.timeoutMs): Promise<GitResult> {
+  let p: Bun.Subprocess<"ignore", "pipe", "ignore">;
+  try {
+    p = Bun.spawn(["git", "-C", repo, ...args], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "ignore",
+      env: { ...scrubSecrets(process.env), GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" },
+    });
+  } catch {
+    return { kind: "failed", exit: null };
+  }
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    p.kill("SIGKILL");
+  }, timeoutMs);
+  const out = new Response(p.stdout).text().catch(() => "");
+  const code = await p.exited;
+  clearTimeout(timer);
+  if (timedOut) return { kind: "timed-out" };
+  return code === 0 ? { kind: "ok", out: await out } : { kind: "failed", exit: code };
+}
+
+const gitBroken = (repo: string, args: string[], r: GitResult) =>
+  new CatherdError(
+    "E_IO_UNEXPECTED",
+    `git ${args[0]} ${r.kind === "timed-out" ? "timed out" : "failed"} in ${repo}`,
+    { fix: `check that git works in ${repo}` },
+  );
+
+export async function gitToplevel(dir: string): Promise<string | null> {
+  const r = await git(dir, ["rev-parse", "--show-toplevel"]);
+  return r.kind === "ok" ? r.out.trim() || null : null;
+}
+
+/** The short HEAD, or null when git cannot say (no commit, not a repo, failure, timeout). */
+export async function gitHead(repo: string, timeoutMs?: number): Promise<string | null> {
+  const r = await git(repo, ["rev-parse", "--short", "HEAD"], timeoutMs);
+  return (r.kind === "ok" && r.out.trim()) || null;
+}
+
+/** False for a missing commit; throws E_IO_UNEXPECTED when git times out, since that proves nothing. */
+export async function commitExists(repo: string, commit: string, timeoutMs?: number): Promise<boolean> {
+  const args = ["cat-file", "-e", `${commit}^{commit}`];
+  const r = await git(repo, args, timeoutMs);
+  if (r.kind === "timed-out") throw gitBroken(repo, args, r);
+  return r.kind === "ok";
+}
+
+function fingerprint(repo: string, xy: string, path: string): string {
+  try {
+    const s = statSync(join(repo, path));
+    return `${xy} ${s.size} ${s.mtimeMs}`;
+  } catch {
+    return `${xy} gone`;
+  }
+}
+
+/**
+ * The repo's dirty files, each with a fingerprint. Throws E_IO_UNEXPECTED when git fails or times out
+ * (including outside a repository), so a broken git never reads as a clean tree.
+ */
+export async function statusSnapshot(repo: string, timeoutMs?: number): Promise<Snapshot> {
+  const args = ["status", "--porcelain=v1", "-z", "--untracked-files=all"];
+  const r = await git(repo, args, timeoutMs);
+  if (r.kind !== "ok") throw gitBroken(repo, args, r);
+  const snap: Snapshot = {};
+  for (const { xy, path } of parsePorcelainZ(r.out)) snap[path] = fingerprint(repo, xy, path);
+  return snap;
+}

package/src/infra/heavy-lock.ts

@@ -0,0 +1,36 @@
+import { availableParallelism } from "node:os";
+import { join } from "node:path";
+import { tryLock } from "./filelock.ts";
+import { locksDir } from "./paths.ts";
+import { ensurePrivateDir } from "./store.ts";
+
+/** A profile's `lock.heavy` as a slot count: a number, or half the cores. */
+export function heavySlots(setting: number | "cpus/2" | undefined): number {
+  if (typeof setting === "number" && Number.isFinite(setting)) return Math.max(1, Math.floor(setting));
+  return Math.max(1, Math.floor(availableParallelism() / 2));
+}
+
+/**
+ * Runs `fn` holding one of `slots` machine-wide heavy-command slots, waiting for a free one. A slot is
+ * a file lock, so a slot whose holder died, or died before writing its name, is reclaimed.
+ */
+export async function withHeavySlot<T>(
+  slots: number,
+  fn: (slot: number) => T | Promise<T>,
+  o: { pollMs?: number } = {},
+): Promise<T> {
+  const dir = locksDir();
+  ensurePrivateDir(dir);
+  for (;;) {
+    for (let i = 0; i < slots; i++) {
+      const release = tryLock(join(dir, `slot-${i}`));
+      if (!release) continue;
+      try {
+        return await fn(i);
+      } finally {
+        release();
+      }
+    }
+    await Bun.sleep(o.pollMs ?? 500);
+  }
+}

package/src/infra/jev-client.ts

@@ -0,0 +1,162 @@
+// Spec §5.5 transport: a thin client (the official SDK is 0.x and Node-targeted) with the SDK's retry
+// semantics (research 2026-09-25-jev.md §4, §5.6).
+
+export const JEV_BASE = "https://api.typesafe.ai/v1";
+
+export interface JevTransport {
+  fetchImpl?: typeof fetch;
+  /** the clock and the wait between attempts; tests replace both */
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  random?: () => number;
+  /** per attempt (10 s) */
+  attemptMs?: number;
+  /** for the whole call, retries included (25 s) */
+  deadlineMs?: number;
+  retries?: number;
+}
+
+export type JevResponse =
+  | { ok: true; body: unknown; requestId: string | null; latencyMs: number; attempts: number }
+  | { ok: false; error: string; status: number | null; latencyMs: number; attempts: number };
+
+const RETRY_AFTER_MAX_MS = 10_000;
+const retryable = (status: number) => status === 408 || status === 429 || status >= 500;
+
+/** A header's value, or null when it is absent or blank. */
+const header = (h: Headers, name: string): string | null => {
+  const v = h.get(name)?.trim();
+  return v ? v : null;
+};
+
+/** `Retry-After` (seconds or an HTTP date) or `retry-after-ms`, capped at 10 s; null when absent. */
+export function retryAfterMs(h: Headers, now: number): number | null {
+  const rawMs = header(h, "retry-after-ms");
+  const ms = Number(rawMs);
+  if (rawMs !== null && Number.isFinite(ms)) return Math.min(Math.max(ms, 0), RETRY_AFTER_MAX_MS);
+  const v = header(h, "retry-after");
+  if (v === null) return null;
+  const secs = Number(v);
+  const wait = Number.isFinite(secs) ? secs * 1000 : Date.parse(v) - now;
+  return Number.isFinite(wait) ? Math.min(Math.max(wait, 0), RETRY_AFTER_MAX_MS) : null;
+}
+
+/** 500 ms doubling per retry, ±25 % jitter. */
+const backoffMs = (retry: number, random: () => number) => 500 * 2 ** (retry - 1) * (0.75 + random() * 0.5);
+
+/**
+ * A failed status as an error, naming a validation error by Jev's own `error_type` and `message` only,
+ * never the raw body (which could echo the request's state).
+ */
+function httpError(status: number, text: string): string {
+  let detail: unknown = null;
+  try {
+    detail = (JSON.parse(text) as { detail?: unknown })?.detail;
+  } catch {
+    // not JSON: nothing to name
+  }
+  if (detail && typeof detail === "object") {
+    const { error_type: type, message } = detail as { error_type?: unknown; message?: unknown };
+    if (typeof type === "string" && /validation/i.test(type))
+      return `http ${status}: ${type}${typeof message === "string" ? `: ${message.slice(0, 200)}` : ""}`;
+  }
+  return `http ${status}`;
+}
+
+/**
+ * `method path` against the Jev API with a bearer key: 10 s per attempt, up to two retries on 408, 429,
+ * 5xx, a network error or a timeout, honouring Retry-After, and never past the 25 s deadline. The attempt
+ * timer covers the whole exchange, body included, and aborts the request when it fires.
+ */
+export async function jevRequest(
+  method: "GET" | "POST",
+  path: string,
+  key: string,
+  body: unknown,
+  o: JevTransport = {},
+): Promise<JevResponse> {
+  const now = o.now ?? Date.now;
+  const sleep = o.sleep ?? ((ms: number) => Bun.sleep(ms));
+  const random = o.random ?? Math.random;
+  const fetchImpl = o.fetchImpl ?? globalThis.fetch;
+  const start = now();
+  const deadline = start + (o.deadlineMs ?? 25_000);
+  const retries = o.retries ?? 2;
+  let last: { error: string; status: number | null } = { error: "network error", status: null };
+  let attempt = 0;
+  for (;;) {
+    attempt++;
+    const left = deadline - now();
+    const ctl = new AbortController();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<"timeout">((resolve) => {
+      timer = setTimeout(
+        () => {
+          // settle first, so the race reads a timeout rather than the abort it causes
+          resolve("timeout");
+          ctl.abort();
+        },
+        Math.min(o.attemptMs ?? 10_000, Math.max(left, 0)),
+      );
+    });
+    const exchange = async () => {
+      const res = await fetchImpl(`${JEV_BASE}${path}`, {
+        method,
+        headers: {
+          authorization: `Bearer ${key}`,
+          ...(body === undefined ? {} : { "content-type": "application/json" }),
+          ...(attempt > 1 ? { "x-typesafe-retry-count": String(attempt - 1) } : {}),
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        signal: ctl.signal,
+      });
+      const text = res.ok ? await res.text() : await res.text().catch(() => "");
+      return { res, text };
+    };
+    let wait: number | null = null;
+    try {
+      const r = await Promise.race([exchange(), timeout]);
+      if (r === "timeout") {
+        last = { error: "timeout", status: null };
+      } else if (r.res.ok) {
+        let parsed: unknown = null;
+        try {
+          parsed = JSON.parse(r.text);
+        } catch {
+          return {
+            ok: false,
+            error: "unexpected response",
+            status: r.res.status,
+            latencyMs: now() - start,
+            attempts: attempt,
+          };
+        }
+        return {
+          ok: true,
+          body: parsed,
+          requestId: r.res.headers.get("x-typesafe-request-id"),
+          latencyMs: now() - start,
+          attempts: attempt,
+        };
+      } else {
+        last = { error: httpError(r.res.status, r.text), status: r.res.status };
+        if (!retryable(r.res.status))
+          return { ok: false, ...last, latencyMs: now() - start, attempts: attempt };
+        wait = retryAfterMs(r.res.headers, now());
+      }
+    } catch {
+      last = { error: "network error", status: null };
+    } finally {
+      clearTimeout(timer);
+      ctl.abort();
+    }
+    if (attempt > retries) break;
+    const pause = wait ?? backoffMs(attempt, random);
+    if (now() + pause >= deadline) {
+      last = { error: `deadline (${last.error})`, status: last.status };
+      break;
+    }
+    await sleep(pause);
+  }
+  return { ok: false, ...last, latencyMs: now() - start, attempts: attempt };
+}

package/src/infra/launch.ts

@@ -0,0 +1,25 @@
+import { closeSync, openSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { scrubSecrets } from "./env.ts";
+import { log as logRow } from "./log.ts";
+import { PRIVATE_FILE } from "./store.ts";
+
+/** A thin executable that supervises one spec; unlike src/cli.ts it never loads the TUI. */
+export const SUPERVISE_ENTRY = fileURLToPath(new URL("../entry/supervise-bin.ts", import.meta.url));
+
+/** Starts `supervise-bin.ts <spec>` in its own session and returns at once; it outlives this process. */
+export function launchSupervisor(specPath: string): number {
+  const log = openSync(join(dirname(specPath), "supervisor.log"), "a", PRIVATE_FILE);
+  const p = Bun.spawn([process.execPath, SUPERVISE_ENTRY, specPath], {
+    stdin: "ignore",
+    stdout: log,
+    stderr: log,
+    detached: true,
+    env: scrubSecrets(process.env),
+  });
+  closeSync(log);
+  p.unref();
+  logRow("info", "launch", { spec: specPath, pid: p.pid });
+  return p.pid;
+}

package/src/infra/log.ts

@@ -0,0 +1,84 @@
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { MIN_SECRET, replaceSecrets, scrubKeyShapes, secretEnvValues } from "../domain/secrets.ts";
+import { isPlain } from "../domain/util.ts";
+import { logsDir } from "./paths.ts";
+import { appendJsonl, ensureJsonlHeader } from "./store.ts";
+
+// Spec §10.2: `<data>/logs/catherd-<date>.jsonl`, 7-day rotation, level from CATHERD_LOG or `--verbose`.
+
+const LEVELS = ["off", "error", "warn", "info", "debug"] as const;
+export type Level = Exclude<(typeof LEVELS)[number], "off">;
+/** Days of logs kept, today included. */
+const KEEP_DAYS = 7;
+
+/** `CATHERD_LOG` (off, error, warn, info, debug); info when unset or unknown. */
+function logLevel(): (typeof LEVELS)[number] {
+  const v = process.env.CATHERD_LOG?.toLowerCase();
+  return (LEVELS as readonly string[]).includes(v ?? "") ? (v as Level) : "info";
+}
+
+const rank = (l: string) => LEVELS.indexOf(l as (typeof LEVELS)[number]);
+
+const extra = new Set<string>();
+/** A secret that lives outside the env (the saved Jev key): scrubbed from every row from now on. */
+export function addSecret(value: string | null | undefined): void {
+  if (value && value.length >= MIN_SECRET) extra.add(value);
+}
+
+/** Every literal secret a row must not carry: credential-named env values and each added secret. */
+export const knownSecrets = (env: Record<string, string | undefined> = process.env): string[] => [
+  ...secretEnvValues(env),
+  ...extra,
+];
+
+/**
+ * `v` with every known secret and every key-shaped string replaced by `[redacted]`, in any string at
+ * any depth, and every env map (a field named `env`) reduced to its keys.
+ */
+export function redact<T>(v: T, secrets: string[] = knownSecrets()): T {
+  const walk = (x: unknown, key: string | null): unknown => {
+    if (typeof x === "string") return scrubKeyShapes(replaceSecrets(x, secrets, "[redacted]"), "[redacted]");
+    if (Array.isArray(x)) return x.map((y) => walk(y, null));
+    if (isPlain(x)) {
+      if (key === "env") return Object.keys(x).sort();
+      return Object.fromEntries(Object.entries(x).map(([k, y]) => [k, walk(y, k)]));
+    }
+    return x;
+  };
+  return walk(v, null) as T;
+}
+
+const day = (d: Date) => d.toISOString().slice(0, 10);
+export const logFile = (now: Date = new Date()): string => join(logsDir(), `catherd-${day(now)}.jsonl`);
+
+let rotatedOn: string | null = null;
+/** Deletes log files from before the last KEEP_DAYS days; once per process per day. */
+export function rotate(now: Date = new Date()): void {
+  if (rotatedOn === day(now) || !existsSync(logsDir())) return;
+  rotatedOn = day(now);
+  const oldest = day(new Date(now.getTime() - (KEEP_DAYS - 1) * 86_400_000));
+  for (const f of readdirSync(logsDir())) {
+    const m = /^catherd-(\d{4}-\d{2}-\d{2})\.jsonl$/.exec(f);
+    if (m && (m[1] as string) < oldest) rmSync(join(logsDir(), f), { force: true });
+  }
+}
+
+/** Tests only: rotate again on the next write. */
+export const resetRotation = (): void => {
+  rotatedOn = null;
+};
+
+/** One redacted JSONL row. Never throws: logging must not fail the work it records. */
+export function log(level: Level, event: string, fields: Record<string, unknown> = {}): void {
+  if (rank(level) > rank(logLevel())) return;
+  const now = new Date();
+  try {
+    rotate(now);
+    const file = logFile(now);
+    ensureJsonlHeader(file, "log");
+    appendJsonl(file, redact({ at: now.toISOString(), level, event, pid: process.pid, ...fields }));
+  } catch {
+    // a full disk or an unwritable data dir costs the log row, never the call
+  }
+}

package/src/infra/paths.ts

@@ -0,0 +1,38 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+function root(kind: "config" | "data"): string {
+  // set for an isolated worker whose XDG_CONFIG_HOME points elsewhere, so its `catherd lock` reads this config
+  if (kind === "config" && process.env.CATHERD_CONFIG_DIR) return process.env.CATHERD_CONFIG_DIR;
+  const home = process.env.CATHERD_HOME;
+  if (home) return join(home, kind);
+  if (kind === "config") return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "catherd");
+  return join(process.env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "catherd");
+}
+
+export const configDir = (): string => root("config");
+export const dataDir = (): string => root("data");
+
+/** Claude Code's own folder, as Claude Code finds it (`CLAUDE_CONFIG_DIR`, else `~/.claude`). */
+export const claudeHome = (): string => process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+
+/** Where Claude Code reads user agents; catherd links its agent files here (spec §7.3). */
+export const claudeAgentsDir = (): string =>
+  process.env.CATHERD_CLAUDE_AGENTS_DIR || join(claudeHome(), "agents");
+
+/** A readable slug of the repo's git toplevel plus 8 hex chars of its hash: `/a-b/c` ≠ `/a/b-c`. */
+export function repoKey(toplevel: string): string {
+  const slug =
+    toplevel
+      .replace(/^\/+/, "")
+      .replace(/[^A-Za-z0-9._-]+/g, "-")
+      .slice(0, 60) || "root";
+  const hash = new Bun.CryptoHasher("sha256").update(toplevel).digest("hex").slice(0, 8);
+  return `${slug}-${hash}`;
+}
+
+export const repoDir = (toplevel: string): string => join(dataDir(), "repos", repoKey(toplevel));
+export const runsDir = (toplevel: string): string => join(repoDir(toplevel), "runs");
+export const logsDir = (): string => join(dataDir(), "logs");
+export const discoveryDir = (): string => join(dataDir(), "discovery");
+export const locksDir = (): string => join(dataDir(), "locks");