iterate-plugin 3.5.5 → 3.5.6

package/src/skill-prompt.ts

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

package/src/tools/checkpoint.ts

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

package/src/tools/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,7 +24,7 @@
  *   - 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'
@@ -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,
@@ -333,8 +347,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 +482,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) {

package/src/transcript.ts

@@ -98,7 +98,10 @@ function normalizeFinding(input: unknown): TranscriptFinding | null {
     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,
@@ -267,7 +270,8 @@ 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]! as LiveRound | undefined
-    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,
@@ -275,7 +279,86 @@ export class ReviewTranscriptBuilder {
         readFiles: [],
         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: number,
+    thread: {
+      dimension?: unknown
+      attempt?: unknown
+      messages?: unknown
+      readFiles?: unknown
+      findings?: unknown
+    },
+  ): void {
+    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: LiveThread = {
+      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 as string[]))
+    }
+    if (Array.isArray(thread.findings)) {
+      for (const f of thread.findings) {
+        if (normalizeFinding(f)) pushThreadFinding(t, f)
+      }
     }
+    live.threads.push(t)
     this.touch()
   }
 

package/src/types.ts

@@ -18,9 +18,12 @@ export interface IterateConfig {
   }
   /**
    * LLM reasoning effort for review passes ('low' | 'medium' | 'high').
-   * Absent → follow the provider default. The harness forwards it into the
-   * OpenAI-compatible request body; the plugin surfaces it in the settings
-   * panel and review plan (dsh 0.1.1-rc.7+ exposes the same 'low' effort).
+   * Absent → follow the provider default. Accepted by `iterate_config` write
+   * validation (config-write), exposed in the settings guide, and carried on
+   * the review plan (`buildReviewPlan.reasoningEffort`, plus an effort
+   * directive injected into every reviewer prompt) so the orchestrating
+   * harness can honor it per reviewer subagent. The plugin itself never reads
+   * or modifies the provider request body.
    */
   reasoning_effort?: 'low' | 'medium' | 'high'
   reviewer: {
@@ -226,7 +229,9 @@ export interface IterationStatus {
   findingsCount: number
   totalDecisionLogEntries: number
   hasCheckpoint: boolean
-  /** True when a checkpoint is present — i.e. the previous run was interrupted before finishing. */
+  /** True when a checkpoint is present AND no decision-log entry is newer than
+   *  it — i.e. the previous run left a checkpoint and nothing has logged since
+   *  (a live run that saved progress keeps `interrupted=false`). */
   interrupted: boolean
   /** How many times the current checkpoint has already been resumed. */
   resumeCount: number