iterate-plugin 3.5.5 → 3.5.6

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,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)
@@ -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/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,7 +23,7 @@
  *   - 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";
@@ -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,
@@ -292,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;
@@ -422,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}`,

package/dist/tools/transcript.js

@@ -148,7 +148,7 @@ export function registerTranscriptTool(ctx) {
                 description: 'For `capture`: array of applied fixes [{id, file, round, summary, linesAdded, linesRemoved, success}].',
             },
             refReadFiles: { type: 'json', description: 'For `capture`: flat array of all read files across rounds (optional).' },
-            stoppedReason: { type: 'string', description: 'For `capture`: why the run ended — "converged" | "max_rounds_reached" | "aborted_by_validation". When omitted, derived from the convergence trend (trailing 0 = converged, otherwise = max_rounds_reached once a round ran).' },
+            stoppedReason: { type: 'string', description: 'For `capture`: why the run ended — "converged" | "max_rounds_reached" | "aborted_by_validation" | "aborted_by_config" | "schema_invalid" | "no_usable_reviewer_output" | "inconclusive". When omitted, derived from the convergence trend (trailing 0 = converged, otherwise = max_rounds_reached once a round ran).' },
             text: { type: 'string', description: 'For `nudge`: steering text to set (or null to clear).' },
             path: { type: 'string', description: 'Project root directory (default: current working directory).' },
         },
@@ -344,13 +344,24 @@ function rehydrateBuilder(manifest, approval) {
         maxRounds: manifest.maxRounds,
     });
     for (const r of Array.isArray(manifest.rounds) ? manifest.rounds : []) {
+        // A malformed/null round row must be skipped, never a throw (the caller
+        // wraps rehydrate in a fallback, but preserving sibling rows is better).
+        if (!r || typeof r !== 'object')
+            continue;
         builder.roundStart(r.round, manifest.maxRounds);
         for (const t of Array.isArray(r.threads) ? r.threads : []) {
-            builder.reviewerStart(t.dimension || 'review', t.attempt || 1);
-            builder.reviewerMessage((t.messages ?? []).join('\n'));
-            builder.reviewerRead(t.readFiles ?? []);
-            for (const f of t.findings ?? [])
-                builder.reviewerFindings([f]);
+            // restoreThread (not reviewerStart + reviewerMessage(join)) preserves the
+            // message ARRAY boundaries and the thread's own dimension: rehydration
+            // previously collapsed each thread's messages into one string and, once a
+            // round hit the per-round thread cap, silently DROPPED the extra threads
+            // / mis-merged their findings into the previous dimension's thread.
+            builder.restoreThread(r.round, {
+                dimension: t.dimension,
+                attempt: t.attempt,
+                messages: t.messages,
+                readFiles: t.readFiles,
+                findings: t.findings,
+            });
         }
     }
     for (let idx = 0; idx < (manifest.convergence ?? []).length; idx += 1) {

package/dist/transcript.js

@@ -82,7 +82,9 @@ function normalizeFinding(input) {
     const severity = sev === 'critical' || sev === 'high' || sev === 'medium' || sev === 'low'
         ? sev
         : 'low';
-    const line = typeof f.line === 'number' && Number.isFinite(f.line) ? f.line : 0;
+    // Only a non-negative integer is a real line anchor; a fractional/malformed
+    // value (e.g. 3.7 from a bypassed schema) must not leak into the manifest.
+    const line = typeof f.line === 'number' && Number.isInteger(f.line) && f.line >= 0 ? f.line : 0;
     return {
         dimension,
         file,
@@ -219,7 +221,9 @@ export class ReviewTranscriptBuilder {
         const att = typeof attempt === 'number' && Number.isFinite(attempt) ? Math.floor(attempt) : 1;
         this.roundStart(this.round);
         const live = this.rounds[this.round - 1];
-        if (live && this.threadCount(live) < MAX_THREADS_PER_ROUND) {
+        if (!live)
+            return;
+        if (this.threadCount(live) < MAX_THREADS_PER_ROUND) {
             live.threads.push({
                 dimension: dim || 'review',
                 attempt: att > 0 ? att : 1,
@@ -228,6 +232,78 @@ export class ReviewTranscriptBuilder {
                 findings: [],
             });
         }
+        else {
+            // Thread cap reached: route the extra dimension/retry into ONE shared
+            // "other" overflow thread instead of silently dropping it. A dropped
+            // reviewerStart used to leave `currentThread()` pointing at the PREVIOUS
+            // dimension's thread, so its findings were mis-attributed to that
+            // dimension. The overflow thread stays bounded (at most ONE extra thread
+            // per round) while keeping over-cap findings attributable to "other".
+            let overflow = live.threads.find((t) => t.dimension === 'other');
+            if (!overflow) {
+                overflow = {
+                    dimension: 'other',
+                    attempt: att > 0 ? att : 1,
+                    messages: [],
+                    readFiles: [],
+                    findings: [],
+                };
+                live.threads.push(overflow);
+            }
+        }
+        this.touch();
+    }
+    /**
+     * Restore ONE persisted thread during rehydration, preserving the message
+     * ARRAY boundaries (a rehydrated manifest is re-serialized on the next nudge
+     * edit, so collapsed messages would silently rewrite the evidence) and the
+     * thread's own dimension (never merging it into a previous dimension's
+     * thread). Bypasses the live per-round cap — the manifest already enforced
+     * it at capture time — but every restored field is hard-bounded so a hostile
+     * hand-edited manifest can never blow up memory.
+     */
+    restoreThread(round, thread) {
+        const r = typeof round === 'number' && Number.isFinite(round)
+            ? Math.min(Math.floor(round), MAX_ROUNDS)
+            : 1;
+        this.roundStart(r);
+        const live = this.rounds[this.round - 1];
+        if (!live)
+            return;
+        if (!thread || typeof thread !== 'object')
+            return;
+        // Hostile-manifest guard: keep the live hard bound (with headroom for the
+        // single overflow thread) and newest-first truncate beyond it.
+        if (live.threads.length >= MAX_THREADS_PER_ROUND * 2 + 1)
+            return;
+        const dim = typeof thread.dimension === 'string' && thread.dimension.trim()
+            ? thread.dimension.trim()
+            : 'review';
+        const att = typeof thread.attempt === 'number' && Number.isFinite(thread.attempt)
+            ? Math.floor(thread.attempt)
+            : 1;
+        const t = {
+            dimension: dim,
+            attempt: att > 0 ? att : 1,
+            messages: [],
+            readFiles: [],
+            findings: [],
+        };
+        const messages = Array.isArray(thread.messages) ? thread.messages : [];
+        for (const m of messages.slice(0, MAX_MESSAGES_PER_THREAD)) {
+            if (typeof m === 'string' && m.trim())
+                t.messages.push(m);
+        }
+        if (Array.isArray(thread.readFiles)) {
+            t.readFiles.push(...dedupePaths(thread.readFiles));
+        }
+        if (Array.isArray(thread.findings)) {
+            for (const f of thread.findings) {
+                if (normalizeFinding(f))
+                    pushThreadFinding(t, f);
+            }
+        }
+        live.threads.push(t);
         this.touch();
     }
     /** Append narration (assistant text) to the current reviewer thread. */