iterate-plugin 3.5.4 → 3.5.6

package/src/review.ts

@@ -39,17 +39,18 @@ export const SEVERITY_RANK: Record<ReviewFinding['severity'], number> = {
 export function sortFindings(findings: ReviewFinding[]): ReviewFinding[] {
   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)
   })
 }
 
@@ -161,13 +162,17 @@ export function aggregateRounds(
   // Clamp the allocation bound so a hostile round number cannot OOM the tool.
   const effectiveMax = Math.min(maxRound, Math.max(1, roundCap * 2))
 
-  const findingsByRound: number[] = []
-  for (let r = 1; r <= effectiveMax; r++) {
-    let count = 0
-    for (const key of firstRoundByKey.keys()) {
-      if (firstRoundByKey.get(key) === r) count++
-    }
-    findingsByRound.push(count)
+  const findingsByRound: number[] = new Array(effectiveMax).fill(0)
+  for (const key of firstRoundByKey.keys()) {
+    const firstRound = firstRoundByKey.get(key) ?? 1
+    // Fold rounds BEYOND the allocation bound into the highest slot instead of
+    // dropping them: a finding first seen in an over-cap round was previously
+    // invisible to `findingsByRound`, so a run whose final rounds exceeded the
+    // cap looked "converged" even though a real round found new issues. Folding
+    // keeps the counts truthful (the sum still equals totalFindings) while the
+    // memory bound stays fixed.
+    const idx = Math.min(firstRound, effectiveMax) - 1
+    findingsByRound[idx] = (findingsByRound[idx] || 0) + 1
   }
 
   return { findings: dedupeFindings(merged), findingsByRound, firstRoundByKey }
@@ -281,8 +286,13 @@ export function buildReviewReport(input: {
   for (const r of filteredRounds) {
     if (typeof r.round === 'number' && r.round > lastRound) lastRound = r.round
   }
+  // `lastRound` can exceed the array length when over-cap rounds were FOLDED
+  // into the last slot (see aggregateRounds). Read the same clamped index
+  // computeConvergence uses, so a real over-cap round is never mis-read as 0
+  // new findings (which would falsely report "converged").
+  const idx = Math.min(lastRound, findingsByRound.length) - 1
   const lastRoundCount =
-    lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0
+    lastRound > 0 && idx >= 0 ? (findingsByRound[idx] ?? 0) : 0
   const converged = filteredRounds.length > 0 && lastRoundCount === 0
 
   // Attach the normal-mode fix count to the summary (dry-run leaves it absent).
@@ -629,6 +639,12 @@ export function reviewerTaskPrompt(input: {
    * every dimension reviewer inspects/considers them before judging.
    */
   attachments?: ReviewAttachment[]
+  /**
+   * Configured reasoning effort ('low' | 'medium' | 'high') to apply to this
+   * review pass. Injected as a directive so the harness can honor it when
+   * running each reviewer subagent. Omitted → follow the provider default.
+   */
+  effort?: 'low' | 'medium' | 'high'
 }): string {
   const parts: string[] = []
   parts.push(
@@ -636,6 +652,9 @@ export function reviewerTaskPrompt(input: {
     `Goal: ${input.goal}`,
     `Scope: ${input.scope === 'full' ? 'entire codebase' : 'changed files only'}.`,
   )
+  if (input.effort) {
+    parts.push(`Reasoning effort for this review pass: ${input.effort}.`)
+  }
   if (input.focus) {
     parts.push(`FOCUS: ${input.focus}`)
   }
@@ -743,6 +762,12 @@ export function buildReviewPlan(input: {
   fallbackToFull: boolean
   /** The attachments threaded into every reviewer prompt (empty when none). */
   attachments: ReviewAttachment[]
+  /**
+   * Configured reasoning effort carried on the plan for the orchestrator to
+   * honor (null when unset → provider default). Also injected as a directive
+   * into every dimension's reviewer prompt.
+   */
+  reasoningEffort: 'low' | 'medium' | 'high' | null
 } {
   // Defensive reads: a malformed config (e.g. `dimensions` as a non-array, or
   // `review`/`atomic` missing) must degrade to sane defaults instead of
@@ -750,6 +775,12 @@ export function buildReviewPlan(input: {
   const language = input.config.language === 'zh' ? 'Chinese (中文)' : 'English'
   const goal = input.config.goal ?? ''
   const configuredScope = input.config.review?.scope ?? 'full'
+  const reasoningEffort =
+    input.config.reasoning_effort === 'low' ||
+    input.config.reasoning_effort === 'medium' ||
+    input.config.reasoning_effort === 'high'
+      ? input.config.reasoning_effort
+      : null
   const dimensions = Array.isArray(input.config.dimensions) ? input.config.dimensions : []
   const maxLines = input.config.atomic?.max_lines ?? 20
   const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : []
@@ -815,6 +846,7 @@ export function buildReviewPlan(input: {
           scopeFiles: batch,
           focus: focusMap.get(d),
           attachments,
+          effort: reasoningEffort ?? undefined,
         }),
         findingsSchema: findingsSchema(),
       })
@@ -831,5 +863,6 @@ export function buildReviewPlan(input: {
     changedFiles: effectiveChangedOnly ? changedFiles : [],
     fallbackToFull,
     attachments,
+    reasoningEffort,
   }
 }

package/src/skill-prompt.ts

@@ -20,7 +20,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.
@@ -81,6 +81,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.
@@ -118,6 +122,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 : [])),
@@ -145,23 +155,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
   }
 }
 
@@ -197,8 +214,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 },
@@ -260,7 +282,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
@@ -274,6 +296,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
@@ -316,6 +339,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 : [])),
@@ -339,10 +366,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)
@@ -357,10 +393,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).',
@@ -476,7 +512,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}.',
@@ -495,9 +531,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' }
@@ -509,6 +547,7 @@ return {
   maxRounds: maxRounds,
   converged: converged,
   abortedByValidation: abortedByValidation,
+  schemaFailed: schemaFailed,
   failedCommands: failedCommands,
   configErrors: configErrors,
   stoppedReason: stopReason,
@@ -529,12 +568,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/src/tools/checkpoint.ts

@@ -177,9 +177,17 @@ 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,
@@ -354,7 +362,7 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
             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/src/tools/decision-log.ts

@@ -1,4 +1,14 @@
-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 type { JsonValue } from '@deepseek-ai/dsh-util-values'
@@ -8,6 +18,109 @@ import type { DecisionLogEntry } from '../types.ts'
 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: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+/** Synchronous busy-wait sleep (Atomics.wait is a reliable sleep in Node). */
+function sleepSync(ms: number): void {
+  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: string): () => void {
+  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: number | null = null
+    try {
+      fd = openSync(lockPath, 'wx')
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).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<string, { size: number; count: number }>()
+
+/** Line-count the log file from scratch (entries = non-empty JSON lines). */
+function recountEntries(filePath: string): number {
+  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<DecisionLogEntry['type']>([
   'round_start',
@@ -57,23 +170,30 @@ function logPath(projectRoot: string): string {
  * miss without failing the mutation they already performed.
  */
 export function appendDecisionEntry(projectRoot: string, entry: DecisionLogEntry): { count: number; path: string; error?: string } {
-  let filePath: string
-  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
-  } catch {
-    count = 1
+    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)}` }
+    }
+  } finally {
+    release()
   }
-  return { count, path: filePath }
 }
 
 /**

package/src/tools/fix.ts

@@ -366,6 +366,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
             linesRemoved: { type: 'integer' },
             diffSummary: { type: 'string' },
             backupPath: { type: 'string' },
+            warning: { type: 'string' },
             error: { type: 'string' },
           },
         },
@@ -456,6 +457,17 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           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 }
 
@@ -528,13 +540,16 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           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,
@@ -544,6 +559,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           linesRemoved: removed,
           diffSummary: record.diffSummary,
           backupPath,
+          ...(logRes.error ? { warning: logRes.error } : {}),
         }
         })
         return result
@@ -710,6 +726,7 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
             ok: { type: 'boolean', required: true },
             id: { type: 'string' },
             file: { type: 'string' },
+            warning: { type: 'string' },
             error: { type: 'string' },
           },
         },
@@ -749,7 +766,7 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
           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',
@@ -762,7 +779,12 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
         // 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/src/tools/history.ts

@@ -102,7 +102,7 @@ export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<t
         },
         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',