infinity-harness 2.0.0

package/src/core/gates.ts

@@ -0,0 +1,444 @@
+/**
+ * infinity-harness — deterministic gates.
+ *
+ * Gates are the referee. No agent marks its own work complete; a phase only
+ * advances when every check for that phase passes. Each check is a pure
+ * function of the project on disk, so the same tree always produces the same
+ * verdict — that determinism is what makes an unattended multi-day run safe.
+ *
+ * Checks that cannot run (no lint command configured, no upstream branch) are
+ * *advisory*: reported, but never a reason to fail. A gate that fails for a
+ * reason the agent cannot fix is a gate that deadlocks the loop.
+ */
+
+import { resolve } from "node:path";
+import { readdirSync, statSync } from "node:fs";
+import type { CheckResult, GateResult, HarnessConfig, Phase } from "./types.ts";
+import { loadConfig, saveConfig, recordGate } from "./config.ts";
+import { loadFeatureList, findTask, findFeature, computeProgress, isDone } from "./featureList.ts";
+import * as P from "./paths.ts";
+import { readText, fileExists } from "./fsx.ts";
+import {
+  run,
+  isGitRepo,
+  gitIsClean,
+  gitHasTag,
+  gitBehindUpstream,
+  gitHasUpstream,
+  LONG_TIMEOUT_MS,
+} from "./exec.ts";
+
+type Ctx = { targetDir: string; config: HarnessConfig };
+
+const pass = (name: string, detail: string): CheckResult => ({ name, pass: true, detail });
+const fail = (name: string, detail: string): CheckResult => ({ name, pass: false, detail });
+const skip = (name: string, detail: string): CheckResult => ({
+  name,
+  pass: true,
+  detail,
+  advisory: true,
+});
+
+// ── Individual checks ───────────────────────────────────────────────────────
+
+async function checkGitRepo({ targetDir }: Ctx): Promise<CheckResult> {
+  return (await isGitRepo(targetDir))
+    ? pass("git-repo", "inside a git work tree")
+    : fail("git-repo", "not a git repository — run `git init`");
+}
+
+async function checkConfigExists({ targetDir }: Ctx): Promise<CheckResult> {
+  return fileExists(P.configPath(targetDir))
+    ? pass("config-exists", "harness/config.json present")
+    : fail("config-exists", "harness/config.json is missing");
+}
+
+async function checkGitClean({ targetDir }: Ctx): Promise<CheckResult> {
+  return (await gitIsClean(targetDir))
+    ? pass("git-clean", "working tree clean")
+    : fail("git-clean", "uncommitted changes — commit or stash before advancing");
+}
+
+async function checkLint({ targetDir, config }: Ctx): Promise<CheckResult> {
+  const cmd = config.commands?.lint;
+  if (!cmd) return skip("lint", "no lint command configured (config.commands.lint)");
+  const r = await run(cmd, { cwd: targetDir, timeoutMs: LONG_TIMEOUT_MS });
+  if (r.timedOut) return fail("lint", `lint timed out after ${LONG_TIMEOUT_MS}ms`);
+  if (r.spawnError) return fail("lint", `lint could not start: ${r.spawnError}`);
+  return r.ok
+    ? pass("lint", "lint clean")
+    : fail("lint", firstLines(r.stderr || r.stdout, 6) || `lint exited ${r.code}`);
+}
+
+async function checkTests({ targetDir, config }: Ctx): Promise<CheckResult> {
+  const cmd = config.commands?.test;
+  if (!cmd) return skip("tests", "no test command configured (config.commands.test)");
+  const r = await run(cmd, { cwd: targetDir, timeoutMs: LONG_TIMEOUT_MS });
+  if (r.timedOut) return fail("tests", `tests timed out after ${LONG_TIMEOUT_MS}ms`);
+  if (r.spawnError) return fail("tests", `tests could not start: ${r.spawnError}`);
+  return r.ok
+    ? pass("tests", "tests pass")
+    : fail("tests", firstLines(r.stderr || r.stdout, 10) || `tests exited ${r.code}`);
+}
+
+async function checkCoverage({ targetDir, config }: Ctx): Promise<CheckResult> {
+  if (!config.gates?.coverage?.enabled) return skip("coverage", "coverage gate disabled");
+  const cmd = config.commands?.coverage;
+  if (!cmd) return skip("coverage", "no coverage command configured");
+  const threshold = config.gates.coverage.threshold ?? 80;
+  const r = await run(cmd, { cwd: targetDir, timeoutMs: LONG_TIMEOUT_MS });
+  if (r.timedOut) return fail("coverage", `coverage run timed out after ${LONG_TIMEOUT_MS}ms`);
+  if (r.spawnError) return fail("coverage", `coverage could not start: ${r.spawnError}`);
+  const pct = parseCoveragePercent(r.stdout + "\n" + r.stderr);
+  if (pct === null) {
+    return r.ok
+      ? skip("coverage", "coverage ran but no percentage could be parsed")
+      : fail("coverage", `coverage command exited ${r.code}`);
+  }
+  return pct >= threshold
+    ? pass("coverage", `${pct}% ≥ ${threshold}% threshold`)
+    : fail("coverage", `${pct}% is below the ${threshold}% threshold`);
+}
+
+/** Pull the highest "NN%"-looking number out of a coverage report. */
+export function parseCoveragePercent(text: string): number | null {
+  const matches = [...text.matchAll(/(\d{1,3}(?:\.\d+)?)\s*%/g)];
+  if (matches.length === 0) return null;
+  const nums = matches
+    .map((m) => Number.parseFloat(m[1]!))
+    .filter((n) => Number.isFinite(n) && n >= 0 && n <= 100);
+  if (nums.length === 0) return null;
+  // Coverage tools print several figures (lines/branches/functions). The
+  // "all files" total is normally the lowest of the set, so take the minimum
+  // rather than an optimistic maximum.
+  return Math.min(...nums);
+}
+
+const PLACEHOLDER_PATTERNS = [
+  /\bTODO\b\s*:?\s*implement/i,
+  /\bFIXME\b/,
+  /\bnot implemented\b/i,
+  /throw new Error\((["'`])(?:TODO|unimplemented|not implemented)/i,
+  /\bplaceholder\b/i,
+  /\bcoming soon\b/i,
+];
+
+const SCAN_EXTENSIONS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+  ".py", ".go", ".rs", ".rb", ".java", ".kt", ".swift", ".cs", ".php",
+]);
+
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", "out", "target", "vendor",
+  "coverage", ".next", ".venv", "venv", "__pycache__", "tmp", ".pi",
+]);
+
+function walkSource(dir: string, out: string[], depth = 0): void {
+  if (depth > 8 || out.length > 4000) return;
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (name.startsWith(".") && name !== ".") continue;
+    if (SKIP_DIRS.has(name)) continue;
+    const full = resolve(dir, name);
+    let st;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      walkSource(full, out, depth + 1);
+    } else if (SCAN_EXTENSIONS.has(name.slice(name.lastIndexOf(".")))) {
+      out.push(full);
+    }
+  }
+}
+
+async function checkNoPlaceholders({ targetDir, config }: Ctx): Promise<CheckResult> {
+  if (!config.gates?.antiPlaceholder?.enabled) {
+    return skip("anti-placeholder", "anti-placeholder gate disabled");
+  }
+  const extra = (config.gates.antiPlaceholder.patterns ?? [])
+    .map((p) => {
+      try {
+        return new RegExp(p, "i");
+      } catch {
+        return null;
+      }
+    })
+    .filter((r): r is RegExp => r !== null);
+  const patterns = [...PLACEHOLDER_PATTERNS, ...extra];
+
+  const files: string[] = [];
+  walkSource(targetDir, files);
+  const hits: string[] = [];
+  for (const f of files) {
+    const text = readText(f);
+    if (text === null) continue;
+    for (const p of patterns) {
+      if (p.test(text)) {
+        hits.push(f.replace(targetDir + "/", ""));
+        break;
+      }
+    }
+    if (hits.length >= 8) break;
+  }
+  return hits.length === 0
+    ? pass("anti-placeholder", `${files.length} source files, no placeholder markers`)
+    : fail("anti-placeholder", `placeholder markers in: ${hits.join(", ")}`);
+}
+
+function docCheck(name: string, path: string, minChars: number, hint: string): CheckResult {
+  const text = readText(path);
+  if (text === null) return fail(name, `${hint} is missing`);
+  const body = text.replace(/^#.*$/gm, "").trim();
+  return body.length >= minChars
+    ? pass(name, `${hint} present (${body.length} chars)`)
+    : fail(name, `${hint} exists but is essentially empty (${body.length} chars, need ${minChars})`);
+}
+
+async function checkReadme({ targetDir }: Ctx): Promise<CheckResult> {
+  return docCheck("readme", resolve(targetDir, "README.md"), 200, "README.md");
+}
+async function checkLicense({ targetDir }: Ctx): Promise<CheckResult> {
+  return fileExists(resolve(targetDir, "LICENSE")) || fileExists(resolve(targetDir, "LICENSE.md"))
+    ? pass("license", "LICENSE present")
+    : fail("license", "LICENSE is missing");
+}
+async function checkChangelog({ targetDir }: Ctx): Promise<CheckResult> {
+  return docCheck("changelog", resolve(targetDir, "CHANGELOG.md"), 100, "CHANGELOG.md");
+}
+async function checkArchitectureDoc({ targetDir }: Ctx): Promise<CheckResult> {
+  return docCheck("architecture-doc", P.architecturePath(targetDir), 200, "harness/docs/ARCHITECTURE.md");
+}
+async function checkDecisionsLogged({ targetDir }: Ctx): Promise<CheckResult> {
+  return docCheck("decisions-logged", P.decisionsPath(targetDir), 100, "harness/docs/DECISIONS.md");
+}
+async function checkRubricContent({ targetDir }: Ctx): Promise<CheckResult> {
+  return docCheck("rubric-content", P.rubricPath(targetDir), 100, "harness/evaluator-rubric.md");
+}
+
+async function checkTagged({ targetDir }: Ctx): Promise<CheckResult> {
+  return (await gitHasTag(targetDir))
+    ? pass("tagged", "HEAD carries a release tag")
+    : fail("tagged", "HEAD is not tagged — tag the release before shipping");
+}
+
+async function checkBranchUpToDate({ targetDir }: Ctx): Promise<CheckResult> {
+  if (!(await gitHasUpstream(targetDir))) {
+    return skip("branch-up-to-date", "no upstream configured");
+  }
+  const behind = await gitBehindUpstream(targetDir);
+  if (behind === null) return skip("branch-up-to-date", "could not compare against upstream");
+  return behind === 0
+    ? pass("branch-up-to-date", "level with upstream")
+    : fail("branch-up-to-date", `${behind} commit(s) behind upstream — pull first`);
+}
+
+async function checkNoEmptyDirs({ targetDir }: Ctx): Promise<CheckResult> {
+  const empties: string[] = [];
+  const walk = (dir: string, depth: number): void => {
+    if (depth > 6 || empties.length >= 5) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    const visible = entries.filter((e) => !SKIP_DIRS.has(e) && !e.startsWith("."));
+    if (visible.length === 0 && dir !== targetDir) {
+      empties.push(dir.replace(targetDir + "/", ""));
+      return;
+    }
+    for (const e of visible) {
+      const full = resolve(dir, e);
+      try {
+        if (statSync(full).isDirectory()) walk(full, depth + 1);
+      } catch {
+        /* unreadable */
+      }
+    }
+  };
+  walk(targetDir, 0);
+  return empties.length === 0
+    ? pass("no-empty-dirs", "no empty directories")
+    : fail("no-empty-dirs", `empty directories: ${empties.join(", ")}`);
+}
+
+/** Every feature must declare acceptance criteria before BUILD starts. */
+async function checkFeatureCriteria({ targetDir }: Ctx): Promise<CheckResult> {
+  const { list } = loadFeatureList(targetDir);
+  const features = list.features ?? [];
+  if (features.length === 0) return fail("feature-criteria", "no features planned yet");
+  const missing = features.filter((f) => !(f.criteria ?? []).length).map((f) => f.id);
+  return missing.length === 0
+    ? pass("feature-criteria", `${features.length} feature(s) have criteria`)
+    : fail("feature-criteria", `features without criteria: ${missing.join(", ")}`);
+}
+
+/** Every task in the plan must be complete before the phase gate opens. */
+async function checkTasksComplete({ targetDir }: Ctx): Promise<CheckResult> {
+  const { list } = loadFeatureList(targetDir);
+  const p = computeProgress(list);
+  if (p.tasksTotal === 0) return fail("tasks-complete", "no tasks planned");
+  if (p.tasksDone === p.tasksTotal) return pass("tasks-complete", `${p.tasksDone}/${p.tasksTotal} tasks complete`);
+  const remaining = p.tasksTotal - p.tasksDone;
+  return fail(
+    "tasks-complete",
+    `${remaining} task(s) still open (${p.blocked} blocked, ${p.inProgress} in progress, ${p.rework} rework)`,
+  );
+}
+
+function firstLines(s: string, n: number): string {
+  return s.split("\n").slice(0, n).join("\n").trim();
+}
+
+// ── Phase → checks ──────────────────────────────────────────────────────────
+
+type Check = (ctx: Ctx) => Promise<CheckResult>;
+
+const PHASE_CHECKS: Record<Phase, Check[]> = {
+  init: [checkGitRepo, checkConfigExists],
+  define: [checkFeatureCriteria],
+  plan: [checkFeatureCriteria, checkTasksPlanned],
+  build: [checkLint, checkTests, checkCoverage, checkNoPlaceholders, checkTasksComplete],
+  verify: [checkTests, checkCoverage, checkGitClean],
+  simplify: [checkTests, checkNoEmptyDirs, checkGitClean],
+  review: [checkBranchUpToDate, checkRubricContent, checkReadme, checkArchitectureDoc, checkDecisionsLogged],
+  ship: [
+    checkGitClean,
+    checkTagged,
+    checkChangelog,
+    checkReadme,
+    checkLicense,
+    checkNoEmptyDirs,
+    checkNoPlaceholders,
+  ],
+};
+
+async function checkTasksPlanned({ targetDir }: Ctx): Promise<CheckResult> {
+  const { list } = loadFeatureList(targetDir);
+  const total = (list.features ?? []).reduce((n, f) => n + (f.tasks ?? []).length, 0);
+  return total > 0
+    ? pass("tasks-planned", `${total} task(s) planned`)
+    : fail("tasks-planned", "no tasks planned — PLAN must produce a task list");
+}
+
+/** Checks that are meaningful for a single task rather than a whole phase. */
+const TASK_SCOPED = new Set(["lint", "tests", "coverage"]);
+
+export function getPhaseCheckNames(phase: Phase): string[] {
+  return (PHASE_CHECKS[phase] ?? []).map((fn) => fn.name.replace(/^check/, "").toLowerCase());
+}
+
+// ── Runner ──────────────────────────────────────────────────────────────────
+
+export type RunChecksOptions = {
+  feature?: string;
+  task?: string;
+  /** Persist the verdict to gateHistory. Read-only callers pass false. */
+  record?: boolean;
+};
+
+/**
+ * Run the checks for `phase`.
+ *
+ * With `feature` + `task` set, only task-scoped checks run plus that task's
+ * own acceptance criteria — validating one task must not demand that the
+ * whole phase is finished.
+ */
+export async function runChecks(
+  targetDir: string,
+  phase: Phase | null,
+  options: RunChecksOptions = {},
+): Promise<GateResult> {
+  const { config } = loadConfig(targetDir);
+
+  if (!phase) {
+    return { phase: "none", checks: [], overall: false, failures: ["no-phase"] };
+  }
+  if (config.gates?.enabled === false) {
+    return {
+      phase,
+      checks: [skip("gates-disabled", "gates are disabled in config — nothing enforced")],
+      overall: true,
+      failures: [],
+    };
+  }
+
+  const ctx: Ctx = { targetDir, config };
+  const isTaskScoped = Boolean(options.feature && options.task);
+
+  let checks = PHASE_CHECKS[phase] ?? [];
+  if (isTaskScoped) {
+    checks = checks.filter((fn) => TASK_SCOPED.has(fn.name.replace(/^check/, "").toLowerCase()));
+  }
+
+  const results: CheckResult[] = [];
+  for (const fn of checks) {
+    try {
+      results.push(await fn(ctx));
+    } catch (e) {
+      results.push(fail(fn.name, `check threw: ${e instanceof Error ? e.message : String(e)}`));
+    }
+  }
+
+  if (isTaskScoped) {
+    results.push(checkTaskCriteria(targetDir, options.feature!, options.task!));
+  }
+
+  const failures = results.filter((r) => !r.pass).map((r) => r.name);
+  const result: GateResult = {
+    phase,
+    checks: results,
+    overall: failures.length === 0,
+    failures,
+    ...(options.feature ? { feature: options.feature } : {}),
+    ...(options.task ? { task: options.task } : {}),
+  };
+
+  if (options.record !== false) {
+    try {
+      const fresh = loadConfig(targetDir);
+      if (fresh.ok) {
+        recordGate(fresh.config, phase, result.overall ? "pass" : "fail", {
+          feature: options.feature,
+          task: options.task,
+        });
+        saveConfig(targetDir, fresh.config);
+      }
+    } catch {
+      /* gate history is best-effort and must never break validation */
+    }
+  }
+
+  return result;
+}
+
+/** A task passes when it is marked complete and every subtask is complete. */
+export function checkTaskCriteria(targetDir: string, featureId: string, taskId: string): CheckResult {
+  const { list } = loadFeatureList(targetDir);
+  const feature = findFeature(list, featureId);
+  if (!feature) return fail("task-criteria", `unknown feature ${featureId}`);
+  const found = findTask(list, taskId);
+  if (!found) return fail("task-criteria", `unknown task ${taskId}`);
+  const { task } = found;
+  const openSubtasks = (task.subtasks ?? []).filter((s) => s.status !== "complete");
+  if (openSubtasks.length > 0) {
+    return fail("task-criteria", `${openSubtasks.length} subtask(s) still open on ${taskId}`);
+  }
+  if (!isDone(task.status)) {
+    return fail("task-criteria", `${taskId} is "${task.status}", not complete`);
+  }
+  return pass("task-criteria", `${taskId} complete with all subtasks done`);
+}
+
+export function areGatesEnabled(targetDir: string): boolean {
+  const { config } = loadConfig(targetDir);
+  return config.gates?.enabled !== false;
+}

package/src/core/lock.ts

@@ -0,0 +1,192 @@
+/**
+ * infinity-harness — cross-process file locking.
+ *
+ * Parallel workers all write the same plan file. Without mutual exclusion,
+ * two writers that both read revision N both pass the `baseRevision` check and
+ * both write N+1 — one set of edits vanishes. `baseRevision` detects a stale
+ * *read*; it cannot serialise a read-modify-write. Only a lock can.
+ *
+ * Two flavours, deliberately:
+ *
+ *   - `withLockSync` wraps the plan's read-apply-write in one atomic section.
+ *     It is synchronous because the critical section is, and it **fails
+ *     closed**: if the lock cannot be taken, the write is refused rather than
+ *     racing. Losing an edit silently is worse than an error the caller can
+ *     retry.
+ *   - `withLock` is the async, best-effort variant for coarse advisory
+ *     locking where proceeding un-locked is acceptable.
+ *
+ * Both hold the lock only for the duration of the work, never across a turn.
+ * An earlier version took a lock at the start of an agent turn with an
+ * 8-second staleness timeout, so every turn longer than 8 seconds left a lock
+ * another process was entitled to steal.
+ */
+
+import { dirname } from "node:path";
+import { mkdirSync, rmdirSync, statSync, writeFileSync, unlinkSync, readdirSync } from "node:fs";
+import { ensureDir, fileExists, writeTextAtomic } from "./fsx.ts";
+
+export type LockHandle = { release: () => Promise<void> };
+
+/** A lock held longer than this is assumed to belong to a dead process. */
+export const STALE_MS = 30_000;
+export const RETRIES = 12;
+export const RETRY_MIN_MS = 20;
+/** Total time `withLockSync` will wait before refusing. */
+export const SYNC_LOCK_TIMEOUT_MS = 10_000;
+
+export class LockTimeoutError extends Error {
+  override readonly name = "LockTimeoutError";
+  constructor(path: string, waitedMs: number) {
+    super(
+      `could not lock ${path} after ${waitedMs}ms — another process is holding it. ` +
+        `Retry; if this persists, remove ${path}.ilock`,
+    );
+    Object.setPrototypeOf(this, LockTimeoutError.prototype);
+  }
+}
+
+// ── Synchronous lock ────────────────────────────────────────────────────────
+
+/**
+ * Lock directory name.
+ *
+ * Deliberately NOT `<path>.lock` — that is exactly what `proper-lockfile`
+ * uses, and it is a directory there too. Sharing the name means a caller that
+ * wraps `withLock` around something that calls `withLockSync` deadlocks
+ * against itself: it holds the async lock, then blocks the event loop waiting
+ * for the same directory it already owns, until the timeout fires. Distinct
+ * names make nesting the two merely redundant instead of fatal.
+ */
+function lockDirFor(path: string): string {
+  return `${path}.ilock`;
+}
+
+/**
+ * Block the current thread for `ms`.
+ *
+ * `Atomics.wait` on a never-notified buffer is the only real synchronous sleep
+ * in Node. Busy-waiting on `Date.now()` would spin a core, and the critical
+ * sections here are short enough that blocking is the right trade.
+ */
+function sleepSync(ms: number): void {
+  const shared = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(shared, 0, 0, ms);
+}
+
+function isStale(lockDir: string): boolean {
+  try {
+    return Date.now() - statSync(lockDir).mtimeMs > STALE_MS;
+  } catch {
+    // Vanished between the EEXIST and the stat — treat as free.
+    return true;
+  }
+}
+
+function breakStaleLock(lockDir: string): void {
+  try {
+    for (const entry of readdirSync(lockDir)) {
+      try {
+        unlinkSync(`${lockDir}/${entry}`);
+      } catch {
+        /* best effort */
+      }
+    }
+    rmdirSync(lockDir);
+  } catch {
+    // Another process broke it first, or it is no longer stale. Either way the
+    // next acquire attempt settles it.
+  }
+}
+
+/**
+ * Run `fn` while holding an exclusive lock on `path`.
+ *
+ * `mkdir` is the primitive: it either creates the directory or fails with
+ * EEXIST, atomically, on every filesystem we care about — unlike a
+ * check-then-create on a lock *file*, which has the same race we are trying to
+ * close.
+ *
+ * @throws LockTimeoutError when the lock cannot be acquired in time.
+ */
+export function withLockSync<T>(path: string, fn: () => T, timeoutMs = SYNC_LOCK_TIMEOUT_MS): T {
+  const lockDir = lockDirFor(path);
+  ensureDir(dirname(path));
+
+  const deadline = Date.now() + timeoutMs;
+  let acquired = false;
+  let backoff = RETRY_MIN_MS;
+
+  while (!acquired) {
+    try {
+      mkdirSync(lockDir);
+      acquired = true;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+      if (isStale(lockDir)) {
+        breakStaleLock(lockDir);
+        continue;
+      }
+      if (Date.now() >= deadline) throw new LockTimeoutError(path, timeoutMs);
+      sleepSync(Math.min(backoff, 250));
+      backoff = Math.min(backoff * 2, 250);
+    }
+  }
+
+  try {
+    // Owner marker: purely diagnostic, so a stuck lock names a pid.
+    try {
+      writeFileSync(`${lockDir}/owner`, `${process.pid}\n`, "utf-8");
+    } catch {
+      /* the directory is the lock; the marker is a nicety */
+    }
+    return fn();
+  } finally {
+    breakStaleLock(lockDir);
+  }
+}
+
+// ── Asynchronous, best-effort lock ──────────────────────────────────────────
+
+/**
+ * Run `fn` while holding an advisory lock on `path`.
+ *
+ * Best-effort by design: if the lock cannot be acquired, `fn` still runs and
+ * `locked` reports false. Use this only where an interleave is tolerable —
+ * never for a read-modify-write. Plan writes use `withLockSync`.
+ */
+export async function withLock<T>(
+  path: string,
+  fn: () => Promise<T> | T,
+): Promise<{ value: T; locked: boolean }> {
+  const handle = await acquire(path);
+  try {
+    const value = await fn();
+    return { value, locked: handle !== null };
+  } finally {
+    if (handle) {
+      try {
+        await handle.release();
+      } catch {
+        /* the lock times out on its own */
+      }
+    }
+  }
+}
+
+async function acquire(path: string): Promise<LockHandle | null> {
+  try {
+    ensureDir(dirname(path));
+    // proper-lockfile refuses to lock a path that does not exist.
+    if (!fileExists(path)) writeTextAtomic(path, "");
+    const lockfile = await import("proper-lockfile");
+    const release = await lockfile.lock(path, {
+      retries: { retries: RETRIES, minTimeout: RETRY_MIN_MS, maxTimeout: 500, factor: 1.6 },
+      stale: STALE_MS,
+      realpath: false,
+    });
+    return { release: async () => release() };
+  } catch {
+    return null;
+  }
+}