iterate-plugin 3.5.4 → 3.5.6

package/dist/skill-prompt.js

@@ -19,7 +19,7 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_diff\` — show the accumulated diff for a fixed file (vs its original backup) or a per-file summary of all fixes
 - \`iterate_rollback\` — revert a fix by id: restore the file from its backup, remove the fix from the registry, log a \`revert\` entry. Use when a round's validation fails
 - \`iterate_checkpoint\` — save / load / clear an iteration checkpoint (\`.iterate/checkpoint.json\`) so a long run can resume where it left off
-- \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence, and whether the run was interrupted (a checkpoint left on disk means the previous run was interrupted and can be resumed)
+- \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence, and whether the run was interrupted (a checkpoint on disk with no newer decision-log activity means the previous run was interrupted and can be resumed)
 - \`iterate_history\` — inspect the runtime state in detail: decision-log entries and applied fixes (optionally scoped to a round or a fixed file)
 - \`iterate_prune\` — remove stale runtime artifacts (\`.iterate/\` entries). Defaults to a read-only dry-run that reports what WOULD be removed; pass \`dryRun:false\` to actually prune.
 - \`iterate_transcript\` — runtime observatory file (\`.iterate/transcript.json\`). \`read\` fetches the persisted manifest including any steering \`nudge\` for this run's reviewers; \`capture\` (call once after the final report) persists the per-reviewer threads, convergence trend, findings, fixes, checkpoint, and timeline so the client observatory panel reflects the run; \`nudge\` sets/clears steering text the next round's reviewers read. Purely local, never touches source files.
@@ -80,6 +80,10 @@ const maxRounds = plan.maxReviewRounds
 const knownIntentional = (plan.knownIntentional || [])   // config personalization filter, applied in aggregate
 let known = []              // cumulative DEDUPED findings fed back to reviewers
 const rounds = []           // raw per-round findings
+// Tracks whether the LAST executed round produced usable reviewer output. A
+// round where every reviewer subagent failed (or output stayed schema-invalid
+// after retries) is INCONCLUSIVE — it must never make the run look converged.
+let lastRoundOk = true
 
 phase('transcript')
 // Read any steering nudge written (via iterate_transcript nudge) for this run's reviewers.
@@ -117,6 +121,12 @@ for (let r = 1; r <= maxRounds; r++) {
         JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.'
       return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
     }))
+    // A per-dimension reviewer subagent resolves \`null\` on child failure; the
+    // aggregate below would report an all-failed round as an empty round, and
+    // the convergence math would then read "0 new findings". An all-failed
+    // round is NOT a clean pass — it is inconclusive, so the convergence gate
+    // below refuses it before any "converged" signal fires.
+    const reviewersOk = raw.length > 0 ? raw.some(x => x !== null && typeof x === 'object') : true
     const thisRound = {
       round: r,
       findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])),
@@ -144,23 +154,30 @@ for (let r = 1; r <= maxRounds; r++) {
     // final summary can explain WHY the round was inconclusive.
     log('round ' + r + ' output STILL schema-invalid after 3 attempts — marking round inconclusive (NOT converged)')
   }
+  const roundUnusable = schemaInvalid || !reviewersOk
+  if (roundUnusable) lastRoundOk = false
   // Feed the DEDUPED + already-filtered set back (not raw findings) so the known
-  // list stays bounded and reviewers never see the same issue twice.
-  if (agg && agg.report && Array.isArray(agg.report.findings)) known = agg.report.findings
+  // list stays bounded and reviewers never see the same issue twice. Never feed
+  // an unusable round's empty result — it would erase the still-valid known list
+  // and let reviewers re-report everything next round.
+  if (!roundUnusable && agg && agg.report && Array.isArray(agg.report.findings)) known = agg.report.findings
   // A round counts as "converged" ONLY when the aggregate accepted it
-  // (schema-valid) AND it genuinely found zero NEW findings. If reviewers all
-  // failed or their output stayed schema-invalid after retries, the round is
-  // INCONCLUSIVE — never report an empty-but-broken round as converged (an
-  // invalid/failed round must fail the run, not masquerade as a clean pass).
-  if (!schemaInvalid) {
+  // (schema-valid) AND its reviewers actually returned output AND it genuinely
+  // found zero NEW findings. If reviewers all failed or their output stayed
+  // schema-invalid after retries, the round is INCONCLUSIVE — never report an
+  // empty-but-broken round as converged (an invalid/failed round would
+  // otherwise masquerade as a clean pass and stop the run early).
+  if (!roundUnusable && !schemaInvalid) {
     const newCount =
       agg && agg.report && agg.report.convergence
         ? agg.report.convergence.findingsByRound[r - 1]
         : thisRound.findings.length
     if (newCount === 0) {
       log('round ' + r + ' found 0 new findings — converged')
+      lastRoundOk = true
       break
     }
+    lastRoundOk = true
   }
 }
 
@@ -196,8 +213,13 @@ return {
   mode: 'dry-run',
   goal: report.goal,
   rounds: rounds.length,
-  converged: report.convergence.converged,
-  stoppedReason: report.convergence.stoppedReason,
+  // The aggregate's convergence flag is only trustworthy when the last round
+  // was usable — an all-failed/schema-invalid final round looks like "0 new"
+  // to the convergence math but is an inconclusive run, never a clean pass.
+  converged: report.convergence.converged && lastRoundOk,
+  stoppedReason: report.convergence.converged && !lastRoundOk
+    ? 'inconclusive'
+    : report.convergence.stoppedReason,
   findingsByRound: report.convergence.findingsByRound,
   totalFindings: report.summary.totalFindings,
   bySeverity: { critical: report.summary.critical, high: report.summary.high, medium: report.summary.medium, low: report.summary.low },
@@ -259,7 +281,7 @@ const configRes = await agent(
 const cfg = (configRes && configRes.config) ? configRes.config : null
 const atomicMaxLines = (cfg && cfg.atomic && cfg.atomic.max_lines) ? cfg.atomic.max_lines : 20
 const planRes = await agent(
-  'Call iterate_review({operation:"plan", mode:"normal", maxReviewRounds:' + (args.maxRounds || 3) + '}) and return the plan JSON.',
+  'Call iterate_review({operation:"plan", mode:"normal"' + (args.maxRounds ? ', maxReviewRounds:' + args.maxRounds : '') + '}) and return the plan JSON.',
   Object.assign({ label: 'review:plan' }, backend)
 )
 const plan = (planRes && planRes.plan) ? planRes.plan : null
@@ -273,6 +295,7 @@ const architectural = (checkpoint && Array.isArray(checkpoint.findings)) ? check
 let fixedCount = (checkpoint && typeof checkpoint.fixedCount === 'number') ? checkpoint.fixedCount : 0
 let converged = false
 let abortedByValidation = false
+let schemaFailed = false        // last round produced no usable reviewer output (schema-invalid after retries / all reviewers failed)
 let failedCommands = []
 let configErrors = []          // validation commands NOT in validation.commands (config gap, no rollback)
 const fixRecords = []        // observatory fix records collected round by round
@@ -315,6 +338,10 @@ for (let r = startRound; r <= maxRounds; r++) {
         '\\n Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.'
       return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
     }))
+    // ALL reviewers returning null (child failures) means this round produced
+    // no usable output — an empty aggregate must not read like a clean
+    // "nothing to fix" convergence. Gate the loop exit + convergence on it.
+    const reviewersOk = raw.length > 0 ? raw.some(x => x !== null && typeof x === 'object') : true
     const thisRound = {
       round: r,
       findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])),
@@ -338,10 +365,19 @@ for (let r = startRound; r <= maxRounds; r++) {
       log('retry ' + attempts + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
     }
   } while (schemaInvalid && attempts < 3)
-  if (schemaInvalid) {
-    // Bounded exit: never loop forever. Surface the failure so the run's
-    // final summary can explain WHY the round was inconclusive.
-    log('round ' + r + ' output STILL schema-invalid after 3 attempts — marking round inconclusive (NOT converged)')
+  if (schemaInvalid || !reviewersOk) {
+    // Bounded exit: never loop forever, and never let an all-failed/empty round
+    // read like a clean convergence. Stop the run WITHOUT applying fixes for
+    // this round, record the failure in the audit trail, and leave the
+    // checkpoint in place so a user/DM can resume or re-roll after fixing the
+    // reviewer configuration.
+    schemaFailed = true
+    log('round ' + r + ' produced NO usable reviewer output (schema-invalid after retries or all reviewers failed) — stopping run (NOT converged)')
+    await agent(
+      'Call iterate_decision_log({operation:"append", type:"round_failed", round:' + r + ', data:{reason:"' + (schemaInvalid ? 'schema_invalid' : 'no_usable_reviewer_output') + '", rolledBack:0}})',
+      Object.assign({ label: 'log:schemaFailed:r' + r }, backend)
+    )
+    break
   }
   const findings = (agg && agg.report && agg.report.findings) ? agg.report.findings : thisRound.findings
   const atomic = findings.filter(f => f.is_atomic === true)
@@ -356,10 +392,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).',
@@ -475,7 +511,7 @@ const statusRes = await agent(
   { label: 'status:final' }
 )
 const status = (statusRes && statusRes.ok) ? statusRes : null
-if (!abortedByValidation) {
+if (!abortedByValidation && !schemaFailed) {
   // Iteration finished cleanly → clear the checkpoint so the next run starts fresh.
   await agent(
     'Call iterate_checkpoint({ operation: "clear" }) and return {ok, existed}.',
@@ -494,9 +530,11 @@ if (!abortedByValidation) {
     fixedCount: fixedCount,
     resumeCount: effectiveResumeCount,
   }
-  const stopReason = abortedByValidation
-    ? (configErrors.length > 0 ? 'aborted_by_config' : 'aborted_by_validation')
-    : (converged ? 'converged' : 'max_rounds_reached')
+  const stopReason = schemaFailed
+    ? 'schema_invalid'
+    : abortedByValidation
+      ? (configErrors.length > 0 ? 'aborted_by_config' : 'aborted_by_validation')
+      : (converged ? 'converged' : 'max_rounds_reached')
   await agent(
     'Call iterate_transcript({operation:"capture", mode:"normal", goal:' + JSON.stringify(plan.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + rounds.length + ', findingsByRound:' + JSON.stringify(rounds.map(rr => (rr.findings && rr.findings.length) ? rr.findings.length : 0)) + ', stoppedReason:"' + stopReason + '", fixes:' + JSON.stringify(fixRecords) + ', checkpoint:' + JSON.stringify(obsCheckpoint) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
     { label: 'transcript:capture' }
@@ -508,6 +546,7 @@ return {
   maxRounds: maxRounds,
   converged: converged,
   abortedByValidation: abortedByValidation,
+  schemaFailed: schemaFailed,
   failedCommands: failedCommands,
   configErrors: configErrors,
   stoppedReason: stopReason,
@@ -528,12 +567,12 @@ return {
 Key rules for normal mode:
 - Fixers are the ONLY agents allowed to write files, and they must go through \`iterate_fix\` — never edit files directly. That is what gives every change a backup, a diff, and a rollback path. Reviewers read only. Architectural findings are reported, never auto-fixed.
 - Aggregate the current round deterministically (\`report.findings\`) before fixing, so fixes act on deduped/filtered/sorted findings.
-- **Schema validation & retry**: when \`reviewer.output_schema_validation\` is on (default), retry the round's reviewers up to 2 times (3 attempts total) when \`aggregate\` reports \`schemaValidation\` valid=false for it, then re-aggregate. Never forward schema-invalid findings into \`iterate_fix\`. If the output is still schema-invalid after the 3rd attempt, mark the round inconclusive (never report it as a clean convergence).
+- **Schema validation & retry**: when \`reviewer.output_schema_validation\` is on (default), retry the round's reviewers up to 2 times (3 attempts total) when \`aggregate\` reports \`schemaValidation\` valid=false for it, then re-aggregate. Never forward schema-invalid findings into \`iterate_fix\`. If the output is still schema-invalid after the 3rd attempt — or every reviewer subagent failed outright (no usable output at all) — the round is INCONCLUSIVE: \`break\` the loop, log a \`round_failed\` entry, set \`schemaFailed = true\`, and report \`stoppedReason:"schema_invalid"\`/\`"no_usable_reviewer_output"\`. Never report an inconclusive round as a clean convergence, and keep the checkpoint so the run can be resumed after the reviewer configuration is fixed.
 - Apply atomic fixes **per file**: one fixer agent handles all findings for a given file serially (so the same file is never edited concurrently); different files are fixed in parallel.
 - **Resume**: load the checkpoint first; if a previous run left one, continue from \`checkpoint.round + 1\` (its \`fixedCount\` and deduped \`findings\` are carried forward).
 - **Validate after every round** of fixes; on ANY validation failure, roll back the round's fixes via \`iterate_rollback\` and stop (the checkpoint is left in place so the run can be resumed). EXCEPTION: \`iterate_validate\` returning \`allowed:false\` means the command is simply not in \`validation.commands\` — a config gap, not broken code. In that case abort WITHOUT rolling back the round's fixes and surface the missing command + file so the user can fix the trust list.
 - **Checkpoint after every round**; clear it only when the iteration completes cleanly.
-- Stop when a round produces nothing to fix (converged) or maxReviewRounds is reached.
+- Stop when a round produces nothing to fix (converged), maxReviewRounds is reached, validation aborts the run, or a round yields no usable reviewer output (\`stoppedReason:"schema_invalid"\`).
 - Every round, every rollback, and the final report go to the append-only decision log.
 - Close with \`iterate_status\` metrics and surface the convergence indicators (fixed count, remaining architectural count, abort reason) in the final summary.
 

package/dist/tools/checkpoint.js

@@ -148,9 +148,16 @@ export function computeStatus(input) {
         findingsCount: Array.isArray(checkpoint?.findings) ? checkpoint.findings.length : 0,
         totalDecisionLogEntries: entries.length,
         hasCheckpoint: checkpoint !== null,
-        // A checkpoint left on disk means the previous run was interrupted before
-        // it could clear it — this is the durable "interruption" signal.
-        interrupted: checkpoint !== null,
+        // A checkpoint left on disk is the durable "the run did not finish" signal
+        // — EXCEPT when a decision-log entry is NEWER than the checkpoint: the
+        // workflow saves a checkpoint at the end of each round (right after that
+        // round's review_result log), so a live run proceeding past its last
+        // checkpoint would otherwise be flagged as "interrupted" for its whole
+        // duration. A fresh checkpoint (or no log at all) is genuinely leftover.
+        interrupted: checkpoint !== null &&
+            !(lastEntry != null &&
+                checkpoint.updatedAt &&
+                (Date.parse(checkpoint.updatedAt) || 0) >= (Date.parse(lastEntry.timestamp) || 0)),
         resumeCount: checkpoint?.resumeCount ?? 0,
         checkpoint,
         lastUpdated,
@@ -315,7 +322,7 @@ export function registerStatusTool(ctx) {
                     findingsCount: { type: 'integer' },
                     totalDecisionLogEntries: { type: 'integer' },
                     hasCheckpoint: { type: 'boolean' },
-                    interrupted: { type: 'boolean', description: 'True when a checkpoint exists, meaning the previous run was interrupted before finishing.' },
+                    interrupted: { type: 'boolean', description: 'True when a checkpoint exists and no decision-log entry is newer than it — the previous run left a checkpoint that nothing has resumed or progressed past.' },
                     resumeCount: { type: 'integer', description: 'How many times the current checkpoint has already been resumed.' },
                     lastUpdated: { oneOf: [{ type: 'string' }, { type: 'null' }] },
                     qualityGate: { type: 'json', description: 'v3.0: persisted quality-gate snapshot (.iterate/quality-gate.json), when present.' },

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.

package/dist/tools/fix.js

@@ -364,6 +364,7 @@ export function registerFixTool(ctx) {
                     linesRemoved: { type: 'integer' },
                     diffSummary: { type: 'string' },
                     backupPath: { type: 'string' },
+                    warning: { type: 'string' },
                     error: { type: 'string' },
                 },
             },
@@ -451,6 +452,16 @@ export function registerFixTool(ctx) {
                 if (findFixRecord(registry, id)) {
                     return { ok: false, error: `finding already fixed this run (id: ${id})`, id };
                 }
+                // No-op guard: content-identical "fixes" (e.g. a fixer that re-sent the
+                // file unchanged) must never burn a backup, a write, or a registry/success
+                // record. Placed after the registry check so a re-sent fix of an id that
+                // was ALREADY fixed is still reported as "already fixed this run".
+                if (added === 0 && removed === 0) {
+                    return {
+                        ok: false,
+                        error: `no changes: the supplied content for ${file} is identical to the current content — apply a real edit`,
+                    };
+                }
                 const target = resolveProjectFile(projectRoot, file);
                 if (!target.ok)
                     return { ok: false, error: target.reason };
@@ -521,12 +532,15 @@ export function registerFixTool(ctx) {
                     }
                     return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` };
                 }
-                appendDecisionEntry(projectRoot, {
+                const logRes = appendDecisionEntry(projectRoot, {
                     timestamp,
                     round: args.round,
                     type: 'atomic_fix',
                     data: { id, file, finding: finding.summary, linesAdded: added, linesRemoved: removed },
                 });
+                // The fix itself succeeded, but a decision-log write failure would leave
+                // the audit trail incomplete — surface it (warning, not fatal) so the
+                // model/UI knows the record was not persisted.
                 return {
                     ok: true,
                     id,
@@ -536,6 +550,7 @@ export function registerFixTool(ctx) {
                     linesRemoved: removed,
                     diffSummary: record.diffSummary,
                     backupPath,
+                    ...(logRes.error ? { warning: logRes.error } : {}),
                 };
             });
             return result;
@@ -696,6 +711,7 @@ export function registerRollbackTool(ctx) {
                     ok: { type: 'boolean', required: true },
                     id: { type: 'string' },
                     file: { type: 'string' },
+                    warning: { type: 'string' },
                     error: { type: 'string' },
                 },
             },
@@ -736,7 +752,7 @@ export function registerRollbackTool(ctx) {
             catch (err) {
                 return { ok: false, error: `failed to update fix registry: ${String(err)}` };
             }
-            appendDecisionEntry(projectRoot, {
+            const logRes = appendDecisionEntry(projectRoot, {
                 timestamp: new Date().toISOString(),
                 round: record.round,
                 type: 'revert',
@@ -747,7 +763,12 @@ export function registerRollbackTool(ctx) {
             // a missing/corrupt transcript is left untouched and never breaks the
             // rollback flow.
             await markFixRolledBackInTranscript(projectRoot, id);
-            return { ok: true, id, file: record.finding.file };
+            return {
+                ok: true,
+                id,
+                file: record.finding.file,
+                ...(logRes.error ? { warning: logRes.error } : {}),
+            };
         },
     }));
 }

package/dist/tools/history.js

@@ -84,7 +84,7 @@ export function registerHistoryTool(ctx) {
             },
             limit: {
                 type: 'integer',
-                description: `Max entries to return (default: ${DEFAULT_LIMIT}, cap: ${MAX_LIMIT}). Newest first.`,
+                description: `Max entries to return (default: ${DEFAULT_LIMIT}, cap: ${MAX_LIMIT}). Returns the newest window in chronological order.`,
             },
             path: {
                 type: 'string',

package/dist/tools/prune.js

@@ -23,12 +23,12 @@
  *   - dryRun=true by default — the caller must explicitly opt into deletion.
  *   - Each deletion is logged to the decision log (when not dry-run).
  */
-import { existsSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
+import { existsSync, readdirSync, rmSync, unlinkSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { writeTextAtomic, writeJsonAtomic } from "../atomic-fs.js";
-import { readDecisionEntries, appendDecisionEntry } from "./decision-log.js";
+import { readDecisionEntries, appendDecisionEntry, acquireLogLock } from "./decision-log.js";
 import { readRegistry, recomputeRoundCounts } from "./fix.js";
 import { readExperienceBank, writeExperienceBank } from "./experience-store.js";
 import { readDefenseEvents, writeDefenseEvents } from "./defense-store.js";
@@ -143,8 +143,22 @@ export function inspectPrune(projectRoot, retainDays) {
     // 1. Decision-log entries older than retainDays.
     const entries = readDecisionEntries(projectRoot);
     const oldLogEntries = entries.filter((e) => e.timestamp < cutoff).length;
-    // 2. Checkpoint presence.
+    // 2. Checkpoint presence. A checkpoint is only STALE once it is older than
+    // retainDays — a fresh checkpoint means a run was interrupted recently and
+    // may still be resumed, so `hasCheckpoint` is kept as pure existence while
+    // `checkpointStale` decides whether a prune actually deletes it.
     const hasCheckpoint = existsSync(checkpointPath(projectRoot));
+    let checkpointStale = false;
+    if (hasCheckpoint) {
+        try {
+            const st = statSync(checkpointPath(projectRoot));
+            if (st && st.mtimeMs < Date.parse(cutoff))
+                checkpointStale = true;
+        }
+        catch {
+            checkpointStale = true; // unreadable mtime — treat as garbage / deletable
+        }
+    }
     // 3. Stale fix backups: .bak files whose fix-id prefix is not in the registry.
     const registry = readRegistry(projectRoot);
     const activeIds = new Set();
@@ -204,6 +218,7 @@ export function inspectPrune(projectRoot, retainDays) {
     return {
         oldLogEntries,
         hasCheckpoint,
+        checkpointStale,
         staleBackups,
         staleTemps,
         emptyRounds,
@@ -234,26 +249,36 @@ export function inspectPrune(projectRoot, retainDays) {
  */
 function rewriteDecisionLogKeepingRecent(projectRoot, cutoff) {
     const logPath = join(iterateDir(projectRoot), 'decision-log.jsonl');
-    for (let attempt = 0; attempt < MAX_LOG_REWRITE_RETRIES; attempt++) {
-        try {
-            const entries = readDecisionEntries(projectRoot);
-            const kept = entries.filter((e) => e.timestamp >= cutoff);
-            const deleted = entries.length - kept.length;
-            if (deleted === 0)
-                return { deleted: 0 };
-            writeTextAtomic(logPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n');
-            // A concurrent appender may have landed new lines after our read. If the
-            // log grew during the write window, re-read and prune again instead of
-            // accepting a lost audit trail.
-            const after = readDecisionEntries(projectRoot);
-            if (after.length <= kept.length)
-                return { deleted };
-        }
-        catch (err) {
-            return { deleted: 0, error: `failed to rewrite decision log: ${String(err)}` };
+    // Take the cross-process log lock for the ENTIRE loop: with the mutex held,
+    // no concurrent appender can slip a fresh line into the read-before-rewrite
+    // window, so the first attempt is nearly always the only one. (The retry
+    // loop stays as defense-in-depth for the lock-unavailable path.)
+    const release = acquireLogLock(projectRoot);
+    try {
+        for (let attempt = 0; attempt < MAX_LOG_REWRITE_RETRIES; attempt++) {
+            try {
+                const entries = readDecisionEntries(projectRoot);
+                const kept = entries.filter((e) => e.timestamp >= cutoff);
+                const deleted = entries.length - kept.length;
+                if (deleted === 0)
+                    return { deleted: 0 };
+                writeTextAtomic(logPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n');
+                // A concurrent appender (cross-process, lock-unavailable path) may have
+                // landed new lines after our read. If the log grew during the write
+                // window, re-read and prune again instead of accepting a lost audit trail.
+                const after = readDecisionEntries(projectRoot);
+                if (after.length <= kept.length)
+                    return { deleted };
+            }
+            catch (err) {
+                return { deleted: 0, error: `failed to rewrite decision log: ${String(err)}` };
+            }
         }
+        return { deleted: 0, error: `failed to rewrite decision log after ${MAX_LOG_REWRITE_RETRIES} attempts` };
+    }
+    finally {
+        release();
     }
-    return { deleted: 0, error: `failed to rewrite decision log after ${MAX_LOG_REWRITE_RETRIES} attempts` };
 }
 /**
  * Execute the prune: apply every cleanable item reported by `inspectPrune`.
@@ -282,8 +307,10 @@ export function executePrune(projectRoot, retainDays, report) {
         if (error)
             result.errors.push(error);
     }
-    // 2. Remove checkpoint.
-    if (report.hasCheckpoint) {
+    // 2. Remove checkpoint — ONLY when it is actually stale (older than
+    // retainDays). A fresh checkpoint is a live resume point for a recently
+    // interrupted run; pruning it would silently destroy the ability to resume.
+    if (report.checkpointStale) {
         try {
             rmSync(checkpointPath(projectRoot), { force: true });
             result.deletedCheckpoint = true;
@@ -412,7 +439,7 @@ export function registerPruneTool(ctx) {
                     const lines = [
                         `[dry-run] prune report (retainDays=${value.retainDays}):`,
                         `  Decision-log entries to remove: ${report?.oldLogEntries ?? '?'} (of ${report?.totalLogEntries ?? '?'})`,
-                        `  Checkpoint to delete: ${report?.hasCheckpoint ? 'yes' : 'none'}`,
+                        `  Checkpoint to delete: ${report?.checkpointStale ? 'yes (stale)' : report?.hasCheckpoint ? 'no (fresh — resume point, kept)' : 'none'}`,
                         `  Stale backups to delete: ${report?.staleBackups?.length ?? 0}`,
                         `  Stray temp files to delete: ${report?.staleTemps?.length ?? 0}`,
                         `  Empty rounds to trim: ${report?.emptyRounds?.length ?? 0}`,
@@ -459,8 +486,10 @@ export function registerPruneTool(ctx) {
                 };
             }
             const result = executePrune(projectRoot, retainDays, report);
-            // Log the prune to the decision log.
-            appendDecisionEntry(projectRoot, {
+            // Log the prune to the decision log. The mutations already happened, so
+            // a failed log append is reported via `errors` — a silent audit miss
+            // (F2) must never pretend every deletion was recorded.
+            const logRes = appendDecisionEntry(projectRoot, {
                 timestamp: new Date().toISOString(),
                 round: 0,
                 type: 'decision',
@@ -475,6 +504,8 @@ export function registerPruneTool(ctx) {
                     deletedDefenseEvents: result.deletedDefenseEvents,
                 },
             });
+            if (logRes.error)
+                result.errors.push(logRes.error);
             return {
                 ok: true,
                 dryRun: false,