iterate-plugin 3.5.5 → 3.5.7

package/dist/config-loader.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve, sep } from 'node:path';
 import yaml from 'js-yaml';
@@ -201,7 +201,27 @@ export function resolveProjectRoot(input, sessionCwd) {
     if (raw.includes('\0')) {
         return { ok: false, reason: 'Refusing project root containing NUL bytes.' };
     }
-    const root = raw ? resolve(raw) : resolve(effectiveCwd(sessionCwd));
+    const rootLexical = raw ? resolve(raw) : resolve(effectiveCwd(sessionCwd));
+    // Collapse symlinks (documented contract: "collapsing `..` and symlinks") —
+    // a path through a symlinked directory must resolve to its REAL location so
+    // two aliases of the same project share one `.iterate/` state, and tools can
+    // never read outside the resolved root via a link. Only when the path
+    // exists: a not-yet-created target (dirs created through the tools) keeps
+    // the lexical path so the caller can still write into it. The filesystem
+    // root check runs against the NORMALIZED path, so a symlink to `/` is
+    // refused too.
+    let root = rootLexical;
+    try {
+        if (existsSync(rootLexical)) {
+            const real = realpathSync(rootLexical);
+            if (real)
+                root = real;
+        }
+    }
+    catch {
+        // realpath can throw on a broken link or a permission fence — keep the
+        // lexical path (existing behavior) rather than failing the resolution.
+    }
     if (!root || root === sep) {
         return { ok: false, reason: 'Refusing filesystem root as project root.' };
     }

package/dist/config-write.js

@@ -25,6 +25,8 @@ export const MAX_MAX_ROUNDS = 100;
 export const MAX_ATOMIC_MAX_LINES = 10_000;
 /** Upper bound on `atomic.max_adjacent_methods`. */
 export const MAX_MAX_ADJACENT_METHODS = 200;
+/** Upper bound on `reviewer.scope_chunk_size` (files per reviewer task batch). */
+export const MAX_SCOPE_CHUNK_SIZE = 1000;
 /** Keep at most this many timestamped config backups (older ones are removed). */
 export const MAX_CONFIG_BACKUPS = 5;
 /**
@@ -78,6 +80,32 @@ export function validateConfigUpdates(updates) {
             errors.push(`updates.max_rounds must be an integer between 1 and ${MAX_MAX_ROUNDS}`);
         }
     }
+    if ('reasoning_effort' in updates) {
+        if (updates.reasoning_effort !== undefined &&
+            updates.reasoning_effort !== 'low' &&
+            updates.reasoning_effort !== 'medium' &&
+            updates.reasoning_effort !== 'high') {
+            errors.push('updates.reasoning_effort must be "low", "medium", or "high"');
+        }
+    }
+    if ('reviewer' in updates) {
+        const rv = updates.reviewer;
+        if (!rv || typeof rv !== 'object') {
+            errors.push('updates.reviewer must be an object');
+        }
+        else {
+            for (const boolKey of ['output_schema_validation', 'evidence_validation', 'coverage_validation']) {
+                if (rv[boolKey] !== undefined && typeof rv[boolKey] !== 'boolean') {
+                    errors.push(`updates.reviewer.${boolKey} must be a boolean`);
+                }
+            }
+            if (rv.scope_chunk_size !== undefined &&
+                (typeof rv.scope_chunk_size !== 'number' || !Number.isInteger(rv.scope_chunk_size) ||
+                    rv.scope_chunk_size < 1 || rv.scope_chunk_size > MAX_SCOPE_CHUNK_SIZE)) {
+                errors.push(`updates.reviewer.scope_chunk_size must be an integer between 1 and ${MAX_SCOPE_CHUNK_SIZE}`);
+            }
+        }
+    }
     if ('review' in updates) {
         const r = updates.review;
         if (!r || typeof r !== 'object') {

package/dist/evidence.js

@@ -83,7 +83,11 @@ export function verifyLineBounds(line, text) {
     if (line === undefined || line === null || line === WHOLE_FILE_LINE) {
         return { inBounds: true, lineTotal };
     }
-    if (line < 1)
+    // Only a positive INTEGER is a valid line anchor. A fractional line (e.g.
+    // 3.7 from a bypassed schema) or a negative value is out of bounds — a
+    // fractional line "within" the file would otherwise be accepted and poison
+    // the evidence trail with a location nothing can jump to.
+    if (line < 1 || !Number.isInteger(line))
         return { inBounds: false, lineTotal };
     return { inBounds: line <= lineTotal, lineTotal };
 }

package/dist/meta-review.js

@@ -129,7 +129,11 @@ export function metaReviewReport(report) {
         ? reportRounds[reportRounds.length - 1].round
         : null;
     const lastRoundNew = lastRecordedRound !== null && lastRecordedRound > 0
-        ? Number(findingsByRound[lastRecordedRound - 1] ?? 0)
+        // Over-cap rounds are FOLDED by aggregateRounds into the final slot, so a
+        // reported round number may exceed the array length — read the SAME
+        // clamped index buildReviewReport/computeConvergence use, or a real
+        // over-cap round would be mis-read as 0 new (flag mismatch).
+        ? Number(findingsByRound[Math.min(lastRecordedRound, findingsByRound.length) - 1] ?? 0)
         : null;
     const expectedConverged = lastRoundNew === 0;
     if (report.convergence?.converged !== expectedConverged) {

package/dist/review.js

@@ -144,14 +144,17 @@ export function aggregateRounds(rounds, maxReviewRounds) {
     }
     // 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 = [];
-    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 = 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 };
 }
@@ -246,7 +249,12 @@ export function buildReviewReport(input) {
         if (typeof r.round === 'number' && r.round > lastRound)
             lastRound = r.round;
     }
-    const lastRoundCount = lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0;
+    // `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 && 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).
     const computed = summarize(sorted);
@@ -517,6 +525,9 @@ export function attachmentClause(attachments) {
 export function reviewerTaskPrompt(input) {
     const parts = [];
     parts.push(`You are the "${input.dimension}" reviewer for the iterate review.`, `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}`);
     }
@@ -574,6 +585,11 @@ 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 : [];
@@ -632,6 +648,7 @@ export function buildReviewPlan(input) {
                     scopeFiles: batch,
                     focus: focusMap.get(d),
                     attachments,
+                    effort: reasoningEffort ?? undefined,
                 }),
                 findingsSchema: findingsSchema(),
             });
@@ -647,5 +664,6 @@ export function buildReviewPlan(input) {
         changedFiles: effectiveChangedOnly ? changedFiles : [],
         fallbackToFull,
         attachments,
+        reasoningEffort,
     };
 }

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,13 @@ 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
+// Slot index of the current round within this run's rounds array. A resumed
+// run starts at startRound > 1, so the round NUMBER is not a valid array index.
+let roundSlot = -1
 
 phase('transcript')
 // Read any steering nudge written (via iterate_transcript nudge) for this run's reviewers.
@@ -92,9 +99,14 @@ const steering = transRead && typeof transRead.nudge === 'string' && transRead.n
 phase('review')
 for (let r = 1; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — finding NEW issues only')
+  roundSlot = rounds.length
   let agg = null
   let schemaInvalid = false
   let attempts = 0
+  // Declared OUTSIDE the do-block: it is read after the retry loop exits, and a
+  // block-scoped const here raised ReferenceError at runtime (crashing both
+  // canonical workflows after the first round).
+  let reviewersOk = true
   do {
     attempts += 1
     // Schema validation retry: on the 2nd+ pass, nudge reviewers toward strict JSON.
@@ -117,6 +129,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.
+    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 : [])),
@@ -124,7 +142,7 @@ for (let r = 1; r <= maxRounds; r++) {
       // gate can compare self-reported reads against the assigned inventory.
       readFiles: [].concat(...raw.map(x => x && Array.isArray(x.readFiles) ? x.readFiles : [])),
     }
-    if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
+    if (roundSlot < rounds.length) rounds[roundSlot] = thisRound; else rounds.push(thisRound)
     // Deterministic aggregate: cross-round dedupe + known_intentional filter + severity sort.
     agg = await agent(
       'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
@@ -144,23 +162,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 +221,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 +289,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,9 +303,16 @@ 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
+// Slot index of the current round within this run's rounds array. A resumed
+// run starts at startRound > 1, so the round NUMBER is not a valid array index.
+let roundSlot = -1
+// Highest round number actually executed by THIS run (carried so a resumed run
+// reports its true round, not the count of rounds it happened to run).
+let lastRound = startRound - 1
 
 // Read any steering nudge intended for this run's reviewers.
 const transRead = await agent(
@@ -287,6 +324,8 @@ const steering = transRead && typeof transRead.nudge === 'string' && transRead.n
 phase('loop')
 for (let r = startRound; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — review current state, fix atomics via iterate_fix, validate')
+  roundSlot = rounds.length
+  lastRound = r
   // Audit-trail: record the round start (SKILL.md Phase 4 requires per-round records).
   await agent(
     'Call iterate_decision_log({operation:"append", type:"round_start", round:' + r + ', data:{maxRounds:' + maxRounds + ', fixedSoFar:' + fixedCount + '}})',
@@ -295,6 +334,10 @@ for (let r = startRound; r <= maxRounds; r++) {
   let agg = null
   let schemaInvalid = false
   let attempts = 0
+  // Declared OUTSIDE the do-block: it is read after the retry loop exits, and a
+  // block-scoped const here raised ReferenceError at runtime (crashing both
+  // canonical workflows after the first round).
+  let reviewersOk = true
   do {
     attempts += 1
     // Schema validation retry: on the 2nd+ pass, nudge reviewers toward strict JSON.
@@ -315,12 +358,16 @@ 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.
+    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 : [])),
       readFiles: [].concat(...raw.map(x => x && Array.isArray(x.readFiles) ? x.readFiles : [])),
     }
-    if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
+    if (roundSlot < rounds.length) rounds[roundSlot] = thisRound; else rounds.push(thisRound)
 
     // Deterministic dedupe / known_intentional filter / severity sort for this round.
     // \`fixedCount\` is threaded into the report summary so the client dashboard can
@@ -338,10 +385,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)
@@ -466,7 +522,7 @@ for (let r = startRound; r <= maxRounds; r++) {
 
 phase('report')
 await agent(
-  'Call iterate_decision_log({operation:"append", type:"report", round:' + rounds.length +
+  'Call iterate_decision_log({operation:"append", type:"report", round:' + lastRound +
   ', data:{mode:"normal", fixed:' + fixedCount + ', architectural:' + architectural.length + '}})',
   { label: 'report:log' }
 )
@@ -475,7 +531,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}.',
@@ -489,25 +545,28 @@ if (!abortedByValidation) {
   // would hide the very thing F5 is meant to resume. Reflect what is on disk.
   const obsCheckpoint = {
     mode: 'normal',
-    round: rounds.length,
+    round: lastRound,
     maxRounds: maxRounds,
     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"}.',
+    'Call iterate_transcript({operation:"capture", mode:"normal", goal:' + JSON.stringify(plan.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + lastRound + ', 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' }
   )
 return {
   mode: 'normal',
   goal: plan.goal,
-  roundsExecuted: rounds.length,
+  roundsExecuted: lastRound,
   maxRounds: maxRounds,
   converged: converged,
   abortedByValidation: abortedByValidation,
+  schemaFailed: schemaFailed,
   failedCommands: failedCommands,
   configErrors: configErrors,
   stoppedReason: stopReason,
@@ -528,12 +587,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

@@ -122,6 +122,17 @@ function recountEntries(filePath) {
         return 1;
     }
 }
+/**
+ * Drop the cached entry count for a log file. The cache is keyed by the log
+ * path and assumes "same byte size ⇒ same entry count"; a prune rewrite
+ * (temp + atomic rename) replaces the file with a DIFFERENT number of entries,
+ * so only a stale-cache invalidation keeps the fast path honest. Without it, a
+ * rewrite that lands on the exact same byte size as the previous append would
+ * make the next append report a wrong `count`.
+ */
+export function invalidateLogCountCache(filePath) {
+    entryCountCache.delete(filePath);
+}
 /** All valid DecisionLogEntry `type` values (must stay in sync with Types). */
 const VALID_ENTRY_TYPES = new Set([
     'round_start',

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, acquireLogLock } from "./decision-log.js";
+import { readDecisionEntries, appendDecisionEntry, acquireLogLock, invalidateLogCountCache } 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,
@@ -248,6 +263,12 @@ function rewriteDecisionLogKeepingRecent(projectRoot, cutoff) {
                 if (deleted === 0)
                     return { deleted: 0 };
                 writeTextAtomic(logPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n');
+                // The append-side entry-count cache is keyed by path and assumes "same
+                // byte size ⇒ same count"; the rename above replaced the file with a
+                // different number of entries, so drop the stale cache or the next
+                // append can report a wrong entryCount when the sizes coincidentally
+                // match.
+                invalidateLogCountCache(logPath);
                 // 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.
@@ -292,8 +313,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;
@@ -422,7 +445,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}`,