dsh-workflow-map 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -3,6 +3,92 @@
 `dsh-workflow-map` 的所有重要变更记录在此。
 格式遵循 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)，版本号遵循 [SemVer](https://semver.org/)。
 
+## [0.3.4] - 2026-10-30
+
+### Changed
+
+- **宿主要求改由 `engines.dsh` 声明**：`>=0.2.1-rc.1 <0.3.0-0`，覆盖 `0.2.1` 全系列（`rc.1` 至 `rc.5`）与 `0.2.1` 正式版。
+  该区间由宿主在安装与启用期读取（`dsh-app-boot` 的 `evaluatePluginCompatibility()`），不满足即拒绝加载。
+- **删除非标准 `dsh.host` 字段**：宿主包仍由 `peerDependencies` 声明（均为可选 peer），版本闸门只看 `engines.dsh`。
+- **中英 README 增加宿主要求块**：逐版本核验方式与结论、区间写法说明，区间字符串与 `package.json` 的 `engines.dsh` 逐字符一致。
+
+### Added
+
+- **`docs/host-compatibility.md`**：区间判据、206 包闭包比对、九个契约点的逐版本证据，以及 `0.2.1-rc.3`（实机运行）
+  与 `0.2.1-rc.1` / `rc.2` / `rc.4` / `rc.5`（契约核验）的区别。
+
+### Fixed
+
+- **计划行自带的步骤文件名不再被当成标题的一部分**。PAE 会把计划行渲染成 `1. 标题（限定语）（step-01-x.md）`，
+  折叠时连行尾的文件名一起收进标题，于是这一步的标题比待办表里那一行多一个括号组：`foldTodos` 拿步骤键
+  与表比对时判定「无变化」，视图里留下一条对话正文并不存在的分步（`audit-real` 约束 ①）。
+  现在解析计划行时就剥掉行尾的 `.md` / `.json` 等文件名标注；计划标题改写时同步更新步骤键，
+  旧键归档进 `aliasKeys`（与改名同一条路径），已挂在旧键上的节点随之迁移。
+- **`docs/` 与两份 README 的口语化表述收敛为陈述句**：删去带日期的括号注、第一人称示例与破折号转折，
+  内容不变。
+- **浅色主题下分步卡与背景同色**。宿主在浅色主题里把 `--dsw-alias-bg-layer-1` 与 `-2` 都解析到
+  `--dsw-static-neutral-bluish-00`（即 `#fff`），与 `--dsw-alias-bg-base` 同一个值；分步卡当时只填 `bg-layer-2`
+  且边线是 `transparent`，于是整块卡面在白底上不可见。现在卡面带自己的抬升墨色
+  （`--wf-lift` / `--wf-lift-2`，深色主题另行覆盖），边线改用 `--dsw-alias-border-l2`，分步、节点、
+  单元三类卡面与悬停/选中态一致。
+- **待办表是步骤生命周期的唯一依据**。`todo/write` 每次重写整张表，但视图同步把行“配对”到旧记录时
+  沿用了那条记录的旧状态：表中写 `pending` 的行显示成 `done`/100%，表中写 `in_progress` 的行显示成
+  `pending`（同一会话里两种都出现过）。现在配对后一律按行本身的状态落值，未命名、从未开始、又不拥有
+  任何节点的 `pending` 行会被丢弃，会话不再因为改写过表格而长出空卡。
+- **非运行中的分步不再显示百分比**。`percentFor()` 在进入各条测算路径（自报 / 待办比值 / 基线）之前先判状态：
+  只要不是 `running` 就不出数字。此前 74 步待办（5–99%）带着一个没人更新过的旧数字，看着像停滞。
+- **回合结束时关闭该回合的运行步**。`foldTurnEnd` 以前只翻 `turnActive` 标志，运行步会一直是 `running`；
+  现在按结束时刻补时长并结束该步，唯一的例外是待办表此刻仍标 `in_progress`（那一步确实跨回合继续做）。
+- **检查点版本 3 → 4**：旧检查点里的步骤台账按旧映射生成（错误状态、残留空行、带有不应存在的百分比），
+  按既有契约丢弃后从日志重建。
+- **量测脚本不再依赖 `--dump-dom`**。Edge 156.0.4314.50 的启动器会在毫秒内以退出码 0 退出、把真正的浏览器进程
+  甩成独立进程，于是 `--dump-dom` 写进一个没人持有的 stdout，落盘文件恒为 0 字节（`--version` 也无输出）。
+  新增 `tools/cdp-dump.mjs`：自己拉起无头浏览器、从 `DevToolsActivePort` 拿调试端口、连页面 target、
+  `Page.enable` + `Runtime.evaluate(document.documentElement.outerHTML)` 取 DOM，失败必抛；
+  10 个 `tools\measure-*.ps1` 全部改为调它，并新增 `tools\patch-measure-cdp.mjs` 留证改法。
+
+### Tests
+
+- **离线自测 10 套 / 1533 条断言**全部通过，退出码全 0（0.3.3 为 1515 条）。本轮新增 13 条：`selftest-fold`
+  的 `(r)` 用例 8 条（待办表改回 `pending` 必须降级、改写表后的 `pending` 行不得顶替运行步、
+  `in_progress` 行对应的记录即使原来是 `pending` 也要转为运行、未命名空行被丢弃、回合结束仍保留表中
+  `in_progress` 的步、非运行行不出数字……），`selftest-panel` 的浅色主题针脚 5 条（抬升变量、深色覆盖、
+  卡面抬升、卡面边线取 token、悬停抬升）。
+- **真实会话日志**：`check-real-injects` 折叠 147 个会话、识别出 19 条热注入记录、failures 0；
+  `audit-real` 折叠 148 个会话、629 个步骤，约束 ①（分步必须存在于待办表）与 ②（同一时刻只有一个
+  running 步）各 0 违规；`done` 步显示 <100% 的数量为 **0**，非运行步带数字的数量为 **0**（修前 74 条）。
+- **浏览器量测 10 套 / 323 条断言**全部通过，退出码全 0（0.3.3 为 308 条）：
+  `panel 21 · timing 20 · inject 43 · dock 14 · flow 20 · effects 28 · branches 15 · detail 50 · settings 56 · main 56`。
+  `main` 从 41 增至 56 的 15 条是本轮新增的主题对比检查：浅色帧的页面底色确实是宿主真值 `#fff`、
+  两种主题下 `--wf-lift` 各自生效、单元卡边线 alpha 与抬升渐变俱在、14 px 颗星徽标靠自身颜色边线可见
+  （实测 light/dark 均为 `rgba(…,1)`）。旧的 `card` / `node`（遗留组件）不在单页上，按「不存在不记失败」处理，
+  它们的边线与抬升由 `selftest-panel` 的样式表针脚守住。
+- **`0.2.1-rc.5` 隔离实机**：`--dump-config` 退出码 0、stdout 1234 行、零告警；
+  `/dsh-workflow/state`、`/steer`、`/unsteer` 按本插件契约应答（`404 unknown session`、缺参 `400`）。
+  记录与复跑命令见 `docs/host-compatibility.md` §3.1。
+
+## [0.3.3] - 2026-10-29
+
+### Fixed
+
+- **编号清单的序号不再丢失，地图不再重复显示步骤**。模型把待办表从 7 行无编号换成 14 行带 `1. `–`14. ` 前缀后，`syncToTodos` 把序号从**已经剥掉前缀的标题**上再解析一次，
+  于是 `planIndexOf` 永远返回 null；创建出的行丢了序号，而 `foldTodos` 按位置配对时又不回写序号，
+  旧行继续带着上一份计划的 `planIndex`。`applyPlanToView` 随后按这个错序号把计划步骤 2/3/4 的标题和状态
+  盖到别的行上。用户看到的是第 3–7 步各出现两次，跑动中的那一格也不是真正的当前步。
+  修法：`planIndex` 从**原始 content** 解析；配对到旧行时把序号按当前表回写；槽位配对遇到序号冲突时让位给按序号匹配。
+  复现判据：修前的视图里 14 行有 5 组标题重名，修后 `planIndex` 1–14 连续且无重名。
+- **计划自带的确认点不再丢失**。`orchestrator.json` 里 `requiresConfirmation: true` 的步骤（该会话第 2/12/13 步）
+  在地图上一个「需确认」标记都没有：`applyPlanToView` 的注释说宿主会合并这一半，但代码里没有这段合并。
+  现在由 `applyPlanToView` 补上，标记的 `kind` 为 `plan`；已 done/failed 的步骤不带标记（与日志侧规则一致），
+  重复应用同一份计划不会叠加。
+
+### Tests
+
+- `tools/selftest-fold.mjs` 新增 8 条断言：`(o1)`/`(o2)` 编号清单换表后序号连续、标题不重名、
+  行不继承邻居标题；`(p)` 计划确认点只落在该落的步骤、`kind` 为 `plan`、重复应用不重复、已完成步骤不带标记。
+- 离线自测 **10 套 / 1515 条断言**全部通过（0.3.2 为 1507 条）。
+
+
 ## [0.3.1] - 2026-10-28
 
 ### Fixed
@@ -10,9 +96,9 @@
 - **`soft` 配色的同类残留**。0.3.0 已让 `brand` 配色下运行中卡片的外框跟随品牌色，
   但 `soft` 配色的规则仍只认单页改版之前的选择器（`.wf-step-item > .wf-step-card` / `.wf-node`），
   于是切到 `soft` 时运行中单元的外框仍是默认彩虹渐变、状态环仍停在品牌蓝、
-  卫星圆点与连线的流光也没换色。现在 `soft` 与 `brand` 一样同时命名现役选择器——
-  `.wf-unit[data-status='running']>.wf-unit-center>.wf-unit-card::after`、`.wf-unit-ring`、
-  `.wf-sat[data-live='true']::after` 与 `.wf-sat-row[data-live='true'] .wf-sat-line`——
+卫星圆点与连线的流光也没换色。现在 `soft` 与 `brand` 一样同时命名现役选择器
+  （`.wf-unit[data-status='running']>.wf-unit-center>.wf-unit-card::after`、`.wf-unit-ring`、
+  `.wf-sat[data-live='true']::after` 与 `.wf-sat-row[data-live='true'] .wf-sat-line`），
   三处一并跟随 `--wf-soft-1` / `--wf-soft-2`。
 - 对应的浏览器量测从「记录缺陷」改为「断言修复」：`settings.soft.keepsRainbowRing`
   换成 `settings.soft.frameMigrated` 与 `settings.soft.ringColor`，两者都用期望色
@@ -56,7 +142,7 @@
   收敛为唯一 running 行；进度上报也归属到待办表里真正 `in_progress` 的那一行。
 - **地图分步与对话里的待办表不一致**：折叠只增不删，重新规划或改写标题后旧行会残留。
   现在视图严格按最新待办表产出分步，表里已不存在的行与其节点一并移除。
-- **已完成的步显示「0 工具 0 文件」**：三个叠加的问题——按标题匹配导致改写文案后旧行变孤儿、
+- **已完成的步显示「0 工具 0 文件」**：三个叠加的问题。按标题匹配导致改写文案后旧行变孤儿、
   新建行未写入步骤键、全局节点上限按「丢弃最老」执行而最老的恰属已完成步。
   现已改为就地改名并迁移节点、统一赋值步骤键、并从节点最多的步开始淘汰（单步永不被清空）。
 - **被拒绝的审批仍标「需确认」**：审批被拒时该行仍需人工处理，原实现把任何「已决议」都当成已结束。
@@ -66,7 +152,7 @@
 
 ### Changed
 
-- **面板布局改为单页**：原先的左右双列（分步列 + 流程列）合并为一个视图——串行主流程在中间，
+- **面板布局改为单页**：原先的左右双列（分步列 + 流程列）合并为一个视图。串行主流程在中间，
   每步两侧以圆形接口表示该类工具/文件，点击后在右页展开详情。两列之间的跨列曲线随之移除。
 - **移除「预计剩余时间」**：进度条第二行只保留「N 分钟前估计」（这个数字有多旧），
   不再预测还需要多久。宿主侧相应的计算与字段一并移除。

package/README.en.md

@@ -4,6 +4,22 @@ English · [**简体中文**](README.md)
 
 A DeepSeek Harness plugin that renders the current session as an interactive step-by-step workflow map.
 
+> **Host requirement**
+>
+> - **DSH kernel**: `engines.dsh` = `>=0.2.1-rc.1 <0.3.0-0`, covering the whole `0.2.1` series (`0.2.1-rc.1` through `0.2.1-rc.5`) and the `0.2.1` release.
+> - **Node.js**: `>=20` (`engines.node`).
+> - Host packages are declared as `peerDependencies` (all optional peers, same range as `engines.dsh`); the host is not bundled. Hosts below `0.2.1-rc.1`, or at `0.3.0` and above, are outside the declared range.
+> - Range note: `>=0.2.1-rc.1 <0.3.0-0` carries an explicit prerelease tag on the `0.2.1` tuple, which is what makes it match `0.2.1-rc.x`; a start of `>=0.1.0-rc.1` silently excludes every `0.2.1` prerelease. The upper bound `<0.3.0-0` sorts below every prerelease of `0.3.0`, so the whole `0.3` line (including `0.3.0-rc.1`) stays outside the range.
+
+Per-version method and result:
+
+| Host version | How it was checked | Result |
+|---|---|---|
+| `0.2.1-rc.3` | Run on a real host: plugin load, panel injection, view routes | Baseline |
+| `0.2.1-rc.1` / `0.2.1-rc.2` / `0.2.1-rc.4` / `0.2.1-rc.5` | Cross-version contract check: closure metadata, per-file SHA-256, contract anchor windows | All nine contract points unchanged |
+
+A contract check is not a real-host run: the last four versions were compared against published artifacts and contract anchors only, and never booted. Method and evidence: [`docs/host-compatibility.md`](docs/host-compatibility.md).
+
 Three entry points share one data source and one set of components: the sidebar panel item
 (`sidebar.panellist`), the main content area (`main`), and the session tab bar (`conversation.view`).
 The panel folds session events into a step sequence, showing each step's status, progress, tool calls
@@ -18,7 +34,7 @@ opened for a step (type list, step detail). Bottom: the persistent injection bar
 ![license](https://img.shields.io/badge/license-MIT-blue)
 ![platform](https://img.shields.io/badge/platform-DeepSeek%20Harness-brightgreen)
 ![node](https://img.shields.io/badge/node-%E2%89%A520-informational)
-![version](https://img.shields.io/badge/version-0.3.1-success)
+![version](https://img.shields.io/badge/version-0.3.4-success)
 
 ---
 
@@ -63,8 +79,6 @@ encoding (animation and colour).
 
 ### 2.1 Hot injection (steer / unsteer)
 
-This section states the write semantics, state determination and failure semantics of the injection channel.
-All three are derived from session log events; the front end does not guess.
 **Write semantics**: `POST /dsh-workflow/steer` calls the host's `agent.steer(message)`; the message
 enters the session inbox queue `next-step` and is claimed by the next step **after the current turn
 ends**. The call does not trigger `cancel`, so the running turn is not interrupted.
@@ -94,9 +108,6 @@ the capability.
 
 ### 2.2 Progress estimation
 
-This section states the percentage priority order, the algorithm and cap of each source, and the definition
-of the staleness field. The rule is implemented by `percentFor` in `src/fold.mjs`.
-
 Each step's percentage is resolved by the following **priority** (`percentFor` in `src/fold.mjs`):
 | Priority | Source | Rule | Cap |
 |---|---|---|---|
@@ -163,7 +174,7 @@ can collapse the host's composer on that page; switching back unmounts the view
 ## 3. Installation
 
 > **Prerequisites for installing from the market**: two conditions must both hold. (1) `dsh-workflow-map`
-> is published on npm (currently `0.3.1`). (2) The `awesome-dsh-plugin` PR is merged **and** the market index
+> is published on npm (currently `0.3.4`). (2) The `awesome-dsh-plugin` PR is merged **and** the market index
 > (`dsh-plugin-catalog`, served via jsDelivr) has refreshed and picked up the entry.
 > Once both hold, install from the **DSH market** (Plugins > Discover) by searching `workflow`, no terminal needed.
 > If it is not indexed yet, use the command line below (3.2) to install the same package; both routes are equivalent.
@@ -293,8 +304,8 @@ steps, their status, the percentage source, the node list and the report artifac
 
 ## 8. Compatibility and constraints
 
-- **DeepSeek Harness** 0.2.x or newer (relies on session projections and `webServer` route registration).
-- **Node.js** ≥ 20。
+- **DeepSeek Harness**: the `engines.dsh` range `>=0.2.1-rc.1 <0.3.0-0` (relies on session projections and `webServer` route registration); `0.3.0` and newer are not supported.
+- **Node.js**: `>=20`.
 - The three endpoints mount on the host's existing port; **no new listener** is opened.
 - The composer is rendered by the host and is not part of this plugin. The plugin neither replaces nor
   overlays it; it only yields space on the session-tab page through a stylesheet rule.
@@ -309,7 +320,7 @@ steps, their status, the percentage source, the node list and the report artifac
 # after editing src/client/*.js, rebuild the browser half
 node tools/build-client.mjs
 
-# offline self-tests (10 suites, 1507 assertions)
+# offline self-tests (10 suites, 1533 assertions)
 node tools/selftest-fold.mjs          # fold semantics
 node tools/selftest-host.mjs          # registration, schema, projection wiring
 node tools/selftest-orchestrator.mjs  # plan file reading and merging
@@ -326,7 +337,7 @@ node tools/check-real-injects.mjs     # fold historical logs in bulk
 node tools/audit-real.mjs             # four-constraint audit
 ```
 
-Browser measurements (needs a Chromium; the scripts auto-detect Chrome / Edge; 308 assertions):
+Browser measurements (needs a Chromium; the scripts auto-detect Chrome / Edge; 323 assertions, light/dark theme contrast included):
 
 ```bash
 pwsh -File tools/measure-panel.ps1
@@ -417,7 +428,7 @@ baseline creeps up but is capped at 90 %. The second line ("estimated N minutes
 The todo table caps at 99 and the time baseline at 90; only a done/failed status pins 100 %. This keeps
 "nearly there" from being confused with "already there".
 
-**Does it upload my code?**
+**Does it upload user code?**
 No. The plugin makes no network requests; it reads only the local session log and the `.pae` plan file.
 
 **Can I install only the UI and skip the host half?**

package/README.md

@@ -4,7 +4,23 @@
 
 DeepSeek Harness 插件：把当前会话渲染为一张可交互的分步工作流地图。
 
-三个入口共用同一份数据与同一套组件 —— 侧边栏面板项（`sidebar.panellist`）、主内容区（`main`）、
+> **宿主适配要求（Host requirement）**
+>
+> - **DSH 内核**：`engines.dsh` = `>=0.2.1-rc.1 <0.3.0-0`，覆盖 `0.2.1` 全系列（`0.2.1-rc.1` 至 `0.2.1-rc.5`）与 `0.2.1` 正式版。
+> - **Node.js**：`>=20`（`engines.node`）。
+> - 宿主包以 `peerDependencies` 声明（均为可选 peer，区间与 `engines.dsh` 一致），不打包宿主；低于 `0.2.1-rc.1` 或 `0.3.0` 及以上的宿主不在声明范围内。
+> - 区间写法：`>=0.2.1-rc.1 <0.3.0-0` 在 `0.2.1` 元组上带显式预发布标签，才能匹配 `0.2.1-rc.x`；起点若写 `>=0.1.0-rc.1`，`0.2.1` 的预发布版本会被静默排除。上界 `<0.3.0-0` 小于 `0.3.0` 的任何预发布版本，因此整条 `0.3` 线（含 `0.3.0-rc.1`）都在区间外。
+
+逐版本核验方式与结论：
+
+| 宿主版本 | 核验方式 | 结论 |
+|---|---|---|
+| `0.2.1-rc.3` | 实机运行：插件加载、面板注入、视图路由 | 基线版本 |
+| `0.2.1-rc.1` / `0.2.1-rc.2` / `0.2.1-rc.4` / `0.2.1-rc.5` | 跨版本契约核验：闭包元数据、逐文件 SHA-256、契约锚点窗口 | 九个契约点未变 |
+
+契约核验不等于实机运行：上表后四个版本只处理已发布的产物与契约锚点，未启动宿主。方法与证据见 [`docs/host-compatibility.md`](docs/host-compatibility.md)。
+
+三个入口共用同一份数据与同一套组件：侧边栏面板项（`sidebar.panellist`）、主内容区（`main`）、
 会话标签栏（`conversation.view`）。面板将会话事件折叠为分步序列，展示每步的状态、进度、
 工具调用与文件操作，并支持在会话运行中向其下一步注入提示词。
 
@@ -17,7 +33,7 @@ DeepSeek Harness 插件：把当前会话渲染为一张可交互的分步工作
 ![license](https://img.shields.io/badge/license-MIT-blue)
 ![platform](https://img.shields.io/badge/platform-DeepSeek%20Harness-brightgreen)
 ![node](https://img.shields.io/badge/node-%E2%89%A520-informational)
-![version](https://img.shields.io/badge/version-0.3.1-success)
+![version](https://img.shields.io/badge/version-0.3.4-success)
 
 ---
 
@@ -60,7 +76,6 @@ DeepSeek Harness 插件：把当前会话渲染为一张可交互的分步工作
 
 ### 2.1 热注入（steer / unsteer）
 
-本节给出注入通道的写入语义、状态判定与失败语义；三者均以会话日志事件为依据，前端不作推测。
 **写入语义**：`POST /dsh-workflow/steer` 调用宿主的 `agent.steer(message)`，消息进入会话收件箱的
 `next-step` 队列，在**当前轮次结束后**由下一步取用。调用不触发 `cancel`，因此不中断正在执行的轮次。
 
@@ -81,14 +96,12 @@ HTTP 200 仅表示消息已进入收件箱，**不等价于**会话已读取；
 事件区分。撤回的持久记录是 splice 的**位置**而非消息 id，因此折叠侧维护一份收件箱台账
 （按宿主 `inboxProjectionDefinition` 的 splice 语义逐条重放）才能定位被移除的具体行。
 
-失败语义：文档型错误一律返回 JSON，不向 HTTP 层抛出异常。常见状态码 —— `400` 缺字段 /
+失败语义：文档型错误一律返回 JSON，不向 HTTP 层抛出异常。常见状态码：`400` 缺字段 /
 body 非 JSON，`404` 会话不存在，`409` 会话未在运行或消息已被取用，`413` 文本超 2000 字或
 body 超 64 KiB，`503` 宿主未暴露相应能力。
 
 ### 2.2 进度估算
 
-本节给出百分比的取值优先级、各来源的算法与上限，以及陈旧程度字段的定义。
-
 每步的百分比按以下**优先级**取值（`src/fold.mjs` 的 `percentFor`）：
 | 优先级 | 来源 | 计算规则 | 上限 |
 |---|---|---|---|
@@ -147,7 +160,7 @@ body 超 64 KiB，`503` 宿主未暴露相应能力。
 
 ## 3. 安装
 
-> **市场安装的前提**：该入口要求同时满足两个条件 ——（1）`dsh-workflow-map` 已发布到 npm（当前为 `0.3.1`）；
+> **市场安装的前提**：该入口要求同时满足两个条件。（1）`dsh-workflow-map` 已发布到 npm（当前为 `0.3.4`）；
 > （2）`awesome-dsh-plugin` 的 PR 已合并，且市场索引（`dsh-plugin-catalog`，经 jsDelivr 分发）已刷新收录该条目。
 > 满足后在 **DSH 市场**（Plugins → Discover）搜索 `workflow` 即可安装，无需命令行；
 > 若尚未收录，使用下面的命令行方式（3.2）安装同一个包，两者效果一致。
@@ -275,7 +288,7 @@ curl -i "http://127.0.0.1:<GUI端口>/dsh-workflow/state?sessionId=<会话ID>"
 
 ## 8. 兼容性与约束
 
-- **DeepSeek Harness** 0.2.x 及以上（依赖会话投影与 `webServer` 路由注册）。
+- **DeepSeek Harness**：`engines.dsh` 声明的区间 `>=0.2.1-rc.1 <0.3.0-0`（依赖会话投影与 `webServer` 路由注册）；`0.3.0` 及以后不支持。
 - **Node.js** ≥ 20。
 - 三个端点挂载在宿主既有端口上，**不新开监听**。
 - 输入框（composer）由宿主渲染，不属于本插件。插件不替代、不覆盖该组件；仅在会话标签栏入口
@@ -290,7 +303,7 @@ curl -i "http://127.0.0.1:<GUI端口>/dsh-workflow/state?sessionId=<会话ID>"
 # 修改 src/client/*.js 后必须重新生成浏览器半
 node tools/build-client.mjs
 
-# 离线自测（10 套，共 1507 条断言）
+# 离线自测（10 套，共 1533 条断言）
 node tools/selftest-fold.mjs          # 折叠语义
 node tools/selftest-host.mjs          # 注册、schema、投影接线
 node tools/selftest-orchestrator.mjs  # 计划文件读取与合并
@@ -307,7 +320,7 @@ node tools/check-real-injects.mjs     # 批量折叠历史日志
 node tools/audit-real.mjs             # 四项约束审计
 ```
 
-浏览器量测（需一份 Chromium，脚本自动探测 Chrome / Edge，共 308 条断言）：
+浏览器量测（需一份 Chromium，脚本自动探测 Chrome / Edge，共 323 条断言，含浅色/深色主题对比检查）：
 
 ```bash
 pwsh -File tools/measure-panel.ps1
@@ -396,7 +409,7 @@ dsh-workflow-map/
 待办表封顶 99、时间基线封顶 90；只有状态进入完成/失败才固定 100%。
 这是为了避免「看起来快好了」与「已经好了」混淆。
 
-**它会把我的代码上传吗？**
+**会把用户代码上传吗？**
 不会。插件不发起任何网络请求；只读本地会话日志与 `.pae` 计划文件。
 
 **可以只换界面、不装宿主半吗？**
@@ -418,7 +431,7 @@ MIT。允许商用、修改与再分发，需保留版权声明。
 以下信息有助于定位问题：
 
 1. DSH 版本与插件版本（`package.json` 的 `version`）；
-2. `GET /dsh-workflow/state?sessionId=<id>` 的响应体 —— **其中包含任务标题与文件路径，
-   提交前请自行删减**；
+2. `GET /dsh-workflow/state?sessionId=<id>` 的响应体（**其中包含任务标题与文件路径，
+   提交前请自行删减**）；
 3. 出现问题的面板截图；
 4. 若与折叠有关，附上该会话日志中相关事件序列的片段。

package/client.js

@@ -198,7 +198,15 @@ window.__ModuleLoader__.load({
      // the three branch hues live on the ROOT, so the dashed branches and their round
      // icons share one palette with the rest of the panel (and one place to change it).
         "--wf-chain-read:#5b8cff;--wf-chain-edit:#e0a13a;--wf-chain-tool:#8f7bea;" +
+      // `--dsw-alias-bg-layer-1` and `-2` carry the SAME value in the host's light theme (both
+      // neutral-bluish-00, i.e. #fff), so a card filled with layer-2 is invisible on the page. Every
+      // raised surface in the panel therefore paints one translucent lift over that fill. The lift goes
+      // towards ink on a light page and towards white on a dark one; the host marks dark by putting
+      // `data-ds-dark-theme` on <body>, so the light values are the defaults and the dark block below
+      // only wins when that attribute is present.
+        "--wf-lift:rgba(15,23,42,.045);--wf-lift-2:rgba(15,23,42,.085);" +
         "font-family:ui-sans-serif,system-ui,-apple-system,'Segoe UI','Microsoft YaHei',sans-serif;font-size:12px;line-height:1.5}",
+      "body[data-ds-dark-theme] .wf-root{--wf-lift:rgba(255,255,255,.035);--wf-lift-2:rgba(255,255,255,.07)}",
 
      /* card: fills the main area; the header and the settings card keep their own height,
          the two-column body takes the rest. No drag grips: the column has no free edges.
@@ -281,13 +289,14 @@ window.__ModuleLoader__.load({
      // `grid-area:1/1` is what makes the triangle and the card share the cell: without it the
      // auto-placement cursor would drop the card into row 2, below the triangle.
       ".wf-step-card{grid-area:1/1;display:flex;gap:8px;align-items:flex-start;width:100%;padding:7px 8px;border-radius:8px;text-align:left;" +
-        "font:inherit;color:inherit;cursor:pointer;border:1px solid transparent;" +
-        "background:var(--dsw-alias-bg-layer-2,#282d3a);border-left:3px solid transparent}",
+        "font:inherit;color:inherit;cursor:pointer;border:1px solid var(--dsw-alias-border-l2,rgba(255,255,255,.22));" +
+        "background:var(--dsw-alias-bg-layer-2,#282d3a);background-image:linear-gradient(var(--wf-lift),var(--wf-lift));" +
+        "border-left:3px solid transparent}",
       ".wf-step-card:hover{border-color:var(--dsw-alias-border-l2,rgba(255,255,255,.22));" +
-        "background:var(--dsw-alias-bg-layer-1,#232733)}",
+        "background:var(--dsw-alias-bg-layer-1,#232733);background-image:linear-gradient(var(--wf-lift-2),var(--wf-lift-2))}",
       ".wf-step-card:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5b8cff);outline-offset:1px}",
       ".wf-step-card[data-selected='true']{border-color:var(--dsw-alias-brand-primary,#5b8cff);" +
-        "background:var(--dsw-alias-bg-layer-1,#232733)}",
+        "background:var(--dsw-alias-bg-layer-1,#232733);background-image:linear-gradient(var(--wf-lift-2),var(--wf-lift-2))}",
       ".wf-step-card[data-active='true']{border-left-color:var(--dsw-alias-brand-primary,#5b8cff)}",
       ".wf-step-ring{flex:0 0 auto;width:18px;height:18px;margin-top:1px;border-radius:50%;" +
         "display:inline-flex;align-items:center;justify-content:center;font-size:11px;line-height:1;" +
@@ -441,7 +450,7 @@ window.__ModuleLoader__.load({
       ".wf-branch-icon{flex:0 0 auto;width:" + WF_CHAIN_ICON + "px;height:" + WF_CHAIN_ICON + "px;padding:0;" +
         "border-radius:50%;display:inline-flex;align-items:center;justify-content:center;" +
         "font:inherit;font-size:11px;line-height:1;cursor:pointer;position:relative;" +
-        "background:var(--dsw-alias-bg-layer-2,#282d3a);color:var(--dsw-alias-label-secondary,#9aa3b2);" +
+        "background:var(--dsw-alias-bg-layer-2,#282d3a);background-image:linear-gradient(var(--wf-lift),var(--wf-lift));color:var(--dsw-alias-label-secondary,#9aa3b2);" +
         "border:1px solid var(--dsw-alias-border-l2,rgba(255,255,255,.28))}",
       ".wf-branch-icon:hover{color:var(--dsw-alias-label-primary,#e9ecf3)}",
       ".wf-branch-icon:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5b8cff);outline-offset:2px}",
@@ -471,12 +480,14 @@ window.__ModuleLoader__.load({
      /* node card: icon · title · meta · status dot */
       ".wf-node{display:flex;gap:7px;align-items:flex-start;width:100%;padding:6px 8px;border-radius:8px;" +
         "text-align:left;font:inherit;color:inherit;cursor:pointer;" +
-        "background:var(--dsw-alias-bg-layer-2,#282d3a);border:1px solid transparent;" +
+        "background:var(--dsw-alias-bg-layer-2,#282d3a);background-image:linear-gradient(var(--wf-lift),var(--wf-lift));" +
+        "border:1px solid var(--dsw-alias-border-l2,rgba(255,255,255,.22));" +
         "border-left:3px solid var(--dsw-alias-border-l2,rgba(255,255,255,.2))}",
-      ".wf-node:hover{border-color:var(--dsw-alias-border-l2,rgba(255,255,255,.24));background:var(--dsw-alias-bg-layer-1,#232733)}",
+      ".wf-node:hover{border-color:var(--dsw-alias-border-l2,rgba(255,255,255,.24));" +
+        "background:var(--dsw-alias-bg-layer-1,#232733);background-image:linear-gradient(var(--wf-lift-2),var(--wf-lift-2))}",
       ".wf-node:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5b8cff);outline-offset:1px}",
       ".wf-node[data-selected='true']{border-color:var(--dsw-alias-brand-primary,#5b8cff);" +
-        "background:var(--dsw-alias-bg-layer-1,#232733)}",
+        "background:var(--dsw-alias-bg-layer-1,#232733);background-image:linear-gradient(var(--wf-lift-2),var(--wf-lift-2))}",
       ".wf-node[data-selected='true'] .wf-node-title{font-weight:600}",
       ".wf-node[data-kind='tool']{border-left-color:var(--dsw-alias-brand-primary,#5b8cff)}",
       ".wf-node[data-kind='report']{border-left-color:var(--dsw-alias-state-success-primary,#45c07a)}",
@@ -1053,11 +1064,12 @@ window.__ModuleLoader__.load({
 
      /* ---- the unit card ---- */
       ".wf-unit-card{display:grid;grid-template-columns:auto auto minmax(0,1fr);align-items:flex-start;gap:8px;" +
-        "width:100%;padding:10px 12px;border-radius:10px;text-align:left;border:1px solid transparent;" +
-        "background:var(--dsw-alias-bg-layer-2,#282d3a);color:inherit;font:inherit;cursor:pointer;" +
+        "width:100%;padding:10px 12px;border-radius:10px;text-align:left;border:1px solid var(--dsw-alias-border-l2,rgba(255,255,255,.22));" +
+        "background:var(--dsw-alias-bg-layer-2,#282d3a);background-image:linear-gradient(var(--wf-lift),var(--wf-lift));" +
+        "color:inherit;font:inherit;cursor:pointer;" +
         "border-left:3px solid transparent;box-sizing:border-box}",
       ".wf-unit-card:hover{border-color:var(--dsw-alias-border-l2,rgba(255,255,255,.22));" +
-        "background:var(--dsw-alias-bg-layer-1,#232733)}",
+        "background:var(--dsw-alias-bg-layer-1,#232733);background-image:linear-gradient(var(--wf-lift-2),var(--wf-lift-2))}",
       ".wf-unit-card:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5b8cff);outline-offset:1px}",
       ".wf-unit-card[data-selected='true']{border-color:var(--dsw-alias-brand-primary,#5b8cff)}",
       ".wf-unit-card[data-active='true']{border-left-color:var(--dsw-alias-brand-primary,#5b8cff)}",
@@ -2653,7 +2665,7 @@ window.__ModuleLoader__.load({
      * "0 seconds ago" would be a fabricated number, which is exactly what this plugin
      * refuses to print.
      *
-     * (2026-10-26) · the projected REMAINING half is GONE by user request. It used to be shipped
+     * The projected REMAINING half is no longer part of this rail. It used to be shipped
      * by the host as a derived millisecond field (median of the finished steps, hard-bounded) and
      * rendered as "remaining ~N minutes"; the host no longer computes it and this rail no longer renders it.
      * One line, one fact, no consumer-less field — and a payload that still carries that field (an

package/cordis.patch.yml

@@ -1,8 +1,8 @@
 # dsh-workflow-map — bundle 挂载声明
 #
-# 本文件只做一件事：把这个包的宿主半插入 DSH 的插件行。
-# 浏览器半不需要单独声明 —— 它由 package.json 的 `dsh.client`（platform: web）指向
-# 本包的 ./client，所以这里没有 client 行。
+# 作用：把这个包的宿主半插入 DSH 的插件行。
+# 浏览器半不由本文件声明 —— package.json 的 `dsh.client`（platform: web）指向本包的
+# ./client，因此这里没有 client 行。
 #
 # id 在整个 profile 的 patch 层里必须唯一。
 

package/docs/OPEN-SOURCE-GUIDE.md

@@ -23,8 +23,8 @@
 | `locale/` / `icon.svg` | 词典与图标 |
 | `tools/` | 自测、探针、浏览器量测（**不随 npm 包发布**，进 Git） |
 
-**发布前必改**：`package.json` 里三处 `YOUR_GITHUB_USERNAME`（`repository.url`、`homepage`、`bugs.url`）
-替换成真实用户名。
+**发布前核对**：`package.json` 里 `repository.url`、`homepage`、`bugs.url` 三处必须指向真实的 GitHub 用户名与仓库名；
+仓库改名或 fork 后要同步改这三处。
 
 ---
 
@@ -36,7 +36,7 @@
 
 在 <https://github.com/new> 建一个**空**仓库，仓库名与 `package.json` 的 `name` 一致。
 
-⚠️ **不要**勾选 "Add a README / .gitignore / license"——本地已有，勾选会导致首次推送冲突。
+⚠️ **不要**勾选 "Add a README / .gitignore / license"：本地已有，勾选会导致首次推送冲突。
 
 ### 2.2 初始化并推送
 
@@ -87,8 +87,8 @@ pnpm pack --dry-run
 
 - 第一行为 `package: dsh-workflow-map@<版本>`；
 - 含 `client.js`、`lib/`、`src/`、`index.js`、`cordis.patch.yml`、`locale/*.json`、`icon.svg`、
-  `README.md`、`CHANGELOG.md`、`LICENSE`、`docs/OPEN-SOURCE-GUIDE.md`；
-- **不含** `tools/`、`evidence/`、`*.bak*`、任何个人文档。
+  `README.md`、`CHANGELOG.md`、`LICENSE`、`docs/OPEN-SOURCE-GUIDE.md`、`docs/host-compatibility.md`；
+- **不含** `tools/`、`evidence/`、`*.bak*` 与本地草稿。
 
 `files[]` 是白名单：以**文件**（而非目录）列出，能避免整目录被连带发布。
 
@@ -168,7 +168,7 @@ node tools/probe-route.mjs            # 真实 HTTP 路由
 node tools/probe-steer.mjs            # 注入 / 撤回通道
 ```
 
-合计 **1507 条离线断言**。也可一条命令：
+合计 **1533 条离线断言**。也可一条命令：
 
 ```bash
 npm test
@@ -196,7 +196,7 @@ pwsh -File tools/measure-settings.ps1  # 设置卡与导出
 pwsh -File tools/measure-main.ps1      # 单页几何与交互
 ```
 
-合计 **308 条浏览器量测**。
+合计 **323 条浏览器量测**（0.3.4 起 `measure-main` 另含 15 条浅色/深色主题对比检查）。
 
 > `tools/retired/` 里是量「已移除界面」的历史脚本，**不属于验证链**，不期望通过。
 
@@ -248,7 +248,7 @@ dsh-workflow-map/
 ├─ client.js             生成物，禁止手改
 ├─ cordis.patch.yml      挂载声明
 ├─ locale/{zh,en}.json   词典
-├─ docs/                 本文件
+├─ docs/                 发布指南与宿主兼容性核验
 ├─ tools/                自测 · 探针 · 浏览器量测
 ├─ CHANGELOG.md
 ├─ LICENSE (MIT)

package/docs/host-compatibility.md

@@ -0,0 +1,320 @@
+# 宿主兼容性核验（DSH `0.2.1-rc.1` – `0.2.1-rc.5`）
+
+本文件回答一个问题：本插件声明的宿主范围，在 `0.2.1` 全系列（`rc.1` 至 `rc.5`）里是否真的有依据。
+
+结论以 `package.json` 的 `engines.dsh` 为唯一声明口径；本文件记录该口径的判据、核验方法与逐条证据，供使用者自行复核。
+
+---
+
+## 一、声明
+
+```json
+"engines": {
+  "node": ">=20",
+  "dsh": ">=0.2.1-rc.1 <0.3.0-0"
+}
+```
+
+区间含义：
+
+- 起点 `>=0.2.1-rc.1`：`0.2.1` 元组上的第一个预发布版本，带显式预发布标签。
+- 上界 `<0.3.0-0`：排除 `0.3.0` 及其预发布（`0.3.0-0` 是 `0.3.0` 预发布的最小值），即不声称兼容下一 minor。
+
+本插件不使用 `dsh.host` 之类的自定义元数据字段：宿主包由 `peerDependencies` 声明（均为可选 peer），版本闸门由 `engines.dsh` 单独决定。
+
+---
+
+## 二、`engines.dsh` 由谁判定：两种判据
+
+同一个区间字符串会被两套判据读取，结论不完全相同，声明必须同时满足两者。
+
+### 2.1 DSH 自身的兼容性判定
+
+`@deepseek-ai/dsh-app-boot` 的 `evaluatePluginCompatibility()` 是安装与启用期的判定入口：
+
+```js
+// @deepseek-ai/dsh-app-boot  lib/index.js:252-284（节选，省略参数校验与回落分支的具体实现）
+function satisfies(runtimeVersion, range) {
+  return range.trim() !== "" && semver.satisfies(runtimeVersion, range, { includePrerelease: true });
+}
+function unmetRequirements(fields, runtimeVersion) {
+  const engines = Object.hasOwn(fields, "engines") ? objectOf$1(fields.engines, "Plugin manifest engines") : {};
+  if (Object.hasOwn(engines, "dsh")) {
+    const range = engines.dsh;
+    if (typeof range !== "string") throw new Error("Plugin manifest engines.dsh must be a string");
+    return satisfies(runtimeVersion, range) ? {} : { "engines.dsh": range };
+  }
+  // 没有 engines.dsh 时，回落到逐个 @deepseek-ai/dsh / @deepseek-ai/dsh-* peer 的 range 判定
+}
+```
+
+`@deepseek-ai/dsh-plugin-manager` 在三个位置调用它，未满足即抛 `incompatible-version`：
+
+| 位置 | 场景 |
+|---|---|
+| `lib/types/index.js:368` | 列出 bundle 时逐个核对 |
+| `lib/types/index.js:660` | 安装（`add`）前核对 |
+| `lib/types/index.js:857` | 启用（`enable`）前核对 |
+
+同一包对外的 `requirements` 字段说明也把键名写死为 `engines.dsh`（`lib/typert.host.js:59`）：
+
+> "Only the requirements the running version does not satisfy, keyed `engines.dsh` or by DSH peer package name."
+
+### 2.2 npm / pnpm 自身的 engines 检查
+
+npm 与 pnpm 用不带 `includePrerelease` 的默认 semver 语义检查 `engines`。
+
+### 2.3 两者对同一区间的判定（semver 7.8.5 实测）
+
+| 运行时版本 | `>=0.2.1-rc.1 <0.3.0-0`（npm 默认） | 同区间（DSH 闸门，`includePrerelease`） | `>=0.1.0-rc.1 <0.3.0-0`（npm 默认） |
+|---|---|---|---|
+| `0.2.1-alpha.5` | 不通过 | 不通过 | 不通过 |
+| `0.2.1-rc.1` | 通过 | 通过 | **不通过** |
+| `0.2.1-rc.2` | 通过 | 通过 | **不通过** |
+| `0.2.1-rc.3` | 通过 | 通过 | **不通过** |
+| `0.2.1-rc.4` | 通过 | 通过 | **不通过** |
+| `0.2.1-rc.5` | 通过 | 通过 | **不通过** |
+| `0.2.1` | 通过 | 通过 | 通过 |
+| `0.2.2-rc.1` | 不通过 | 通过 | 不通过 |
+| `0.3.0-0` | 不通过 | 不通过 | 不通过 |
+| `0.3.0` | 不通过 | 不通过 | 不通过 |
+
+由此得到两个写法上的硬要求：
+
+1. **起点必须落在 `0.2.1` 元组上。** 默认 semver 只允许「与区间内某个比较符同元组」的预发布版本参与匹配；写成 `>=0.1.0-rc.1`（元组 `0.1.0`）时，`0.2.1-rc.x` 全部被判为不匹配。所以在 npm/pnpm 的默认判据下，`>=0.1.0-rc.1 <0.3.0-0` 会静默排除全部 `0.2.1` 预发布版本。
+2. **上界取 `<0.3.0-0`。** 写成 `<0.3.0` 会在 DSH 闸门（`includePrerelease`）下把 `0.3.0-rc.x` 也算作通过，与「不声称兼容下一 minor」冲突。
+
+DSH 闸门带 `includePrerelease`，因此 `0.2.2-rc.x` 这类后续 `0.2.x` 预发布也会通过。这是有意接受的结果：声明覆盖整个 `0.2.x` 预发布链，而不是逐版本列举。
+
+---
+
+## 三、逐版本核验表
+
+| 版本 | 取样方式 | 结论 |
+|---|---|---|
+| `0.2.1-rc.1` | npm 闭包元数据（206 包）+ 9 个契约点的逐文件 SHA / 锚点窗口 | 契约面与 `rc.5` 一致；闭包比 `rc.3` 少 3 个包（见 §4.3） |
+| `0.2.1-rc.2` | 同上 | 同上 |
+| `0.2.1-rc.3` | 同上 + 核验机实机运行（插件加载、面板注入、视图路由） | 基线版本 |
+| `0.2.1-rc.4` | npm 闭包元数据 + 5 个变动包逐文件 SHA + 契约锚点窗口 | 契约面无变化 |
+| `0.2.1-rc.5` | npm 闭包元数据 + 逐文件比对 + **隔离 `DSH_HOME` 实机运行**（`--dump-config` 解析、web 宿主启动、`/dsh-workflow/*` 三种端点实测，见 §3.1） | 契约面无变化，且宿主半在 `rc.5` 上实机应答 |
+
+`rc.4` 的结论来自与 `rc.3` 的逐文件比对，不是实机运行结论（见 §8）。`rc.5` 已补做隔离实机运行，记录见下节。
+
+### 3.1 `rc.5` 隔离实机运行记录（2026-10-30）
+
+核验机内核是 `rc.3`，因此不升级本机环境：在 `%TEMP%\wfmap-rc5-run\` 另起一套 `npm i @deepseek-ai/dsh@0.2.1-rc.5`，`DSH_HOME=%TEMP%\wfmap-rc5-run\home`（隔离），新 profile `wfmap5` 的 `dsh.profile.bundles` = `dsh-base` + `dsh-web-app` + `dsh-workflow-map`（后者以 `link:` 指向本仓库的工作副本，未改动源文件）。全程不写本机 `~/.dsh`、不动 `desktop` profile。
+
+**A 级 —— `rc.5` 的 loader 解析本插件 manifest 与 patch：通过**
+
+```text
+node <run>\node_modules\@deepseek-ai\dsh\lib\bin.js --profile wfmap5 --dump-config
+# 退出码 0；stdout 1234 行；stderr 0 行
+# 末尾三行即本插件层：
+#   # == dsh-workflow-map
+#   - id: workflow-map
+#     name: dsh-workflow-map
+# stdout 全文无 unknown / invalid / unresolved / warn / error 类告警
+```
+
+**B 级 —— `rc.5` 宿主上路由实机应答：通过**
+
+同一套 `rc.5` 起 web 宿主（`--profile wfmap5 --port 55999 --no-open --host 127.0.0.1`），逐端点实测（响应头均为 `content-type: application/json; charset=utf-8`，与 `src/route.js` 的契约一致）：
+
+| 请求 | 状态 | 响应体（原文） | 说明 |
+|---|---|---|---|
+| `GET /dsh-workflow/state?sessionId=none` | `404` | `{"ok":false,"error":"unknown session"}` | 前缀路由已挂上；`sessions` 服务在 `rc.5` 上可用（否则会是 503） |
+| `GET /dsh-workflow/state`（无 `sessionId`） | `400` | `{"ok":false,"error":"sessionId is required"}` | 参数校验分支 |
+| `POST /dsh-workflow/steer` | `404` | `{"ok":false,"error":"unknown session"}` | 热注入通道已挂上 |
+| `POST /dsh-workflow/unsteer` | `404` | `{"ok":false,"error":"unknown session"}` | 撤回通道已挂上 |
+| `GET /dsh-workflow/nope` | `404` | `{"ok":false,"error":"not found","path":"/dsh-workflow/state \| /dsh-workflow/steer \| /dsh-workflow/unsteer"}` | 前缀内部路由表，证明命中的是本插件的 handler，而非宿主兜底 404 |
+
+对照：同一宿主上 `GET /` 返回 `401 dsh web authentication required; reopen the URL printed by dsh web.`（`dsh-client-connection` 的页面鉴权闸门，`lib/index.js:576`），属宿主行为，不影响插件路由。
+
+**两个会把人带偏的坑（实测）**
+
+1. **系统代理会把 `127.0.0.1` 也拦走。** 本机代理 `127.0.0.1:26561` 的 `ProxyOverride` 不含 `localhost`/`127.0.0.1`，于是 `Invoke-WebRequest http://127.0.0.1:55999/...` 全部返回 **404 且空体**——看着像「插件没挂」。改用裸 socket 或 `-NoProxy` 后立刻看到 `401`（页面）与本插件的 JSON（路由）。**结论：HTTP 404 不能单独作为「路由未注册」的证据。**
+2. **`--profile <name>` 后面不能再跟 `web`。** `dsh --profile wfmap5 web` 报 `too many arguments. Expected 0 arguments but got 1: web`（`web` 是 profile 名，不是子命令）；正确写法是 `dsh --profile wfmap5 --port 55999 --no-open --host 127.0.0.1`。
+
+**复跑命令**（升级到 `rc.5` 后任选一个临时目录执行，不动本机环境）：
+
+```powershell
+$run="$env:TEMP\wfmap-rc5-run"; $env:DSH_HOME="$run\home"
+node "$run\node_modules\@deepseek-ai\dsh\lib\bin.js" --profile wfmap5 --port 55999 --no-open --host 127.0.0.1
+# 另开窗口（-NoProxy 是关键，否则会被系统代理拦成假 404）：
+Invoke-WebRequest 'http://127.0.0.1:55999/dsh-workflow/state?sessionId=none' -SkipHttpErrorCheck -NoProxy
+# 期望：404 + {"ok":false,"error":"unknown session"}
+```
+
+---
+
+## 四、闭包级别比对
+
+### 4.1 方法
+
+以 `@deepseek-ai/dsh-base` 与 `@deepseek-ai/dsh-web-app` 的依赖并集为闭包，共 **206 个包名**。对每个包从 npm registry 取 `dist.unpackedSize` 与 `dist.fileCount`，逐版本比较；任一版本组合不同即进入人工取证。
+
+用 registry 元数据做初筛、再用逐文件 SHA-256 取证，是因为元数据能覆盖全部 206 个包，而逐文件下载只对筛出的少数包做。
+
+### 4.2 差异分布
+
+206 个包中有 **24 个**在 `rc.1`–`rc.5` 之间存在差异，全部集中在三段边界上：
+
+| 变化边界 | 包数 | 包 |
+|---|---|---|
+| `rc.1 → rc.2` | 5 | `dsh-web`、`dsh-web-search-deepseek`、`dsh-web-deepseek-api`、`dsh-client-ui-deepseek-model-label-1017`、`dsh-client-ui-settings-web-search` |
+| `rc.1 → rc.2` 且 `rc.2 → rc.3` | 1 | `dsh-agent-preset` |
+| `rc.2 → rc.3` | 13 | `dsh-llm-deepseek-api-key`、`dsh-api-session-controller`、`dsh-api-remotes`、`dsh-client-ui-entry-customization`、`dsh-client-ui-plugin-manager`、`dsh-client-ui-settings-general`、`dsh-client-ui-agent-preset`、`dsh-client-ui-sidebar-right`、`dsh-client-ui-workspace`、`dsh-client-ui-sidebar`、`dsh-tool-cordis`、`dsh-web-frontend`、`dsh-client-product-analytics` |
+| `rc.2 → rc.3` 且 `rc.3 → rc.4` | 2 | `dsh-llm-deepseek-account`、`dsh-client-ui-conversation` |
+| `rc.3 → rc.4` | 1 | `dsh-mcp-resources` |
+| `rc.4 → rc.5` | 1 | `dsh-client-ui-chat` |
+| 三个边界都有 | 1 | `dsh-cordis-client-runner` |
+
+其中 `dsh-client-ui-sidebar` 与 `dsh-client-ui-conversation` 属于本插件的契约面，其锚点级比对见 §5。
+
+### 4.3 版本缺席
+
+| 包 | 缺席版本 | 说明 |
+|---|---|---|
+| `dsh-web-deepseek-api` | `rc.1` | 首次发布于 `rc.2` |
+| `dsh-client-ui-deepseek-model-label-1017` | `rc.1` | 首次发布于 `rc.2` |
+| `dsh-client-ui-entry-customization` | `rc.1`、`rc.2` | 首次发布于 `rc.3` |
+| `cordis-plugin-timer`、`schemastery` | 全部 | 第三方依赖，不随 DSH 的 `rc` 编号发布 |
+
+`rc.1` 的 profile 因此比 `rc.3` 少 3 个客户端包。这 3 个包都与本插件的契约面无关（模型标签角标、入口定制、API 通道包），缺失不影响本插件加载。
+
+### 4.4 `rc.3 → rc.5` 之间真正改动的 5 个包
+
+| 包 | `rc.3` | `rc.4` | `rc.5` | 改动文件 | 是否触及本插件契约 |
+|---|---|---|---|---|---|
+| `dsh-llm-deepseek-account` | 35661 B / 10 | 35735 B / 10 | 35735 B / 10 | `lib/index.js`、三个 README、`package.json` | 否：`lib/index.js` 只改 1 行，日志级别 `console.info` → `console.error` |
+| `dsh-mcp-resources` | 30771 B / 11 | 30844 B / 11 | 30844 B / 11 | 三个 README、`package.json` | 否：无代码改动 |
+| `dsh-client-ui-chat` | 857882 B / 106 | 同 `rc.3` | 859933 B / 107 | `lib/client.js`、3 个 `*.d.ts`、新增 `reasoning-text.d.ts`、README、`package.json` | 否：改动集中在推理正文渲染（新增 `conversation.chat.reasoning.content` 槽、`ReasoningBodyOwnerProps.text` 拆成 `rawText` + 显示文本） |
+| `dsh-client-ui-conversation` | 1130507 B / 89 | 1131117 B / 89 | 同 `rc.4` | `lib/client.js`、`locales.d.ts`、README、`package.json` | 否：92 个 bundle 分区中仅 `locales.js` 与 `skeleton/ConversationSession.js` 变化 |
+| `dsh-cordis-client-runner` | 483933 B / 20 | 同 `rc.3` | 484021 B / 20 | `lib/client.js`、`package.json` | 否：12 行变化全部是槽文档文本与 `sources` 源行号（`slots.ts:441` → `:447`） |
+
+`dsh-client-ui-conversation` 的改动按 bundle 内 `//#region` 分区逐一比对：`lib/types/client/locales.js`（词条增删）与 `lib/types/client/skeleton/ConversationSession.js`（输入框手势与文件选择绑定重构）。本插件依赖的槽注册、DOM 属性都不在这两个分区内。
+
+---
+
+## 五、契约面逐项核对
+
+本插件只依赖九个契约点。下表每个点都给出提供方、用法与 `rc.1` ↔ `rc.5` 的比对证据。
+
+| 契约点 | 提供方 | 本插件用法 | `rc.1` ↔ `rc.5` 证据 | 结论 |
+|---|---|---|---|---|
+| `sidebar.panellist` 槽 | `dsh-client-ui-sidebar` | 注册左栏面板项（`kind: 'list'`） | 槽声明在 `rc.1` 与 `rc.3` 逐字节相同：`kind: 'list'; scope: 'root'; owner: SidebarPanelIconOwnerProps` | 未变 |
+| `main` 槽 | `dsh-client-ui-layout` | 注册主内容面板（`kind: 'keyed'`） | 整包除 `package.json` 外逐文件 SHA-256 相同（`lib/client.js` = `686fb83c91c8ff8d…`） | 未变 |
+| `conversation.view` 槽 | `dsh-client-ui-conversation` | 注册会话标签栏视图 | 4 处锚点窗口（`DefaultConversationViews` 的 `renderSlot`、`apply.js` 的 `entries` / `subscribe` / `children`）在 `rc.1`/`rc.3`/`rc.4`/`rc.5` 逐字节相同 | 未变 |
+| 输入框座位 DOM | `dsh-client-ui-conversation` | 选中本插件视图时隐藏输入框 | `data-composer-seat`（1 处）、`data-conversation-content`（1 处）、`data-conversation-scroll`（3 处）的上下文窗口逐字节相同 | 未变 |
+| `sessionProjections` 服务 | `dsh-session-projection` | 注册会话投影 | `lib/index.js` SHA-256 `7dc2b212819baf4f…` 相同 | 未变 |
+| `sessions` 服务 | `dsh-session` | 按会话号取会话 | `lib/index.js` SHA-256 `2f5dd07cb5c744a2…` 相同 | 未变 |
+| `webServer` 服务 | `dsh-host-webserver` | 注册面板数据路由 | `lib/index.js` SHA-256 `08907285802f0edd…` 相同 | 未变 |
+| `agents` 服务 | `dsh-agent-loop` | 读运行中的 agent 状态 | `lib/index.js` SHA-256 `cf57e3ecd487ac5c…` 相同 | 未变 |
+| 会话事件 / JSONL 格式 | `dsh-session-persistence-jsonl` | 折叠会话事件为步骤序列 | `lib/worker.cjs` SHA-256 `4b0f235e772792d7…` 相同 | 未变 |
+
+输入框座位的实测嵌套（`dsh-client-ui-conversation` `rc.5` 的 `lib/client.js`）：
+
+```text
+div[data-conversation-content]
+└─ div[data-conversation-scroll]
+   ├─ Views            ← 选中的 conversation.view 占据位
+   └─ div[data-composer-seat]
+```
+
+本插件依赖的 DOM 只有这一条父子链与两个 `data-*` 属性，不依赖 class 名或内部组件。
+
+§4.2 表里其余 22 个变动包与本插件的九个契约点没有交集：不注册 `conversation.chat.*` 系列槽、不读设置页组件、不调用搜索工具、不依赖 API 网关包。
+
+---
+
+## 六、安装闸门生效性
+
+结论：`engines.dsh` 不是装饰性字段，安装与启用期都会被读取。
+
+| 环节 | 证据 |
+|---|---|
+| 判定实现 | `dsh-app-boot` 的 `evaluatePluginCompatibility()` → `unmetRequirements()`（§2.1 引文） |
+| 判定实现版本一致 | `dsh-app-boot` `rc.1` 与 `rc.5` 除 `package.json` 外逐文件 SHA-256 相同（`lib/index.js` = `5135179ac810e4f6…`） |
+| 安装期调用 | `dsh-plugin-manager` 三处调用（§2.1 表），未满足抛 `incompatible-version`，并在 `requirements` 里给出 `engines.dsh` 键 |
+| 调用方版本一致 | `dsh-plugin-manager` `rc.3` 与 `rc.5` 除 `package.json` 外逐文件 SHA-256 相同 |
+
+由此可推出两条可验证的后果：
+
+1. 在 `0.2.1-rc.1`–`0.2.1-rc.5` 任一内核上安装或启用，本插件的 `engines.dsh` 判定通过，不会有 `incompatible-version`。
+2. 在 `0.3.0` 及以后的内核上，`engines.dsh` 判定不通过（§2.3），安装或启用会被上述任一调用点拦下并给出明确的 `engines.dsh: ">=0.2.1-rc.1 <0.3.0-0"` 说明。这属于预期行为：不兼容时应显式失败，而不是勉强加载。
+
+---
+
+## 七、可复跑命令
+以下命令只需 Node.js 20 以上。前两条只需 npm registry 访问；第三条需要环境里能解析到 `semver`（`npm i semver`，或使用 DSH 安装目录自带的副本）。
+
+**1) 闭包元数据对比（206 包 × 5 个版本）**
+
+```bash
+node -e '
+const { readFileSync } = require("node:fs");
+const names = readFileSync("closure-names.txt", "utf8").split(/\r?\n/).filter(Boolean);
+const V = ["0.2.1-rc.1","0.2.1-rc.2","0.2.1-rc.3","0.2.1-rc.4","0.2.1-rc.5"];
+let i = 0; const rows = [];
+(async () => {
+  await Promise.all(Array.from({ length: 8 }, async () => {
+    while (i < names.length) {
+      const name = names[i++];
+      const p = await (await fetch("https://registry.npmjs.org/" + name.replace("/", "%2f"))).json();
+      const pick = (v) => { const d = p.versions?.[v]?.dist; return d ? [d.unpackedSize, d.fileCount] : null; };
+      const row = V.map((v) => JSON.stringify(pick(v)));
+      if (new Set(row).size > 1) rows.push({ name, row });
+    }
+  }));
+  console.log(rows.length, JSON.stringify(rows, null, 1));
+})();
+'
+```
+
+`closure-names.txt` 是 `dsh-base` 与 `dsh-web-app` 依赖并集的包名清单（每行一个）。换用别的清单会得到别的闭包，比较结果随之变化。
+
+**2) 单包逐文件 SHA-256 比对**
+
+```bash
+# 取两个版本的 tarball，解包后逐文件比对
+npm pack @deepseek-ai/dsh-session-projection@0.2.1-rc.1
+npm pack @deepseek-ai/dsh-session-projection@0.2.1-rc.5
+tar -xzf deepseek-ai-dsh-session-projection-0.2.1-rc.1.tgz -C rc1
+tar -xzf deepseek-ai-dsh-session-projection-0.2.1-rc.5.tgz -C rc5
+diff -r rc1/package rc5/package   # 期望：仅 package.json 不同
+```
+
+**3) 区间判定矩阵**
+
+```bash
+node -e '
+const semver = require("semver");
+const ranges = [">=0.2.1-rc.1 <0.3.0-0", ">=0.1.0-rc.1 <0.3.0-0"];
+const versions = ["0.2.1-alpha.5","0.2.1-rc.1","0.2.1-rc.5","0.2.1","0.2.2-rc.1","0.3.0-0","0.3.0"];
+for (const r of ranges) console.log(r, versions.map((v) => [v, semver.satisfies(v, r), semver.satisfies(v, r, { includePrerelease: true })]));
+'
+```
+
+---
+
+## 八、限制声明
+
+- **动态核验范围**：截至 2026-10-30，`0.2.1-rc.3` 是本机实机运行版本；`0.2.1-rc.5` 已在隔离 `DSH_HOME` 的临时区实机启动并实测路由应答（§3.1），但不覆盖「真实会话内的投影内容」——`rc.5` 上没有跑过带会话的完整回合，`/state` 只验到「按契约返回 `unknown session`」。`rc.4` 仍只做了静态比对（闭包元数据、逐文件 SHA-256、契约锚点窗口），未实机启动。
+- **比对对象**：只比对 npm 上已发布的产物，不覆盖未发布的仓库提交。
+- **闭包口径**：206 个包名按 `dsh-base` 与 `dsh-web-app` 的依赖并集确定；更换清单会改变闭包边界。
+- **第三方依赖**：闭包内含 `cordis`、`schemastery`、`zod` 等第三方包，它们不随 DSH 的 `rc` 编号发布，本文件不对其版本承诺做任何声明。
+- **上界外版本**：`0.3.0` 及以后未做任何核验，声明上也不覆盖。
+- **判定语义**：§2.3 的矩阵来自 semver 7.8.5；换用其他实现时 `includePrerelease` 的细节可能不同。
+
+---
+
+## 九、复核记录
+
+| 项 | 取值 |
+|---|---|
+| 复核日期 | 2026-10-30 |
+| 数据来源 | `registry.npmjs.org` 发布产物 |
+| semver 实现 | 7.8.5（`satisfies`，分别带与不带 `includePrerelease`） |
+| 闭包规模 | 206 个包名，24 个存在版本间差异 |
+| 逐文件比对包 | `dsh-app-boot`、`dsh-session`、`dsh-session-projection`、`dsh-host-webserver`、`dsh-agent-loop`、`dsh-session-persistence-jsonl`、`dsh-plugin-manager`、`dsh-client-ui-layout`、`dsh-client-ui-sidebar`、`dsh-client-ui-conversation`、`dsh-client-ui-chat`、`dsh-cordis-client-runner`、`dsh-llm-deepseek-account`、`dsh-mcp-resources` |
+| 实机运行内核 | `0.2.1-rc.3`（本机内核）；`0.2.1-rc.5`（隔离 `DSH_HOME` 临时区，仅路由与 loader 层） |

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "dsh-workflow-map",
-  "version": "0.3.2",
-  "description": "工作流地图插件（DeepSeek Harness bundle）：在会话标签栏、左栏菜单与主内容区以同一份面板展示当前会话的分步总览、每步的工具/文件类型明细、唯一彩色流光进度条，并支持热注入（steer）与「需确认」标注。宿主半折叠会话事件并读取 PAE 计划，经本地 HTTP 视图供数据；浏览器半渲染面板。",
+  "version": "0.3.4",
+  "description": "把当前会话渲染成一张可交互的分步工作流地图：会话标签栏、左栏菜单与主内容区共用同一份面板，逐步显示状态、工具与文件类型明细、进度条，并支持热注入（steer）与「需确认」标注。宿主半折叠会话事件、读取按步执行（PAE）计划，经本地 HTTP 视图供数据；浏览器半渲染面板。",
   "private": false,
   "type": "module",
   "license": "MIT",
   "keywords": [
     "deepseek-harness",
+    "deepseek-harness-plugin",
     "dsh",
+    "dsh-0.2.1",
     "cordis",
     "plugin",
     "bundle",
@@ -24,7 +26,20 @@
     "url": "https://github.com/Joz739/dsh-workflow-map/issues"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20",
+    "dsh": ">=0.2.1-rc.1 <0.3.0-0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent-loop": ">=0.2.1-rc.1 <0.3.0-0",
+    "@deepseek-ai/dsh-llm": ">=0.2.1-rc.1 <0.3.0-0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-agent-loop": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    }
   },
   "exports": {
     ".": "./index.js",
@@ -45,6 +60,7 @@
     "CHANGELOG.md",
     "LICENSE",
     "docs/OPEN-SOURCE-GUIDE.md",
+    "docs/host-compatibility.md",
     "docs/screenshot.png",
     "docs/screenshot-detail.png",
     "package.json"

package/src/client/ProgressUnder.js

@@ -24,7 +24,7 @@
  * "0 seconds ago" would be a fabricated number, which is exactly what this plugin
  * refuses to print.
  *
- * (2026-10-26) · the projected REMAINING half is GONE by user request. It used to be shipped
+ * The projected REMAINING half is no longer part of this rail. It used to be shipped
  * by the host as a derived millisecond field (median of the finished steps, hard-bounded) and
  * rendered as "remaining ~N minutes"; the host no longer computes it and this rail no longer renders it.
  * One line, one fact, no consumer-less field — and a payload that still carries that field (an

package/src/client/theme.js

@@ -169,7 +169,15 @@ var WF_CSS = [
  // the three branch hues live on the ROOT, so the dashed branches and their round
  // icons share one palette with the rest of the panel (and one place to change it).
     "--wf-chain-read:#5b8cff;--wf-chain-edit:#e0a13a;--wf-chain-tool:#8f7bea;" +
+  // `--dsw-alias-bg-layer-1` and `-2` carry the SAME value in the host's light theme (both
+  // neutral-bluish-00, i.e. #fff), so a card filled with layer-2 is invisible on the page. Every
+  // raised surface in the panel therefore paints one translucent lift over that fill. The lift goes
+  // towards ink on a light page and towards white on a dark one; the host marks dark by putting
+  // `data-ds-dark-theme` on <body>, so the light values are the defaults and the dark block below
+  // only wins when that attribute is present.
+    "--wf-lift:rgba(15,23,42,.045);--wf-lift-2:rgba(15,23,42,.085);" +
     "font-family:ui-sans-serif,system-ui,-apple-system,'Segoe UI','Microsoft YaHei',sans-serif;font-size:12px;line-height:1.5}",
+  "body[data-ds-dark-theme] .wf-root{--wf-lift:rgba(255,255,255,.035);--wf-lift-2:rgba(255,255,255,.07)}",
 
  /* card: fills the main area; the header and the settings card keep their own height,
      the two-column body takes the rest. No drag grips: the column has no free edges.
@@ -252,13 +260,14 @@ var WF_CSS = [
  // `grid-area:1/1` is what makes the triangle and the card share the cell: without it the
  // auto-placement cursor would drop the card into row 2, below the triangle.
   ".wf-step-card{grid-area:1/1;display:flex;gap:8px;align-items:flex-start;width:100%;padding:7px 8px;border-radius:8px;text-align:left;" +
-    "font:inherit;color:inherit;cursor:pointer;border:1px solid transparent;" +
-    "background:var(--dsw-alias-bg-layer-2,#282d3a);border-left:3px solid transparent}",
+    "font:inherit;color:inherit;cursor:pointer;border:1px solid var(--dsw-alias-border-l2,rgba(255,255,255,.22));" +
+    "background:var(--dsw-alias-bg-layer-2,#282d3a);background-image:linear-gradient(var(--wf-lift),var(--wf-lift));" +
+    "border-left:3px solid transparent}",
   ".wf-step-card:hover{border-color:var(--dsw-alias-border-l2,rgba(255,255,255,.22));" +
-    "background:var(--dsw-alias-bg-layer-1,#232733)}",
+    "background:var(--dsw-alias-bg-layer-1,#232733);background-image:linear-gradient(var(--wf-lift-2),var(--wf-lift-2))}",
   ".wf-step-card:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5b8cff);outline-offset:1px}",
   ".wf-step-card[data-selected='true']{border-color:var(--dsw-alias-brand-primary,#5b8cff);" +
-    "background:var(--dsw-alias-bg-layer-1,#232733)}",
+    "background:var(--dsw-alias-bg-layer-1,#232733);background-image:linear-gradient(var(--wf-lift-2),var(--wf-lift-2))}",
   ".wf-step-card[data-active='true']{border-left-color:var(--dsw-alias-brand-primary,#5b8cff)}",
   ".wf-step-ring{flex:0 0 auto;width:18px;height:18px;margin-top:1px;border-radius:50%;" +
     "display:inline-flex;align-items:center;justify-content:center;font-size:11px;line-height:1;" +
@@ -412,7 +421,7 @@ var WF_CSS = [
   ".wf-branch-icon{flex:0 0 auto;width:" + WF_CHAIN_ICON + "px;height:" + WF_CHAIN_ICON + "px;padding:0;" +
     "border-radius:50%;display:inline-flex;align-items:center;justify-content:center;" +
     "font:inherit;font-size:11px;line-height:1;cursor:pointer;position:relative;" +
-    "background:var(--dsw-alias-bg-layer-2,#282d3a);color:var(--dsw-alias-label-secondary,#9aa3b2);" +
+    "background:var(--dsw-alias-bg-layer-2,#282d3a);background-image:linear-gradient(var(--wf-lift),var(--wf-lift));color:var(--dsw-alias-label-secondary,#9aa3b2);" +
     "border:1px solid var(--dsw-alias-border-l2,rgba(255,255,255,.28))}",
   ".wf-branch-icon:hover{color:var(--dsw-alias-label-primary,#e9ecf3)}",
   ".wf-branch-icon:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5b8cff);outline-offset:2px}",
@@ -442,12 +451,14 @@ var WF_CSS = [
  /* node card: icon · title · meta · status dot */
   ".wf-node{display:flex;gap:7px;align-items:flex-start;width:100%;padding:6px 8px;border-radius:8px;" +
     "text-align:left;font:inherit;color:inherit;cursor:pointer;" +
-    "background:var(--dsw-alias-bg-layer-2,#282d3a);border:1px solid transparent;" +
+    "background:var(--dsw-alias-bg-layer-2,#282d3a);background-image:linear-gradient(var(--wf-lift),var(--wf-lift));" +
+    "border:1px solid var(--dsw-alias-border-l2,rgba(255,255,255,.22));" +
     "border-left:3px solid var(--dsw-alias-border-l2,rgba(255,255,255,.2))}",
-  ".wf-node:hover{border-color:var(--dsw-alias-border-l2,rgba(255,255,255,.24));background:var(--dsw-alias-bg-layer-1,#232733)}",
+  ".wf-node:hover{border-color:var(--dsw-alias-border-l2,rgba(255,255,255,.24));" +
+    "background:var(--dsw-alias-bg-layer-1,#232733);background-image:linear-gradient(var(--wf-lift-2),var(--wf-lift-2))}",
   ".wf-node:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5b8cff);outline-offset:1px}",
   ".wf-node[data-selected='true']{border-color:var(--dsw-alias-brand-primary,#5b8cff);" +
-    "background:var(--dsw-alias-bg-layer-1,#232733)}",
+    "background:var(--dsw-alias-bg-layer-1,#232733);background-image:linear-gradient(var(--wf-lift-2),var(--wf-lift-2))}",
   ".wf-node[data-selected='true'] .wf-node-title{font-weight:600}",
   ".wf-node[data-kind='tool']{border-left-color:var(--dsw-alias-brand-primary,#5b8cff)}",
   ".wf-node[data-kind='report']{border-left-color:var(--dsw-alias-state-success-primary,#45c07a)}",
@@ -1024,11 +1035,12 @@ var WF_CSS_PAGE = [
 
  /* ---- the unit card ---- */
   ".wf-unit-card{display:grid;grid-template-columns:auto auto minmax(0,1fr);align-items:flex-start;gap:8px;" +
-    "width:100%;padding:10px 12px;border-radius:10px;text-align:left;border:1px solid transparent;" +
-    "background:var(--dsw-alias-bg-layer-2,#282d3a);color:inherit;font:inherit;cursor:pointer;" +
+    "width:100%;padding:10px 12px;border-radius:10px;text-align:left;border:1px solid var(--dsw-alias-border-l2,rgba(255,255,255,.22));" +
+    "background:var(--dsw-alias-bg-layer-2,#282d3a);background-image:linear-gradient(var(--wf-lift),var(--wf-lift));" +
+    "color:inherit;font:inherit;cursor:pointer;" +
     "border-left:3px solid transparent;box-sizing:border-box}",
   ".wf-unit-card:hover{border-color:var(--dsw-alias-border-l2,rgba(255,255,255,.22));" +
-    "background:var(--dsw-alias-bg-layer-1,#232733)}",
+    "background:var(--dsw-alias-bg-layer-1,#232733);background-image:linear-gradient(var(--wf-lift-2),var(--wf-lift-2))}",
   ".wf-unit-card:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5b8cff);outline-offset:1px}",
   ".wf-unit-card[data-selected='true']{border-color:var(--dsw-alias-brand-primary,#5b8cff)}",
   ".wf-unit-card[data-active='true']{border-left-color:var(--dsw-alias-brand-primary,#5b8cff)}",

package/src/fold.mjs

@@ -63,7 +63,12 @@
 // own `inboxProjectionDefinition` replays. A checkpoint written before this bump has no ledger,
 // so the registry is told to drop it and rebuild from the log (the same contract as v1→v2: a
 // missing field must never be silently answered with a wrong index).
-export const STATE_VERSION = 3;
+//
+// STATE_VERSION 4 : the step ledger now follows the todo table's own statuses (a `pending` row
+// demotes a step that still carried `done`/`running`, and a step any table no longer names is
+// dropped). Checkpoints written before the bump hold ledgers from the older mapping — wrong
+// statuses and leftover rows — so the same contract applies: drop and rebuild from the log.
+export const STATE_VERSION = 4;
 
 export const SCHEMA_VERSION = 1;
 
@@ -515,6 +520,13 @@ function percentFor(state, step, now) {
     const pinned = step.percent === null ? 100 : step.percent;
     return { percent: clamp(pinned, 0, 100), source: step.percentSource === "none" ? "closed" : step.percentSource };
   }
+  // Only the step that is actually running can be partly done. A pending row is future work and a
+  // skipped one never will be done, so NEITHER carries a number. The old code let the todo table's
+  // completion ratio paint a bar on every waiting row as well, which is where the wall of bars
+  // below 100 % in an already finished session came from.
+  if (step.status !== STEP_STATUS.running) {
+    return { percent: null, source: "none" };
+  }
   // Priority 2 when a self-report exists: the todo table's completion ratio is a measurement (no
   // clock, no extrapolation), so it determines the number whenever it has rows to report on.
   // The self-report can only lower the result, never raise it above the measured ratio.
@@ -752,12 +764,22 @@ function foldTodos(state, event, time) {
   // session (no PAE plan at all) still produces a step list.
   let steps = [...state.steps];
   let durations = state.durations;
+  // Every row that matched an existing step, and the status that row states. The table is the one
+  // authority on a step's lifecycle, so these are applied in a final pass instead of inline: a row
+  // can match a step that a LATER row also matches (slot reuse after the model rewrites the table),
+  // and an inline write could then be overwritten by a stale copy of the old status.
+  const authority = new Map();
+  // The ledger as it stood BEFORE this table. Slot binding has to read this snapshot: by the time a
+  // later row is examined, `steps` already holds the rows this very table created, so "the row in
+  // this position" would point at a row from the NEW table instead of the one being replaced.
+  const prior = state.steps;
 
   for (const item of todos) {
     if (item.content === "") continue;
     const planIndex = planIndexOf(item.content);
     let at = planIndex === null ? -1 : steps.findIndex((step) => step.planIndex === planIndex);
     if (at === -1) at = steps.findIndex((step) => normalizeTitle(step.title) === normalizeTitle(item.content));
+    const matchedByTitle = at !== -1;
     // REWORDED ROW at the source. The model often rewrites its own todo text between two
     // `todo/write` events (measured: "read-only inventory: read plugin sources..." -> "read-only inventory: sources/config..."). Matching on the
     // title alone then misses the row that already exists, a SECOND row is created for the new
@@ -765,8 +787,13 @@ function foldTodos(state, event, time) {
     // sync then drops. That was "only the running step shows tool types". The fix belongs HERE:
     // reword in place when the slot and lifecycle agree, so the row keeps its ledger.
     if (at === -1) {
-      const slotRow = steps[steps.length > todos.indexOf(item) ? todos.indexOf(item) : -1];
-      const sameSlot = slotRow && (slotRow.status === item.status || slotRow.status === STEP_STATUS.running);
+      const slotRow = prior[todos.indexOf(item)];
+      // A running step is never taken over by a row that is not running: that is how a pending row
+      // used to hijack the live step and leave the real one with no running row at all.
+      const sameSlot =
+        slotRow &&
+        (slotRow.status === item.status ||
+          (slotRow.status === STEP_STATUS.running && item.status === "in_progress"));
       if (sameSlot) at = steps.indexOf(slotRow);
     }
 
@@ -796,6 +823,12 @@ function foldTodos(state, event, time) {
     // its old key, so the nodes it already owns can follow the rename. Both the rename and the
     // lifecycle change are applied in one assignment, so neither can lose the other.
     let next = step;
+    // The row's ordinal follows the TABLE, not the row's history. A matched row that used to be
+    // unnumbered (or numbered differently) must take the ordinal this table now states, or the
+    // view keeps a stale planIndex and `applyPlanToView` patches the wrong plan step onto it.
+    // Measured 2026-10-29 on session 164e339f: leftover unnumbered rows kept planIndex 2 / 3 /
+    // 4... from an earlier PAE plan and the map rendered plan steps 3-7 twice.
+    if (planIndex !== null && next.planIndex !== planIndex) next = { ...next, planIndex };
     const shown = text(stripOrdinal(item.content) || item.content, TITLE_LIMIT);
     const shownKey = normalizeTitle(shown);
     if (shownKey !== "" && shownKey !== next.stepKey) {
@@ -815,8 +848,40 @@ function foldTodos(state, event, time) {
     } else if (next !== step) {
       steps[at] = next;
     }
+    authority.set(at, { status: item.status, byTitle: matchedByTitle });
   }
 
+  // The final pass: one status per step, exactly as the table now states it. `pending` is a real
+  // state — a row the model has not started — and a step that still carried `done` or `running`
+  // from the previous wording of the table has to be demoted, or the panel shows finished work the
+  // table does not claim (and a bar at 100 % next to an empty todo). Demotion is only safe when the
+  // row matched on its own title; a slot match after a reword could hit a different row's step.
+  for (const [at, claim] of authority) {
+    const step = steps[at];
+    if (!step) continue;
+    if (claim.status === "completed" && step.status !== STEP_STATUS.done) {
+      if (step.startedAt > 0) durations = [...durations, time - step.startedAt].filter((value) => value > 0);
+      steps[at] = closeStep(step, time);
+    } else if (claim.status === "in_progress" && step.status !== STEP_STATUS.running) {
+      steps[at] = { ...step, status: STEP_STATUS.running, endedAt: null, startedAt: step.startedAt || time };
+    } else if (claim.status === "pending" && step.status !== STEP_STATUS.pending) {
+      steps[at] = { ...step, status: STEP_STATUS.pending, endedAt: null, startedAt: 0, percent: null, percentSource: "none" };
+    }
+  }
+
+  // A row the table no longer names, that never started and owns no node, is the leftover of an
+  // earlier wording of the same list. Keeping it leaves a permanently empty card in the step
+  // column, which is how every rewritten table used to grow the panel by one or two rows.
+  const named = new Set(todos.map((item) => normalizeTitle(item.content)).filter((key) => key !== ""));
+  const nodeKeys = new Set(state.nodes.map((node) => node.stepKey));
+  const kept = steps.filter((step) => {
+    if (step.status !== STEP_STATUS.pending || step.startedAt > 0) return true;
+    const keys = [step.stepKey, ...(Array.isArray(step.aliasKeys) ? step.aliasKeys : [])].filter(Boolean);
+    if (keys.some((key) => nodeKeys.has(key))) return true;
+    return keys.some((key) => named.has(key));
+  });
+  if (kept.length !== steps.length) steps = kept;
+
 
   return { ...state, asOf: time, todos, steps: reindex(steps), durations };
 }
@@ -1134,7 +1199,14 @@ function parsePlanRows(blockText) {
   for (const raw of blockText.split("\n")) {
     const match = /^\s*(\d+)\.\s*(.+)$/.exec(raw);
     if (!match) continue;
-    rows.push({ planIndex: Number(match[1]), title: text(match[2], TITLE_LIMIT) });
+    // PAE appends each row's own step FILE to the title ("1. title（…）（step-01-x.md）"). That
+    // annotation is not title text: keeping it leaves `normalizeTitle` one parenthetical group short
+    // of the todo row the model writes ("1. title（…）"), so a plan step can carry a title that no
+    // row of the todo table has. Measured 2026-10-30 on session 1bb4baa0: the fold opened step 1 with
+    // the annotated title while its `stepKey` still held the table's wording, `foldTodos` therefore
+    // saw "no change" and the view kept a step the conversation does not list (audit-real ①).
+    const title = match[2].replace(/\s*[（(][^（()）]*\.(?:md|markdown|mjs|cjs|js|json|ya?ml|txt)[）)]\s*$/, "");
+    rows.push({ planIndex: Number(match[1]), title: text(title, TITLE_LIMIT) });
     if (rows.length >= 80) break;
   }
   return rows;
@@ -1195,10 +1267,26 @@ function openPlanStep(state, time, seq, planIndex, title, blockText) {
     steps.push(created);
   } else {
     const step = steps[targetAt];
+    // A plan title must not replace the row's identity key on its own: `stepKey` is what `foldTodos`
+    // compares the live table against and what node attribution follows. Adopting a title without its
+    // key left the pair inconsistent, so the next todo/write judged the row unchanged and a stale
+    // title survived into the view (measured 2026-10-30, session 1bb4baa0). The old key is parked in
+    // `aliasKeys` exactly as a rename does, so nodes already carrying it still migrate.
+    const adopted = title || step.title;
+    const adoptedKey = normalizeTitle(adopted);
+    const renamed = adoptedKey !== "" && adoptedKey !== step.stepKey;
+    const seenKeys = Array.isArray(step.aliasKeys) ? step.aliasKeys : [];
     steps[targetAt] = {
       ...step,
       planIndex,
-      title: title || step.title,
+      title: adopted,
+      ...(renamed
+        ? {
+            prevKey: step.stepKey,
+            stepKey: adoptedKey,
+            aliasKeys: [...new Set([...seenKeys, step.stepKey, adoptedKey])].filter((key) => key !== ""),
+          }
+        : {}),
       anchorSeq: step.anchorSeq === undefined ? anchorOf(state, planIndex, seq) : step.anchorSeq,
       status: STEP_STATUS.running,
       endedAt: null,
@@ -1261,7 +1349,20 @@ function foldTurnStart(state, _event, time) {
 }
 
 function foldTurnEnd(state, _event, time) {
-  return { ...state, asOf: time, turnActive: false };
+  const next = { ...state, asOf: time, turnActive: false };
+  // The turn is over, so the step it was running is over too. Leaving it `running` kept a live,
+  // forever-partial bar on the last step of every finished session.
+  // The one exception is a step the todo table still names as its `in_progress` row: that step
+  // really does continue into the next turn, and closing it here would make the next turn reopen
+  // a step that never stopped.
+  const running = runningStep(next);
+  if (!running) return next;
+  const inProgress = inProgressStepIndex(next);
+  if (isFiniteNumber(inProgress) && inProgress === running.index) return next;
+  const durations =
+    running.startedAt > 0 ? [...next.durations, time - running.startedAt].filter((value) => value > 0) : next.durations;
+  const steps = next.steps.map((step) => (step.index === running.index ? closeStep(step, time) : step));
+  return withPercents({ ...next, steps, durations }, time);
 }
 
 function foldReport(state, event, time) {
@@ -2341,9 +2442,27 @@ function syncToTodos(state) {
     const key = normalizeTitle(item.content);
     if (key === "" || seen.has(key)) continue;
     seen.add(key);
-    wanted.push({ key, title, status: item.status });
+    // `planIndex` MUST be parsed from the RAW content, not from `title`: `stripOrdinal`
+    // already removed the "3." prefix, so `planIndexOf(title)` always returned null and every
+    // created row lost its ordinal. Measured 2026-10-29 on session 164e339f: a 14-row numbered
+    // table produced rows whose planIndex fell back to POSITION, so row 9 ("9. n8n 主工作流…")
+    // was stamped planIndex 2 and `applyPlanToView` then rewrote it with plan step 2's title and
+    // status — the map showed steps 3–7 twice and the wrong step as running.
+    wanted.push({ key, title, status: item.status, planIndex: planIndexOf(item.content) });
   }
   if (wanted.length === 0) return state;
+  // The row's status is the ONE statement of a step's lifecycle: `todo/write` replaces the whole
+  // table every time, so a matched row must not inherit the status of whatever record the matcher
+  // bound it to. Without this pass a row the model has not started kept the `done` of an old record
+  // (a card at 100 % next to an empty todo), while an `in_progress` row showed as `pending` because
+  // the record it landed on was still pending — both seen in one session on 2026-10-30.
+  const rowStatus = (step, row) => {
+    if (row.status === "completed") return step.status === STEP_STATUS.done ? step : closeStep(step, state.asOf || 0);
+    if (row.status === "in_progress") {
+      return { ...step, status: STEP_STATUS.running, endedAt: null, startedAt: step.startedAt || state.asOf || 0 };
+    }
+    return { ...step, status: STEP_STATUS.pending, endedAt: null, startedAt: 0, percent: null, percentSource: "none" };
+  };
 
   const byKey = new Map();
   for (const step of state.steps) {
@@ -2390,14 +2509,30 @@ function syncToTodos(state) {
     // (2) TEXT SHARE as the fallback for a re-numbered or re-ordered table.
     let candidate = null;
     const slot = wanted.indexOf(row);
-    const sameSlot = orphans.find((step) => !used.has(step.index) && step.index === slot);
+    // An explicit ordinal OUTRANKS position. A numbered table states which plan step each row
+    // IS; letting the slot win anyway pairs row 9 with whatever orphan happens to sit at
+    // position 8, and the row inherits that orphan's planIndex. Measured 2026-10-29 on session
+    // 164e339f: after a 7-row unnumbered table was replaced by a 14-row numbered one, row 9
+    // took the leftover row 2 and the map rendered plan steps 3-7 twice.
+    const ordinalConflict = (step) =>
+      row.planIndex !== null && Number.isInteger(step.planIndex) && step.planIndex !== row.planIndex;
+    const sameSlot = orphans.find(
+      (step) => !used.has(step.index) && step.index === slot && !ordinalConflict(step),
+    );
     if (sameSlot && (sameSlot.status === row.status || sameSlot.status === STEP_STATUS.running)) {
       candidate = sameSlot;
     }
+    if (candidate === null && row.planIndex !== null) {
+      const byOrdinal = orphans.find(
+        (step) => !used.has(step.index) && Number.isInteger(step.planIndex) && step.planIndex === row.planIndex,
+      );
+      if (byOrdinal) candidate = byOrdinal;
+    }
     if (candidate === null) {
       let bestShare = 0;
       for (const step of orphans) {
         if (used.has(step.index)) continue;
+        if (ordinalConflict(step)) continue;
         const other = normalizeTitle(step.title);
         const score = commonPrefix(other, row.key);
         if (score < REWORD_PREFIX_MIN) continue;
@@ -2417,7 +2552,7 @@ function syncToTodos(state) {
       // reworded title - the two did not match, so the nodes were dropped as orphans in the view.
       const oldKey = candidate.stepKey || normalizeTitle(candidate.title);
       const newKey = normalizeTitle(row.title);
-      const nextStep = { ...candidate, title: text(row.title, TITLE_LIMIT), stepKey: newKey };
+      const nextStep = rowStatus({ ...candidate, title: text(row.title, TITLE_LIMIT), stepKey: newKey }, row);
       reworded.set(oldKey, newKey);
       ordered.push(nextStep);
       origins.push(candidate.index);
@@ -2430,13 +2565,8 @@ function syncToTodos(state) {
     // node-remap nor the node attribution can ever find it.
     created.stepKey = row.key;
     created.startedAt = 0;
-    created.planIndex = planIndexOf(row.title) ?? undefined;
-    created.status = row.status === "completed" ? STEP_STATUS.done : STEP_STATUS.pending;
-    if (created.status === STEP_STATUS.done) {
-      created.percent = 100;
-      created.percentSource = "closed";
-      created.maxPercent = 100;
-    }
+    created.planIndex = row.planIndex ?? undefined;
+    Object.assign(created, rowStatus(created, row));
     ordered.push(created);
     origins.push(-1);
   }

package/src/orchestrator.mjs

@@ -300,6 +300,24 @@ export function applyPlanToView(view, plan) {
         }
       }
     }
+    // The plan's own `requiresConfirmation` is the OTHER half of the needs-confirmation flag:
+    // `buildView` derives the log half (an open approval, an unanswered question), and this
+    // adds the plan half. It belongs HERE because this is the only place that has both the
+    // normalised plan step and the view row it lands on. Measured 2026-10-29 on session
+    // 164e339f: plan steps 2 / 12 / 13 carry requiresConfirmation and the map showed none of
+    // them, while `pendingConfirmSteps` in fold.mjs only ever consulted the log.
+    //
+    // A finished step never carries the flag (the same rule `buildView` applies): a decision a
+    // done step was waiting on is history, not a request.
+    if (planStep.requiresConfirmation === true && step.status !== "done" && step.status !== "failed") {
+      const rows = Array.isArray(step.pendingConfirm) ? step.pendingConfirm : [];
+      if (!rows.some((row) => isRecord(row) && row.kind === "plan")) {
+        patch.pendingConfirm = [
+          ...rows,
+          { kind: "plan", label: planStep.title !== "" ? planStep.title : `第 ${planStep.index} 步`, at: 0 },
+        ];
+      }
+    }
     if (Object.keys(patch).length === 0) continue;
     steps[position] = { ...step, ...patch };
     changed = true;