iterate-plugin 3.5.5 → 3.5.7

package/src/review.ts

@@ -162,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 }
@@ -282,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).
@@ -630,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(
@@ -637,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}`)
   }
@@ -744,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
@@ -751,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 : []
@@ -816,6 +846,7 @@ export function buildReviewPlan(input: {
           scopeFiles: batch,
           focus: focusMap.get(d),
           attachments,
+          effort: reasoningEffort ?? undefined,
         }),
         findingsSchema: findingsSchema(),
       })
@@ -832,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,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.
@@ -93,9 +100,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.
@@ -118,6 +130,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 : [])),
@@ -125,7 +143,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.',
@@ -145,23 +163,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 +222,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 +290,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,9 +304,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(
@@ -288,6 +325,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 + '}})',
@@ -296,6 +335,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.
@@ -316,12 +359,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
@@ -339,10 +386,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)
@@ -467,7 +523,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' }
 )
@@ -476,7 +532,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}.',
@@ -490,25 +546,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,
@@ -529,12 +588,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

@@ -121,6 +121,18 @@ function recountEntries(filePath: string): number {
   }
 }
 
+/**
+ * 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: string): void {
+  entryCountCache.delete(filePath)
+}
+
 /** All valid DecisionLogEntry `type` values (must stay in sync with Types). */
 const VALID_ENTRY_TYPES = new Set<DecisionLogEntry['type']>([
   'round_start',

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',

package/src/tools/prune.ts

@@ -24,13 +24,13 @@
  *   - 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 type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { writeTextAtomic, writeJsonAtomic } from '../atomic-fs.ts'
-import { readDecisionEntries, appendDecisionEntry, acquireLogLock } from './decision-log.ts'
+import { readDecisionEntries, appendDecisionEntry, acquireLogLock, invalidateLogCountCache } from './decision-log.ts'
 import { readRegistry, removeRecord, recomputeRoundCounts } from './fix.ts'
 import { readExperienceBank, writeExperienceBank } from './experience-store.ts'
 import { readDefenseEvents, writeDefenseEvents } from './defense-store.ts'
@@ -154,6 +154,7 @@ export function inspectPrune(
 ): {
   oldLogEntries: number
   hasCheckpoint: boolean
+  checkpointStale: boolean
   staleBackups: string[]
   staleTemps: string[]
   emptyRounds: number[]
@@ -170,8 +171,20 @@ export function inspectPrune(
   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)
@@ -233,6 +246,7 @@ export function inspectPrune(
   return {
     oldLogEntries,
     hasCheckpoint,
+    checkpointStale,
     staleBackups,
     staleTemps,
     emptyRounds,
@@ -277,6 +291,12 @@ function rewriteDecisionLogKeepingRecent(projectRoot: string, cutoff: string): {
         const deleted = entries.length - kept.length
         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.
@@ -333,8 +353,10 @@ export function executePrune(
     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
@@ -466,7 +488,7 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
             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 as string[] | undefined)?.length ?? 0}`,
               `  Stray temp files to delete: ${(report?.staleTemps as string[] | undefined)?.length ?? 0}`,
               `  Empty rounds to trim: ${(report?.emptyRounds as number[] | undefined)?.length ?? 0}`,

package/src/tools/transcript.ts

@@ -160,7 +160,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).' },
       },
@@ -358,12 +358,23 @@ function rehydrateBuilder(manifest: TranscriptManifest, approval: 'ask' | 'deny'
     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) {