iterate-plugin 3.5.3 → 3.5.5

package/src/tools/experience-store.ts

@@ -9,6 +9,7 @@ import * as fs from 'node:fs'
 import * as path from 'node:path'
 import { iterateDir } from '../paths.ts'
 import { writeJsonAtomic } from '../atomic-fs.ts'
+import { hashString } from './fix.ts'
 import type { ExperienceBank, ExperienceEntry } from '../types.ts'
 
 const EXPERIENCE_FILE = 'experience.json'
@@ -38,12 +39,15 @@ function stringArray(v: unknown): string[] {
  * throw or emit NaN. Returns null for non-object entries; every required field
  * gets a safe default.
  */
-function normalizeEntry(raw: unknown): ExperienceEntry | null {
+function normalizeEntry(raw: unknown, index: number): ExperienceEntry | null {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
   const e = raw as Record<string, unknown>
   const pattern = typeof e.pattern === 'string' ? e.pattern : ''
   const dimension = typeof e.dimension === 'string' ? e.dimension : ''
-  const id = typeof e.id === 'string' && e.id ? e.id : `exp-${Math.random().toString(36).slice(2, 8)}`
+  // Deterministic id (content + position based) so a read→write cycle never
+  // churns random ids on entries that were hand-edited without one.
+  const derivedId = `exp-${hashString(`${index}|${pattern}|${dimension}`)}`
+  const id = typeof e.id === 'string' && e.id ? e.id : derivedId
   if (!pattern && !dimension) return null
   const hitCount = typeof e.hitCount === 'number' && Number.isFinite(e.hitCount) ? e.hitCount : 0
   return {
@@ -70,7 +74,7 @@ export function readExperienceBank(projectRoot: string): ExperienceBank {
     const parsed = JSON.parse(content) as Partial<ExperienceBank>
     if (parsed && Array.isArray(parsed.entries)) {
       const entries = parsed.entries
-        .map(normalizeEntry)
+        .map((raw, i) => normalizeEntry(raw, i))
         .filter((e): e is ExperienceEntry => e !== null)
       return {
         entries,
@@ -167,8 +171,11 @@ export type ExperienceEntryInput = Omit<
 /**
  * Add or update an experience entry.
  *
- * An entry with an `id` that already exists, OR a new entry whose
- * `pattern`+`dimension` pair matches an existing entry, is treated as a HIT:
+ * An entry with an `id` that already exists is treated as an UPDATE + HIT:
+ * the caller-supplied fields replace the stored ones and the hitCount is
+ * incremented (lastHitAt refreshed) — this fulfills the documented
+ * "update a specific entry via add" contract. A NEW entry whose
+ * `pattern`+`dimension` pair matches an existing entry is treated as a HIT:
  * the matching entry's hitCount is incremented (lastHitAt refreshed) so
  * repeated encounters of the same pattern do not create duplicates. Otherwise
  * a fresh entry is appended with hitCount 1. Never mutates the input bank.
@@ -186,11 +193,14 @@ export function upsertExperience(
     : bank.entries.find((e) => e.pattern === entry.pattern && e.dimension === entry.dimension)
 
   if (existing) {
-    const updated: ExperienceEntry = {
-      ...existing,
-      hitCount: (existing.hitCount ?? 0) + 1,
-      lastHitAt: lastUpdated,
-    }
+    // Explicit-id updates REPLACE the editable fields (fulfilling the
+    // documented "update a specific entry via add" contract); a pattern+
+    // dimension HIT only bumps the hit metadata so a repeat encounter never
+    // overwrites the curated entry.
+    const byId = typeof entry.id === 'string' && entry.id.length > 0
+    const updated: ExperienceEntry = byId
+      ? { ...existing, ...entry, id: existing.id, hitCount: (existing.hitCount ?? 0) + 1, lastHitAt: lastUpdated }
+      : { ...existing, hitCount: (existing.hitCount ?? 0) + 1, lastHitAt: lastUpdated }
     return {
       bank: {
         ...bank,
@@ -203,14 +213,16 @@ export function upsertExperience(
     }
   }
 
-  // Add new entry
+  // Add new entry. Spread the caller input FIRST so the store-generated
+  // `id`/`timestamp`/`hitCount`/`lastHitAt` always win — a hostile or
+  // malformed input can never forge its own identity or hit count.
   const id = entry.id || `exp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
   const newEntry: ExperienceEntry = {
+    ...entry,
     id,
     timestamp: lastUpdated,
     hitCount: 1,
     lastHitAt: lastUpdated,
-    ...entry,
   }
 
   return {

package/src/tools/fix.ts

@@ -366,6 +366,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
             linesRemoved: { type: 'integer' },
             diffSummary: { type: 'string' },
             backupPath: { type: 'string' },
+            warning: { type: 'string' },
             error: { type: 'string' },
           },
         },
@@ -456,6 +457,17 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           return { ok: false, error: `finding already fixed this run (id: ${id})`, id }
         }
 
+        // No-op guard: content-identical "fixes" (e.g. a fixer that re-sent the
+        // file unchanged) must never burn a backup, a write, or a registry/success
+        // record. Placed after the registry check so a re-sent fix of an id that
+        // was ALREADY fixed is still reported as "already fixed this run".
+        if (added === 0 && removed === 0) {
+          return {
+            ok: false,
+            error: `no changes: the supplied content for ${file} is identical to the current content — apply a real edit`,
+          }
+        }
+
         const target = resolveProjectFile(projectRoot, file)
         if (!target.ok) return { ok: false, error: target.reason }
 
@@ -528,13 +540,16 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` }
         }
 
-        appendDecisionEntry(projectRoot, {
+        const logRes = appendDecisionEntry(projectRoot, {
           timestamp,
           round: args.round,
           type: 'atomic_fix',
           data: { id, file, finding: finding.summary, linesAdded: added, linesRemoved: removed },
         })
 
+        // The fix itself succeeded, but a decision-log write failure would leave
+        // the audit trail incomplete — surface it (warning, not fatal) so the
+        // model/UI knows the record was not persisted.
         return {
           ok: true,
           id,
@@ -544,6 +559,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           linesRemoved: removed,
           diffSummary: record.diffSummary,
           backupPath,
+          ...(logRes.error ? { warning: logRes.error } : {}),
         }
         })
         return result
@@ -710,6 +726,7 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
             ok: { type: 'boolean', required: true },
             id: { type: 'string' },
             file: { type: 'string' },
+            warning: { type: 'string' },
             error: { type: 'string' },
           },
         },
@@ -749,7 +766,7 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
           return { ok: false, error: `failed to update fix registry: ${String(err)}` }
         }
 
-        appendDecisionEntry(projectRoot, {
+        const logRes = appendDecisionEntry(projectRoot, {
           timestamp: new Date().toISOString(),
           round: record.round,
           type: 'revert',
@@ -762,7 +779,12 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
         // rollback flow.
         await markFixRolledBackInTranscript(projectRoot, id)
 
-        return { ok: true, id, file: record.finding.file }
+        return {
+          ok: true,
+          id,
+          file: record.finding.file,
+          ...(logRes.error ? { warning: logRes.error } : {}),
+        }
       },
     }),
   )

package/src/tools/prune.ts

@@ -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,16 +30,29 @@ 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'
 import { iterateDir, fixesDir, checkpointPath, fixRegistryPath } from '../paths.ts'
-import type { FixRegistry } from '../types.ts'
+import type { DefenseEventStream, ExperienceBank, FixRegistry } from '../types.ts'
 
 /** 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: number | undefined): number {
   if (typeof days !== 'number' || !Number.isInteger(days) || days <= 0) {
@@ -71,6 +88,62 @@ export function isPrunableTemp(name: string): boolean {
   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: ExperienceBank, cap: number): { bank: ExperienceBank; removed: number } {
+  const size = Number.isFinite(cap) && (cap as number) >= 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: DefenseEventStream,
+  cutoff: string,
+): { stream: DefenseEventStream; removed: number } {
+  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: DefenseEventStream['events']): DefenseEventStream['counts'] {
+  const counts: DefenseEventStream['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.
@@ -86,6 +159,10 @@ export function inspectPrune(
   emptyRounds: number[]
   totalLogEntries: number
   registryRounds: number
+  totalExperiences: number
+  experienceOversize: number
+  totalDefenseEvents: number
+  staleDefenseEvents: number
 } {
   const cutoff = cutoffTimestamp(retainDays)
 
@@ -142,6 +219,17 @@ export function inspectPrune(
   }
   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,
@@ -150,6 +238,10 @@ export function inspectPrune(
     emptyRounds,
     totalLogEntries: entries.length,
     registryRounds: registry.rounds.length,
+    totalExperiences: bank.entries.length,
+    experienceOversize: sweptBank.removed,
+    totalDefenseEvents: defenseStream.events.length,
+    staleDefenseEvents: sweptDefense.removed,
   }
 }
 
@@ -157,6 +249,54 @@ export function inspectPrune(
  * 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: string, cutoff: string): { deleted: number; error?: string } {
+  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: string,
   retainDays: number,
@@ -167,6 +307,8 @@ export function executePrune(
   deletedBackups: string[]
   deletedTemps: string[]
   trimmedEmptyRounds: number
+  deletedExperiences: number
+  deletedDefenseEvents: number
   errors: string[]
 } {
   const cutoff = cutoffTimestamp(retainDays)
@@ -176,22 +318,19 @@ export function executePrune(
     deletedBackups: [] as string[],
     deletedTemps: [] as string[],
     trimmedEmptyRounds: 0,
+    deletedExperiences: 0,
+    deletedDefenseEvents: 0,
     errors: [] as string[],
   }
 
   // 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.
@@ -244,6 +383,34 @@ export function executePrune(
     }
   }
 
+  // 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
 }
 
@@ -260,7 +427,8 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
         '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: {
@@ -302,6 +470,8 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
               `  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}`,
+              `  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.',
             ]
@@ -314,6 +484,8 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
             `  Deleted ${(result?.deletedBackups as string[] | undefined)?.length ?? 0} stale backups.`,
             `  Deleted ${(result?.deletedTemps as string[] | undefined)?.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 as string[] | undefined) ?? []
           if (errs.length > 0) {
@@ -344,8 +516,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',
@@ -356,8 +530,11 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
             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,

package/src/tools/review.ts

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

package/src/tools/transcript.ts

@@ -160,6 +160,7 @@ export function registerTranscriptTool(ctx: {
           description: 'For `capture`: array of applied fixes [{id, file, round, summary, linesAdded, linesRemoved, success}].',
         },
         refReadFiles: { type: 'json', description: 'For `capture`: flat array of all read files across rounds (optional).' },
+        stoppedReason: { type: 'string', description: 'For `capture`: why the run ended — "converged" | "max_rounds_reached" | "aborted_by_validation". When omitted, derived from the convergence trend (trailing 0 = converged, otherwise = max_rounds_reached once a round ran).' },
         text: { type: 'string', description: 'For `nudge`: steering text to set (or null to clear).' },
         path: { type: 'string', description: 'Project root directory (default: current working directory).' },
       },
@@ -231,13 +232,24 @@ 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) as 'dry-run' | 'normal' | null,
+            taskMode: (manifest?.taskMode === 'code' || manifest?.taskMode === 'iterate' ? manifest.taskMode : null) as 'code' | 'iterate' | null,
+            approval,
+            goal: typeof manifest?.goal === 'string' ? manifest.goal : '',
+            maxRounds: typeof manifest?.maxRounds === 'number' ? manifest.maxRounds : 0,
+          }
           let builder: ReviewTranscriptBuilder
           if (manifest) {
             try {
               builder = rehydrateBuilder(manifest, approval)
             } catch {
-              builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval })
+              builder = new ReviewTranscriptBuilder(fallbackOpts)
             }
           } else {
             builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval })
@@ -305,9 +317,18 @@ export function registerTranscriptTool(ctx: {
             if (record) builder.fix(record)
           }
         }
-        // Convergence "found nothing → settled" marker when the trend ends on 0.
+        // End state: an explicit stoppedReason wins; otherwise derive it from
+        // the trend. A run that settled closes as "converged"; a run that did
+        // real work but never trended to 0 closes as "max_rounds_reached";
+        // a capture with no rounds stays "active" (nothing recorded yet).
+        const explicitReason =
+          typeof args.stoppedReason === 'string' && args.stoppedReason.trim()
+            ? args.stoppedReason.trim()
+            : ''
         const last = convergence[convergence.length - 1]
-        if (convergence.length > 0 && last === 0) builder.finish()
+        if (explicitReason) builder.finish(explicitReason)
+        else if (convergence.length > 0 && last === 0) builder.finish('converged')
+        else if (roundsExecuted > 0) builder.finish('max_rounds_reached')
 
         const persisted = await persistChecked(file, builder.serialize())
         if (!persisted.ok) {
@@ -353,7 +374,7 @@ function rehydrateBuilder(manifest: TranscriptManifest, approval: 'ask' | 'deny'
   if (Array.isArray(manifest.fixes)) for (const fx of manifest.fixes) builder.fix(fx as TranscriptFix)
   if (Array.isArray(manifest.timeline)) for (const e of manifest.timeline) builder.decision(e)
   builder.setNudge(manifest.nudge?.text ?? null)
-  if (!manifest.active) builder.finish()
+  if (!manifest.active) builder.finish(manifest.stoppedReason ?? undefined)
   return builder
 }
 

package/src/tools/triage.ts

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