iterate-plugin 3.5.4 → 3.5.5

package/dist/atomic-fs.js

@@ -48,12 +48,21 @@ function tempPathFor(filePath) {
  */
 export function writeTextAtomic(filePath, data) {
     const tmp = tempPathFor(filePath);
-    writeFileSync(tmp, data, 'utf-8');
+    try {
+        writeFileSync(tmp, data, 'utf-8');
+    }
+    catch (err) {
+        // The write itself failed (disk full, permission, …): the temp file may
+        // already be partially written, so remove it before propagating — a
+        // failed write must never litter the directory either.
+        cleanupTemp(tmp);
+        throw err;
+    }
     try {
         renameSync(tmp, filePath);
     }
     catch (err) {
-        // Best-effort temp cleanup so a failed write never litters the directory.
+        // Best-effort temp cleanup so a failed rename never litters the directory.
         cleanupTemp(tmp);
         throw err;
     }
@@ -61,12 +70,21 @@ export function writeTextAtomic(filePath, data) {
 /** Async variant of {@link writeTextAtomic} (same temp naming convention). */
 export async function writeTextAtomicAsync(filePath, data) {
     const tmp = tempPathFor(filePath);
-    await writeFile(tmp, data, 'utf-8');
+    try {
+        await writeFile(tmp, data, 'utf-8');
+    }
+    catch (err) {
+        // The write itself failed (disk full, permission, …): the temp file may
+        // already be partially written, so remove it before propagating — a
+        // failed write must never litter the directory either.
+        await cleanupTempAsync(tmp);
+        throw err;
+    }
     try {
         await rename(tmp, filePath);
     }
     catch (err) {
-        // Best-effort temp cleanup so a failed write never litters the directory.
+        // Best-effort temp cleanup so a failed rename never litters the directory.
         await cleanupTempAsync(tmp);
         throw err;
     }

package/dist/config-loader.js

@@ -10,7 +10,10 @@ export function loadConfig(projectRoot) {
     try {
         const content = readFileSync(join(projectRoot, 'iterate.config.yaml'), 'utf-8');
         const parsed = yaml.load(content);
-        if (!parsed || typeof parsed !== 'object')
+        // A YAML sequence root (e.g. a list of findings or a `- foo` file) must
+        // not masquerade as a config object — treating it as one would merge its
+        // indices into the config (config bomb). Reject it, not coerce it.
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
             return null;
         return parsed;
     }
@@ -141,7 +144,7 @@ export function flattenCommands(commands) {
  */
 export function validateConfig(config) {
     const errors = [];
-    if (!config || typeof config !== 'object') {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
         errors.push('root');
         return errors;
     }
@@ -190,7 +193,9 @@ export function validateConfig(config) {
  *      the DSH runtime injects per-session env into tool sub-processes).
  */
 export function resolveProjectRoot(input, sessionCwd) {
-    const raw = (input ?? '').trim();
+    // A non-string input (number, array, …) from a hostile tool invocation must
+    // be treated as "no explicit path" instead of crashing on `.trim()`.
+    const raw = (typeof input === 'string' ? input : '').trim();
     // A NUL byte can never name a real path and makes `resolve()` (and every
     // downstream fs call) throw — treat it as unsafe input, not a throw path.
     if (raw.includes('\0')) {

package/dist/config-write.js

@@ -9,8 +9,8 @@
  * The security posture mirrors the triage tool: never overwrite a malformed
  * config, always back up before writing, roll back on failure.
  */
-import { copyFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
+import { copyFileSync, existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import yaml from 'js-yaml';
 import { writeTextAtomic } from "./atomic-fs.js";
 /** Config file name (must match config-loader). */
@@ -19,6 +19,39 @@ export const CONFIG_FILE = 'iterate.config.yaml';
 export function configBackupSuffix(now = new Date()) {
     return now.toISOString().replace(/[:.]/g, '-');
 }
+/** 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;
+/** Keep at most this many timestamped config backups (older ones are removed). */
+export const MAX_CONFIG_BACKUPS = 5;
+/**
+ * Bound the timestamped config backups: after a fresh one is written, delete
+ * every older `config.bak-*` file beyond the newest `keep`. Best-effort — a
+ * filesystem failure here must never fail the write that just succeeded.
+ * @returns the absolute paths of the backups that were removed.
+ */
+export function pruneOldConfigBackups(configPath, keep = MAX_CONFIG_BACKUPS) {
+    const removed = [];
+    try {
+        const dir = dirname(configPath);
+        const prefix = `${basename(configPath)}.bak-`;
+        const matches = existsSync(dir)
+            ? readdirSync(dir).filter((f) => f.startsWith(prefix)).sort()
+            : [];
+        const doomed = matches.slice(0, Math.max(0, matches.length - keep));
+        for (const f of doomed) {
+            rmSync(join(dir, f), { force: true });
+            removed.push(join(dir, f));
+        }
+    }
+    catch {
+        // Best-effort cleanup — never surface a cleanup failure.
+    }
+    return removed;
+}
 /**
  * Validate a partial config update.
  * Returns an array of error strings (empty when the update is valid).
@@ -40,8 +73,9 @@ export function validateConfigUpdates(updates) {
         }
     }
     if ('max_rounds' in updates) {
-        if (typeof updates.max_rounds !== 'number' || !Number.isInteger(updates.max_rounds) || updates.max_rounds < 1) {
-            errors.push('updates.max_rounds must be a positive integer');
+        if (typeof updates.max_rounds !== 'number' || !Number.isInteger(updates.max_rounds) ||
+            updates.max_rounds < 1 || updates.max_rounds > MAX_MAX_ROUNDS) {
+            errors.push(`updates.max_rounds must be an integer between 1 and ${MAX_MAX_ROUNDS}`);
         }
     }
     if ('review' in updates) {
@@ -59,11 +93,11 @@ export function validateConfigUpdates(updates) {
             errors.push('updates.atomic must be an object');
         }
         else {
-            if (a.max_lines !== undefined && (typeof a.max_lines !== 'number' || !Number.isInteger(a.max_lines) || a.max_lines < 1)) {
-                errors.push('updates.atomic.max_lines must be a positive integer');
+            if (a.max_lines !== undefined && (typeof a.max_lines !== 'number' || !Number.isInteger(a.max_lines) || a.max_lines < 1 || a.max_lines > MAX_ATOMIC_MAX_LINES)) {
+                errors.push(`updates.atomic.max_lines must be an integer between 1 and ${MAX_ATOMIC_MAX_LINES}`);
             }
-            if (a.max_adjacent_methods !== undefined && (typeof a.max_adjacent_methods !== 'number' || a.max_adjacent_methods < 0)) {
-                errors.push('updates.atomic.max_adjacent_methods must be a non-negative number');
+            if (a.max_adjacent_methods !== undefined && (typeof a.max_adjacent_methods !== 'number' || a.max_adjacent_methods < 0 || a.max_adjacent_methods > MAX_MAX_ADJACENT_METHODS)) {
+                errors.push(`updates.atomic.max_adjacent_methods must be a number between 0 and ${MAX_MAX_ADJACENT_METHODS}`);
             }
         }
     }
@@ -164,7 +198,10 @@ export function readRawConfig(configPath) {
     catch {
         throw new Error('existing iterate.config.yaml is not a valid YAML mapping');
     }
-    if (!parsed || typeof parsed !== 'object') {
+    // A YAML sequence root (array) must not masquerade as a config object —
+    // `typeof [] === 'object'`, so the presence check alone would accept a
+    // config file that is actually a list. Writing over it would destroy data.
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new Error('existing iterate.config.yaml is not a valid YAML mapping');
     }
     return parsed;
@@ -201,5 +238,9 @@ export function writeConfigFile(projectRoot, config) {
         }
         return { ok: false, error: `failed to write config: ${String(err)}${rollbackError}` };
     }
+    // Success: bound the accumulation of timestamped backups so a long-lived
+    // project never collects an unbounded pile of config snapshots.
+    if (backupPath)
+        pruneOldConfigBackups(configPath);
     return { ok: true, backupPath };
 }

package/dist/evidence.js

@@ -89,8 +89,35 @@ export function verifyLineBounds(line, text) {
 }
 /** Verify a single finding's location against the real filesystem. */
 export function verifyFinding(root, input, opts = {}) {
-    const relFile = input.file ?? '';
+    // A null element / non-object finding (hostile or model-authored JSON) must
+    // be reported as poisoned evidence, never crash `path.resolve` downstream.
+    if (!input || typeof input !== 'object') {
+        return {
+            file: '',
+            line: null,
+            lineTotal: null,
+            resolvedPath: null,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
+    // 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;
+    // "" 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.
+    if (relFile === '') {
+        return {
+            file: '',
+            line,
+            lineTotal: null,
+            resolvedPath: null,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
     const resolved = resolveWithin(root, relFile);
     if (resolved === null || !existsSync(resolved)) {
         return {

package/dist/git-scope.js

@@ -89,7 +89,10 @@ function decodeQuotedPath(content) {
 }
 export function parseChangedFiles(stdout) {
     if (stdout.includes('\0')) {
-        return stdout.split('\0').map((s) => s.trim()).filter((s) => s.length > 0);
+        // NUL mode: git emits exact names with no surrounding whitespace, so any
+        // trim would CORRUPT a filename that legitimately starts/ends with spaces
+        // (git supports such names). Split and drop only the trailing empty entry.
+        return stdout.split('\0').filter((s) => s.length > 0);
     }
     return stdout
         .split('\n')
@@ -147,9 +150,15 @@ export function decideScope(changedFiles) {
  * Uses execFile (no shell), so a model-controlled branch name can never be
  * interpreted as shell syntax.
  */
-export function runGit(args, cwd) {
+export function runGit(args, cwd, opts = {}) {
     return new Promise((resolve) => {
-        execFile('git', args, { cwd, timeout: 30_000, maxBuffer: 10 * 1024 * 1024, env: { ...process.env, PAGER: 'cat' } }, (error, stdout, stderr) => {
+        execFile('git', args, {
+            cwd,
+            timeout: 30_000,
+            maxBuffer: 10 * 1024 * 1024,
+            env: { ...process.env, PAGER: 'cat' },
+            signal: opts.signal,
+        }, (error, stdout, stderr) => {
             const exitCode = error ? (typeof error.code === 'number' ? error.code : 1) : 0;
             resolve({ ok: exitCode === 0, stdout: stdout ?? '', stderr: stderr ?? '', exitCode });
         });
@@ -161,7 +170,7 @@ export function runGit(args, cwd) {
  * `full`-scope result with `error` set — the reviewer must never crash the
  * plan because git is unavailable.
  */
-export async function resolveChangedFiles(root, targetBranch) {
+export async function resolveChangedFiles(root, targetBranch, opts = {}) {
     // Option-injection guard: a branch name starting with '-' would be parsed by
     // git as an option (e.g. --output=...), not a ref. Reject it outright.
     if (typeof targetBranch !== 'string' || targetBranch.trim() === '' || targetBranch.startsWith('-')) {
@@ -174,7 +183,7 @@ export async function resolveChangedFiles(root, targetBranch) {
     }
     // -z: NUL-delimited names — machine-safe for any filename (spaces, quotes,
     // non-ASCII), and never confused with option-like content.
-    const { ok, stdout, stderr } = await runGit(['diff', '--name-only', '-z', targetBranch, '--'], root);
+    const { ok, stdout, stderr } = await runGit(['diff', '--name-only', '-z', targetBranch, '--'], root, opts);
     if (!ok) {
         const reason = stderr.trim() || `git diff --name-only -z ${targetBranch} failed`;
         return { scope: 'full', changedFiles: [], fallbackToFull: true, error: reason };

package/dist/jobs.js

@@ -16,6 +16,20 @@
  * - The registry is memory-only and panel rows are read-only (no progress
  *   updates), so these jobs are completion records, not control channels.
  */
+/**
+ * Read `ctx.jobs` defensively: the dsh plugin context can be a Proxy whose
+ * `jobs` getter throws (or is missing) when no job registry is present. A
+ * Proxy throw on property access must degrade to "no jobs", never crash the
+ * tool execution we are about to wrap.
+ */
+function safeJobs(ctx) {
+    try {
+        return ctx?.jobs;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Run `fn` wrapped in a dsh background job, settling it completed/failed
  * with the execution's outcome. When the host exposes no job registry (or
@@ -29,7 +43,7 @@
  * @returns the registry-issued job id, or `null` when unavailable.
  */
 export async function runWithJob(ctx, kind, label, fn) {
-    const jobs = ctx?.jobs;
+    const jobs = safeJobs(ctx);
     if (!jobs || typeof jobs.start !== 'function') {
         return { result: await fn(), jobId: null };
     }

package/dist/live.js

@@ -36,6 +36,45 @@ export const LIVE_MAX_BYTES = 64 * 1024;
 export function liveFilePath(projectRoot) {
     return join(projectRoot, '.iterate', 'transcript-live.ndjson');
 }
+/**
+ * Module-level in-process queue serializing live-feed writes. The trim path
+ * (read → rewrite → append) is a read-modify-write: two concurrent tool
+ * results could interleave and one's rewrite would silently drop the other's
+ * freshly-appended line. Chaining every append onto one tail makes the whole
+ * read+rewrite+append atomic within the process (the only realistic mode for
+ * the plugin); cross-process racing remains a theoretical hazard, but the
+ * cap-trim makes a lost line a cosmetic issue, not a correctness one.
+ */
+let liveWriteQueue = Promise.resolve();
+function enqueueLiveWrite(task) {
+    const next = liveWriteQueue.then(task, task);
+    liveWriteQueue = next.catch(() => { });
+    return next;
+}
+/** Append one activity record to the project's live feed (byte-capped). */
+export function appendLive(projectRoot, entry) {
+    return enqueueLiveWrite(async () => {
+        const file = liveFilePath(projectRoot);
+        const line = JSON.stringify(entry) + '\n';
+        await mkdir(join(projectRoot, '.iterate'), { recursive: true });
+        // Amortized O(1): only read+rewrite when the file has grown past the cap.
+        try {
+            const st = await stat(file).catch(() => null);
+            if (st && st.size > LIVE_MAX_BYTES) {
+                const raw = await readFile(file, 'utf-8');
+                const lines = raw.split('\n').filter(Boolean);
+                const tail = lines.slice(-LIVE_MAX_ENTRIES);
+                // Atomic rewrite (unique temp + rename) so a crash mid-trim never
+                // truncates the live feed; the temp file is prunable by iterate_prune.
+                await writeTextAtomicAsync(file, tail.join('\n') + '\n');
+            }
+            await appendFile(file, line, 'utf-8');
+        }
+        catch {
+            // Fire-and-forget: never let live capture break a tool call.
+        }
+    });
+}
 /** Resolve the project root a tool execution belongs to, if any. */
 function projectRootOf(exec) {
     const cwd = exec.agent?.session?.header?.cwd;
@@ -95,28 +134,6 @@ export function classifyTool(name, args, projectRoot) {
         target = name;
     return { ts: new Date().toISOString(), type, tool: name, target };
 }
-/** Append one activity record to the project's live feed (byte-capped). */
-export async function appendLive(projectRoot, entry) {
-    const file = liveFilePath(projectRoot);
-    const line = JSON.stringify(entry) + '\n';
-    await mkdir(join(projectRoot, '.iterate'), { recursive: true });
-    // Amortized O(1): only read+rewrite when the file has grown past the cap.
-    try {
-        const st = await stat(file).catch(() => null);
-        if (st && st.size > LIVE_MAX_BYTES) {
-            const raw = await readFile(file, 'utf-8');
-            const lines = raw.split('\n').filter(Boolean);
-            const tail = lines.slice(-LIVE_MAX_ENTRIES);
-            // Atomic rewrite (unique temp + rename) so a crash mid-trim never
-            // truncates the live feed; the temp file is prunable by iterate_prune.
-            await writeTextAtomicAsync(file, tail.join('\n') + '\n');
-        }
-        await appendFile(file, line, 'utf-8');
-    }
-    catch {
-        // Fire-and-forget: never let live capture break a tool call.
-    }
-}
 /** Read the live feed (newest first), capped at the last LIVE_MAX_ENTRIES. */
 export async function readLive(projectRoot) {
     const file = liveFilePath(projectRoot);

package/dist/meta-review.js

@@ -99,7 +99,7 @@ export function metaReviewReport(report) {
     if (dimSum !== total) {
         add('DIMENSION_SUM', 'high', 'byDimension counts do not sum to totalFindings', `byDimension sums to ${dimSum}, but totalFindings is ${total}.`);
     }
-    const invalidDim = findings.find((f) => !dimensions.includes(f?.dimension));
+    const invalidDim = findings.find((f) => !!f && !dimensions.includes(f?.dimension));
     if (invalidDim) {
         add('DIMENSION_UNKNOWN', 'medium', `Finding references unknown dimension "${invalidDim.dimension}"`, `dimension "${invalidDim.dimension}" is not in report.dimensions ` +
             `(${dimensions.join(', ') || 'none'}).`);
@@ -227,7 +227,7 @@ export function buildFinalReviewReport(report, opts = {}) {
                     // Try to attribute the poisoned finding to the round that first
                     // surfaced it (best-effort; report rounds carry it).
                     for (const r of report.rounds ?? []) {
-                        const matched = (r.findings ?? []).some((fnd) => fnd.file === violation.file && fnd.line === violation.line);
+                        const matched = (r.findings ?? []).some((fnd) => !!fnd && fnd?.file === violation.file && fnd?.line === violation.line);
                         if (matched) {
                             roundHint = ` (round ${r.round})`;
                             break;

package/dist/review-scope.js

@@ -57,10 +57,14 @@ function normalizePath(path) {
         if (part === '' || part === '.')
             continue;
         if (part === '..') {
-            if (parts.length > 0)
+            // Mirrors Python `os.path.normpath`: a leading `..` is preserved and a
+            // second `..` is NEVER collapsed into a bare `/` away — otherwise a
+            // traversal like `../../evil` folds into the single segment `evil` and
+            // the escape becomes undetectable downstream.
+            if (parts.length > 0 && parts[parts.length - 1] !== '..')
                 parts.pop();
             else
-                parts.push(part); // no root segment to pop — keep the leading '..'
+                parts.push(part);
             continue;
         }
         parts.push(part);

package/dist/review.js

@@ -28,19 +28,20 @@ export const SEVERITY_RANK = {
 export function sortFindings(findings) {
     return [...findings].sort((a, b) => {
         // Guard against an out-of-spec severity string (e.g. from a model that
-        // bypassed the schema): treat it as the least severe so NaN never enters
-        // the comparator and ordering stays deterministic.
-        const rankA = SEVERITY_RANK[a.severity] ?? SEVERITY_RANK.low;
-        const rankB = SEVERITY_RANK[b.severity] ?? SEVERITY_RANK.low;
+        // bypassed the schema) AND against a null list element (model-authored
+        // JSON): treat both as the least severe so NaN never enters the
+        // comparator and ordering stays deterministic.
+        const rankA = SEVERITY_RANK[a?.severity] ?? SEVERITY_RANK.low;
+        const rankB = SEVERITY_RANK[b?.severity] ?? SEVERITY_RANK.low;
         const bySeverity = rankA - rankB;
         if (bySeverity !== 0)
             return bySeverity;
         // Defensive coercion: `file`/`line` can be wrong-typed when schema
         // validation is disabled — String()/Number() keep the comparator total.
-        const byFile = String(a.file ?? '').localeCompare(String(b.file ?? ''));
+        const byFile = String(a?.file ?? '').localeCompare(String(b?.file ?? ''));
         if (byFile !== 0)
             return byFile;
-        return (Number(a.line) || 0) - (Number(b.line) || 0);
+        return (Number(a?.line) || 0) - (Number(b?.line) || 0);
     });
 }
 /** Normalize a summary so near-identical duplicates collapse to one key. */

package/dist/skill-prompt.js

@@ -356,10 +356,10 @@ for (let r = startRound; r <= maxRounds; r++) {
     const byFile = {}
     atomic.forEach(f => { (byFile[f.file] = byFile[f.file] || []).push(f) })
     const fixRes = await parallel(Object.keys(byFile).map(file => () => agent(
-      'Apply the fixes for ' + file + ' using iterate_fix. For EACH finding in this list, ' +
+      'Apply the fixes for ' + JSON.stringify(file) + ' using iterate_fix. For EACH finding in this list, ' +
       'read the current file, compute the edited full content (change <= ' + atomicMaxLines + ' lines), and call ' +
-      'iterate_fix({ file: "' + file + '", content: <full new file content>, finding: <that finding>, round: ' + r + ' }). ' +
-      'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: "' + file + '" }) to verify the accumulated diff and ' +
+      'iterate_fix({ file: ' + JSON.stringify(file) + ', content: <full new file content>, finding: <that finding>, round: ' + r + ' }). ' +
+      'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: ' + JSON.stringify(file) + ' }) to verify the accumulated diff and ' +
       'read its line statistics (lines added/removed). ' +
       'Findings: ' + JSON.stringify(byFile[file]) + '. Return the array of {id, ok, error, file, linesAdded, linesRemoved} per iterate_fix call ' +
       '(id/ok required; put the file-wide line stats from iterate_diff on each record, or on the last record and 0 elsewhere).',

package/dist/tools/decision-log.js

@@ -1,9 +1,127 @@
-import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs';
+import { appendFileSync, readFileSync, mkdirSync, existsSync, openSync, writeSync, closeSync, unlinkSync, statSync, } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 const LOG_DIR = '.iterate';
 const LOG_FILE = 'decision-log.jsonl';
+// ─── Cross-process log mutex ────────────────────────────────────────────────
+//
+// The prune rewrite (temp + atomic rename) can silently discard an audit line
+// from a CONCURRENT appender whose fd was opened against the pre-rename inode:
+// the appender writes to the unlinked inode, the post-rewrite re-read sees a
+// "stable" file, and the fresh entry is lost. In-process safety is guaranteed
+// by synchronous I/O, but a second plugin process appending to the same
+// project realises the race. The log is serialized with a tiny advisory lock
+// file (exclusive create, pid stamped, stale-stealable) so `append` and the
+// prune rewrite mutually exclude across processes. Best-effort: contention
+// timeouts degrade to "proceed unlocked" (the bounded retry loop in prune.ts
+// stays as defense-in-depth), never to a crash.
+const LOCK_FILE = '.decision-log.lock';
+const LOCK_WAIT_MS = 5000;
+const LOCK_STALE_MS = 10000;
+const LOCK_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 busy-wait 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);
+}
+/**
+ * Acquire the decision-log lock for `projectRoot`.
+ * Returns a release function (always callable; a no-op when the lock could
+ * not be taken — never wedge an append behind a vanished holder).
+ */
+export function acquireLogLock(projectRoot) {
+    const dir = join(projectRoot, LOG_DIR);
+    if (!existsSync(dir)) {
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            return () => { };
+        }
+    }
+    const lockPath = join(dir, LOCK_FILE);
+    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 > LOCK_STALE_MS)
+                    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 */ }
+                continue;
+            }
+            if (Date.now() - start > LOCK_WAIT_MS)
+                return () => { };
+            sleepSync(LOCK_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 */ }
+        };
+    }
+}
+// ─── Entry-count cache (avoid an O(n) full re-read per append) ─────────────
+const entryCountCache = new Map();
+/** Line-count the log file from scratch (entries = non-empty JSON lines). */
+function recountEntries(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        return content.split('\n').filter((l) => l.trim().length > 0).length;
+    }
+    catch {
+        return 1;
+    }
+}
 /** All valid DecisionLogEntry `type` values (must stay in sync with Types). */
 const VALID_ENTRY_TYPES = new Set([
     'round_start',
@@ -50,25 +168,32 @@ function logPath(projectRoot) {
  * miss without failing the mutation they already performed.
  */
 export function appendDecisionEntry(projectRoot, entry) {
-    let filePath;
-    try {
-        filePath = logPath(projectRoot);
-        const line = JSON.stringify(entry) + '\n';
-        appendFileSync(filePath, line, 'utf-8');
-    }
-    catch (err) {
-        return { count: 0, path: join(projectRoot, LOG_DIR, LOG_FILE), error: `failed to append decision log: ${String(err)}` };
-    }
-    // Count entries
-    let count = 0;
+    // Serialize with the cross-process log lock so an append can never interleave
+    // with a prune rewrite (which renames the file under us).
+    const release = acquireLogLock(projectRoot);
     try {
-        const content = readFileSync(filePath, 'utf-8');
-        count = content.split('\n').filter((l) => l.trim().length > 0).length;
+        const filePath = logPath(projectRoot);
+        try {
+            const line = JSON.stringify(entry) + '\n';
+            const prevSize = existsSync(filePath) ? statSync(filePath).size : 0;
+            appendFileSync(filePath, line, 'utf-8');
+            // Count entries via the size/count cache: when nothing else changed the
+            // file since our last append (same byte size), count is just +1 — no full
+            // re-read. Falls back to a full re-count whenever the cache is stale.
+            const cached = entryCountCache.get(filePath);
+            const count = cached && cached.size === prevSize
+                ? cached.count + 1
+                : recountEntries(filePath);
+            entryCountCache.set(filePath, { size: existsSync(filePath) ? statSync(filePath).size : prevSize, count });
+            return { count, path: filePath };
+        }
+        catch (err) {
+            return { count: 0, path: join(projectRoot, LOG_DIR, LOG_FILE), error: `failed to append decision log: ${String(err)}` };
+        }
     }
-    catch {
-        count = 1;
+    finally {
+        release();
     }
-    return { count, path: filePath };
 }
 /**
  * Read all entries from the decision log, plus the count of corrupt lines.