iterate-plugin 3.5.3 → 3.5.5

package/dist/tools/prune.js

@@ -13,6 +13,10 @@
  *   - Empty fix rounds (rounds with 0 records).
  *   - Stray temp files left behind by a crashed atomic write (see
  *     `isPrunableTemp` for the recognized naming conventions).
+ *   - Experience bank entries beyond `MAX_EXPERIENCE_ENTRIES` (newest kept) —
+ *     the bank grows across sessions with no natural bound; a sweep caps it.
+ *   - Defense events older than `retainDays` (stale iteration streams that
+ *     were never cleared).
  *
  * Security model:
  *   - Only operates under the resolved project `.iterate/` directory.
@@ -24,13 +28,24 @@ import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { writeTextAtomic, writeJsonAtomic } from "../atomic-fs.js";
-import { readDecisionEntries, appendDecisionEntry } from "./decision-log.js";
+import { readDecisionEntries, appendDecisionEntry, acquireLogLock } from "./decision-log.js";
 import { readRegistry, recomputeRoundCounts } from "./fix.js";
+import { readExperienceBank, writeExperienceBank } from "./experience-store.js";
+import { readDefenseEvents, writeDefenseEvents } from "./defense-store.js";
 import { iterateDir, fixesDir, checkpointPath, fixRegistryPath } from "../paths.js";
 /** Default retention for decision-log entries (in days). */
 const DEFAULT_RETAIN_DAYS = 30;
 const MIN_RETAIN_DAYS = 1;
 const MAX_RETAIN_DAYS = 365;
+/**
+ * Upper bound on experience-bank entries retained by a prune sweep. The bank
+ * accumulates curated knowledge across sessions and each entry is small, so a
+ * generous cap drops only the oldest tail of a pathologically large bank
+ * (never recent learning).
+ */
+export const MAX_EXPERIENCE_ENTRIES = 2000;
+/** How many compare-and-append retries bound the decision-log rewrite race. */
+const MAX_LOG_REWRITE_RETRIES = 3;
 /** Clamp retainDays to a sane range. */
 export function clampRetainDays(days) {
     if (typeof days !== 'number' || !Number.isInteger(days) || days <= 0) {
@@ -66,6 +81,59 @@ export function isPrunableTemp(name) {
     // .<basename>.tmp-<pid>-<rand>: starts with a dot and contains ".tmp-" after it.
     return name.startsWith('.') && name.includes('.tmp-');
 }
+/**
+ * Bound the experience bank to its newest `cap` entries (by timestamp; ties
+ * keep their original order via stable sort). Returns the trimmed bank plus
+ * how many entries would be dropped. Never mutates the input bank.
+ */
+export function sweepExperienceBank(bank, cap) {
+    const size = Number.isFinite(cap) && cap >= 0 ? Math.floor(cap) : MAX_EXPERIENCE_ENTRIES;
+    const total = bank.entries.length;
+    if (total <= size)
+        return { bank, removed: 0 };
+    const kept = [...bank.entries]
+        .sort((a, b) => (b.timestamp ?? '').localeCompare(a.timestamp ?? ''))
+        .slice(0, size);
+    // Preserve the original (insertion) order of the surviving entries.
+    const keptIds = new Set(kept.map((e) => e.id));
+    const ordered = bank.entries.filter((e) => keptIds.has(e.id));
+    return {
+        bank: { ...bank, entries: ordered, lastUpdated: new Date().toISOString() },
+        removed: total - ordered.length,
+    };
+}
+/**
+ * Drop defense events older than `cutoff` from the stream using an ISO
+ * timestamp comparison, recomputing the counts so they can never drift from
+ * the surviving events. Never mutates the input stream.
+ */
+export function sweepDefenseEvents(stream, cutoff) {
+    const kept = stream.events.filter((e) => e.timestamp >= cutoff);
+    if (kept.length === stream.events.length)
+        return { stream, removed: 0 };
+    return {
+        stream: {
+            events: kept,
+            lastUpdated: new Date().toISOString(),
+            counts: computeDefenseCounts(kept),
+        },
+        removed: stream.events.length - kept.length,
+    };
+}
+/** Recompute per-type defense counts from a list of events. */
+function computeDefenseCounts(events) {
+    const counts = {
+        precondition_failed: 0,
+        rollback: 0,
+        invariant_violated: 0,
+        assumption_falsified: 0,
+    };
+    for (const e of events) {
+        if (e.type in counts)
+            counts[e.type]++;
+    }
+    return counts;
+}
 /**
  * Inspect the runtime state and report what would be pruned.
  * Pure (no deletions). Returns a structured report.
@@ -124,6 +192,15 @@ export function inspectPrune(projectRoot, retainDays) {
         iterateEntries = [];
     }
     const staleTemps = iterateEntries.filter((f) => isPrunableTemp(f)).sort();
+    // 6. Experience-bank oversize (entries beyond the entry cap). The bank grows
+    // across sessions with no natural bound — a sweep reports the tail that a
+    // prune would drop (newest `MAX_EXPERIENCE_ENTRIES` preserved).
+    const bank = readExperienceBank(projectRoot);
+    const sweptBank = sweepExperienceBank(bank, MAX_EXPERIENCE_ENTRIES);
+    // 7. Defense events older than retainDays (a previous iteration's stream
+    // that was never cleared).
+    const defenseStream = readDefenseEvents(projectRoot);
+    const sweptDefense = sweepDefenseEvents(defenseStream, cutoff);
     return {
         oldLogEntries,
         hasCheckpoint,
@@ -132,12 +209,67 @@ export function inspectPrune(projectRoot, retainDays) {
         emptyRounds,
         totalLogEntries: entries.length,
         registryRounds: registry.rounds.length,
+        totalExperiences: bank.entries.length,
+        experienceOversize: sweptBank.removed,
+        totalDefenseEvents: defenseStream.events.length,
+        staleDefenseEvents: sweptDefense.removed,
     };
 }
 /**
  * Actually prune the runtime artifacts (only called when dryRun=false).
  * Returns a detailed report of what was deleted.
  */
+/**
+ * Rewrite the decision log to the entries younger than `cutoff`.
+ *
+ * The read-before-rewrite is a TOCTOU hot spot: a concurrent worker can append
+ * a fresh audit line between our read and our atomic rewrite, and an atomic
+ * rename would silently discard it. So instead of a single read+write we use a
+ * bounded compare-and-append loop — after each rewrite we re-read the log and
+ * retry whenever the file grew (a concurrent append slipped in). The loop
+ * terminates when the file is stable or after `MAX_LOG_REWRITE_RETRIES`, and a
+ * failure here is surfaced as a structured error instead of truncating the log.
+ *
+ * @returns the number of entries removed (best-effort) or 0 on error.
+ */
+function rewriteDecisionLogKeepingRecent(projectRoot, cutoff) {
+    const logPath = join(iterateDir(projectRoot), 'decision-log.jsonl');
+    // 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();
+    }
+}
+/**
+ * Execute the prune: apply every cleanable item reported by `inspectPrune`.
+ * Every step is individually hedged so a single disk failure degrades to a
+ * reported error rather than aborting the whole cleanup.
+ */
 export function executePrune(projectRoot, retainDays, report) {
     const cutoff = cutoffTimestamp(retainDays);
     const result = {
@@ -146,22 +278,19 @@ export function executePrune(projectRoot, retainDays, report) {
         deletedBackups: [],
         deletedTemps: [],
         trimmedEmptyRounds: 0,
+        deletedExperiences: 0,
+        deletedDefenseEvents: 0,
         errors: [],
     };
     // 1. Rewrite the decision log, keeping only recent entries. Atomic
-    // (temp + rename) so a crash mid-write can never truncate the log.
-    try {
-        const entries = readDecisionEntries(projectRoot);
-        const kept = entries.filter((e) => e.timestamp >= cutoff);
-        result.deletedLogEntries = entries.length - kept.length;
-        if (result.deletedLogEntries > 0) {
-            const logPath = join(iterateDir(projectRoot), 'decision-log.jsonl');
-            writeTextAtomic(logPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n');
-        }
-    }
-    catch (err) {
-        result.errors.push(`failed to rewrite decision log: ${String(err)}`);
-        result.deletedLogEntries = 0;
+    // (temp + rename) so a crash mid-write can never truncate the log; the
+    // bounded compare-and-append loop guards against a concurrent appender
+    // slipping a fresh audit line into the read-before-rewrite window.
+    {
+        const { deleted, error } = rewriteDecisionLogKeepingRecent(projectRoot, cutoff);
+        result.deletedLogEntries = deleted;
+        if (error)
+            result.errors.push(error);
     }
     // 2. Remove checkpoint.
     if (report.hasCheckpoint) {
@@ -213,6 +342,34 @@ export function executePrune(projectRoot, retainDays, report) {
             result.errors.push(`failed to delete temp file ${tmp}: ${String(err)}`);
         }
     }
+    // 6. Trim the experience bank to its entry cap (newest wins).
+    if (report.experienceOversize > 0) {
+        try {
+            const bank = readExperienceBank(projectRoot);
+            const { bank: swept, removed } = sweepExperienceBank(bank, MAX_EXPERIENCE_ENTRIES);
+            if (removed > 0) {
+                writeExperienceBank(projectRoot, swept);
+                result.deletedExperiences = removed;
+            }
+        }
+        catch (err) {
+            result.errors.push(`failed to trim experience bank: ${String(err)}`);
+        }
+    }
+    // 7. Drop defense events older than retainDays (recounted on write).
+    if (report.staleDefenseEvents > 0) {
+        try {
+            const stream = readDefenseEvents(projectRoot);
+            const { stream: swept, removed } = sweepDefenseEvents(stream, cutoff);
+            if (removed > 0) {
+                writeDefenseEvents(projectRoot, swept);
+                result.deletedDefenseEvents = removed;
+            }
+        }
+        catch (err) {
+            result.errors.push(`failed to sweep defense events: ${String(err)}`);
+        }
+    }
     return result;
 }
 /**
@@ -226,7 +383,8 @@ export function registerPruneTool(ctx) {
         description: 'Inspect or clean up old iterate runtime artifacts (.iterate/). ' +
             'Defaults to dry-run (report-only, no deletion). Pass `dryRun: false` to actually prune. ' +
             'Manages: old decision-log entries, stale checkpoints, orphaned fix backups, empty fix rounds, ' +
-            'and stray temp files left by crashed atomic writes. ' +
+            'stray temp files left by crashed atomic writes, experience-bank entries beyond the entry cap, ' +
+            'and stale defense events. ' +
             'Each deletion is logged to the decision log.',
         parameters: {
             dryRun: {
@@ -268,6 +426,8 @@ export function registerPruneTool(ctx) {
                         `  Stale backups to delete: ${report?.staleBackups?.length ?? 0}`,
                         `  Stray temp files to delete: ${report?.staleTemps?.length ?? 0}`,
                         `  Empty rounds to trim: ${report?.emptyRounds?.length ?? 0}`,
+                        `  Experience entries to drop (over ${report?.totalExperiences ?? '?'} cap): ${report?.experienceOversize ?? 0} of ${report?.totalExperiences ?? '?'}`,
+                        `  Stale defense events to remove: ${report?.staleDefenseEvents ?? 0} (of ${report?.totalDefenseEvents ?? '?'})`,
                         '',
                         'Pass dryRun:false to execute the prune.',
                     ];
@@ -280,6 +440,8 @@ export function registerPruneTool(ctx) {
                     `  Deleted ${result?.deletedBackups?.length ?? 0} stale backups.`,
                     `  Deleted ${result?.deletedTemps?.length ?? 0} stray temp files.`,
                     `  Trimmed ${result?.trimmedEmptyRounds ?? 0} empty rounds.`,
+                    `  Trimmed ${result?.deletedExperiences ?? 0} experience entries (over the entry cap).`,
+                    `  Removed ${result?.deletedDefenseEvents ?? 0} stale defense events.`,
                 ];
                 const errs = result?.errors ?? [];
                 if (errs.length > 0) {
@@ -307,8 +469,10 @@ export function registerPruneTool(ctx) {
                 };
             }
             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',
@@ -319,8 +483,12 @@ export function registerPruneTool(ctx) {
                     deletedCheckpoint: result.deletedCheckpoint,
                     deletedBackups: result.deletedBackups.length,
                     trimmedEmptyRounds: result.trimmedEmptyRounds,
+                    deletedExperiences: result.deletedExperiences,
+                    deletedDefenseEvents: result.deletedDefenseEvents,
                 },
             });
+            if (logRes.error)
+                result.errors.push(logRes.error);
             return {
                 ok: true,
                 dryRun: false,

package/dist/tools/review.js

@@ -229,9 +229,23 @@ export function registerReviewTool(ctx) {
                     const coverageEnabled = config.reviewer?.coverage_validation !== false;
                     let coverage = 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;
+                        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.readFiles)
                             ? source.readFiles
                             : null;

package/dist/tools/transcript.js

@@ -148,6 +148,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).' },
         },
@@ -218,14 +219,25 @@ export function registerTranscriptTool(ctx) {
                 }
                 // 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.
+                // 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),
+                    taskMode: (manifest?.taskMode === 'code' || manifest?.taskMode === 'iterate' ? manifest.taskMode : null),
+                    approval,
+                    goal: typeof manifest?.goal === 'string' ? manifest.goal : '',
+                    maxRounds: typeof manifest?.maxRounds === 'number' ? manifest.maxRounds : 0,
+                };
                 let builder;
                 if (manifest) {
                     try {
                         builder = rehydrateBuilder(manifest, approval);
                     }
                     catch {
-                        builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval });
+                        builder = new ReviewTranscriptBuilder(fallbackOpts);
                     }
                 }
                 else {
@@ -292,10 +304,20 @@ export function registerTranscriptTool(ctx) {
                         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');
             const persisted = await persistChecked(file, builder.serialize());
             if (!persisted.ok) {
                 return { operation: 'capture', found: true, updated: false, error: persisted.error };
@@ -346,7 +368,7 @@ function rehydrateBuilder(manifest, approval) {
             builder.decision(e);
     builder.setNudge(manifest.nudge?.text ?? null);
     if (!manifest.active)
-        builder.finish();
+        builder.finish(manifest.stoppedReason ?? undefined);
     return builder;
 }
 /** Atomically persist a manifest (unique temp + rename) under `.iterate/`. */

package/dist/tools/triage.js

@@ -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 yaml from 'js-yaml';
 import { resolveProjectRootForExec } from "../config-loader.js";
@@ -10,6 +10,8 @@ const PERSONALIZATION_KEY = 'personalization';
 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;
 // ─── Pure helpers (exported for unit tests) ─────────────────────────────────
@@ -148,6 +150,33 @@ export function readKnownIntentional(config) {
 export function backupSuffix(now = new Date()) {
     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, keep = MAX_TRIAGE_BACKUPS) {
+    const removed = [];
+    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). */
 function readConfigFile(configPath) {
@@ -155,8 +184,9 @@ function readConfigFile(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');
@@ -213,6 +243,10 @@ function applyEntries(projectRoot, incoming) {
             error: `Failed to write config: ${String(err)}${rollbackError}`,
         };
     }
+    // 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/dist/transcript.js

@@ -54,6 +54,20 @@ function clampStringList(source, cap) {
     }
     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) {
+    try {
+        return structuredClone(data);
+    }
+    catch {
+        return JSON.parse(JSON.stringify(data));
+    }
+}
 /** Normalize a single finding, dropping malformed entries. */
 function normalizeFinding(input) {
     if (!input || typeof input !== 'object')
@@ -81,12 +95,23 @@ function normalizeFinding(input) {
         acknowledged: typeof f.acknowledged === 'boolean' ? f.acknowledged : undefined,
     };
 }
+/**
+ * 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, raw) {
+    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, findings, readFiles) {
     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')
@@ -107,9 +132,11 @@ export class ReviewTranscriptBuilder {
     round = 0;
     maxRounds = 0;
     active = true;
+    stoppedReason = null;
     rounds = [];
     convergence = [];
     globalFindings = [];
+    globalSeenKeys = new Set();
     fixes = [];
     checkpoint = null;
     timeline = [];
@@ -158,9 +185,15 @@ export class ReviewTranscriptBuilder {
             this.phases.push(n);
         this.touch();
     }
-    /** End the run (stops the "active" pulsing in the UI). */
-    finish() {
+    /**
+     * 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) {
         this.active = false;
+        if (typeof reason === 'string' && reason.trim())
+            this.stoppedReason = reason.trim();
         this.touch();
     }
     /** Open a review round, capturing the current round index. */
@@ -230,12 +263,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();
     }
     /** Merge a round-level report snapshot (findings + readFiles) into a thread. */
@@ -248,9 +280,8 @@ export class ReviewTranscriptBuilder {
         for (const raw of findings) {
             const f = normalizeFinding(raw);
             if (f)
-                this.globalFindings.push(f);
+                this.addGlobal(f);
         }
-        this.reevaluateGlobal();
         this.touch();
     }
     // ─── Convergence (F2) ───────────────────────────────────────────────────
@@ -330,8 +361,12 @@ export class ReviewTranscriptBuilder {
                 ? Math.floor(entry.round)
                 : this.round,
             type,
-            data: entry.data && typeof entry.data === 'object'
-                ? entry.data
+            data: 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)
                 : {},
         });
         if (this.timeline.length > MAX_TIMELINE) {
@@ -378,13 +413,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,
@@ -408,25 +444,23 @@ export class ReviewTranscriptBuilder {
     threadCount(live) {
         return live.threads.length;
     }
-    /** Recompute the global finding list from per-thread findings (dedup). */
-    reevaluateGlobal() {
-        // Rebuild from threads to derive a deterministic global list.
-        this.globalFindings.length = 0;
-        const seen = new Set();
-        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.
+     */
+    addGlobal(f) {
+        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}`);
             }
         }
     }