iterate-plugin 3.5.3 → 3.5.5

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
@@ -113,6 +127,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 +147,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)
@@ -142,9 +168,11 @@ 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[] = []
+  private readonly globalSeenKeys = new Set<string>()
   private readonly fixes: TranscriptFix[] = []
   private checkpoint: TranscriptCheckpoint | null = null
   private readonly timeline: TranscriptEntry[] = []
@@ -203,9 +231,14 @@ 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()
   }
 
@@ -276,12 +309,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()
   }
 
@@ -293,9 +325,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()
   }
 
@@ -384,8 +415,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) {
@@ -435,14 +470,14 @@ 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,
       nudge: this.nudge,
+      stoppedReason: this.stoppedReason,
       approval: {
         active: this.approval !== 'allow',
         policy: this.approval,
@@ -470,22 +505,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

@@ -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 ──────────────────────────────────────────────────────