fix(web): verify current GUI updates end to end

.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md
-2026-07-28-web-gui-feedback-loop.md: 27295704d7b0cde3a46a6a28891545bfe31ed275
-2026-07-28-web-gui-feedback-loop.zh.md: 06367b09bd889bfb7a4052c46369720c4ec6d358
+2026-07-28-web-gui-feedback-loop.md: 039d2aebeeef903d10838a46b48e5172f0195126
+2026-07-28-web-gui-feedback-loop.zh.md: ddf748654788811aa19e2a8a295c3ff6df033fef

.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md

@@ -8,11 +8,13 @@ English | [中文](2026-07-28-web-gui-feedback-loop.zh.md)
 
 The Web agent could identify neither the GUI hosting its session nor the URL the user was viewing. The [runtime-context decision](2026-07-28-web-agent-runtime-context.md) supplies the first fact, but a GUI edit still had no executable acceptance target: source edits, artifact builds, a listening process, and the user's existing page were unrelated observations. Repository affordances made a wrong substitute look valid because `apps/web/package.json` exposed `vite` as its `dev` script and bare Vite returned HTTP 200 even though it could not inject `window.__DSH_BOOT__`.
 
-The incident session recorded three consecutive failures. After changing the theme, turn 2 delegated acceptance to the user with `pnpm run demo:tui` or an unspecified browser application and ran no assembled Web check. Turn 3 read the frontend package script, launched bare Vite on port 5173, treated HTTP 200 as readiness, and reported success; the user instead received the expected missing-`__DSH_BOOT__` white screen. Turn 4 found `dsh web`, rebuilt the shell, started an unmanaged shell-background process on port 3334, and checked only that the new page returned 200 with a boot manifest. It never probed the existing port 3081. In fact, the port-3081 process predated the build, and its static host read the rebuilt dist on the next request, so refreshing the original page already showed the change. Only after the user reported that fact did turn 5 inspect port 3081 and remove the redundant server.
+The [incident post-mortem](../../../../docs/postmortem/0003-web-agent-gui-feedback-loop.md) owns the event-log timeline and why the original checks accepted the wrong page, process, and port.
 
 ## Decision
 
-`dsh web` publishes one canonical loopback URL as both model-visible orientation and a managed shell fact. The `app:web-surface` prompt section says that unqualified references identify this GUI, names the URL, and defines acceptance as rebuilding the affected Web artifacts and verifying that existing URL after refresh. `DSH_WEB_URL` carries the same value into every foreground or managed background bash call, so the agent can query the target without parsing prose or process listings. The section preserves the no-implicit-DOM, route, or screenshot boundary and does not claim that a LAN alias equals the browser's literal address.
+`dsh web` publishes one canonical loopback URL and its actual runtime mode as both model-visible orientation and managed shell facts. The `app:web-surface` prompt section says that unqualified references identify this GUI and names the URL; `DSH_WEB_URL` and `DSH_WEB_MODE=production|development` carry the same facts into every foreground or managed background bash call. The section preserves the no-implicit-DOM, route, or screenshot boundary and does not claim that a LAN alias equals the browser's literal address.
+
+The mode-specific prompt makes the agent, rather than the user, own the hidden startup contract. Production mode defines acceptance as rebuilding the affected artifacts and refreshing the existing URL. Development mode states that `dsh web --dev` activates only the HMR receiver: automatic client-plugin reload additionally requires a same-checkout `pnpm run dev:web` watcher, which the agent verifies before promising no-refresh updates. Shell and other plain-package changes still require rebuild plus refresh. An agent in production mode explains both commands when a user requests no-refresh updates; it does not launch a replacement GUI unless asked.
 
 The `apps/web` development script and Vite configuration reject serve mode before opening a port. Their diagnostics identify `apps/web` as a build-only shell, explain that only `dsh web` injects `window.__DSH_BOOT__`, and name the production and HMR entry paths. Vite build mode remains unchanged.
 
@@ -20,7 +22,7 @@ No server restart or replacement is required merely because static artifacts cha
 
 ## Verification
 
-The keyless fresh-round-trip browser scenario boots the shipped Web composition, drives a real replayed session, snapshots the URL-bearing system-prompt prefix, and invokes the assembled bash tool to prove `$DSH_WEB_URL` equals the scaffold's actual bound URL. A real Vite subprocess test requires serve mode to exit nonzero with the full-host correction. The real-Loader webserver test rewrites a static asset after the process binds and proves the same port returns the new bytes. These assertions inspect prompt state, process exit, shell output, and HTTP bytes rather than an agent's success statement.
+The keyless fresh-round-trip browser scenario boots the shipped production Web composition, drives a real replayed session, snapshots the URL/mode-bearing system-prompt prefix, and invokes the assembled bash tool to prove `$DSH_WEB_URL` and `$DSH_WEB_MODE` match the actual bound runtime. The real CLI smoke launches `dsh web --dev` and captures the provider request, pinning the complete two-command development contract. The `dev:web` watcher test rebuilds an isolated client bundle after a source change; the browser HMR scenario launches `dsh web --dev`, changes an initial production-roster bundle, and observes the new DOM under the same page identity. A real Vite subprocess test requires serve mode to exit naturally with the full-host correction and instruments `Server.listen()` to prove it was never called. The real-Loader webserver test rewrites a static asset after the process binds and proves the same port returns the new bytes. These assertions inspect prompt state, process exit, shell output, DOM identity, and HTTP bytes rather than an agent's success statement.
 
 ## Alternatives considered
 
@@ -34,4 +36,4 @@ The keyless fresh-round-trip browser scenario boots the shipped Web composition,
 
 ## Consequences
 
-Web prompts gain a dynamic URL paragraph, so provider prefix reuse now varies by bound port. Bash processes gain one non-secret managed environment variable. Bare Vite can no longer be used as a shell-only visual sandbox; developers use the full host or build mode instead. In exchange, GUI work has one mechanically observable target, the unsupported startup path fails before a white screen, and a second port can no longer masquerade as proof that the user's current page changed.
+Web prompts gain a dynamic URL-and-mode paragraph, so provider prefix reuse now varies by bound port and mode. Bash processes gain two non-secret managed environment variables. Bare Vite can no longer be used as a shell-only visual sandbox; developers use the full host or build mode instead. In exchange, GUI work has one mechanically observable target, the agent can teach the user the exact update behavior of the process actually serving their session, and the unsupported startup path fails before a white screen. The URL/mode contract guides the agent away from replacement ports; it does not prohibit arbitrary shell commands from starting one.

.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md

@@ -8,19 +8,21 @@ Status: implemented
 
 Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道用户正在查看哪个 URL。[运行时上下文决策](2026-07-28-web-agent-runtime-context.md)提供前一项事实，但 GUI 编辑仍然没有可执行的验收目标：源码编辑、产物构建、监听中的进程与用户已打开的页面只是互不关联的观察结果。仓库提供的入口让错误的替代方案显得合理，因为 `apps/web/package.json` 将 `vite` 暴露为 `dev` 脚本，而裸 Vite 即使无法注入 `window.__DSH_BOOT__`，仍会返回 HTTP 200。
 
-事故会话记录了连续三次失败。修改主题后，第 2 轮把验收交给用户，要求用户运行 `pnpm run demo:tui` 或打开某个未指明的浏览器应用，自己没有执行任何真实组装的 Web 验证。第 3 轮读取前端包脚本，在 5173 端口启动裸 Vite，把 HTTP 200 当作就绪并报告成功；用户看到的却是符合预期的缺少 `__DSH_BOOT__` 的白屏。第 4 轮找到 `dsh web`，重新构建 Web 外壳，在 3334 端口启动了一个不受管理的 shell 后台进程，并且只检查新页面是否能返回 200 和启动 manifest（元数据清单），始终没有探测现有的 3081 端口。事实上，3081 端口的进程早于此次构建启动，其静态宿主会在下一次请求时读取重新构建的 dist，因此刷新原页面就已经能看到改动。直到用户报告这一事实，第 5 轮才检查 3081 端口并移除冗余服务。
+[事故复盘](../../../../docs/postmortem/0003-web-agent-gui-feedback-loop.md)记录事件日志时间线，以及原有检查为何会接受错误的页面、进程和端口。
 
 ## 决策
 
-`dsh web` 发布一个规范的回环 URL，同时将其作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 系统提示词段说明：未加限定的指代指向此 GUI；该段会给出 URL，并把验收定义为重新构建受影响的 Web 产物，然后刷新并验证现有 URL。`DSH_WEB_URL` 会把同一个值传入每次前台或受管后台 bash 调用，使 agent 无需解析提示词或进程列表即可查询目标。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。
+`dsh web` 发布一个规范的回环 URL 及其实际运行时模式，同时将二者作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 提示词段说明：未加限定的指代指向此 GUI，并给出 URL；`DSH_WEB_URL` 和 `DSH_WEB_MODE=production|development` 会把同样的事实传入每次前台或受管后台 bash 调用。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。
 
-`apps/web` 开发脚本和 Vite 配置都会在打开端口前拒绝服务模式。诊断信息会指出 `apps/web` 只是一个仅供构建的外壳，说明只有 `dsh web` 才会注入 `window.__DSH_BOOT__`，并给出生产入口与 HMR（热模块替换）入口路径。Vite 构建模式保持不变。
+按模式区分的提示词让 agent 而非用户负责隐藏的启动契约。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。
+
+`apps/web` 开发脚本和 Vite 配置都会在打开端口前拒绝服务模式。诊断信息会指出 `apps/web` 只是一个仅供构建的外壳，说明只有 `dsh web` 才会注入 `window.__DSH_BOOT__`，并给出生产入口与 HMR 入口路径。Vite 构建模式保持不变。
 
 静态产物发生变化时，不需要仅为此重启或替换服务器。宿主会在每次请求时读取 `index.html` 和静态资源，客户端 bundle 也会从当前文件提供，并设置 `no-cache`；因此，重新构建相关外壳与插件 bundle 后，刷新现有 URL 就是验收路径。启动另一个服务器只能证明另一个服务器可用。如果用户明确要求再启动一个长期运行的服务器，则现有受管后台任务契约负责其生命周期和完成通知；shell `&` 不能替代这套生命周期机制。
 
 ## 验证
 
-无密钥的 fresh-round-trip 浏览器场景会启动已交付的 Web 组合，驱动真实的回放会话，对包含 URL 的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 等于测试脚手架实际绑定的 URL。真实 Vite 子进程测试要求服务模式以非零状态退出，并给出改用完整宿主的纠正信息。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出和 HTTP 字节，而不是 agent 的成功声明。
+无密钥的 fresh-round-trip 浏览器场景会启动已交付的生产 Web 组合，驱动真实的回放会话，对包含 URL 和模式的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 和 `$DSH_WEB_MODE` 与实际绑定的运行时一致。真实 CLI 冒烟测试会启动 `dsh web --dev` 并捕获模型提供方请求，从而固定完整的双命令开发契约。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web --dev`，修改生产初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。
 
 ## 考虑过的替代方案
 
@@ -34,4 +36,4 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 ## 影响
 
-Web 提示词会增加一个动态 URL 段落，因此模型提供方的前缀复用会随绑定端口变化。Bash 进程会增加一个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，不受支持的启动路径会在出现白屏前失败，另一个端口也无法再冒充用户当前页面已经改动的证据。
+Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式契约会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。

apps/cli/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/README.md
-README.md: 3ec427a0bca501d70c9bca938692d6ef9557a2dd
-README.zh.md: e0cf7cd399858822df613a98890c0872554a5085
+README.md: 22bcd3e7dc8fafdf5c9608ef56230b3bd62e4a80
+README.zh.md: c28989de2b19c172998c876574eeb893a3aa4f92

apps/cli/README.md

@@ -14,7 +14,7 @@ The TUI surface:
 - tells the agent where its own source lives: after boot it adds a prompt section naming this harness checkout, resolved from the launcher's real path so it holds under a PATH symlink and an arbitrary cwd, so the self-referential `cordis` toolset can read and modify it;
 - applies the personal overlay from `~/.dsh` (see [app-boot's Personal config](../../packages/ui/app-boot/README.md#personal-config)): `.env` fills environment gaps (ambient > project `.env` > personal `.env`), `config.yaml` patches the booted tree.
 
-The Web and headless surfaces boot one shared composition (`cordis.yml`): both tell the coding agent its model and session working directory, treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root <path>` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, and opt into first-message model titles. Web additionally names the DeepSeek Harness Web GUI as the interaction surface, this checkout as its own source location, and the process's canonical local URL in both the prompt and `$DSH_WEB_URL`; references such as “this page” therefore identify the GUI without claiming access to implicit DOM, route, or screenshot state. The Web host reads frontend dist and client bundles when requests arrive, so rebuilding the affected artifacts and refreshing the existing URL updates that GUI without replacing its process; bare `apps/web` Vite serving fails because it cannot inject `window.__DSH_BOOT__`. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`).
+The Web and headless surfaces boot one shared composition (`cordis.yml`): both tell the coding agent its model and session working directory, treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root <path>` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, and opt into first-message model titles. Web additionally names the DeepSeek Harness Web GUI as the interaction surface, this checkout as its own source location, and the process's canonical local URL and mode in both the prompt and managed `$DSH_WEB_URL`/`$DSH_WEB_MODE`; references such as “this page” therefore identify the GUI without claiming access to implicit DOM, route, or screenshot state. In production mode the host reads rebuilt frontend dist and client bundles on the next request, so refreshing the existing URL updates that GUI without replacing its process. `dsh web --dev` mounts the client-plugin HMR receiver, but no-refresh updates additionally require `pnpm run dev:web` in the same checkout to watch and rebuild plugin bundles; shell and plain-package changes still require a rebuild and page refresh. Bare `apps/web` Vite serving fails because it cannot inject `window.__DSH_BOOT__`. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`).
 
 `DSH_TOOLS_MODE` selects the tool presentation mode for the whole Web/headless process: `native` (the schema default when unset), `code` (the `run_code`-only Code Mode wire), or `both`; any other value fails loud at boot through the `dsh-tools` config schema. It is a TEMPORARY seam — process-wide because Loader composition is static — and is removed once the web UI owns per-session tool-mode selection; the TUI surface ignores it (its config tree pins its own mode).
 

apps/cli/README.zh.md

@@ -14,7 +14,7 @@ TUI 界面：
 - 告知 agent 自身源码所在位置：启动后添加一个命名此 harness checkout 的提示词段。该路径从启动器的真实路径解析，因此在 PATH 符号链接和任意 cwd 下仍然有效，使自指的 `cordis` 工具集可以读取并修改它；
 - 应用 `~/.dsh` 中的个人覆盖（参见 [app-boot 的个人配置](../../packages/ui/app-boot/README.md#personal-config)）：`.env` 填补环境缺口（环境中已有的值 > 项目 `.env` > 个人 `.env`），`config.yaml` 则修补已启动的树。
 
-Web 和无头界面启动同一个共享组合（`cordis.yml`）：两者都会告知编码 agent 所用模型和会话工作目录，将调用目录视为默认项目和 Workspace 根目录，除非通过 `--workspace-root <path>` 覆盖，否则会在该根目录下创建具名 Workspace；它们会把适用的 `AGENTS.md`/`CLAUDE.md` 指令加载到每个 agent-loop 请求前缀中，渲染预算为 65,536 字节，并选用首条消息模型标题。Web 还会明确说明交互界面是 DeepSeek Harness Web GUI、当前 checkout 是自身源码位置，并在提示词和 `$DSH_WEB_URL` 中提供该进程的规范本地 URL；因此，「这个页面」等表述会指向该 GUI，但 agent 不会声称可以访问未显式提供的 DOM、路由或截图状态。Web 宿主会在收到请求时读取前端 dist 和客户端 bundle，因此重新构建受影响的产物并刷新现有 URL 即可更新该 GUI，无须替换其进程；直接使用裸 `apps/web` Vite 服务会失败，因为它无法注入 `window.__DSH_BOOT__`。无头界面唯一的差异是监听操作系统分配的端口（并行 `dsh -p` 运行绝不冲突；stderr 打印的 URL 会在浏览器中打开实时会话）。两者都需要先构建前端 dist 和客户端 bundle（`pnpm run build && pnpm run build:web`）。
+Web 和无头界面启动同一个共享组合（`cordis.yml`）：两者都会告知编码 agent 所用模型和会话工作目录，将调用目录视为默认项目和 Workspace 根目录，除非通过 `--workspace-root <path>` 覆盖，否则会在该根目录下创建具名 Workspace；它们会把适用的 `AGENTS.md`/`CLAUDE.md` 指令加载到每个 agent-loop 请求前缀中，渲染预算为 65,536 字节，并选用首条消息模型标题。Web 还会明确说明交互界面是 DeepSeek Harness Web GUI、当前 checkout 是自身源码位置，并在提示词及受管的 `$DSH_WEB_URL`/`$DSH_WEB_MODE` 中提供该进程的规范本地 URL 和模式；因此，「这个页面」等表述会指向该 GUI，但 agent 不会声称可以访问未显式提供的 DOM、路由或截图状态。在生产模式下，宿主会在下次请求时读取重新构建的前端 dist 和客户端 bundle，因此刷新现有 URL 即可更新该 GUI，无须替换其进程。`dsh web --dev` 会挂载客户端插件的 HMR（热模块替换）接收端，但要实现无刷新更新，还需在同一 checkout 中运行 `pnpm run dev:web`，以监视并重新构建插件 bundle；shell 和普通包（package）的更改仍需重新构建并刷新页面。直接使用裸 `apps/web` Vite 服务会失败，因为它无法注入 `window.__DSH_BOOT__`。无头界面唯一的差异是监听操作系统分配的端口（并行 `dsh -p` 运行绝不冲突；stderr 打印的 URL 会在浏览器中打开实时会话）。两者都需要先构建前端 dist 和客户端 bundle（`pnpm run build && pnpm run build:web`）。
 
 `DSH_TOOLS_MODE` 为整个 Web／无头进程选择工具呈现模式：可选值为 `native`（未设置时的 schema 默认值）、`code`（仅含 `run_code` 的 Code Mode 协议接口）或 `both`；任何其他值都会经由 `dsh-tools` 配置 schema 在启动时明确报错。它是一个临时 seam：Loader 组合是静态的，因此该设置作用于整个进程；待 Web UI 负责逐会话工具模式选择后便会移除。TUI 界面会忽略该变量（其配置树固定了自身模式）。
 

apps/cli/src/args.ts

@@ -115,7 +115,7 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
   web
     .option('--host <host>', 'override the config bind host (127.0.0.1 or 0.0.0.0)')
     .option('--port <port>', 'override the config listen port (0 requests an OS-assigned port)')
-    .option('--dev', 'mount the client HMR driver and watch plugin bundles for rebuilds')
+    .option('--dev', 'mount the client-plugin HMR receiver (run pnpm run dev:web separately to rebuild bundles)')
     .option('--workspace-root <path>', 'parent directory for name-created workspaces')
     .action((options: WebOptions) => {
       // Commander parses the parent (default-surface) options on either side of

apps/cli/src/web.ts

@@ -18,13 +18,23 @@ const CONFIG_PATH = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
 
 const DSH_WEB_URL = 'DSH_WEB_URL' as const
+const DSH_WEB_MODE = 'DSH_WEB_MODE' as const
+
+type WebMode = 'production' | 'development'
 
 /** Model-visible orientation and acceptance boundary for sessions created through `dsh web`. */
-function webSurfacePrompt(webUrl: string): string {
+function webSurfacePrompt(webUrl: string, mode: WebMode): string {
+  const updateContract = mode === 'development'
+    ? 'This Web process was launched with `dsh web --dev`, so its client-plugin HMR receiver is active. '
+      + 'No-refresh updates occur only when `pnpm run dev:web` is also running from this same checkout to rebuild client-plugin bundles; verify that watcher before promising automatic updates. '
+      + 'Client-plugin changes then reload automatically, while apps/web shell and other plain-package changes still require a rebuild and page refresh. '
+    : 'This Web process was launched without `--dev`, so HMR is inactive: rebuild the affected Web artifacts and verify this existing URL after a page refresh. '
+      + 'If the user wants no-refresh client-plugin updates, explain that this GUI must be restarted with `dsh web --dev` and `pnpm run dev:web` must also run from this same checkout; do not present either command alone as sufficient. '
   return `You are interacting with the user through the DeepSeek Harness Web GUI at ${webUrl}. `
     + 'When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. '
     + 'The browser provides no implicit DOM, route, or screenshot context. '
-    + 'For changes to this GUI, rebuild the affected Web artifacts and verify this existing URL after a refresh; starting another server does not update this GUI. '
+    + updateContract
+    + 'Starting another server does not update this GUI. '
     + 'The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. '
     + 'Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.'
 }
@@ -37,20 +47,22 @@ function webSurfacePrompt(webUrl: string): string {
  * @param ctx - settled Web application context.
  * @param sourceRoot - absolute checkout root resolved from the launcher module.
  * @param webUrl - canonical loopback URL printed by this Web process.
+ * @param mode - whether this process mounted the client-plugin HMR receiver.
  */
-export function installWebPromptContext(ctx: Context, sourceRoot: string, webUrl: string): void {
+export function installWebPromptContext(ctx: Context, sourceRoot: string, webUrl: string, mode: WebMode): void {
   const systemPrompt = ctx.get('systemPrompt')
   if (systemPrompt === undefined) throw new Error('dsh web: systemPrompt service missing after settled boot')
   const bashEnv = ctx.get('bashEnv')
   if (bashEnv === undefined) throw new Error('dsh web: bashEnv service missing after settled boot')
   addHarnessSourceSection(ctx, sourceRoot)
-  systemPrompt.section({ name: 'app:web-surface', order: -98, text: webSurfacePrompt(webUrl) })
+  systemPrompt.section({ name: 'app:web-surface', order: -98, text: webSurfacePrompt(webUrl, mode) })
   bashEnv.register({
     name: 'web-runtime',
     variables: {
       [DSH_WEB_URL]: { description: 'Canonical local URL of the DeepSeek Harness Web GUI serving this session.' },
+      [DSH_WEB_MODE]: { description: 'Web runtime mode: production, or development when the client-plugin HMR receiver is active.' },
     },
-    resolve: () => ({ [DSH_WEB_URL]: webUrl }),
+    resolve: () => ({ [DSH_WEB_URL]: webUrl, [DSH_WEB_MODE]: mode }),
   })
 }
 
@@ -65,7 +77,7 @@ const ALL_INTERFACES_HOST = '0.0.0.0'
  * through only when the flag was given; absent, the `cordis.yml` value stands.
  * @param host - the bind host, or `undefined` to keep the config default.
  * @param port - the listen port (`0` requests an OS-assigned port), or `undefined` to keep the config default.
- * @param dev - mount the client HMR driver and watch plugin bundles for rebuilds.
+ * @param dev - mount the client HMR receiver; `pnpm run dev:web` separately rebuilds watched plugin bundles.
  * @param workspaceRoot - parent directory for name-created workspaces, or `undefined` for the gateway's cwd fallback.
  */
 export async function runWeb(
@@ -83,7 +95,8 @@ export async function runWeb(
   })
   const { ctx, port: boundPort } = await entry.run()
   const localUrl = `http://${LOOPBACK_HOST}:${boundPort}`
-  installWebPromptContext(ctx, SOURCE_ROOT, localUrl)
+  const mode: WebMode = dev ? 'development' : 'production'
+  installWebPromptContext(ctx, SOURCE_ROOT, localUrl, mode)
 
   let exiting = false
   const shutdown = (code: number): void => {

apps/web/package.json

@@ -10,7 +10,7 @@
   },
   "scripts": {
     "build": "vite build",
-    "dev": "node -e \"console.error('apps/web is build-only; run dsh web or dsh web --dev with pnpm run dev:web') ; process.exit(1)\"",
+    "dev": "vite",
     "watch": "vite build --watch"
   },
   "license": "BSD-3-Clause",

apps/web/tests/hmr-live.e2e.ts

@@ -0,0 +1,132 @@
+/** Published dsh web --dev + pnpm dev:web → browser HMR, with no page reload. */
+
+import { existsSync } from 'node:fs'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { chromium } from 'playwright'
+import { expect, it } from 'vitest'
+import { Context } from 'cordis'
+import type { Fiber } from 'cordis'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import { REPO_ROOT } from './support.ts'
+
+function spawnSpec(argv: readonly string[], cwd: string, env?: Record<string, string>): SubprocessSpawnSpec {
+  return {
+    argv,
+    cwd,
+    stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' },
+    graceMs: 5_000,
+    ...env === undefined ? {} : { env },
+  }
+}
+
+function waitForOutput(child: SubprocessHandle, pattern: RegExp, label: string): Promise<string> {
+  return new Promise((resolveReady, reject) => {
+    let output = ''
+    let settled = false
+    const cleanup = (): void => {
+      clearTimeout(timer)
+      child.stdout?.off('data', onData)
+      child.stderr?.off('data', onData)
+    }
+    const resolveOnce = (value: string): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      resolveReady(value)
+    }
+    const rejectOnce = (error: Error): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      reject(error)
+    }
+    const onData = (chunk: Buffer): void => {
+      output += chunk.toString()
+      const match = pattern.exec(output)
+      if (match === null) return
+      resolveOnce(match[1] ?? match[0])
+    }
+    const timer = setTimeout(() => { rejectOnce(new Error(`${label} not ready:\n${output}`)) }, 60_000)
+    child.stdout?.on('data', onData)
+    child.stderr?.on('data', onData)
+    void child.done.then((outcome) => {
+      rejectOnce(new Error(`${label} exited before ready (${JSON.stringify(outcome)}):\n${output}`))
+    }, (error: unknown) => {
+      rejectOnce(new Error(`${label} failed before ready:\n${output}`, { cause: error }))
+    })
+  })
+}
+
+async function stopTree(child: SubprocessHandle): Promise<void> {
+  child.terminate()
+  const stopped = await child.waitForExit(AbortSignal.timeout(15_000))
+  if (!stopped) throw new Error(`process tree ${String(child.pid)} did not stop after termination escalation`)
+  await child.done
+}
+
+it('hot-reloads a real client-plugin source edit without refreshing the page', async () => {
+  const world = await mkdtemp(join(tmpdir(), 'dsh-web-hmr-world-'))
+  const sourcePath = join(REPO_ROOT, 'packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx')
+  const bundlePath = join(REPO_ROOT, 'packages/client/ui-conversation/lib/client.js')
+  const binPath = join(REPO_ROOT, 'apps/cli/lib/bin.js')
+  if (!existsSync(binPath)) throw new Error('HMR browser test needs the built dsh bin; run pnpm run build first')
+  const originalSource = await readFile(sourcePath)
+  const originalBundle = await readFile(bundlePath)
+  const oldText = "Let's start building"
+  const sourceNeedle = 'Let&apos;s start building'
+  const newText = `HMR UPDATED ${'x'.repeat(80)}`
+  const updatedSource = originalSource.toString().replace(sourceNeedle, newText)
+  if (updatedSource === originalSource.toString()) throw new Error(`HMR source lacks ${JSON.stringify(sourceNeedle)}`)
+
+  const subprocessCtx = new Context()
+  let subprocessFiber: Fiber | undefined
+  let watcher: SubprocessHandle | undefined
+  let host: SubprocessHandle | undefined
+  let browser: Awaited<ReturnType<typeof chromium.launch>> | undefined
+  const failures: unknown[] = []
+  try {
+    subprocessFiber = await subprocessCtx.plugin(LocalSubprocessService)
+    watcher = subprocessCtx.subprocess.spawn(spawnSpec(['pnpm', 'run', 'dev:web'], REPO_ROOT))
+    await waitForOutput(watcher, /dev-web: watching/, 'pnpm run dev:web')
+    host = subprocessCtx.subprocess.spawn(spawnSpec(
+      [process.execPath, binPath, 'web', '--dev', '--port', '0'],
+      world,
+      {
+        DEEPSEEK_API_KEY: 'keyless-hmr-no-call',
+        DSH_HOME: join(world, '.dsh'),
+      },
+    ))
+    const baseUrl = await waitForOutput(host, /dsh web: (http:\/\/[^\s]+)/, 'built dsh web --dev')
+    browser = await chromium.launch()
+    const page = await browser.newPage()
+    const pageErrors: string[] = []
+    page.on('pageerror', error => pageErrors.push(String(error)))
+    await page.goto(baseUrl, { waitUntil: 'load' })
+    await page.getByText(oldText, { exact: true }).waitFor({ timeout: 15_000 })
+    const pageIdentity = await page.evaluate(() => {
+      const identity = crypto.randomUUID()
+      Object.defineProperty(window, '__dshHmrPageIdentity', { value: identity })
+      return identity
+    })
+
+    await writeFile(sourcePath, updatedSource)
+    await page.getByText(newText, { exact: true }).waitFor({ timeout: 30_000 })
+    expect(await page.evaluate(() => (window as Window & { __dshHmrPageIdentity?: string }).__dshHmrPageIdentity))
+      .toBe(pageIdentity)
+    expect(pageErrors).toEqual([])
+  } catch (error) {
+    failures.push(error)
+  } finally {
+    await writeFile(sourcePath, originalSource).catch((error: unknown) => failures.push(error))
+    if (watcher !== undefined) await stopTree(watcher).catch((error: unknown) => failures.push(error))
+    await writeFile(bundlePath, originalBundle).catch((error: unknown) => failures.push(error))
+    if (host !== undefined) await stopTree(host).catch((error: unknown) => failures.push(error))
+    await browser?.close().catch((error: unknown) => failures.push(error))
+    await subprocessFiber?.dispose().catch((error: unknown) => failures.push(error))
+    await rm(world, { recursive: true, force: true }).catch((error: unknown) => failures.push(error))
+  }
+  if (failures.length > 0) throw new AggregateError(failures, 'HMR browser test or cleanup failed')
+}, 120_000)

apps/web/tests/replay-round-trip.e2e.ts

@@ -101,14 +101,14 @@ describe('web e2e: fresh round trip through the real assembly', () => {
       callId: CallId('web-url-probe'),
       name: 'bash',
       arguments: {
-        command: 'printf \'%s\\n\' "$DSH_WEB_URL"',
-        description: 'Print current Web URL',
+        command: 'printf \'%s\\n%s\\n\' "$DSH_WEB_URL" "$DSH_WEB_MODE"',
+        description: 'Print current Web runtime',
       },
       agent,
     })
     expect(result.isError).toBe(false)
     expect(result.content.filter(block => block.type === 'text').map(block => block.text).join(''))
-      .toBe(`${scaffold.baseUrl}\n`)
+      .toBe(`${scaffold.baseUrl}\nproduction\n`)
   })
 
   it.skipIf(MODE === 'record')('rendered the settled turn: markdown, tool row, composer restore', async () => {

apps/web/tests/scaffold.ts

@@ -208,7 +208,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
       throw new Error('web e2e scaffold: httpServer service missing after settled boot')
     }
     port = boundPort
-    installWebPromptContext(ctx, REPO_ROOT, `http://127.0.0.1:${String(port)}`)
+    installWebPromptContext(ctx, REPO_ROOT, `http://127.0.0.1:${String(port)}`, 'production')
 
     // Fill the open llm seam on the settled root ctx (llm-deepseek is disabled
     // in keyless modes; a scenario with no fixture leaves the seam empty so a

apps/web/tests/smoke-real.e2e.ts

@@ -20,12 +20,14 @@ import { createServer } from 'node:http'
 import { createRequire } from 'node:module'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import { REPO_ROOT, connectFreshWorkspace, probeFreePort, requireDist, saveFailureShot } from './support.ts'
 
+const DEVELOPMENT_PROMPT = fileURLToPath(new URL('./snapshots/web-runtime-context/development-prompt.expected.md', import.meta.url))
+
 function waitForReadyLine(child: ChildProcess): Promise<string> {
   return new Promise((resolveReady, reject) => {
     let out = ''
@@ -180,7 +182,7 @@ describe('dsh web keyless CLI smoke', () => {
     }
   })
 
-  it('injects the invoking workspace AGENTS.md into the provider request', async () => {
+  it('routes --dev runtime context and workspace instructions through the real CLI request', async () => {
     requireDist()
     const workspace = mkdtempSync(join(tmpdir(), 'dsh-web-workspace-'))
     mkdirSync(join(workspace, '.git'))
@@ -212,7 +214,7 @@ describe('dsh web keyless CLI smoke', () => {
     const tsxLoader = pathToFileURL(createRequire(join(REPO_ROOT, 'package.json')).resolve('tsx')).href
     const child = spawn(
       process.execPath,
-      ['--import', tsxLoader, join(REPO_ROOT, 'apps/cli/src/bin.ts'), 'web', '--port', '0'],
+      ['--import', tsxLoader, join(REPO_ROOT, 'apps/cli/src/bin.ts'), 'web', '--port', '0', '--dev'],
       {
         cwd: workspace,
         env: {
@@ -241,6 +243,10 @@ describe('dsh web keyless CLI smoke', () => {
       ])
       const workspaceMessage = captured.messages?.find(message =>
         message.role === 'user' && message.content?.includes('web-workspace-context-probe'))
+      const systemMessage = captured.messages?.find(message => message.role === 'system')
+      const expectedWebSection = readFileSync(DEVELOPMENT_PROMPT, 'utf8').trimEnd()
+        .replace('{{webUrl}}', baseUrl)
+      expect(systemMessage?.content).toContain(expectedWebSection)
       expect(workspaceMessage).toMatchInlineSnapshot(`
         {
           "content": "<system-reminder>

apps/web/tests/snapshots/fresh-round-trip/system-prompt.expected.md

@@ -2,6 +2,6 @@ You are an AI agent powered by the DeepSeek Harness SDK.
 
 Your own source code is the checkout at {{sourceRoot}}; you can read it there to learn how dsh works and how to extend it.
 
-You are interacting with the user through the DeepSeek Harness Web GUI at {{webUrl}}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. For changes to this GUI, rebuild the affected Web artifacts and verify this existing URL after a refresh; starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.
+You are interacting with the user through the DeepSeek Harness Web GUI at {{webUrl}}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. This Web process was launched without `--dev`, so HMR is inactive: rebuild the affected Web artifacts and verify this existing URL after a page refresh. If the user wants no-refresh client-plugin updates, explain that this GUI must be restarted with `dsh web --dev` and `pnpm run dev:web` must also run from this same checkout; do not present either command alone as sufficient. Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.
 
 You are a coding agent powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.

apps/web/tests/snapshots/web-runtime-context/development-prompt.expected.md

@@ -0,0 +1 @@
+You are interacting with the user through the DeepSeek Harness Web GUI at {{webUrl}}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. This Web process was launched with `dsh web --dev`, so its client-plugin HMR receiver is active. No-refresh updates occur only when `pnpm run dev:web` is also running from this same checkout to rebuild client-plugin bundles; verify that watcher before promising automatic updates. Client-plugin changes then reload automatically, while apps/web shell and other plain-package changes still require a rebuild and page refresh. Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.

apps/web/tests/support/listen-probe.mjs

@@ -0,0 +1,9 @@
+import { appendFileSync } from 'node:fs'
+import { Server } from 'node:net'
+
+const marker = process.env.DSH_LISTEN_PROBE_MARKER
+const listen = Server.prototype.listen
+Server.prototype.listen = function (...args) {
+  if (marker !== undefined) appendFileSync(marker, 'listen\n')
+  return listen.apply(this, args)
+}

apps/web/tests/vite-entry.e2e.ts

@@ -1,7 +1,9 @@
 /** Bare Vite must fail before it can present a bootless shell as a working GUI. */
 
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { join } from 'node:path'
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { createServer } from 'node:net'
 import { execa } from 'execa'
 import { describe, expect, it } from 'vitest'
@@ -28,29 +30,34 @@ describe('Web development entry', () => {
   it('rejects the package dev alias with the full-host correction', async () => {
     const result = await execa('pnpm', ['run', 'dev'], { cwd: WEB_ROOT, reject: false })
     expect(result.exitCode).not.toBe(0)
-    expect(result.stderr).toContain('apps/web is build-only')
+    expect(result.stderr).toContain('apps/web is not a standalone application')
     expect(result.stderr).toContain('dsh web')
   })
 
   it('rejects the standalone Vite server with the full-host correction', async () => {
+    const probeRoot = mkdtempSync(join(tmpdir(), 'dsh-vite-listen-probe-'))
+    const marker = join(probeRoot, 'listen-called')
     const port = await freePort()
-    const result = await execa(join(WEB_ROOT, 'node_modules/.bin/vite'), ['--host', '127.0.0.1', '--port', String(port)], {
-      cwd: WEB_ROOT,
-      reject: false,
-      timeout: 10_000,
-    })
-    expect(result.timedOut).toBe(false)
-    expect(result.exitCode).not.toBe(0)
-    expect(result.stderr).toContain('apps/web is not a standalone application')
-    expect(result.stderr).toContain('dsh web')
-    expect(result.stderr).toContain('window.__DSH_BOOT__')
-    await expect(new Promise<void>((resolve, reject) => {
-      const probe = createServer()
-      probe.once('error', reject)
-      probe.listen(port, '127.0.0.1', () => probe.close((error) => {
-        if (error === undefined) resolve()
-        else reject(error)
-      }))
-    })).resolves.toBeUndefined()
+    try {
+      const probeModule = fileURLToPath(new URL('./support/listen-probe.mjs', import.meta.url))
+      const result = await execa(join(WEB_ROOT, 'node_modules/.bin/vite'), ['--host', '127.0.0.1', '--port', String(port)], {
+        cwd: WEB_ROOT,
+        reject: false,
+        timeout: 10_000,
+        env: {
+          ...process.env,
+          DSH_LISTEN_PROBE_MARKER: marker,
+          NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --import ${pathToFileURL(probeModule).href}`.trim(),
+        },
+      })
+      expect(result.timedOut).toBe(false)
+      expect(result.exitCode).not.toBe(0)
+      expect(result.stderr).toContain('apps/web is not a standalone application')
+      expect(result.stderr).toContain('dsh web')
+      expect(result.stderr).toContain('window.__DSH_BOOT__')
+      expect(existsSync(marker), 'Vite called Server.listen before rejecting standalone serve mode').toBe(false)
+    } finally {
+      rmSync(probeRoot, { recursive: true, force: true })
+    }
   })
 })

apps/web/tsconfig.json

@@ -31,6 +31,7 @@
     "tests/settings-chrome.e2e.ts",
     "tests/workspace-management.e2e.ts",
     "tests/replay-round-trip.e2e.ts",
+    "tests/hmr-live.e2e.ts",
     "tests/seeded-history.e2e.ts",
     "tests/code-mode-round.e2e.ts",
     "tests/cordis-tool-round.e2e.ts"

docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/postmortem/0003-web-agent-gui-feedback-loop.md
+0003-web-agent-gui-feedback-loop.md: 13d13a607babfe7f5ddfdb6773c94f973bbef0db
+0003-web-agent-gui-feedback-loop.zh.md: b3d35db9092304fcbca1106c0289fef441a2bad3

docs/postmortem/0003-web-agent-gui-feedback-loop.md

@@ -0,0 +1,53 @@
+# Post-mortem 0003: Web agent validated a replacement server instead of its current GUI
+
+English | [中文](0003-web-agent-gui-feedback-loop.zh.md)
+
+Status: resolved
+
+## Executive summary
+
+A Web agent changed the GUI source but did not know which URL and process hosted its session. It delegated acceptance to the user, then treated a bare Vite HTTP 200 as success despite a missing `window.__DSH_BOOT__` white screen, and finally validated a replacement `dsh web` server on another port while the original page had already picked up rebuilt artifacts. The fix makes the current URL and runtime mode model-visible and shell-queryable, rejects standalone Vite before listen, and verifies production refresh and development HMR against external state.
+
+## Summary
+
+The session ran inside the DeepSeek Harness Web GUI at port 3081 while its selected Workspace was an empty `test/` directory. The model request named neither the GUI nor its source checkout, URL, process, or update mode. Repository affordances exposed `apps/web` with a Vite development script, while the full browser composition lived behind `dsh web`.
+
+The resulting actions were individually plausible but did not share one acceptance target. A source edit, a successful build, an HTTP 200, an injected boot manifest, and the user's existing page were treated as interchangeable facts.
+
+The evidence source is the persisted event log for `session-3eb796c2-5159-4686-affe-df8719f6f987`, whose header records cwd `/Users/tn.shen/Documents/deepseek-harness-gui-master/test`. Its initial request header is sequence 6; the user-facing handoff, bare-Vite launch, replacement-host launch, boot-manifest probe, and first 3081 process probe are sequences 30939, 31865, 34309, 34441, and 34681 respectively. The timeline below follows those events rather than reconstructing intent from the later report.
+
+## Impact
+
+The user had to identify three consecutive mistakes: acceptance was delegated back to them; the proposed preview was a blank page; and the reported successful URL was not the page they were using. An unmanaged replacement server also outlived the turn until the user challenged it.
+
+No change in this investigation restarted or modified the read-only 3081 and 3082 trial services.
+
+## Timeline
+
+- In turn 2, after editing the theme, the agent's sequence-30939 message told the user to run `pnpm run demo:tui` or open an unspecified Web application. It ran no assembled Web acceptance.
+- In turn 3, the agent read `apps/web/package.json`, launched bare Vite on port 5173 at sequence 31865, observed HTTP 200, and declared success. The browser instead threw `client-modules: window.__DSH_BOOT__ is missing or not an object` and rendered a white page.
+- In turn 4, the agent found the full `dsh web` path, rebuilt the shell, launched an unmanaged process on port 3334 at sequence 34309, and checked only that this replacement returned 200 with a boot manifest at sequence 34441. It never probed port 3081.
+- In turn 5, the user reported at sequence 34556 that 3081 already showed the new theme. Only then, at sequence 34681, did the agent inspect the existing process and remove the redundant server.
+
+## Root cause
+
+The Web assembly had no model-visible identity for the current GUI, canonical URL, or runtime mode. The session cwd correctly represented the user's selected Workspace, but the model mistook that project boundary for the application boundary. No durable contract related the GUI source checkout, built artifacts, serving process, target origin, and browser acceptance.
+
+The wrong startup path looked legitimate because bare Vite returned HTTP 200. `window.__DSH_BOOT__` is injected only by the full host, so transport readiness did not imply application readiness. The first regression test repeated this mistake in another form: a timeout killed Vite and satisfied a nonzero-exit assertion. Live reproduction exposed that false positive.
+
+Background process semantics were also bypassed with shell `&`, so task identity, completion notices, collection, and cleanup did not apply. Verifying port 3334 therefore proved only that a second service worked.
+
+## Guardrails added
+
+- The Web launcher publishes the canonical loopback URL and actual production/development mode in the logged `app:web-surface` prompt section and managed `$DSH_WEB_URL`/`$DSH_WEB_MODE` environment.
+- Production guidance requires rebuilding artifacts and verifying the existing URL after refresh. Development guidance explains that `dsh web --dev` mounts only the HMR receiver; `pnpm run dev:web` in the same checkout must also rebuild client-plugin bundles, while shell and plain-package changes still require refresh.
+- `apps/web` standalone Vite serve mode rejects during configuration. Its subprocess test proves natural exit and instruments `Server.listen()` so a transient bind cannot pass unnoticed.
+- Layered real-path tests cover the CLI request, exact production/development prompts, shell runtime facts, same-port static replacement, source watcher rebuild, host stat polling, and browser HMR under an unchanged page identity.
+- PR evidence preserves screenshots from the original 3081 session and a real-model before/after GUI run; external browser, HTTP, process, and session-log observations carry acceptance.
+
+## Lessons
+
+- The agent must know hidden runtime prerequisites before it can guide the user; startup mode is application context, not tribal knowledge.
+- HTTP readiness, build success, and a boot manifest are different facts. Acceptance names the exact origin and externally observes the requested change there.
+- A replacement service cannot prove that an existing page changed. Long-running processes use managed task lifecycles when they are actually requested.
+- A regression test must be able to fail for the reported mechanism. Process timeout is not equivalent to fail-fast, and post-exit port availability does not prove the port was never bound.

docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md

@@ -0,0 +1,53 @@
+# 事故复盘（postmortem） 0003：Web agent（智能体）验收了替代服务器，而非其当前 GUI
+
+[English](0003-web-agent-gui-feedback-loop.md) | 中文
+
+Status: resolved
+
+## 摘要
+
+Web agent 修改了 GUI 源码，却不知道由哪个 URL 和进程承载当前会话。它把验收交还给用户，随后在 `window.__DSH_BOOT__` 缺失导致白屏的情况下，仍把裸 Vite 返回的 HTTP 200 当作成功；最后，原页面其实已经加载了重建产物，它却去验收另一个端口上的替代 `dsh web` 服务器。修复让当前 URL 和运行模式对模型可见且可由 shell 查询，在独立 Vite 开始监听前拒绝启动，并依据外部状态验收生产模式刷新与开发模式 HMR（热模块替换）。
+
+## 概述
+
+该会话运行在端口 3081 的 DeepSeek Harness Web GUI 中，而用户选择的 Workspace 是空的 `test/` 目录。模型请求既未指明该 GUI，也未提供它的源码检出目录、URL、进程或更新模式。仓库在 `apps/web` 中提供了 Vite 开发脚本，完整的浏览器组合则由 `dsh web` 提供。
+
+由此产生的各个动作单看都合理，却没有指向同一个验收目标。源码修改、成功构建、HTTP 200、注入的启动 manifest（元数据清单）和用户原本打开的页面，被当成了可以相互替代的事实。
+
+证据源是 `session-3eb796c2-5159-4686-affe-df8719f6f987` 的持久化事件日志，其头部记录的 cwd 为 `/Users/tn.shen/Documents/deepseek-harness-gui-master/test`。初始请求头位于序列 6；面向用户的交接、裸 Vite 启动、替代宿主启动、启动 manifest 探测，以及首次探测 3081 进程，分别位于序列 30939、31865、34309、34441 和 34681。下方时间线以这些事件为依据，而不是根据后续报告反推意图。
+
+## 影响
+
+用户不得不连续指出三个错误：agent 把验收交还给用户；建议预览的页面一片空白；报告成功的 URL 并不是用户正在使用的页面。一个不受管理的替代服务器还持续运行到下一轮，直到用户提出质疑。
+
+本次调查没有重启或修改只读的 3081 和 3082 试验服务。
+
+## 时间线
+
+- 在第 2 轮中，agent 修改主题后，在序列 30939 的消息中让用户运行 `pnpm run demo:tui` 或打开一个未明确指定的 Web 应用。它没有对组装后的 Web 应用执行任何验收。
+- 在第 3 轮中，agent 读取 `apps/web/package.json`，在序列 31865 于端口 5173 上启动裸 Vite，观察到 HTTP 200 后便宣布成功。浏览器却抛出 `client-modules: window.__DSH_BOOT__ is missing or not an object`，并显示白屏。
+- 在第 4 轮中，agent 找到了完整的 `dsh web` 启动路径，重新构建 shell，在序列 34309 于端口 3334 上启动一个不受管理的进程，并且只在序列 34441 检查了这个替代服务是否返回 200 和启动 manifest。它从未探测端口 3081。
+- 在第 5 轮中，用户在序列 34556 报告 3081 已经显示新主题。直到序列 34681，agent 才检查既有进程并移除冗余服务器。
+
+## 根因
+
+Web 组合没有向模型提供当前 GUI、规范 URL 或运行模式的身份信息。会话 cwd 正确表示了用户选择的 Workspace，但模型误把这个项目边界当成了应用边界。系统也没有持久契约将 GUI 源码检出目录、构建产物、服务进程、目标 origin 和浏览器验收关联起来。
+
+裸 Vite 返回 HTTP 200，使错误的启动路径看似合理。`window.__DSH_BOOT__` 只由完整宿主注入，因此传输层就绪不代表应用已就绪。首个回归测试以另一种方式重复了同样的错误：超时机制终止 Vite 后，非零退出断言仍会通过。真实复现暴露了这一误报。
+
+agent 还通过 shell `&` 绕过了后台进程语义，因此任务身份、完成通知、结果收集和清理机制均未生效。验证端口 3334 只能证明第二个服务可以工作。
+
+## 已添加的防护措施
+
+- Web 启动器在记录到日志的 `app:web-surface` 提示词区段，以及受管的 `$DSH_WEB_URL`/`$DSH_WEB_MODE` 环境变量中，发布规范环回 URL 和实际的生产／开发模式。
+- 生产模式指南要求重新构建产物，并在刷新后验证既有 URL。开发模式指南说明，`dsh web --dev` 只挂载 HMR 接收端；同一源码检出目录中的 `pnpm run dev:web` 还必须重新构建客户端插件 bundle，而 Web shell 和普通包的改动仍然需要刷新页面。
+- `apps/web` 的独立 Vite 服务模式会在配置阶段拒绝启动。其子进程测试验证进程自然退出，并插桩 `Server.listen()`，确保短暂绑定端口也不会漏检。
+- 分层的真实路径测试覆盖 CLI（命令行界面）请求、精确的生产／开发模式提示词、shell 运行时事实、同端口静态产物替换、源码 watcher 重建、宿主 stat 轮询，以及页面 identity 不变的浏览器 HMR。
+- PR（Pull Request）证据保留了原始 3081 会话的截图，以及真实模型驱动的 GUI 修改前后对比；验收以外部浏览器、HTTP、进程和会话日志的观测结果为准。
+
+## 教训
+
+- agent 必须先知道隐藏的运行时前置条件，才能指导用户；启动模式属于应用上下文，不应依赖团队口口相传。
+- HTTP 就绪、构建成功和启动 manifest 是不同的事实。验收必须明确指定确切的 origin，并从外部观察所请求的改动是否在该 origin 生效。
+- 替代服务无法证明既有页面已经改变。确实需要长时间运行的进程时，应使用受管的任务生命周期。
+- 回归测试必须能够针对所报告的机制失败。进程超时不等同于快速失败，进程退出后端口可用也不能证明该端口从未被绑定。

docs/postmortem/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-README.md: df0e2fcb8540aeed005153dbecc451d781ca5ff1
-README.zh.md: 2ce6de475c705b02cd9dabfb2181929d81478e2c
+#   pnpm run verify-translation-pairing --write docs/postmortem/README.md
+README.md: 4858f8841e92a895f2d1a840b59b42758e83d952
+README.zh.md: f2f69e44448df8e7016fbe5672a0c0d5a522c47a

docs/postmortem/README.md

@@ -14,3 +14,4 @@ Every post-mortem opens with an **Executive summary**: one short paragraph a bus
 |---|---|
 | [0001](0001-acp-default-export-drops-inject.md) | ACP server crashed on connect: `export default` dropped the plugin's `inject` |
 | [0002](0002-js-expression-disabled-filesystem-tools.md) | Filesystem snapshot tools were permanently disabled by a literal `!!js` object |
+| [0003](0003-web-agent-gui-feedback-loop.md) | Web agent validated a replacement server instead of the GUI hosting its session |

docs/postmortem/README.zh.md

@@ -14,3 +14,4 @@
 |---|---|
 | [0001](0001-acp-default-export-drops-inject.md) | ACP（Agent Client Protocol）服务器在连接时崩溃：`export default` 丢失了插件的 `inject` |
 | [0002](0002-js-expression-disabled-filesystem-tools.md) | 文件系统快照工具被一个字面量 `!!js` 对象永久禁用 |
+| [0003](0003-web-agent-gui-feedback-loop.md) | Web agent 验证了替代服务器，而非承载其会话的 GUI |

scripts/dev-web.spec.ts

@@ -0,0 +1,42 @@
+import { mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it } from 'vitest'
+import type { TsdownBundle } from 'tsdown'
+import { watchClientPlugins } from './dev-web.ts'
+
+it('rebuilds a client-plugin bundle after its source changes', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-dev-web-watch-'))
+  let bundles: TsdownBundle[] = []
+  try {
+    await symlink(join(import.meta.dirname, '..', 'node_modules'), join(root, 'node_modules'), 'dir')
+    await writeFile(join(root, 'package.json'), JSON.stringify({ name: '@dsh-test/dev-web-watch', private: true, type: 'module' }))
+    await writeFile(join(root, 'tsdown.config.ts'), `
+import { defineConfig } from 'tsdown'
+export default defineConfig({
+  entry: { client: 'src.ts' }, outDir: 'lib', format: 'cjs', platform: 'browser', dts: false, clean: false,
+  outputOptions: { entryFileNames: 'client.js' },
+})
+`)
+    const sourcePath = join(root, 'src.ts')
+    const bundlePath = join(root, 'lib/client.js')
+    await writeFile(sourcePath, 'export const version = "watch-v1"\n')
+    bundles = await watchClientPlugins(root, ['.'], 50)
+    await expect.poll(async () => {
+      try {
+        return (await readFile(bundlePath, 'utf8')).includes('watch-v1')
+      } catch {
+        return false
+      }
+    }, { timeout: 10_000 }).toBe(true)
+
+    await new Promise(resolve => setTimeout(resolve, 1_000))
+    await writeFile(sourcePath, `export const version = "watch-v2-${'x'.repeat(100)}"\n`)
+    await expect.poll(async () => (await readFile(bundlePath, 'utf8')).includes('watch-v2-'), {
+      timeout: 10_000,
+    }).toBe(true)
+  } finally {
+    for (const bundle of bundles) await bundle[Symbol.asyncDispose]()
+    await rm(root, { recursive: true, force: true })
+  }
+}, 20_000)

scripts/dev-web.ts

@@ -18,9 +18,10 @@
  * keys under each package's file config, and no package config defines it).
  */
 import { globSync, readFileSync } from 'node:fs'
-import { dirname, join, sep } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { dirname, join, resolve, sep } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { build } from 'tsdown'
+import type { TsdownBundle } from 'tsdown'
 
 const repoRoot = fileURLToPath(new URL('..', import.meta.url))
 
@@ -29,46 +30,64 @@ const repoRoot = fileURLToPath(new URL('..', import.meta.url))
  * whose package.json carries `dshClient` with platform "web" is a client
  * plugin bundle emitter. Scanned once at startup — a package added while
  * watching means restarting this script.
+ * @param root - repository root containing the grouped package directories.
  * @returns workspace-relative plugin package directories.
  */
-function discoverPluginDirs(): string[] {
+export function discoverPluginDirs(root = repoRoot): string[] {
   const dirs: string[] = []
-  for (const manifestPath of globSync('packages/*/*/package.json', { cwd: repoRoot }).sort()) {
-    const manifest = JSON.parse(readFileSync(join(repoRoot, manifestPath), 'utf8')) as { dshClient?: { platform?: unknown } }
+  for (const manifestPath of globSync('packages/*/*/package.json', { cwd: root }).sort()) {
+    const manifest = JSON.parse(readFileSync(join(root, manifestPath), 'utf8')) as { dshClient?: { platform?: unknown } }
     if (manifest.dshClient?.platform === 'web') dirs.push(dirname(manifestPath).split(sep).join('/'))
   }
   return dirs
 }
 
-const PLUGIN_DIRS = discoverPluginDirs()
-if (PLUGIN_DIRS.length === 0) {
-  console.error('dev-web: no dshClient (platform "web") packages found under packages/')
-  process.exit(1)
+/**
+ * Start the tsdown watch build used by `pnpm run dev:web`.
+ * @param root - repository or fixture root passed to tsdown.
+ * @param pluginDirs - workspace-relative package directories to watch.
+ * @param pollInterval - optional source-watcher polling interval in milliseconds.
+ * @returns live bundles whose async disposers stop every watcher.
+ */
+export async function watchClientPlugins(
+  root: string,
+  pluginDirs: readonly string[],
+  pollInterval?: number,
+): Promise<TsdownBundle[]> {
+  return build({
+    cwd: root,
+    workspace: [...pluginDirs],
+    watch: true,
+    ...pollInterval !== undefined
+      ? { inputOptions: { watch: { watcher: { usePolling: true, pollInterval } } } }
+      : {},
+  })
 }
 
-const args = process.argv.slice(2)
-const pollArg = args.find(a => a === '--poll' || a.startsWith('--poll='))
-if (args.some(a => a !== pollArg)) {
-  console.error('dev-web: usage: tsx scripts/dev-web.ts [--poll[=ms]]')
-  process.exit(1)
-}
-const pollInterval = pollArg === undefined ? undefined : Number(pollArg.split('=')[1] ?? '500')
-if (pollInterval !== undefined && (!Number.isInteger(pollInterval) || pollInterval <= 0)) {
-  console.error(`dev-web: invalid --poll interval "${pollArg ?? ''}"`)
-  process.exit(1)
-}
+const invokedPath = process.argv[1]
+const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(resolve(invokedPath)).href
+if (isMain) {
+  const pluginDirs = discoverPluginDirs()
+  if (pluginDirs.length === 0) {
+    console.error('dev-web: no dshClient (platform "web") packages found under packages/')
+    process.exit(1)
+  }
 
-await build({
-  cwd: repoRoot,
-  workspace: PLUGIN_DIRS,
-  watch: true,
-  // Rolldown watch options ride through inputOptions (tsdown has no watcher
-  // tuning of its own); polling is opt-in for network mounts without inotify.
-  ...pollInterval !== undefined
-    ? { inputOptions: { watch: { watcher: { usePolling: true, pollInterval } } } }
-    : {},
-})
-console.log(
-  `dev-web: watching ${String(PLUGIN_DIRS.length)} dshClient plugin packages`
-  + `${pollInterval !== undefined ? ` (polling ${String(pollInterval)}ms)` : ''}:\n  ${PLUGIN_DIRS.join('\n  ')}`,
-)
+  const args = process.argv.slice(2)
+  const pollArg = args.find(a => a === '--poll' || a.startsWith('--poll='))
+  if (args.some(a => a !== pollArg)) {
+    console.error('dev-web: usage: tsx scripts/dev-web.ts [--poll[=ms]]')
+    process.exit(1)
+  }
+  const pollInterval = pollArg === undefined ? undefined : Number(pollArg.split('=')[1] ?? '500')
+  if (pollInterval !== undefined && (!Number.isInteger(pollInterval) || pollInterval <= 0)) {
+    console.error(`dev-web: invalid --poll interval "${pollArg ?? ''}"`)
+    process.exit(1)
+  }
+
+  await watchClientPlugins(repoRoot, pluginDirs, pollInterval)
+  console.log(
+    `dev-web: watching ${String(pluginDirs.length)} dshClient plugin packages`
+    + `${pollInterval !== undefined ? ` (polling ${String(pollInterval)}ms)` : ''}:\n  ${pluginDirs.join('\n  ')}`,
+  )
+}

tsconfig.host.json

@@ -18,6 +18,7 @@
     "apps/web/tests/settings-chrome.e2e.ts",
     "apps/web/tests/workspace-management.e2e.ts",
     "apps/web/tests/replay-round-trip.e2e.ts",
+    "apps/web/tests/hmr-live.e2e.ts",
     "apps/web/tests/seeded-history.e2e.ts",
     "apps/web/tests/code-mode-round.e2e.ts",
     "apps/web/tests/cordis-tool-round.e2e.ts",