iterate-plugin 3.5.2 → 3.5.4

package/src/tools/review.ts

@@ -265,9 +265,22 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
           const coverageEnabled = config.reviewer?.coverage_validation !== false
           let coverage: CoverageResult | null = null
           if (coverageEnabled) {
-            const assigned = collectScopeFiles(projectRoot, {
-              scope: config.review?.scope === 'changed-only' ? 'changed-only' : 'full',
-            })
+            // Build the assigned inventory the SAME way `plan` builds it: a
+            // changed-only scope uses the resolved git-diff file set, and
+            // falls back to the FULL walk when git is unavailable or nothing
+            // changed (mirrors buildReviewPlan's effective-scope decision), so
+            // the coverage ratio reflects the files reviewers were actually
+            // told to read — never a vacuous 1.0 on an empty inventory.
+            let assigned: string[]
+            if (config.review?.scope === 'changed-only') {
+              const gitScope = await resolveChangedFiles(projectRoot, config.git?.target_branch ?? 'main')
+              assigned =
+                gitScope.changedFiles.length > 0
+                  ? collectScopeFiles(projectRoot, { scope: 'changed-only', changedFiles: gitScope.changedFiles })
+                  : collectScopeFiles(projectRoot, { scope: 'full' })
+            } else {
+              assigned = collectScopeFiles(projectRoot, { scope: 'full' })
+            }
             const readFiles = Array.isArray((source as unknown as { readFiles?: unknown }).readFiles)
               ? ((source as unknown as { readFiles?: unknown }).readFiles as string[])
               : null

package/src/tools/transcript.ts

@@ -44,7 +44,10 @@ function captureRound(builder: ReviewTranscriptBuilder, round: unknown): void {
     findings?: unknown
     readFiles?: unknown
   }
-  const roundNo = typeof r.round === 'number' ? Math.floor(r.round) : 0
+  const roundNo = typeof r.round === 'number' && Number.isFinite(r.round) ? Math.floor(r.round) : 0
+  // NaN round values (`Math.floor(NaN) === NaN`, and `NaN <= 0` is false) would
+  // fall through the guard below; a finite check rejects them outright so a
+  // malformed round can never collapse into round 1 via the builder's coercion.
   if (roundNo <= 0) return
   builder.roundStart(roundNo)
   const findings = Array.isArray(r.findings) ? r.findings : []
@@ -70,14 +73,16 @@ function captureRound(builder: ReviewTranscriptBuilder, round: unknown): void {
 function normalizeCheckpoint(input: unknown): TranscriptManifest['checkpoint'] {
   if (!input || typeof input !== 'object') return null
   const c = input as Record<string, unknown>
-  const round = typeof c.round === 'number' ? c.round : 0
+  // Number.isFinite: a NaN round must not pass `round <= 0` (which is false for
+  // NaN) and later coerce into a phantom round 1 row.
+  const round = typeof c.round === 'number' && Number.isFinite(c.round) ? c.round : 0
   if (round <= 0) return null
   return {
     mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : 'normal',
     round,
-    maxRounds: typeof c.maxRounds === 'number' ? c.maxRounds : 0,
-    fixedCount: typeof c.fixedCount === 'number' ? c.fixedCount : 0,
-    resumeCount: typeof c.resumeCount === 'number' ? c.resumeCount : 0,
+    maxRounds: typeof c.maxRounds === 'number' && Number.isFinite(c.maxRounds) ? c.maxRounds : 0,
+    fixedCount: typeof c.fixedCount === 'number' && Number.isFinite(c.fixedCount) ? c.fixedCount : 0,
+    resumeCount: typeof c.resumeCount === 'number' && Number.isFinite(c.resumeCount) ? c.resumeCount : 0,
     updatedAt: typeof c.updatedAt === 'string' ? c.updatedAt : new Date().toISOString(),
   }
 }
@@ -92,7 +97,7 @@ function normalizeFix(input: unknown): TranscriptFix | null {
   return {
     id,
     timestamp: typeof f.timestamp === 'string' ? f.timestamp : new Date().toISOString(),
-    round: typeof f.round === 'number' ? f.round : 0,
+    round: typeof f.round === 'number' && Number.isFinite(f.round) ? f.round : 0,
     file,
     summary: typeof f.summary === 'string' ? f.summary : '',
     linesAdded: typeof f.linesAdded === 'number' ? f.linesAdded : 0,
@@ -155,6 +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).' },
         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).' },
       },
@@ -224,11 +230,35 @@ export function registerTranscriptTool(ctx: {
               manifest = null
             }
           }
-          const builder = manifest
-            ? rehydrateBuilder(manifest, approval)
-            : new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval })
+          // Rehydrating a parsed-but-malformed manifest (e.g. `rounds: [null]`
+          // or a non-object) must never crash the nudge — degrade to a fresh
+          // builder so the steering text still lands. The fallback must keep
+          // the ORIGINAL run identity (mode/taskMode/goal/maxRounds) so a
+          // stray malformed field can never silently rewrite a dry-run run
+          // into a `normal` one.
+          const fallbackOpts = {
+            project: projectRoot,
+            mode: (manifest?.mode === 'dry-run' || manifest?.mode === 'normal' ? manifest.mode : null) as 'dry-run' | 'normal' | null,
+            taskMode: (manifest?.taskMode === 'code' || manifest?.taskMode === 'iterate' ? manifest.taskMode : null) as 'code' | 'iterate' | null,
+            approval,
+            goal: typeof manifest?.goal === 'string' ? manifest.goal : '',
+            maxRounds: typeof manifest?.maxRounds === 'number' ? manifest.maxRounds : 0,
+          }
+          let builder: ReviewTranscriptBuilder
+          if (manifest) {
+            try {
+              builder = rehydrateBuilder(manifest, approval)
+            } catch {
+              builder = new ReviewTranscriptBuilder(fallbackOpts)
+            }
+          } else {
+            builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval })
+          }
           builder.setNudge(typeof args.text === 'string' && args.text.trim() ? args.text : null)
-          await persist(file, builder.serialize())
+          const persisted = await persistChecked(file, builder.serialize())
+          if (!persisted.ok) {
+            return { operation: 'nudge', updated: false, error: persisted.error }
+          }
           return {
             operation: 'nudge',
             updated: true,
@@ -287,11 +317,23 @@ export function registerTranscriptTool(ctx: {
             if (record) builder.fix(record)
           }
         }
-        // Convergence "found nothing → settled" marker when the trend ends on 0.
+        // End state: an explicit stoppedReason wins; otherwise derive it from
+        // the trend. A run that settled closes as "converged"; a run that did
+        // real work but never trended to 0 closes as "max_rounds_reached";
+        // a capture with no rounds stays "active" (nothing recorded yet).
+        const explicitReason =
+          typeof args.stoppedReason === 'string' && args.stoppedReason.trim()
+            ? args.stoppedReason.trim()
+            : ''
         const last = convergence[convergence.length - 1]
-        if (convergence.length > 0 && last === 0) builder.finish()
+        if (explicitReason) builder.finish(explicitReason)
+        else if (convergence.length > 0 && last === 0) builder.finish('converged')
+        else if (roundsExecuted > 0) builder.finish('max_rounds_reached')
 
-        await persist(file, builder.serialize())
+        const persisted = await persistChecked(file, builder.serialize())
+        if (!persisted.ok) {
+          return { operation: 'capture', found: true, updated: false, error: persisted.error }
+        }
         const live = await readLive(projectRoot)
         return {
           operation: 'capture',
@@ -332,7 +374,7 @@ function rehydrateBuilder(manifest: TranscriptManifest, approval: 'ask' | 'deny'
   if (Array.isArray(manifest.fixes)) for (const fx of manifest.fixes) builder.fix(fx as TranscriptFix)
   if (Array.isArray(manifest.timeline)) for (const e of manifest.timeline) builder.decision(e)
   builder.setNudge(manifest.nudge?.text ?? null)
-  if (!manifest.active) builder.finish()
+  if (!manifest.active) builder.finish(manifest.stoppedReason ?? undefined)
   return builder
 }
 
@@ -342,6 +384,21 @@ async function persist(file: string, manifest: TranscriptManifest): Promise<void
   await writeTextAtomicAsync(file, JSON.stringify(manifest, null, 2))
 }
 
+/** persist wrapped with a structured error channel so disk failures surface
+ *  as a structured tool result instead of rejecting the whole execute (matches
+ *  every other write path in this codebase). */
+async function persistChecked(
+  file: string,
+  manifest: TranscriptManifest,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    await persist(file, manifest)
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, error: `failed to persist transcript: ${err instanceof Error ? err.message : String(err)}` }
+  }
+}
+
 /**
  * Mark one applied fix as rolled back in the PERSISTED transcript, so the
  * client observatory (F4 fix/rollback tab) reflects the reversal instead of

package/src/tools/triage.ts

@@ -1,5 +1,5 @@
-import { copyFileSync, existsSync, readFileSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
+import { copyFileSync, existsSync, readdirSync, readFileSync, rmSync } from 'node:fs'
+import { join, dirname, basename } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import yaml from 'js-yaml'
@@ -16,6 +16,9 @@ const KNOWN_INTENTIONAL_KEY = 'known_intentional'
 /** Max entries per single `apply` call. */
 const MAX_ENTRIES = 500
 
+/** How many timestamped config backups are retained (older ones are removed). */
+export const MAX_TRIAGE_BACKUPS = 5
+
 /** Whole-file marker line (matches review.ts filterKnownIntentional semantics). */
 const WHOLE_FILE_LINE = 0
 
@@ -171,6 +174,33 @@ export function backupSuffix(now = new Date()): string {
   return now.toISOString().replace(/[:.]/g, '-')
 }
 
+/**
+ * Bound the timestamped config backups: after a fresh one is written, delete
+ * every older `config.bak-*` file beyond the newest `keep`. Best-effort — a
+ * filesystem failure here must never fail the apply that just succeeded
+ * (backups are a safety net, not a requirement).
+ * @returns the absolute paths of the backups that were removed.
+ */
+export function pruneOldConfigBackups(configPath: string, keep = MAX_TRIAGE_BACKUPS): string[] {
+  const removed: string[] = []
+  try {
+    const dir = dirname(configPath)
+    const prefix = `${basename(configPath)}.bak-`
+    const matches = readdirSync(dir)
+      .filter((f) => f.startsWith(prefix))
+      .sort()
+    // Keep the newest `keep`; remove everything older.
+    const doomed = matches.slice(0, Math.max(0, matches.length - keep))
+    for (const f of doomed) {
+      rmSync(join(dir, f), { force: true })
+      removed.push(join(dir, f))
+    }
+  } catch {
+    // Best-effort cleanup — never surface a cleanup failure.
+  }
+  return removed
+}
+
 // ─── File I/O ───────────────────────────────────────────────────────────────
 
 /** Load the raw config object (empty when the file is missing). */
@@ -248,6 +278,10 @@ function applyEntries(
     }
   }
 
+  // Success: bound the accumulation of timestamped backups so a long-lived
+  // project never collects an unbounded pile of config snapshots.
+  if (backupPath) pruneOldConfigBackups(configPath)
+
   return { ok: true, added, skipped, count: merged.length, configPath, backupPath }
 }
 

package/src/transcript.ts

@@ -53,6 +53,11 @@ const MAX_TIMELINE = 500
  *  grow the manifest payload without limit). */
 const MAX_FIXES = 200
 
+/** Max round number accepted by the builder. A model-authored/manifest-backed
+ *  round value is attacker-influenced JSON: `roundStart(1e9)` / `snapshotConvergence`
+ *  would otherwise preallocate arrays of that size and OOM the host. */
+const MAX_ROUNDS = 1000
+
 /** Thresholds applied when reducing a string list under a cap. */
 function clampStringList(source: string[], cap: number): string[] {
   const out: string[] = []
@@ -137,6 +142,7 @@ export class ReviewTranscriptBuilder {
   private round = 0
   private maxRounds = 0
   private active = true
+  private stoppedReason: string | null = null
   private readonly rounds: LiveRound[] = []
   private readonly convergence: number[] = []
   private readonly globalFindings: TranscriptFinding[] = []
@@ -198,18 +204,27 @@ export class ReviewTranscriptBuilder {
     this.touch()
   }
 
-  /** End the run (stops the "active" pulsing in the UI). */
-  finish(): void {
+  /**
+   * End the run (stops the "active" pulsing in the UI). `reason` records WHY
+   * it ended, so a run stopped by max-rounds or validation is never mistaken
+   * for a live run NOR for a clean convergence.
+   */
+  finish(reason?: string): void {
     this.active = false
+    if (typeof reason === 'string' && reason.trim()) this.stoppedReason = reason.trim()
     this.touch()
   }
 
   /** Open a review round, capturing the current round index. */
   roundStart(round: number, maxRounds?: number): void {
     const r = typeof round === 'number' && Number.isFinite(round) ? Math.floor(round) : 1
-    this.round = r > 0 ? r : 1
+    // Clamp to MAX_ROUNDS: `this.rounds.length < this.round` below preallocates
+    // an array of size `round` — an unbounded model-controlled value (e.g. 1e9)
+    // would OOM the host. Values above the cap are folded into the cap so the
+    // real rounds are never silently dropped.
+    this.round = Math.min(r > 0 ? r : 1, MAX_ROUNDS)
     if (typeof maxRounds === 'number' && Number.isFinite(maxRounds) && maxRounds >= 0) {
-      this.maxRounds = Math.floor(maxRounds)
+      this.maxRounds = Math.min(Math.floor(maxRounds), MAX_ROUNDS)
     }
     while (this.rounds.length < this.round) {
       this.rounds.push({ round: this.rounds.length + 1, threads: [] })
@@ -294,7 +309,10 @@ export class ReviewTranscriptBuilder {
 
   /** Record a round's new-finding count for the convergence series. */
   snapshotConvergence(round: number, newCount: number): void {
-    const r = typeof round === 'number' && Number.isFinite(round) ? Math.floor(round) : 1
+    const rawR = typeof round === 'number' && Number.isFinite(round) ? Math.floor(round) : 1
+    // Clamp (mirrors roundStart): the loop below preallocates `r` slots, so an
+    // unbounded model-controlled round number would OOM the host.
+    const r = Math.min(rawR > 0 ? rawR : 1, MAX_ROUNDS)
     const n = typeof newCount === 'number' && Number.isFinite(newCount) ? newCount : 0
     while (this.convergence.length < r) this.convergence.push(-1)
     this.convergence[r - 1] = Math.floor(n)
@@ -312,7 +330,10 @@ export class ReviewTranscriptBuilder {
     this.fixes.push({
       id,
       timestamp: typeof record.timestamp === 'string' ? record.timestamp : isoNow(),
-      round: typeof record.round === 'number' ? record.round : this.round,
+      round:
+        typeof record.round === 'number' && Number.isFinite(record.round)
+          ? Math.floor(record.round)
+          : this.round,
       file,
       summary: typeof record.summary === 'string' ? record.summary : '',
       linesAdded:
@@ -363,7 +384,10 @@ export class ReviewTranscriptBuilder {
     const type = typeof entry.type === 'string' ? entry.type : 'decision'
     this.timeline.push({
       timestamp: typeof entry.timestamp === 'string' ? entry.timestamp : isoNow(),
-      round: typeof entry.round === 'number' ? entry.round : this.round,
+      round:
+        typeof entry.round === 'number' && Number.isFinite(entry.round)
+          ? Math.floor(entry.round)
+          : this.round,
       type,
       data:
         entry.data && typeof entry.data === 'object'
@@ -425,6 +449,7 @@ export class ReviewTranscriptBuilder {
       checkpoint: this.checkpoint,
       timeline: this.timeline,
       nudge: this.nudge,
+      stoppedReason: this.stoppedReason,
       approval: {
         active: this.approval !== 'allow',
         policy: this.approval,

package/src/types.ts

@@ -349,6 +349,8 @@ export interface TranscriptManifest {
   }
   /** v3.0: task_mode indicator from harness status */
   taskMode?: 'code' | 'iterate' | null
+  /** Why the run ended: converged / max_rounds_reached / aborted_by_validation. */
+  stoppedReason?: string | null
 }
 
 // ─── v3.0: Quality Gate ──────────────────────────────────────────────────────