iterate-plugin 3.6.0 → 3.8.0

package/README.md

@@ -104,7 +104,7 @@ Both modes share:
 - Validates after each round's fixes
 - Rolls back failed fixes, and can save / resume progress
 
-### UI layer (build-free client slots, v3.6: 11 tabs)
+### 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.
@@ -112,7 +112,8 @@ Both modes share:
 - **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.
 - **ProgressCapsule** (`shell.overlay`) — popup notification on each round completion / convergence (incl. convergence confirm).
-- **SettingsPanel** (`settings.section`) — theme toggle, triage-persistence notes, config-management guide (covers `validation.commands` / `language` / `personalization.known_intentional` with an explicit "empty validation.commands = unprotected" warning; a field picker generates the matching `iterate_config write` instruction), runtime status overview (artifact layout + view/cleanup tool guide + disk-snapshot pull), one-click triage data reset.
+- **SettingsPanel** (`settings.section`) — theme toggle, triage-persistence notes, config-management guide (covers `validation.commands` / `language` / `personalization.known_intentional` with an explicit "empty validation.commands = unprotected" warning; a field picker generates the matching `iterate_config write` instruction), **v3.7: a 回读当前配置 (read back current config) button that closes the write → read-back loop** — it copies an `iterate_config read` instruction and, once the model echoes the result into the session, shows the current value of the selected field, runtime status overview (artifact layout + view/cleanup tool guide + disk-snapshot pull), one-click triage data reset.
+- **Bilingual UI (v3.7)** — every piece of UI chrome (panels, empty states, tabs, badges, settings, stop-reason and completion labels) ships in 简体中文 and English. Pick the language under **Settings → 界面语言 / Interface language**; the choice persists in `localStorage` (`iterate-ui-lang`) and otherwise auto-detects from `navigator.language` (a stored choice always wins, and auto-detection never writes a preference). **Model-facing copy deliberately stays Chinese** — the `build*Instruction` payloads and the copy-paste guides are contract text mirroring `SKILL.md`, so the two expanded guides carry a 「中文（粘贴给模型的契约文案）」 chip instead of looking like a missed translation.
 
 The UI layer is **defensive by design**: it degrades gracefully if any of `slots` / `theme` / `React` is unavailable — it never crashes the client.
 
@@ -125,7 +126,8 @@ Beyond the 17 registered tools (full reference further down), the plugin closes
 - **Breakpoint resume** — checkpoints saved at the start of each round; interrupted long iterations can resume
 - **History audit** — `iterate_history` reads the decision log (filtered by `type` / `since` / `round` / fixed `file` / `limit`, default latest 50, cap 200) plus a fix-registry summary (per-round fixed/failed counts, scoped by the same round/file filters) to audit run process and fix details
 - **Runtime cleanup** — `iterate_prune` removes stale decision-log entries, stale checkpoints, orphaned fix backups, empty rounds and stray temp files left by crashed atomic writes; dry-run by default (report-only), real cleanup requires `dryRun:false`, and every cleanup is logged
-- **Config read / write** — `iterate_config` supports validated, backed-up, rollback-capable partial writes
+- **Config read / write** — `iterate_config` supports validated, backed-up, rollback-capable partial writes; since v3.7 the settings page can also **read the effective config back** (instruction + inline current value)
+- **Session-aware project root (v3.7)** — on dsh ≥ `0.2.1-alpha.2` the plugin follows the session's *mutable* working directory through the host's `WorkingDirectoryService` instead of the immutable `Session.header.cwd`, so a mid-session directory switch redirects everything under `.iterate/` (config, decision log, checkpoints, fix backups, approval policy) to the workspace actually in use. The service is feature-detected with a `header.cwd` fallback on every failure mode, so older hosts behave exactly as before.
 - **v3.2 Experience Bank** — `iterate_experience` queries historical fixes and patterns with search / filter / adopt, and can persist new verified fixes (`add`) — re-adding the same pattern+dimension bumps its hit count instead of duplicating it
 - **v3.2 Quality Gate** — `iterate_quality_gate` reads quality gate status with per-dimension convergence rates and PASS/FAIL, and can recompute + persist a fresh certificate (`compute`) from this round's findings / validation results (real convergence from `findingsByRound`)
 - **v3.2 Defense Events** — `iterate_defense_events` queries defense events (precondition failures, rollbacks, invariant violations, assumption falsifications) and can `record` new ones; readable labels follow the project language (en / zh)
@@ -209,6 +211,8 @@ Press `1`–`9` to jump to F1–F9, `0` for F10, and `-` to return to the live s
 
 The settings section copies a config-edit guide that lists the supported `iterate.config.yaml` fields — including `validation.commands` (with an explicit warning that an empty list means every round runs unprotected) — and offers a **field picker**: choose a field, and the button generates the matching `iterate_config write` instruction (schema-validated, auto-backup, auto-rollback) for you to paste back.
 
+**Reading back what actually landed** — the matching **回读当前配置 / Read back current config** button copies an `iterate_config` `{ operation: "read" }` instruction; when the model echoes the result into the session, the card shows the current value of the selected field right under the picker (arrays inline, e.g. `["npm test","npm run lint"]`). Three states are told apart honestly: *nothing read back yet*, *the value*, and *read back but this field is absent* (the built-in defaults are in play). If the clipboard refuses, the read instruction is revealed in the panel for manual copy — the button is never a dead end.
+
 ---
 
 ## 💬 Usage
@@ -338,10 +342,15 @@ 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` (18 releases, `0.1.1-rc.1` … `0.2.1-alpha.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`).
   The plugin is built against `@deepseek-ai/dsh-tools` /
-  `@deepseek-ai/dsh-util-values` `0.2.1-alpha.1` and uses only public contracts
+  `@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
+  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
@@ -379,8 +388,62 @@ 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. No
+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`)
+
+- **Adopted — the mutable session working directory.** `src/working-directory.ts`
+  resolves the project root through `ctx.get('workingDirectory').get(session)`
+  when the host offers it (feature-detected; `header.cwd` fallback on a missing
+  service, a throwing service, hostile getters or a non-string result). Needed
+  because as of `0.2.1-alpha.2` the immutable header keeps the *original*
+  project by design, so reading it after a directory switch would anchor the
+  review to the wrong checkout.
+- **Evaluated, not adopted:**
+  - *Session state-record APIs* (experimental plugins writing/reading their own
+    session records) — reaching into shell-owned record internals is fragile
+    across alpha releases, and iterate's cross-session state already lives in
+    `.iterate/`.
+  - *Shared `AGENTS.md` agents directory (`DSH_AGENTS_HOME`)* — a host-level
+    instruction concern; the plugin injects its own workflow prompt.
+  - *Experimental Git Worktrees plugin* — an upstream agent-workflow feature;
+    the plugin's own `git.use_worktree` config predates it and is unrelated
+    (per-round git hygiene for the iterate loop).
+  - *Removal of the `both` tool-presentation mode* — the plugin never set a
+    presentation mode (it renders `presentCall` cards), so nothing to migrate.
+  - *Installing the dsh CLI globally from the plugin* — disk cost for a plugin
+    that never shells out at runtime.
+- All five `@deepseek-ai/*` packages are pinned to the exact `0.2.1-alpha.2`
+  (`@deepseek-ai/cordis` stays `4.0.5-alpha.1`). No
 install-time lifecycle scripts (`preinstall`/`install`/`postinstall`/`prepare`);
 only `prepublishOnly` (build) runs on publish.
 

package/README.zh-CN.md

@@ -103,7 +103,7 @@ dsh plugin --profile web add iterate-plugin
 - 每轮修复后验证
 - 修复失败自动回滚
 
-### UI 层（客户端免构建槽位，v3.6：11 个页签）
+### 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` 指令。
@@ -111,7 +111,8 @@ dsh plugin --profile web add iterate-plugin
 - **收敛统计卡片 `StatsCard`**（`conversation.chat.turnTail`）— 无 findings 时显示收敛统计、历史轮次、趋势图、完成摘要。
 - **iterate 主题皮肤**（`theme.overrideTokens`）— 暖琥珀配色的 13 个 `--dsw-*` token 覆盖，明暗双模式，可在设置页开关。
 - **进度胶囊 `ProgressCapsule`**（`shell.overlay`）— 每轮完成 / 收敛时右下角弹出通知（含收敛确认）。
-- **iterate 设置区 `SettingsPanel`**（`settings.section`）— 主题开关、分诊持久化说明、配置管理指引（覆盖 `validation.commands` / `language` / `personalization.known_intentional`，并显式警告"validation.commands 为空 = 本轮不受任何测试保护"；字段选择器可生成对应的 `iterate_config write` 指令）、运行时状态概览（产物布局 + 查看/清理工具指引 + 磁盘快照拉取）、一键清空分诊数据。
+- **iterate 设置区 `SettingsPanel`**（`settings.section`）— 主题开关、分诊持久化说明、配置管理指引（覆盖 `validation.commands` / `language` / `personalization.known_intentional`，并显式警告"validation.commands 为空 = 本轮不受任何测试保护"；字段选择器可生成对应的 `iterate_config write` 指令），**v3.7：新增「回读当前配置」补齐写入 → 回读闭环**——复制 `iterate_config read` 指令，模型把结果回显进会话后，卡片就地展示所选字段的当前值；运行时状态概览（产物布局 + 查看/清理工具指引 + 磁盘快照拉取）、一键清空分诊数据。
+- **双语 UI（v3.7）**——所有界面文案（面板、空态、页签、徽标、设置、停止原因与完成汇总）均提供简体中文与 English。在**设置 → 界面语言 / Interface language**切换；选择持久化在 `localStorage`（`iterate-ui-lang`），否则按 `navigator.language` 自动探测（已保存的选择始终优先，且自动探测不会写入偏好）。**面向模型的文案有意保持中文**——`build*Instruction` 指令与可粘贴指引是与 `SKILL.md` 对齐的契约文本，因此两处展开的指引带「中文（粘贴给模型的契约文案）」标签，避免被误当成漏翻。
 
 UI 层为**防御式设计**：`slots` / `theme` / `React` 任一不可用时自动降级，不会崩溃客户端。
 
@@ -124,7 +125,8 @@ UI 层为**防御式设计**：`slots` / `theme` / `React` 任一不可用时自
 - **断点续跑** — 长迭代在每轮开头保存 checkpoint，中断后可恢复进度
 - **历史审计** — `iterate_history` 读取决策日志（可按 `type` / `since` / `round` / 修复文件 `file` / `limit` 过滤，默认取最新 50 条，上限 200 条）与修复注册表汇总（各轮 fixed/failed 计数，按同一 round/file 过滤收窄），审查运行过程与修复明细
 - **运行时清理** — `iterate_prune` 清理过期的决策日志条目、陈旧断点、孤儿修复备份、空轮次与原子写入崩溃残留的临时文件；默认 dry-run 只报告不删除，显式 `dryRun:false` 才真正清理，每次清理写入决策日志
-- **配置读写** — `iterate_config` 支持带校验、备份、回滚的局部写入
+- **配置读写** — `iterate_config` 支持带校验、备份、回滚的局部写入；v3.7 起设置页还能**回读生效配置**（指令 + 就地展示当前值）
+- **跟随会话的工作目录（v3.7）** — 在 dsh ≥ `0.2.1-alpha.2` 上，插件通过宿主的 `WorkingDirectoryService` 解析项目根，而不是不可变的 `Session.header.cwd`：会话中途切换目录后，`.iterate/` 下的一切（配置、决策日志、断点、修复备份、审批策略）都会跟着当前工作区走。该服务按特性探测，任何失败路径（服务缺失/抛错/敌意 getter/非字符串结果）都回退到 `header.cwd`，旧宿主行为完全不变。
 - **v3.2 经验银行** — `iterate_experience` 以检索 / 过滤 / 采纳查阅历史修复与模式，并可 `add` 持久化新的已验证修复——重复添加同一 pattern + dimension 时累加命中次数而非重复写入
 - **v3.2 质量门禁** — `iterate_quality_gate` 读取质量门禁状态（各维度收敛率 + PASS/FAIL），并可基于本轮 findings / 验证结果 `compute` 重新计算并持久化一份新的质量凭证（收敛率来自 `findingsByRound` 的真实收敛序列）
 - **v3.2 防御事件流** — `iterate_defense_events` 查询防御事件（前置条件失败、回滚、不变量违反、假设证伪），并可 `record` 记录新事件；可读标签跟随项目语言（en / zh）
@@ -208,6 +210,8 @@ pnpm add /path/to/iterate-skill/harness/iterate-plugin
 
 设置区复制一份配置编辑指引，列出支持的 `iterate.config.yaml` 字段——包括 `validation.commands`（并显式警告：留空意味着每一轮迭代都不受任何测试保护）——并提供**字段选择器**：选中字段后，按钮会生成对应的 `iterate_config write` 指令（schema 校验、自动备份、失败自动回滚）供你粘贴回会话。
 
+**回读实际写入的结果**——配套的**「回读当前配置」**按钮复制 `iterate_config` 的 `{ operation: "read" }` 指令；模型把结果回显进会话后，卡片会在选择器下方展示所选字段的当前值（数组内联展示，如 `["npm test","npm run lint"]`）。三种状态被诚实区分：*尚未回读*、*当前值*、*已回读但没有该字段*（说明走的是内置默认值）。若剪贴板被拒绝，回读指令会在面板中展开供手动复制——按钮不会成为死路。
+
 ---
 
 ## 💬 使用
@@ -330,7 +334,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`（共 18 个版本，`0.1.1-rc.1` … `0.2.1-alpha.1`）。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.2.1-alpha.1` 构建，只使用公开契约（工具注册、客户端 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`（共 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 版本）。
 - **一次性 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>
@@ -360,8 +364,48 @@ 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`）
+
+- **已采纳——可变的会话工作目录。** `src/working-directory.ts` 通过
+  `ctx.get('workingDirectory').get(session)` 解析项目根（特性探测；服务缺失、
+  抛错、敌意 getter 或非字符串结果一律回退 `header.cwd`）。必须采纳的原因：
+  自 `0.2.1-alpha.2` 起，不可变的 header 按设计保留*原始*项目，切换目录后再读它
+  会把评审锚定到错误的检出。
+- **已评估、未采纳：**
+  - *Session 状态记录接口*（实验插件读写自己的会话记录）——依赖 shell 内部记录结构，
+    跨 alpha 版本极脆弱；iterate 的跨会话状态本就存放在 `.iterate/`。
+  - *共享 agents 目录的 `AGENTS.md`（`DSH_AGENTS_HOME`）*——属于宿主的全局指令机制，
+    插件注入的是自己的工作流提示词。
+  - *实验性 Git Worktrees 插件*——上游的 agent 工作流特性；插件自己的
+    `git.use_worktree` 配置早于它，且是另一回事（iterate 循环的逐轮 git 卫生）。
+  - *移除 `both` 混合展示模式*——插件从未设置展示模式（用的是 `presentCall` 卡片），
+    无需迁移。
+  - *从插件全局安装 dsh CLI*——运行时从不 shell 调用，纯占磁盘。
+- 五个 `@deepseek-ai/*` 包全部精确锁到 `0.2.1-alpha.2`
+  （`@deepseek-ai/cordis` 保持 `4.0.5-alpha.1`）。无安装期生命周期脚本
 （`preinstall`/`install`/`postinstall`/`prepare`）；仅 `prepublishOnly`（构建）在发布时运行。
 
 ### 失败边界

package/dist/config-loader.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import yaml from 'js-yaml';
+import { sessionCwdOf } from "./working-directory.js";
 /**
  * Load and parse iterate.config.yaml from the project root.
  * Returns null if the file is missing or invalid.
@@ -701,9 +702,14 @@ export function resolveProjectRoot(input, sessionCwd) {
 /**
  * Thin adapter for tool `execute(args, exec)` bodies: pull the session cwd
  * from the DSH run context and hand it to {@link resolveProjectRoot}.
+ *
+ * The cwd source is the EFFECTIVE session directory (dsh 0.2.1-alpha.2's
+ * `workingDirectory` service when the host provides one, else the immutable
+ * `header.cwd` — see `./working-directory.ts`), so a session whose directory
+ * was switched mid-run still resolves the project it is actually editing.
  */
 export function resolveProjectRootForExec(exec, input) {
-    return resolveProjectRoot(input, exec?.agent?.session?.header?.cwd);
+    return resolveProjectRoot(input, sessionCwdOf(exec));
 }
 /**
  * Resolve the default working directory for tools invoked without an explicit

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,19 +155,88 @@ export function acquireProjectLock(projectRoot, name, options = {}) {
         catch {
             // best-effort
         }
-        let released = false;
-        return () => {
-            if (released)
-                return;
-            released = true;
+        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.
+ *
+ * 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 (the shape left
+ * when our own advisory pid write failed, or when the content is not a pid).
+ *
+ * Always callable, idempotent, and never throws.
+ */
+/**
+ * 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)
+            return;
+        released = true;
+        let raw = '';
+        try {
+            raw = readFileSync(lockPath, 'utf-8').trim();
+        }
+        catch {
+            // Already gone (or unreadable) — nothing of ours left to remove.
+            return;
+        }
+        // A stamp naming another pid means the lock was stolen and reassigned:
+        // 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 {
-                unlinkSync(lockPath);
+                if (statSync(lockPath).ino !== ino)
+                    return;
             }
             catch {
-                // already gone
+                return; // vanished mid-release — nothing of ours left
             }
-        };
-    }
+        }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            // already gone
+        }
+    };
 }
 /**
  * Run `fn` while holding the advisory lock named `name`.

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

@@ -43,6 +43,7 @@ import { registerQualityGateTool } from "./tools/quality-gate.js";
 import { registerDefenseEventsTool } from "./tools/defense-events.js";
 import { registerSessionHooks } from "./session-hooks.js";
 import { registerLiveCapture } from "./live.js";
+import { installWorkingDirectoryContext } from "./working-directory.js";
 import { ITERATE_SKILL_PROMPT } from "./skill-prompt.js";
 export const name = 'iterate-plugin';
 export const inject = ['tools', 'systemPrompt'];
@@ -54,6 +55,12 @@ export function apply(ctx) {
     //    running with NO `tools/pre-execute` approval gate — a fail-open hole
     //    created by load order. Registering the gate first means a partial load
     //    can only ever err on the side of MORE gating, never less.
+    //
+    //    The working-directory context is installed first for the same reason:
+    //    every cwd read below (gate policy, live capture, tool project roots)
+    //    must see dsh 0.2.1-alpha.2+ directory switches, and installing it last
+    //    would leave a partially-loaded plugin resolving the wrong workspace.
+    installWorkingDirectoryContext(ctx);
     registerSessionHooks(ctx);
     registerLiveCapture(ctx);
     // 1. Register the 17 tools (14 original + 3 v3.0). Each registration is

package/dist/live.js

@@ -31,6 +31,7 @@ import { existsSync } from 'node:fs';
 import { writeTextAtomicAsync } from "./atomic-fs.js";
 import { join } from 'node:path';
 import { loadEffectiveConfig, resolveProjectRoot } from "./config-loader.js";
+import { sessionCwdOf } from "./working-directory.js";
 /** Keep at most this many live activity entries. */
 export const LIVE_MAX_ENTRIES = 300;
 /** Rewrite the live file when its byte size exceeds this threshold. */
@@ -107,7 +108,7 @@ export function appendLive(projectRoot, entry) {
 }
 /** Resolve the project root a tool execution belongs to, if any. */
 function projectRootOf(exec) {
-    const cwd = exec.agent?.session?.header?.cwd;
+    const cwd = sessionCwdOf(exec);
     if (!cwd)
         return null;
     const resolved = resolveProjectRoot(undefined, cwd);

package/dist/session-hooks.js

@@ -54,6 +54,7 @@
  */
 import { loadEffectiveConfig, resolveProjectRoot } from "./config-loader.js";
 import { decideApproval, isDestructiveIterateTool } from "./approval-gate.js";
+import { sessionCwdOf } from "./working-directory.js";
 /** Structured error identity attached to policy denials (dsh 0.1.6-alpha.1:
  *  `deny.info` lets durable projections / retry / replay distinguish an
  *  approval-policy denial from a tool-thrown failure). */
@@ -111,7 +112,11 @@ export function gateDecision(exec) {
             if (typeof p === 'string')
                 argPath = p;
         }
-        sessionCwd = exec?.agent?.session?.header?.cwd;
+        // Effective session directory (see ./working-directory.ts): a session whose
+        // directory was switched via dsh 0.2.1-alpha.2's `working_directory` tool
+        // must have its POLICY read from the workspace it is now in — `header.cwd`
+        // alone would read the original project's approval policy.
+        sessionCwd = sessionCwdOf(exec);
     }
     catch {
         // hostile/proxied exec — fall through with both undefined (defaults to ask)

package/dist/skill-prompt.js

@@ -134,7 +134,7 @@ for (let r = 1; r <= maxRounds; r++) {
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Already-known findings (do NOT re-report): ' +
         JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.'
-      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta?.findingsSchema }, backend))
     }))
     // A per-dimension reviewer subagent resolves \`null\` on child failure; the
     // aggregate below would report an all-failed round as an empty round, and
@@ -463,7 +463,7 @@ for (let r = startRound; r <= maxRounds; r++) {
         (steering ? '\\n STEERING — read this first: ' + steering : '') +
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.'
-      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta?.findingsSchema }, backend))
     }))
     // ALL reviewers returning null (child failures) means this round produced
     // no usable output — an empty aggregate must not read like a clean

package/dist/tools/checkpoint.js

@@ -12,6 +12,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { writeJsonAtomic } from "../atomic-fs.js";
+import { withProjectLock } from "../file-lock.js";
 import { checkpointPath, iterateDir, transcriptPath } from "../paths.js";
 import { readRegistry } from "./fix.js";
 import { readDecisionEntries } from "./decision-log.js";
@@ -289,23 +290,29 @@ export function registerCheckpointTool(ctx) {
                 return { operation: 'load', ok: true, checkpoint: checkpoint };
             }
             if (args.operation === 'resume') {
-                const current = readCheckpoint(projectRoot);
-                if (!current) {
-                    return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' };
-                }
-                const resumed = {
-                    ...current,
-                    resumeCount: (current.resumeCount ?? 0) + 1,
-                    updatedAt: new Date().toISOString(),
-                };
-                try {
-                    mkdirSync(iterateDir(projectRoot), { recursive: true });
-                    writeJsonAtomic(checkpointPath(projectRoot), resumed);
-                }
-                catch (err) {
-                    return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` };
-                }
-                return { operation: 'resume', ok: true, checkpoint: resumed };
+                // Read-modify-write across processes: a concurrent resume in a
+                // sibling process would read the same resumeCount and write it back,
+                // losing one increment. Serialize on a checkpoint lock (the same
+                // advisory pattern the config/triage/transcript writers use).
+                return withProjectLock(projectRoot, 'checkpoint', () => {
+                    const current = readCheckpoint(projectRoot);
+                    if (!current) {
+                        return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' };
+                    }
+                    const resumed = {
+                        ...current,
+                        resumeCount: (current.resumeCount ?? 0) + 1,
+                        updatedAt: new Date().toISOString(),
+                    };
+                    try {
+                        mkdirSync(iterateDir(projectRoot), { recursive: true });
+                        writeJsonAtomic(checkpointPath(projectRoot), resumed);
+                    }
+                    catch (err) {
+                        return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` };
+                    }
+                    return { operation: 'resume', ok: true, checkpoint: resumed };
+                });
             }
             if (args.operation === 'clear') {
                 const existed = existsSync(checkpointPath(projectRoot));