dsh-workflow-map 0.0.0-stage → 0.3.4

package/CHANGELOG.md

@@ -0,0 +1,184 @@
+# Changelog
+
+`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
+
+- **`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`），
+  三处一并跟随 `--wf-soft-1` / `--wf-soft-2`。
+- 对应的浏览器量测从「记录缺陷」改为「断言修复」：`settings.soft.keepsRainbowRing`
+  换成 `settings.soft.frameMigrated` 与 `settings.soft.ringColor`，两者都用期望色
+  `rgb(127, 147, 184)` 比对；同一份期望里也存了它的十六进制写法 `#7f93b8`。
+
+### Changed
+
+- `docs/screenshot.png`（1400×900）与 `docs/screenshot-detail.png`（1500×950）
+  用当前代码重新渲染，替换为修复后的界面。
+
+### Tests
+
+- 离线自测 **10 套 / 1507 条断言**、浏览器量测 **10 套 / 308 条断言**，全部通过。
+
+### Notes
+
+- 仅改浏览器半（`src/client/*.js` 与重建的 `client.js`）与文档，**宿主半未改动**：
+  升级后 **F5 刷新页面**即可，不需要重启 DSH 进程。
+
+## [0.3.0] - 2026-10-27
+
+首个公开发布版本。相比内部迭代期，这一版把面板从「开发中的实验界面」收敛成可日常使用的形态。
+
+### Added
+
+- **热注入的完整撤回链路**：历史行在「待会话拾取」状态时出现「撤回」按钮，走 `POST /dsh-workflow/unsteer`
+  → 宿主的 `agent.inbox.remove(messageId)`；`/steer` 的响应同时带回它写下的 `messageId`。
+  撤回后刷新页面状态依然正确：折叠会重放宿主的收件箱变动（`agent/inbox/spliced` 记录的是**位置**，
+  所以需要维护一份收件箱台账才能定位到具体是哪一行）。旧检查点按契约丢弃重建。
+- **会话标签栏入口**：在会话区顶部标签栏新增一个席位，与左栏图标、主内容区共用同一份面板、
+  同一份轮询、同一份设置。
+- **热注入入口常驻化**：页头入口改为醒目的品牌色按钮；右页注入器底部新增可回车直发的常驻输入条，
+  不必先展开面板才能发。
+- **进度估算的诚实化**：只要待办清单有已完成行，百分比就取该实测比值，模型自报不再参与显示值计算
+  （自报仅作为无实测行时的备选）；时间基线冷启动时改用计划自身的步序推算，避免首个进行中的步只剩一条空流光。
+
+### Fixed
+
+- **多个分步同时显示为「进行中」**：折叠时取「第一个 running 行」，而规划阶段的合成步要等到
+  计划开启才收尾，导致它长期占用 running 状态、后续每一步再叠一个。现在每个折叠事件后
+  收敛为唯一 running 行；进度上报也归属到待办表里真正 `in_progress` 的那一行。
+- **地图分步与对话里的待办表不一致**：折叠只增不删，重新规划或改写标题后旧行会残留。
+  现在视图严格按最新待办表产出分步，表里已不存在的行与其节点一并移除。
+- **已完成的步显示「0 工具 0 文件」**：三个叠加的问题。按标题匹配导致改写文案后旧行变孤儿、
+  新建行未写入步骤键、全局节点上限按「丢弃最老」执行而最老的恰属已完成步。
+  现已改为就地改名并迁移节点、统一赋值步骤键、并从节点最多的步开始淘汰（单步永不被清空）。
+- **被拒绝的审批仍标「需确认」**：审批被拒时该行仍需人工处理，原实现把任何「已决议」都当成已结束。
+  现改为「已询问，或已决议但未放行」都算未决；同时修掉了状态修复函数遗漏 `outcome` 字段的问题
+  （否则一次重启就会把这个语义抹掉）。
+- **唯一流光**：只有唯一那一行的进度条与连接线跑动画，其余即使状态是 running 也只是静态填充。
+
+### Changed
+
+- **面板布局改为单页**：原先的左右双列（分步列 + 流程列）合并为一个视图。串行主流程在中间，
+  每步两侧以圆形接口表示该类工具/文件，点击后在右页展开详情。两列之间的跨列曲线随之移除。
+- **移除「预计剩余时间」**：进度条第二行只保留「N 分钟前估计」（这个数字有多旧），
+  不再预测还需要多久。宿主侧相应的计算与字段一并移除。
+- **移除实验性的输入框覆盖层**：该方案多轮实测无法稳定覆盖宿主渲染的输入框，
+  改为在会话标签栏席位用样式规则让位，切回对话页自动恢复。
+
+### Tests
+
+- 离线自测 **10 套**，合计 **1505 条断言**。
+- 浏览器量测 **10 套**，合计 **308 条断言**（真实 CSS + 真实事件，覆盖几何、动画、剪贴板、
+  键盘与降级路径）。
+- 真实日志只读回归：批量折叠历史会话日志、零失败；另有四条硬约束审计。
+
+### Known issues
+
+- 品牌配色的「运行中卡片外框」仍沿用默认彩虹渐变（选择器未迁移）。仅影响外观，
+  进度条与其余元素已正确换色。
+- 类型页副标题会原样印出未替换的 `{count}` 占位符。仅影响文案。
+
+### Notes
+
+- **宿主半改动需要重启 DSH 进程**；浏览器半改动 **F5 即生效**（profile 使用符号链接安装时）。
+- 输入框（composer）由宿主渲染，不属于本插件；插件只在会话标签页席位让它让位。
+
+## 更早的内部迭代
+
+0.3.0 之前的版本为内部迭代，未对外发布，因此不在此列出逐条记录。
+所涉及的能力（会话投影、计划读取、HTTP 视图路由、面板骨架、进度条、节点详情、设置与导出）
+均已并入 0.3.0。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-workflow-map contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,458 @@
+# dsh-workflow-map
+
+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
+and file operations, and can inject prompts into the next step of a running session.
+
+![Workflow map: one main flow, type interfaces on both sides, details on the right page](docs/screenshot-detail.png)
+
+*Left: the selected sidebar entry. Centre: the serial main flow (one unit card per step, round interfaces
+on both sides for tool/file types; the running unit is highlighted with a flowing frame). Right: the page
+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.4-success)
+
+---
+
+## 1. What problem it solves
+
+Long tasks grow session logs to thousands of events. Answering "which step is it on", "what did this
+step do" and "how much is done" means scrolling back through those logs. This plugin presents those
+three facts on one screen, with every data source and decision rule traceable.
+
+### Layout
+
+```
+┌──────────────────────────────┬───────────────────┐
+│ session         4/10 · 46%                 ⚙ │
+├──────────────────────────────┼───────────────────┤
+│ ◯─┐  01/10  skeleton and registration │  step 5 detail       │
+│   │   ▓▓▓▓▓▓▓▓▓▓ 100% reported │  ──────────────── │
+│   │                            │  files this step used │
+│ ◯─┘  02/10  host projection      │  ● md type   4 calls │
+│   │   ▓▓▓▓▓▓▓▓▓▓ 100% reported │  ● js type   2 calls │
+│   │                            │  ● pwsh type 2 calls │
+│ ◯─┐  05/10  browser shell       <- running (highlighted) │
+│   │   ▓▓▓▓▓░░░░░ ~58% estimated │  step 5 detail      │
+│   │   estimated 3 min ago       │  what it delivered  │
+│   │                            │  ● done              │
+│ ◯─┘  06/10  step cards and rail │  12 tools 12 files │
+│       ▓▓▓░░░░░░░ ~36% estimated │  ──────────────── │
+│                                │  inject [........] │
+└──────────────────────────────┴───────────────────┘
+   main flow (one unit per step, round type interfaces on both sides)   right page (opens on click)
+```
+
+> Diagram, not a screenshot; see the screenshot above for the real UI.
+
+---
+
+## 2. Capabilities
+
+The four capabilities below map onto four regions of the UI: injection (header button and the right
+page input), progress (the rail under each card), layout (main flow and side interfaces), and state
+encoding (animation and colour).
+
+### 2.1 Hot injection (steer / unsteer)
+
+**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.
+
+| Endpoint | Method | Semantics |
+|---|---|---|
+| `/dsh-workflow/steer` | POST | Write one prompt to `next-step`; the response returns the generated `messageId` |
+| `/dsh-workflow/unsteer` | POST | Call `agent.inbox.remove()` with the `messageId`, removing a message that is **not yet claimed** |
+
+**State determination** (mutually exclusive, all derived from the log, never guessed by the UI):
+
+| State | Determined by |
+|---|---|
+| Awaiting pickup | `agent/inbox/spliced` exists and no `user/message` with the same id |
+| Picked up | A `user/message` with the same id exists (the turn claimed it) |
+| Revoked | `agent/inbox/spliced { outcome: "canceled" }` exists and the id was never claimed |
+
+HTTP 200 only means the message reached the inbox; it does **not** mean the session has read it. The
+"awaiting pickup" versus "picked up" distinction comes from the log events above. A revoke's durable
+record is the splice **position**, not the message id, so the fold keeps an inbox ledger (replaying
+splices with the host's own `inboxProjectionDefinition` semantics) to identify which row was removed.
+
+Failure semantics: document-level errors always return JSON and never throw into the HTTP layer.
+Common codes: `400` missing field / non-JSON body, `404` unknown session, `409` session not running or
+message already claimed, `413` text over 2000 chars or body over 64 KiB, `503` the host does not expose
+the capability.
+
+### 2.2 Progress estimation
+
+Each step's percentage is resolved by the following **priority** (`percentFor` in `src/fold.mjs`):
+| Priority | Source | Rule | Cap |
+|---|---|---|---|
+| 1 | Todo table `todos` | `round(completed / total * 100)`; when a self-report exists, this measured value is still what is returned | 99 |
+| 2 | Model self-report `model` | Only when the todo table has no countable rows: the **larger** of the `stepProgress/report` percentage and the self-report high-water mark | 100 |
+| 3 | Time baseline `baseline` | `elapsed / median(finished-step durations in this session) * 100` | 90 |
+| 4 | Plan ordinal `baseline:steps` | Cold start with `current step / total steps * 100` when no durations exist | 90 |
+| - | `none` | None of the four is available | No number shown |
+
+Constraint: an unfinished step never shows 100 %; a finished (done or failed) step is pinned to 100 %.
+
+The choice follows verifiability: the todo table is an objective count, a model self-report is not. So
+whenever the todo table has completed rows, the percentage is that measured ratio (both branches of that
+`percentFor` expression yield `measured`); the self-report is a fallback only when no row can be measured.
+The high-water record `step.maxPercent` is still kept and never rolled back, but it no longer takes part in
+computing the displayed value.
+
+A second line under the rail reads `estimated N minutes ago`, i.e. `view.asOf - step.lastEstimateAt`.
+It describes how **stale** the number is, distinguishing "being updated" from "unchanged for a long time".
+The line is not rendered when the field is absent.
+
+### 2.3 Single-page layout
+
+One vertical main flow, one unit per step; each unit carries round interfaces on both sides, one per
+tool or file type.
+
+| Dimension | Rule |
+|---|---|
+| Side assignment | Read-type (`read` / `grep` / `glob` / path queries) on the left; write and execute (`edit` / `write` / `pwsh`) on the right |
+| Capacity per side | 2 interfaces |
+| Overflow | Extra types are not drawn; the unit states "N more types are not drawn on the sides" |
+| Connector | A straight line between interface and unit |
+| Details | Click an interface -> the right page lists that type's calls; click a unit -> the right page shows that step's record |
+
+A single page was chosen over columns for continuity: switching steps in a two-column layout moves two
+scroll regions at once, whereas here the main flow does not shift when the right page opens or closes.
+
+### 2.4 Visual state encoding
+
+The running unit and the single connector pointing at it use a flowing gradient; every other unit stays
+statically filled even when its status is `running` (for example, when it is not the live one). Durations
+and thresholds live in `src/client/theme.js`:
+
+| Element | Implementation | Period |
+|---|---|---|
+| Running unit frame | `::after` multi-stop linear gradient plus a position animation | 2.6 s |
+| Running unit ring | Opacity pulse | 1.6 s |
+| Progress fill | Background position | 1.5 s |
+| Activity dots | Three dots breathing out of phase | 1.2 s |
+
+`data-motion="static"` (the "reduce motion" setting, or the OS `prefers-reduced-motion: reduce`) sets
+every animation inside the panel to `none`, and `document.getAnimations()` returns an empty set;
+`data-idle="1"` (session idle) sets animations to `paused` while keeping the current frame. The two are
+not the same thing.
+
+### 2.5 One implementation, three seats
+
+All three entries register the same component, the same polling and the same preferences record - there is
+no second implementation. The session-tab entry additionally carries a box-less marker so a `:has()` rule
+can collapse the host's composer on that page; switching back unmounts the view and the composer returns.
+
+---
+
+## 3. Installation
+
+> **Prerequisites for installing from the market**: two conditions must both hold. (1) `dsh-workflow-map`
+> 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.
+
+### 3.1 Install through the agent
+
+```
+install dsh-workflow-map with plugin_manager, path is <absolute path to the plugin>
+```
+
+A returned `application: applied` means it took effect; no other value does.
+
+### 3.2 Command line
+
+```bash
+cd "$HOME/.dsh/profiles/desktop"
+pnpm add dsh-workflow-map
+```
+
+```powershell
+# One command into the desktop profile (the bundled DSH CLI forwards the rest to that profile's pnpm; use the full path if it is not on PATH)
+dsh plugin --profile desktop add dsh-workflow-map
+```
+
+Then append `"dsh-workflow-map"` to the `dsh.profile.bundles` array in that directory's `package.json`.
+
+### 3.3 Local source
+
+```bash
+cd "$HOME/.dsh/profiles/desktop"
+pnpm add "dsh-workflow-map@link:/path/to/dsh-workflow-map"
+```
+
+`link:` creates a symlink, so source edits are reflected on disk immediately.
+
+### 3.4 Verify the install
+
+```bash
+# 1) the package is on disk
+ls "$HOME/.dsh/profiles/desktop/node_modules/dsh-workflow-map"
+
+# 2) the host view endpoint works (expect HTTP 200 and a JSON body)
+curl -i "http://127.0.0.1:<GUI port>/dsh-workflow/state?sessionId=<session id>"
+
+# 3) the UI: a clickable sidebar icon, a panel in the main area, a same-named tab in the session tab bar
+```
+
+---
+
+## 4. How changes take effect
+
+The plugin has two halves with different load times:
+
+| Half | Contains | Takes effect | Why |
+|---|---|---|---|
+| Browser half | `client.js` (built from `src/client/*.js`) | **Page refresh (F5)** | Front-end code loads per request |
+| Host half | `lib/index.js`, `src/fold.mjs`, `src/route.js` | **Restart the DSH process** | ESM module cache cannot be replaced in-process |
+
+Restart once after the first install; afterwards UI-only changes need no restart.
+
+---
+
+## 5. Data boundary
+
+### 5.1 What is read
+
+- **Session event log**: `todo/write`, `tool/call`, `tool/result`, `step/start|end`, `turn/start|end`,
+  `stepProgress/report`, `user/message`, `assistant/message`, `approval/*`, `agent/inbox/*` and others.
+  Event types not listed return the same state reference with no copy.
+- **PAE plan file**: `<project>/.pae/<sessionId>/orchestrator.json`. Read-only, cached by `mtime:size` and
+  re-parsed only when the file changes; the parsed result is deep-frozen. A missing file, a partial write or
+  malformed fields yield `null` and degrade to the todo table only, never throwing.
+
+### 5.2 What is not read
+
+- **File bodies**. Fields such as `content`, `old_str` and `new_str` never enter the state, so how much
+  the agent writes does not grow the panel's state.
+- **The network**. The plugin makes no outbound requests; all data comes from local processes and files.
+
+### 5.3 Truncation and limits
+
+| Item | Limit | On overflow |
+|---|---|---|
+| Arguments / result text | 200 characters each | The UI states "host cap 200 characters" |
+| Nodes per step | 300 | Keep head and tail, drop the middle into `truncated.stepNodes` |
+| Nodes per session | 1200 | Evict starting from the step with the most nodes; no step is ever emptied |
+| Injection history | 40 rows | Keep the newest |
+| Approval records | 40 rows | Keep the newest |
+| Titles | 120 characters | Truncated with an ellipsis |
+
+Eviction deliberately does not start with the oldest: the oldest nodes usually belong to finished steps,
+so time-based eviction would empty historical steps.
+
+---
+
+## 6. Interaction
+
+| Action | Result |
+|---|---|
+| Click a unit | The right page shows that step's record (report, artifacts, stats) |
+| Click a round interface | The right page lists that type's calls |
+| Click a call row | Expand the full arguments, result and error in place |
+| `Esc` | Close the right page, not the panel |
+| Gear | Open settings: palette, motion, detail depth, node limit |
+| Copy control | Copy path / command / snapshot, with a receipt that restores after 1.5 s |
+
+Settings:
+
+| Item | Values | Effect |
+|---|---|---|
+| Palette `palette` | `rainbow` / `brand` / `soft` | Switches accent colours and gradients |
+| Motion `motion` | `full` / `always` / `static` | `full` follows session activity; `always` plays even when idle; `static` turns everything off |
+| Detail depth `detail` | `summary` / `title` | `title` hides the rail's second line |
+| Node limit `nodeLimit` | 30 / 60 / 120 / 0 | `0` means unlimited |
+
+Preferences live in one `localStorage` record; a corrupted or outdated record degrades field by field to the
+ defaults without blocking rendering.
+
+---
+
+## 7. Export
+
+The gear offers four exports: copy / download times Markdown / JSON. The exported snapshot contains the
+steps, their status, the percentage source, the node list and the report artifact paths - never file bodies.
+
+---
+
+## 8. Compatibility and constraints
+
+- **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.
+- The fold path never reads a clock: every time value in the view comes from event timestamps, so the same
+  event sequence always yields the same view (replayable).
+
+---
+
+## 9. Development
+
+```bash
+# after editing src/client/*.js, rebuild the browser half
+node tools/build-client.mjs
+
+# 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
+node tools/selftest-shape.mjs         # package shape, config, files whitelist
+node tools/selftest-panel.mjs         # render tree, styles, interaction
+node tools/selftest-detail.mjs        # node and step details
+node tools/selftest-effects.mjs       # animation and motion fallback
+node tools/selftest-settings.mjs      # settings and export
+node tools/probe-route.mjs            # HTTP routes (real loopback)
+node tools/probe-steer.mjs            # injection / revoke channel
+
+# read-only regression over real logs
+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; 323 assertions, light/dark theme contrast included):
+
+```bash
+pwsh -File tools/measure-panel.ps1
+pwsh -File tools/measure-timing.ps1
+pwsh -File tools/measure-inject.ps1
+pwsh -File tools/measure-dock.ps1
+pwsh -File tools/measure-flow.ps1
+pwsh -File tools/measure-effects.ps1
+pwsh -File tools/measure-branches.ps1
+pwsh -File tools/measure-detail.ps1
+pwsh -File tools/measure-settings.ps1
+pwsh -File tools/measure-main.ps1
+```
+
+`client.js` is a build artifact (its first line carries a GENERATED marker) and must not be edited by hand.
+`tools/retired/` holds historical scripts for removed UI; they are not part of the verification chain.
+
+---
+
+## 10. Key constants
+
+Every threshold is defined once and asserted by the tests, so this table cannot drift from the code:
+
+| Constant | Value | Location | Meaning |
+|---|---|---|---|
+| `NODES_PER_STEP` | 300 | `src/fold.mjs` | Nodes per step |
+| `NODES_TOTAL` | 1200 | `src/fold.mjs` | Nodes per session |
+| `TEXT_LIMIT` | 200 | `src/fold.mjs` | Argument and result text |
+| `TITLE_LIMIT` | 120 | `src/fold.mjs` | Titles |
+| `INJECT_LIMIT` | 40 | `src/fold.mjs` | Injection history retained |
+| `APPROVAL_LIMIT` | 40 | `src/fold.mjs` | Approval records retained |
+| `WF_SIDE_SLOTS` | 2 | `src/client/theme.js` | Interfaces per side |
+| `WF_STEP_RAIL` | 6 | `src/client/theme.js` | Progress rail height (px) |
+| `WF_FLOW_CAP` | 60 | `src/client/theme.js` | Default call-list window |
+| Request body | 2000 chars / 64 KiB | `src/route.js` | Injection request limit |
+
+---
+
+## 11. Known issues
+
+Both defects recorded in 0.3.0 are closed:
+
+| Original # | Symptom | Status |
+|---|---|---|
+| 1 | With the brand palette the running unit's frame used the default gradient | Fixed (`8bf6f2c`); the same residue under the `soft` palette was fixed in 0.3.1 |
+| 2 | The type page subtitle showed an unsubstituted `{count}` placeholder | Fixed (`8bf6f2c`) |
+
+There are no known functional defects at present. Changes to the host half need a DSH process restart;
+that is how activation works, not a defect.
+
+---
+
+## 12. Layout
+
+```
+dsh-workflow-map/
+├─ index.js                  package entry (re-exports lib/index.js)
+├─ lib/index.js              host half: session projection + three HTTP endpoints
+├─ src/
+│  ├─ fold.mjs               events -> state -> view (pure, no clock, no IO)
+│  ├─ orchestrator.mjs       read-only PAE plan file
+│  ├─ route.js               /state · /steer · /unsteer
+│  └─ client/                browser-half sources (inlined into one file at build)
+├─ client.js                 build artifact
+├─ cordis.patch.yml          mount declaration
+├─ locale/{zh,en}.json       dictionaries
+├─ docs/                     release guide
+└─ tools/                    self-tests · probes · browser measurements
+```
+
+---
+
+## 13. FAQ
+
+**Can it show several sessions at once?**
+The panel shows the current session only. Switching sessions switches the content; nothing is merged or tiled.
+
+**Does it slow DSH down?**
+The fold is pure with no IO; the view is derived from state, and state has hard limits (300 nodes per step,
+1200 per session). Polling compares `rev` first and returns 304 without rebuilding when nothing changed.
+File bodies never enter the state.
+
+**Why does the percentage sometimes stay still for a long time?**
+The number only moves when new events arrive. When neither the todo table nor the report updates, the time
+baseline creeps up but is capped at 90 %. The second line ("estimated N minutes ago") states how stale it is.
+
+**Why does an unfinished step never reach 100 %?**
+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 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?**
+No. Both halves belong to one package: `dsh.profile.bundles` registers the host row, and the browser half is
+loaded by that row.
+
+**Can I turn animation off?**
+Set motion to `static` in the settings, or enable "reduce motion" in the OS; both set every animation inside
+the panel to `none`.
+
+---
+
+## 14. License
+
+MIT. Commercial use, modification and redistribution are permitted; keep the copyright notice.
+
+---
+
+## 15. Reporting an issue
+
+The following helps locate a problem:
+
+1. DSH version and plugin version (`version` in `package.json`);
+2. The response body of `GET /dsh-workflow/state?sessionId=<id>` - **it contains task titles and file
+   paths, so redact before posting**;
+3. A screenshot of the panel where it goes wrong;
+4. For fold-related issues, include the relevant event sequence from that session log.