iterate-plugin 3.8.0 → 3.9.0

package/README.md

@@ -107,7 +107,7 @@ Both modes share:
 ### UI layer (build-free client slots, v3.7: 11 tabs, bilingual)
 
 - **ConvergenceDashboard** (`conversation.input.dock`) — live round progress bar, severity stats, dimension badges, trend mini-chart above the input; normal mode also shows fix-count badges; plus a live workflow-phase chip (current phase + running/stopped) and a **task_mode indicator (code / iterate)**, now backed by the persisted transcript (`iterate_status` / `iterate_transcript` emit `taskMode`). While a run is active the dashboard switches to a running state (round + phase) instead of the static empty state, and the start buttons are hidden.
-- **ObservatoryPanel** (`conversation.input.dock`) — an **eleven-tab** runtime observatory below the input: **live activity stream** (default tab, type filter) + **F1** review threads (expand / collapse all), **F2** convergence trend (incl. the per-round comparison table: findings raised / fixed / severity mix / validation outcomes), **F3** finding locations (severity / dimension / search filter), **F4** fixes + rollback, **F5** checkpoint resume, **F6** run console, **F7** decision timeline (type / round filter + search), **F8** Quality Gate, **F9** Experience Bank, **F10** Defense Events. Number-key shortcuts: `1`–`9` jump to F1–F9, `0` to F10, `-` back to the live stream. **F8/F9/F10 are live** — they scan the session stream for the latest `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` results and render real data (PASS/FAIL chip + per-dimension score bars, experience entries with adopt buttons + client-side search, defense type-count chips + filtered event stream); when the session stream has none they distinguish "no data on disk" from "not pulled yet" and offer a **拉取磁盘快照 (pull disk snapshot)** instruction that has the model call the read-side tools and echo the `.iterate/` artifacts back into the stream. One-click JSON export of all observatory data — manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report` (download, copy fallback). **v3.5.3: reset actions surfaced** — F5 copies an `iterate_checkpoint clear` instruction, F8 an `iterate_quality_gate clear` instruction, F10 an `iterate_defense_events clear` instruction.
+- **ObservatoryPanel** (`conversation.input.dock`) — an **eleven-tab** runtime observatory below the input: **live activity stream** (default tab, type filter) + **F1** review threads (expand / collapse all), **F2** convergence trend (incl. the per-round comparison table: findings raised / fixed / severity mix / validation outcomes), **F3** finding locations (severity / dimension / search filter), **F4** fixes + rollback, **F5** checkpoint resume, **F6** run console, **F7** decision timeline (type / round filter + search), **F8** Quality Gate, **F9** Experience Bank, **F10** Defense Events. Number-key shortcuts: `1`–`9` jump to F1–F9, `0` to F10, `-` back to the live stream. **F8/F9/F10 are live** — they scan the session stream for the latest `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` results and render real data (PASS/FAIL chip + per-dimension score bars, experience entries with adopt buttons + client-side search, defense type-count chips + filtered event stream); when the session stream has none they distinguish "no data on disk" from "not pulled yet" and offer a **拉取磁盘快照 (pull disk snapshot)** instruction that has the model call the read-side tools and echo the `.iterate/` artifacts back into the stream. One-click JSON export of all observatory data — manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report` (download, copy fallback). **v3.9: two report-export buttons** (导出报告 / 导出 SARIF) render the *same shared data model* as the `iterate_report` tool — a PR-pasteable Markdown run report and a SARIF 2.1.0 log for CI / GitHub Code Scanning. **v3.5.3: reset actions surfaced** — F5 copies an `iterate_checkpoint clear` instruction, F8 an `iterate_quality_gate clear` instruction, F10 an `iterate_defense_events clear` instruction.
 - **TriagePanel** (`conversation.chat.turnTail`) — per-finding triage with `y` (keep → fix), `n` (skip), `a` (known-intentional) keyboard shortcuts and `↑`/`↓` navigation (focus-guarded: only active while the panel has focus), filtering, batch ops (incl. select-all), localStorage persistence. **Write-back closed loop**: the primary button copies an `iterate_triage apply` instruction for the marked entries (the tool validates, dedupes, backs up, rolls back on failure); a secondary button copies the raw `known_intentional` YAML; **回读已写入条目** copies an `iterate_triage list` instruction to confirm what actually landed. Copy payloads are aligned to the target tool schemas. **v3.2: native command buttons** (approve architectural fix, trigger new round, rollback to checkpoint). **v3.3: §8 指派修复 (assign)** — one click copies an `iterate_fix` instruction carrying every in-scope finding (respecting the batch toggle).
 - **StatsCard** (`conversation.chat.turnTail`) — convergence stats, round history, trend chart and completion summary when no findings remain.
 - **iterate theme skin** (`theme.overrideTokens`) — a warm-amber 13-token `--dsw-*` override, light/dark modes, togglable in settings.
@@ -303,10 +303,11 @@ validation:
 - `iterate_status` — summarize current iteration state: mode, current/last round, fixes applied, remaining architectural, decision-log entry count, whether a checkpoint exists; **v3.4: also surfaces the persisted quality-gate snapshot, experience-bank summary, and defense-events summary** (`qualityGate` / `experienceBank` / `defenseEvents`)
 - `iterate_history` — read iteration history (read-only): decision-log entries (filter by `type` / `since` / `round` / fixed `file` / `limit`, default latest 50, cap 200) + fix-registry summary (per-round fixed/failed counts, scoped by the same round/file filters; a `file`-scoped summary recomputes counts from the kept records). For auditing the run, tracing logs, and inventorying fixes
 - `iterate_prune` — clean runtime artifacts: stale decision-log entries (by `retainDays`, default 30), stale checkpoints, orphaned fix backups, empty rounds, stray temp files (crashed atomic writes). Dry-run by default (report-only); real cleanup with `dryRun:false`, each cleanup logged
-- `iterate_transcript` — runtime observatory: persist review transcripts, threads, fixes, and nudge directions to `.iterate/transcript.json` for the client observatory
+- `iterate_transcript` — runtime observatory: persist review transcripts, threads, fixes, and nudge directions to `.iterate/transcript.json` for the client observatory. **v3.9: `read` recovers a summary manifest from the session log's run record when the file is lost/corrupt (`recovered:true`); `capture` links the run to the dsh session (`sessionRecord`); `recall` lists this session's run records (newest first)**
 - `iterate_experience` — **v3.2** query the experience bank (list / search / get), `add` a new verified fix (re-adding the same pattern+dimension bumps its hit count instead of duplicating it), or **v3.5 remove a stale/incorrect entry by `id`** so bad experiences never resurface. Persists to `.iterate/experience.json`
 - `iterate_quality_gate` — **v3.2** read the quality certificate (`read`), or recompute + persist a fresh one (`compute`) from findings, validation results, `findingsByRound`, and `fixedByDimension`. Real per-dimension convergence rates. **v3.5: `clear` removes the persisted certificate to reset a stale gate before a fresh iteration**
 - `iterate_defense_events` — **v3.2** query defense events (list / counts), `record` a new one, or **v3.5.3 `clear` the persisted stream** so a fresh iteration starts without stale defensive data. Human-readable labels follow the project language (en / zh)
+- `iterate_report` — **v3.9** export the run as a portable report. `format:"markdown"` (default) renders a PR-pasteable report (run header, quality gate, findings, fixes, validations, defense events, experience bank); `format:"sarif"` renders a SARIF 2.1.0 log for CI / GitHub Code Scanning (one rule per review dimension, severity → error/warning/note, file+line locations, suggested fix attached). `write:true` persists it to `.iterate/report.md` / `.iterate/report.sarif`; `lang` (zh | en) selects the report language. Read-only apart from the optional report file
 
 ---
 
@@ -343,12 +344,14 @@ All runtime state lives under `.iterate/` at the project root (can be excluded v
   `0.1.5-rc.1`, `0.1.5-rc.2`, `0.1.6-alpha.1`, `0.1.6-alpha.2`,
   `0.1.7-alpha.1`, `0.1.7-alpha.2`, `0.1.7-rc.1`, `0.1.7-rc.2`, `0.2.0-rc.1`,
   `0.2.0-rc.2`, `0.2.1-alpha.1`, `0.2.1-alpha.2`, `0.2.1-alpha.3`,
-  `0.2.1-alpha.4` (21 releases, `0.1.1-rc.1` …
-  `0.2.1-alpha.4`).
+  `0.2.1-alpha.4`, `0.2.1-alpha.5`, `0.2.1-rc.1`, `0.2.1-rc.2` (24 releases,
+  `0.1.1-rc.1` …
+  `0.2.1-rc.2`).
   The plugin is built against `@deepseek-ai/dsh-tools` /
-  `@deepseek-ai/dsh-util-values` `0.2.1-alpha.4` and uses only public contracts
-  (tool registration, client slots + theme, bundle patch).
-  It also declares `engines.dsh` (`>=0.1.1-rc.1`) so the dsh ≥ 0.2.1-alpha.4
+  `@deepseek-ai/dsh-util-values` `0.2.1-rc.2` and uses only public contracts
+  (tool registration, client slots + theme, bundle patch, and — since v3.9 —
+  the session state-record API for session-linked run records).
+  It also declares `engines.dsh` (`>=0.1.1-rc.1`) so the dsh ≥ 0.2.1-rc.2
   runtime evaluates compatibility from that single range (earlier runtimes fall
   back to the `@deepseek-ai/dsh-*` peer versions listed in `package.json`).
 - **Disposable-Profile evidence (real, `dsh` CLI `0.1.1-rc.1`)**: on a temp

package/README.zh-CN.md

@@ -106,7 +106,7 @@ dsh plugin --profile web add iterate-plugin
 ### UI 层（客户端免构建槽位，v3.7：11 个页签，双语）
 
 - **收敛看板 `ConvergenceDashboard`**（`conversation.input.dock`）— 输入框上方实时显示轮次进度条、严重度统计、维度徽章、趋势迷你图；normal 模式另显示修复计数徽章；还有运行阶段芯片（当前工作流阶段 + 运行中/已结束）与 **task_mode 指示器（code / iterate）**。运行期间看板切换为"运行中"状态（显示轮次与阶段），并隐藏启动按钮。
-- **运行时观测台 `ObservatoryPanel`**（`conversation.input.dock`）— 输入框下方**十一个页签**运行时观测台：**实时活动流**（默认页，支持按活动类型筛选）+ **F1** 审查线程（全部展开/全部收起）、**F2** 收敛趋势（含跨轮对比表：每轮 findings / fixed / 严重度分布 / 验证结果）、**F3** 发现定位（按严重度/维度/关键词筛选）、**F4** 修复与回滚、**F5** 断点恢复、**F6** 运行控制台、**F7** 决策时间线（按类型/轮次筛选与关键词搜索）、**F8** 质量门禁、**F9** 经验银行、**F10** 防御事件。数字键快捷键：`1`–`9` 跳到 F1–F9，`0` 到 F10，`-` 回实时活动流。**F8/F9/F10 为实时数据**——扫描会话流中最近一次 `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` 结果并渲染真实数据（PASS/FAIL 徽章 + 分维度评分条、经验条目（含采纳按钮 + 客户端搜索）、防御类型计数芯片 + 筛选后的事件流）；会话流中没有数据时区分"磁盘无数据"与"尚未拉取"，并提供**拉取磁盘快照**指令（让模型调用只读工具、把 `.iterate/` 产物回显进会话流）。一键导出全部观测数据为 JSON——manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report`（优先下载，失败回退复制）。**v3.5.3 新增重置操作**：F5 复制 `iterate_checkpoint clear`、F8 复制 `iterate_quality_gate clear`、F10 复制 `iterate_defense_events clear` 指令。
+- **运行时观测台 `ObservatoryPanel`**（`conversation.input.dock`）— 输入框下方**十一个页签**运行时观测台：**实时活动流**（默认页，支持按活动类型筛选）+ **F1** 审查线程（全部展开/全部收起）、**F2** 收敛趋势（含跨轮对比表：每轮 findings / fixed / 严重度分布 / 验证结果）、**F3** 发现定位（按严重度/维度/关键词筛选）、**F4** 修复与回滚、**F5** 断点恢复、**F6** 运行控制台、**F7** 决策时间线（按类型/轮次筛选与关键词搜索）、**F8** 质量门禁、**F9** 经验银行、**F10** 防御事件。数字键快捷键：`1`–`9` 跳到 F1–F9，`0` 到 F10，`-` 回实时活动流。**F8/F9/F10 为实时数据**——扫描会话流中最近一次 `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` 结果并渲染真实数据（PASS/FAIL 徽章 + 分维度评分条、经验条目（含采纳按钮 + 客户端搜索）、防御类型计数芯片 + 筛选后的事件流）；会话流中没有数据时区分"磁盘无数据"与"尚未拉取"，并提供**拉取磁盘快照**指令（让模型调用只读工具、把 `.iterate/` 产物回显进会话流）。一键导出全部观测数据为 JSON——manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report`（优先下载，失败回退复制）。**v3.9 新增两个报告导出按钮**（导出报告 / 导出 SARIF），与 `iterate_report` 工具共用同一份数据模型——分别产出可直接粘贴进 PR 的 Markdown 运行报告，与供 CI / GitHub Code Scanning 消费的 SARIF 2.1.0 日志。**v3.5.3 新增重置操作**：F5 复制 `iterate_checkpoint clear`、F8 复制 `iterate_quality_gate clear`、F10 复制 `iterate_defense_events clear` 指令。
 - **Findings 分诊面板 `TriagePanel`**（`conversation.chat.turnTail`）— 逐条分诊，键盘快捷键 `y`（保留→修复）、`n`（跳过）、`a`（已知有意）与 `↑`/`↓` 移动（焦点守卫：仅面板内焦点时生效），支持筛选、批量（含一键全选所有 findings）、localStorage 持久化。**写回闭环**：主按钮复制已标记条目的 `iterate_triage apply` 指令（工具负责校验、去重、备份、失败回滚）；次按钮复制裸 `known_intentional` YAML；**回读已写入条目**复制 `iterate_triage list` 指令核对实际落盘内容。复制载荷与目标工具 schema 对齐。**v3.2：原生命令按钮**（批准架构修复、触发新一轮、回滚到断点）。
 - **收敛统计卡片 `StatsCard`**（`conversation.chat.turnTail`）— 无 findings 时显示收敛统计、历史轮次、趋势图、完成摘要。
 - **iterate 主题皮肤**（`theme.overrideTokens`）— 暖琥珀配色的 13 个 `--dsw-*` token 覆盖，明暗双模式，可在设置页开关。
@@ -302,10 +302,11 @@ validation:
 - `iterate_status` — 汇总当前迭代状态：模式、当前轮/总轮、已修复数、剩余 architectural、决策日志条数、是否存在 checkpoint；**v3.4：同时返回持久化的质量门禁快照、经验银行摘要与防御事件摘要**（`qualityGate` / `experienceBank` / `defenseEvents`）
 - `iterate_history` — 读取迭代历史（只读）：决策日志条目（可按 `type` / `since` / `round` / 修复文件 `file` / `limit` 过滤，默认取最新 50 条，上限 200 条）+ 修复注册表汇总（各轮 fixed/failed 计数，按同一 round/file 过滤收窄；`file` 过滤时按保留的记录重算计数）。用于审查运行过程、审计日志、盘点修复
 - `iterate_prune` — 清理运行时产物：过期决策日志条目（按 `retainDays`，默认 30 天）、陈旧断点、孤儿修复备份、空轮次、崩溃原子写入残留的临时文件。默认 dry-run 只报告不删除；`dryRun:false` 才真正清理，每次清理写入决策日志
-- `iterate_transcript` — 运行时观测台：把审查转录、线程、修复与 nudge 指令持久化到 `.iterate/transcript.json`，供客户端观测台读取
+- `iterate_transcript` — 运行时观测台：把审查转录、线程、修复与 nudge 指令持久化到 `.iterate/transcript.json`，供客户端观测台读取。**v3.9：`read` 在文件丢失/损坏时从会话日志的运行记录恢复出一份摘要 manifest（`recovered:true`）；`capture` 把本次运行关联到 dsh 会话（`sessionRecord`）；`recall` 列出本会话的运行记录（最新在前）**
 - `iterate_experience` — **v3.2** 查询经验银行（list / search / get），或 `add` 一条新的已验证修复：重复添加同一 pattern + dimension 累加命中次数而非重复写入。**v3.5 新增 `remove`：按 `id` 删除过时或错误的经验条目**。持久化到 `.iterate/experience.json`
 - `iterate_quality_gate` — **v3.2** 读取质量凭证（`read`），或基于 findings、验证结果、`findingsByRound` 与 `fixedByDimension` 重新计算并持久化一份新凭证（`compute`）。真实的逐维度收敛率。**v3.5 新增 `clear`：删除持久化的质量凭证**，用于新一轮迭代前重置陈旧的门禁
 - `iterate_defense_events` — **v3.2** 查询防御事件（list / counts），`record` 记录一条新事件，或 **v3.5.3 `clear` 清除持久化事件流**，让新一轮迭代不带陈旧防御数据起跑。可读标签跟随项目语言（en / zh）
+- `iterate_report` — **v3.9** 把本次运行导出为可移植报告。`format:"markdown"`（默认）产出可直接粘贴进 PR 的报告（运行头部、质量门禁、发现、修复、验证、防御事件、经验银行）；`format:"sarif"` 产出 SARIF 2.1.0 日志供 CI / GitHub Code Scanning 消费（每个审查维度一条规则，严重度 → error/warning/note，携带文件+行号位置与建议修复）。`write:true` 持久化到 `.iterate/report.md` / `.iterate/report.sarif`；`lang`（zh | en）选择报告语言。除可选的报告文件外均为只读
 
 ---
 
@@ -334,7 +335,7 @@ validation:
 ### Node.js / DSH 兼容范围
 
 - **Node.js**：`>=20`（`package.json` 的 `engines.node`）。
-- **DSH**：`package.json` 的 `dsh.compatibility.dshReleases` 字段是发布兼容性的**唯一真源**（本 README 逐字镜像该字段；两者需同步更新）。以下官方版本声明为 `compatible`：`0.1.1-rc.1`、`0.1.2-alpha.4`、`0.1.2-alpha.5`、`0.1.2-rc.1`、`0.1.3-alpha.1`、`0.1.5-alpha.1`、`0.1.5-alpha.2`、`0.1.5-rc.1`、`0.1.5-rc.2`、`0.1.6-alpha.1`、`0.1.6-alpha.2`、`0.1.7-alpha.1`、`0.1.7-alpha.2`、`0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-alpha.1`、`0.2.1-alpha.2`、`0.2.1-alpha.3`、`0.2.1-alpha.4`（共 21 个版本，`0.1.1-rc.1` … `0.2.1-alpha.4`）。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.2.1-alpha.4` 构建，只使用公开契约（工具注册、客户端 slots + theme、bundle patch）。插件同时声明 `engines.dsh`（`>=0.1.1-rc.1`），使 dsh ≥ 0.2.1-alpha.4 运行时只依据该范围判断兼容性（更早的运行时仍回退校验 `package.json` 中列出的 `@deepseek-ai/dsh-*` peer 版本）。
+- **DSH**：`package.json` 的 `dsh.compatibility.dshReleases` 字段是发布兼容性的**唯一真源**（本 README 逐字镜像该字段；两者需同步更新）。以下官方版本声明为 `compatible`：`0.1.1-rc.1`、`0.1.2-alpha.4`、`0.1.2-alpha.5`、`0.1.2-rc.1`、`0.1.3-alpha.1`、`0.1.5-alpha.1`、`0.1.5-alpha.2`、`0.1.5-rc.1`、`0.1.5-rc.2`、`0.1.6-alpha.1`、`0.1.6-alpha.2`、`0.1.7-alpha.1`、`0.1.7-alpha.2`、`0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-alpha.1`、`0.2.1-alpha.2`、`0.2.1-alpha.3`、`0.2.1-alpha.4`、`0.2.1-alpha.5`、`0.2.1-rc.1`、`0.2.1-rc.2`（共 24 个版本，`0.1.1-rc.1` … `0.2.1-rc.2`）。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.2.1-rc.2` 构建，只使用公开契约（工具注册、客户端 slots + theme、bundle patch，以及 v3.9 起的会话状态记录接口）。插件同时声明 `engines.dsh`（`>=0.1.1-rc.1`），使 dsh ≥ 0.2.1-rc.2 运行时只依据该范围判断兼容性（更早的运行时仍回退校验 `package.json` 中列出的 `@deepseek-ai/dsh-*` peer 版本）。
 - **一次性 Profile 证据（真实，`dsh` CLI `0.1.1-rc.1`）**：在临时 `$DSH_HOME` 下
   `dsh plugin --profile <p> add <本仓库>` 约 449ms 完成安装；`dsh --profile <p>
   --dump-config` 正确合成 `iterate-plugin` bundle patch；`dsh plugin --profile <p>

package/dist/index.js

@@ -2,16 +2,18 @@
  * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
  *
  * Architecture:
- * - The plugin registers 17 tools (14 original + 3 v3.0 quality command center tools)
+ * - The plugin registers 18 tools (14 original + 3 v3.0 quality command center
+ *   tools + 1 v3.9 report export)
  *   Original: config, validate, decision-log, context, review, triage, fix, diff,
  *   rollback, checkpoint, status, history, prune, transcript
  *   v3.0: experience, quality_gate, defense_events
+ *   v3.9: report
  * - The plugin injects a system prompt section teaching the iterate workflow pattern
  * - The model (prompted by the skill) writes a workflow script using dsh's `workflow` tool
  * - The workflow script uses `agent()` / `parallel()` / `phase()` / `log()` to orchestrate
- * - Subagents use the 17 tools to do real work (read config, run validation, log decisions,
+ * - Subagents use the 18 tools to do real work (read config, run validation, log decisions,
  *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune, transcript,
- *   query experience bank, check quality gates, query defense events)
+ *   query experience bank, check quality gates, query defense events, export a report)
  * - A `tools/pre-execute` hook gates destructive iterate calls behind human approval
  *   (F8 observatory approval policy: ask / deny / allow).
  *
@@ -23,7 +25,7 @@
  *
  * Key files:
  * - src/index.ts      — Plugin entry: register tools + inject skill prompt
- * - src/tools/        — 17 tool implementations (14 original + 3 v3.0)
+ * - src/tools/        — 18 tool implementations (14 original + 3 v3.0 + 1 v3.9)
  * - src/config-loader.ts — YAML config loading
  * - src/types.ts     — Shared types
  */
@@ -41,6 +43,7 @@ import { registerTranscriptTool } from "./tools/transcript.js";
 import { registerExperienceBankTool } from "./tools/experience-bank.js";
 import { registerQualityGateTool } from "./tools/quality-gate.js";
 import { registerDefenseEventsTool } from "./tools/defense-events.js";
+import { registerReportTool } from "./tools/report.js";
 import { registerSessionHooks } from "./session-hooks.js";
 import { registerLiveCapture } from "./live.js";
 import { installWorkingDirectoryContext } from "./working-directory.js";
@@ -87,6 +90,8 @@ export function apply(ctx) {
         ['iterate_experience', () => registerExperienceBankTool(ctx)],
         ['iterate_quality_gate', () => registerQualityGateTool(ctx)],
         ['iterate_defense_events', () => registerDefenseEventsTool(ctx)],
+        // v3.9: PR-ready / CI-ready report export
+        ['iterate_report', () => registerReportTool(ctx)],
     ];
     for (const [toolName, register] of toolRegistrations) {
         try {

package/dist/report-render.js

@@ -0,0 +1,452 @@
+/**
+ * src/report-render.ts — pure renderers for the portable iterate run report.
+ *
+ * ONE data model, TWO consumers that must never disagree:
+ *   - the `iterate_report` tool (server side), and
+ *   - the observatory's "导出报告 / 导出 SARIF" buttons (client side),
+ * both call {@link renderRunReportMarkdown} / {@link renderRunReportSarif} on
+ * the same normalized {@link RunReportData}.
+ *
+ * This module is deliberately dependency-free and DOM-free: it is compiled to
+ * `dist/` for the server AND inlined into `lib/client.js` by esbuild. It must
+ * import NOTHING — importing `lib/parse.js` would drag a file outside `src/`
+ * into the server's tsc program and scatter the emit into `dist/src/**`. Every
+ * extraction is tolerant: a hand-edited manifest can only ever produce an empty
+ * section, never a thrown export.
+ *
+ * Formats:
+ *   - **markdown** — a PR-pasteable run report (header, quality gate, findings,
+ *     fixes, validations, defense events, experience bank).
+ *   - **sarif**    — SARIF 2.1.0 for CI / GitHub Code Scanning (ruleId =
+ *     review dimension, severity → error | warning | note, file+line
+ *     locations, suggested fix attached).
+ */
+/** Report formats accepted by the tool and the export buttons. */
+export const REPORT_FORMATS = ['markdown', 'sarif'];
+/** Severity ordering (lowest index = most severe). */
+const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low'];
+/** Human labels for the report, keyed by language. */
+const REPORT_LABELS = {
+    en: {
+        title: 'iterate run report',
+        project: 'Project',
+        goal: 'Goal',
+        mode: 'Mode',
+        status: 'Status',
+        round: 'Round',
+        updated: 'Updated',
+        converged: 'converged',
+        running: 'running',
+        stopped: 'stopped',
+        qualityGate: 'Quality gate',
+        overall: 'Overall',
+        verification: 'Verification',
+        dimension: 'Dimension',
+        qstatus: 'Status',
+        score: 'Score',
+        findingsCount: 'Findings',
+        fixed: 'Fixed',
+        convergence: 'Convergence',
+        findings: 'Findings',
+        severity: 'Severity',
+        location: 'Location',
+        summary: 'Summary',
+        defensiveType: 'Type',
+        none: '_none_',
+        fixes: 'Fixes',
+        file: 'File',
+        delta: 'Δ',
+        result: 'Result',
+        applied: 'applied',
+        failed: 'failed',
+        validations: 'Validations',
+        command: 'Command',
+        exit: 'Exit',
+        allowed: 'Allowed',
+        yes: 'yes',
+        no: 'no',
+        defenseEvents: 'Defense events',
+        experienceBank: 'Experience bank',
+        hits: 'hits',
+        entries: 'entries',
+        generatedAt: 'Generated at',
+        notRecorded: 'not recorded',
+    },
+    zh: {
+        title: 'iterate 运行报告',
+        project: '项目',
+        goal: '目标',
+        mode: '模式',
+        status: '状态',
+        round: '轮次',
+        updated: '更新时间',
+        converged: '已收敛',
+        running: '运行中',
+        stopped: '已结束',
+        qualityGate: '质量门禁',
+        overall: '总体',
+        verification: '验证',
+        dimension: '维度',
+        qstatus: '状态',
+        score: '得分',
+        findingsCount: '发现数',
+        fixed: '已修复',
+        convergence: '收敛率',
+        findings: '发现',
+        severity: '严重度',
+        location: '位置',
+        summary: '摘要',
+        defensiveType: '类型',
+        none: '无',
+        fixes: '修复',
+        file: '文件',
+        delta: '变更',
+        result: '结果',
+        applied: '成功',
+        failed: '失败',
+        validations: '验证',
+        command: '命令',
+        exit: '退出码',
+        allowed: '已授权',
+        yes: '是',
+        no: '否',
+        defenseEvents: '防御事件',
+        experienceBank: '经验银行',
+        hits: '命中',
+        entries: '条目',
+        generatedAt: '生成时间',
+        notRecorded: '未记录',
+    },
+};
+function reportLabels(lang) {
+    return lang === 'en' ? REPORT_LABELS.en : REPORT_LABELS.zh;
+}
+/** Proxy-safe object read (never lets a hostile getter trap throw). */
+function get(source, key) {
+    if (!source || typeof source !== 'object')
+        return undefined;
+    try {
+        return source[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+function asString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Escape a value for a Markdown table cell / inline text. */
+function mdCell(value) {
+    const s = value === null || value === undefined ? '' : String(value);
+    return s.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ').trim();
+}
+/** Severity of a finding, defaulting to the least-severe bucket. */
+function findingSeverity(f) {
+    const s = get(f, 'severity');
+    return typeof s === 'string' && SEVERITY_ORDER.includes(s) ? s : 'low';
+}
+/** Repo-relative POSIX uri for SARIF artifact locations. */
+function sarifUri(file) {
+    const s = typeof file === 'string' ? file.trim() : '';
+    if (!s)
+        return '';
+    return s.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+/** SARIF result level for an iterate severity. */
+export function sarifLevel(severity) {
+    if (severity === 'critical' || severity === 'high')
+        return 'error';
+    if (severity === 'medium')
+        return 'warning';
+    return 'note';
+}
+/**
+ * Normalize a manifest (+ the pulled disk artifacts) into ONE shape. Pure;
+ * tolerates junk at every field.
+ */
+export function buildRunReportData(manifest, extra) {
+    const src = asObject(manifest) ?? {};
+    const ex = asObject(extra);
+    const qg = asObject(get(ex, 'qualityGate'));
+    const bank = asObject(get(ex, 'experienceBank'));
+    const defense = asObject(get(ex, 'defenseEvents'));
+    const findings = asArray(get(src, 'findings')).map((f) => ({
+        dimension: asString(get(f, 'dimension')),
+        file: asString(get(f, 'file')),
+        line: asNumber(get(f, 'line')),
+        severity: findingSeverity(f),
+        summary: asString(get(f, 'summary')),
+        failureScenario: asString(get(f, 'failure_scenario')),
+        suggestedFix: asString(get(f, 'suggested_fix')),
+        isAtomic: get(f, 'is_atomic') === true,
+        acknowledged: get(f, 'acknowledged') === true,
+    }));
+    findings.sort((a, b) => SEVERITY_ORDER.indexOf(a.severity) -
+        SEVERITY_ORDER.indexOf(b.severity));
+    const fixes = asArray(get(src, 'fixes')).map((f) => ({
+        round: asNumber(get(f, 'round')),
+        file: asString(get(f, 'file')),
+        summary: asString(get(f, 'summary')),
+        linesAdded: asNumber(get(f, 'linesAdded')),
+        linesRemoved: asNumber(get(f, 'linesRemoved')),
+        success: get(f, 'success') !== false,
+    }));
+    const validations = asArray(get(src, 'validations')).map((v) => ({
+        round: asNumber(get(v, 'round')),
+        command: asString(get(v, 'command')),
+        exitCode: typeof get(v, 'exitCode') === 'number' ? asNumber(get(v, 'exitCode')) : null,
+        allowed: get(v, 'allowed') === true,
+        rejectReason: asString(get(v, 'rejectReason')),
+    }));
+    const severityCounts = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const f of findings) {
+        const key = f.severity;
+        if (key in severityCounts)
+            severityCounts[key] += 1;
+    }
+    const mode = get(src, 'mode');
+    const taskMode = get(src, 'taskMode');
+    const stoppedReason = get(src, 'stoppedReason');
+    return {
+        project: asString(get(src, 'project')),
+        goal: asString(get(src, 'goal')),
+        mode: mode === 'normal' || mode === 'dry-run' ? mode : null,
+        taskMode: taskMode === 'code' || taskMode === 'iterate' ? taskMode : null,
+        round: asNumber(get(src, 'round')),
+        maxRounds: asNumber(get(src, 'maxRounds')),
+        active: get(src, 'active') !== false,
+        stoppedReason: typeof stoppedReason === 'string' && stoppedReason ? stoppedReason : null,
+        updatedAt: asString(get(src, 'updatedAt')),
+        convergence: asArray(get(src, 'convergence')).filter((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0),
+        findings,
+        severityCounts,
+        fixes,
+        validations,
+        qualityGate: qg,
+        experienceBank: bank,
+        defenseEvents: defense,
+    };
+}
+/** One-line human status for the report header. */
+function reportStatus(data, labels) {
+    if (data.active === true)
+        return labels.running;
+    if (data.stoppedReason)
+        return `${labels.stopped} · ${data.stoppedReason}`;
+    return labels.stopped;
+}
+/** Render a PR-pasteable Markdown run report. */
+export function renderRunReportMarkdown(manifest, extra, opts) {
+    const data = buildRunReportData(manifest, extra);
+    const o = opts ?? {};
+    const labels = reportLabels(o.lang === 'en' ? 'en' : 'zh');
+    const when = o.now && o.now ? o.now : new Date().toISOString();
+    const lines = [];
+    lines.push(`# ${labels.title}`);
+    lines.push('');
+    lines.push(`- **${labels.project}**: \`${mdCell(data.project || labels.notRecorded)}\``);
+    if (data.goal)
+        lines.push(`- **${labels.goal}**: ${mdCell(data.goal)}`);
+    lines.push(`- **${labels.mode}**: ${mdCell(data.mode || labels.notRecorded)}${data.taskMode ? ` · task_mode: ${data.taskMode}` : ''}`);
+    const roundText = data.maxRounds > 0 ? `${data.round}/${data.maxRounds}` : String(data.round);
+    lines.push(`- **${labels.round}**: ${mdCell(roundText)} · **${labels.status}**: ${mdCell(reportStatus(data, labels))}`);
+    lines.push(`- **${labels.updated}**: ${mdCell(data.updatedAt || when)}`);
+    lines.push(`- **${labels.generatedAt}**: ${mdCell(when)}`);
+    lines.push('');
+    // ── Quality gate ──
+    const qg = data.qualityGate;
+    if (qg) {
+        lines.push(`## ${labels.qualityGate}`);
+        lines.push('');
+        const status = typeof qg.overallStatus === 'string' ? qg.overallStatus.toUpperCase() : 'PENDING';
+        lines.push(`- **${labels.overall}**: ${mdCell(status)} (${labels.score} ${asNumber(qg.overallScore)})`);
+        lines.push(`- **${labels.verification}**: ${asNumber(qg.passedChecks)}/${asNumber(qg.totalChecks)} (${asNumber(qg.verificationPassRate)}%)`);
+        if (typeof qg.failReason === 'string' && qg.failReason) {
+            lines.push(`- ${labels.status}: ${mdCell(qg.failReason)}`);
+        }
+        lines.push('');
+        const dims = asArray(qg.dimensions);
+        if (dims.length > 0) {
+            lines.push(`| ${labels.dimension} | ${labels.qstatus} | ${labels.score} | ${labels.findingsCount} | ${labels.fixed} | ${labels.convergence} |`);
+            lines.push('| --- | --- | --- | --- | --- | --- |');
+            for (const d of dims) {
+                lines.push(`| ${mdCell(get(d, 'dimension'))} | ${mdCell(get(d, 'status'))} | ${mdCell(get(d, 'score'))} | ${mdCell(get(d, 'findingsCount'))} | ${mdCell(get(d, 'fixedCount'))} | ${mdCell(get(d, 'convergenceRate'))}% |`);
+            }
+            lines.push('');
+        }
+    }
+    // ── Findings ──
+    lines.push(`## ${labels.findings} (${data.findings.length})`);
+    lines.push('');
+    if (data.findings.length === 0) {
+        lines.push(labels.none);
+    }
+    else {
+        lines.push(`| ${labels.severity} | ${labels.dimension} | ${labels.location} | ${labels.summary} |`);
+        lines.push('| --- | --- | --- | --- |');
+        for (const f of data.findings) {
+            const loc = f.file ? `${f.file}${f.line > 1 ? `:${f.line}` : ''}` : '';
+            lines.push(`| ${mdCell(f.severity)} | ${mdCell(f.dimension)} | ${mdCell(loc)} | ${mdCell(f.summary)} |`);
+        }
+    }
+    lines.push('');
+    // ── Fixes ──
+    lines.push(`## ${labels.fixes} (${data.fixes.length})`);
+    lines.push('');
+    if (data.fixes.length === 0) {
+        lines.push(labels.none);
+    }
+    else {
+        lines.push(`| # | ${labels.file} | ${labels.delta} | ${labels.result} | ${labels.summary} |`);
+        lines.push('| --- | --- | --- | --- | --- |');
+        for (const f of data.fixes) {
+            lines.push(`| ${mdCell(f.round)} | ${mdCell(f.file)} | ${mdCell(`+${f.linesAdded}/-${f.linesRemoved}`)} | ${f.success ? labels.applied : labels.failed} | ${mdCell(f.summary)} |`);
+        }
+    }
+    lines.push('');
+    // ── Validations ──
+    if (data.validations.length > 0) {
+        lines.push(`## ${labels.validations}`);
+        lines.push('');
+        lines.push(`| # | ${labels.command} | ${labels.exit} | ${labels.allowed} |`);
+        lines.push('| --- | --- | --- | --- |');
+        for (const v of data.validations) {
+            lines.push(`| ${mdCell(v.round)} | \`${mdCell(v.command)}\` | ${v.exitCode === null ? '—' : mdCell(v.exitCode)} | ${v.allowed ? labels.yes : labels.no} |`);
+        }
+        lines.push('');
+    }
+    // ── Defense events ──
+    const deEvents = asArray(get(data.defenseEvents, 'events'));
+    if (deEvents.length > 0) {
+        lines.push(`## ${labels.defenseEvents} (${deEvents.length})`);
+        lines.push('');
+        lines.push(`| ${labels.severity} | ${labels.defensiveType} | ${labels.round} | ${labels.summary} |`);
+        lines.push('| --- | --- | --- | --- |');
+        for (const e of deEvents) {
+            lines.push(`| ${mdCell(get(e, 'severity'))} | ${mdCell(get(e, 'type'))} | ${mdCell(get(e, 'round'))} | ${mdCell(get(e, 'description') || get(e, 'outcome'))} |`);
+        }
+        lines.push('');
+    }
+    // ── Experience bank ──
+    const entries = asArray(get(data.experienceBank, 'entries'));
+    if (entries.length > 0) {
+        const totalHits = asNumber(get(data.experienceBank, 'totalHits'));
+        lines.push(`## ${labels.experienceBank} (${entries.length} ${labels.entries}, ${totalHits} ${labels.hits})`);
+        lines.push('');
+        for (const e of entries) {
+            lines.push(`- **[${mdCell(get(e, 'id'))}]** ${mdCell(get(e, 'pattern'))} — ${mdCell(get(e, 'description'))} (${labels.hits}: ${mdCell(get(e, 'hitCount'))})`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+/** Render a SARIF 2.1.0 document from the same normalized data. */
+export function renderRunReportSarif(manifest, extra, opts) {
+    const data = buildRunReportData(manifest, extra);
+    const o = opts ?? {};
+    const rules = [];
+    const seenRules = new Set();
+    for (const f of data.findings) {
+        const id = f.dimension || 'review';
+        if (seenRules.has(id))
+            continue;
+        seenRules.add(id);
+        rules.push({
+            id,
+            name: id,
+            shortDescription: { text: `${id} review dimension` },
+            defaultConfiguration: { level: 'warning' },
+        });
+    }
+    const results = data.findings.map((f) => {
+        const result = {
+            ruleId: f.dimension || 'review',
+            level: sarifLevel(f.severity),
+            message: { text: f.summary || `${f.severity} finding` },
+            properties: {
+                severity: f.severity,
+                atomic: f.isAtomic,
+                acknowledged: f.acknowledged,
+            },
+        };
+        const uri = sarifUri(f.file);
+        if (uri) {
+            result.locations = [
+                {
+                    physicalLocation: {
+                        artifactLocation: { uri },
+                        ...(f.line > 0 ? { region: { startLine: f.line } } : {}),
+                    },
+                },
+            ];
+        }
+        if (f.suggestedFix)
+            result.fixes = [{ description: { text: f.suggestedFix } }];
+        return result;
+    });
+    const failedValidations = data.validations.filter((v) => v.exitCode !== 0).length;
+    return {
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'iterate-plugin',
+                        informationUri: o.informationUri && o.informationUri
+                            ? o.informationUri
+                            : 'https://github.com/jingzhao-l/iterate-plugin',
+                        ...(o.toolVersion ? { version: o.toolVersion } : {}),
+                        rules,
+                    },
+                },
+                invocations: [
+                    {
+                        executionSuccessful: failedValidations === 0 && data.qualityGate?.overallStatus !== 'fail',
+                        ...(data.updatedAt ? { startTimeUtc: data.updatedAt } : {}),
+                        properties: {
+                            mode: data.mode,
+                            taskMode: data.taskMode,
+                            round: data.round,
+                            maxRounds: data.maxRounds,
+                            stoppedReason: data.stoppedReason,
+                            qualityStatus: data.qualityGate ? (data.qualityGate.overallStatus ?? null) : null,
+                            convergence: data.convergence,
+                            findingsBySeverity: data.severityCounts,
+                        },
+                    },
+                ],
+                results,
+            },
+        ],
+    };
+}
+/**
+ * Render a report in the requested format. Unknown formats fall back to
+ * Markdown (the tool's default).
+ */
+export function renderRunReport(format, manifest, extra, opts) {
+    if (format === 'sarif')
+        return renderRunReportSarif(manifest, extra, opts);
+    return renderRunReportMarkdown(manifest, extra, opts);
+}
+/**
+ * Deterministic download filename for a report, e.g.
+ * `iterate-report-2026-10-18T01-02-03-000Z.md`.
+ */
+export function runReportFilename(format, opts) {
+    const ext = format === 'sarif' ? 'sarif' : 'md';
+    const stamp = opts?.now && opts.now ? opts.now.replace(/[:.]/g, '-') : new Date().toISOString().replace(/[:.]/g, '-');
+    return `iterate-report-${stamp}.${ext}`;
+}