iterate-plugin 3.5.4 → 3.5.6

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 } from './decision-log.ts'
+import { readDecisionEntries, appendDecisionEntry, acquireLogLock } 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,
@@ -264,23 +278,32 @@ export function inspectPrune(
  */
 function rewriteDecisionLogKeepingRecent(projectRoot: string, cutoff: string): { deleted: number; error?: string } {
   const logPath = join(iterateDir(projectRoot), 'decision-log.jsonl')
-  for (let attempt = 0; attempt < MAX_LOG_REWRITE_RETRIES; attempt++) {
-    try {
-      const entries = readDecisionEntries(projectRoot)
-      const kept = entries.filter((e) => e.timestamp >= cutoff)
-      const deleted = entries.length - kept.length
-      if (deleted === 0) return { deleted: 0 }
-      writeTextAtomic(logPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n')
-      // A concurrent appender 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.
-      const after = readDecisionEntries(projectRoot)
-      if (after.length <= kept.length) return { deleted }
-    } catch (err) {
-      return { deleted: 0, error: `failed to rewrite decision log: ${String(err)}` }
+  // Take the cross-process log lock for the ENTIRE loop: with the mutex held,
+  // no concurrent appender can slip a fresh line into the read-before-rewrite
+  // window, so the first attempt is nearly always the only one. (The retry
+  // loop stays as defense-in-depth for the lock-unavailable path.)
+  const release = acquireLogLock(projectRoot)
+  try {
+    for (let attempt = 0; attempt < MAX_LOG_REWRITE_RETRIES; attempt++) {
+      try {
+        const entries = readDecisionEntries(projectRoot)
+        const kept = entries.filter((e) => e.timestamp >= cutoff)
+        const deleted = entries.length - kept.length
+        if (deleted === 0) return { deleted: 0 }
+        writeTextAtomic(logPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n')
+        // 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.
+        const after = readDecisionEntries(projectRoot)
+        if (after.length <= kept.length) return { deleted }
+      } catch (err) {
+        return { deleted: 0, error: `failed to rewrite decision log: ${String(err)}` }
+      }
     }
+    return { deleted: 0, error: `failed to rewrite decision log after ${MAX_LOG_REWRITE_RETRIES} attempts` }
+  } finally {
+    release()
   }
-  return { deleted: 0, error: `failed to rewrite decision log after ${MAX_LOG_REWRITE_RETRIES} attempts` }
 }
 
 /**
@@ -324,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
@@ -457,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}`,
@@ -507,8 +532,10 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
 
         const result = executePrune(projectRoot, retainDays, report)
 
-        // Log the prune to the decision log.
-        appendDecisionEntry(projectRoot, {
+        // Log the prune to the decision log. The mutations already happened, so
+        // a failed log append is reported via `errors` — a silent audit miss
+        // (F2) must never pretend every deletion was recorded.
+        const logRes = appendDecisionEntry(projectRoot, {
           timestamp: new Date().toISOString(),
           round: 0,
           type: 'decision',
@@ -523,6 +550,7 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
             deletedDefenseEvents: result.deletedDefenseEvents,
           },
         })
+        if (logRes.error) result.errors.push(logRes.error)
 
         return {
           ok: true,

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/tools/triage.ts

@@ -208,8 +208,9 @@ function readConfigFile(configPath: string): Record<string, unknown> {
   if (!existsSync(configPath)) return {}
   const content = readFileSync(configPath, 'utf-8')
   const parsed = yaml.load(content)
-  if (!parsed || typeof parsed !== 'object') {
-    // A config that exists but is not a YAML mapping must NOT be silently
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    // A config that exists but is NOT a YAML mapping (including a YAML list,
+    // which `typeof [] === 'object'` alone would accept) must NOT be silently
     // treated as empty: writing over it would destroy user data. Callers
     // surface this as an error and refuse to write.
     throw new Error('existing iterate.config.yaml is not a valid YAML mapping')

package/src/transcript.ts

@@ -71,6 +71,20 @@ function clampStringList(source: string[], cap: number): string[] {
   return out
 }
 
+/**
+ * Deep-clone a decision-timeline payload so it is decoupled from the caller's
+ * live object. structuredClone is available in every supported Node release;
+ * on the off chance it is missing, fall back to a JSON round-trip (decision
+ * payloads are JSON-serializable by construction).
+ */
+function cloneDecisionData(data: Record<string, unknown>): Record<string, unknown> {
+  try {
+    return structuredClone(data)
+  } catch {
+    return JSON.parse(JSON.stringify(data)) as Record<string, unknown>
+  }
+}
+
 /** Normalize a single finding, dropping malformed entries. */
 function normalizeFinding(input: unknown): TranscriptFinding | null {
   if (!input || typeof input !== 'object') return null
@@ -84,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,
@@ -113,6 +130,19 @@ interface LiveRound {
   threads: LiveThread[]
 }
 
+/**
+ * Append one raw finding to a thread's list, bound to MAX_FINDINGS_PER_THREAD
+ * with NEWEST-WINS eviction (drop the oldest findings once the cap is hit).
+ * A single oversized fixer agent could otherwise OOM the client with an
+ * unbounded finding dump inside one thread.
+ */
+function pushThreadFinding(thread: LiveThread, raw: unknown): void {
+  thread.findings.push(raw)
+  if (thread.findings.length > MAX_FINDINGS_PER_THREAD) {
+    thread.findings.splice(0, thread.findings.length - MAX_FINDINGS_PER_THREAD)
+  }
+}
+
 /** Merge a report snapshot's findings/readFiles into a thread by dimension. */
 function mergeReportIntoThread(
   thread: LiveThread,
@@ -120,8 +150,7 @@ function mergeReportIntoThread(
   readFiles: readonly unknown[] | undefined,
 ): void {
   for (const raw of findings) {
-    const f = normalizeFinding(raw)
-    if (f) thread.findings.push(raw)
+    if (normalizeFinding(raw)) pushThreadFinding(thread, raw)
   }
   for (const r of readFiles ?? []) {
     if (typeof r === 'string') thread.readFiles.push(r)
@@ -146,6 +175,7 @@ export class ReviewTranscriptBuilder {
   private readonly rounds: LiveRound[] = []
   private readonly convergence: number[] = []
   private readonly globalFindings: TranscriptFinding[] = []
+  private readonly globalSeenKeys = new Set<string>()
   private readonly fixes: TranscriptFix[] = []
   private checkpoint: TranscriptCheckpoint | null = null
   private readonly timeline: TranscriptEntry[] = []
@@ -240,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,
@@ -248,10 +279,89 @@ 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()
+  }
+
   /** Append narration (assistant text) to the current reviewer thread. */
   reviewerMessage(text: string): void {
     if (typeof text !== 'string' || !text.trim()) return
@@ -282,12 +392,11 @@ export class ReviewTranscriptBuilder {
       for (const raw of findings) {
         const f = normalizeFinding(raw)
         if (f) {
-          thread.findings.push(raw)
-          this.globalFindings.push(f)
+          pushThreadFinding(thread, raw)
+          this.addGlobal(f)
         }
       }
     }
-    this.reevaluateGlobal()
     this.touch()
   }
 
@@ -299,9 +408,8 @@ export class ReviewTranscriptBuilder {
     mergeReportIntoThread(thread, findings, readFiles)
     for (const raw of findings) {
       const f = normalizeFinding(raw)
-      if (f) this.globalFindings.push(f)
+      if (f) this.addGlobal(f)
     }
-    this.reevaluateGlobal()
     this.touch()
   }
 
@@ -390,8 +498,12 @@ export class ReviewTranscriptBuilder {
           : this.round,
       type,
       data:
-        entry.data && typeof entry.data === 'object'
-          ? (entry.data as Record<string, unknown>)
+        entry.data && typeof entry.data === 'object' && !Array.isArray(entry.data)
+          // Deep clone so a caller mutating its own object later can never
+          // alias into the timeline (serialize would then emit the mutated
+          // values instead of what was actually decided). Decision-log payloads
+          // are small JSON, so the clone cost is negligible.
+          ? cloneDecisionData(entry.data as Record<string, unknown>)
           : {},
     })
     if (this.timeline.length > MAX_TIMELINE) {
@@ -441,10 +553,9 @@ export class ReviewTranscriptBuilder {
       maxRounds: this.maxRounds,
       rounds,
       convergence: this.convergence,
-      findings:
-        this.globalFindings.length > MAX_FINDINGS_TOTAL
-          ? this.globalFindings.slice(0, MAX_FINDINGS_TOTAL)
-          : this.globalFindings,
+      // addGlobal maintains the newest-wins cap incrementally, so the array is
+      // already ≤ MAX_FINDINGS_TOTAL — no post-hoc slice needed.
+      findings: this.globalFindings,
       fixes: this.fixes,
       checkpoint: this.checkpoint,
       timeline: this.timeline,
@@ -477,22 +588,24 @@ export class ReviewTranscriptBuilder {
     return live.threads.length
   }
 
-  /** Recompute the global finding list from per-thread findings (dedup). */
-  private reevaluateGlobal(): void {
-    // Rebuild from threads to derive a deterministic global list.
-    this.globalFindings.length = 0
-    const seen = new Set<string>()
-    for (const r of this.rounds) {
-      for (const t of r.threads) {
-        for (const raw of t.findings) {
-          const f = normalizeFinding(raw)
-          if (!f) continue
-          const key = `${f.file}\u0000${f.line ?? 0}\u0000${f.dimension}\u0000${f.summary}`
-          if (seen.has(key)) continue
-          seen.add(key)
-          this.globalFindings.push(f)
-          if (this.globalFindings.length >= MAX_FINDINGS_TOTAL) return
-        }
+  /**
+   * Insert one deduplicated finding into the compact global list.
+   * NEWEST-WINS: when the global cap (MAX_FINDINGS_TOTAL) is hit, the oldest
+   * kept finding is evicted so fresh, still-relevant findings survive — this
+   * is the documented contract. Amortized O(1): dedupe via a seen-key set and
+   * eviction is one `shift` per overflow insert.
+   */
+  private addGlobal(f: TranscriptFinding): void {
+    const key = `${f.file}\u0000${f.line ?? 0}\u0000${f.dimension}\u0000${f.summary}`
+    if (this.globalSeenKeys.has(key)) return
+    this.globalSeenKeys.add(key)
+    this.globalFindings.push(f)
+    if (this.globalFindings.length > MAX_FINDINGS_TOTAL) {
+      const evicted = this.globalFindings.shift()
+      if (evicted) {
+        this.globalSeenKeys.delete(
+          `${evicted.file}\u0000${evicted.line ?? 0}\u0000${evicted.dimension}\u0000${evicted.summary}`,
+        )
       }
     }
   }

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