dsh-workflow-map 0.3.4 → 0.3.5

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 `dsh-workflow-map` 的所有重要变更记录在此。
 格式遵循 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)，版本号遵循 [SemVer](https://semver.org/)。
 
+## [0.3.5] - 2026-10-31
+
+### Added
+
+- **README 截图区改为按市场评分规则书写的六图画廊**：主界面（深色/浅色）、运行中的单元、分步详情、
+  热注入、设置面板。图片落在 `docs/screenshots/`，相对路径引用，图注含「预览/截图/主界面」等关键词，
+  使插件市场的卡片与安装对话框能自动取到（该市场只认 README 里位于 GitHub 四域名的图片，
+  并按语义与尺寸打分取前 6 张；带 badge/logo 的一律排除）。
+- **标题栏增加手动刷新按钮（`↻`）**。点一次立即重新读取当前会话的视图，不等自动轮询的下一个周期；
+  读取成功后按钮短暂变为「已刷新」，随后恢复图标。它走的是同一条 `GET /dsh-workflow/state` 与同一个
+  `If-None-Match` 校验器，不引入第二条数据通道。自动轮询正常工作时无需使用，仅在自动刷新受阻时兜底。
+
+### Fixed
+
+- **返回即结束：节点的「已完成」不再由正文是否为空推断**。`nodeView` 发布布尔 `result`（折叠层的 `settled` 标记），
+  工具返回空正文（例如无输出的 `pwsh`）也算已返回。此前浏览器半只按 `resultHead !== ""` 判断，
+  空输出的调用因此永远停在「正在调用」状态。同时 `STATE_VERSION` 升到 5，旧检查点按契约丢弃重建。
+- **结果不是活动**。`foldToolResult` 曾把刚返回的节点重新设为 `active`，面板因此对已经返回的调用声称「正在调用」；
+  现在只有当更新的调用打开了另一个节点时才保留高亮，否则交还给步骤。
+- **未收到 `turn/end` 的回合不再让整张图无限流动**。`view.running` 是回合标志，中断/崩溃/压缩后的会话会把它永久留在 `true`；
+  浏览器半现在以时钟为第二证人：最后一个已折叠事件早于空闲窗口（15 s）即判定为空闲，无时钟（离线预览）时仍信任标志。
+- **重开的行不再继承上一轮的 100 %**。`foldTodos` 把 `completed` 行改回 `in_progress` 时保留了 `percent` 与 `maxPercent`，
+  新行一出现就钉在 100 %，进度条不再移动。现在重开（以及降级为 `pending`）会清空百分比与高水位，`startedAt` 重新计时。
+- **运行中的步骤不再显示 100 %**，且**自报的最新值就是显示值**。`percentFor` 的模型分支此前取「自报」与「高水位」的较大值并允许 100，
+  既让未完成的步骤声称 100 %，也让后续自报被历史高水位压住。高水位仍记录在 `step.maxPercent`，只是不再参与显示。
+- **自动轮询不再因一次慢请求而永久停止**。每个周期开始时会中止上一个未完成的请求，被中止的请求返回
+  `status: -1`；旧代码在这里直接 `return`，不重新排程。只要有一次请求慢于轮询间隔（网络抖动、宿主繁忙），
+  循环就此结束，地图停在最后一帧——表现为「地图不会自己更新」。现在中止只让位给已在飞行中的替代请求，
+  两者都结束后照常排程；该规则抽成纯函数 `wfPollContinues()` 并纳入自测。
+- **已结束的 PAE 计划不再改写地图**。`<cwd>/.pae/<sessionId>/orchestrator.json` 一旦写入就长期保留，
+  `phase` 为 `completed` / `aborted` 时仍会被当作当前计划读取，用它自己的 `statuses`、`anchorSeqs` 与步骤标题
+  覆盖本轮待办表刚建出的行，于是面板显示的是上一轮的计划。现在计划段新增布尔 `terminal`，为真时仍发布
+  （详情页要用它的 `stepReports`），但不再修改任何行的标题与状态；浏览器半的状态判定同样据此让位。
+
+### Changed
+
+- 自测口径：离线 10 套合计 1570 条（`selftest-fold` 217、`selftest-host` 54、`selftest-orchestrator` 155、其余同前），
+  浏览器量测 10 套合计 323 条。各套件的输出以退出码与逐条结果为准，本文件不复述结论。
+
 ## [0.3.4] - 2026-10-30
 
 ### Changed
@@ -49,7 +88,7 @@
 
 ### Tests
 
-- **离线自测 10 套 / 1533 条断言**全部通过，退出码全 0（0.3.3 为 1515 条）。本轮新增 13 条：`selftest-fold`
+- **离线自测 10 套 / 1533 条**（0.3.3 为 1515 条）。本轮新增 13 条：`selftest-fold`
   的 `(r)` 用例 8 条（待办表改回 `pending` 必须降级、改写表后的 `pending` 行不得顶替运行步、
   `in_progress` 行对应的记录即使原来是 `pending` 也要转为运行、未命名空行被丢弃、回合结束仍保留表中
   `in_progress` 的步、非运行行不出数字……），`selftest-panel` 的浅色主题针脚 5 条（抬升变量、深色覆盖、
@@ -57,7 +96,7 @@
 - **真实会话日志**：`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 条）：
+- **浏览器量测 10 套 / 323 条**（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 颗星徽标靠自身颜色边线可见
@@ -86,7 +125,7 @@
 
 - `tools/selftest-fold.mjs` 新增 8 条断言：`(o1)`/`(o2)` 编号清单换表后序号连续、标题不重名、
   行不继承邻居标题；`(p)` 计划确认点只落在该落的步骤、`kind` 为 `plan`、重复应用不重复、已完成步骤不带标记。
-- 离线自测 **10 套 / 1515 条断言**全部通过（0.3.2 为 1507 条）。
+- 离线自测 **10 套 / 1515 条**（0.3.2 为 1507 条）。
 
 
 ## [0.3.1] - 2026-10-28
@@ -111,7 +150,7 @@
 
 ### Tests
 
-- 离线自测 **10 套 / 1507 条断言**、浏览器量测 **10 套 / 308 条断言**，全部通过。
+- 离线自测 **10 套 / 1507 条**、浏览器量测 **10 套 / 308 条**。
 
 ### Notes
 

package/README.en.md

@@ -25,16 +25,28 @@ Three entry points share one data source and one set of components: the sidebar
 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)
+![Workflow map main screen preview (dark theme): serial main flow, type interfaces on both sides, details on the right page](docs/screenshots/01-main-dark.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.*
+*Main screen (dark): the selected sidebar entry on the left, the serial main flow in the centre (one unit
+card per step, round interfaces on both sides for tool/file types, the running unit highlighted with a
+flowing frame), the step detail page on the right, and the persistent injection bar at the bottom.*
+
+### Screenshots (full preview)
+
+| | |
+|---|---|
+| ![Main screen full preview (light theme)](docs/screenshots/02-main-light.png) | ![Running step preview: flowing gradient frame](docs/screenshots/03-running-step.png) |
+| **Main screen · light theme** — same layout, colours follow the host theme | **Running unit** — the flowing frame marks "calling right now" |
+| ![Step detail preview: type list and call records on the right page](docs/screenshots/04-step-detail.png) | ![Hot inject preview: queue a prompt for the next step](docs/screenshots/05-hot-inject.png) |
+| **Step detail** — type list, call arguments and result summary for that step | **Hot inject** — queue a prompt for the next step, revocable before it is claimed |
+| ![Settings panel preview: palette, motion, detail depth and export](docs/screenshots/06-settings.png) | |
+
+All six are offscreen renders of the interface and contain no real session content.
 
 ![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)
+![version](https://img.shields.io/badge/version-0.3.5-success)
 
 ---
 
@@ -112,18 +124,21 @@ Each step's percentage is resolved by the following **priority** (`percentFor` i
 | 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 |
+| 2 | Model self-report `model` | Only when the todo table has no countable rows: the most recent `stepProgress/report` percentage | 99 |
 | 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.
+The choice follows verifiability: the todo table is a count of rows, a model self-report has no per-row
+basis. So whenever the todo table has completed rows, the percentage is that ratio (both branches of
+`percentFor` return `measured`); the self-report is a fallback only when no row can be counted, and the
+**most recent** report is used so that a later report can move the value. The high-water record
+`step.maxPercent` is kept and never rolled back, and does not take part in the displayed value.
+When `foldTodos` takes a finished row back to `in_progress`, or demotes it to `pending`, it clears
+`percent` and `maxPercent` and resets `startedAt`: a finished record's number belongs to that closure,
+not to the row that reopens it.
 
 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".
@@ -279,8 +294,14 @@ so time-based eviction would empty historical steps.
 | 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 |
+| `↻` | Read the current session's view again now; the button briefly shows "Refreshed" |
 | Copy control | Copy path / command / snapshot, with a receipt that restores after 1.5 s |
 
+The view is polled: every 0.8 s while the page is visible, every 3 s while it is hidden, as a conditional
+request (`If-None-Match`) that the host answers with `304` and no body when nothing changed. `↻` runs one
+cycle of that same request, for the case where automatic polling is blocked; it neither changes the cadence
+nor adds a second data path.
+
 Settings:
 
 | Item | Values | Effect |
@@ -320,7 +341,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, 1533 assertions)
+# offline self-tests (10 suites)
 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
@@ -337,7 +358,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; 323 assertions, light/dark theme contrast included):
+Browser measurements (needs a Chromium; the scripts auto-detect Chrome / Edge; light/dark theme contrast included):
 
 ```bash
 pwsh -File tools/measure-panel.ps1
@@ -359,7 +380,7 @@ pwsh -File tools/measure-main.ps1
 
 ## 10. Key constants
 
-Every threshold is defined once and asserted by the tests, so this table cannot drift from the code:
+Every threshold is defined once and read by the self-tests, so this table and the code share one source:
 
 | Constant | Value | Location | Meaning |
 |---|---|---|---|
@@ -376,7 +397,23 @@ Every threshold is defined once and asserted by the tests, so this table cannot
 
 ---
 
-## 11. Known issues
+## 11. Plan file and todo table precedence
+
+The map's steps come from two sources, in a fixed order:
+
+| Priority | Source | Effect |
+|---|---|---|
+| 1 | Todo table `todo/write` | This turn's step titles and statuses, the session's newest statement |
+| 2 | Plan file `.pae/<sessionId>/orchestrator.json` | While `phase` is `planning` / `scheduled` / `executing` / `paused`, its step titles, `statuses` and `anchorSeqs` apply |
+| - | The same file at `completed` / `aborted` | The plan is over: its steps and reports are still published for the detail page, but it no longer changes any row's title or status |
+
+The plan file is written once and never deleted. Read without that distinction, a previous turn's plan
+overrides the rows the current todo table has just created, and the panel disagrees with the conversation.
+The view's plan section therefore carries a boolean `terminal`, and both halves (host and browser) obey it.
+
+---
+
+## 12. Known issues
 
 Both defects recorded in 0.3.0 are closed:
 
@@ -390,7 +427,7 @@ that is how activation works, not a defect.
 
 ---
 
-## 12. Layout
+## 13. Layout
 
 ```
 dsh-workflow-map/
@@ -410,7 +447,7 @@ dsh-workflow-map/
 
 ---
 
-## 13. FAQ
+## 14. 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.
@@ -441,13 +478,13 @@ the panel to `none`.
 
 ---
 
-## 14. License
+## 15. License
 
 MIT. Commercial use, modification and redistribution are permitted; keep the copyright notice.
 
 ---
 
-## 15. Reporting an issue
+## 16. Reporting an issue
 
 The following helps locate a problem:
 

package/README.md

@@ -24,16 +24,27 @@ DeepSeek Harness 插件：把当前会话渲染为一张可交互的分步工作
 会话标签栏（`conversation.view`）。面板将会话事件折叠为分步序列，展示每步的状态、进度、
 工具调用与文件操作，并支持在会话运行中向其下一步注入提示词。
 
-![工作流地图：单一主流程 + 两侧类型接口 + 右页详情](docs/screenshot-detail.png)
+![工作流地图主界面预览（深色主题）：串行主流程 + 两侧类型接口 + 右页详情](docs/screenshots/01-main-dark.png)
 
-*左：侧边栏入口选中态；中：串行主流程（每步一张单元卡，两侧圆形接口为工具/文件类型，
-运行中的单元高亮并带流动外框）；右：点开分步后的右页（类型清单、分步详情），
-底部为常驻注入条。*
+*主界面（深色）：左为侧边栏入口选中态，中为串行主流程（每步一张单元卡，两侧圆形接口为工具/文件
+类型，运行中的单元高亮并带流动外框），右为分步详情页，底部为常驻注入条。*
+
+### 界面截图（完整预览）
+
+| | |
+|---|---|
+| ![主界面完整预览（浅色主题）](docs/screenshots/02-main-light.png) | ![运行中的步骤预览：流动渐变外框](docs/screenshots/03-running-step.png) |
+| **主界面 · 浅色主题** —— 与深色同一布局，配色随宿主主题切换 | **运行中的单元** —— 流动渐变外框标出「此刻在调用」 |
+| ![分步详情预览：右页的类型清单与调用记录](docs/screenshots/04-step-detail.png) | ![热注入界面预览：把提示词排入下一步队列](docs/screenshots/05-hot-inject.png) |
+| **分步详情** —— 右页列出该步的类型清单、调用参数与结果摘要 | **热注入** —— 提示词排入下一步执行队列，被取用前可撤回 |
+| ![设置面板预览：配色、动效、详情深度与导出](docs/screenshots/06-settings.png) | |
+
+以上六张为离屏渲染的界面预览，不含任何真实会话内容。
 
 ![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)
+![version](https://img.shields.io/badge/version-0.3.5-success)
 
 ---
 
@@ -106,15 +117,18 @@ body 超 64 KiB，`503` 宿主未暴露相应能力。
 | 优先级 | 来源 | 计算规则 | 上限 |
 |---|---|---|---|
 | 1 | 待办表实测 `todos` | `round(已完成项 / 总项 × 100)`；自报存在时也只取该实测值 | 99 |
-| 2 | 模型自报 `model` | 待办表无可计行时，取 `stepProgress/report` 百分比与自报高水位中的较 **大** 者 | 100 |
+| 2 | 模型自报 `model` | 待办表无可计行时，取最近一次 `stepProgress/report` 的百分比 | 99 |
 | 3 | 时间基线 `baseline` | `elapsed / median(本会话已完步耗时) × 100` | 90 |
 | 4 | 计划步序 `baseline:steps` | 无历史耗时时，用 `当前步序 / 总步数 × 100` 冷启动 | 90 |
 | — | `none` | 四个来源均不可用 | 不显示数字 |
 
 约束：未结束的步不会显示 100%；已结束（完成或失败）的步固定为 100%。
-选用规则由可验证性决定：待办表是逐行计数得到的实测值，模型自报无此行级依据。因此只要待办表有已完成行，
-百分比就取该实测比值（`percentFor` 中两个分支值均为 `measured`），自报只能作为无实测行时的备选；
-高水位记录 `step.maxPercent` 仍保留且不回退，只是不再参与显示值计算。
+
+选用规则依据可核验性：待办表是逐行计数得到的量值，模型自报没有对应的行级依据。因此只要待办表存在已完成行，
+百分比取该计数比值（`percentFor` 的两个分支均返回 `measured`），自报仅在无行可计数时作为备选；且取
+**最近一次**自报，使后续报告能够改变显示值。高水位记录 `step.maxPercent` 保留且不回退，不参与显示值计算。
+`foldTodos` 将已结束行改回 `in_progress`、或降级为 `pending` 时，清空 `percent` 与 `maxPercent` 并重置
+`startedAt`：已结束记录的数字属于那一次结束，不属于重新打开它的行。
 
 进度条下方另有一行元信息：`N 分钟前估计`，即 `view.asOf − step.lastEstimateAt`。
 该值描述数字的**陈旧程度**，用于区分「正在更新」与「长时间未更新」。字段缺失时整行不渲染。
@@ -264,8 +278,13 @@ curl -i "http://127.0.0.1:<GUI端口>/dsh-workflow/state?sessionId=<会话ID>"
 | 点调用行 | 就地展开参数全文、结果与错误 |
 | `Esc` | 关闭右页，不关闭面板 |
 | 齿轮 | 打开设置：配色、动效、详情深度、节点上限 |
+| `↻` | 立即重新读取当前会话的视图；读取成功后按钮短暂显示「已刷新」 |
 | 复制控件 | 复制路径 / 命令 / 快照，1.5 秒后回执并复原 |
 
+视图由轮询获得：页面可见时每 0.8 秒一次，隐藏时每 3 秒一次，条件请求（`If-None-Match`），
+未变化时宿主返回 `304` 且无响应体。`↻` 只是触发同一请求的一个周期，用于自动轮询受阻时手动取一次，
+不改变轮询节奏，也不构成第二条数据通道。
+
 设置项：
 
 | 项 | 取值 | 作用 |
@@ -303,7 +322,7 @@ curl -i "http://127.0.0.1:<GUI端口>/dsh-workflow/state?sessionId=<会话ID>"
 # 修改 src/client/*.js 后必须重新生成浏览器半
 node tools/build-client.mjs
 
-# 离线自测（10 套，共 1533 条断言）
+# 离线自测（10 套）
 node tools/selftest-fold.mjs          # 折叠语义
 node tools/selftest-host.mjs          # 注册、schema、投影接线
 node tools/selftest-orchestrator.mjs  # 计划文件读取与合并
@@ -320,7 +339,7 @@ node tools/check-real-injects.mjs     # 批量折叠历史日志
 node tools/audit-real.mjs             # 四项约束审计
 ```
 
-浏览器量测（需一份 Chromium，脚本自动探测 Chrome / Edge，共 323 条断言，含浅色/深色主题对比检查）：
+浏览器量测（需一份 Chromium，脚本自动探测 Chrome / Edge；含浅色/深色主题对比检查）：
 
 ```bash
 pwsh -File tools/measure-panel.ps1
@@ -342,7 +361,7 @@ pwsh -File tools/measure-main.ps1
 
 ## 10. 关键常量
 
-所有阈值集中定义，并由测试直接断言，因此文档取值与实现取值不会脱节：
+所有阈值集中定义，并由自测直接引用，因此本表取值与实现取值同源：
 
 | 常量 | 值 | 位置 | 含义 |
 |---|---|---|---|
@@ -359,7 +378,22 @@ pwsh -File tools/measure-main.ps1
 
 ---
 
-## 11. 已知问题
+## 11. 计划文件与待办表的优先级
+
+地图的分步有两个来源，优先级固定：
+
+| 优先级 | 来源 | 作用 |
+|---|---|---|
+| 1 | 待办表 `todo/write` | 本轮分步的标题与状态，是当前会话的最新陈述 |
+| 2 | 计划文件 `.pae/<sessionId>/orchestrator.json` | `phase` 为 `planning` / `scheduled` / `executing` / `paused` 时，其步骤标题、`statuses`、`anchorSeqs` 生效 |
+| — | 同一文件的 `completed` / `aborted` | 计划已结束：步骤与报告仍发布给详情页，但不再修改任何行的标题与状态 |
+
+计划文件写入后长期保留，不会被删除。若不加区分地读取，上一轮计划的标题与状态会覆盖本轮待办表刚建出的行，
+面板与对话因此不一致。视图的计划段为此携带布尔 `terminal`，两侧（宿主与浏览器半）都以它为准。
+
+---
+
+## 12. 已知问题
 
 0.3.0 记录过的两个缺陷均已关闭：
 
@@ -372,7 +406,7 @@ pwsh -File tools/measure-main.ps1
 
 ---
 
-## 12. 目录
+## 13. 目录
 
 ```
 dsh-workflow-map/
@@ -392,7 +426,7 @@ dsh-workflow-map/
 
 ---
 
-## 13. 常见问题
+## 14. 常见问题
 
 **能同时看多个会话吗？**
 面板只展示当前会话。切换会话即切换内容；不合并、不并排。
@@ -420,13 +454,13 @@ dsh-workflow-map/
 
 ---
 
-## 14. 许可
+## 15. 许可
 
 MIT。允许商用、修改与再分发，需保留版权声明。
 
 ---
 
-## 15. 问题反馈
+## 16. 问题反馈
 
 以下信息有助于定位问题：
 

package/client.js

@@ -232,6 +232,10 @@ window.__ModuleLoader__.load({
       ".wf-btn:hover{background:var(--dsw-alias-bg-layer-2,#2c3140);color:var(--dsw-alias-label-primary,#e9ecf3)}",
       ".wf-btn:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5b8cff);outline-offset:1px}",
       ".wf-btn[data-active='true']{color:var(--dsw-alias-brand-primary,#5b8cff);border-color:var(--dsw-alias-brand-primary,#5b8cff)}",
+     // The refresh button's one-second acknowledgement. Width is pinned to the glyph's own
+     // box so swapping "↻" for "已刷新" cannot shift the header row underneath the pointer.
+      ".wf-btn-ok{color:var(--dsw-alias-state-success-primary,#3fb950);border-color:var(--dsw-alias-state-success-primary,#3fb950);" +
+        "width:auto;min-width:23px;padding:0 6px;font-size:11px}",
      // Hot injection is the one header action that injects text into the RUNNING turn, so it is the
      // one that must never be hunted for: a named, filled chip that keeps its name in Chinese.
      // User feedback: "too small, still have to open it first" - so it grows to 96x30 (the other two in the row stay
@@ -1382,6 +1386,22 @@ window.__ModuleLoader__.load({
       return "/dsh-workflow/state?sessionId=" + encodeURIComponent(String(sessionId));
     }
 
+    /**
+     * May the poll loop re-arm after this result?
+     *
+     * A tick aborts the request it replaces, and an aborted request resolves as status -1.
+     * That is the ORDINARY path whenever a poll outlives its interval, so -1 must not end
+     * the loop: it only defers to the replacement that is already in the air. Returning
+     * false there is what keeps two loops from running; returning false for anything else
+     * (a real error, a 4xx) would stop the panel from ever updating again.
+     *
+     * Extracted from the hook so the rule is testable without a renderer.
+     */
+    function wfPollContinues(result, inflight) {
+      if (!result || result.status !== -1) return true;
+      return wfFinite(inflight) === null ? true : inflight <= 0;
+    }
+
     /**
      * One conditional GET. Never throws: every outcome is a value, so the loop can
      * always decide what to render and how long to wait.
@@ -1572,6 +1592,9 @@ window.__ModuleLoader__.load({
         }
       }
       return {
+     // A finished plan must not decide a card's status any more; the summary carries
+     // the flag so the status policy can stand down without re-reading the phase.
+        terminal: plan.terminal === true,
         statuses: plan.statuses && typeof plan.statuses === "object" ? plan.statuses : {},
         anchorSeqs: plan.anchorSeqs && typeof plan.anchorSeqs === "object" ? plan.anchorSeqs : {},
         skipped: Array.isArray(plan.skipped) ? plan.skipped.slice() : [],
@@ -2085,7 +2108,10 @@ window.__ModuleLoader__.load({
           errorText: typeof found.error === "string" ? found.error.slice(0, 200) : "",
           seq: wfFinite(found.seq),
           error: typeof found.error === "string" && found.error !== "",
-          result: typeof found.resultHead === "string" && found.resultHead !== "",
+          // The host's result boolean is the settled fact: a call that returned with an EMPTY body is
+          // settled. Falling back to resultHead alone marked such a call unsettled, so the panel kept
+          // it in the "calling right now" state and its dot pulsed after the call had already returned.
+          result: found.result === true || (typeof found.resultHead === "string" && found.resultHead !== ""),
           durationMs: wfFinite(found.durationMs),
           at: wfFinite(found.at),
         });
@@ -2566,7 +2592,17 @@ window.__ModuleLoader__.load({
      * working session as idle (which would make the curve and the frame look broken).
      */
     function wfSessionRunning(view, activeNodeId, nowMs) {
-      if (view && typeof view.running === "boolean") return view.running;
+      // The clock is the second witness. view.running is the turn flag, and a turn that never
+      // received its turn/end event (interrupt, crash, a compacted session) leaves it true forever.
+      // Once the last folded event is older than the idle window the session is not working,
+      // whatever the flag says.
+      if (view && typeof view.running === "boolean") {
+        if (view.running !== true) return false;
+        var flagAsOf = wfFinite(view.asOf);
+        var flagNow = wfFinite(nowMs);
+        if (flagAsOf !== null && flagAsOf > 0 && flagNow !== null && flagNow - flagAsOf >= WF_IDLE_AFTER_MS) return false;
+        return true;
+      }
       if (typeof activeNodeId === "string" && activeNodeId !== "") return true;
       var asOf = wfFinite(view && view.asOf);
       if (asOf === null || asOf <= 0) return false;
@@ -3266,8 +3302,11 @@ window.__ModuleLoader__.load({
      */
     function wfDeriveStepStatus(row, plan, todoIndex, currentPlanIndex) {
       var planIndex = row && wfFinite(row.planIndex) !== null ? Math.round(row.planIndex) : null;
+     // A finished plan (completed / aborted) is history: its statuses and anchor
+     // cursor describe a turn that is over, so the todo table and the host decide.
+      var live = plan && plan.terminal !== true;
 
-      if (plan && planIndex !== null) {
+      if (live && planIndex !== null) {
      // 1. PAE's own statuses are the published truth.
         var label = wfHasKey(plan.statuses, String(planIndex)) ? plan.statuses[String(planIndex)] : null;
         var fromPae = wfCanonicalStatus(label);
@@ -7800,6 +7839,9 @@ window.__ModuleLoader__.load({
       "panel.planning.note": "计划尚未提交，提交后会显示分步。",
       "panel.collapse": "收起",
       "panel.expand": "展开",
+      "panel.refresh": "刷新",
+      "panel.refresh.hint": "立即重新读取这一步的状态（自动刷新每 0.8 秒一次，这里是不等它的手动兜底）",
+      "panel.refresh.done": "已刷新",
       "panel.settings": "设置",
       "panel.steps": "总任务分步",
       "panel.flow": "分步流程",
@@ -8010,6 +8052,9 @@ window.__ModuleLoader__.load({
       "panel.planning.note": "The plan has not been submitted yet; steps appear after it is.",
       "panel.collapse": "Collapse",
       "panel.expand": "Expand",
+      "panel.refresh": "Refresh",
+      "panel.refresh.hint": "Read this step's state again now (auto-refresh runs every 0.8 s; this is the manual fallback)",
+      "panel.refresh.done": "Refreshed",
       "panel.settings": "Settings",
       "panel.steps": "Task steps",
       "panel.flow": "Step flow",
@@ -8289,6 +8334,10 @@ window.__ModuleLoader__.load({
       });
       var snap = pair[0];
       var setSnap = pair[1];
+     // The running loop's own tick, so the header's refresh button can pull once on
+     // demand without waiting for the interval. A ref, not state: swapping the function
+     // must not re-render, and a click must never restart the effect.
+      var tickRef = React.useRef(null);
 
       React.useEffect(
         function () {
@@ -8301,6 +8350,9 @@ window.__ModuleLoader__.load({
           var timer = 0;
           var controller = null;
           var etag = "";
+     // How many requests are in the air. A replaced request resolves as -1 and must
+     // not re-arm while the newer one is still going, or two loops would run.
+          var inflight = 0;
 
           setSnap({ status: "loading", view: null, rev: null, error: "" });
 
@@ -8325,11 +8377,20 @@ window.__ModuleLoader__.load({
             }
             controller = typeof AbortController === "function" ? new AbortController() : null;
             var signal = controller ? controller.signal : undefined;
+            inflight += 1;
             wfPollOnce(window.fetch, wfPollUrl(sessionId), etag, signal).then(function (result) {
+              inflight -= 1;
               if (stopped) return;
-     // -1 = this request was aborted by a newer one (visibility change): the
-     // newer tick already owns the loop, so stay silent and do not re-arm.
-              if (result.status === -1) return;
+     // -1 = this request was aborted. A tick aborts the request it replaces, so this
+     // is the ORDINARY path on a slow link, not an exception: returning here without
+     // re-arming stopped the loop for good the first time a poll outlived its tick —
+     // the map then froze while the session kept working, which is the reported
+     // "the map does not update by itself". Only the deliberate stop (stopped) ends it.
+              if (result.status === -1) {
+     // A replaced request: re-arm only when no replacement is still in the air.
+                if (wfPollContinues(result, inflight)) schedule(delay);
+                return;
+              }
               if (result.status === 304) {
                 setSnap(function (prev) {
                   return prev.view ? { status: "live", view: prev.view, rev: prev.rev, error: "" } : prev;
@@ -8362,10 +8423,12 @@ window.__ModuleLoader__.load({
             tick();
           }
 
+          tickRef.current = tick;
           tick();
           document.addEventListener("visibilitychange", onVisibilityChange);
           return function () {
             stopped = true;
+            tickRef.current = null;
             window.clearTimeout(timer);
             if (controller && typeof controller.abort === "function") {
               try {
@@ -8380,7 +8443,18 @@ window.__ModuleLoader__.load({
         [sessionId]
       );
 
-      return snap;
+     // One object, not two returns: every caller already reads the snapshot field by field,
+     // so the refresh hook rides along without changing the shape they destructure.
+      return {
+        status: snap.status,
+        view: snap.view,
+        rev: snap.rev,
+        error: snap.error,
+        refresh: function () {
+          var pull = tickRef.current;
+          if (typeof pull === "function") pull();
+        },
+      };
     }
 
     /** The stylesheet lives exactly as long as the mount. */
@@ -8400,6 +8474,25 @@ window.__ModuleLoader__.load({
       }, []);
     }
 
+    /**
+     * Clear a "just happened" stamp after a moment, so the button returns to its own
+     * glyph. One timer, cleared on unmount and on a second click (the stamp changes).
+     */
+    function wfUseFlashClear(stamp, clear) {
+      React.useEffect(
+        function () {
+          if (!(stamp > 0)) return undefined;
+          var timer = window.setTimeout(function () {
+            clear();
+          }, 1200);
+          return function () {
+            window.clearTimeout(timer);
+          };
+        },
+        [stamp]
+      );
+    }
+
     /** Alt+W toggles the collapsed state; the listener is removed on unmount. */
     function wfUseAltW(updatePrefs) {
       React.useEffect(function () {
@@ -8792,6 +8885,15 @@ window.__ModuleLoader__.load({
       var prefs = prefsHandle.prefs;
       var updatePrefs = prefsHandle.update;
       var snap = wfUseSnap(sessionId);
+     // When the header's refresh was last clicked; drives the one-word acknowledgement
+     // that clears itself. Deliberately NOT the poll's own state: a click must not look
+     // like a data change.
+      var refreshedPair = React.useState(0);
+      var refreshed = refreshedPair[0];
+      var setRefreshed = refreshedPair[1];
+      wfUseFlashClear(refreshed, function () {
+        setRefreshed(0);
+      });
       var settingsPair = React.useState(false);
       var settingsOpen = settingsPair[0];
       var setSettingsOpen = settingsPair[1];
@@ -8890,6 +8992,13 @@ window.__ModuleLoader__.load({
         onToggleSettings: function () {
           setSettingsOpen(!settingsOpen);
         },
+     // The manual fallback: one pull, now, without waiting for the interval and without
+     // touching the loop. It reads the same endpoint with the same validator, so a click
+     // is a normal poll and never a second data path.
+        onRefresh: function () {
+          setRefreshed(Date.now());
+          if (typeof snap.refresh === "function") snap.refresh();
+        },
      // Clicking a main-flow unit: it becomes the SELECTED step (store.js builds its detail) and the
      // right page opens on it. It deliberately does not expand anything in place.
      // right page opens on it. It deliberately does not expand anything in place.
@@ -8968,6 +9077,7 @@ window.__ModuleLoader__.load({
 
       return wfRenderPanel(model, prefs, say, actions, {
         settingsOpen: settingsOpen,
+        refreshed: refreshed,
         status: snap.status,
         error: snap.error,
         rev: snap.rev,
@@ -9008,6 +9118,9 @@ window.__ModuleLoader__.load({
       var pendingCount = wfPendingInjectCount(model.injects);
       var extras = ui || {};
       var fire = actions || {};
+     // The refresh button's one-second acknowledgement, handed in by the component: the
+     // renderer stays pure, so a self-test can drive it with a fixed stamp.
+      var refreshed = wfFinite(extras.refreshed) === null ? 0 : extras.refreshed;
      // the two attributes the living layer needs. `motion` comes from the system's
      // prefers-reduced-motion preference (pulse.js), `idle` from the model's running flag.
      // Both live on .wf-root so the capsule is covered as well as the panel.
@@ -9107,6 +9220,24 @@ window.__ModuleLoader__.load({
         h(
           "div",
           { className: "wf-btns", key: "btns" },
+     // First in the row: it is the escape hatch when the automatic poll is not
+     // delivering, so it must not be the hard one to find.
+          h(
+            "button",
+            {
+              type: "button",
+              key: "refresh",
+              className: refreshed > 0 ? "wf-btn wf-btn-ok" : "wf-btn",
+              "data-dsh-workflow-map": "refresh",
+              "data-refreshed": refreshed > 0 ? "true" : undefined,
+              title: say("panel.refresh.hint"),
+              "aria-label": say("panel.refresh"),
+              onClick: function () {
+                wfFire(fire.onRefresh);
+              },
+            },
+            refreshed > 0 ? say("panel.refresh.done") : "↻"
+          ),
           h(
             "button",
             {
@@ -9577,6 +9708,7 @@ window.__ModuleLoader__.load({
       sessionIdFromSnapshot: wfSessionIdFromSnapshot,
       pollUrl: wfPollUrl,
       pollOnce: wfPollOnce,
+      pollContinues: wfPollContinues,
       parsePrefs: wfParsePrefs,
       sanitizePrefs: wfSanitizePrefs,
       applyPrefsPatch: wfApplyPrefsPatch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-workflow-map",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "把当前会话渲染成一张可交互的分步工作流地图：会话标签栏、左栏菜单与主内容区共用同一份面板，逐步显示状态、工具与文件类型明细、进度条，并支持热注入（steer）与「需确认」标注。宿主半折叠会话事件、读取按步执行（PAE）计划，经本地 HTTP 视图供数据；浏览器半渲染面板。",
   "private": false,
   "type": "module",
@@ -63,6 +63,7 @@
     "docs/host-compatibility.md",
     "docs/screenshot.png",
     "docs/screenshot-detail.png",
+    "docs/screenshots",
     "package.json"
   ],
   "scripts": {

package/src/client/StepColumn.js

@@ -155,8 +155,11 @@ function wfHasKey(object, key) {
  */
 function wfDeriveStepStatus(row, plan, todoIndex, currentPlanIndex) {
   var planIndex = row && wfFinite(row.planIndex) !== null ? Math.round(row.planIndex) : null;
+ // A finished plan (completed / aborted) is history: its statuses and anchor
+ // cursor describe a turn that is over, so the todo table and the host decide.
+  var live = plan && plan.terminal !== true;
 
-  if (plan && planIndex !== null) {
+  if (live && planIndex !== null) {
  // 1. PAE's own statuses are the published truth.
     var label = wfHasKey(plan.statuses, String(planIndex)) ? plan.statuses[String(planIndex)] : null;
     var fromPae = wfCanonicalStatus(label);

package/src/client/panel.js

@@ -34,6 +34,9 @@ var DICT_ZH = {
   "panel.planning.note": "计划尚未提交，提交后会显示分步。",
   "panel.collapse": "收起",
   "panel.expand": "展开",
+  "panel.refresh": "刷新",
+  "panel.refresh.hint": "立即重新读取这一步的状态（自动刷新每 0.8 秒一次，这里是不等它的手动兜底）",
+  "panel.refresh.done": "已刷新",
   "panel.settings": "设置",
   "panel.steps": "总任务分步",
   "panel.flow": "分步流程",
@@ -244,6 +247,9 @@ var DICT_EN = {
   "panel.planning.note": "The plan has not been submitted yet; steps appear after it is.",
   "panel.collapse": "Collapse",
   "panel.expand": "Expand",
+  "panel.refresh": "Refresh",
+  "panel.refresh.hint": "Read this step's state again now (auto-refresh runs every 0.8 s; this is the manual fallback)",
+  "panel.refresh.done": "Refreshed",
   "panel.settings": "Settings",
   "panel.steps": "Task steps",
   "panel.flow": "Step flow",
@@ -523,6 +529,10 @@ function wfUseSnap(sessionId) {
   });
   var snap = pair[0];
   var setSnap = pair[1];
+ // The running loop's own tick, so the header's refresh button can pull once on
+ // demand without waiting for the interval. A ref, not state: swapping the function
+ // must not re-render, and a click must never restart the effect.
+  var tickRef = React.useRef(null);
 
   React.useEffect(
     function () {
@@ -535,6 +545,9 @@ function wfUseSnap(sessionId) {
       var timer = 0;
       var controller = null;
       var etag = "";
+ // How many requests are in the air. A replaced request resolves as -1 and must
+ // not re-arm while the newer one is still going, or two loops would run.
+      var inflight = 0;
 
       setSnap({ status: "loading", view: null, rev: null, error: "" });
 
@@ -559,11 +572,20 @@ function wfUseSnap(sessionId) {
         }
         controller = typeof AbortController === "function" ? new AbortController() : null;
         var signal = controller ? controller.signal : undefined;
+        inflight += 1;
         wfPollOnce(window.fetch, wfPollUrl(sessionId), etag, signal).then(function (result) {
+          inflight -= 1;
           if (stopped) return;
- // -1 = this request was aborted by a newer one (visibility change): the
- // newer tick already owns the loop, so stay silent and do not re-arm.
-          if (result.status === -1) return;
+ // -1 = this request was aborted. A tick aborts the request it replaces, so this
+ // is the ORDINARY path on a slow link, not an exception: returning here without
+ // re-arming stopped the loop for good the first time a poll outlived its tick —
+ // the map then froze while the session kept working, which is the reported
+ // "the map does not update by itself". Only the deliberate stop (stopped) ends it.
+          if (result.status === -1) {
+ // A replaced request: re-arm only when no replacement is still in the air.
+            if (wfPollContinues(result, inflight)) schedule(delay);
+            return;
+          }
           if (result.status === 304) {
             setSnap(function (prev) {
               return prev.view ? { status: "live", view: prev.view, rev: prev.rev, error: "" } : prev;
@@ -596,10 +618,12 @@ function wfUseSnap(sessionId) {
         tick();
       }
 
+      tickRef.current = tick;
       tick();
       document.addEventListener("visibilitychange", onVisibilityChange);
       return function () {
         stopped = true;
+        tickRef.current = null;
         window.clearTimeout(timer);
         if (controller && typeof controller.abort === "function") {
           try {
@@ -614,7 +638,18 @@ function wfUseSnap(sessionId) {
     [sessionId]
   );
 
-  return snap;
+ // One object, not two returns: every caller already reads the snapshot field by field,
+ // so the refresh hook rides along without changing the shape they destructure.
+  return {
+    status: snap.status,
+    view: snap.view,
+    rev: snap.rev,
+    error: snap.error,
+    refresh: function () {
+      var pull = tickRef.current;
+      if (typeof pull === "function") pull();
+    },
+  };
 }
 
 /** The stylesheet lives exactly as long as the mount. */
@@ -634,6 +669,25 @@ function wfUseStyle() {
   }, []);
 }
 
+/**
+ * Clear a "just happened" stamp after a moment, so the button returns to its own
+ * glyph. One timer, cleared on unmount and on a second click (the stamp changes).
+ */
+function wfUseFlashClear(stamp, clear) {
+  React.useEffect(
+    function () {
+      if (!(stamp > 0)) return undefined;
+      var timer = window.setTimeout(function () {
+        clear();
+      }, 1200);
+      return function () {
+        window.clearTimeout(timer);
+      };
+    },
+    [stamp]
+  );
+}
+
 /** Alt+W toggles the collapsed state; the listener is removed on unmount. */
 function wfUseAltW(updatePrefs) {
   React.useEffect(function () {
@@ -1026,6 +1080,15 @@ function WorkflowMapPanel(props) {
   var prefs = prefsHandle.prefs;
   var updatePrefs = prefsHandle.update;
   var snap = wfUseSnap(sessionId);
+ // When the header's refresh was last clicked; drives the one-word acknowledgement
+ // that clears itself. Deliberately NOT the poll's own state: a click must not look
+ // like a data change.
+  var refreshedPair = React.useState(0);
+  var refreshed = refreshedPair[0];
+  var setRefreshed = refreshedPair[1];
+  wfUseFlashClear(refreshed, function () {
+    setRefreshed(0);
+  });
   var settingsPair = React.useState(false);
   var settingsOpen = settingsPair[0];
   var setSettingsOpen = settingsPair[1];
@@ -1124,6 +1187,13 @@ function WorkflowMapPanel(props) {
     onToggleSettings: function () {
       setSettingsOpen(!settingsOpen);
     },
+ // The manual fallback: one pull, now, without waiting for the interval and without
+ // touching the loop. It reads the same endpoint with the same validator, so a click
+ // is a normal poll and never a second data path.
+    onRefresh: function () {
+      setRefreshed(Date.now());
+      if (typeof snap.refresh === "function") snap.refresh();
+    },
  // Clicking a main-flow unit: it becomes the SELECTED step (store.js builds its detail) and the
  // right page opens on it. It deliberately does not expand anything in place.
  // right page opens on it. It deliberately does not expand anything in place.
@@ -1202,6 +1272,7 @@ function WorkflowMapPanel(props) {
 
   return wfRenderPanel(model, prefs, say, actions, {
     settingsOpen: settingsOpen,
+    refreshed: refreshed,
     status: snap.status,
     error: snap.error,
     rev: snap.rev,
@@ -1242,6 +1313,9 @@ function wfRenderPanel(model, prefs, say, actions, ui) {
   var pendingCount = wfPendingInjectCount(model.injects);
   var extras = ui || {};
   var fire = actions || {};
+ // The refresh button's one-second acknowledgement, handed in by the component: the
+ // renderer stays pure, so a self-test can drive it with a fixed stamp.
+  var refreshed = wfFinite(extras.refreshed) === null ? 0 : extras.refreshed;
  // the two attributes the living layer needs. `motion` comes from the system's
  // prefers-reduced-motion preference (pulse.js), `idle` from the model's running flag.
  // Both live on .wf-root so the capsule is covered as well as the panel.
@@ -1341,6 +1415,24 @@ function wfRenderPanel(model, prefs, say, actions, ui) {
     h(
       "div",
       { className: "wf-btns", key: "btns" },
+ // First in the row: it is the escape hatch when the automatic poll is not
+ // delivering, so it must not be the hard one to find.
+      h(
+        "button",
+        {
+          type: "button",
+          key: "refresh",
+          className: refreshed > 0 ? "wf-btn wf-btn-ok" : "wf-btn",
+          "data-dsh-workflow-map": "refresh",
+          "data-refreshed": refreshed > 0 ? "true" : undefined,
+          title: say("panel.refresh.hint"),
+          "aria-label": say("panel.refresh"),
+          onClick: function () {
+            wfFire(fire.onRefresh);
+          },
+        },
+        refreshed > 0 ? say("panel.refresh.done") : "↻"
+      ),
       h(
         "button",
         {
@@ -1811,6 +1903,7 @@ var __test = {
   sessionIdFromSnapshot: wfSessionIdFromSnapshot,
   pollUrl: wfPollUrl,
   pollOnce: wfPollOnce,
+  pollContinues: wfPollContinues,
   parsePrefs: wfParsePrefs,
   sanitizePrefs: wfSanitizePrefs,
   applyPrefsPatch: wfApplyPrefsPatch,

package/src/client/pulse.js

@@ -53,7 +53,17 @@ function wfMotionMode(matchMediaFn) {
  * working session as idle (which would make the curve and the frame look broken).
  */
 function wfSessionRunning(view, activeNodeId, nowMs) {
-  if (view && typeof view.running === "boolean") return view.running;
+  // The clock is the second witness. view.running is the turn flag, and a turn that never
+  // received its turn/end event (interrupt, crash, a compacted session) leaves it true forever.
+  // Once the last folded event is older than the idle window the session is not working,
+  // whatever the flag says.
+  if (view && typeof view.running === "boolean") {
+    if (view.running !== true) return false;
+    var flagAsOf = wfFinite(view.asOf);
+    var flagNow = wfFinite(nowMs);
+    if (flagAsOf !== null && flagAsOf > 0 && flagNow !== null && flagNow - flagAsOf >= WF_IDLE_AFTER_MS) return false;
+    return true;
+  }
   if (typeof activeNodeId === "string" && activeNodeId !== "") return true;
   var asOf = wfFinite(view && view.asOf);
   if (asOf === null || asOf <= 0) return false;

package/src/client/store.js

@@ -175,6 +175,22 @@ function wfPollUrl(sessionId) {
   return "/dsh-workflow/state?sessionId=" + encodeURIComponent(String(sessionId));
 }
 
+/**
+ * May the poll loop re-arm after this result?
+ *
+ * A tick aborts the request it replaces, and an aborted request resolves as status -1.
+ * That is the ORDINARY path whenever a poll outlives its interval, so -1 must not end
+ * the loop: it only defers to the replacement that is already in the air. Returning
+ * false there is what keeps two loops from running; returning false for anything else
+ * (a real error, a 4xx) would stop the panel from ever updating again.
+ *
+ * Extracted from the hook so the rule is testable without a renderer.
+ */
+function wfPollContinues(result, inflight) {
+  if (!result || result.status !== -1) return true;
+  return wfFinite(inflight) === null ? true : inflight <= 0;
+}
+
 /**
  * One conditional GET. Never throws: every outcome is a value, so the loop can
  * always decide what to render and how long to wait.
@@ -365,6 +381,9 @@ function wfPlanSummary(plan) {
     }
   }
   return {
+ // A finished plan must not decide a card's status any more; the summary carries
+ // the flag so the status policy can stand down without re-reading the phase.
+    terminal: plan.terminal === true,
     statuses: plan.statuses && typeof plan.statuses === "object" ? plan.statuses : {},
     anchorSeqs: plan.anchorSeqs && typeof plan.anchorSeqs === "object" ? plan.anchorSeqs : {},
     skipped: Array.isArray(plan.skipped) ? plan.skipped.slice() : [],
@@ -878,7 +897,10 @@ function wfBuildModel(view, prefs, nowMs) {
       errorText: typeof found.error === "string" ? found.error.slice(0, 200) : "",
       seq: wfFinite(found.seq),
       error: typeof found.error === "string" && found.error !== "",
-      result: typeof found.resultHead === "string" && found.resultHead !== "",
+      // The host's result boolean is the settled fact: a call that returned with an EMPTY body is
+      // settled. Falling back to resultHead alone marked such a call unsettled, so the panel kept
+      // it in the "calling right now" state and its dot pulsed after the call had already returned.
+      result: found.result === true || (typeof found.resultHead === "string" && found.resultHead !== ""),
       durationMs: wfFinite(found.durationMs),
       at: wfFinite(found.at),
     });

package/src/client/theme.js

@@ -203,6 +203,10 @@ var WF_CSS = [
   ".wf-btn:hover{background:var(--dsw-alias-bg-layer-2,#2c3140);color:var(--dsw-alias-label-primary,#e9ecf3)}",
   ".wf-btn:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5b8cff);outline-offset:1px}",
   ".wf-btn[data-active='true']{color:var(--dsw-alias-brand-primary,#5b8cff);border-color:var(--dsw-alias-brand-primary,#5b8cff)}",
+ // The refresh button's one-second acknowledgement. Width is pinned to the glyph's own
+ // box so swapping "↻" for "已刷新" cannot shift the header row underneath the pointer.
+  ".wf-btn-ok{color:var(--dsw-alias-state-success-primary,#3fb950);border-color:var(--dsw-alias-state-success-primary,#3fb950);" +
+    "width:auto;min-width:23px;padding:0 6px;font-size:11px}",
  // Hot injection is the one header action that injects text into the RUNNING turn, so it is the
  // one that must never be hunted for: a named, filled chip that keeps its name in Chinese.
  // User feedback: "too small, still have to open it first" - so it grows to 96x30 (the other two in the row stay

package/src/fold.mjs

@@ -68,7 +68,7 @@
 // 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 STATE_VERSION = 5;
 
 export const SCHEMA_VERSION = 1;
 
@@ -548,7 +548,11 @@ function percentFor(state, step, now) {
       const value = measured;
       return { percent: clamp(value, 0, 99), source: "todos" };
     }
-    return { percent: clamp(Math.max(reported.percent, step.maxPercent), 0, 100), source: "model" };
+    // The model's latest statement is the number, and an open step is 0..99: 100 % on a running
+    // row is a claim the log does not support. The high-water record is deliberately not applied
+    // here, as the comment above states; applying it freezes a row at the highest number it ever
+    // reached, so later reports cannot move the bar.
+    return { percent: clamp(reported.percent, 0, 99), source: "model" };
   }
   // The checklist's own completion ratio — a real measurement, so it sits above the time baseline.
   // It never claims 100 % for an OPEN step: the remaining row is still in progress.
@@ -620,6 +624,10 @@ function newNode(kind, tool, title, at, extra) {
     argsText: "",
     resultHead: "",
     error: "",
+    // Whether the call returned. Separate from the body text: a call that succeeds with
+    // no output has an empty resultHead and is still settled. The browser half colours by
+    // this flag, so deriving it from resultHead leaves every silent call "running".
+    settled: false,
     at,
     durationMs: null,
     // filled by appendNode when the caller did not pass one (see toolKey).
@@ -751,6 +759,25 @@ function argsDigest(args) {
 // fold
 // ---------------------------------------------------------------------------
 
+/**
+ * Reopen a closed row without letting its 100 % speak for the reopened one.
+ *
+ * A row taken back to in_progress used to keep the percent and the high-water record of its
+ * closed state, so the panel showed an in-progress step pinned at 100 %: a bar that can never
+ * move again, and a later self-report cannot lower it. A closed record's number belongs to
+ * that closure, not to the row that reopens it.
+ */
+function reopenStep(step, time) {
+  const reopened = step.status === STEP_STATUS.done || step.status === STEP_STATUS.failed;
+  const base = {
+    ...step,
+    status: STEP_STATUS.running,
+    endedAt: null,
+    startedAt: reopened || !step.startedAt ? time : step.startedAt,
+  };
+  return reopened ? { ...base, percent: null, percentSource: "none", maxPercent: 0 } : base;
+}
+
 function foldTodos(state, event, time) {
   const data = dataOf(event);
   const raw = data && Array.isArray(data.todos) ? data.todos : [];
@@ -844,7 +871,7 @@ function foldTodos(state, event, time) {
       if (next.startedAt > 0) durations = [...durations, time - next.startedAt].filter((value) => value > 0);
     } else if (item.status === "in_progress" && next.status !== STEP_STATUS.running) {
       // A step re-opened by a re-plan or a retry: keep its ledger row, restart the clock.
-      steps[at] = { ...next, status: STEP_STATUS.running, endedAt: null, startedAt: next.startedAt || time };
+      steps[at] = reopenStep(next, time);
     } else if (next !== step) {
       steps[at] = next;
     }
@@ -863,9 +890,18 @@ function foldTodos(state, event, time) {
       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 };
+      steps[at] = reopenStep(step, 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" };
+      // Same rule for a demotion: the row is not done, so it cannot keep a done row's number.
+      steps[at] = {
+        ...step,
+        status: STEP_STATUS.pending,
+        endedAt: null,
+        startedAt: 0,
+        percent: null,
+        percentSource: "none",
+        maxPercent: 0,
+      };
     }
   }
 
@@ -965,6 +1001,8 @@ function foldToolResult(state, event, time, seq) {
     ...previous,
     resultHead: isError ? "" : line(body),
     error: isError ? line(body) : "",
+    // Settled means "the call came back", whatever its body: empty output is not a pending call.
+    settled: true,
     durationMs: previous.at > 0 && time > previous.at ? time - previous.at : null,
   };
   const answered = { ...state, asOf: time, nodes };
@@ -979,7 +1017,14 @@ function foldToolResult(state, event, time, seq) {
           ),
         }
       : answered;
-  const next = withActive(settled, previous.id, time);
+  // A result is not an activity. Re-asserting the node that just finished as the active one
+  // makes the panel claim "calling right now" about a call that already returned. Keep the
+  // node a newer call opened, and otherwise hand the highlight back to the step.
+  const keepActive =
+    state.active && typeof state.active.nodeId === "string" && state.active.nodeId !== "" && state.active.nodeId !== previous.id
+      ? state.active.nodeId
+      : null;
+  const next = withActive(settled, keepActive, time);
   // A tool result is the moment two branch decisions become possible: a job that is STILL
   // open (background) is promoted to a lane, and a launcher's acknowledgement attaches its
   // run id. Both are no-ops for ordinary calls.
@@ -2326,6 +2371,8 @@ function nodeView(node) {
     files: node.files.map((file) => ({ path: file.path, action: file.action })),
     resultHead: node.resultHead,
     error: node.error,
+    // the boolean the browser half colours by; see newNode.settled
+    result: node.settled === true,
     at: node.at,
     durationMs: node.durationMs,
     // the detail's meta line names the event that produced the node. Null for the
@@ -2458,10 +2505,24 @@ function syncToTodos(state) {
   // 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);
+    // A closed record cannot speak for an open row. When the table takes a row back to
+    // in_progress/pending, the record it is bound to may be a step this table already closed,
+    // or an older row a reworded title landed on. Keeping that percent and high-water renders
+    // a brand-new first row at 100 % the instant it appears.
+    const reopened = step.status === STEP_STATUS.done || step.status === STEP_STATUS.failed;
+    const carried = reopened
+      ? { percent: null, percentSource: "none", maxPercent: 0 }
+      : { percent: step.percent, percentSource: step.percentSource, maxPercent: step.maxPercent };
     if (row.status === "in_progress") {
-      return { ...step, status: STEP_STATUS.running, endedAt: null, startedAt: step.startedAt || state.asOf || 0 };
+      return {
+        ...step,
+        ...carried,
+        status: STEP_STATUS.running,
+        endedAt: null,
+        startedAt: reopened || !step.startedAt ? state.asOf || 0 : step.startedAt,
+      };
     }
-    return { ...step, status: STEP_STATUS.pending, endedAt: null, startedAt: 0, percent: null, percentSource: "none" };
+    return { ...step, ...carried, status: STEP_STATUS.pending, endedAt: null, startedAt: 0, percent: null, percentSource: "none" };
   };
 
   const byKey = new Map();

package/src/orchestrator.mjs

@@ -37,6 +37,21 @@ export const PLAN_VERSION = 1;
 export const PLAN_ROOT = ".pae";
 export const PLAN_FILE = "orchestrator.json";
 
+/**
+ * Plan phases that are history rather than a live view.
+ *
+ * PAE's own vocabulary (dsh-plan-and-execute): none / planning / scheduled /
+ * executing / paused / completed / aborted. The last two never resume, and the
+ * file that carries them is never removed, so they must not speak for a row the
+ * session created after the plan ended.
+ */
+const TERMINAL_PHASES = new Set(["completed", "aborted"]);
+
+/** Is this normalized plan finished? True for completed and aborted. */
+export function planIsTerminal(plan) {
+  return isRecord(plan) && TERMINAL_PHASES.has(String(plan.phase ?? "").trim().toLowerCase());
+}
+
 /** Bounds. The plan is display data; a runaway file must not grow the session cache. */
 export const MAX_PLAN_STEPS = 200;
 export const MAX_STEP_REPORTS = 200;
@@ -197,9 +212,14 @@ export function normalizePlanDocument(raw, meta) {
   }
 
   const rawTask = typeof doc.task === "string" ? doc.task : "";
+  const phase = text(doc.phase, MAX_PHASE);
   const result = {
     ver: PLAN_VERSION,
-    phase: text(doc.phase, MAX_PHASE),
+    phase,
+ // Published as a boolean as well: the browser half decides card statuses from this
+ // section alone, and "is this plan finished" must not be re-derived from a string
+ // vocabulary in two places.
+    terminal: TERMINAL_PHASES.has(phase.trim().toLowerCase()),
     task: text(rawTask, MAX_TASK),
  // The first non-empty line, before flattening: it is the panel's header.
     taskTitle: line(rawTask, MAX_TASK_TITLE),
@@ -263,6 +283,10 @@ export function applyPlanToView(view, plan) {
   const normalized = isRecord(plan) ? plan : null;
   const result = { ...view, plan: normalized };
   if (normalized === null) return result;
+ // A finished plan is published for the detail page but patches nothing: its
+ // rows belong to a turn that is over, and the current todo table is the newer
+ // statement. See planIsTerminal.
+  if (planIsTerminal(normalized)) return result;
 
   if (normalized.taskTitle !== "") result.task = normalized.taskTitle;