iterate-plugin 3.5.7 → 3.7.0

package/src/tools/fix.ts

@@ -19,10 +19,11 @@
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs'
 import { writeJsonAtomic, writeTextAtomic } from '../atomic-fs.ts'
-import { dirname, join, sep } from 'node:path'
+import { dirname, isAbsolute, join, normalize, sep } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { loadEffectiveConfig, resolveProjectRootForExec } from '../config-loader.ts'
+import { withProjectLock } from '../file-lock.ts'
 import { runWithJob } from '../jobs.ts'
 import { countTouchedMethods } from '../method-scope.ts'
 import { fixBackupPath, fixRegistryPath, fixesDir } from '../paths.ts'
@@ -56,11 +57,28 @@ export function fixId(finding: Pick<ReviewFinding, 'file' | 'dimension' | 'line'
   return `fix-${hashString(key)}`
 }
 
+/**
+ * Exact-alignment budget for the changed middle block: a dynamic-programming
+ * LCS pass over `m × n` cells. Beyond these bounds diffLines falls back to the
+ * legacy single-hunk report (coarser counts, but never a hang), so a
+ * pathological multi-thousand-line input cannot stall the tool loop.
+ */
+export const DIFF_MAX_REGION_CELLS = 20_000
+export const DIFF_MAX_REGION_LINES = 5_000
+
 /**
  * Compute a minimal line diff between two texts.
- * Returns an array of hunks (empty when unchanged). Uses common-prefix/suffix
- * trimming then reports the changed middle block — sufficient and deterministic
- * for the small atomic edits this toolchain produces.
+ * Returns an array of hunks (empty when unchanged).
+ *
+ * Common prefix/suffix are trimmed first, then the changed middle block is
+ * aligned EXACTLY (suffix-LCS dynamic programming, bounded by
+ * DIFF_MAX_REGION_CELLS / DIFF_MAX_REGION_LINES) and split into one hunk per
+ * run of changed lines separated by unchanged lines. This keeps counts honest:
+ * changing line 1 AND line 100 of a 200-line file reports {added:2, removed:2}
+ * across two hunks, not {100,100} for the whole span — the atomic `max_lines`
+ * gate and the persisted FixRecord line counts are derived from these numbers.
+ * When the region exceeds the budget, the old single-hunk behavior is kept so
+ * huge inputs degrade to coarse-but-correct counts instead of hanging.
  */
 export function diffLines(before: string, after: string): FileDiffHunk[] {
   const a = before.split('\n')
@@ -76,6 +94,14 @@ export function diffLines(before: string, after: string): FileDiffHunk[] {
   const removed = a.slice(start, endA)
   const added = b.slice(start, endB)
   if (removed.length === 0 && added.length === 0) return []
+  return alignRegion(removed, added, start) ?? singleRegionHunk(removed, added, start)
+}
+
+/**
+ * Legacy single-hunk report for the trimmed changed block (also the bounded
+ * fallback when `alignRegion` refuses an over-budget region).
+ */
+function singleRegionHunk(removed: string[], added: string[], start: number): FileDiffHunk[] {
   const contentLines: string[] = []
   for (const line of removed) contentLines.push(`- ${line}`)
   for (const line of added) contentLines.push(`+ ${line}`)
@@ -90,6 +116,80 @@ export function diffLines(before: string, after: string): FileDiffHunk[] {
   ]
 }
 
+/**
+ * Exactly align the trimmed changed block and split it into per-spot hunks
+ * (each maximal run of changed lines, separated by at least one unchanged
+ * line). Returns `null` when the region exceeds the DP budget so the caller
+ * can fall back to {@link singleRegionHunk}.
+ *
+ * Hunk coordinates follow GNU `diff -U0` conventions: for a pure insertion
+ * `oldStart` is the line BEFORE the insertion point (oldLines = 0), for a pure
+ * deletion `newStart` is the line before the deletion point (newLines = 0),
+ * and for a replacement both point at the replaced line.
+ */
+function alignRegion(removed: string[], added: string[], start: number): FileDiffHunk[] | null {
+  const m = removed.length
+  const n = added.length
+  if (m > DIFF_MAX_REGION_LINES || n > DIFF_MAX_REGION_LINES || m * n > DIFF_MAX_REGION_CELLS) return null
+
+  // dp[i][j] = LCS length of removed[i..] / added[j..] (suffix table).
+  const stride = n + 1
+  const dp = new Int32Array((m + 1) * stride)
+  for (let i = m - 1; i >= 0; i--) {
+    for (let j = n - 1; j >= 0; j--) {
+      dp[i * stride + j] = removed[i] === added[j]
+        ? dp[(i + 1) * stride + j + 1]! + 1
+        : Math.max(dp[(i + 1) * stride + j]!, dp[i * stride + j + 1]!)
+    }
+  }
+
+  const hunks: FileDiffHunk[] = []
+  let open: { iOpen: number; jOpen: number; oldLines: number; newLines: number; content: string[] } | null = null
+  const closeHunk = (): void => {
+    if (!open) return
+    hunks.push({
+      // oldLines > 0 → first removed line (1-based); pure insertion → the
+      // line before the insertion point (= its 0-based index).
+      oldStart: start + open.iOpen + (open.oldLines > 0 ? 1 : 0),
+      oldLines: open.oldLines,
+      newStart: start + open.jOpen + (open.newLines > 0 ? 1 : 0),
+      newLines: open.newLines,
+      content: open.content.join('\n'),
+    })
+    open = null
+  }
+
+  let i = 0 // region index into removed
+  let j = 0 // region index into added
+  while (i < m || j < n) {
+    // A matching pair always belongs to SOME optimal alignment (CLRS
+    // x_i = y_j ⇒ LCS(i,j) = 1 + LCS(i+1,j+1)), so greedily closing the
+    // current hunk here is exact, not heuristic.
+    if (i < m && j < n && removed[i] === added[j]) {
+      closeHunk()
+      i++
+      j++
+      continue
+    }
+    // Diverged: consume whichever side the suffix table says costs less.
+    // Ties prefer removal so a plain replacement reads `- old / + new`.
+    const takeRemoved = i >= m ? false : j >= n ? true : dp[(i + 1) * stride + j]! >= dp[i * stride + j + 1]!
+    if (takeRemoved) {
+      if (!open) open = { iOpen: i, jOpen: j, oldLines: 0, newLines: 0, content: [] }
+      open.oldLines++
+      open.content.push(`- ${removed[i]}`)
+      i++
+    } else {
+      if (!open) open = { iOpen: i, jOpen: j, oldLines: 0, newLines: 0, content: [] }
+      open.newLines++
+      open.content.push(`+ ${added[j]}`)
+      j++
+    }
+  }
+  closeHunk()
+  return hunks
+}
+
 /** Added/removed line counts for a change (derived from diffLines). */
 export function countChangedLines(before: string, after: string): { added: number; removed: number } {
   const hunks = diffLines(before, after)
@@ -130,11 +230,18 @@ export function readRegistry(projectRoot: string): FixRegistry {
     // contain a round without a `records` array, or records that are missing
     // their id / finding object — all of which would make readers
     // (findFixRecord / recordsForFile / iterate_diff) throw or sum NaN.
+    // Numeric counters are also floored to non-negative integers: the status
+    // output schema declares them `type: 'integer'`, so a `fixedCount: 1.5`
+    // must never reach iterate_status.
+    const intCount = (v: unknown): number =>
+      typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0
     parsed.rounds = parsed.rounds
       .filter((r) => r && typeof r === 'object' && Array.isArray(r.records))
       .map((r) => ({
         ...r,
         round: typeof r.round === 'number' && Number.isFinite(r.round) ? Math.floor(r.round) : 0,
+        fixedCount: intCount(r.fixedCount),
+        failedCount: intCount(r.failedCount),
         records: r.records.filter(
           (rec): rec is FixRecord =>
             !!rec &&
@@ -160,12 +267,18 @@ export function findFixRecord(registry: FixRegistry, id: string): FixRecord | un
   return undefined
 }
 
-/** All fix records for a file, in chronological order. */
+/**
+ * All fix records for a file, in chronological order.
+ * Both sides are canonicalized with {@link normalizeProjectPath} so a record
+ * persisted as `./README.md` (pre-normalization builds) still matches a
+ * query for `README.md` and vice versa.
+ */
 export function recordsForFile(registry: FixRegistry, file: string): FixRecord[] {
+  const want = normalizeProjectPath(file)
   const out: FixRecord[] = []
   for (const round of registry.rounds) {
     for (const r of round.records) {
-      if (r.finding.file === file && r.success) out.push(r)
+      if (normalizeProjectPath(r.finding.file) === want && r.success) out.push(r)
     }
   }
   return out
@@ -251,6 +364,66 @@ export function resolveProjectFile(projectRoot: string, file: string): { ok: tru
   return { ok: true, resolved }
 }
 
+/**
+ * Canonicalize a model-supplied relative path ONCE at argument intake.
+ *
+ * Strips a leading `./`, collapses duplicate separators, and resolves `.` /
+ * `..` segments lexically so the containment check, the protected-path glob,
+ * the persisted FixRecord, and every later diff/rollback lookup all compare
+ * the SAME string — a raw `./README.md` must not dodge a `README.md` veto
+ * glob, and `src/../README.md` must record as `README.md`.
+ * Absolute paths and `..` escapes survive normalization and are rejected by
+ * {@link resolveProjectFile} afterwards. Pure, exported for unit tests.
+ */
+export function normalizeProjectPath(file: string): string {
+  // An empty intake must stay empty (node's normalize('') === '.') so
+  // resolveProjectFile still rejects it instead of resolving to the root.
+  if (typeof file !== 'string' || file === '') return ''
+  return normalize(file)
+}
+
+/**
+ * Validate a registry-recorded backup path before it is read (iterate_diff)
+ * or used to overwrite a project file (iterate_rollback).
+ *
+ * The registry is a plain JSON file on disk: a hand-edited/corrupt record can
+ * point `backupPath` anywhere, turning diff into an arbitrary-file read and
+ * rollback into arbitrary-content injection. A backup must stay inside the
+ * project's fixes directory — lexically AND via realpath when it exists (so a
+ * symlink planted inside `.iterate/fixes` cannot smuggle content either).
+ */
+export function resolveBackupPath(
+  projectRoot: string,
+  backupPath: string,
+): { ok: true; resolved: string } | { ok: false; reason: string } {
+  if (typeof backupPath !== 'string' || backupPath.trim().length === 0) {
+    return { ok: false, reason: 'backup path is missing from the fix record' }
+  }
+  const fixes = fixesDir(projectRoot)
+  // Relative entries are anchored at the project root (never the process cwd)
+  // so `../../etc/passwd` fails the containment check below.
+  const resolved = isAbsolute(backupPath) ? normalize(backupPath) : join(projectRoot, backupPath)
+  const prefix = fixes.endsWith(sep) ? fixes : fixes + sep
+  if (resolved !== fixes && !resolved.startsWith(prefix)) {
+    return { ok: false, reason: `backup path escapes the fixes directory: ${backupPath}` }
+  }
+  if (existsSync(resolved)) {
+    let realFixes: string
+    let real: string
+    try {
+      realFixes = realpathSync(fixes)
+      real = realpathSync(resolved)
+    } catch {
+      return { ok: false, reason: `failed to resolve real path for backup containment check: ${backupPath}` }
+    }
+    const realPrefix = realFixes.endsWith(sep) ? realFixes : realFixes + sep
+    if (real !== realFixes && !real.startsWith(realPrefix)) {
+      return { ok: false, reason: `backup path escapes the fixes directory (symlink): ${backupPath}` }
+    }
+  }
+  return { ok: true, resolved }
+}
+
 // ─── Shared execute helpers ──────────────────────────────────────────────────
 
 /**
@@ -384,8 +557,14 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         const maxLines = config.atomic?.max_lines ?? 20
         const maxAdjacentMethods = config.atomic?.max_adjacent_methods ?? 3
 
-        const file = typeof args.file === 'string' ? args.file : ''
-        if (!file) return { ok: false, error: 'file is required' }
+        // Canonicalize ONCE at intake: `./README.md` and `src/../README.md`
+        // must behave exactly like `README.md` downstream — the protected-path
+        // glob, the fix id, the persisted FixRecord, and later diff/rollback
+        // lookups all compare this normalized form (escapes/absolute paths
+        // survive normalization and are rejected by resolveProjectFile).
+        const rawFile = typeof args.file === 'string' ? args.file : ''
+        if (!rawFile) return { ok: false, error: 'file is required' }
+        const file = normalizeProjectPath(rawFile)
         if (typeof args.content !== 'string') return { ok: false, error: 'content must be a string' }
         if (args.content.length > MAX_FIX_CONTENT_CHARS) {
           return {
@@ -396,21 +575,23 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         if (typeof args.round !== 'number' || !Number.isInteger(args.round) || args.round < 1) {
           return { ok: false, error: 'round must be a positive integer' }
         }
-        const finding = args.finding as unknown as ReviewFinding | undefined
-        if (!finding || typeof finding !== 'object') {
+        const rawFinding = args.finding as unknown as ReviewFinding | undefined
+        if (!rawFinding || typeof rawFinding !== 'object') {
           return { ok: false, error: 'finding must be an object' }
         }
-        if (typeof finding.file !== 'string' || finding.file.trim().length === 0) {
+        if (typeof rawFinding.file !== 'string' || rawFinding.file.trim().length === 0) {
           return { ok: false, error: 'finding.file must be a non-empty string' }
         }
-        if (typeof finding.dimension !== 'string' || finding.dimension.trim().length === 0) {
+        if (typeof rawFinding.dimension !== 'string' || rawFinding.dimension.trim().length === 0) {
           return { ok: false, error: 'finding.dimension must be a non-empty string' }
         }
         // The finding must reference the file being fixed — the fix id and the
         // rollback/diff target are derived from finding.file, so a mismatch
-        // would back up/restore the WRONG file.
+        // would back up/restore the WRONG file. Both sides are compared in
+        // their NORMALIZED form (`./src/a.ts` and `src/a.ts` are the same fix).
+        const finding: ReviewFinding = { ...rawFinding, file: normalizeProjectPath(rawFinding.file) }
         if (finding.file !== file) {
-          return { ok: false, error: `finding.file ("${finding.file}") must match the file being fixed ("${file}")` }
+          return { ok: false, error: `finding.file ("${rawFinding.file}") must match the file being fixed ("${rawFile}")` }
         }
         // Full finding validation, mirroring the review schema: malformed
         // findings would produce lossy registry/log entries and a degraded id.
@@ -452,6 +633,16 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         }
 
         const id = fixId(finding)
+        const timestamp = new Date().toISOString()
+
+        // Cross-process read-modify-write guard: the registry read (dup check)
+        // and the record write form ONE window — two plugin processes racing
+        // here could each read the old registry and silently drop the other's
+        // update. The shared advisory lock (src/file-lock.ts) serializes the
+        // window; the decision-log append runs after it is released.
+        const applied = withProjectLock(projectRoot, 'fix-registry', ():
+          | { ok: false; error: string; id?: string }
+          | { ok: true; record: FixRecord; backupPath: string } => {
         const registry = readRegistry(projectRoot)
         if (findFixRecord(registry, id)) {
           return { ok: false, error: `finding already fixed this run (id: ${id})`, id }
@@ -474,7 +665,8 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         // Personalization guards (SKILL.md Phase 2): protected_paths veto the
         // fix outright; forbidden_fixes veto fix approaches appearing in the
         // new content. Both are security-relevant, so they are enforced here
-        // in the tool, not left to the model.
+        // in the tool, not left to the model. The glob runs against the
+        // NORMALIZED `file`, so `./README.md` cannot dodge a `README.md` veto.
         const pers = config.personalization as
           | { protected_paths?: unknown; forbidden_fixes?: unknown }
           | undefined
@@ -495,7 +687,6 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           }
         }
 
-        const timestamp = new Date().toISOString()
         const backupPath = fixBackupPath(projectRoot, id, timestamp)
         try {
           mkdirSync(fixesDir(projectRoot), { recursive: true })
@@ -539,6 +730,11 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           }
           return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` }
         }
+        return { ok: true, record, backupPath }
+        })
+
+        if (!applied.ok) return applied
+        const { record, backupPath } = applied
 
         const logRes = appendDecisionEntry(projectRoot, {
           timestamp,
@@ -629,17 +825,24 @@ export function registerDiffTool(ctx: { tools: { register: (def: ReturnType<type
         if (!resolved.ok) return { ok: false, error: resolved.reason }
         const projectRoot = resolved.root
         const registry = readRegistry(projectRoot)
-        const file = typeof args.file === 'string' && args.file.trim() ? args.file : undefined
+        const file = typeof args.file === 'string' && args.file.trim()
+          ? normalizeProjectPath(args.file)
+          : undefined
 
         if (file) {
           const records = recordsForFile(registry, file)
           const first = records[0]
           if (!first) return { ok: false, error: `no fixes recorded for ${file}` }
+          // Containment: the registry is on-disk JSON that a hand edit can
+          // point anywhere — a tampered backupPath must never turn this
+          // read-only diff into an arbitrary-file read.
+          const backup = resolveBackupPath(projectRoot, first.backupPath)
+          if (!backup.ok) return { ok: false, error: `invalid backup for ${file}: ${backup.reason}` }
           const current = readProjectFile(projectRoot, file)
           if (!current.ok) return { ok: false, error: current.reason }
           let original = ''
           try {
-            original = readFileSync(first.backupPath, 'utf-8')
+            original = readFileSync(backup.resolved, 'utf-8')
           } catch (err) {
             return { ok: false, error: `backup missing for ${file}: ${String(err)}` }
           }
@@ -742,10 +945,40 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
         const id = typeof args.id === 'string' ? args.id : ''
         if (!id) return { ok: false, error: 'id is required' }
 
+        // One locked read-modify-write window (see src/file-lock.ts): the
+        // registry read, the file restore, and the record removal must not
+        // interleave with another process's fix/rollback or the update is lost.
+        const restored = withProjectLock(projectRoot, 'fix-registry', ():
+          | { ok: false; error: string }
+          | { ok: true; record: FixRecord } => {
         const registry = readRegistry(projectRoot)
         const record = findFixRecord(registry, id)
         if (!record) return { ok: false, error: `fix not found: ${id}` }
-        if (!existsSync(record.backupPath)) {
+
+        // LIFO safety: restoring an OLDER backup would silently destroy every
+        // NEWER successful fix to the same file — their records would stay
+        // success:true while the bytes they wrote are gone. Refuse and name
+        // the clobbered ids so the caller can roll back in reverse order first.
+        const fileRecords = recordsForFile(registry, record.finding.file)
+        const targetIdx = fileRecords.findIndex((r) => r.id === id)
+        const newer = targetIdx >= 0
+          ? fileRecords.slice(targetIdx + 1)
+          : fileRecords.filter((r) => r.id !== id && r.timestamp > record.timestamp)
+        if (newer.length > 0) {
+          const clobbered = newer.map((r) => r.id).join(', ')
+          return {
+            ok: false,
+            error: `rollback refused: fix ${id} is older than fix(es) ${clobbered} on ${record.finding.file} — ` +
+              'restoring its backup would destroy them. Roll back the later fix(es) first (LIFO order).',
+          }
+        }
+
+        // Containment: the registry is on-disk JSON that a hand edit can
+        // point anywhere — a tampered backupPath must never inject arbitrary
+        // content into the project file.
+        const backup = resolveBackupPath(projectRoot, record.backupPath)
+        if (!backup.ok) return { ok: false, error: `invalid backup for fix ${id}: ${backup.reason}` }
+        if (!existsSync(backup.resolved)) {
           return { ok: false, error: `backup missing for fix ${id}` }
         }
 
@@ -754,7 +987,7 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
         try {
           // Atomic restore: never leave a truncated source file if we crash
           // mid-restore (matches the writeTextAtomic guarantee used by apply).
-          writeTextAtomic(target.resolved, readFileSync(record.backupPath, 'utf-8'))
+          writeTextAtomic(target.resolved, readFileSync(backup.resolved, 'utf-8'))
         } catch (err) {
           return { ok: false, error: `failed to restore backup: ${String(err)}` }
         }
@@ -765,6 +998,11 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
         } catch (err) {
           return { ok: false, error: `failed to update fix registry: ${String(err)}` }
         }
+        return { ok: true, record }
+        })
+
+        if (!restored.ok) return restored
+        const record = restored.record
 
         const logRes = appendDecisionEntry(projectRoot, {
           timestamp: new Date().toISOString(),

package/src/tools/history.ts

@@ -30,18 +30,30 @@ export function clampHistoryLimit(limit: number | undefined): number {
  * Filter + cap decision-log entries. Pure, unit-tested.
  * Returns the newest `limit` matching entries plus the total match count
  * (before the cap), so callers can tell when the result was truncated.
+ *
+ * `round` keeps only entries logged for that round; `file` keeps only entries
+ * whose `data.file` names that fixed file. Invalid `round`/`file` inputs are
+ * ignored (same convention as `type`/`since`), never treated as a match-nothing
+ * filter by accident.
  */
 export function filterDecisionEntries(
   entries: DecisionLogEntry[],
-  opts: { type?: unknown; since?: unknown; limit?: unknown },
+  opts: { type?: unknown; since?: unknown; limit?: unknown; round?: unknown; file?: unknown },
 ): { entries: DecisionLogEntry[]; filteredCount: number; limit: number } {
   const type = typeof opts.type === 'string' && opts.type ? opts.type : undefined
   const since = typeof opts.since === 'string' && opts.since ? opts.since : undefined
+  const round =
+    typeof opts.round === 'number' && Number.isInteger(opts.round) && opts.round >= 0
+      ? opts.round
+      : undefined
+  const file = typeof opts.file === 'string' && opts.file ? opts.file : undefined
   const limit = clampHistoryLimit(opts.limit as number | undefined)
 
   const matching = (Array.isArray(entries) ? entries : []).filter((e) => {
     if (type && e.type !== type) return false
     if (since && e.timestamp <= since) return false
+    if (round !== undefined && e.round !== round) return false
+    if (file && (!e.data || e.data.file !== file)) return false
     return true
   })
   return {
@@ -51,20 +63,53 @@ export function filterDecisionEntries(
   }
 }
 
-/** Per-round fix counts + totals from a fix registry. Pure, unit-tested. */
-export function summarizeFixRegistry(registry: FixRegistry): {
+/**
+ * Per-round fix counts + totals from a fix registry. Pure, unit-tested.
+ *
+ * `opts.round` narrows the view to one round. `opts.file` narrows each round to
+ * the records that fixed that file: the stored per-round counts cover every
+ * file and cannot be subsetted, so a file-scoped summary RECOMPUTES the counts
+ * from the kept records (mirroring `recomputeRoundCounts`), and rounds left
+ * without any matching record are dropped entirely — an all-zero placeholder
+ * round would falsely suggest the file was touched that round.
+ */
+export function summarizeFixRegistry(
+  registry: FixRegistry,
+  opts: { round?: unknown; file?: unknown } = {},
+): {
   totalFixed: number
   totalFailed: number
   roundCount: number
   rounds: { round: number; fixedCount: number; failedCount: number }[]
 } {
-  const rounds = (registry.rounds ?? []).map((r) => ({
-    round: r.round,
-    // Coerce defensively so a hand-edited registry round missing either count
-    // can never propagate NaN into the integer output fields.
-    fixedCount: Number(r.fixedCount) || 0,
-    failedCount: Number(r.failedCount) || 0,
-  }))
+  const roundFilter =
+    typeof opts.round === 'number' && Number.isInteger(opts.round) && opts.round >= 0
+      ? opts.round
+      : undefined
+  const fileFilter = typeof opts.file === 'string' && opts.file ? opts.file : undefined
+
+  const rounds = (registry.rounds ?? [])
+    .filter((r) => roundFilter === undefined || r.round === roundFilter)
+    .flatMap((r) => {
+      if (fileFilter === undefined) {
+        // Coerce defensively so a hand-edited registry round missing either count
+        // can never propagate NaN into the integer output fields.
+        return [{
+          round: r.round,
+          fixedCount: Number(r.fixedCount) || 0,
+          failedCount: Number(r.failedCount) || 0,
+        }]
+      }
+      const kept = (r.records ?? []).filter((rec) => rec && rec.finding && rec.finding.file === fileFilter)
+      if (kept.length === 0) return []
+      // Recompute from the kept records: a rolled-back (success:false) record
+      // counts as failed, matching the registry's own recomputeRoundCounts.
+      return [{
+        round: r.round,
+        fixedCount: kept.filter((rec) => rec.success).length,
+        failedCount: kept.filter((rec) => !rec.success).length,
+      }]
+    })
   return {
     totalFixed: rounds.reduce((s, r) => s + r.fixedCount, 0),
     totalFailed: rounds.reduce((s, r) => s + r.failedCount, 0),
@@ -75,8 +120,9 @@ export function summarizeFixRegistry(registry: FixRegistry): {
 
 /**
  * Register the `iterate_history` tool.
- * Reads the decision log (optionally filtered by type / since / limit) and a
- * fix-registry summary. Read-only; never modifies the filesystem.
+ * Reads the decision log (optionally filtered by type / since / round / file /
+ * limit) and a fix-registry summary (scoped by the same round / file filters).
+ * Read-only; never modifies the filesystem.
  */
 export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
   ctx.tools.register(
@@ -87,7 +133,8 @@ export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<t
       isConcurrencySafe: () => true,
       description:
         'Read the iteration history: decision-log entries (optionally filtered by entry `type`, `since` ' +
-        'timestamp, and a `limit`) plus a summary of the fix registry (per-round fixed/failed counts). ' +
+        'timestamp, `round`, fixed `file`, and a `limit`) plus a summary of the fix registry (per-round ' +
+        'fixed/failed counts, scoped by the same round/file filters). ' +
         'Read-only — use it to review what the run did, audit a log, or inspect fixes.',
       parameters: {
         type: {
@@ -100,6 +147,18 @@ export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<t
           type: 'string',
           description: 'Optional ISO timestamp; only entries AFTER this timestamp are returned.',
         },
+        round: {
+          type: 'integer',
+          description:
+            'Optional round number; only decision-log entries logged for this round are returned, ' +
+            'and the fix summary is scoped to this round.',
+        },
+        file: {
+          type: 'string',
+          description:
+            'Optional fixed-file path; only decision-log entries whose `data.file` matches are returned, ' +
+            'and the fix summary counts only fixes applied to that file.',
+        },
         limit: {
           type: 'integer',
           description: `Max entries to return (default: ${DEFAULT_LIMIT}, cap: ${MAX_LIMIT}). Returns the newest window in chronological order.`,
@@ -148,9 +207,9 @@ export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<t
 
         const { entries, filteredCount, limit } = filterDecisionEntries(
           readDecisionEntries(projectRoot),
-          { type: args.type, since: args.since, limit: args.limit },
+          { type: args.type, since: args.since, limit: args.limit, round: args.round, file: args.file },
         )
-        const fixes = summarizeFixRegistry(readRegistry(projectRoot))
+        const fixes = summarizeFixRegistry(readRegistry(projectRoot), { round: args.round, file: args.file })
 
         return {
           ok: true,

package/src/tools/present.ts

@@ -0,0 +1,89 @@
+/**
+ * src/tools/present.ts — shared `presentResult` helpers for the iterate tools (#12).
+ *
+ * dsh presents a completed call through `ToolDefinition.presentResult(args,
+ * result)` when the tool supplies one; the return value is a `ToolResultView`
+ * (a `card`-tagged render intent from `@deepseek-ai/dsh-tools`). These helpers
+ * read ONLY the durable result projection handed to the presenter
+ * (`result.content` / `result.isError`) — they never re-execute anything, so a
+ * live call and a session-log replay produce the identical card.
+ *
+ * House rules for every presenter built on this module:
+ *   - Pure / replay-safe: depend on `args` + `result` only.
+ *   - Defensive: any shape it cannot read returns `undefined`, which makes the
+ *     UI fall back to the default presentation (pending title + raw result)
+ *     instead of a wrong or half-guessed card.
+ *   - No invented copy: card text is derived from the render output the tool
+ *     itself produced.
+ */
+
+/** The content-block subset a presenter inspects (`ContentBlock` is structural). */
+interface RenderedBlock {
+  type?: unknown
+  text?: unknown
+}
+
+/**
+ * Concatenated text of a completed call's rendered content, or `undefined`
+ * when there is none. Failure results are never summarized — the presenter
+ * declines the card and the UI shows the raw error.
+ */
+export function renderedText(result: { content?: unknown; isError?: unknown }): string | undefined {
+  if (!result || result.isError === true || !Array.isArray(result.content)) return undefined
+  const parts: string[] = []
+  for (const block of result.content as RenderedBlock[]) {
+    if (block && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string') {
+      parts.push(block.text)
+    }
+  }
+  return parts.length > 0 ? parts.join('\n') : undefined
+}
+
+/**
+ * First non-empty line of the rendered content — the card headline for a
+ * `presentResult` (#12). Long lines are clamped so a card header stays a
+ * header. `undefined` (failure / no text) means "decline the card".
+ */
+export function resultHeadline(
+  result: { content?: unknown; isError?: unknown },
+  maxLength = 160,
+): string | undefined {
+  const text = renderedText(result)
+  if (!text) return undefined
+  const line = text.split('\n').find((l) => l.trim().length > 0)
+  if (!line) return undefined
+  const trimmed = line.trim()
+  return trimmed.length > maxLength ? `${trimmed.slice(0, maxLength - 1)}…` : trimmed
+}
+
+/**
+ * Parse a tool's rendered content as JSON — for tools whose `render` emits
+ * `JSON.stringify(value, null, 2)` verbatim (review, checkpoint). Returns a
+ * plain record, or `undefined` when the content is not an object-shaped JSON
+ * document (the presenter then declines the card rather than guess).
+ */
+export function parseRenderedJson(result: { content?: unknown; isError?: unknown }): Record<string, unknown> | undefined {
+  const text = renderedText(result)
+  if (!text) return undefined
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return undefined
+  }
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>)
+    : undefined
+}
+
+/** Narrow an unknown value to a plain record (arrays/null/primitives → undefined). */
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+/** Finite-number narrow for defensively reading fields off a parsed result. */
+export function asNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}