Merge remote-tracking branch 'origin/master' into perf/tui-resume-scan

# Conflicts: # packages/ui/tui/README.i18n.yaml # packages/ui/tui/src/components/dialogs.ts
2026-08-03 17:06:28 +08:00
parent 7077d6befc 731f16ceb0
commit f128e126d7
201 changed files with 5490 additions and 601 deletions
@@ -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 .agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
+2026-07-31-fail-loud-releases-the-terminal.md: 2a6e7fcbbdd5d35bcf70dee09fdb9e5592486b78
+2026-07-31-fail-loud-releases-the-terminal.zh.md: f75c21cf79b241e6714c10ec7df9ac25f3d978b4
@@ -0,0 +1,59 @@
+# Agent Note: fail-loud releases the terminal before exiting
+
+Status: implemented
+
+English | [中文](2026-07-31-fail-loud-releases-the-terminal.zh.md)
+
+## Problem
+
+A `dsh` launch whose config failed validation printed its diagnostic and returned the user to a broken shell. Typing was invisible, and the next command was mangled by stray text:
+
+```
+dsh: fatal load failure: ValidationError: invalid config:
+  - $.providers expected object but got [object Object] (at providers)
+$ 1;2;4cecho hello
+zsh: command not found: 4cecho
+```
+
+The Loader mounts entries concurrently, so entry failure order is not startup order. `ui-tui` activates and calls pi-tui's `ProcessTerminal.start()`, which puts stdin in raw mode, enables bracketed paste, and writes the Kitty keyboard-protocol probe — a sequence ending in a Device Attributes query (`ESC [ c`). A sibling entry (here `llm-pi-ai`) then rejects on its own config. At the time, that rejection surfaced as an unhandled rejection, and `installFailLoud` wrote one stderr line and called `process.exit(1)` immediately. (The transactional Loader now settles config-tree failures through `boot()`, which disposes the partial context itself; the release hook remains the guard for rejections `boot()` cannot see — a plugin's detached async work rejecting during or after mounting.)
+
+Nothing disposed the tree, so `ProcessTerminal.stop()` never ran: raw mode, bracketed paste, and the keyboard protocol stayed set on the shell that outlived the process. The terminal's answer to the Device Attributes query (`1;2;4c`) arrived after exit and was read by the shell as typed input — the literal text above.
+
+The `/exit` path was never affected, because it disposes the tree and reaches the TUI's own `shutdown()`, which calls `drainInput()` (absorbing the pending reply) and then `ui.stop()`. The defect was that a *failed boot* had no path to that same teardown.
+
+## Decision
+
+`installFailLoud` takes an optional `release` teardown, awaited between the diagnostic and the exit:
+
+- The diagnostic is written **before** the release, so a hanging or failing disposer cannot swallow the reason.
+- A latch, not an uninstall, keeps the first rejection the reported one. Removing the listener during teardown would let a second concurrent rejection become uncaught, and Node would kill the process mid-teardown — stranding exactly the terminal state this restores. Later rejections, including the release's own, fall through to the pending exit.
+- The release is bounded by `FAIL_LOUD_RELEASE_TIMEOUT_MS` (2s) and its rejection is swallowed. A wedged or failing disposer delays the fatal exit; it never cancels it. That timer stays **referenced**: an `unref()`ed one lets Node reach an empty event loop and exit 0 on the very failure being reported, because an `unhandledRejection` listener suppresses the default fatal exit.
+- Omitting `release` keeps the previous behavior exactly, so the ACP, JSON-RPC, and demo bins are unchanged.
+
+`dsh`'s TUI launcher passes a release that disposes the root context, which runs the TUI's existing `shutdown()` and hands the terminal back.
+
+The launcher captures the root context in `boot()`'s `prepare` hook rather than from its return value. The rejection arrives while `boot()` is still in flight, so `app.current` assigned after the `await` would still be `undefined` at exactly the moment the hook needs it. `prepare` runs after the Loader installs and before any config-tree entry mounts, which covers the whole window in which an entry can reject.
+
+## Alternatives considered
+
+**Reset the terminal from the fail-loud handler** (write `ESC [ ? 2004 l`, pop the keyboard protocol, clear raw mode). This duplicates pi-tui's teardown in a package that owns no terminal, and would drift as pi-tui's startup sequence changes. It also cannot absorb the in-flight Device Attributes reply, which is what corrupts the next prompt — only draining stdin while it is still raw does that.
+
+**Register a `process.on('exit')` terminal reset in the TUI.** Exit handlers are synchronous, so they cannot await `drainInput()`; the stray reply would still land. It also puts teardown on a global hook rather than the disposal path that already exists.
+
+**Have the TUI refuse to start until the tree settles.** This serializes a deliberately concurrent Loader and delays first paint for every healthy launch to fix a failure path.
+
+**Reorder config entries so `llm-pi-ai` mounts before `ui-tui`.** Ordering is not a guarantee the Loader makes, and any future entry could fail after the TUI mounts.
+
+## Consequences
+
+A failed boot now costs one tree disposal (bounded at 2s) before exit, and the exit code stays 1. In exchange, a misconfigured `dsh` returns a usable shell instead of one needing `stty sane` or `reset`.
+
+The guarantee belongs to whichever bin owns the terminal: a surface that grabs terminal state and does not pass `release` reintroduces this defect. `installFailLoud` cannot detect that on its own, since it has no view of what a mounted plugin did to the process.
+
+## Testing
+
+`packages/ui/app-boot/tests/app-boot.spec.ts` covers the release contract: the hook is awaited before the exit commits, a rejecting hook still exits 1, a never-settling hook exits after `FAIL_LOUD_RELEASE_TIMEOUT_MS`, and a burst of rejections reports only the first while the release still completes.
+
+Those fake-process tests cannot observe the two failure modes that matter most — process exit code with a real event loop, and terminal state after exit — so the regression lives in `apps/cli/tests/tui-keyless-smoke.e2e.ts`. It boots the shipped tree in a real PTY over `fixtures/tui-invalid-provider.cordis.yml` (a list-shaped `providers`, the mistake users actually make), expects exit 1, and asserts the captured bytes contain both the labelled boot rejection (`dsh: plugin tree failed to load:`) and `ESC[?2004l`. The same case pins the boot path end to end: it caught the [HMR initial-scan boot deadlock](2026-08-03-hmr-initial-scan-boot-deadlock.md) that silently exited 13 with the terminal stranded.
+
+Testing policy requires a PTY case whenever terminal teardown changes, and this is it. The `/exit` path keeps its existing assertion that the same reset appears on a clean exit.
@@ -0,0 +1,59 @@
+# Agent Note：fail-loud 在退出前释放终端
+
+Status: implemented
+
+[English](2026-07-31-fail-loud-releases-the-terminal.md) | 中文
+
+## Problem
+
+配置校验失败的 `dsh` 启动会打印诊断信息，然后把用户丢回一个损坏的 shell：输入不可见，下一条命令还会被残留文本弄乱：
+
+```
+dsh: fatal load failure: ValidationError: invalid config:
+  - $.providers expected object but got [object Object] (at providers)
+$ 1;2;4cecho hello
+zsh: command not found: 4cecho
+```
+
+Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动顺序。`ui-tui` 会先激活并调用 pi-tui 的 `ProcessTerminal.start()`，它把 stdin 置为 raw 模式、启用 bracketed paste，并写出 Kitty 键盘协议探测序列——该序列以一个 Device Attributes 查询（`ESC [ c`）结尾。随后某个同级条目（这里是 `llm-pi-ai`）因自身配置而 rejection。
+
+在当时，该 rejection 以未处理 rejection 的形式浮现，而 `installFailLoud` 只写一行 stderr 就立即调用 `process.exit(1)`。（事务化 Loader 现在让配置树失败经 `boot()` 结算，由它自行释放部分构建的上下文；release 回调仍然守护 `boot()` 看不到的 rejection——插件游离的异步工作在挂载期间或挂载之后失败。）没有任何环节释放这棵树，因此 `ProcessTerminal.stop()` 从未执行：raw 模式、bracketed paste 和键盘协议都残留在比进程活得更久的 shell 上。终端对 Device Attributes 查询的回应（`1;2;4c`）在进程退出之后才到达，被 shell 当作用户输入读入——也就是上面那段字面文本。
+
+`/exit` 路径从不受影响，因为它会释放整棵树，从而进入 TUI 自身的 `shutdown()`：先 `drainInput()`（吸收尚未返回的响应），再 `ui.stop()`。缺陷在于**启动失败**没有通往这同一套拆卸流程的路径。
+
+## Decision
+
+`installFailLoud` 新增可选的 `release` 拆卸回调，在诊断信息与退出之间被等待：
+
+- 诊断信息在 release **之前**写出，因此卡住或失败的 disposer 无法吞掉失败原因。
+- 使用闩锁（latch）而非卸载监听器，来保证被报告的始终是第一个 rejection。若在拆卸期间移除监听器，第二个并发 rejection 就会变成未捕获错误，Node 会在拆卸中途杀死进程——恰好残留下本次要恢复的终端状态。后续 rejection（包括 release 自身的）都会落入已挂起的退出流程。
+- release 以 `FAIL_LOUD_RELEASE_TIMEOUT_MS`（2 秒）为上限，且其 rejection 被吞掉。卡住或失败的 disposer 只会延迟致命退出，绝不会取消它。该定时器保持 **referenced**：一旦 `unref()`，Node 就会在事件循环清空后、恰恰在报告这次失败时以 0 退出，因为 `unhandledRejection` 监听器抑制了默认的致命退出。
+- 不传 `release` 时行为与此前完全一致，因此 ACP、JSON-RPC 和各 demo bin 均无变化。
+
+`dsh` 的 TUI 启动器传入的 release 会释放根上下文，从而执行 TUI 已有的 `shutdown()` 并把终端交还。
+
+启动器在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值。rejection 到达时 `boot()` 尚未结算，因此在 `await` 之后赋值的 `app.current` 恰好在回调需要它的那一刻仍是 `undefined`。`prepare` 在 Loader 安装之后、任何配置树条目挂载之前运行，覆盖了条目可能 rejection 的整个窗口。
+
+## Alternatives considered
+
+**在 fail-loud 处理函数里直接重置终端**（写 `ESC [ ? 2004 l`、弹出键盘协议、清除 raw 模式）。这会在一个并不拥有终端的包里重复 pi-tui 的拆卸逻辑，并随 pi-tui 启动序列的变化而漂移。它同样无法吸收尚未返回的 Device Attributes 响应——而这正是弄乱下一个提示符的原因，只有在 stdin 仍处于 raw 模式时排空它才能解决。
+
+**在 TUI 中注册 `process.on('exit')` 终端重置。** exit 处理函数是同步的，无法等待 `drainInput()`，残留响应依旧会落到 shell；而且这把拆卸挂到全局钩子上，而非已经存在的释放路径。
+
+**让 TUI 等整棵树结算后再启动。** 这会把刻意并发的 Loader 串行化，并为修复一条失败路径而拖慢每一次正常启动的首次绘制。
+
+**调整配置顺序，让 `llm-pi-ai` 先于 `ui-tui` 挂载。** 顺序并不是 Loader 提供的保证，而且未来任何条目都可能在 TUI 挂载之后失败。
+
+## Consequences
+
+启动失败现在会在退出前多付出一次树释放的代价（上限 2 秒），退出码仍为 1。作为交换，配置错误的 `dsh` 会交还一个可用的 shell，而不是需要 `stty sane` 或 `reset` 才能恢复的终端。
+
+这项保证属于**拥有终端的那个 bin**：任何抢占终端状态却不传 `release` 的界面都会重新引入该缺陷。`installFailLoud` 自身无法察觉这一点，因为它看不到已挂载的插件对进程做了什么。
+
+## Testing
+
+`packages/ui/app-boot/tests/app-boot.spec.ts` 覆盖 release 契约：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
+
+这些基于假进程的测试无法观测到最关键的两种失败形态——真实事件循环下的进程退出码，以及退出之后的终端状态——因此回归用例放在 `apps/cli/tests/tui-keyless-smoke.e2e.ts`。它在真实 PTY 中以 `fixtures/tui-invalid-provider.cordis.yml`（`providers` 为列表形状，正是用户真实会犯的错误）启动出厂配置树，期望退出码为 1，并断言捕获到的字节流同时包含带标签的启动 rejection（`dsh: plugin tree failed to load:`）与 `ESC[?2004l`。同一用例端到端钉住了启动路径：正是它发现了以 13 静默退出、终端状态被残留的 [HMR 初始扫描启动死锁](2026-08-03-hmr-initial-scan-boot-deadlock.md)。
+
+测试规范要求：只要改动终端拆卸，就必须有 PTY 用例——这就是它。`/exit` 路径保留其原有断言，确认正常退出时同样会出现该重置序列。
@@ -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 .agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md
+2026-08-02-message-fork-actions-require-completed-turn-tail.md: f2e7fd67b65a6ce4a86ba3f4405f78842be8f234
+2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md: 2c3feeaa3ef01dbde67faa73257520918996f9c8
@@ -0,0 +1,29 @@
+# Agent Note: Message fork actions require a completed turn tail
+
+Status: implemented
+
+English | [中文](2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md)
+
+## Problem
+
+The Web conversation attached branch to the last assistant node with nonempty text in each turn. A later tool result, interrupted reasoning node, or terminal error did not take ownership because those rows have no content-text IconActions. The branch icon could therefore appear beneath an assistant response while more rows from the same turn remained below it. The Host correctly expanded that message anchor through the containing `turn/end`, but the placement made the action look like a message-level cut and the child visibly inherited the same-turn suffix.
+
+## Decision
+
+`ConversationSnapshot.turnEnds` retains the completed turn boundaries present in the raw event window. The conversation view walks transcript nodes through each boundary and enables branch only when the boundary's last node is a user message, a durable steering message, or a content-bearing assistant message. Open turns have no eligible message, and a later tool result, reasoning-only interruption, turn error, or other transcript node leaves branch unavailable on earlier messages. The unavailable control stays visible, focusable, and hoverable; `aria-disabled`, a tooltip, and `aria-describedby` explain the completed-tail requirement without sending a Host request. Copy and clock remain available under their existing message chrome, and the Host's completed-turn fork semantics remain unchanged.
+
+This narrows the message eligibility established by the earlier [Web session fork action decision](../feature/2026-07-27-web-session-fork-actions.md). Session-row forking still selects the latest completed turn, and eligible message actions still pass their event seq through the shared client runtime operation.
+
+## Alternatives considered
+
+**Cut the event log at the clicked assistant message.** Rejected because an assistant message can sit inside an open step and can contain tool calls whose results occur later. A raw prefix at that seq is not a balanced turn and may not be a valid provider transcript.
+
+**Infer completion from `running` or the next user message.** Rejected because retry and steering turns need not align with the next visible user bubble, and a paged window may omit that later bubble. The durable `turn/end` event is the authoritative completion fact.
+
+**Hide branch from every interrupted turn.** Rejected because an aborted turn is durably closed and its final interrupted text can be the true transcript tail. Eligibility depends on the completed boundary and node order, not the outcome kind.
+
+**Hide ineligible message controls.** Rejected because a disappearing control does not explain the boundary requirement and shifts otherwise stable message chrome. A focusable unavailable control preserves the affordance while preventing the request.
+
+## Consequences
+
+An enabled branch icon denotes the same completed-turn boundary that the Host will copy. In the reported response → tool → interrupted Think shape, the response keeps copy, clock, and a disabled branch control that explains why it cannot act. This change deliberately does not provide same-turn transcript editing or a retry-before-turn operation; the Session-row action remains available when a reader wants to copy the latest completed turn in full. Runtime tests pin boundary projection and reference stability, while conversation tests cover assistant, user-only, and durable-steering tails plus unavailable controls caused by later tool and interrupted reasoning rows.
@@ -0,0 +1,29 @@
+# Agent Note: 消息 fork 操作要求消息位于已完成轮次尾部
+
+Status: implemented
+
+[English](2026-08-02-message-fork-actions-require-completed-turn-tail.md) | 中文
+
+## 问题
+
+Web 会话把分支操作挂到每个轮次中最后一个文本非空的 assistant 节点上。如果后面还有工具结果、被中断的推理（reasoning）节点或终态错误，这些行也不会接管操作，因为它们没有内容文本 IconActions。因此，分支图标可能出现在 assistant 响应下方，而同一轮次的更多行仍位于其后。Host 会正确地把该消息锚点扩展到其所在的 `turn/end`，但图标位置使操作看起来像在消息级截断，子会话又会明显继承同轮次的后缀。
+
+## 决策
+
+`ConversationSnapshot.turnEnds` 保留原始事件窗口中的已完成轮次边界。会话视图按各边界遍历 transcript（文本记录）节点，仅当边界的最后一个节点是用户消息、持久 steering（中途引导）消息或含内容的 assistant 消息时才启用分支操作。开放轮次没有符合条件的消息；如果后面还有工具结果、只有推理内容的中断、轮次错误或其他 transcript 节点，较早消息上的分支操作会保持不可用。不可用的控件仍然可见、可聚焦、可悬停；`aria-disabled`、tooltip 与 `aria-describedby` 会说明已完成尾部这一要求，且不会发送 Host 请求。复制和时钟仍可在既有消息 chrome 下使用，Host 按已完成轮次 fork 的语义保持不变。
+
+本决策收紧了较早的 [Web 会话 fork 操作决策](../feature/2026-07-27-web-session-fork-actions.md)所定义的消息资格。Session 行 fork 仍选择最新的已完成轮次；符合条件的消息操作仍通过共享 client 运行时操作传递其事件 seq。
+
+## 考虑过的替代方案
+
+**在点击的 assistant 消息处截断事件日志。** 不予采纳：assistant 消息可能位于尚未结束的步骤内，也可能包含结果随后才出现的工具调用。以该 seq 截取的原始前缀并不是结构完整的轮次，也可能不是有效的提供方 transcript。
+
+**从 `running` 或下一条用户消息推断完成状态。** 不予采纳：重试轮次与 steering 轮次不一定和下一个可见用户气泡对齐，分页窗口也可能省略该气泡。持久 `turn/end` 事件才是权威的完成事实。
+
+**对每个被中断轮次隐藏分支。** 不予采纳：已中止的轮次会持久关闭，其最终的中断文本可能正是真正的 transcript 尾部。资格取决于已完成边界与节点顺序，而非结果类别。
+
+**隐藏不符合条件的消息控件。** 不予采纳：消失的控件无法说明边界要求，还会让本应稳定的消息 chrome 发生位移。保留可聚焦但不可用的控件，既能维持操作提示，也能阻止请求。
+
+## 后果
+
+启用的分支图标现在表示的已完成轮次边界与 Host 实际复制的边界一致。在所报告的「响应 → 工具 → 被中断的 Think」形态中，响应仍保留复制、时钟，以及一个说明无法操作原因的禁用分支控件。本变更刻意不提供同轮次 transcript 编辑，也不提供轮次前重试操作；当读者希望完整复制最新的已完成轮次时，仍可使用 Session 行操作。运行时测试固定边界投影和引用稳定性，会话测试则覆盖 assistant 尾部、纯用户消息尾部、持久 steering 尾部，以及后续工具行和被中断推理行导致的不可用控件。
@@ -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 .agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
+2026-08-03-hmr-initial-scan-boot-deadlock.md: 4b3e259c216d258c321ab06c41225b33ed240d19
+2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: ce1bc8396ac6e7fb6ecb1647fe2b29cdc788c7e1
@@ -0,0 +1,41 @@
+# Agent Note: HMR's initial scan deadlocked a failing boot into a silent exit 13
+
+Status: implemented
+
+English | [中文](2026-08-03-hmr-initial-scan-boot-deadlock.zh.md)
+
+## Problem
+
+A `dsh` launch whose config-tree failed validation exited 13 (unsettled top-level await) with no diagnostic at all, and left the TUI's terminal state stranded on the shell — the exact symptom the [fail-loud release](2026-07-31-fail-loud-releases-the-terminal.md) fixed, reintroduced through a different mechanism after the [transactional config reload](2026-07-20-config-hot-reload-resilience.md).
+
+Two defects compounded:
+
+1. **Concurrent Include applies corrupt the transactional group update.** The HMR main watcher's chokidar initial scan re-announces every existing file as `add`. Its `add` for the config file triggered `Include.refresh()` while the Include's initial apply was still in flight (`this.content`, the changed-content dedup key, commits only after apply). Two concurrent `EntryGroup.update` calls on one group interleave create and rollback on the same entries, and the Include fiber never settles — `loader.create` hangs, `boot()` neither resolves nor rejects, and Node exits 13 once the loop drains.
+2. **Serialized applies alone deadlock the failure rollback.** With Include mutations queued, a failing initial apply rolls back by disposing every mounted entry — including `hmr`, whose teardown drains its refresh tasks. The scan-triggered refresh task sits in the Include queue behind the very apply whose rollback is disposing HMR: rollback waits on HMR, HMR waits on the refresh, the refresh waits on the apply.
+
+## Decision
+
+Both halves are fixed in the vendored packages (logged in `vendor/README.md`):
+
+- `include/src/index.ts` funnels every child-tree mutation — initial apply, refresh, and `internal/update` patch re-application — through one per-Include promise queue. The group's transactional `update` is not reentrant, so serialization is a correctness requirement, not a throughput choice. `refresh()` also reads inside the queue so its changed-content check compares against the predecessor's committed state.
+- `hmr/src/index.ts` passes `ignoreInitial: true` to the main watcher. The initial scan only re-announces files boot has just consumed; suppressing it removes both the boot-time refresh and the spurious `add` events for already-loaded modules. `registerConfig()` keeps its own `ignoreInitial: false` watcher because a personal config present at registration must apply exactly once.
+
+With both in place a failing boot follows the intended path: the single apply fails, the rollback disposes the tree (running the TUI's own shutdown, restoring the terminal), `loader.create` rejects, and `boot()` rethrows the labelled diagnostic with exit 1.
+
+## Alternatives considered
+
+**Only `ignoreInitial: true`.** Removes the trigger but leaves the corruption: any genuinely concurrent refresh (a config edit racing a slow apply) still interleaves two group updates and strands the fiber.
+
+**Only serialization.** Converts the corruption into the rollback deadlock described above; the process still exits 13 silently.
+
+**Cancel queued refreshes on HMR teardown.** Requires cancellation plumbing through `refreshConfig`'s task loop and the Include queue for a case `ignoreInitial` already removes from every boot; not worth the machinery until a real trigger remains.
+
+## Consequences
+
+A config file edit landing inside the watcher's startup scan window is now picked up by the next `change` event rather than the scan itself; steady-state reload behavior is unchanged.
+
+One latent gap remains: a config edit made during a *failing* initial apply can still queue a refresh that the rollback's HMR teardown waits on — the same deadlock shape with a human-scale trigger window of one failing boot. If that ever bites, the fix is refresh-task cancellation at HMR teardown.
+
+## Testing
+
+The `dsh` invalid-provider PTY case in `apps/cli/tests/tui-keyless-smoke.e2e.ts` pins the end-to-end contract: exit 1, the labelled `dsh: plugin tree failed to load:` diagnostic naming `$.providers`, and the bracketed-paste reset proving the tree was disposed. Before this fix the same case observed exit 13 with no diagnostic. Reload behavior stays covered by `packages/ui/app-boot/tests/config-reload.spec.ts` and `packages/ui/app-boot/tests/hmr-config.spec.ts`.
@@ -0,0 +1,41 @@
+# Agent Note：HMR 初始扫描使失败的启动死锁为静默的 exit 13
+
+状态：已实现
+
+[English](2026-08-03-hmr-initial-scan-boot-deadlock.md) | 中文
+
+## 问题
+
+当 `dsh` 启动时配置树校验失败，进程以 13 退出（未结算的顶层 await），不输出任何诊断，并把 TUI 的终端状态残留在 shell 上——这正是 [fail-loud release](2026-07-31-fail-loud-releases-the-terminal.md) 修复过的症状，在[事务化配置重载](2026-07-20-config-hot-reload-resilience.md)之后经由另一条机制重新出现。
+
+两个缺陷叠加：
+
+1. **并发的 Include apply 破坏事务化的 group update。** HMR 主 watcher 的 chokidar 初始扫描会把每个已存在的文件重新宣告为 `add`。其中配置文件的 `add` 在 Include 的首次 apply 尚未结束时触发了 `Include.refresh()`（内容去重键 `this.content` 只在 apply 完成后才提交）。同一 group 上两个并发的 `EntryGroup.update` 会在相同条目上交错执行 create 与回滚，导致 Include fiber 永远无法结算：`loader.create` 挂起，`boot()` 既不 resolve 也不 reject，事件循环排空后 Node 以 13 退出。
+2. **仅序列化 apply 会让失败回滚死锁。** 将 Include 的变更排入队列后，首次 apply 失败时的回滚会释放每个已挂载条目——包括 `hmr`，而它的拆卸会等待自身的 refresh 任务排空。扫描触发的 refresh 任务正排在 Include 队列中、位于正在回滚的那次 apply 之后：回滚等 HMR，HMR 等 refresh，refresh 等 apply。
+
+## 决定
+
+两处修复都落在 vendored 包中（记录于 `vendor/README.md`）：
+
+- `include/src/index.ts` 将每次子树变更——首次 apply、refresh、`internal/update` 补丁重应用——汇入每个 Include 一条的 promise 队列。group 的事务化 `update` 不可重入，因此序列化是正确性要求，而不是吞吐取舍。`refresh()` 也在队列内读取文件，使其内容变更判断与前一任务提交后的状态比较。
+- `hmr/src/index.ts` 给主 watcher 传入 `ignoreInitial: true`。初始扫描只会重新宣告启动刚刚消费过的文件；抑制它同时消除了启动期 refresh 和对已加载模块的多余 `add` 事件。`registerConfig()` 保留自己 `ignoreInitial: false` 的 watcher，因为注册时已存在的个人配置必须恰好应用一次。
+
+两者齐备后，失败的启动走上预期路径：唯一一次 apply 失败，回滚释放整棵树（执行 TUI 自身的 shutdown、恢复终端），`loader.create` reject，`boot()` 重新抛出带标签的诊断并以 1 退出。
+
+## 曾考虑的替代方案
+
+**只加 `ignoreInitial: true`。** 消除了触发条件，但保留了破坏本身：任何真正并发的 refresh（配置编辑与缓慢的 apply 竞争）仍会交错两次 group update 并使 fiber 悬置。
+
+**只做序列化。** 把破坏转化为上述回滚死锁；进程仍然静默地以 13 退出。
+
+**在 HMR 拆卸时取消排队中的 refresh。** 需要在 `refreshConfig` 的任务循环和 Include 队列中铺设取消机制，而 `ignoreInitial` 已把该场景从每次启动中移除；在真实触发条件出现之前不值得引入这套机构。
+
+## 后果
+
+落在 watcher 启动扫描窗口内的配置文件编辑，现在由下一个 `change` 事件而非扫描本身拾取；稳态的重载行为不变。
+
+仍留有一个潜在缺口：在一次*失败的*首次 apply 期间进行的配置编辑，仍可能排入一个被回滚的 HMR 拆卸所等待的 refresh——同样的死锁形态，但触发窗口缩小到一次失败启动的人力尺度。若它真的发生，修复方向是在 HMR 拆卸时取消 refresh 任务。
+
+## 测试
+
+`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端契约：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已被释放的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/ui/app-boot/tests/config-reload.spec.ts` 与 `packages/ui/app-boot/tests/hmr-config.spec.ts` 覆盖。