iterate-plugin 3.5.7 → 3.6.0

package/dist/config-write.js

@@ -13,22 +13,52 @@ import { copyFileSync, existsSync, readFileSync, readdirSync, rmSync } from 'nod
 import { basename, dirname, join } from 'node:path';
 import yaml from 'js-yaml';
 import { writeTextAtomic } from "./atomic-fs.js";
+import { MAX_ATOMIC_MAX_LINES, MAX_MAX_ADJACENT_METHODS, MAX_MAX_ROUNDS, MAX_SCOPE_CHUNK_SIZE, SUPPORTED_CONFIG_KEYS, } from "./config-loader.js";
+export { MAX_ATOMIC_MAX_LINES, MAX_MAX_ADJACENT_METHODS, MAX_MAX_ROUNDS, MAX_SCOPE_CHUNK_SIZE, };
 /** Config file name (must match config-loader). */
 export const CONFIG_FILE = 'iterate.config.yaml';
-/** Backup suffix helper (filesystem-safe timestamp). */
+/**
+ * Monotonic collision guard for {@link configBackupSuffix}: two writes in the
+ * SAME millisecond used to build the identical `config.bak-<iso>` path, so the
+ * second backup overwrote the first and one snapshot was silently lost.
+ * Only ever moves forward (a clock stepping backwards also counts as a
+ * collision), so every suffix issued by this process is unique.
+ */
+let lastSuffixMs = -1;
+let suffixSequence = 0;
+/**
+ * Backup suffix helper (filesystem-safe timestamp + monotonic disambiguator).
+ * The ISO timestamp is kept verbatim when the millisecond is fresh (existing
+ * `config.bak-…` names sort chronologically); repeats within the same
+ * millisecond get `-1`, `-2`, … appended so the backup path never collides.
+ */
 export function configBackupSuffix(now = new Date()) {
-    return now.toISOString().replace(/[:.]/g, '-');
+    const ms = now.getTime();
+    if (ms > lastSuffixMs) {
+        lastSuffixMs = ms;
+        suffixSequence = 0;
+    }
+    else {
+        suffixSequence += 1;
+    }
+    const base = now.toISOString().replace(/[:.]/g, '-');
+    return suffixSequence === 0 ? base : `${base}-${suffixSequence}`;
 }
-/** Upper bound on configurable iteration rounds (config bomb guard). */
-export const MAX_MAX_ROUNDS = 100;
-/** Upper bound on `atomic.max_lines` (a single fix never needs more). */
-export const MAX_ATOMIC_MAX_LINES = 10_000;
-/** Upper bound on `atomic.max_adjacent_methods`. */
-export const MAX_MAX_ADJACENT_METHODS = 200;
-/** Upper bound on `reviewer.scope_chunk_size` (files per reviewer task batch). */
-export const MAX_SCOPE_CHUNK_SIZE = 1000;
 /** Keep at most this many timestamped config backups (older ones are removed). */
 export const MAX_CONFIG_BACKUPS = 5;
+/**
+ * Top-level keys `iterate_config` accepts in `updates`.
+ *
+ * The write path MERGES updates into the file, so an unrecognized key used to
+ * be persisted verbatim: a typo (`maxRounds`) or a hallucinated field
+ * (`task_modes`) silently became part of the project's config, survived every
+ * later read, and was never consumed by anything. Rejecting unknown keys turns
+ * that silent no-op into a structured error the model can correct.
+ *
+ * Defined once in config-loader (shared with `validateConfig`) and re-exported
+ * here under its write-path name.
+ */
+export const SUPPORTED_UPDATE_KEYS = SUPPORTED_CONFIG_KEYS;
 /**
  * Bound the timestamped config backups: after a fresh one is written, delete
  * every older `config.bak-*` file beyond the newest `keep`. Best-effort — a
@@ -63,6 +93,13 @@ export function validateConfigUpdates(updates) {
     if (!updates || typeof updates !== 'object' || Array.isArray(updates)) {
         return ['updates must be a JSON object'];
     }
+    // Unknown top-level keys are refused rather than merged into the file
+    // (see SUPPORTED_UPDATE_KEYS for why a typo used to persist forever).
+    for (const key of Object.keys(updates)) {
+        if (!SUPPORTED_UPDATE_KEYS.includes(key)) {
+            errors.push(`updates.${key} is not a supported config key (supported: ${SUPPORTED_UPDATE_KEYS.join(', ')})`);
+        }
+    }
     if ('goal' in updates && typeof updates.goal !== 'string') {
         errors.push('updates.goal must be a string');
     }
@@ -70,8 +107,12 @@ export function validateConfigUpdates(updates) {
         errors.push('updates.language must be "zh" or "en"');
     }
     if ('dimensions' in updates) {
-        if (!Array.isArray(updates.dimensions) || updates.dimensions.some((d) => typeof d !== 'string' || d.trim().length === 0)) {
-            errors.push('updates.dimensions must be an array of non-empty strings');
+        // `.some` on an EMPTY array is false, so `dimensions: []` used to validate
+        // clean and then replace the whole dimension list with "review nothing".
+        if (!Array.isArray(updates.dimensions) ||
+            updates.dimensions.length === 0 ||
+            updates.dimensions.some((d) => typeof d !== 'string' || d.trim().length === 0)) {
+            errors.push('updates.dimensions must be a non-empty array of non-empty strings');
         }
     }
     if ('max_rounds' in updates) {
@@ -90,7 +131,7 @@ export function validateConfigUpdates(updates) {
     }
     if ('reviewer' in updates) {
         const rv = updates.reviewer;
-        if (!rv || typeof rv !== 'object') {
+        if (!rv || typeof rv !== 'object' || Array.isArray(rv)) {
             errors.push('updates.reviewer must be an object');
         }
         else {
@@ -108,7 +149,7 @@ export function validateConfigUpdates(updates) {
     }
     if ('review' in updates) {
         const r = updates.review;
-        if (!r || typeof r !== 'object') {
+        if (!r || typeof r !== 'object' || Array.isArray(r)) {
             errors.push('updates.review must be an object');
         }
         else if (r.scope !== undefined && r.scope !== 'full' && r.scope !== 'changed-only') {
@@ -117,7 +158,7 @@ export function validateConfigUpdates(updates) {
     }
     if ('atomic' in updates) {
         const a = updates.atomic;
-        if (!a || typeof a !== 'object') {
+        if (!a || typeof a !== 'object' || Array.isArray(a)) {
             errors.push('updates.atomic must be an object');
         }
         else {
@@ -131,7 +172,7 @@ export function validateConfigUpdates(updates) {
     }
     if ('git' in updates) {
         const g = updates.git;
-        if (!g || typeof g !== 'object') {
+        if (!g || typeof g !== 'object' || Array.isArray(g)) {
             errors.push('updates.git must be an object');
         }
         else {
@@ -147,16 +188,34 @@ export function validateConfigUpdates(updates) {
     }
     if ('validation' in updates) {
         const v = updates.validation;
-        if (!v || typeof v !== 'object') {
+        if (!v || typeof v !== 'object' || Array.isArray(v)) {
             errors.push('updates.validation must be an object');
         }
-        else if ('commands' in v && v.commands !== undefined && typeof v.commands !== 'object') {
-            errors.push('updates.validation.commands must be an object of command arrays');
+        else {
+            if ('command_whitelist' in v && v.command_whitelist !== undefined) {
+                if (!Array.isArray(v.command_whitelist) || !v.command_whitelist.every((x) => typeof x === 'string')) {
+                    errors.push('updates.validation.command_whitelist must be an array of strings');
+                }
+            }
+            // `typeof [] === 'object'` let `commands: ["npm t"]` validate clean, and
+            // `flattenCommands` drops every non-object entry — the allow-list would
+            // read as configured while matching NOTHING. Require the real shape:
+            // a mapping of module → string[] (string keys, string-array values).
+            if ('commands' in v && v.commands !== undefined) {
+                const c = v.commands;
+                const shapeOk = typeof c === 'object' &&
+                    c !== null &&
+                    !Array.isArray(c) &&
+                    Object.entries(c).every(([, value]) => Array.isArray(value) && value.every((x) => typeof x === 'string'));
+                if (!shapeOk) {
+                    errors.push('updates.validation.commands must be a mapping of module → string[] (not an array)');
+                }
+            }
         }
     }
     if ('observatory' in updates) {
         const o = updates.observatory;
-        if (!o || typeof o !== 'object') {
+        if (!o || typeof o !== 'object' || Array.isArray(o)) {
             errors.push('updates.observatory must be an object');
         }
         else {
@@ -175,10 +234,12 @@ export function validateConfigUpdates(updates) {
             }
         }
     }
-    if ('personalization' in updates && (!updates.personalization || typeof updates.personalization !== 'object')) {
+    if ('personalization' in updates &&
+        (!updates.personalization || typeof updates.personalization !== 'object' || Array.isArray(updates.personalization))) {
         errors.push('updates.personalization must be an object');
     }
-    if ('onboarding' in updates && (!updates.onboarding || typeof updates.onboarding !== 'object')) {
+    if ('onboarding' in updates &&
+        (!updates.onboarding || typeof updates.onboarding !== 'object' || Array.isArray(updates.onboarding))) {
         errors.push('updates.onboarding must be an object');
     }
     return errors;

package/dist/evidence.js

@@ -8,8 +8,15 @@
  *
  * - a finding's `file` must resolve to an existing file under the project root
  *   (traversal-safe), otherwise evidence is poisoned (`file_not_found`);
- * - a finding with an explicit line must reference a line that actually exists
- *   in that file (`line_out_of_range`);
+ * - a finding with an explicit line must reference an INTEGER line that
+ *   actually exists in that file (`line_out_of_range`); a fractional line
+ *   (e.g. 42.5) can never anchor to real code and fails the gate, and so
+ *   does a PRESENT-but-non-numeric line (`"42"`, `true`) — only an absent or
+ *   null line keeps the whole-file semantics;
+ * - files that exist but cannot be line-addressed report a DISTINCT error:
+ *   `file_too_large` (over MAX_EVIDENCE_BYTES) or `binary_file` (NUL bytes),
+ *   so the meta-review can describe the actual reason instead of lumping
+ *   every non-addressable file into `line_out_of_range`;
  * - a whole-file finding (line 0 / undefined) must still reference an existing
  *   file, so even structural findings cannot point at nothing;
  * - `readVerified` is a best-effort, NON-gating hint: the plugin's reviewers are
@@ -33,6 +40,10 @@ export const WHOLE_FILE_LINE = 0;
  * treated as not line-addressable.
  */
 const MAX_EVIDENCE_BYTES = 10 * 1024 * 1024;
+/** Create an empty probe cache for `opts.cache`. */
+export function createEvidenceCache() {
+    return new Map();
+}
 /** Number of physical lines in `text`. A trailing newline does not add a line. */
 export function countLines(text) {
     if (text === '')
@@ -74,22 +85,84 @@ function safeRealpath(p) {
         return p;
     }
 }
+/**
+ * Pure decision: does `line` anchor to an existing line in a file with
+ * `lineTotal` lines? Shared by `verifyLineBounds` and the cached probe path
+ * (which has the line count but not the text).
+ */
+function lineInBounds(line, lineTotal) {
+    // Whole-file findings (undefined/null/0 = WHOLE_FILE_LINE) are always
+    // bounds-valid — semantics preserved from the original gate.
+    if (line === undefined || line === null || line === WHOLE_FILE_LINE)
+        return true;
+    // Only a positive INTEGER is a valid line anchor. A fractional line (e.g.
+    // 42.5 from a bypassed schema), NaN, ±Infinity or a negative value is out of
+    // bounds — a fractional line "within" the file would otherwise be accepted
+    // and poison the evidence trail with a location nothing can jump to.
+    if (line < 1 || !Number.isInteger(line))
+        return false;
+    return line <= lineTotal;
+}
 /**
  * Pure check that `line` (if anchored) exists in `text`.
  * Whole-file findings (undefined/0) are always bounds-valid.
+ *
+ * Exported PUBLIC API: the production gate routes through the cached probe
+ * path (`lineInBounds` + the per-file line count), while tests and external
+ * consumers use this text-based form. Kept — not deleted — for that reason.
  */
 export function verifyLineBounds(line, text) {
     const lineTotal = countLines(text);
-    if (line === undefined || line === null || line === WHOLE_FILE_LINE) {
-        return { inBounds: true, lineTotal };
+    return { inBounds: lineInBounds(line, lineTotal), lineTotal };
+}
+/**
+ * One filesystem probe for `root`/`resolved`: symlink containment, stat,
+ * regular-file + size cap, full read, NUL check, line count. Everything a
+ * finding needs beyond its own per-line check is captured in the result so
+ * repeated findings on the same file never re-stat or re-read it.
+ */
+function probeEvidenceFile(root, resolved) {
+    // Symlink containment: resolveWithin is lexical only, but existsSync /
+    // readFileSync follow symlinks. Verify the REAL path stays inside the REAL
+    // project root so a finding path can never read (or line-count) a file
+    // outside the project via a symlinked directory or file.
+    const rootReal = safeRealpath(root);
+    const real = safeRealpath(resolved);
+    if (!isWithin(rootReal, real)) {
+        return { resolvedPath: resolved, outcome: 'file_not_found', lineTotal: null };
     }
-    // Only a positive INTEGER is a valid line anchor. A fractional line (e.g.
-    // 3.7 from a bypassed schema) or a negative value is out of bounds — a
-    // fractional line "within" the file would otherwise be accepted and poison
-    // the evidence trail with a location nothing can jump to.
-    if (line < 1 || !Number.isInteger(line))
-        return { inBounds: false, lineTotal };
-    return { inBounds: line <= lineTotal, lineTotal };
+    // Regular-file + size guard: a directory, device file (/dev/zero), FIFO or
+    // multi-GB file is not a line-addressable text target. statSync follows
+    // symlinks, so a link to a device still lands here and is rejected.
+    let st;
+    try {
+        st = statSync(resolved);
+    }
+    catch {
+        return { resolvedPath: resolved, outcome: 'file_not_found', lineTotal: null };
+    }
+    if (!st.isFile()) {
+        // Directory / device / FIFO: exists but is not line-addressable at all.
+        return { resolvedPath: resolved, outcome: 'line_out_of_range', lineTotal: null };
+    }
+    if (st.size > MAX_EVIDENCE_BYTES) {
+        return { resolvedPath: resolved, outcome: 'file_too_large', lineTotal: null };
+    }
+    let raw;
+    try {
+        raw = readFileSync(resolved);
+    }
+    catch {
+        return { resolvedPath: resolved, outcome: 'file_not_found', lineTotal: null };
+    }
+    // A file containing a NUL byte is a binary payload: anchored line numbers
+    // on it cannot be trusted (mirrors the harness `evidence.py` NUL check).
+    // Reported as `binary_file` so it is distinguishable from a plain
+    // out-of-range line anchor.
+    if (raw.includes(0)) {
+        return { resolvedPath: resolved, outcome: 'binary_file', lineTotal: null };
+    }
+    return { resolvedPath: resolved, outcome: 'text', lineTotal: countLines(raw.toString('utf-8')) };
 }
 /** Verify a single finding's location against the real filesystem. */
 export function verifyFinding(root, input, opts = {}) {
@@ -108,10 +181,16 @@ export function verifyFinding(root, input, opts = {}) {
     // A non-string `file` (number, object, …) would make `resolve` throw
     // ERR_INVALID_ARG_TYPE — coerce to "" so it fails closed as not-found.
     const relFile = typeof input.file === 'string' ? input.file : '';
-    const line = typeof input.line === 'number' ? input.line : null;
+    const rawLine = input.line;
+    const line = typeof rawLine === 'number' ? rawLine : null;
+    // A PRESENT `line` must be a number. `line: "42"` / `line: true` (schema-
+    // bypassing JSON) is a claimed anchor we cannot resolve — fail closed as
+    // poisoned evidence instead of silently degrading it to a whole-file
+    // finding. Only an absent / null line keeps the WHOLE_FILE_LINE semantics.
+    const badLineType = rawLine !== undefined && rawLine !== null && typeof rawLine !== 'number';
     // "" resolves to the project ROOT (resolve(root, '') === root), which then
-    // trips the not-a-regular-file branch as `line_out_of_range` — but there is
-    // no file reference at all. Report it as `file_not_found` upfront.
+    // trips the not-a-regular-file branch — but there is no file reference at
+    // all. Report it as `file_not_found` upfront.
     if (relFile === '') {
         return {
             file: '',
@@ -123,95 +202,59 @@ export function verifyFinding(root, input, opts = {}) {
         };
     }
     const resolved = resolveWithin(root, relFile);
-    if (resolved === null || !existsSync(resolved)) {
-        return {
-            file: relFile,
-            line,
-            lineTotal: null,
-            resolvedPath: resolved,
-            verified: false,
-            error: 'file_not_found',
-        };
-    }
-    // Symlink containment: resolveWithin is lexical only, but existsSync /
-    // readFileSync follow symlinks. Verify the REAL path stays inside the REAL
-    // project root so a finding path can never read (or line-count) a file
-    // outside the project via a symlinked directory or file.
-    const rootReal = safeRealpath(root);
-    const real = safeRealpath(resolved);
-    if (!isWithin(rootReal, real)) {
-        return {
-            file: relFile,
-            line,
-            lineTotal: null,
-            resolvedPath: resolved,
-            verified: false,
-            error: 'file_not_found',
-        };
-    }
-    // Regular-file + size guard: a directory, device file (/dev/zero), FIFO or
-    // multi-GB file is not a line-addressable text target. statSync follows
-    // symlinks, so a link to a device still lands here and is rejected.
-    let st;
-    try {
-        st = statSync(resolved);
-    }
-    catch {
-        return {
-            file: relFile,
-            line,
-            lineTotal: null,
-            resolvedPath: resolved,
-            verified: false,
-            error: 'file_not_found',
-        };
-    }
-    if (!st.isFile() || st.size > MAX_EVIDENCE_BYTES) {
-        return {
-            file: relFile,
-            line,
-            lineTotal: null,
-            resolvedPath: resolved,
-            verified: false,
-            error: 'line_out_of_range',
-        };
+    let probe;
+    if (resolved === null) {
+        // Path escapes the root: no I/O happens, so nothing to cache.
+        probe = { resolvedPath: null, outcome: 'file_not_found', lineTotal: null };
     }
-    let raw;
-    try {
-        raw = readFileSync(resolved);
+    else {
+        const cached = opts.cache?.get(resolved);
+        if (cached) {
+            probe = cached;
+        }
+        else {
+            if (!existsSync(resolved)) {
+                probe = { resolvedPath: resolved, outcome: 'file_not_found', lineTotal: null };
+            }
+            else {
+                probe = probeEvidenceFile(root, resolved);
+            }
+            // Cache every resolved-path outcome (including not-found) so repeated
+            // findings on the same file cost one stat/read per audit, not one per
+            // finding (O(F×bytes) → O(unique files × bytes)).
+            if (opts.cache)
+                opts.cache.set(resolved, probe);
+        }
     }
-    catch {
+    if (probe.outcome !== 'text') {
         return {
             file: relFile,
             line,
             lineTotal: null,
-            resolvedPath: resolved,
+            resolvedPath: probe.resolvedPath,
             verified: false,
-            error: 'file_not_found',
+            error: probe.outcome,
         };
     }
-    // A file is not line-addressable if it contains a NUL byte (binary payload).
-    // Anchored line numbers on a binary file cannot be trusted, so treat them the
-    // same as an out-of-range line rather than credulously accepting them
-    // (mirrors the harness `evidence.py` NUL check).
-    if (raw.includes(0)) {
+    const lineTotal = probe.lineTotal ?? 0;
+    // Present-but-unanchorable line type (string/boolean/object): the file is
+    // real, but the claimed location can never be verified → poisoned.
+    if (badLineType) {
         return {
             file: relFile,
             line,
-            lineTotal: null,
-            resolvedPath: resolved,
+            lineTotal,
+            resolvedPath: probe.resolvedPath,
             verified: false,
             error: 'line_out_of_range',
         };
     }
-    const text = raw.toString('utf-8');
-    const { inBounds, lineTotal } = verifyLineBounds(line, text);
-    if (!inBounds) {
+    if (!lineInBounds(line, lineTotal)) {
         return {
             file: relFile,
             line,
             lineTotal,
-            resolvedPath: resolved,
+            resolvedPath: probe.resolvedPath,
             verified: false,
             error: 'line_out_of_range',
         };
@@ -220,24 +263,35 @@ export function verifyFinding(root, input, opts = {}) {
         file: relFile,
         line,
         lineTotal,
-        resolvedPath: resolved,
+        resolvedPath: probe.resolvedPath,
         verified: true,
     };
     if (opts.readSet !== undefined) {
+        // Per-finding, never cached: the read set may differ between calls sharing
+        // a probe cache, and membership is a cheap in-memory lookup.
         outcome.readVerified = opts.readSet.has(resolved);
     }
     return outcome;
 }
-/** Attest every finding in a list. */
+/** Attest every finding in a list (one shared per-file probe per call). */
 export function verifyFindings(root, findings, opts = {}) {
-    const results = findings.map((f) => verifyFinding(root, f, opts));
+    const cache = opts.cache ?? createEvidenceCache();
+    const scoped = opts.cache ? opts : { ...opts, cache };
+    const results = findings.map((f) => verifyFinding(root, f, scoped));
     return { checked: results.length, results };
 }
 /** `passed` is true only when no real existence failure exists (read is a hint). */
 export function evidencePassed(audit) {
     return audit.results.every((r) => r.error === undefined);
 }
-/** Violating (non-grounded) results. */
+/**
+ * Violating (non-grounded) results.
+ *
+ * Exported PUBLIC API (tests and integrations filter by it directly);
+ * the production payload uses `evidenceToPlain`, which inlines the same
+ * filter — so this stays as the named, shared accessor rather than being
+ * folded into it.
+ */
 export function evidenceViolations(audit) {
     return audit.results.filter((r) => r.error !== undefined);
 }

package/dist/file-lock.js

@@ -0,0 +1,165 @@
+/**
+ * src/file-lock.ts — generic cross-process advisory lock for `.iterate/` state.
+ *
+ * Several plugin writers mutate small JSON/JSONL state files with a
+ * read-modify-write cycle (fix registry, decision log, defense events,
+ * experience bank). `writeJsonAtomic` only makes a SINGLE write atomic — two
+ * plugin processes racing on the same project can still lose an update between
+ * their read and their write. The decision log already guards itself with a
+ * purpose-built mutex (see `tools/decision-log.ts`); this module generalizes
+ * that exact pattern so every other writer can serialize the same way.
+ *
+ * Semantics (identical to the decision-log lock, deliberately):
+ *   - exclusive create (`openSync(..., 'wx')`) with the holder pid stamped in;
+ *   - a lock whose owner process is gone, or whose mtime is ancient, is
+ *     stolen (unlink + retry);
+ *   - bounded wait — on timeout the lock degrades to "proceed unlocked"
+ *     (returns a callable no-op release) instead of wedging the tool call;
+ *   - the returned release is always callable, idempotent, and never throws.
+ *
+ * Best-effort by design: an advisory lock that cannot be taken must never turn
+ * a working tool into a failed one; the worst case is the pre-existing
+ * (unlocked) behavior.
+ *
+ * In-process callers get synchronous mutual exclusion through the same API —
+ * tools run on one thread, so acquiring twice in one process would self-deadlock;
+ * `withProjectLock` is therefore NOT reentrant and must not be nested for the
+ * same (projectRoot, name).
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync, } from 'node:fs';
+import { join } from 'node:path';
+const LOCK_DIR = '.iterate';
+const DEFAULT_WAIT_MS = 5000;
+const DEFAULT_STALE_MS = 10000;
+const POLL_MS = 25;
+/** True when a pid refers to a live process (or we lack permission to tell). */
+function processAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** Synchronous sleep (Atomics.wait is a reliable sleep in Node). */
+function sleepSync(ms) {
+    const sab = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(sab, 0, 0, ms);
+}
+/**
+ * Validate a lock name into a safe file-name fragment.
+ * Throws on anything that could escape `.iterate/` (path separators, dots).
+ */
+function lockFileName(name) {
+    if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(name)) {
+        throw new Error(`invalid lock name: ${JSON.stringify(name)}`);
+    }
+    return `.${name}.lock`;
+}
+/**
+ * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`.
+ *
+ * Returns a release function: always callable, idempotent, never throws.
+ * A no-op (but callable) release is returned when the lock directory cannot be
+ * created or the wait times out — callers then proceed unlocked, which is the
+ * historical best-effort behavior, rather than failing the operation.
+ */
+export function acquireProjectLock(projectRoot, name, options = {}) {
+    const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
+        ? options.waitMs
+        : DEFAULT_WAIT_MS;
+    const staleMs = Number.isFinite(options.staleMs) && (options.staleMs ?? 0) >= 0
+        ? options.staleMs
+        : DEFAULT_STALE_MS;
+    const dir = join(projectRoot, LOCK_DIR);
+    if (!existsSync(dir)) {
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            return () => { };
+        }
+    }
+    const lockPath = join(dir, lockFileName(name));
+    const start = Date.now();
+    for (;;) {
+        let fd = null;
+        try {
+            fd = openSync(lockPath, 'wx');
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                return () => { };
+            // Lock exists — steal it when the owner is gone or the lock is ancient.
+            let stale = false;
+            try {
+                const st = statSync(lockPath);
+                if (Date.now() - st.mtimeMs > staleMs)
+                    stale = true;
+                else {
+                    const pid = Number(readFileSync(lockPath, 'utf-8'));
+                    if (!processAlive(pid))
+                        stale = true;
+                }
+            }
+            catch {
+                stale = true; // unreadable/vanishing lock → retry as stale
+            }
+            if (stale) {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    // another holder stole it first — retry immediately
+                }
+                continue;
+            }
+            if (Date.now() - start > waitMs)
+                return () => { };
+            sleepSync(POLL_MS);
+            continue;
+        }
+        // Owned the lock: stamp the holder pid, then release once on return.
+        try {
+            writeSync(fd, String(process.pid));
+        }
+        catch {
+            // pid stamp is advisory
+        }
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // best-effort
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                // already gone
+            }
+        };
+    }
+}
+/**
+ * Run `fn` while holding the advisory lock named `name`.
+ * The release is guaranteed via `finally`; `fn`'s value or error propagates
+ * unchanged. Not reentrant for the same (projectRoot, name) — see header.
+ */
+export function withProjectLock(projectRoot, name, fn, options = {}) {
+    const release = acquireProjectLock(projectRoot, name, options);
+    try {
+        return fn();
+    }
+    finally {
+        release();
+    }
+}