iterate-plugin 3.7.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
 
 ---
 
@@ -342,11 +343,17 @@ All runtime state lives under `.iterate/` at the project root (can be excluded v
   `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` (19 releases, `0.1.1-rc.1` …
-  `0.2.1-alpha.2`).
+  `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 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.2` and uses only public contracts
-  (tool registration, client slots + theme, bundle patch).
+  `@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
   `$DSH_HOME`, `dsh plugin --profile <p> add <this-repo>` installed the bundle in
   ~449 ms; `dsh --profile <p> --dump-config` composed the `iterate-plugin` bundle
@@ -384,8 +391,36 @@ following capabilities; elevated capability means a DSH Profile install stays
 
 ### Dependencies
 
-Runtime dependencies: `@deepseek-ai/cordis`, `@deepseek-ai/dsh-tools`,
-`@deepseek-ai/dsh-util-values`, `js-yaml` — all pinned exact versions.
+Runtime dependency: `js-yaml` (pinned exact version). The three DSH host
+modules the plugin is built against — `@deepseek-ai/cordis`,
+`@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-util-values` — are declared as
+**optional `peerDependencies`** so the host's own copies are used instead of a
+second one bundled with the plugin (no duplicate module instances; `dsh`
+supplies them). They stay pinned in `devDependencies` for local builds and
+tests, in lockstep with the newest `dsh.compatibility.dshReleases` entry.
+
+#### Upstream adoption (v3.8.0 → dsh `0.2.1-alpha.4`)
+
+- **Adopted — the `engines.dsh` compatibility contract.** As of `0.2.1-alpha.4`
+  the dsh runtime decides a third-party plugin's compatibility **from
+  `engines.dsh` when it is declared** (a semver range, prereleases included),
+  ignoring `peerDependencies`; when it is absent the runtime falls back to
+  checking the exact `@deepseek-ai/dsh-*` peer versions. The plugin now declares
+  `engines.dsh: ">=0.1.1-rc.1"` — the same lower bound as the oldest
+  `dshReleases` entry — so a current runtime loads it without flagging the
+  exact-pinned peer list, while every host-specific capability stays
+  feature-detected (a missing `WorkingDirectoryService`, `ask.displayReason`,
+  `ctx.jobs`, etc. still degrade to the safe fallback). Earlier runtimes keep
+  using the `@deepseek-ai/dsh-*` peer versions, which are extended through
+  `0.2.1-alpha.4`.
+- **`0.2.1-alpha.3` / `0.2.1-alpha.4` are otherwise host-level releases** — Web
+  sign-in, secret/token masking, minimal-mode image reading, `/compact`, plugin
+  hot-reload, custom plugin index sources, and per-model reasoning-level UI. None
+  expose a tool/agent/session API this plugin consumes (`defineTool`, `JsonValue`,
+  `exec.*`, `tools/pre-execute`, `presentCall`), so no further adoption is
+  required this cycle.
+- All five `@deepseek-ai/*` packages are pinned to the exact `0.2.1-alpha.4`
+  (`@deepseek-ai/cordis` stays `4.0.5-alpha.2`).
 
 #### Upstream adoption (v3.7.0 → dsh `0.2.1-alpha.2`)
 

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`（共 19 个版本，`0.1.1-rc.1` … `0.2.1-alpha.2`）。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.2.1-alpha.2` 构建，只使用公开契约（工具注册、客户端 slots + theme、bundle patch）。
+- **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>
@@ -364,8 +365,28 @@ validation:
 
 ### 依赖
 
-运行时依赖：`@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`、
-`@deepseek-ai/dsh-util-values`、`js-yaml`——全部精确锁版。
+运行时依赖：`js-yaml`（精确锁版）。本插件构建所依赖的三个 DSH 宿主模块——
+`@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-util-values`
+——已声明为**可选 `peerDependencies`**，直接复用宿主自带的那一份，避免插件内
+再打包一份造成双模块实例（由 `dsh` 提供）；同时在 `devDependencies` 中精确锁版，
+供本地构建与测试，并与 `dsh.compatibility.dshReleases` 的最新条目保持一致。
+
+#### 上游采纳记录（v3.8.0 → dsh `0.2.1-alpha.4`）
+
+- **已采纳——`engines.dsh` 兼容契约。** 自 `0.2.1-alpha.4` 起，dsh 运行时**在声明了
+  `engines.dsh` 时只依据该字段**（一个含预发布版本的 semver 范围）判断第三方插件兼容性，
+  忽略 `peerDependencies`；未声明时才回退逐个校验精确的 `@deepseek-ai/dsh-*` peer 版本。
+  插件现已声明 `engines.dsh: ">=0.1.1-rc.1"`（与最早的 `dshReleases` 条目同下界），
+  使当前运行时加载时不再因精确锁版的 peer 列表被判不兼容；而所有宿主相关能力依旧
+  特性探测（缺少 `WorkingDirectoryService`、`ask.displayReason`、`ctx.jobs` 等一律
+  降级到安全回退）。更早的运行时仍走 `@deepseek-ai/dsh-*` peer 版本，已扩展至
+  `0.2.1-alpha.4`。
+- **`0.2.1-alpha.3` / `0.2.1-alpha.4` 其余均为宿主级变更**——Web 登录、密钥/令牌脱敏、
+  极简模式读图、`/compact`、插件热重载、自定义插件索引源、按模型配置推理等级 UI。
+  都未暴露本插件消费的 tool/agent/session API（`defineTool`、`JsonValue`、`exec.*`、
+  `tools/pre-execute`、`presentCall`），本轮无需进一步采纳。
+- 五个 `@deepseek-ai/*` 包全部精确锁到 `0.2.1-alpha.4`
+  （`@deepseek-ai/cordis` 保持 `4.0.5-alpha.2`）。
 
 #### 上游采纳记录（v3.7.0 → dsh `0.2.1-alpha.2`）
 

package/dist/file-lock.js

@@ -26,10 +26,17 @@
  * `withProjectLock` is therefore NOT reentrant and must not be nested for the
  * same (projectRoot, name).
  */
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync, } from 'node:fs';
+import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync, } from 'node:fs';
 import { join } from 'node:path';
 const LOCK_DIR = '.iterate';
-const DEFAULT_WAIT_MS = 5000;
+// Bounded wait before degrading to "proceed unlocked". `acquireProjectLock`
+// spins on `Atomics.wait`, which BLOCKS the single plugin thread for the whole
+// budget — so a long default wedges unrelated tool calls and the UI heartbeat
+// whenever a sibling process holds the lock. Healthy holders release in
+// microseconds, so 1000ms is very generous; anything slower is treated as
+// contention and degrades to the historical unlocked behavior rather than
+// stalling the event loop for five seconds.
+const DEFAULT_WAIT_MS = 1000;
 const DEFAULT_STALE_MS = 10000;
 const POLL_MS = 25;
 /** True when a pid refers to a live process (or we lack permission to tell). */
@@ -60,14 +67,17 @@ function lockFileName(name) {
     return `.${name}.lock`;
 }
 /**
- * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`.
+ * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`,
+ * reporting whether it was actually taken.
  *
- * Returns a release function: always callable, idempotent, never throws.
- * A no-op (but callable) release is returned when the lock directory cannot be
- * created or the wait times out — callers then proceed unlocked, which is the
- * historical best-effort behavior, rather than failing the operation.
+ * The returned release function is always callable, idempotent, and never
+ * throws. `acquired:false` (with a no-op release) is returned when the lock
+ * directory cannot be created or the wait times out — callers then proceed
+ * unlocked, which is the historical best-effort behavior, rather than failing
+ * the operation. Callers that MUST hold the mutex (e.g. a log rewrite that
+ * renames the file) branch on `acquired` and refuse to run unlocked.
  */
-export function acquireProjectLock(projectRoot, name, options = {}) {
+export function acquireProjectLockChecked(projectRoot, name, options = {}) {
     const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
         ? options.waitMs
         : DEFAULT_WAIT_MS;
@@ -80,7 +90,7 @@ export function acquireProjectLock(projectRoot, name, options = {}) {
             mkdirSync(dir, { recursive: true });
         }
         catch {
-            return () => { };
+            return { acquired: false, release: () => { } };
         }
     }
     const lockPath = join(dir, lockFileName(name));
@@ -92,7 +102,7 @@ export function acquireProjectLock(projectRoot, name, options = {}) {
         }
         catch (err) {
             if (err.code !== 'EEXIST')
-                return () => { };
+                return { acquired: false, release: () => { } };
             // Lock exists — steal it when the owner is gone or the lock is ancient.
             let stale = false;
             try {
@@ -118,11 +128,21 @@ export function acquireProjectLock(projectRoot, name, options = {}) {
                 continue;
             }
             if (Date.now() - start > waitMs)
-                return () => { };
+                return { acquired: false, release: () => { } };
             sleepSync(POLL_MS);
             continue;
         }
-        // Owned the lock: stamp the holder pid, then release once on return.
+        // Owned the lock: capture the created inode (for the ownership-checked
+        // release), stamp the holder pid, then release once on return.
+        let ino = 0;
+        try {
+            ino = fstatSync(fd).ino;
+        }
+        catch {
+            // inode unavailable on this filesystem — the release falls back to the
+            // pid-stamp check only.
+            ino = 0;
+        }
         try {
             writeSync(fd, String(process.pid));
         }
@@ -135,9 +155,20 @@ export function acquireProjectLock(projectRoot, name, options = {}) {
         catch {
             // best-effort
         }
-        return makeLockRelease(lockPath);
+        return { acquired: true, release: makeLockRelease(lockPath, ino) };
     }
 }
+/**
+ * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`.
+ *
+ * Returns a release function: always callable, idempotent, never throws.
+ * A no-op (but callable) release is returned when the lock directory cannot be
+ * created or the wait times out — callers then proceed unlocked, which is the
+ * historical best-effort behavior, rather than failing the operation.
+ */
+export function acquireProjectLock(projectRoot, name, options = {}) {
+    return acquireProjectLockChecked(projectRoot, name, options).release;
+}
 /**
  * Build the release function for a lock file this process just acquired.
  *
@@ -151,7 +182,25 @@ export function acquireProjectLock(projectRoot, name, options = {}) {
  *
  * Always callable, idempotent, and never throws.
  */
-export function makeLockRelease(lockPath) {
+/**
+ * Build the release function for a lock file this process just acquired.
+ *
+ * Advisory locks here are STOLEN when the recorded owner dies or the mtime
+ * goes ancient: the steal unlinks our file and creates a new one stamped with
+ * the STEALER's pid. An unguarded release would then unlink the new holder's
+ * lock — turning our release into a double-release that admits a third process
+ * into a "held" critical section. So the release re-reads the stamp and only
+ * unlinks a file that is still ours: same pid (or unstamped) AND, when we know
+ * the inode we created, the SAME inode still at the path. The inode check closes
+ * the read-then-unlink window where the stamp check alone could race a steal
+ * (our pid is alive, but the file was already replaced between the two calls).
+ *
+ * Always callable, idempotent, and never throws.
+ *
+ * @param lockPath - the lock file path.
+ * @param ino - the inode captured at acquisition (0 = unknown; skip the check).
+ */
+export function makeLockRelease(lockPath, ino) {
     let released = false;
     return () => {
         if (released)
@@ -169,6 +218,18 @@ export function makeLockRelease(lockPath) {
         // it is no longer ours to delete.
         if (raw !== '' && Number(raw) !== process.pid)
             return;
+        // The path must still refer to the file WE created. A stealer unlinked our
+        // file and created a fresh one; that replacement carries a different inode,
+        // so unlinking by path would delete the NEW holder's lock.
+        if (typeof ino === 'number' && ino !== 0) {
+            try {
+                if (statSync(lockPath).ino !== ino)
+                    return;
+            }
+            catch {
+                return; // vanished mid-release — nothing of ours left
+            }
+        }
         try {
             unlinkSync(lockPath);
         }

package/dist/git-scope.js

@@ -21,7 +21,7 @@
  * git repo.
  */
 import { execFile } from 'node:child_process';
-import { existsSync, statSync } from 'node:fs';
+import { lstatSync, realpathSync } from 'node:fs';
 import { join, sep } from 'node:path';
 /**
  * Parse `git diff --name-only -z` stdout into a list of relative paths.
@@ -112,6 +112,15 @@ export function parseChangedFiles(stdout) {
  * Keep only entries that resolve to an existing regular file under `root`.
  * Traversal-safe: rejects absolute paths and any relative path that would
  * escape `root` via `..` (resolved against the root before stat).
+ *
+ * Symlink handling: `statSync` (and `existsSync`) FOLLOW symlinks, so a git
+ * entry that is a link to a file OUTSIDE the project would pass a path-only
+ * containment check and enter the changed-only scope. Such a file is then
+ * rejected by the evidence gate (realpath out of bounds → `file_not_found`),
+ * so every finding on it would fail closed as `EVIDENCE_VIOLATION` forever —
+ * a permanent false positive for repos with dotfile or shared-config links.
+ * `lstatSync` distinguishes the link itself; a link whose REAL target escapes
+ * `root` is dropped here instead.
  */
 export function filterExistingFiles(root, files) {
     const out = [];
@@ -123,7 +132,18 @@ export function filterExistingFiles(root, files) {
         if (!candidate.startsWith(rootPrefix) && candidate !== root)
             continue;
         try {
-            if (existsSync(candidate) && statSync(candidate).isFile())
+            const st = lstatSync(candidate);
+            if (st.isFile()) {
+                out.push(rel);
+                continue;
+            }
+            if (!st.isSymbolicLink())
+                continue;
+            // A link whose real target stays inside the project is a legitimate,
+            // reviewable file; one that escapes is excluded from scope (fail-closed
+            // at the source instead of as a permanent evidence violation).
+            const real = realpathSync(candidate);
+            if (real === root || real.startsWith(rootPrefix))
                 out.push(rel);
         }
         catch {

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 {