iterate-plugin 3.5.2 → 3.5.4

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.
@@ -26,11 +30,22 @@ import { resolveProjectRootForExec } from "../config-loader.js";
 import { writeTextAtomic, writeJsonAtomic } from "../atomic-fs.js";
 import { readDecisionEntries, appendDecisionEntry } 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.
@@ -87,17 +155,25 @@ export function inspectPrune(projectRoot, retainDays) {
     }
     const staleBackups = [];
     const fixDir = fixesDir(projectRoot);
-    if (existsSync(fixDir)) {
-        for (const entry of readdirSync(fixDir)) {
-            if (!entry.endsWith('.bak'))
-                continue;
-            // Extract the fix-id prefix (up to the first underscore after the id).
-            // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
-            const match = entry.match(/^(fix-[a-z0-9]+)_/);
-            const id = match?.[1];
-            if (id && !activeIds.has(id)) {
-                staleBackups.push(entry);
-            }
+    // existsSync does not prove readability — a permissions failure must degrade
+    // to "nothing listable" (report skipped) instead of throwing out of execute.
+    let fixEntries = [];
+    try {
+        if (existsSync(fixDir))
+            fixEntries = readdirSync(fixDir);
+    }
+    catch {
+        fixEntries = [];
+    }
+    for (const entry of fixEntries) {
+        if (!entry.endsWith('.bak'))
+            continue;
+        // Extract the fix-id prefix (up to the first underscore after the id).
+        // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
+        const match = entry.match(/^(fix-[a-z0-9]+)_/);
+        const id = match?.[1];
+        if (id && !activeIds.has(id)) {
+            staleBackups.push(entry);
         }
     }
     // 4. Empty rounds (rounds with 0 records).
@@ -106,10 +182,25 @@ export function inspectPrune(projectRoot, retainDays) {
         .map((r) => r.round);
     // 5. Stray atomic-write temp files left behind by a crashed writer. The
     // unique prefix makes them recognizable and safe to delete — no live writer
-    // ever reads another writer's temp file.
-    const staleTemps = existsSync(iterateDir(projectRoot))
-        ? readdirSync(iterateDir(projectRoot)).filter((f) => isPrunableTemp(f)).sort()
-        : [];
+    // ever reads another writer's temp file. A permissions failure listing the
+    // dir degrades to "none found" (report-only) rather than throwing.
+    let iterateEntries = [];
+    try {
+        iterateEntries = existsSync(iterateDir(projectRoot)) ? readdirSync(iterateDir(projectRoot)) : [];
+    }
+    catch {
+        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,
@@ -118,12 +209,57 @@ 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');
+    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)}` };
+        }
+    }
+    return { deleted: 0, error: `failed to rewrite decision log after ${MAX_LOG_REWRITE_RETRIES} attempts` };
+}
+/**
+ * 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 = {
@@ -132,22 +268,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) {
@@ -199,6 +332,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;
 }
 /**
@@ -212,7 +373,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: {
@@ -254,6 +416,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.',
                     ];
@@ -266,6 +430,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) {
@@ -305,6 +471,8 @@ export function registerPruneTool(ctx) {
                     deletedCheckpoint: result.deletedCheckpoint,
                     deletedBackups: result.deletedBackups.length,
                     trimmedEmptyRounds: result.trimmedEmptyRounds,
+                    deletedExperiences: result.deletedExperiences,
+                    deletedDefenseEvents: result.deletedDefenseEvents,
                 },
             });
             return {

package/dist/tools/quality-gate.js

@@ -9,6 +9,8 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { readQualityGate, writeQualityGate, computeQualityGate, clearQualityGate } from "./quality-store.js";
+/** Valid severity values (kept in sync with QualityGateSnapshot counting). */
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
 /** Validate a single finding object; returns true when well-formed. */
 function isValidFinding(raw) {
     if (!raw || typeof raw !== 'object')
@@ -16,6 +18,7 @@ function isValidFinding(raw) {
     const f = raw;
     return (typeof f.dimension === 'string' &&
         typeof f.severity === 'string' &&
+        VALID_SEVERITIES.has(f.severity) &&
         typeof f.file === 'string' &&
         (f.line === undefined || typeof f.line === 'number'));
 }

package/dist/tools/quality-store.js

@@ -200,13 +200,19 @@ export function computeQualityGate(opts) {
     const overallScore = dimensionGates.length > 0
         ? Math.round(dimensionGates.reduce((sum, d) => sum + d.score, 0) / dimensionGates.length)
         : 0;
-    // Determine overall status
+    // Determine overall status. An empty review (no dimensions, no findings, no
+    // validation results) is NOT a failure — there is simply nothing to gate —
+    // so it reports `pending` (not-applicable) instead of a fabricated FAIL.
     const hasCritical = criticalCount > 0;
     const hasHighFail = dimensionGates.some((d) => d.status === 'fail');
     const verificationFails = totalChecks > 0 && failedChecks > 0;
+    const noData = dimensionGates.length === 0 && totalFindings === 0 && totalChecks === 0;
     let overallStatus = 'pass';
     let failReason;
-    if (hasCritical) {
+    if (noData) {
+        overallStatus = 'pending';
+    }
+    else if (hasCritical) {
         overallStatus = 'fail';
         failReason = `${criticalCount} critical findings present`;
     }

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

@@ -31,7 +31,10 @@ function captureRound(builder, round) {
     if (!round || typeof round !== 'object')
         return;
     const r = round;
-    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);
@@ -61,15 +64,17 @@ function normalizeCheckpoint(input) {
     if (!input || typeof input !== 'object')
         return null;
     const c = input;
-    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(),
     };
 }
@@ -85,7 +90,7 @@ function normalizeFix(input) {
     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,
@@ -143,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).' },
         },
@@ -211,11 +217,37 @@ 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),
+                    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(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,
@@ -272,11 +304,24 @@ 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();
-            await persist(file, builder.serialize());
+            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 };
+            }
             const live = await readLive(projectRoot);
             return {
                 operation: 'capture',
@@ -323,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/`. */
@@ -331,6 +376,18 @@ async function persist(file, manifest) {
     await mkdir(dirname(file), { recursive: true });
     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, manifest) {
+    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/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) {
@@ -213,6 +242,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 };
 }
 /**