@tachikomagundam/abathur 0.1.0

package/dist/core/ids.js

@@ -0,0 +1,154 @@
+// Canonical fingerprints + id construction (plan todo 2, AC a).
+// Digest discipline mirrors hr/bench/manifest.py: sha256 over JSON with
+// recursively sorted keys and no whitespace, so two producers of the same
+// logical value always agree byte-for-byte.
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function encode(value, top) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return JSON.stringify(value);
+        case "number":
+            // JSON.stringify would silently map non-finite to null: a digest
+            // collision we refuse instead of trusting callers to pre-filter.
+            if (!Number.isFinite(value)) {
+                throw new TypeError(`canonicalJson: non-finite number ${String(value)}`);
+            }
+            return JSON.stringify(value);
+        case "undefined":
+            if (top)
+                throw new TypeError("canonicalJson: undefined has no canonical encoding");
+            return "null"; // JSON.stringify parity inside arrays; object props are dropped
+        case "function":
+        case "symbol":
+        case "bigint":
+            throw new TypeError(`canonicalJson: unsupported ${typeof value}`);
+        case "object": {
+            if (Array.isArray(value))
+                return `[${value.map((el) => encode(el, false)).join(",")}]`;
+            const proto = Object.getPrototypeOf(value);
+            if (proto !== Object.prototype && proto !== null) {
+                throw new TypeError("canonicalJson: only plain JSON objects are accepted (convert Date etc. first)");
+            }
+            const parts = [];
+            for (const key of Object.keys(value).sort()) {
+                const child = value[key];
+                if (child === undefined)
+                    continue;
+                parts.push(`${JSON.stringify(key)}:${encode(child, false)}`);
+            }
+            return `{${parts.join(",")}}`;
+        }
+    }
+    throw new TypeError(`canonicalJson: unsupported input of type ${typeof value}`);
+}
+/** Sorted-key, whitespace-free JSON — the canonical form every fingerprint hashes. */
+export function canonicalJson(value) {
+    return encode(value, true);
+}
+export function fingerprint(value) {
+    return sha256Hex(canonicalJson(value));
+}
+/**
+ * Content-only tree digest: sha256 over [{path, sha256(content)}] sorted by
+ * path. Modes/mtimes/ownership are excluded BY CONSTRUCTION (never read), so
+ * clone, checkout and chmod can never change the digest — only bytes can.
+ */
+export function fileTreeDigest(files) {
+    const seen = new Set();
+    const rows = [];
+    for (const { path: filePath, content } of files) {
+        if (seen.has(filePath))
+            throw new Error(`fileTreeDigest: duplicate path '${filePath}'`);
+        seen.add(filePath);
+        rows.push({ path: filePath, sha256: sha256Hex(content) });
+    }
+    rows.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return sha256Hex(canonicalJson(rows));
+}
+/** Regular files only (symlinks/dirs excluded), forward-slash paths relative to root. */
+export function walkTree(root) {
+    const out = [];
+    const visit = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                visit(full);
+            else if (entry.isFile()) {
+                out.push({
+                    path: path.relative(root, full).split(path.sep).join("/"),
+                    content: readFileSync(full),
+                });
+            }
+        }
+    };
+    visit(root);
+    out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return out;
+}
+export function treeDigestAt(root) {
+    return fileTreeDigest(walkTree(root));
+}
+/** Compact path-safe UTC stamp: 2026-09-09T14:25:30.000Z -> 20260909T142530Z. */
+export function compactUtc(at) {
+    return at.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+}
+/** Generation id: g-<ulctime>-<first8 of the generation content fingerprint>. */
+export function genId(contentFingerprint, at) {
+    if (contentFingerprint.length === 0) {
+        throw new TypeError("genId: fingerprint seed must be a non-empty string");
+    }
+    return `g-${compactUtc(at ?? new Date())}-${contentFingerprint.slice(0, 8)}`;
+}
+/** Run id: r-<genId>-<unitId>-<repIdx> — one benchmark repeat of one unit. */
+export function runId(genId, unitId, repIdx) {
+    if (genId.length === 0)
+        throw new TypeError("runId: genId must be non-empty");
+    if (unitId.length === 0)
+        throw new TypeError("runId: unitId must be non-empty");
+    if (!Number.isInteger(repIdx) || repIdx < 0) {
+        throw new TypeError(`runId: repIdx must be an integer >= 0, got ${String(repIdx)}`);
+    }
+    return `r-${genId}-${unitId}-${repIdx}`;
+}
+/**
+ * Version of the BenchAdapter interface contract (todo 5 `src/bench/adapter.ts`:
+ * reset/seed/run/score + RunResult/ScoreOutcome shapes). The todo 5 toy adapter and
+ * todo 6 fixture adapter both implement this iface; any breaking change to that
+ * surface must bump this constant so benchDigest values stop comparing across
+ * incompatible adapter generations.
+ */
+export const ADAPTER_IFACE_VERSION = "abathur-bench-adapter-v1";
+function sha256Of(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+/**
+ * Deterministic bench-configuration digest: sha256 over canonical JSON of the
+ * unit list (sorted by unitId), script contents (sorted by path), the command
+ * templates, models, timeout and the adapter iface version. Reordering units or
+ * scripts never moves it; any content or config change always does.
+ */
+export function benchDigest(input) {
+    return fingerprint({
+        adapterIface: ADAPTER_IFACE_VERSION,
+        agentModel: input.agentModel ?? null,
+        graderCommand: input.graderCommand,
+        judgeCommand: input.judgeCommand ?? null,
+        judgeModel: input.judgeModel ?? null,
+        runCommand: input.runCommand,
+        scripts: [...input.scripts]
+            .sort((a, b) => (a.path < b.path ? -1 : 1))
+            .map((s) => ({ path: s.path, sha256: sha256Of(s.content) })),
+        timeoutS: input.timeoutS,
+        units: [...input.units]
+            .sort((a, b) => (a.unitId < b.unitId ? -1 : 1))
+            .map((u) => ({ unitId: u.unitId, sha256: sha256Of(u.content) })),
+    });
+}

package/dist/core/incumbent.js

@@ -0,0 +1,46 @@
+// Fast-forward-only incumbent promotion (todo 3 helper; todo 10 consumes it).
+// The ref may only move FORWARD: `update-ref <ref> <new> <old>` compare-and-swap
+// refuses a rewind or a concurrent move by exiting non-zero — abathur never
+// rewrites history and never updates a ref while the branch is checked out.
+import path from "node:path";
+import { blocked } from "../exit.js";
+import { tryGit } from "../util/git.js";
+import { gitOpts, requireSha } from "./genome-paths.js";
+/** Promotion branch — moved by fast-forward CAS only (todo 10), created if absent. */
+export const INCUMBENT_BRANCH = "abathur/incumbent";
+/**
+ * Move INCUMBENT_BRANCH to `commitSha` iff it is a descendant of the current
+ * tip (or the branch is absent and gets created). A no-op when already there.
+ */
+export async function fastForwardIncumbent(genome, commitSha, opts = {}) {
+    const sha = requireSha(commitSha);
+    const gopts = gitOpts(opts, path.resolve(genome.repoPath));
+    const current = await tryGit(["symbolic-ref", "--short", "-q", "HEAD"], gopts);
+    if (current.ok && current.stdout.trim() === INCUMBENT_BRANCH) {
+        blocked(`worktree: ${INCUMBENT_BRANCH} is checked out in ${gopts.cwd} — promotion needs it idle`, "switch the genome repo to another branch before promoting");
+    }
+    const ref = `refs/heads/${INCUMBENT_BRANCH}`;
+    const existing = await tryGit(["rev-parse", "--verify", "-q", ref], gopts);
+    if (!existing.ok) {
+        const created = await tryGit(["branch", INCUMBENT_BRANCH, sha], gopts);
+        if (!created.ok) {
+            const why = created.error.stderr.trim().split("\n")[0] ?? created.error.message;
+            blocked(`worktree: cannot create ${INCUMBENT_BRANCH} at ${sha}: ${why}`, "is the commit reachable in the genome repo?");
+        }
+        return { branch: INCUMBENT_BRANCH, fromSha: null, toSha: sha };
+    }
+    const fromSha = existing.stdout.trim();
+    if (fromSha === sha)
+        return { branch: INCUMBENT_BRANCH, fromSha, toSha: sha };
+    const ancestor = await tryGit(["merge-base", "--is-ancestor", fromSha, sha], gopts);
+    if (!ancestor.ok) {
+        blocked(`worktree: ${INCUMBENT_BRANCH} (${fromSha.slice(0, 12)}) is not an ancestor of ${sha} — only fast-forward moves are allowed`, "point the promotion at a descendant of the current incumbent");
+    }
+    // CAS: the old-value argument makes this a pure fast-forward — if the ref
+    // moved concurrently, update-ref exits non-zero instead of clobbering it.
+    const moved = await tryGit(["update-ref", ref, sha, fromSha], gopts);
+    if (!moved.ok) {
+        blocked(`worktree: ${INCUMBENT_BRANCH} moved concurrently (expected ${fromSha}) — rerun the promotion`);
+    }
+    return { branch: INCUMBENT_BRANCH, fromSha, toSha: sha };
+}

package/dist/core/kernel.js

@@ -0,0 +1,112 @@
+// Kernel manifest (todo 4): sha256 seal of every working-tree file matching the
+// genome's immutableGlobs, stored out-of-tree at <configDir>/kernels/<fp16>.json.
+// This module is READ-ONLY by design — resealing belongs exclusively to promote
+// (todo 10): the oracle Critical #2 rule that tampering can never be laundered by
+// a plain re-add. auditKernel() is the reuse seam for todos 9/10.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { cannotAnswer } from "../exit.js";
+import { compileGlob, listFiles } from "./glob.js";
+import { effectiveRepoPath, errorText } from "./spec.js";
+export const manifestEntrySchema = z.strictObject({
+    glob: z.string().min(1),
+    /** Repo-root-relative POSIX path. */
+    path: z.string().min(1),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/, "expected 64-char lowercase sha256 hex"),
+});
+const manifestFileSchema = z.strictObject({ entries: z.array(manifestEntrySchema) });
+export function kernelsDirOf(configDir) {
+    return path.join(configDir, "kernels");
+}
+export function manifestPathFor(configDir, fingerprint16) {
+    return path.join(kernelsDirOf(configDir), `${fingerprint16}.json`);
+}
+function sha256File(absPath) {
+    return createHash("sha256").update(readFileSync(absPath)).digest("hex");
+}
+/**
+ * One entry per sealed file; `glob` attributes the FIRST matching pattern in
+ * declaration order (spec fingerprint pins that order, so bytes are stable per
+ * fingerprint). listFiles() is sorted ⇒ entries are sorted by path.
+ */
+export function buildManifest(repoRoot, globs) {
+    const matchers = globs.map((glob) => ({ glob, re: compileGlob(glob) }));
+    const entries = [];
+    for (const rel of listFiles(repoRoot)) {
+        const hit = matchers.find((matcher) => matcher.re.test(rel));
+        if (hit !== undefined) {
+            entries.push({ glob: hit.glob, path: rel, sha256: sha256File(path.join(repoRoot, rel)) });
+        }
+    }
+    return entries;
+}
+/** Deterministic manifest bytes: key order fixed by the type, entries sorted by path. */
+export function serializeManifest(entries) {
+    const sorted = [...entries].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return `${JSON.stringify({ entries: sorted })}\n`;
+}
+/** Parse stored manifest text; throws a plain Error (callers map to exit codes). */
+export function parseManifestText(text, origin) {
+    let document;
+    try {
+        document = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new Error(`malformed kernel manifest in ${origin}: ${errorText(cause)}`);
+    }
+    const result = manifestFileSchema.safeParse(document);
+    if (!result.success) {
+        throw new Error(`kernel manifest rejected in ${origin}: ${result.error.issues[0]?.message ?? "schema"}`);
+    }
+    return result.data.entries;
+}
+export function readManifestFile(filePath) {
+    let text;
+    try {
+        text = readFileSync(filePath, "utf8");
+    }
+    catch {
+        throw new Error(`kernel manifest is missing: ${filePath}`);
+    }
+    return parseManifestText(text, filePath);
+}
+/** Set-diff of two manifests → deterministic drift list (sorted by path, then kind). */
+export function compareManifest(saved, fresh) {
+    const savedByPath = new Map(saved.map((entry) => [entry.path, entry]));
+    const freshByPath = new Map(fresh.map((entry) => [entry.path, entry]));
+    const drifted = [];
+    for (const [entryPath, entry] of savedByPath) {
+        const now = freshByPath.get(entryPath);
+        if (now === undefined)
+            drifted.push({ path: entryPath, kind: "missing", glob: entry.glob });
+        else if (now.sha256 !== entry.sha256) {
+            drifted.push({ path: entryPath, kind: "modified", glob: entry.glob });
+        }
+    }
+    for (const [entryPath, entry] of freshByPath) {
+        if (!savedByPath.has(entryPath)) {
+            drifted.push({ path: entryPath, kind: "added", glob: entry.glob });
+        }
+    }
+    return drifted.sort((a, b) => a.path.localeCompare(b.path) || a.kind.localeCompare(b.kind));
+}
+/**
+ * Re-seal the genome's repo in memory and diff against the stored manifest.
+ * Missing/corrupt manifest ⇒ exit 2 (cannot answer); any drift ⇒ ok:false with
+ * every affected file named — consumed by `kernel audit` now, todos 9/10 later.
+ */
+export function auditKernel(entry, configDir) {
+    const filePath = manifestPathFor(configDir, entry.fingerprint);
+    let saved;
+    try {
+        saved = readManifestFile(filePath);
+    }
+    catch (cause) {
+        return cannotAnswer(`kernel audit: ${errorText(cause)} — genome '${entry.spec.label}' (${entry.fingerprint})`);
+    }
+    const fresh = buildManifest(effectiveRepoPath(entry.spec.repoPath), entry.spec.kernel.immutableGlobs);
+    const drifted = compareManifest(saved, fresh);
+    return { ok: drifted.length === 0, drifted };
+}

package/dist/core/ledger.js

@@ -0,0 +1,198 @@
+// Append-only per-genome ledger + crash resume + friction queue (plan todo 2).
+// One JSONL file per genome at <genomeRepo>/.state/abathur/ledger.jsonl.
+// Discipline (border/README.md precedent): lines are only ever appended, never
+// rewritten or truncated — the sole exception is the corrupt-TAIL quarantine
+// at open, which MOVES the original bytes to ledger.corrupt-<ts> and keeps the
+// intact prefix byte-for-byte. Every read re-validates every line with zod;
+// mid-file corruption is an integrity error, never a silent skip.
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, writeSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { canonicalJson, compactUtc } from "./ids.js";
+import { acquireLock } from "./locks.js";
+export { acquireLock, lockDirFor } from "./locks.js";
+export const LEDGER_KIND_LOCK_TAKEOVER = "lock_takeover";
+export const LEDGER_KIND_GENERATION_COMPLETE = "generation_complete";
+export const ledgerRecordSchema = z.strictObject({
+    v: z.literal(1),
+    ts: z.string().min(1),
+    kind: z.string().min(1),
+    genId: z.string().min(1).optional(),
+    runId: z.string().min(1).optional(),
+    data: z.record(z.string(), z.unknown()),
+});
+export class LedgerError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "LedgerError";
+    }
+}
+export function ledgerPath(genomeRepo) {
+    return path.join(genomeRepo, ".state", "abathur", "ledger.jsonl");
+}
+function buildRecord(input, now) {
+    const candidate = {
+        v: 1,
+        ts: input.ts ?? now().toISOString(),
+        kind: input.kind,
+        data: input.data ?? {},
+    };
+    if (input.genId !== undefined)
+        candidate.genId = input.genId;
+    if (input.runId !== undefined)
+        candidate.runId = input.runId;
+    return ledgerRecordSchema.parse(candidate); // invalid input never reaches the file
+}
+/** ONE write() per record: fully serialized line, O_APPEND, partial-write loop is the only retry. */
+function appendSerialized(filePath, record) {
+    const bytes = Buffer.from(`${canonicalJson(record)}\n`, "utf8");
+    const fd = openSync(filePath, "a");
+    try {
+        let written = 0;
+        while (written < bytes.length)
+            written += writeSync(fd, bytes, written);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function parseLine(line, filePath, lineNo) {
+    let json;
+    try {
+        json = JSON.parse(line);
+    }
+    catch (error) {
+        throw new LedgerError("integrity", `${filePath}: line ${lineNo} is not valid JSON: ${error.message}`);
+    }
+    const parsed = ledgerRecordSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new LedgerError("integrity", `${filePath}: line ${lineNo} failed schema validation: ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+function validateCompleteLines(prefix, filePath) {
+    if (prefix.length === 0)
+        return [];
+    const lines = prefix.toString("utf8").split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    const records = [];
+    lines.forEach((line, index) => {
+        records.push(parseLine(line, filePath, index + 1));
+    });
+    return records;
+}
+/**
+ * Load + validate, repairing a crash-truncated tail first. A file not ending
+ * in \n means the last record died mid-write (the kernel only splits a single
+ * write() on signals, and SIGKILL between mkdir/append leaves byte-prefixed
+ * debris too). Repair keeps prior lines byte-identical: rename the original
+ * to <name>.corrupt-<ts> (full bytes preserved), then recreate the file with
+ * only the newline-terminated prefix.
+ */
+function loadValidated(filePath, now) {
+    let buf;
+    try {
+        buf = readFileSync(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const cut = buf.lastIndexOf(0x0a) + 1;
+    if (cut === buf.length)
+        return validateCompleteLines(buf, filePath);
+    const ext = path.extname(filePath);
+    const archive = path.join(path.dirname(filePath), `${path.basename(filePath, ext)}.corrupt-${compactUtc(now())}-${process.pid}${ext}`);
+    renameSync(filePath, archive);
+    writeFileSync(filePath, buf.subarray(0, cut));
+    return validateCompleteLines(buf.subarray(0, cut), filePath);
+}
+export class Ledger {
+    genomeRepo;
+    filePath;
+    now;
+    constructor(genomeRepo, filePath, now) {
+        this.genomeRepo = genomeRepo;
+        this.filePath = filePath;
+        this.now = now;
+    }
+    /** Opens, ensures the state dir, quarantines a corrupt tail and validates every line. */
+    static open(genomeRepo, opts = {}) {
+        const filePath = ledgerPath(genomeRepo);
+        mkdirSync(path.dirname(filePath), { recursive: true });
+        const ledger = new Ledger(genomeRepo, filePath, opts.now ?? (() => new Date()));
+        ledger.readAll();
+        return ledger;
+    }
+    append(input) {
+        const record = buildRecord(input, this.now);
+        appendSerialized(this.filePath, record);
+        return record;
+    }
+    readAll() {
+        return loadValidated(this.filePath, this.now);
+    }
+    /** Resume point for the evolution loop: genId of the last completed generation. */
+    lastCompleteGeneration() {
+        let last = null;
+        for (const record of this.readAll()) {
+            if (record.kind === LEDGER_KIND_GENERATION_COMPLETE && record.genId !== undefined) {
+                last = record.genId;
+            }
+        }
+        return last;
+    }
+}
+/**
+ * Single-flight per genome. The lock lives under config home keyed by the
+ * genome FINGERPRINT (not repo path) so parallel checkouts of the same genome
+ * still contend; a dead holder is replaced and the takeover is booked into
+ * the genome's own ledger before the lease is handed out.
+ */
+export function acquireGenomeLock(opts) {
+    const { ledger, configDir, genomeFp } = opts;
+    const lease = acquireLock({
+        configDir,
+        key: genomeFp,
+        label: "genome lock",
+        waitMs: opts.waitMs,
+        now: opts.now,
+    });
+    if (lease.tookOverFrom !== null) {
+        ledger.append({
+            kind: LEDGER_KIND_LOCK_TAKEOVER,
+            data: { lockKey: genomeFp, stalePid: lease.tookOverFrom.stalePid, takenOverByPid: process.pid },
+        });
+    }
+    return lease;
+}
+/** Global friction queue (todo 11 consumes): <configDir>/friction.jsonl. */
+export function frictionQueuePath(configDir) {
+    return path.join(configDir, "friction.jsonl");
+}
+/** Guarded by .locks/friction.lock; every genome can append without corrupting another's line. */
+export function appendFriction(configDir, input, opts = {}) {
+    const now = opts.now ?? (() => new Date());
+    const record = buildRecord(input, now);
+    const lease = acquireLock({
+        configDir,
+        key: "friction",
+        label: "friction lock",
+        waitMs: opts.waitMs ?? 15_000,
+        now,
+    });
+    try {
+        appendSerialized(frictionQueuePath(configDir), record);
+    }
+    finally {
+        lease.release();
+    }
+    return record;
+}
+export function readFriction(configDir) {
+    return loadValidated(frictionQueuePath(configDir), () => new Date());
+}

package/dist/core/locks.js

@@ -0,0 +1,172 @@
+// mkdir-atomic advisory locks (plan todo 2). Lives under CONFIG HOME
+// (<configDir>/.locks/<key>.lock) on purpose: keyed by genome fingerprint and
+// shared across clones/machine-local paths, so single-flight survives the
+// genome repo being cloned or moved.
+//
+// Protocol:
+//  - acquire = mkdirSync(lockDir) — exclusive at the kernel level; the winner
+//    immediately writes owner.json {pid, createdAt, label}.
+//  - EEXIST  = read owner.json and probe liveness via process.kill(pid, 0):
+//    ESRCH -> dead, EPERM -> alive (foreign user), success -> alive.
+//  - stale takeover uses renameSync(lockDir, <lockDir>.stale-<nonce>) rather
+//    than rm+mkdir: rename is atomic, so when two acquirers race to reclaim,
+//    exactly one succeeds and the loser re-runs acquisition against the
+//    freshly-mkdir'd winner. rm-then-mkdir would let both "win".
+//  - release removes the dir only while owner.json still names us, so a lease
+//    we no longer hold can never clobber a legitimate new holder.
+//
+//  - an unreadable owner.json alone does NOT prove staleness: a fresh holder
+//    is microseconds from writing it, so a lock younger than STALE_GRACE_MS
+//    (by dir mtime) is still honoured; only after the grace is a missing
+//    owner treated as "holder died between mkdir and owner-write". Without
+//    the grace, a racer can rename away a lock a live holder just created —
+//    caught by the two-writer friction test on the first run.
+// Remaining accepted race: Linux PID reuse can mislabel a dead holder as
+// live until the lock is manually cleared.
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { cannotAnswer } from "../exit.js";
+import { canonicalJson } from "./ids.js";
+const OWNER_FILE = "owner.json";
+export function lockDirFor(configDir, key) {
+    if (key.length === 0 || key.includes("/") || key.includes(path.sep) || key === "..") {
+        throw new TypeError(`lock key '${key}' is not a safe directory name`);
+    }
+    return path.join(configDir, ".locks", `${key}.lock`);
+}
+function readOwner(lockDir) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path.join(lockDir, OWNER_FILE), "utf8"));
+    }
+    catch {
+        return null; // absent or unparseable — see protocol note above
+    }
+    if (typeof raw.pid !== "number" || !Number.isInteger(raw.pid) || raw.pid <= 0)
+        return null;
+    return {
+        pid: raw.pid,
+        createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "unknown",
+        label: typeof raw.label === "string" ? raw.label : "unknown",
+    };
+}
+const STALE_GRACE_MS = 250;
+function lockDirIsFresh(lockDir) {
+    try {
+        return Date.now() - statSync(lockDir).mtimeMs < STALE_GRACE_MS;
+    }
+    catch {
+        return false; // dir vanished mid-observe; the next mkdir/rename resolves the race
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function writeOwner(lockDir, label, now) {
+    const owner = canonicalJson({ createdAt: now().toISOString(), label, pid: process.pid });
+    writeFileSync(path.join(lockDir, OWNER_FILE), `${owner}\n`, "utf8");
+}
+export function acquireLock(opts) {
+    const { configDir, key } = opts;
+    const lockDir = lockDirFor(configDir, key);
+    mkdirSync(path.dirname(lockDir), { recursive: true }); // the .locks/ parent, not the lock itself
+    const label = opts.label ?? "lock";
+    const now = opts.now ?? (() => new Date());
+    const deadline = Date.now() + (opts.waitMs ?? 0);
+    let takeovers = 0;
+    let reclaimed = null;
+    for (;;) {
+        try {
+            mkdirSync(lockDir);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const owner = readOwner(lockDir);
+            if (owner === null && lockDirIsFresh(lockDir)) {
+                sleepSync(2); // a live holder may be mid-owner-write; re-observe next pass
+                continue;
+            }
+            if (owner !== null && pidAlive(owner.pid)) {
+                reclaimed = null; // a fresh occupant took over: our old reclaim is not ours to book
+                if (Date.now() < deadline) {
+                    sleepSync(2);
+                    continue;
+                }
+                cannotAnswer(`${label} '${key}' is held by live pid ${owner.pid} (since ${owner.createdAt})`, `wait for it to finish; remove ${lockDir} only once that pid is gone`);
+            }
+            takeovers += 1;
+            if (takeovers > 8) {
+                cannotAnswer(`lock '${key}' is churn: 8 takeover races lost`, lockDir);
+            }
+            const quarantine = `${lockDir}.stale-${process.pid}-${randomUUID().slice(0, 8)}`;
+            try {
+                renameSync(lockDir, quarantine);
+            }
+            catch (race) {
+                reclaimed = null; // another taker won the rename — re-observe their lock normally
+                continue;
+            }
+            rmSync(quarantine, { recursive: true, force: true });
+            reclaimed = { stalePid: owner?.pid ?? null };
+            continue; // retry mkdir; if a competitor wins it, the claim check below resets us
+        }
+        // mkdir won. Claim, then PROVE the claim: a holder descheduled past the
+        // grace can have its brand-new dir stolen between mkdir and owner-write,
+        // so verify owner pid AND directory inode (rename+remkdir changes ino).
+        // A lost claim retries instead of silently double-holding the lock.
+        let wonInode;
+        try {
+            wonInode = statSync(lockDir).ino;
+        }
+        catch {
+            reclaimed = null;
+            continue; // dir renamed away before we could even claim it
+        }
+        try {
+            writeOwner(lockDir, label, now);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                reclaimed = null;
+                continue; // dir was renamed away mid-claim — re-observe
+            }
+            throw error;
+        }
+        const claim = readOwner(lockDir);
+        let dirInode;
+        try {
+            dirInode = statSync(lockDir).ino;
+        }
+        catch {
+            dirInode = null;
+        }
+        const ours = claim !== null && claim.pid === process.pid && dirInode === wonInode;
+        if (ours)
+            return makeLease(lockDir, key, reclaimed);
+        reclaimed = null;
+    }
+}
+function makeLease(lockDir, key, tookOverFrom) {
+    return {
+        lockDir,
+        key,
+        tookOverFrom,
+        release() {
+            const owner = readOwner(lockDir);
+            if (owner !== null && owner.pid === process.pid) {
+                rmSync(lockDir, { recursive: true, force: true });
+            }
+        },
+    };
+}