iterate-plugin 2.5.0 → 2.7.0

package/lib/client.js

@@ -47,6 +47,8 @@ import {
   buildCompletionSummary,
   buildConfigEditGuide,
   keyToVerdict,
+  allVerdictKeys,
+  buildRuntimeStatusGuide,
   SEVERITY_LABEL,
   SEVERITY_COLOR,
 } from './parse.js'
@@ -194,6 +196,9 @@ const ITERATE_CSS = `
 .iterate-completion[data-warn] { border: 1px solid var(--dsw-alias-state-warn-primary); color: var(--dsw-alias-state-warn-primary); background: color-mix(in srgb, var(--dsw-alias-state-warn-primary) 10%, transparent); }
 .iterate-capsule[data-ok] { border-color: var(--dsw-alias-state-success-primary); color: var(--dsw-alias-state-success-primary); }
 .iterate-settings-guide { white-space: pre-wrap; padding: 8px; border: 1px solid var(--dsw-alias-border-l1); border-radius: 8px; background: var(--dsw-alias-bg-layer-2); color: var(--dsw-alias-label-primary); font-family: var(--dsw-font-mono, ui-monospace, monospace); font-size: 11px; max-height: 180px; overflow: auto; }
+.iterate-chip[data-ok] { border-color: var(--dsw-alias-state-success-primary); color: var(--dsw-alias-state-success-primary); background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 10%, transparent); }
+.iterate-batch-check { display: inline-flex; align-items: center; gap: 4px; padding: 3px 8px; border-radius: 6px; border: 1px solid var(--dsw-alias-border-l1); background: var(--dsw-alias-bg-layer-2); color: var(--dsw-alias-label-secondary); font-size: 11px; cursor: pointer; }
+.iterate-batch-check input { margin: 0; cursor: pointer; }
 `
 
 // ─── Small helpers ───────────────────────────────────────────────────────────
@@ -225,6 +230,7 @@ function createStorage() {
       get(key) { return window.localStorage.getItem(key) },
       set(key, value) { window.localStorage.setItem(key, value) },
       remove(key) { window.localStorage.removeItem(key) },
+      keys() { return Object.keys(window.localStorage) },
     }
   } catch {
     const mem = new Map()
@@ -232,10 +238,31 @@ function createStorage() {
       get(key) { return mem.has(key) ? mem.get(key) : null },
       set(key, value) { mem.set(key, value) },
       remove(key) { mem.delete(key) },
+      keys() { return [...mem.keys()] },
     }
   }
 }
 
+/**
+ * Remove every stored key with the given prefix (e.g. all triage verdicts).
+ * Returns how many keys were removed.
+ */
+function removeStorageByPrefix(prefix) {
+  if (!storage) return 0
+  let removed = 0
+  try {
+    for (const key of storage.keys()) {
+      if (key.startsWith(prefix)) {
+        storage.remove(key)
+        removed++
+      }
+    }
+  } catch (err) {
+    log('failed to clear storage prefix', prefix, err)
+  }
+  return removed
+}
+
 /** Copy text to the clipboard, returning whether it succeeded. */
 function copyText(text) {
   if (typeof navigator !== 'undefined' && navigator.clipboard && typeof navigator.clipboard.writeText === 'function') {
@@ -357,6 +384,17 @@ function ConvergenceDashboard(props) {
     ),
   )
 
+  // Fix-count badge: show when the report has a fixes summary.
+  const mode = report.mode
+  const summary = report.summary
+  const isNormal = mode === 'normal'
+  const fixCount = isNormal && summary && typeof summary.fixedCount === 'number' ? summary.fixedCount : null
+  const fixBadge = fixCount !== null
+    ? React.createElement('span', { className: 'iterate-metric', key: 'fixes' },
+        '\u{1F527} ' + String(fixCount) + ' fixes',
+      )
+    : null
+
   return React.createElement(
     'div',
     { 'data-iterate-root': '', 'data-iterate': 'dashboard', className: 'iterate-dashboard' },
@@ -380,6 +418,7 @@ function ConvergenceDashboard(props) {
       React.createElement('span', { className: 'iterate-sev-dot', style: { background: SEVERITY_COLOR.medium } }),
       stats.medium,
     ),
+    fixBadge,
     React.createElement(TrendChart, { points: trend.points }),
     ...dimBadges,
   )
@@ -484,6 +523,7 @@ function TriagePanel(props) {
   const [copied, setCopied] = React.useState(false)
   const [filter, setFilter] = React.useState({ severities: [], dimensions: [], search: '' })
   const [selected, setSelected] = React.useState(null)
+  const [selectAll, setSelectAll] = React.useState(false)
 
   /** Persist + return the next verdicts state. */
   const persistVerdicts = (next) => {
@@ -506,13 +546,20 @@ function TriagePanel(props) {
   const setSearchFilter = (value) => setFilter((f) => ({ ...f, search: value }))
   const clearFilter = () => setFilter({ severities: [], dimensions: [], search: '' })
 
-  // ── Batch operations (apply to the currently VISIBLE findings) ───────────
+  // ── Batch operations (apply to the currently VISIBLE findings, or to ALL
+  //    findings when the select-all toggle is on) ──────────────────────────
+  const allIndices = allVerdictKeys(verdicts)
+  const batchTarget = selectAll ? allIndices : indices
   const applyBatch = (verdict) => {
-    setVerdicts((prev) => persistVerdicts(batchSetVerdict(prev, indices, verdict)))
+    setVerdicts((prev) => persistVerdicts(batchSetVerdict(prev, batchTarget, verdict)))
   }
   const applyBatchAll = (verdict) => {
     setVerdicts((prev) => persistVerdicts(setAllVerdicts(prev, verdict)))
   }
+  const doResetVerdicts = () => {
+    setVerdicts((prev) => persistVerdicts(setAllVerdicts(prev, 'keep')))
+    setSelectAll(false)
+  }
 
   // ── Keyboard shortcuts (y / n / a on the selected finding, ↑/↓ to move) ──
   React.useEffect(() => {
@@ -637,7 +684,11 @@ function TriagePanel(props) {
       ),
     ),
     React.createElement('div', { className: 'iterate-batch' },
-      React.createElement('span', { className: 'iterate-batch-label' }, '批量（当前可见）：'),
+      React.createElement('span', { className: 'iterate-batch-label' }, '批量：'),
+      React.createElement('label', { className: 'iterate-batch-check', title: '勾选后批量按钮作用于全部 findings，否则仅当前可见' },
+        React.createElement('input', { type: 'checkbox', checked: selectAll, onChange: (e) => setSelectAll(e.target.checked) }),
+        selectAll ? `全部 ${allIndices.length}` : '全选',
+      ),
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatch('keep') }, '全部 y'),
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatch('skip') }, '全部 n'),
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatch('ignore') }, '全部 a'),
@@ -645,6 +696,7 @@ function TriagePanel(props) {
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatchAll('keep') }, 'y'),
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatchAll('skip') }, 'n'),
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatchAll('ignore') }, 'a'),
+      React.createElement('button', { className: 'iterate-batch-btn', onClick: doResetVerdicts, title: '把所有判定恢复为默认 y（修复）' }, '重置'),
     ),
     ...rows,
     React.createElement('div', { className: 'iterate-triage-foot' },
@@ -712,7 +764,10 @@ function SettingsPanel() {
   const [enabled, setEnabled] = React.useState(themeEnabled)
   const [copied, setCopied] = React.useState(false)
   const [showGuide, setShowGuide] = React.useState(false)
+  const [clearedCount, setClearedCount] = React.useState(null)
+  const [showStatus, setShowStatus] = React.useState(false)
   const guide = buildConfigEditGuide()
+  const statusGuide = buildRuntimeStatusGuide()
 
   const toggleTheme = () => {
     const next = !enabled
@@ -726,6 +781,12 @@ function SettingsPanel() {
     setTimeout(() => setCopied(false), 1600)
   }
 
+  const doClearTriage = () => {
+    const count = removeStorageByPrefix(TRIAGE_STORAGE_PREFIX)
+    setClearedCount(count)
+    setTimeout(() => setClearedCount(null), 3000)
+  }
+
   return React.createElement('div', { 'data-iterate-root': '', 'data-iterate': 'settings', className: 'iterate-settings' },
     React.createElement('div', { className: 'iterate-settings-title' }, 'iterate 设置'),
     React.createElement('div', { className: 'iterate-settings-row' },
@@ -744,7 +805,16 @@ function SettingsPanel() {
         React.createElement('div', { className: 'iterate-settings-title' }, '分诊持久化'),
         React.createElement('div', { className: 'iterate-settings-desc' }, '分诊面板的 y/n/a 判定保存在本地浏览器（localStorage），刷新会话后仍保留。'),
       ),
-      React.createElement('span', { className: 'iterate-chip' }, '本地保存'),
+      React.createElement('span', { style: { display: 'flex', gap: 6, alignItems: 'center' } },
+        React.createElement('span', { className: 'iterate-chip' }, '本地保存'),
+        React.createElement('button', {
+          className: 'iterate-btn',
+          onClick: doClearTriage,
+          title: '清除所有分诊判定记录',
+          'data-primary': clearedCount !== null ? '' : undefined,
+          'data-copied': clearedCount !== null ? '' : undefined,
+        }, clearedCount !== null ? `已清除 ${clearedCount} 条` : '清除分诊'),
+      ),
     ),
     React.createElement('div', { className: 'iterate-settings-row' },
       React.createElement('div', {},
@@ -759,6 +829,16 @@ function SettingsPanel() {
     showGuide
       ? React.createElement('div', { className: 'iterate-settings-guide' }, guide)
       : null,
+    React.createElement('div', { className: 'iterate-settings-row' },
+      React.createElement('div', {},
+        React.createElement('div', { className: 'iterate-settings-title' }, '状态概览'),
+        React.createElement('div', { className: 'iterate-settings-desc' }, '运行时产物布局与清理指引。iterate_status / iterate_history / iterate_prune 工具用于查看和管理。'),
+      ),
+      React.createElement('button', { className: 'iterate-btn', onClick: () => setShowStatus((v) => !v) }, showStatus ? '收起' : '查看'),
+    ),
+    showStatus
+      ? React.createElement('div', { className: 'iterate-settings-guide' }, statusGuide)
+      : null,
   )
 }
 

package/lib/parse.js

@@ -787,4 +787,72 @@ export const VERDICT_SHORTCUTS = {
  */
 export function keyToVerdict(key) {
   return VERDICT_SHORTCUTS[key] ?? null
+}
+
+// ─── Select-all keys ────────────────────────────────────────────────────────
+
+/**
+ * Every finding index in a triage state, sorted ascending.
+ * Used by the select-all toggle so batch operations can target ALL findings
+ * (not just the currently visible/filtered ones).
+ *
+ * @param {Record<string, 'keep' | 'skip' | 'ignore'> | null | undefined} triageState
+ * @returns {number[]}
+ */
+export function allVerdictKeys(triageState) {
+  const state = triageState && typeof triageState === 'object' ? triageState : {}
+  return Object.keys(state)
+    .map(Number)
+    .filter((n) => Number.isInteger(n) && n >= 0)
+    .sort((a, b) => a - b)
+}
+
+// ─── Runtime status guide ────────────────────────────────────────────────────
+
+/**
+ * Runtime artifacts produced under `<projectRoot>/.iterate/`.
+ * @type {Array<{ key: string, label: string, hint: string }>}
+ */
+export const RUNTIME_ARTIFACTS = [
+  {
+    key: 'decision-log.jsonl',
+    label: '决策日志',
+    hint: '追加式 JSONL，记录每轮 plan / review / fix / revert / validation 决策',
+  },
+  {
+    key: 'checkpoint.json',
+    label: '迭代断点',
+    hint: '长迭代的进度快照，中断后可恢复（iterate_checkpoint）',
+  },
+  {
+    key: 'fixes/registry.json',
+    label: '修复注册表',
+    hint: '每个原子修复的 id / diff / 备份路径（iterate_fix / iterate_diff）',
+  },
+  {
+    key: 'fixes/*.bak',
+    label: '修复备份',
+    hint: '每次修复前的原文件备份，回滚依赖（iterate_rollback）',
+  },
+]
+
+/**
+ * Copy-paste guide for inspecting / pruning the runtime state. Shown in the
+ * settings "状态概览" card so the user knows exactly where artifacts live and
+ * which tools inspect them.
+ *
+ * @returns {string}
+ */
+export function buildRuntimeStatusGuide() {
+  const lines = [
+    'iterate 运行时状态概览',
+    '----------------------',
+    '所有运行时产物位于项目根目录 .iterate/ 下：',
+    '',
+    ...RUNTIME_ARTIFACTS.map((a) => `- ${a.key}（${a.label}）：${a.hint}`),
+    '',
+    '查看状态：让模型调用 iterate_status（汇总）或 iterate_history（明细）。',
+    '清理状态：让模型调用 iterate_prune（默认 dry-run，只报告不删除，显式 dryRun:false 才真正清理）。',
+  ]
+  return lines.join('\n')
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus a dry-run pure-review mode with multi-round convergence and a meta-review that audits the report and emits a final review report.",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,7 @@
   "files": [
     "src",
     "lib",
+    "dist",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"
@@ -44,11 +45,14 @@
   "exports": {
     ".": {
       "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "default": "./dist/index.js"
     },
-    "./client": "./lib/client.js"
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit",
     "test": "tsx --test test/*.test.ts",
     "test:validate": "tsx --test test/validate.test.ts"

package/src/index.ts

@@ -30,6 +30,8 @@ import { registerReviewTool } from './tools/review.ts'
 import { registerTriageTool } from './tools/triage.ts'
 import { registerFixTool, registerDiffTool, registerRollbackTool } from './tools/fix.ts'
 import { registerCheckpointTool, registerStatusTool } from './tools/checkpoint.ts'
+import { registerHistoryTool } from './tools/history.ts'
+import { registerPruneTool } from './tools/prune.ts'
 import { ITERATE_SKILL_PROMPT } from './skill-prompt.ts'
 
 export const name = 'iterate-plugin'
@@ -48,6 +50,8 @@ export function apply(ctx: Context): void {
   registerRollbackTool(ctx)
   registerCheckpointTool(ctx)
   registerStatusTool(ctx)
+  registerHistoryTool(ctx)
+  registerPruneTool(ctx)
 
   // 2. Inject the iterate skill prompt as a system prompt section
   // This teaches the model how to write iterate workflow scripts using the tools.

package/src/meta-review.ts

@@ -205,7 +205,20 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
         `but totalFindings is ${total}.`,
     )
   }
-  const lastRoundNew = findingsByRound.length > 0 ? Number(findingsByRound[findingsByRound.length - 1]) : null
+  // `findingsByRound` is indexed by the actual round number (round r → index
+  // r-1), so the "last round" is the LAST RECORDED round's reported number, not
+  // the array's last index (the array is sized to the highest round, which only
+  // equals the record count for contiguous 1..N round numbers). Read the flag
+  // consistency the same way buildReviewReport/computeConvergence set it.
+  const reportRounds = Array.isArray(report.rounds) ? report.rounds : []
+  const lastRecordedRound =
+    reportRounds.length > 0 && typeof reportRounds[reportRounds.length - 1]?.round === 'number'
+      ? reportRounds[reportRounds.length - 1]!.round
+      : null
+  const lastRoundNew =
+    lastRecordedRound !== null && lastRecordedRound > 0
+      ? Number(findingsByRound[lastRecordedRound - 1] ?? 0)
+      : null
   const expectedConverged = lastRoundNew === 0
   if (report.convergence?.converged !== expectedConverged) {
     add(

package/src/review.ts

@@ -106,7 +106,12 @@ export function filterKnownIntentional(
  * Merge per-round findings into one globally-deduped stream while tracking
  * which round first surfaced each finding. This is the deterministic core of
  * "反复多轮审查直至收敛":
- *  - `findingsByRound[r]` = number of GLOBALLY new findings first seen in round r
+ *  - `findingsByRound` = number of GLOBALLY new findings first seen in round r,
+ *    indexed by the actual `round` number (round r → index r-1). The array is
+ *    sized to the highest round number encountered, so non-contiguous round
+ *    numbers (e.g. a resumed run that starts at round 5, or a caller that only
+ *    passes `[{round: 3}]`) still yield correct counts instead of being
+ *    collapsed onto wrong indices.
  *  - `converged` = the last executed round produced 0 new findings
  *  - `stoppedReason` = 'converged' | 'max_rounds_reached'
  */
@@ -122,7 +127,12 @@ export function aggregateRounds(
   const firstRoundByKey = new Map<string, number>()
   const merged: ReviewFinding[] = []
 
+  // Guard: round numbers are expected to be positive integers. Skip malformed
+  // entries defensively rather than letting `firstRoundByKey` key on NaN/0.
+  let maxRound = 0
   for (const round of rounds) {
+    if (typeof round.round !== 'number' || !Number.isInteger(round.round) || round.round < 1) continue
+    if (round.round > maxRound) maxRound = round.round
     for (const f of round.findings) {
       const key = findingKey(f)
       if (seen.has(key)) continue
@@ -133,7 +143,7 @@ export function aggregateRounds(
   }
 
   const findingsByRound: number[] = []
-  for (let r = 1; r <= rounds.length; r++) {
+  for (let r = 1; r <= maxRound; r++) {
     let count = 0
     for (const key of firstRoundByKey.keys()) {
       if (firstRoundByKey.get(key) === r) count++
@@ -153,7 +163,13 @@ export function computeConvergence(
 ): ReviewReport['convergence'] {
   const { findingsByRound } = aggregateRounds(rounds, maxReviewRounds)
   const totalRounds = rounds.length
-  const lastRoundCount = totalRounds > 0 ? findingsByRound[totalRounds - 1] ?? 0 : 0
+  // `findingsByRound` is indexed by the actual round number (round r → index
+  // r-1), so convergence must read the LAST PRESENT round's count using its
+  // reported round number — not `totalRounds - 1`, which is only valid for
+  // contiguous 1..N round numbers.
+  const lastRound = totalRounds > 0 ? rounds[totalRounds - 1]!.round : 0
+  const lastRoundCount =
+    lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0
   const converged = totalRounds > 0 && lastRoundCount === 0
   return {
     totalRounds,
@@ -218,6 +234,18 @@ export function buildReviewReport(input: {
   // 3. Severity sort the global result.
   const sorted = sortFindings(findings)
 
+  // 4. Convergence. Must be identical to `computeConvergence`: `findingsByRound`
+  //    is indexed by the actual round number (round r → index r-1) and sized to
+  //    the highest round, so convergence reads the LAST PRESENT round's count
+  //    using its reported round number — NOT `filteredRounds.length - 1`, which
+  //    is only valid for contiguous 1..N round numbers (resumed iterations and
+  //    non-contiguous round sets would otherwise read the wrong count).
+  const lastRound =
+    filteredRounds.length > 0 ? filteredRounds[filteredRounds.length - 1]!.round : 0
+  const lastRoundCount =
+    lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0
+  const converged = filteredRounds.length > 0 && lastRoundCount === 0
+
   return {
     mode: input.mode,
     goal: input.goal,
@@ -228,11 +256,11 @@ export function buildReviewReport(input: {
     convergence: {
       totalRounds: filteredRounds.length,
       findingsByRound,
-      converged: filteredRounds.length > 0 && (findingsByRound[filteredRounds.length - 1] ?? 0) === 0,
+      converged,
       stoppedReason:
         filteredRounds.length === 0
           ? 'max_rounds_reached'
-          : (findingsByRound[filteredRounds.length - 1] ?? 0) === 0
+          : converged
             ? 'converged'
             : 'max_rounds_reached',
     },

package/src/tools/fix.ts

@@ -26,6 +26,11 @@ import { fixBackupPath, fixRegistryPath, fixesDir } from '../paths.ts'
 import { appendDecisionEntry } from './decision-log.ts'
 import type { FileDiffHunk, FixRecord, FixRegistry, ReviewFinding } from '../types.ts'
 
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Upper bound for a single fix `content` payload (characters). */
+export const MAX_FIX_CONTENT_CHARS = 1_000_000
+
 // ─── Pure helpers (exported for unit tests) ─────────────────────────────────
 
 /**
@@ -288,6 +293,12 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         const file = typeof args.file === 'string' ? args.file : ''
         if (!file) return { ok: false, error: 'file is required' }
         if (typeof args.content !== 'string') return { ok: false, error: 'content must be a string' }
+        if (args.content.length > MAX_FIX_CONTENT_CHARS) {
+          return {
+            ok: false,
+            error: `content exceeds the ${MAX_FIX_CONTENT_CHARS}-character limit (got ${args.content.length})`,
+          }
+        }
         if (typeof args.round !== 'number' || !Number.isInteger(args.round) || args.round < 1) {
           return { ok: false, error: 'round must be a positive integer' }
         }

package/src/tools/history.ts

@@ -0,0 +1,162 @@
+/**
+ * src/tools/history.ts — iteration history reader.
+ *
+ *   iterate_history — read the decision-log entries (with optional filters)
+ *                     plus a summary of the fix registry, so the user or the
+ *                     orchestrator can review exactly what the run did.
+ *
+ * Complements `iterate_status` (compact summary) with the actual detail.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { resolveProjectRoot } from '../config-loader.ts'
+import { readDecisionEntries } from './decision-log.ts'
+import { readRegistry } from './fix.ts'
+import type { DecisionLogEntry, FixRegistry } from '../types.ts'
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 200
+
+/** Clamp a caller-supplied `limit` to a sane range. */
+export function clampHistoryLimit(limit: number | undefined): number {
+  if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
+    return DEFAULT_LIMIT
+  }
+  return Math.min(limit, MAX_LIMIT)
+}
+
+/**
+ * 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.
+ */
+export function filterDecisionEntries(
+  entries: DecisionLogEntry[],
+  opts: { type?: unknown; since?: unknown; limit?: 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 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
+    return true
+  })
+  return {
+    entries: matching.slice(-limit),
+    filteredCount: matching.length,
+    limit,
+  }
+}
+
+/** Per-round fix counts + totals from a fix registry. Pure, unit-tested. */
+export function summarizeFixRegistry(registry: FixRegistry): {
+  totalFixed: number
+  totalFailed: number
+  roundCount: number
+  rounds: { round: number; fixedCount: number; failedCount: number }[]
+} {
+  const rounds = (registry.rounds ?? []).map((r) => ({
+    round: r.round,
+    fixedCount: r.fixedCount,
+    failedCount: r.failedCount,
+  }))
+  return {
+    totalFixed: rounds.reduce((s, r) => s + r.fixedCount, 0),
+    totalFailed: rounds.reduce((s, r) => s + r.failedCount, 0),
+    roundCount: rounds.length,
+    rounds,
+  }
+}
+
+/**
+ * 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.
+ */
+export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_history',
+      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). ' +
+        'Read-only — use it to review what the run did, audit a log, or inspect fixes.',
+      parameters: {
+        type: {
+          type: 'string',
+          description:
+            'Optional entry-type filter: round_start, review_result, atomic_fix, architectural_fix, ' +
+            'revert, validation, decision, report.',
+        },
+        since: {
+          type: 'string',
+          description: 'Optional ISO timestamp; only entries AFTER this timestamp are returned.',
+        },
+        limit: {
+          type: 'integer',
+          description: `Max entries to return (default: ${DEFAULT_LIMIT}, cap: ${MAX_LIMIT}). Newest first.`,
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            kind: { type: 'string' },
+            count: { type: 'integer' },
+            filteredCount: { type: 'integer' },
+            limit: { type: 'integer' },
+            log: { type: 'json' },
+            fixes: { type: 'json' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `history failed: ${value.error}` }]
+          const log = (value.log as DecisionLogEntry[] | undefined) ?? []
+          const fixes = (value.fixes as { totalFixed: number; totalFailed: number; roundCount: number } | undefined)
+          const lines = [
+            `Decision-log entries: ${value.count} (filtered to ${value.limit})`,
+            fixes
+              ? `Fixes: ${fixes.totalFixed} applied · ${fixes.totalFailed} failed · across ${fixes.roundCount} round(s)`
+              : 'Fixes: none',
+            '',
+            ...log.map((e) => `[${e.timestamp}] r${e.round} ${e.type}: ${JSON.stringify(e.data ?? {})}`),
+          ]
+          return [{ type: 'text', text: lines.join('\n') }]
+        },
+      },
+
+      async execute(args) {
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) return { ok: false, kind: 'history', error: resolved.reason }
+        const projectRoot = resolved.root
+
+        const { entries, filteredCount, limit } = filterDecisionEntries(
+          readDecisionEntries(projectRoot),
+          { type: args.type, since: args.since, limit: args.limit },
+        )
+        const fixes = summarizeFixRegistry(readRegistry(projectRoot))
+
+        return {
+          ok: true,
+          kind: 'history',
+          count: entries.length,
+          filteredCount,
+          limit,
+          log: entries as unknown as JsonValue,
+          fixes: fixes as unknown as JsonValue,
+        }
+      },
+    }),
+  )
+}