catherd-cli 0.2.1 → 1.0.0

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");

package/src/infra/proc.ts

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from "node:fs";
+import { scrubSecrets } from "./env.ts";
+
+/** A string that differs between two processes that held the same pid: /proc starttime, else `ps lstart`. */
+export function processStartTime(pid: number): string | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // Field 22 (starttime); the command name in field 2 may hold spaces, so split after its ')'.
+    const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    return fields[19] ?? null;
+  } catch {
+    return psStartTime(pid);
+  }
+}
+
+let ownStart: string | null = null;
+/**
+ * This process's own identity for the leases and claims it writes. The start time is read once and kept:
+ * on macOS `ps` can fail for a moment, and a second read must never make a process a stranger to itself.
+ */
+export function selfIdentity(): { pid: number; startTime: string | null } {
+  ownStart ??= processStartTime(process.pid);
+  return { pid: process.pid, startTime: ownStart };
+}
+
+/** `ps` by absolute path where it lives, so a caller with a narrow PATH (a test, a sandbox) still finds it. */
+const PS = existsSync("/bin/ps") ? "/bin/ps" : "ps";
+
+/** `ps lstart` for a pid, or null when ps is missing or fails (macOS has no /proc). */
+export function psStartTime(
+  pid: number,
+  env: Record<string, string | undefined> = process.env,
+): string | null {
+  try {
+    // lstart is printed in the local time zone and locale: pin both so every process agrees.
+    const ps = Bun.spawnSync([PS, "-o", "lstart=", "-p", String(pid)], {
+      stdout: "pipe",
+      stderr: "ignore",
+      env: { ...scrubSecrets(env), LC_ALL: "C", TZ: "UTC" },
+    });
+    const out = ps.success ? ps.stdout.toString("utf8").trim() : "";
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Only an integer >= 1 names one real process: 0 and negatives address groups. Pid 1 is valid
+ * (catherd may be a container's entrypoint); only killGroup refuses it, since kill(-1) signals everything.
+ */
+export const isValidPid = (pid: unknown): pid is number => Number.isInteger(pid) && (pid as number) >= 1;
+
+/**
+ * Whether a live pid is still the process recorded with `recorded`. A start time that cannot be read now
+ * (`ps` fails for a moment on macOS) counts as the same process: a live lock holder or worker is never
+ * taken for dead, and the worst case is a lock that times out with E_IO_LOCK instead.
+ */
+export const sameProcess = (recorded: string | null, current: string | null): boolean =>
+  recorded === null || current === null || current === recorded;
+
+/**
+ * For a signal only: the pid is live and its start time reads back exactly as recorded. An unreadable or
+ * unrecorded start time is not a match, since the pid may belong to another process by now.
+ */
+export const surelySame = (recorded: string | null, current: string | null): boolean =>
+  recorded !== null && current !== null && current === recorded;
+
+export function isSurelyAlive(pid: number, startTime: string | null): boolean {
+  return isAlive(pid, startTime) && surelySame(startTime, processStartTime(pid));
+}
+
+/** Whether /proc shows the pid as a zombie: dead, only never reaped (a pid 1 that reaps no orphans). */
+function isZombie(pid: number): boolean {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    return stat.slice(stat.lastIndexOf(")") + 2, stat.lastIndexOf(")") + 3) === "Z";
+  } catch {
+    return false;
+  }
+}
+
+export function isAlive(pid: number, startTime: string | null): boolean {
+  if (!isValidPid(pid)) return false;
+  try {
+    process.kill(pid, 0);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "EPERM") return false;
+  }
+  if (isZombie(pid)) return false;
+  return startTime === null || sameProcess(startTime, processStartTime(pid));
+}
+
+/**
+ * Signals the process group a detached child leads (pgid === pid), falling back to the pid alone. No
+ * group (ESRCH) means its leader is gone too, and that pid may belong to another process by now.
+ */
+export function killGroup(pid: number, signal: NodeJS.Signals = "SIGTERM"): void {
+  if (!isValidPid(pid) || pid === 1) return;
+  try {
+    process.kill(-pid, signal);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ESRCH") return;
+    try {
+      process.kill(pid, signal);
+    } catch {
+      // already gone
+    }
+  }
+}

package/src/infra/store.ts

@@ -0,0 +1,229 @@
+import {
+  appendFileSync,
+  chmodSync,
+  closeSync,
+  existsSync,
+  fchmodSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readSync,
+  renameSync,
+  statSync,
+  writeSync,
+} from "node:fs";
+import { dirname, sep } from "node:path";
+import { z } from "zod";
+import { CatherdError, UPGRADE } from "../domain/errors.ts";
+import { configDir, dataDir } from "./paths.ts";
+
+// Audit S2: catherd's dirs hold briefs, argv, stderr tails and logs, so they are 0700 and its files 0600.
+export const PRIVATE_DIR = 0o700;
+export const PRIVATE_FILE = 0o600;
+
+const tightened = new Set<string>();
+/** Once per process per dir: `dir` at 0700, if an older catherd left it open to others. */
+function tighten(dir: string): void {
+  if (tightened.has(dir)) return;
+  tightened.add(dir);
+  try {
+    if (statSync(dir).mode & 0o077) chmodSync(dir, PRIVATE_DIR);
+  } catch {
+    // not ours to fix (another owner, a read-only mount): the files inside are still 0600
+  }
+}
+
+/**
+ * `dir` and any missing parent, created 0700. `mkdirSync` leaves an existing dir as it is, so under
+ * catherd's config or data dir, `dir` and every dir up to that root are tightened to 0700 (a 0.x install).
+ */
+export function ensurePrivateDir(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: PRIVATE_DIR });
+  for (const root of [configDir(), dataDir()]) {
+    if (dir !== root && !dir.startsWith(root + sep)) continue;
+    for (let d = dir; d.length >= root.length; d = dirname(d)) {
+      tighten(d);
+      if (d === root) break;
+    }
+  }
+}
+
+/** `file` at 0600 when it exists and others may read it: a file another program wrote into catherd's dirs. */
+export function makePrivate(file: string): void {
+  try {
+    if (statSync(file).mode & 0o077) chmodSync(file, PRIVATE_FILE);
+  } catch {
+    // missing, or not ours: its dir is 0700 all the same
+  }
+}
+
+/** `mode` (0600 by default) is the file's exact permission bits (umask aside), set before any byte is written. */
+export function writeTextAtomic(file: string, text: string, o: { mode?: number } = {}): void {
+  const mode = o.mode ?? PRIVATE_FILE;
+  ensurePrivateDir(dirname(file));
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  const fd = openSync(tmp, "w", mode);
+  try {
+    fchmodSync(fd, mode);
+    writeSync(fd, text);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, file);
+}
+
+export const writeJsonAtomic = (file: string, value: unknown, o: { mode?: number } = {}): void =>
+  writeTextAtomic(file, `${JSON.stringify(value, null, 2)}\n`, o);
+
+function newer(file: string, found: number, current: number): CatherdError {
+  return new CatherdError(
+    "E_CONFIG_NEWER_SCHEMA",
+    `${file} has schema ${found}, newer than this catherd (${current})`,
+    {
+      fix: `upgrade catherd: ${UPGRADE}`,
+    },
+  );
+}
+
+/**
+ * The parsed content of a JSON file catherd keeps. The error never carries the parser's message: it
+ * quotes the offending text, which for a key pasted into credentials.json is the key itself (audit B1).
+ */
+export function readJsonFile(file: string, fix = `fix or delete ${file}`): unknown {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code ?? "an I/O error";
+    throw new CatherdError("E_CONFIG_INVALID", `${file} cannot be read (${code})`, { fix });
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CatherdError("E_CONFIG_INVALID", `${file} is not valid JSON`, { fix });
+  }
+}
+
+/**
+ * Reads a `"schema": n` JSON file. Schemas are loose objects, so unknown fields survive a rewrite.
+ * `fix` replaces the default fix of an unreadable or invalid file.
+ */
+export function readVersioned<T>(
+  file: string,
+  schema: z.ZodType<T>,
+  current: number,
+  o: { fix?: string } = {},
+): T {
+  const fix = o.fix ?? `fix or delete ${file}`;
+  const raw = readJsonFile(file, fix);
+  const found = (raw as { schema?: unknown } | null)?.schema;
+  if (typeof found === "number" && found > current) throw newer(file, found, current);
+  const r = schema.safeParse(raw);
+  if (!r.success)
+    throw new CatherdError("E_CONFIG_INVALID", `${file} is invalid:\n${z.prettifyError(r.error)}`, { fix });
+  return r.data;
+}
+
+/** True when `file` exists, is non-empty and does not end in a newline (a crash-truncated tail). */
+function endsMidLine(file: string): boolean {
+  let size: number;
+  try {
+    size = statSync(file).size;
+  } catch {
+    return false;
+  }
+  if (size === 0) return false;
+  const fd = openSync(file, "r");
+  try {
+    const last = Buffer.alloc(1);
+    readSync(fd, last, 0, 1, size - 1);
+    return last[0] !== 0x0a;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * One `appendFileSync` per row, so a crash can only ever truncate the last line. A truncated
+ * tail left by an earlier crash is ended first, in the same write, so the new row stays whole.
+ */
+export function appendJsonl(file: string, value: unknown): void {
+  ensurePrivateDir(dirname(file));
+  const prefix = endsMidLine(file) ? "\n" : "";
+  appendPrivate(file, `${prefix}${JSON.stringify(value)}\n`);
+}
+
+const madePrivate = new Set<string>();
+/**
+ * Appends `text` to `file`, created 0600. `appendFileSync`'s mode only applies to a new file, so one
+ * an older catherd left open to others is tightened first, once per process.
+ */
+export function appendPrivate(file: string, text: string): void {
+  ensurePrivateDir(dirname(file));
+  if (!madePrivate.has(file)) {
+    makePrivate(file);
+    madePrivate.add(file);
+  }
+  appendFileSync(file, text, { mode: PRIVATE_FILE });
+}
+
+export function ensureJsonlHeader(file: string, kind: string): void {
+  ensurePrivateDir(dirname(file));
+  try {
+    // O_APPEND: a row another process appends between the create and this write is kept, not overwritten
+    const fd = openSync(file, "ax", PRIVATE_FILE);
+    try {
+      writeSync(fd, `${JSON.stringify({ schema: 1, kind })}\n`);
+    } finally {
+      closeSync(fd);
+    }
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+  }
+}
+
+const isHeader = (v: unknown): v is { schema: number; kind: string } =>
+  typeof v === "object" &&
+  v !== null &&
+  Object.keys(v).length === 2 &&
+  typeof (v as { schema?: unknown }).schema === "number" &&
+  typeof (v as { kind?: unknown }).kind === "string";
+
+/** The non-blank lines of `file`; none when it cannot be read (missing, or not written yet). */
+export function nonBlankLines(file: string): string[] {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  return text.split("\n").filter((l) => l.trim());
+}
+
+export function readJsonl<T>(file: string, current = 1): { kind: string | null; rows: T[]; corrupt: number } {
+  if (!existsSync(file)) return { kind: null, rows: [], corrupt: 0 };
+  const rows: T[] = [];
+  let kind: string | null = null;
+  let corrupt = 0;
+  const lines = readFileSync(file, "utf8").split("\n");
+  lines.forEach((line) => {
+    if (!line.trim()) return;
+    let v: unknown;
+    try {
+      v = JSON.parse(line);
+    } catch {
+      corrupt++;
+      return;
+    }
+    // the header is first unless another writer's row won the race to a new file (ensureJsonlHeader)
+    if (kind === null && isHeader(v)) {
+      if (v.schema > current) throw newer(file, v.schema, current);
+      kind = v.kind;
+      return;
+    }
+    rows.push(v as T);
+  });
+  return { kind, rows, corrupt };
+}