Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/master' into worktree/web-multimodal-image-input

Browse Source 
# Conflicts:
#	.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
#	.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
#	.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
#	.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
#	.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
#	.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
#	THIRD_PARTY_NOTICES.md
#	apps/cli/composition.md
#	apps/cli/config/base.cordis.yml
#	apps/cli/package.json
#	apps/cli/src/app-cli-entry.ts
#	apps/cli/src/bin.ts
#	apps/cli/tests/args.spec.ts
#	apps/web/tests/built-boot.snapshot.ts
#	apps/web/tests/navigation-panes.e2e.ts
#	docs/architecture.i18n.yaml
#	docs/architecture.md
#	docs/architecture.zh.md
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/core.i18n.yaml
#	docs/core-data-structures/llm-streaming.i18n.yaml
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	packages/README.i18n.yaml
#	packages/bundle/README.i18n.yaml
#	packages/client/connection/README.i18n.yaml
#	packages/client/connection/README.md
#	packages/client/connection/README.zh.md
#	packages/client/connection/src/client/fixture.ts
#	packages/client/connection/src/http-bridge.ts
#	packages/client/connection/src/index.ts
#	packages/client/connection/tests/fixture.spec.ts
#	packages/client/connection/tests/node-half.spec.ts
#	packages/client/runtime/README.i18n.yaml
#	packages/client/runtime/README.md
#	packages/client/runtime/README.zh.md
#	packages/client/runtime/src/client/contract/session.ts
#	packages/client/runtime/src/client/sessions/session.ts
#	packages/client/ui-conversation/README.i18n.yaml
#	packages/client/ui-conversation/README.md
#	packages/client/ui-conversation/README.zh.md
#	packages/client/ui-conversation/src/client/apply.ts
#	packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
#	packages/client/ui-conversation/src/client/chat/ChatView.tsx
#	packages/client/ui-conversation/src/client/chat/MessageItem.module.css
#	packages/client/ui-conversation/src/client/chat/MessageItem.tsx
#	packages/client/ui-conversation/src/client/contract/slots.ts
#	packages/client/ui-conversation/src/client/index.ts
#	packages/client/ui-conversation/src/client/input/contract.ts
#	packages/client/ui-conversation/src/client/input/facade.ts
#	packages/client/ui-conversation/src/client/input/hub.ts
#	packages/client/ui-conversation/src/client/locales.ts
#	packages/client/ui-conversation/src/client/service.ts
#	packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx
#	packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
#	packages/client/ui-conversation/tests/apply-inject.spec.tsx
#	packages/client/ui-conversation/tests/input-bar.spec.tsx
#	packages/client/ui-conversation/tests/input-matrix.spec.tsx
#	packages/client/ui-conversation/tests/input-scenarios.spec.tsx
#	packages/client/ui-conversation/tests/service-orchestration.spec.ts
#	packages/client/ui-conversation/tests/skeleton.spec.tsx
#	packages/client/ui-trajectory/tests/views.spec.tsx
#	packages/compact/compact-basic/README.i18n.yaml
#	packages/cordis/tool-cordis/src/api-catalog.ts
#	packages/host/apiproxy/README.i18n.yaml
#	packages/host/apiproxy/README.md
#	packages/host/apiproxy/README.zh.md
#	packages/host/apiproxy/src/api-proxy.ts
#	packages/host/apiproxy/src/api/rpc.ts
#	packages/host/apiproxy/src/api/sessions.ts
#	packages/host/apiproxy/src/index.ts
#	packages/host/apiproxy/tests/api-proxy-models.spec.ts
#	packages/host/apiproxy/tests/rpc-schemas.spec.ts
#	packages/llm/llm-pi-ai/README.i18n.yaml
#	packages/llm/llm-pi-ai/README.md
#	packages/llm/llm-pi-ai/README.zh.md
#	packages/llm/llm-pi-ai/src/adapter.ts
#	packages/llm/llm/README.i18n.yaml
#	packages/ui/tui/README.md
#	packages/ui/tui/README.zh.md
#	packages/ui/tui/src/components/content.ts
#	packages/ui/tui/src/components/transcript.ts
#	packages/ui/tui/tests/tui.spec.ts
#	pnpm-lock.yaml
This commit is contained in:
Yichen Jiang
2026-08-08 01:56:29 +08:00
parent 78d956a65d 698d65de2d
commit 25d959aa08
3973 changed files with 144864 additions and 60887 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
View File

@@ -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
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md
2026-07-19-windows-atomic-write-dacl-preservation.md: be9f82174300a7d605c6a6e63878728f08cb37be
2026-07-19-windows-atomic-write-dacl-preservation.zh.md: fc6ec5232c992f3a230ee0de89439c869b8b46f9
2026-07-19-windows-atomic-write-dacl-preservation.zh.md: d31b52b0a99240a1e4449427438e1e187b1b98da

2
.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
View File

@@ -28,4 +28,4 @@ Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成
## 影响
替换 Windows 文件现在要求调用方有权读取目标 DACL 并设置临时文件 DACL；如果权限不足，系统会在写入内容前明确失败。该包（package）引入 Koffi 以执行少量 Win32 调用，并且只在 Windows 替换路径上加载。新的 Windows 文件会在目录按设计开放较宽访问权限时继承该权限，而 POSIX 临时内容仍仅允许所有者访问；只读 Windows 目标文件仍会在发布时失败，早于重放合成 mode 可能产生影响的时点。
替换 Windows 文件现在要求调用方有权读取目标 DACL 并设置临时文件 DACL；如果权限不足，系统会在写入内容前明确失败。该包引入 Koffi 以执行少量 Win32 调用，并且只在 Windows 替换路径上加载。新的 Windows 文件会在目录按设计开放较宽访问权限时继承该权限，而 POSIX 临时内容仍仅允许所有者访问；只读 Windows 目标文件仍会在发布时失败，早于重放合成 mode 可能产生影响的时点。

6
.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
View File

@@ -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
2026-07-20-config-hot-reload-resilience.md: 1a8e29c603ede50b60199e9151fca58dadcc3d40
2026-07-20-config-hot-reload-resilience.zh.md: 6c7a421bfa84504a36d5329e13a485bf72cc6b6c
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
2026-07-20-config-hot-reload-resilience.md: 0f15bb0aaacb6e06c416cbe35b44155279497eee
2026-07-20-config-hot-reload-resilience.zh.md: 8a185c1915b5247150d8bb1dd5c42d69bd4f2a35

31
.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
View File

@@ -6,33 +6,36 @@ English | [中文](2026-07-20-config-hot-reload-resilience.zh.md)
## Problem
The demo apps mount `@cordisjs/plugin-hmr` as a leaf so a running agent picks up `cordis.yml` edits. One bad edit killed the process: `Include.refresh()` rethrew the YAML parse error, the HMR watcher awaits `refresh()` inside an async chokidar callback nobody catches, and the resulting unhandled rejection tripped `dsh-app-boot`'s fail-loud handler — `exit(1)` mid-session, losing the live TUI. Two adjacent defects made even *valid* reloads wrong: a file that parses to `undefined` (empty or mid-write truncated — editors and `sed -i` routinely produce these states) crashed the entry walk instead of reading as invalid, and a re-read never re-applied the include's `config.patches`, so any hot-reload of an overlay-based tree (Code Mode, personal overlays) silently reverted patched entries and removed inserted ones.
An invalid `cordis.yml` edit must not kill a running agent, but preserving the process is insufficient when a valid-looking update partially replaces the Loader tree before a later entry fails. Callers also need to observe a rejected live update without treating the same error as an unhandled boot failure. Personal configuration adds a second requirement: HMR must observe one exact file outside its module roots, including a file or parent directory created after startup.
## Decision
Harden the vendored `@cordisjs/plugin-include` (logged as local modification 8 in [vendor/README.md](../../../../vendor/README.md)) rather than the callers:
The vendored Cordis lifecycle and Loader plugins provide an awaited, compensating config transaction, logged as local modifications 6, 8, and 9 in [vendor/README.md](../../../../vendor/README.md).
- `refresh()` awaits the whole read-and-update and catches failures, logs a warning, and keeps the last good entry tree. A hot-reload is advisory; the invariant is that no file state reachable by an editor may take the process down.
- `read()` rejects a non-array parse result with a `TypeError`, folding the `undefined`-parse case into the same "invalid file" signal, and commits `content`/`data` only after a successful parse — so reverting an edit to the exact last good content correctly reads as "unchanged".
- `refresh()` and the `internal/update` listener apply `this.applyPatches(...)` before `root.update()`, restoring parity with `[Service.init]`. `applyPatches` deep-copies the cached parse (`structuredClone`) instead of mutating it, so repeated application converges and removing a patch reverts to the file's own values. The listener uses the incoming config's `patches` and persists that config itself: it vetoes the fiber restart (children update in place), and `Fiber.update` only assigns `this.config` behind `next()`, so without the explicit assignment the next re-read would re-apply the old overlay.
`Fiber.update()` returns its `internal/update` waterfall result. Config validation remains synchronous, while the default continuation returns the restart promise. Loader entry updates can therefore distinguish validation, import, application, and rollback failure from successful lifecycle settlement. `EntryTree.await()` rechecks service-gated fibers after Loader tasks drain and rejects settled failures; a fiber waiting on an absent service remains a valid pending entry rather than making settlement hang.
Boot-time behavior stays fail-loud and gets a sharper diagnostic: `[Service.init]` falls back to `initial` (or "config file not found") only on `ENOENT`; an existing-but-invalid file now fails with its real parse error instead of being mislabelled as absent or silently overwritten by `initial`.
Loader imports a changed module name before disposing the active fiber. Candidate application is awaited; a failure disposes candidate effects and restores the prior plugin or config. Group reconciliation starts candidates concurrently, awaits every outcome, and restores changed entries, additions, removals, and moves before rejecting. Persistence occurs only after successful programmatic mutation. This is a compensating transaction: lifecycle effects may be briefly visible, and a failed rollback is reported as an `AggregateError` rather than misrepresented as a retained tree.
Include reads and validates detached candidate content, applies patches to a clone, reconciles the Loader tree, and only then commits cached content and parsed data. `refresh()` rejects to its caller after a parse, validation, application, or rollback failure. Initial load remains fail-loud; only an absent file may use `initial`. A non-array YAML/JSON result is invalid, and both file refresh and Include-config update re-apply patches without mutating the cached parse.
HMR contains live refresh rejection. Its `registerConfig(filename, refresh)` method watches one exact path from the nearest existing ancestor, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Both exact-path and ordinary config-file refreshes use that queue. A failure is normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed(filename, error)` event; rejecting observers are logged without stopping later refreshes. Creation, change, and removal are observed.
## Alternatives considered
**Catch in the HMR watcher callback instead of `refresh()`.** Rejected: it would leave `refresh()` a trap for every other caller (the `internal/update` path shares the same tree-update logic), and it cannot fix the `undefined`-parse or patch-loss defects, which live inside the include.
**Contain failures inside `Include.refresh()`.** Rejected because it prevents an HMR host from broadcasting the failure and still permits Loader reconciliation to hide partial application. Include owns candidate parsing and commit; HMR owns containment and observation.
**Filter config-file rejections in `installFailLoud`.** Rejected: the fail-loud handler exists to make late load failures visible; teaching it to classify exceptions by origin would silently swallow genuine boot failures and leave the stale-`data` crash in place.
**Restart the process for every config edit.** Rejected because Cordis effects already provide reversible plugin lifecycle, and a syntax error or failed optional plugin must not discard live sessions merely to recover the prior composition.
**A PTY e2e proving the TUI survives a bad edit.** Rejected as the primary gate: the PTY smoke reads the repo's committed `cordis.yml`, so corrupting it in-place is not test-safe, and a temp copy cannot resolve the tree's bare package specifiers. The unit spec drives the exact `refresh()` entry point the watcher calls; the fix was additionally verified manually against the live TUI (bad YAML, empty file, restored file).
**Promise invisible atomic replacement.** Rejected because arbitrary plugin effects cannot be snapshotted. Awaited application plus explicit compensation provides a stable final result without claiming that observers cannot see intermediate lifecycle transitions.
## Consequences
- A bad `cordis.yml` edit now logs `ignoring config reload at <file>` and the agent keeps running on the last good tree; the next valid edit applies normally. With no logger exporter mounted in the TUI demos the warning is currently invisible on screen — surfacing loader warnings in the TUI is deferred.
- Overlay trees survive base-file reloads with patches intact instead of silently reverting to the unpatched base.
- The vendored include diverges further from upstream; the divergence is logged in the vendor manifest and re-applies on the next sync.
- Known gap, out of scope here: the HMR watcher only handles chokidar `change` events, so editors that replace the file by rename (BSD `sed -i`, `git checkout`) do not trigger a config reload at all; and a reloaded app-entry config does not visibly restart the running TUI (pre-existing on the unmodified tree).
- A failed live refresh rejects internally, retains or restores the last-good tree when compensation succeeds, and broadcasts one typed failure without becoming an unhandled rejection.
- A rollback failure is visible and may leave an entry unavailable; the event and log do not claim otherwise.
- Fibers waiting on declared dependencies remain valid pending entries: lifecycle settlement means no current work failed, not that every dependency exists.
- Exact config watchers add filesystem resources only for registered paths and release them with their owning HMR fiber.
- The vendored Loader, Include, HMR, and core event typing diverge further from upstream; the complete divergence is maintained in the vendor manifest.
## Testing
`packages/ui/app-boot/tests/config-reload.spec.ts` boots real Loader trees against temp configs and pins: an invalid-YAML edit and an empty-file edit both resolve `refresh()` without rejection and keep the previous entry config; a subsequent valid edit applies; an overlay tree re-applies both entry patches and inserted entries on re-read; a hot-update of the include entry's own `patches` applies immediately, survives the next file re-read, and reverts cleanly when the patches are removed. The assertions fail on the unpatched vendored include.
`packages/ui/app-boot/tests/config-reload.spec.ts` boots real temporary Loader/Include trees and covers parse and shape rejection, import-before-dispose, plugin/config restoration, multi-entry rollback, ancestor disablement, overlay convergence, option identity, failed direct-update persistence, and failed programmatic moves. `packages/ui/app-boot/tests/hmr-config.spec.ts` covers existing and missing exact paths, add/change/removal, serialized coalescing, disposal drainage, non-`Error` normalization, failure broadcast, and rejecting-observer containment. `packages/host/webserver/tests/webserver.spec.ts` proves a service-gated startup failure rejects Loader composition with its bind diagnostic, `packages/typert/loader/tests/loader.spec.ts` exercises awaited programmatic removal through a real Loader consumer, and the ACP `pty-tools` snapshot guards concurrent composition from reordering equal-priority prompt sections.

31
.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
View File

@@ -6,33 +6,36 @@ Status: implemented
## Problem
各示例应用把 `@cordisjs/plugin-hmr` 挂载为叶子配置项，让运行中的 agent 能感知 `cordis.yml` 的编辑。一次错误的编辑就会杀死进程：`Include.refresh()` 把 YAML 解析错误原样抛出，HMR 的文件监听器在一个无人捕获的异步 chokidar 回调里 await `refresh()`，产生的未处理 rejection 触发 `dsh-app-boot` 的快速失败处理器——会话中途 `exit(1)`，正在运行的 TUI 就此丢失。另有两个相邻缺陷让*合法*的重载也出错：解析结果为 `undefined` 的文件（空文件或写入中途被截断的文件——编辑器和 `sed -i` 常态性地产生这类中间状态）会让配置项遍历直接崩溃，而不是被判定为无效文件；并且重新读取时从不重新应用 include 的 `config.patches`，因此对基于 overlay 的配置树（Code Mode、个人 overlay）做任何热重载，都会悄悄把打过补丁的配置项回退、并把插入的配置项移除。
无效的 `cordis.yml` 编辑不得杀死运行中的 agent（智能体）；但若一次看似有效的更新先部分替换 Loader 树，后续配置项才失败，仅仅保住进程仍不够。调用方还需要能观察到被拒绝的实时更新，同时不能让同一个错误被当作未处理的启动失败。个人配置还带来第二项要求：HMR（热模块替换）必须观察其模块根目录之外的一个确切文件，包括启动后才创建的文件或父目录。
## Decision
加固 vendor 的 `@cordisjs/plugin-include`（在 [vendor/README.md](../../../../vendor/README.md) 中记录为本地修改第 8 条），而不是修改调用方：
vendor 中的 Cordis 生命周期和 Loader 插件提供可等待、带补偿的配置事务，并在 [vendor/README.md](../../../../vendor/README.md) 中记录为本地修改第 6、8、9 条。
- `refresh()` await 整个「读取并更新」过程并捕获失败，记录一条警告，并保留上一份完好的配置树。热重载是尽力而为的；不变式是编辑器可能产生的任何文件状态都不得导致进程退出。
- `read()` 对非数组的解析结果抛出 `TypeError`，把 `undefined` 解析结果并入同一个「无效文件」信号，并且只在解析成功后才提交 `content`/`data`——因此把编辑撤销回与上一份完好内容完全一致时，会正确地判定为「无变化」。
- `refresh()` 与 `internal/update` 监听器在 `root.update()` 之前调用 `this.applyPatches(...)`，与 `[Service.init]` 保持一致。`applyPatches` 对缓存的解析结果做深拷贝（`structuredClone`）而不是就地修改，因此重复应用会收敛，移除补丁会回退到文件自身的值。监听器使用传入配置中的 `patches` 并自行持久化该配置：它否决 fiber 重启（子配置项就地更新），而 `Fiber.update` 只在 `next()` 之后才赋值 `this.config`，若不显式赋值，下一次重新读取会重新应用旧的 overlay。
`Fiber.update()` 返回其 `internal/update` waterfall（瀑布式事件）的结果。配置校验保持同步，而默认 continuation 返回重启 promise。因此，Loader 配置项更新可以区分校验、导入、应用和回滚失败，以及生命周期成功完成。`EntryTree.await()` 会在 Loader 任务排空后重新检查受服务门控的 fiber，并在 fiber 已结算为失败时 reject；等待缺失服务的 fiber 仍是有效的 pending 配置项，不会让结算挂起。
启动期行为保持快速失败并获得更准确的诊断：`[Service.init]` 只在 `ENOENT` 时回退到 `initial`（或「config file not found」）；存在但无效的文件现在会以真实的解析错误失败，而不是被误标为文件缺失、或被 `initial` 静默覆盖。
Loader 会先导入变化后的模块名，再 dispose（资源释放）活动 fiber。它会 await 候选项的应用；若失败，则 dispose 候选项的 effect，并恢复先前的插件或配置。组内对账会并发启动各候选项，等待每项结果，并会在拒绝前恢复已变更的配置项、添加项、移除项和移动项。只有程序化变更成功后才会持久化。这是一种补偿事务：生命周期 effect 可能短暂可见；回滚失败会报告为 `AggregateError`，而不会被误称为树已保留。
Include 读取并校验尚未提交的候选内容，把补丁应用到其副本，对账 Loader 树，然后才提交缓存内容和解析数据。解析、校验、应用或回滚失败后，`refresh()` 会向调用方 reject。初始加载继续快速失败；只有文件不存在时才可以使用 `initial`。YAML/JSON 结果若不是数组即为无效；文件刷新和 Include 配置更新都会重新应用补丁，且不修改缓存的解析结果。
HMR 收容实时刷新 rejection。其 `registerConfig(filename, refresh)` 方法从最近的现有祖先目录开始监听一个确切路径，串行化并合并刷新，并返回一个异步 disposer；该 disposer 会关闭 watcher 并排空活跃工作。确切路径和普通配置文件的刷新都使用此队列。失败会被规范化为 `Error`、记入日志，并通过并行事件 `hmr/config-update-failed(filename, error)` 广播；发生 rejection 的观察者会被记录，但不会阻止后续刷新。创建、变更和移除均会被观察。
## Alternatives considered
**在 HMR 监听回调里捕获，而不是在 `refresh()` 里。** 否决：这会让 `refresh()` 继续成为其他所有调用方的陷阱（`internal/update` 路径共享同一套树更新逻辑），而且无法修复 `undefined` 解析结果与补丁丢失这两个位于 include 内部的缺陷。
**在 `Include.refresh()` 内收容失败。** 已否决，因为这会使 HMR 宿主无法广播失败，却仍允许 Loader 对账掩盖部分应用。Include 负责候选内容的解析与提交；HMR 负责收容和观察。
**在 `installFailLoud` 里过滤配置文件相关的 rejection。** 否决：快速失败处理器的存在意义就是让延迟出现的加载失败可见；教它按来源给异常分类会悄悄吞掉真正的启动失败，并且原样保留陈旧 `data` 导致的崩溃。
**每次编辑配置都重启进程。** 已否决，因为 Cordis effect 已经提供可逆的插件生命周期，而语法错误或可选插件失败不应只为恢复先前的组合就丢弃正在进行的会话。
**用 PTY e2e 证明 TUI 能在错误编辑后存活。** 否决其作为主要门禁：PTY 冒烟测试读取仓库中已提交的 `cordis.yml`，就地破坏它对测试不安全，而临时副本无法解析该配置树的裸包说明符。单元测试直接驱动监听器所调用的 `refresh()` 入口；此外还对运行中的 TUI 做了人工验证（错误 YAML、空文件、恢复文件）。
**承诺不可见的原子替换。** 已否决，因为任意插件 effect 无法制作快照。等待应用完成并显式补偿可以得到稳定的最终结果，同时不会声称观察者看不到中间生命周期转换。
## Consequences
- 现在错误的 `cordis.yml` 编辑会记录 `ignoring config reload at <file>`，agent 继续运行在上一份完好的配置树上；下一次合法编辑正常生效。TUI 示例没有挂载任何日志导出器，这条警告目前不会显示在屏幕上——在 TUI 中呈现 loader 警告的工作暂缓。
- overlay 配置树在基础文件重载后补丁保持完整，不再悄悄回退到未打补丁的基础配置。
- vendor 的 include 与上游进一步分叉；该分叉已记录在 vendor 的 manifest 里，下次同步时重新应用。
- 已知缺口，不在本次范围内：HMR 监听器只处理 chokidar 的 `change` 事件，因此通过重命名替换文件的编辑方式（BSD `sed -i`、`git checkout`）完全不会触发配置重载；应用配置项重载后也不会可见地重启运行中的 TUI（未修改的代码树上即已如此）。
- 实时刷新失败会在内部 reject；补偿成功时会保留或恢复上一份完好的树，并广播一次类型化失败，而不会成为未处理的 rejection。
- 回滚失败可见，并可能使一个配置项不可用；事件和日志不会误称其已恢复。
- 等待已声明依赖的 fiber 仍是有效的 pending 配置项：生命周期完成只表示当前工作均未失败，而不表示每项依赖都存在。
- 确切配置 watcher 只为已注册路径增加文件系统资源，并随其所属 HMR fiber 一起释放。
- vendor 中的 Loader、Include、HMR 与核心事件类型定义进一步偏离上游；全部分叉均维护在 vendor manifest（元数据清单）中。
## Testing
`packages/ui/app-boot/tests/config-reload.spec.ts` 用真实 Loader 树加载临时配置并固定以下行为：无效 YAML 编辑和空文件编辑都让 `refresh()` 正常 resolve 而不产生 rejection，并保留之前的配置项配置；随后的合法编辑正常生效；overlay 配置树在重新读取时重新应用配置项补丁和插入的配置项；对 include 配置项自身 `patches` 的热更新立即生效、在下一次文件重读后依然保持、并在补丁移除后干净地回退。这些断言在未打补丁的 vendor include 上会失败。
`packages/ui/app-boot/tests/config-reload.spec.ts` 启动真实的临时 Loader/Include 树，并覆盖对解析和形状错误的拒绝、先导入再 dispose、插件/配置恢复、多配置项回滚、祖先禁用、overlay 收敛、option 对象身份、失败的直接更新不持久化以及失败的程序化移动。`packages/ui/app-boot/tests/hmr-config.spec.ts` 覆盖现有和缺失的确切路径、添加/变更/移除、串行化合并、dispose 排空、非 `Error` 值的规范化、失败广播以及对发生 rejection 的观察者的收容。`packages/host/webserver/tests/webserver.spec.ts` 证明受服务门控的启动失败会让 Loader 组合以其 bind 诊断 reject；`packages/typert/loader/tests/loader.spec.ts` 则通过真实 Loader 消费方演练可等待的程序化移除；ACP（Agent Client Protocol）的 `pty-tools` 快照会防止并发组合改变同优先级提示词段的顺序。

2
.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
View File

@@ -3,4 +3,4 @@
# 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-20-error-cause-chain-diagnostics.md
2026-07-20-error-cause-chain-diagnostics.md: 7de1f4f631cec90048ccc8eab7a6654560d84846
2026-07-20-error-cause-chain-diagnostics.zh.md: 74820e80f729343a833c926adc6187b7cc9fc372
2026-07-20-error-cause-chain-diagnostics.zh.md: 6ce642eb4a18a1a412fb63c3bb00042a921f4da3

34
.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
View File

@@ -1,37 +1,37 @@
# Agent Note: 在每个诊断接缝处渲染错误 cause 链
# Agent Note: 在每个诊断界面渲染错误 cause 链
Status: implemented
[English](2026-07-20-error-cause-chain-diagnostics.md) | 中文
## Problem
## 问题
TUI 连接不可达的 DeepSeek 端点时，失败只显示一条 `fetch failed` 通知，没有任何进一步细节。两个独立缺口共同造成了这个死胡同：
1. undici 的 `fetch` 把所有传输层失败（DNS、连接被拒、TLS、代理）包装成裸的 `TypeError: fetch failed`，可操作的细节——`ECONNREFUSED`、`bad port`、Happy Eyeballs 的 AggregateError——都在 `error.cause` 上。harness 里的每个诊断接缝都只渲染 `error.message`（或对 Error 等价的 `String(error)`），于是包装层在 TUI 通知、持久化的 `turn/end` reason 和所有日志行里都掩盖了诊断信息。
1. undici 的 `fetch` 把所有传输层失败（DNS、连接被拒、TLS、代理）包装成裸的 `TypeError: fetch failed`，可操作的细节——`ECONNREFUSED`、`bad port`、Happy Eyeballs 的 AggregateError——都在 `error.cause` 上。harness 里的每个诊断界面都只渲染 `error.message`（或对 Error 等价的 `String(error)`），于是包装层在 TUI 通知、持久化的 `turn/end` reason 和所有日志行里都掩盖了诊断信息。
2. readline 前门（`dsh-stdio`）完全不渲染失败原因：`reason.kind === 'error'` 的 `turn/end` 只打印下一个 `> ` 提示符，同样的失败在 `demo:repl` 里就是纯粹的沉默。
## Decision
## 决策
- `dsh-llm` 导出 `errorChain(value)`：渲染抛出值及其完整 `cause` 链（`outer: inner: …`）与 AggregateError 成员（`msg [m1; m2]`），并容错循环 cause 和恶意强制转换。它只是诊断表面的渲染器；路由仍然基于 `HarnessError.code`。
- DeepSeek 适配器把拿到响应之前的传输失败包装成 `LlmError('TRANSPORT')`，写明配置的 `baseURL` 并把原始拒绝值链为 `cause`。被中止的请求变为 `LlmError('ABORTED')`；由于轮次信号已处于中止状态，循环仍将该轮次归类为取消而非恢复。
- 每个诊断接缝改用 `errorChain` 而非 `error.message`/`String(error)`：agent-loop 的持久化 `turn/end` 错误消息（`errorData`）、其日志警告、TUI 的 `agent/error` 通知与启动失败行、以及 `dsh-stdio` 的启动失败日志行。实时 `agent/error` 事件与 `SettleReason` 以 `unknown` 原样保留抛出值；各诊断消费者自行渲染，而不是由循环把它包装成另一个错误。`dsh-agent-loop`、`dsh-stdio`、`dsh-tui` 里各自的 `renderThrown` 副本被删除，统一使用这一个共享渲染器。
- `dsh-stdio` 渲染失败的 `turn/end` reason：`[turn failed <code>] <message>`、`[turn aborted] <reason>`、`[turn rejected] <reason>`、`[turn interrupted by a previous process exit]` 以及输出 token 上限通知。未知的 merge 扩展 kind 按普通 turn 结束处理。
- `dsh-llm` 导出 `errorChain(value)`：渲染抛出值及其完整 `cause` 链（`outer: inner: …`）与 AggregateError 成员（`msg [m1; m2]`），并容错循环 cause 和恶意强制转换。它只是用于诊断界面的渲染器；路由仍然基于 `HarnessError.code`。
- DeepSeek 适配器把拿到响应之前的传输失败包装成 `LlmError('TRANSPORT')`，写明配置的 `baseURL` 并将原始拒绝值作为 `cause` 串入错误链。被中止的请求变为 `LlmError('ABORTED')`；由于轮次信号已处于中止状态，agent loop（智能体循环）仍将该轮次归类为取消而非恢复。
- 每个诊断界面改用 `errorChain` 而非 `error.message`/`String(error)`：agent-loop 的持久化 `turn/end` 错误消息（`errorData`）、其日志警告、TUI 的 `agent/error` 通知与启动失败行、以及 `dsh-stdio` 的启动失败日志行。实时 `agent/error` 事件与 `SettleReason` 以 `unknown` 原样保留抛出值；各诊断消费方自行渲染，而不是由循环把它包装成另一个错误。`dsh-agent-loop`、`dsh-stdio`、`dsh-tui` 里各自的 `renderThrown` 副本被删除，统一使用这一个共享渲染器。
- `dsh-stdio` 渲染失败的 `turn/end` reason：`[turn failed <code>] <message>`、`[turn aborted] <reason>`、`[turn rejected] <reason>`、`[turn interrupted by a previous process exit]` 以及输出 token 上限通知。通过声明合并扩展出的未知 kind 按普通 turn 结束处理。
`errorChain` 与 `HarnessError` 一样放在 `dsh-llm` 里，理由相同：它是每个消费者都已导入的叶子包，共享不增加新的依赖边。
`errorChain` 与 `HarnessError` 一样放在 `dsh-llm` 里，理由相同：它是每个消费方都已导入的叶子包，共享不增加新的依赖边。
## Alternatives considered
## 考虑过的替代方案
**在每个错误的构造函数里渲染链（把 cause 烤进 `message`）。** 否决：当消费者同时遍历 `cause` 时会双重渲染（适配器修复的第一版产出了 `… fetch failed: bad port: fetch failed: bad port`），并且破坏了想按内层错误路由的消费者所需的结构化链。
**在每个错误的构造函数里渲染链（把 cause 写入 `message`）。** 否决：当消费方同时遍历 `cause` 时会双重渲染（适配器修复的第一版产出了 `… fetch failed: bad port: fetch failed: bad port`），并且破坏了想按内层错误路由的消费方所需的结构化链。
**只做一个感知 `cause` 的日志导出器。** 否决：持久化的 `turn/end` reason 和 TUI 通知不是日志行；被掩盖的消息会留在会话日志——回合内失败的唯一持久记录——以及主要 UI 表面里。
**只做一个感知 `cause` 的日志导出器。** 否决：持久化的 `turn/end` reason 和 TUI 通知不是日志行；被掩盖的消息会留在会话日志——轮次内失败的唯一持久记录——以及主要 UI 表面里。
**逐包升级 `renderThrown`。** 否决：三个包已经各自持有几乎相同的私有副本；分别升级只会固化共享渲染器所要消除的重复。
## Consequences
## 后果
- 传输失败现在在 TUI 通知、readline transcript 和持久化会话日志里显示为 `DeepSeek API request to <baseURL> failed: fetch failed: connect ECONNREFUSED …`，代价是更长的诊断字符串。
- 持久化的 `turn/end` 错误消息包含 cause 细节。现有 snapshot fixture 字节级一致地回放，因为其脚本化错误不带 `cause`（对这类错误 `errorChain(err)` 等于 `err.message`）；只有单元测试的期望字符串有变化。从真实传输失败录制的 fixture 会携带完整链。
- `errorChain` 渲染 `message` 而不带类名（`String(error)` 会渲染 `Error: <message>`），因此日志行里的裸 `TypeError` 会丢失类型标签，除非消息为空（此时回退到类名）。在这些接缝上，链细节被判断为比类名更有价值。
- `dsh-stdio` 对失败回合的输出不再沉默；解析 transcript 的管道消费者会看到新的 `[turn …]` 行。
- 传输失败现在在 TUI 通知、readline transcript（文本记录）和持久化会话日志里显示为 `DeepSeek API request to <baseURL> failed: fetch failed: connect ECONNREFUSED …`，代价是更长的诊断字符串。
- 持久化的 `turn/end` 错误消息包含 cause 细节。现有快照 fixture（测试前置数据）字节级一致地回放，因为其脚本化错误不带 `cause`（对这类错误 `errorChain(err)` 等于 `err.message`）；只有单元测试的期望字符串有变化。从真实传输失败录制的 fixture 会携带完整链。
- `errorChain` 渲染 `message` 而不带类名（`String(error)` 会渲染 `Error: <message>`），因此日志行里的裸 `TypeError` 会丢失类型标签，除非消息为空（此时回退到类名）。在这些诊断界面上，链细节被判断为比类名更有价值。
- `dsh-stdio` 对失败轮次的输出不再沉默；解析 transcript 的管道消费方会看到新的 `[turn …]` 行。
- `dsh-subagent`、`dsh-workflow`、`dsh-skill`、`dsh-workflow-workerthread`、`cli-demo` 里剩余的 `renderThrown` 副本仍不渲染链；它们包装的是自带消息的包内错误，等诊断信息证明不足时再采用 `errorChain`。

4
.agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.i18n.yaml
View File

@@ -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
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.md
2026-07-20-jsonl-storage-identity.md: 1079eb700c819951dbb81e99376c0b71e3e84617
2026-07-20-jsonl-storage-identity.zh.md: d7ba5c646a7adaaa0ebd60fac7b9c2f030361ff9
2026-07-20-jsonl-storage-identity.zh.md: 6beb0d9f92ac1b1f4c3b03a783aa67e16b5fa7bb

4
.agents/notes/implemented/bug-fix/2026-07-20-jsonl-storage-identity.zh.md
View File

@@ -14,7 +14,7 @@ JSONL 查找会根据请求的会话 id 在各个项目目录中选出物理日
协调器会独立断言返回的 id，并在修复、发布状态或持久化后缀之前比较已存 cwd 和活动会话的 cwd。协调器保留一份已验证元数据的独立副本；JSONL 的追加和修复操作根据该副本派生路径。因此，`PersistenceBackend<TornMarker>` 接口既不需要限定范围的活动会话查找，也不需要存储定位器类型。
如果配置的 JSONL 根目录已存在，插件加载时该路径必须是可读目录。根目录不存在仍然是有效配置，首次物化时会创建该目录。后端对每个会话只支持一个活动写入方；在所有者完成资源释放且所有写入停止之前，另一个后端实例或进程不得变更该会话。
如果配置的 JSONL 根目录已存在，插件加载时该路径必须是可读目录。根目录不存在仍然是有效配置，首次物化时会创建该目录。后端对每个会话只支持一个活动写入方；在所有者完成 dispose（资源释放）且所有写入停止之前，另一个后端实例或进程不得变更该会话。
## 考虑过的替代方案
@@ -22,7 +22,7 @@ JSONL 查找会根据请求的会话 id 在各个项目目录中选出物理日
**通过协调器传递不透明存储定位器。** 定位器可以将 JSONL 变更直接绑定到选定路径，但 JSONL 可以根据已经验证的元数据重新得到该路径。为 SQLite、测试后端、追加和修复操作增加一个泛型和参数，会让每个实现都承担只有文件后端需要的概念。
**协调多个活动写入方。** 专用协调服务、进程级全局注册表或跨进程锁会定义新的部署拓扑，而不是修复身份验证。受支持的拓扑只有一个活动写入方；禁止覆盖的硬链接发布仍会裁决初始的同 id 创建竞争。
**协调多个活动写入方。** 专用协调服务、进程级全局注册表或跨进程锁会定义新的部署拓扑，而不是修复身份验证。受支持的拓扑只有一个活动写入方；禁止覆盖的硬链接发布仍会裁决初始的同 id 创建竞态。
## 后果

4
.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml
View File

@@ -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
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md
2026-07-21-compaction-summary-prefix-cache-reuse.md: d05d25cfa7c3984ce0ce75c38068a91a0e07dfe8
2026-07-21-compaction-summary-prefix-cache-reuse.zh.md: edf9de6fe5388d75612946bfb05c4383d1856102
2026-07-21-compaction-summary-prefix-cache-reuse.zh.md: f31c33e680b3db60a6fb758a522addca63224fea

18
.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md
View File

@@ -1,14 +1,14 @@
# Agent Note: 摘要调用回放对话前缀以复用 KV 缓存
# Agent Note: 摘要调用回放对话前缀以复用 KV Cache
Status: implemented
[English](2026-07-21-compaction-summary-prefix-cache-reuse.md) | 中文
## Problem
## 问题
自动压缩（compaction）在对话中途触发，恰好在循环用最后一个已路由请求（`system` + `tools` + 派生历史）预热了提供方的 KV 缓存之后。随后默认摘要器发出一个*独立的*辅助请求，其前缀与那个已预热请求没有任何共享部分：一个专门的摘要器 `system` 提示词，后接被拍平成单个渲染后 transcript（文本记录）字符串的较早历史。提供方基于请求起始的 token 序列做缓存，因此第一个 token 只要不同（即一个不同的系统提示词），整个已缓存前缀就会失效。于是每次压缩都要为整段回放的历史付出两次完整的提示词处理成本：一次用于触发压力的对话请求，另一次用于摘要调用，恰好在对话最大时让缓存失去作用。
自动压缩（compaction）在对话中途触发，恰好在循环用最后一个已路由请求（`system` + `tools` + 派生历史）预热了提供方的 KV Cache 之后。随后默认摘要器发出一个*独立的*辅助请求，其前缀与那个已预热请求没有任何共享部分：一个专门的摘要器 `system` 提示词，后接被拍平成单个渲染后 transcript（文本记录）字符串的较早历史。提供方基于请求起始的 token 序列做缓存，因此第一个 token 只要不同（即一个不同的系统提示词），整个已缓存前缀就会失效。于是每次压缩都要为整段回放的历史付出两次完整的提示词处理成本：一次用于触发压力的对话请求，另一次用于摘要调用，恰好在对话最大时让缓存失去作用。
## Decision
## 决策
摘要指令从请求的**前端**（一个全新的 `system` 提示词）移到对话的**末尾**（最后一条 `user` 消息）。辅助调用现在逐字复现最后一个已路由请求的前缀，并追加一条尾部指令，因此它是已预热请求的真正前缀扩展，提供方会复用已缓存的 token。
@@ -20,25 +20,25 @@ Status: implemented
`COMPACTION_INSTRUCTION` 以 "You are now acting as a compaction engine…" 开头，指示模型浓缩*上方的对话*。它保留先前检查点的结构化标题，并在其新位置上新增了两条前置系统提示词此前不需要的规则：不要提及摘要请求，以及只输出检查点文本而不调用任何工具。被遮蔽区域总是结束在工具配对平衡的边界上，因此在其后追加一条 `user` 消息，对 OpenAI 兼容适配器和 DeepSeek 适配器而言是合法的消息排序。
### 缓存复用是尽力而为，正确性不是
### 缓存复用是尽力而为，正确性则有保证
自动压缩总是锚定在表层头部，因此被遮蔽区域就是已路由请求的头部，回放的前缀与之完全匹配，这就是保证命中的情形。手动的中段 `compactRegion` 仍然回放真实的前缀并保持正确，但会放弃复用，因为它的被遮蔽区域不是请求头部。配置的 `summarizationProvider`/`summarizationModel` 若与对话的路由不同，也会放弃复用；这是部署方明确的权衡，而非缺陷。目标解析（配置的覆盖值 → 最新的已路由 header → agent（智能体）选项，否则抛出）保持不变。
## Alternatives considered
## 考虑过的替代方案
- **保留摘要器系统提示词但复用其余部分**——否决：system 槽位正是提供方最先做缓存的 token 区域，因此一个不同的摘要器系统提示词无论后面跟着什么都会使整个前缀失效。只有把指令移离前端才能恢复缓存。
- **只发送被遮蔽区域而不带 `system`/`tools` 头部**——否决：头部不同的序列在第一个 token 处仍然与已缓存请求分叉，因此缓存效果并不更好，反而丢失了摘要所需的框架。
- **从摘要请求中省略 `tools`**（模型从不调用任何工具）——否决：工具 schema 是已缓存 token 序列的一部分；省略它们会让后续每个 token 失去对齐，破坏复用。
- **为快照回放专门建立一个发出 `assistant/chunk` 的摘要子会话**——此处超出范围；该回放缺口早于本次改动，记录在 [compaction-seam Agent Note](../feature/2026-06-18-compaction-capability-seam.md) 中。
## Consequences
## 后果
- **`dsh-compact-basic`** 拥有 `SummarizationInput`；受保护的 `summarize(input, agent, signal?)` 钩子签名发生变化（发布前可接受），并且 `region.ts` 新增了 `buildSummarizationInput`，它在 header 前缀之后对被遮蔽的 seq 折叠 `deriveEventMessage`。
- **移除无用的渲染表面。** 旧的拍平路径（`renderTranscript` / `renderContentBlocks` 及其在 `dsh-compact` 中的 spec）已无消费方，连同其导出一并删除。
- **README 的 Model Experience** 现在把 `dsh-compact-basic` 的辅助请求记述为回放的前缀加上一条尾部压缩指令消息，并把其 KV 缓存效果记述为复用已预热的对话前缀。
- **README 的 Model Experience** 现在把 `dsh-compact-basic` 的辅助请求记述为回放的前缀加上一条尾部压缩指令消息，并把其 KV Cache 效果记述为复用已预热的对话前缀。
- **带框架的检查点输出未改变**，因此落地的 `user/message` 和每个对话请求快照都不受影响；只有辅助请求的形状发生了变化。
## Testing
## 测试
- **单元：** `compact-basic.spec.ts` 断言辅助调用转发 `system`/`tools`/前导消息，并把压缩指令作为最后一条消息追加，且 `compactRegion` 回放最新的已路由 header 前缀。现有的内容断言通过回放的消息而非 transcript 字符串来读取摘要器输入。
- **循环：** `compact-loop-repro.spec.ts` 依据摘要请求尾部 user 消息中的压缩指令对其分类，溢出恢复测试则继续在真实循环中固定对话请求与摘要请求的数量。

4
.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
View File

@@ -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-21-semantic-session-checkpoints.md
2026-07-21-semantic-session-checkpoints.md: 927a4c5d6d2aad5dea460ea29f97c1686e9d5398
2026-07-21-semantic-session-checkpoints.zh.md: 6454b496aa8c03c172d6a4bc969e43e8dbca2430
2026-07-21-semantic-session-checkpoints.md: 697d878dccbfab1ded9f73e134d594ba6f0665e1
2026-07-21-semantic-session-checkpoints.zh.md: c6184b0b00db16f9e318f4cbd148b1f0525f03a5

4
.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md
View File

@@ -10,9 +10,9 @@ Persistence buffered every synchronous `session/event` until the loop's final tu
## Decision
`dsh-session-checkpoint-policy` owns semantic durability barriers as a zero-config plugin beside a persistence backend. At `agent/step`, it flushes pending prompt input or the preceding response/result batch before the next request is derived. It wraps `llm/stream` lazily and flushes the live session after `request/header` is logged but before the adapter stream is constructed. It wraps top-level `tools/execute` after ordered pre-execute policy and flushes the recorded `tool/call` before the tool body; nested dispatches reuse the outer model-visible call. The loop's final `turn/end` checkpoint remains the closing boundary and settles before another queued turn or idle observation.
`dsh-session-checkpoint-policy` owns semantic durability barriers as a zero-config plugin beside a persistence backend. At `agent/pre-step`, it flushes pending prompt input or the preceding response/result batch before the next request is derived. It wraps `llm/stream` lazily and flushes the live session after `request/header` is logged but before the adapter stream is constructed. It wraps top-level `tools/execute` after ordered pre-execute policy and flushes the recorded `tool/call` before the tool body; nested dispatches reuse the outer model-visible call. The loop's final `turn/end` checkpoint remains the closing boundary and settles before another queued turn or idle observation.
Persistence and checkpoint scheduling remain separate Cordis plugins. A backend makes requested `session/flush` boundaries durable but does not choose them; loading it without this policy is valid and retains the loop's coarser checkpoints. First-party persisted apps and runtimes explicitly mount both, while a specialized deployment may intentionally omit or replace the policy. Registration order governs whether events appended by other `agent/step` listeners precede this checkpoint; prompt input and the preceding loop-owned assistant message and ordered results are already in the log.
Persistence and checkpoint scheduling remain separate Cordis plugins. A backend makes requested `session/flush` boundaries durable but does not choose them; loading it without this policy is valid and retains the loop's coarser checkpoints. First-party persisted apps and runtimes explicitly mount both, while a specialized deployment may intentionally omit or replace the policy. Registration order governs whether events appended by other `agent/pre-step` listeners precede this checkpoint; prompt input and the preceding loop-owned assistant message and ordered results are already in the log.
Checkpoint failure and cancellation are fail-closed at effect boundaries. A rejected request checkpoint prevents adapter dispatch; a rejected tool checkpoint becomes an error result without invoking the tool body. If cancellation lands while the tool checkpoint is pending, the policy rechecks the signal and returns the canonical `ABORTED_BEFORE_DISPATCH` result. A rejected between-step checkpoint closes the turn before another model request. A rejected final turn checkpoint is reported live and does not prevent later queued work. Persistence serialization continues to belong to the coordinator, so concurrent tool checkpoints cannot duplicate event sequences.

10
.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
View File

@@ -10,15 +10,15 @@ Status: implemented
## 决策
`dsh-session-checkpoint-policy` 以零配置插件的形式与持久化后端共同加载，并负责语义持久性屏障。在 `agent/step` 时，该插件会在推导下一个请求前刷新待持久化的提示词输入或前一批响应/结果。该插件惰性包装 `llm/stream`，在记录 `request/header` 之后、构造适配器流之前，刷新活动会话。该插件还在有序的执行前策略之后包装顶层 `tools/execute`，在进入工具主体前刷新已记录的 `tool/call`；嵌套分发则复用外层模型可见调用。循环的最终 `turn/end` 检查点仍是轮次的收尾边界，并会在处理另一个已排队轮次或观察到空闲状态之前完成。
`dsh-session-checkpoint-policy` 以零配置插件的形式与持久化后端共同加载，并负责语义持久性屏障。在 `agent/pre-step` 时，该插件会在推导下一个请求前刷新待持久化的提示词输入或前一批响应/结果。该插件惰性包装 `llm/stream`，在记录 `request/header` 之后、构造适配器流之前，刷新活动会话。该插件还在有序的执行前策略之后包装顶层 `tools/execute`，在进入工具主体前刷新已记录的 `tool/call`；嵌套分发则复用外层模型可见调用。循环的最终 `turn/end` 检查点仍是轮次的收尾边界，并会在处理另一个已排队轮次或观察到空闲状态之前完成。
持久化与检查点调度仍是相互独立的 Cordis 插件。后端使请求的 `session/flush` 边界持久化，但不选择边界；只加载后端而不加载本策略仍是有效组合，并保留循环提供的较粗检查点。第一方持久化应用与运行时会显式加载两者，专用部署则可以有意省略或替换本策略。注册顺序决定其他 `agent/step` 监听器追加的事件是否先于本检查点；提示词输入以及前一批由循环自身记录的助手消息与有序结果都已在日志中。
持久化与检查点调度仍是相互独立的 Cordis 插件。后端使请求的 `session/flush` 边界持久化，但不选择边界；只加载后端而不加载本策略仍是有效组合，并保留循环提供的较粗检查点。第一方持久化应用与运行时会显式加载两者，专用部署则可以有意省略或替换本策略。注册顺序决定其他 `agent/pre-step` 监听器追加的事件是否先于本检查点；提示词输入以及前一批由循环自身记录的助手消息与有序结果都已在日志中。
检查点失败与取消在副作用边界上采取失败关闭策略。请求检查点被拒绝时，系统不会分发给适配器；工具检查点被拒绝时，系统会返回错误结果，不调用工具主体。如果在工具检查点等待期间收到取消，策略会重新检查信号，并返回标准的 `ABORTED_BEFORE_DISPATCH` 结果。步骤间检查点被拒绝时，系统会在发起下一个模型请求前结束该轮次。轮次的最终检查点被拒绝时，系统会实时报告该失败，但不会阻止后续排队工作。持久化写入的串行化仍由协调器负责，因此并发的工具检查点不会产生重复的事件序号。
检查点失败与取消在副作用边界上采取失败关闭策略。请求检查点被拒绝时，系统不会分发给适配器；工具检查点被拒绝时，系统会返回错误结果，不调用工具主体。如果在工具检查点等待期间收到取消，策略会重新检查信号，并返回标准的 `ABORTED_BEFORE_DISPATCH` 结果。步骤间检查点被拒绝时，系统会在发起下一个模型请求前结束该轮次。轮次的最终检查点被拒绝时，系统会实时报告该失败，但不会阻止后续排队工作。持久化写入的串行化仍由协调器负责，因此并发的工具检查点不会产生重复的事件序列。
ACP（Agent Client Protocol）应用在一个有序 Cordis effect 中统一持有其桥接层、检查点策略与持久化后端。Cordis 会并发卸载同级插件的 effect；如果分别加载，桥接层仍在为被中断的轮次收尾时，持久化后端就可能已经卸载。组合生命周期会先卸载桥接层，等待其各 agent 达到静止，并刷新真实的 `step/end` 与 `turn/end`，再移除检查点调度与持久化。
ACP（Agent Client Protocol）应用在一个有序 Cordis effect 中统一持有其桥接层、检查点策略与持久化后端。Cordis 会并发卸载同级插件的 effect；如果分别加载，桥接层仍在为被中断的轮次收尾时，持久化后端就可能已经卸载。组合生命周期会先卸载桥接层，等待其各 agent 完全停稳，并刷新真实的 `step/end` 与 `turn/end`，再移除检查点调度与持久化。
崩溃修复会区分持久化证据。如果模型发出了工具请求，却没有 `tool/call`，系统会将其标记为 `TOOL_NOT_STARTED`；如果仍有需要，可以重试。如果持久化的 `tool/call` 没有结果，系统会将其标记为 `TOOL_OUTCOME_UNKNOWN`；对应的模型可见结果只允许重试只读或幂等操作，并指示模型在决定是否重试有副作用的工作前，先验证外部状态或询问用户。支持幂等键的模型提供方可以获取稳定的 `callId`，但 Harness 不承诺通用的副作用恰好执行一次保证。
崩溃修复会区分持久化证据。如果模型发出了工具请求，却没有 `tool/call`，系统会将其标记为 `TOOL_NOT_STARTED`；如果仍有需要，可以重试。如果持久化的 `tool/call` 没有结果，系统会将其标记为 `TOOL_OUTCOME_UNKNOWN`；对应的模型可见结果只允许重试只读或幂等操作，并指示模型在决定如何处理有副作用的工作前，先验证外部状态或询问用户。支持幂等键的模型提供方可以获取稳定的 `callId`，但 Harness 不承诺副作用恰好执行一次这一通用保证。
## 考虑过的替代方案

4
.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.i18n.yaml
View File

@@ -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
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md
2026-07-22-pi-ai-transport-truncation-classification.md: 119200a788c0b0521f385f4cf4e6adf05a0512f9
2026-07-22-pi-ai-transport-truncation-classification.zh.md: 6a1bb478a86fc6ab726968b3df5752e0ad7fc9e6
2026-07-22-pi-ai-transport-truncation-classification.zh.md: 0625d6041ccaeaff9d0d6f659c7b3856ab985ef6

12
.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.zh.md
View File

@@ -4,13 +4,13 @@ Status: implemented
[English](2026-07-22-pi-ai-transport-truncation-classification.md) | 中文
## Problem
## 问题
一次 TUI 运行的模型连接在流式输出中途断开，只浮现出一条 `terminated` 通知，而一个被截断的 Anthropic 响应则浮现出 `Anthropic stream ended before message_stop`。两者都是传输层截断——连接在提供方的终止 SSE 事件之前就已断开——然而 `dsh-llm-pi-ai` 中的 `classifyPiAiError` 对两者都不匹配，最终落入兜底的 `PI_AI_ERROR`。由于 `PI_AI_ERROR` 不在 `llm-retry` 的 `DEFAULT_RETRYABLE_CODES`（`RATE_LIMIT`、`SERVER`、`TIMEOUT`、`TRANSPORT`）中，一次可恢复的断开被当作永久性失败处理，从未被重试。
一次 TUI 运行的模型连接在流式输出中途断开，只浮现出一条 `terminated` 通知，而一个被截断的 Anthropic 响应则浮现出 `Anthropic stream ended before message_stop`。两者都是传输层截断——连接在提供方的终止 SSE（Server-Sent Events）事件之前就已断开——然而 `dsh-llm-pi-ai` 中的 `classifyPiAiError` 对两者都不匹配，最终落入兜底的 `PI_AI_ERROR`。由于 `PI_AI_ERROR` 不在 `llm-retry` 的 `DEFAULT_RETRYABLE_CODES`（`RATE_LIMIT`、`SERVER`、`TIMEOUT`、`TRANSPORT`）中，一次可恢复的断开被当作永久性失败处理，从未被重试。
细节丢失发生在上游，且在适配器内无法恢复：pi-ai 在推送终止 `error` 事件之前，把捕获到的错误缩减为 `error.message`（`api/anthropic-messages.js`：`errorMessage = error instanceof Error ? error.message : JSON.stringify(error)`），丢弃了原始的 `Error` 及其 `cause` 链。undici 把可操作的 `SocketError` 携带在 `cause` 上，却只交给 fetch 包装层一个裸的 `terminated`；pi-ai 只保留了这个词。pi-ai 的 `SimpleStreamOptions` 没有暴露任何 fetch/dispatcher/client 钩子，让我们能在细节被扁平化之前自行捕获 `cause`。
细节丢失发生在上游，且在适配器内无法恢复：pi-ai 在推送终止 `error` 事件之前，把捕获到的错误缩减为 `error.message`（`api/anthropic-messages.js`：`errorMessage = error instanceof Error ? error.message : JSON.stringify(error)`），丢弃了原始的 `Error` 及其 `cause` 链。undici 将可据以采取行动的 `SocketError` 放在 `cause` 上，却只交给 fetch 包装层一个裸的 `terminated`；pi-ai 只保留了这个词。pi-ai 的 `SimpleStreamOptions` 没有暴露任何 fetch/dispatcher/client 钩子，让我们能在细节被扁平化之前自行捕获 `cause`。
## Decision
## 决策
- `classifyPiAiError` 识别另外两种传输层措辞，并将两者都映射为 `TRANSPORT`：
- 流式输出中途的套接字断开，呈现为裸的 `terminated`（undici）或 `Premature close`（Node 流层）；
@@ -20,7 +20,7 @@ Status: implemented
分类仍然基于消息文本，因为那是 pi-ai 唯一交付的信号；`XXX` 标明它是一个权宜之计，而非期望的最终状态。
## Alternatives considered
## 考虑过的替代方案
**通过 pi-ai 的 fetch/dispatcher/client 钩子捕获 `cause`。** 否决：pi-ai 0.81.1 一个都没暴露。`StreamOptions` 只提供 `onPayload`/`onResponse`；`onResponse` 在响应体流被消费之前触发，因此无法观察到流式输出中途的断开。Anthropic 路径接受一个 `client` 对象，但为拦截传输错误而为每个请求构造并注入一个提供方 SDK client，只为一个诊断字符串就越过了适配器的服务边界。
@@ -28,7 +28,7 @@ Status: implemented
**在适配器里把扁平化后的错误包装成 `LlmError('TRANSPORT', { cause })`，仿照 DeepSeek 适配器。** 在此否决：DeepSeek 适配器包装的是拿到响应之前的 `fetch` 拒绝，其 `cause` 仍然完好，因此链式包装保留了真实细节。而在 pi-ai 路径中，终止事件的 `errorMessage` 已经是一个没有 `cause` 可链的扁平化字符串，因此包装只会加一层却恢复不了任何东西；分类出 code 是唯一还能增加的价值。
## Consequences
## 后果
- 流式输出中途的传输层断开和终止前的流截断现在都携带 `TRANSPORT`，因此组合出的 `llm-retry` 策略会默认重试它们，而不是让该轮次失败。
- 通知文本不变（`terminated` / `Anthropic stream ended before message_stop`）：cause 细节在适配器看到之前就已丢失，因此 `errorChain` 没有更多内容可渲染。只有被路由的 `code` 得到了改善。

6
.agents/notes/implemented/bug-fix/2026-07-23-tui-generic-card-markdown.i18n.yaml
View File

@@ -1,6 +0,0 @@
# 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
2026-07-23-tui-generic-card-markdown.md: 494ba580480fa99de54e84025a65bf4589d410f2
2026-07-23-tui-generic-card-markdown.zh.md: 214edd00f50b88a4e8901b19dcdafc7382399831

29
.agents/notes/implemented/bug-fix/2026-07-23-tui-generic-card-markdown.md
View File

@@ -1,29 +0,0 @@
# Agent Note: TUI generic-card Markdown rendering
Status: implemented
English | [中文](2026-07-23-tui-generic-card-markdown.zh.md)
## Problem
Tool presenters can put Markdown in generic-card content, including fenced `console` output used for background-task acknowledgements and execution errors. Rendering that content as plain text exposes the fence markers and diverges from assistant and user content in the same transcript.
## Decision
The TUI renders generic-card result content with its shared Markdown theme before applying the card's head-and-tail line limit. Terminal and diff cards retain their specialized plain-text renderers, and generic-card raw input remains literal because it represents tool arguments rather than presenter-authored prose.
The shared theme hides fence syntax, retains the optional language label, and colors the fenced body as code. Rendering precedes truncation so collapsed-card line counts and boundaries describe the visible terminal rows rather than Markdown source rows.
## Alternatives considered
**Strip fences in the Bash presenter.** This would fix one producer while leaving generic-card Markdown from other tools unrendered and would make the presenter depend on TUI behavior.
**Render every tool card as Markdown.** Terminal output and diffs have dedicated formatting and may contain Markdown punctuation that must remain literal.
**Apply the collapsed-card limit before Markdown rendering.** Source-line truncation can split a fenced block and makes the visible line count differ from the count used by the card.
## Consequences
Generic tool cards use the same Markdown vocabulary and sanitization path as conversation content. Markdown punctuation in a generic card is interpreted rather than always displayed literally; tools that require literal terminal output use the terminal card intent.
The focused TUI test pins hidden fences, retained language labels, and body text. The keyless terminal-state snapshot covers the behavior through an assembled TUI transcript.

29
.agents/notes/implemented/bug-fix/2026-07-23-tui-generic-card-markdown.zh.md
View File

@@ -1,29 +0,0 @@
# Agent Note: TUI 通用卡片的 Markdown 渲染
Status: implemented
[English](2026-07-23-tui-generic-card-markdown.md) | 中文
## Problem
工具展示器可以在通用卡片（generic card）内容中写入 Markdown，其中包括用于后台任务确认和执行错误的围栏 `console` 输出。把这些内容按纯文本渲染会暴露围栏标记，并与同一 transcript（文本记录）中的助手内容和用户内容显示不一致。
## Decision
TUI 先用共享的 Markdown 主题渲染通用卡片的结果内容，再应用卡片的头尾行数限制。终端卡片和 diff 卡片保留各自专门的纯文本渲染器；通用卡片的原始输入仍按字面显示，因为它代表的是工具参数，而非展示器撰写的行文。
共享主题隐藏围栏语法，保留可选的语言标签，并将围栏正文按代码配色。渲染先于截断执行，因此收起状态卡片的行数和边界描述的是可见的终端行，而非 Markdown 源文本行。
## Alternatives considered
**在 Bash 展示器中剥除围栏。**这只修复一个生产方，其他工具产生的通用卡片 Markdown 仍不会被渲染，还会让展示器依赖 TUI 的行为。
**把每种工具卡片都按 Markdown 渲染。**终端输出和 diff 有专门的格式，且可能包含必须保持字面显示的 Markdown 标点。
**在 Markdown 渲染之前应用收起状态卡片的行数限制。**按源文本行截断可能从中间截断围栏块，还会让可见行数与卡片使用的行数不一致。
## Consequences
通用工具卡片与对话内容使用同一套 Markdown 词汇和净化路径。通用卡片中的 Markdown 标点会被解释，而不再总是按字面显示；需要字面终端输出的工具使用终端卡片这一渲染意图。
聚焦的 TUI 测试固定了隐藏的围栏、保留的语言标签和正文文本。无密钥的终端状态快照通过组装后的 TUI transcript 覆盖该行为。

4
.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.i18n.yaml
View File

@@ -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
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md
2026-07-24-empty-model-response-is-retryable.md: 3ecb106fc3a53070f66d1de351120aaf99d4d0de
2026-07-24-empty-model-response-is-retryable.zh.md: 91ce4105ebe60b71f12667ccf28ea905566353d5
2026-07-24-empty-model-response-is-retryable.zh.md: 2573ef66d9ca1e6c0610686d0051c738774af588

20
.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.zh.md
View File

@@ -1,36 +1,36 @@
# Agent Note: Empty model completions are retryable EMPTY_RESPONSE failures
# Agent Note: 空模型补全是可重试的 EMPTY_RESPONSE 失败
Status: implemented
[English](2026-07-24-empty-model-response-is-retryable.md) | 中文
## Problem
## 问题
提供方偶尔会返回一种退化的 completion：流本身格式完好，携带一个终止性的 `stop` 结束，却没有任何内容块——没有文本、没有 reasoning（推理）、没有工具调用。如果适配器把这种形态映射为成功的 `{kind: 'stop'}` 结束，主循环就会记录一条空的 `assistant/message`，并把该轮次以 `completed` 结束。系统不会重试，失败也不会向调用方暴露，而像 goal-session 这样的驱动方会消耗一个轮次，却没有取得任何进展。
提供方偶尔会返回一种退化的 completion：流本身格式完好，以终止性的 `stop` 结束，却没有任何内容块——没有文本、没有推理（reasoning）、没有工具调用。如果适配器把这种形态映射为成功的 `{kind: 'stop'}` 结束，主循环就会记录一条空的 `assistant/message`，并把该轮次以 `completed` 结束。系统不会重试，失败也不会向调用方暴露，而像 goal-session 这样的驱动方会消耗一个 Round，却没有取得任何进展。
## Decision
## 决策
由适配器把「已完成但为空」的响应归类为一次提供方边界失败，重试策略则将其视为瞬时性问题：
- `dsh-llm` 在 `CONTEXT_WINDOW_EXCEEDED_CODE`/`QUOTA_EXCEEDED_CODE` 之外，导出规范代码 `EMPTY_RESPONSE_CODE`（`'EMPTY_RESPONSE'`）。
- `dsh-llm-pi-ai`（`mapStopReason`）：当终止性 `stop` 所对应的 assistant 消息没有内容块时，它会变成一个携带该代码的 `finish {kind: 'error'}`。上下文溢出检测在其适用场景中仍然优先（它先被检查，也是更具可操作性的归类）。
- `dsh-llm-deepseek`（`translate`）：在 `[DONE]` 处，若 `stop`（或缺失）结束且没有打开过任何块，则同样变成该错误结束。仅含 reasoning 的流算作有内容，仍视为成功。
- 提供方拥有的 normal 重试默认策略包含 `EMPTY_RESPONSE`：这次尝试没有产生任何持久内容，因此重复它是安全的；部署方仍可通过 `retryableCodes` 将其移除，而 `dsh-llm-retry` 会执行解析后的策略。
- `dsh-llm-deepseek`（`translate`）：在 `[DONE]` 处，若 `stop`（或缺失）结束且没有打开过任何块，则同样变成该错误结束。仅含推理的流算作有内容，仍视为成功。
- 由提供方定义的常规重试默认值包含 `EMPTY_RESPONSE`：这次尝试没有产生任何持久内容，因此重复它是安全的；部署方仍可通过 `retryableCodes` 将其移除，而 `dsh-llm-retry` 会执行解析后的策略。
检测仅限于 `stop` 结束。内容为空的 `max-tokens` 保持其既有含义（pi-ai 已经把零输出的溢出场景归一化处理），`tool-calls` 在实践中不可能是空块，而 error／aborted 结束本身已经算失败。
这套归类使用既有的主循环机制——`finishError` → `agent/request-error` → `dsh-llm-retry`——并让 `agent-loop` 保持提供方无关。重试预算耗尽时，该轮次会以显式的 `EMPTY_RESPONSE` 失败结束，而不是在没有内容的情况下成功结束。
## Alternatives considered
## 考虑过的替代方案
**在主循环或 `BlockAssembler` 中检测。** 只需一份共享实现，但这会把对提供方响应的判断挪进主循环，违背「插件优先，而非改动主循环」，且 assembler 是纯粹的组装算法。适配器才是把协议层面的事实转化为 harness 归类的地方，而溢出重归类正是精确的先例。
**在 `llm/stream` waterfall（瀑布式事件）上做一个流转换插件。** 这种做法提供方无关且只需一份实现，但它为「每个适配器几行就能声明的边界事实」额外增加了一个包和相应接线，而且默认开启的行为仍需改动每一个 bundle。
**把仅含空白或仅含 reasoning 的响应也当作空响应。** 作为过度设计予以否决：这类响应携带了模型产生的内容，把一个合法（哪怕无用）的响应误判为传输类失败，会在那些故意在 reasoning 之后停止的模型上引发重试循环。其范围严格限定为「零内容块」。
**把仅含空白或仅含推理的响应也当作空响应。** 作为过度设计予以否决：这类响应携带了模型产生的内容，把一个合法（哪怕无用）的响应误判为传输类失败，会在那些故意在推理之后停止的模型上引发重试循环。其范围严格限定为「零内容块」。
## Consequences
## 后果
- 一个偶发异常的提供方会消耗一次有界重试，而不是一个没有输出的轮次；一个持续返回空内容的模型则会暴露为用户可据以行动的 `EMPTY_RESPONSE` 轮次失败。
- 一个确实打算什么都不说的模型（罕见，但在一次工具结果之后有可能出现）会被重试，若始终为空，则该轮次失败。这个取舍是经过审慎权衡后接受的：一条空的 assistant 消息与提供方缺陷无法区分，且对用户毫无价值。
- `empty-response-retry` ACP 快照（一个人工编写的无密钥场景，配有确定性的 1 ms 零抖动重试 overlay，`examples/acp-agent/retry.cordis.yml`）钉住了产品可见的行为：持久的 `llm/retry` 事件、被丢弃的尝试不产生任何 ACP 输出、恢复后的回复，以及一次干净的已完成轮次。
- `empty-response-retry` ACP（Agent Client Protocol）快照（一个人工编写的无密钥场景，配有确定性的 1 ms 零抖动重试 overlay，`examples/acp-agent/retry.cordis.yml`）钉住了产品可见的行为：持久的 `llm/retry` 事件、被丢弃的尝试不产生任何 ACP 输出、恢复后的回复，以及一次正常完成的轮次。

4
.agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.i18n.yaml
View File

@@ -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
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.md
2026-07-24-recursive-python-sdk-session-notifications.md: c90213659391b565acd043a1be64e225f8babd31
2026-07-24-recursive-python-sdk-session-notifications.zh.md: 214a5ef924dcc9da3a97aab6385837acd2b364d9
2026-07-24-recursive-python-sdk-session-notifications.zh.md: f6f0a8c0e393bc19f24085b04db06056369bb329

4
.agents/notes/implemented/bug-fix/2026-07-24-recursive-python-sdk-session-notifications.zh.md
View File

@@ -10,7 +10,7 @@ Python SDK 过去通过将每条通知的 payload 与根会话 ID 直接比较
## 决策
`HarnessClient` 会在分发通知前，记录每条有效 `subagent.started` 所包含的 child-to-parent（子到父）关系。后续的 `subagent.finished` 会依据自身不可变的 parent ID 路由，但不会改写当前祖先关系，因此旧 run 即使在其 child ID 已被复用后才结束，也无法覆盖替代它的新会话。其他会话通知会沿客户端生命周期内保存的祖先关系图回溯自身 session ID，判断它们是否属于请求的根会话。该关系图会跨连续订阅保留，因此某个后代即使跨过一次 `Session.run()`，在后续轮次中发出通知时仍能正确归属；客户端启动新的运行时进程时会重置关系图。
`HarnessClient` 会在分发通知前，记录每条有效 `subagent.started` 所包含的 child-to-parent（子到父）关系。后续的 `subagent.finished` 会依据自身不可变的 parent ID 路由，但不会改写当前祖先关系，因此旧 run 即使在其 child ID 已被复用后才结束，也无法覆盖替代它的新会话。其他会话通知会沿客户端生命周期内保存的祖先关系图回溯自身 session ID，判断它们是否属于请求的根会话。该关系图会跨连续订阅保留，因此某个后代即使在一次 `Session.run()` 结束后仍然存续，在后续轮次中发出通知时仍能正确归属；客户端启动新的运行时进程时会重置关系图。
`Session.run()` 通过 `TurnResult.notifications` 与 `on_notification` 提供已发现会话树的完整通知流。只有 `sessionId` 等于请求根会话的 `session.event` 才会进入 `TurnResult.events` 或参与最终回复重建。因此调用方能够观察后代事件，同时子会话回复不会覆盖根会话回复。
@@ -26,4 +26,4 @@ Python SDK 过去通过将每条通知的 payload 与根会话 ID 直接比较
## 后果
高层消费者会按线上的原始顺序收到嵌套生命周期与会话通知，同时根轮次结果保持原有回复语义。客户端会为每个已观察到的子会话保留一条当前父关系，直到运行时重启；祖先回溯能够安全处理环，无关会话通知仍可从全局队列获取。无密钥 Python 测试覆盖两层派生、根回复隔离、会话树通知不堆积、跨订阅复用祖先关系，以及旧 run 乱序结束的复用 child ID。
高层消费方会按协议传输顺序收到嵌套生命周期与会话通知，同时根轮次结果保持原有回复语义。客户端会为每个已观察到的子会话保留一条当前父关系，直到运行时重启；祖先回溯能够安全处理环，无关会话通知仍可从全局队列获取。无密钥 Python 测试覆盖两层委派、根回复隔离、会话树通知不堆积、跨订阅复用祖先关系，以及旧 run 乱序结束的复用 child ID。

6
.agents/notes/implemented/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.i18n.yaml
View File

@@ -1,6 +0,0 @@
# 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
2026-07-24-tui-turn-end-stop-reason-notices.md: 7c783ce5a347b15d682dbeca03ad5355aca7950b
2026-07-24-tui-turn-end-stop-reason-notices.zh.md: 4a983525779b96c296ac2d621ca5928e7bed61c9

27
.agents/notes/implemented/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
View File

@@ -1,27 +0,0 @@
# Agent Note: TUI presents a reason for every turn-end kind
Status: implemented
English | [中文](2026-07-24-tui-turn-end-stop-reason-notices.zh.md)
## Problem
The TUI rendered transcript notices for `error`, `aborted`, `max-tokens`, `rejected`, and `interrupted` turn ends, but a `disposed` turn end and any plugin-added `TurnEndReasonMap` kind rendered nothing. When such a turn ended — live or replayed from a persisted log — the agent stopped working with no visible reason, breaking the product expectation that every stop is explained to the user.
## Decision
The `turn/end` case in `packages/ui/tui/src/index.ts` switches on the reason's discriminant and covers every kind: `completed` stays silent because the settled assistant message and its `Completed` timing header already present that outcome; `disposed` appends `Turn stopped: the agent was disposed.`; and the merge-extensible default appends `Turn ended: <kind>.` so an unknown plugin-added outcome still names why the agent stopped. All other kinds keep their existing notices.
## Alternatives considered
**A notice for `completed` turns too.** Rejected as noise: every ordinary response would gain a redundant line, and the assistant message plus its frozen timing header already mark the completion.
**Suppressing the `disposed` turn-end notice live because `agent/disposed` also appends `Agent "<id>" was disposed.`** Rejected: the two notices state different facts (this turn was cut short vs. the agent is gone), and the turn-end notice is the only one that survives replay of a persisted log, where the live `agent/disposed` emission does not recur.
**Keeping the default branch silent (the prior behavior).** Rejected: a merge-extensible kind unknown to the TUI is exactly the case where the user has no other way to learn why the agent stopped.
## Consequences
- A turn never ends without a user-visible reason in the TUI: every non-`completed` `turn/end` kind appends a transcript notice, including unknown plugin-added kinds by name.
- Live disposal during a running turn shows two notices (the turn-end notice plus `agent/disposed`); a replayed log shows the turn-end notice alone.
- The `errors-and-help` snapshot pins the `disposed` and unknown-kind notices alongside the existing failure and interruption notices.

27
.agents/notes/implemented/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
View File

@@ -1,27 +0,0 @@
# Agent Note: TUI 为每种轮次结束 kind 呈现原因
Status: implemented
[English](2026-07-24-tui-turn-end-stop-reason-notices.md) | 中文
## 问题
TUI 会为 `error`、`aborted`、`max-tokens`、`rejected`、`interrupted` 这几种轮次结束渲染 transcript（文本记录）通知，但 `disposed` 轮次结束和任何插件新增的 `TurnEndReasonMap` kind 不渲染任何内容。此类轮次结束时，无论实时发生还是从持久化日志回放，agent（智能体）都会在没有任何可见原因的情况下停止工作，违背了「每次停止都要向用户解释」的产品预期。
## 决策
`packages/ui/tui/src/index.ts` 中的 `turn/end` 分支按 reason 的判别字段做 switch，覆盖每一种 kind：`completed` 保持沉默，因为已定稿的助手消息及其 `Completed` 计时头部已经呈现了这一结果；`disposed` 追加 `Turn stopped: the agent was disposed.`；merge 扩展的 default 分支追加 `Turn ended: <kind>.`，让未知的插件新增结果仍能点明 agent 停止的原因。其余各 kind 保留现有通知。
## 备选方案
**为 `completed` 轮次也加一条通知。** 否决，属于噪音：每次普通响应都会平添一行冗余内容，而助手消息加上已冻结的计时头部本就标示了完成。
**因为 `agent/disposed` 也会追加 `Agent "<id>" was disposed.`，就在实时场景下抑制 `disposed` 轮次结束通知。** 否决：两条通知陈述的是不同事实（前者说明这一轮被中途截断，后者说明 agent 已不复存在），而且只有轮次结束通知在回放持久化日志时得以保留，实时发出的 `agent/disposed` 不会在回放中重现。
**让 default 分支保持沉默（沿用先前行为）。** 否决：TUI 不认识的 merge 扩展 kind，恰恰是用户没有其他途径得知 agent 为何停止的情形。
## 后果
- 在 TUI 中，轮次结束永远不会缺少用户可见的原因：每种非 `completed` 的 `turn/end` kind 都会追加一条 transcript 通知，未知的插件新增 kind 也会按名称列明。
- 轮次运行期间实时 dispose（资源释放）会显示两条通知（轮次结束通知加上 `agent/disposed`）；回放日志则只显示轮次结束通知。
- `errors-and-help` 快照把 `disposed` 通知和未知 kind 通知连同现有的失败与中断通知一并固定下来。

50
.agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.md
View File

@@ -1,50 +0,0 @@
# Agent Note: Question-composer option rows are scroll content, not the slack absorber
Status: implemented
English | [中文](2026-07-27-question-composer-rows-do-not-shrink.zh.md)
## Problem
The question composer card is capped against the viewport (`max-height: min(60vh, 520px)`) and scrolls its option list, so the header and the footer actions stay reachable on long question batches. When the composer seat got short — a small window, or a short viewport with the details panel open — the option rows rendered on top of each other and on top of the question title.
The cap was not the defect; the distribution of the shortfall was. `.options` is a `flex-direction: column` box whose children default to `flex-shrink: 1`, so under-allocation shrank the rows first instead of overflowing the scroll container. A row shrank to its `min-height: 42px` while `.optionCopy` kept the taller intrinsic height its wrapped copy needs (two lines for an option with a description). With `align-items: center`, the copy is then centered on a box shorter than itself and paints outside the row's border box in both directions — over the title above and the next row below. Measured on the shipped client at 900x440: 6.5px of copy outside the row box, growing to 10px at 380px tall, while `.options` reported `scrollHeight === clientHeight` and therefore never offered a scrollbar.
Only rows whose copy wraps can reproduce it. A row whose copy fits on one line has slack between its content and its 42px minimum, so shrinking it stays invisible — which is why the pre-existing e2e fixture (options `Blue`/`Green`, no descriptions) rendered correctly at every size.
## Decision
`.option` and `.custom` declare `flex-shrink: 0`.
The rows are the scroll content of a capped card; the card's overflow belongs to `.options`, which already owns `overflow-y: auto` and `min-height: 0`. Pinning the children makes the shortfall reach that scroll container instead of being absorbed by the rows, which is the behavior the cap was designed for. The alternative — letting rows shrink but keeping the copy inside them — would require clipping or ellipsizing option descriptions at exactly the sizes where the user most needs to read them.
`.header` and `.footer` already carried `flex-shrink: 0` for the same reason at the card level; the option list's children were the missing half of that rule.
## Alternatives considered
**Clip or ellipsize the copy inside a shrunk row (`overflow: hidden` on `.option`).** This removes the overlap with one declaration and no layout rethink. Rejected because it trades a visible defect for a silent one: the row keeps its 42px, and the second line of an option description simply disappears at exactly the sizes where the card is tightest. The description is decision-relevant content, not decoration.
**Drop `align-items: center` for `align-items: flex-start`.** The copy would grow downward only, so it would no longer paint over the title above. It does not fix anything: a shrunk row still overflows onto the row below, and the fix would silently change the vertical alignment of every option row at every size, including the common one.
**Remove the card's `max-height` cap so nothing is ever squeezed.** No shortfall means no distribution problem. Rejected because the cap is what keeps the header and the footer actions on screen for a long question batch; removing it reintroduces the failure the cap exists to prevent (the composer seat is a fixed-height conversation column with `overflow: hidden`, so an uncapped card loses its own submit button instead).
**Cap the wrapped copy at one line (`white-space: nowrap` plus ellipsis on `.description`).** Rows would never wrap, so they could never overflow when shrunk. Rejected for the same reason as clipping, plus it degrades the wide-viewport rendering — where there is ample room — to fix a narrow-viewport defect.
## Consequences
- A squeezed composer scrolls its option list instead of overlapping it: at 900x380 the list reports `scrollHeight` 200 against `clientHeight` 114 and offers a scrollbar, where before it reported them equal and offered none.
- Option rows keep their full wrapped copy at every viewport size. Nothing is clipped or ellipsized, and the wide-viewport rendering is unchanged (the rule only takes effect when the flex box is under-allocated).
- The card now reaches its scroll state sooner, since the shortfall is no longer partly absorbed by the rows. That is the intended behavior of the cap, and it means a short seat shows a scrollbar in cases that previously showed a silently mis-painted list.
- The scenario's recorded question is longer than it needs to be for the round trip it primarily tests. That cost is deliberate: the layout invariant is unfalsifiable without wrapping copy, and a second fixture for one CSS rule would be worse.
## Verification
The web e2e composer scenario asserts the invariant on the live composer at three squeezed seat heights (900x520 / 440 / 380): every option row's children stay inside the row's border box. Two guards keep the assertion from holding vacuously — at least one row must be wrapped (the only shape that overflows) and `.options` must actually be scrolling (proof the seat is genuinely capped). The scenario's recorded question now carries long option descriptions for exactly that reason; without wrapping copy the assertion cannot fail.
Confirmed both directions against the built client: with `flex-shrink: 0` reverted the scenario fails (`scrolls: false`, 6.5px spill), and with it restored it passes. A standalone geometry sweep over 340 viewport sizes (420-1600 x 320-960) went from 86 sizes with copy outside a row box to zero.
The assertion is replay-only: record mode must reach the fixture write rather than aborting on layout. Note that the composer ships as a client-module bundle, so `pnpm run build:web` alone does not pick up a change to `QuestionComposer.module.css` — the package build must run for the browser lane to see it.
Reproducing the shortfall requires a short viewport, not a short container. The cap is `min(60vh, 520px)`, so shrinking the conversation column below the card's own height clips the card without under-allocating it — the rows keep their full height and nothing spills. Anything demonstrating or measuring this defect outside the e2e scenario has to change the viewport.
A stale `lib/` makes the browser lane assert against an older client than the tree, and a `pnpm run build` that fails part-way leaves exactly that: the packages built before the failure are current, the rest are not. Refreshing a golden in that state records the older client's surface. Confirm the build exited zero before capturing, and note that untracked directories under `packages/` are compiled too — a leftover from another branch can fail the build for reasons the diff does not explain.

50
.agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.zh.md
View File

@@ -1,50 +0,0 @@
# Agent Note: 提问 composer 的选项行是滚动内容，而非空间不足时的吸收方
Status: implemented
[English](2026-07-27-question-composer-rows-do-not-shrink.md) | 中文
## 问题
提问 composer 的卡片会按视口设上限（`max-height: min(60vh, 520px)`），并让选项列表自行滚动，这样在成批提问时标题和底部操作按钮始终可达。但当 composer 的容器变矮时（窗口较小，或视口偏矮且详情面板处于展开状态），选项行会互相叠在一起，也会叠到问题标题上。
缺陷不在这个高度上限，而在高度不足时由谁来吸收。`.options` 是一个 `flex-direction: column` 的盒子，其子元素默认取 `flex-shrink: 1`，因此空间不足时首先被压缩的是各个选项行，而不是让滚动容器产生溢出。一行会被压到它的 `min-height: 42px`，而 `.optionCopy` 仍保持文案折行后所需的更大固有高度（带描述的选项会占两行）。由于 `align-items: center`，文案于是以一个比自身更矮的盒子为基准居中，并向上下两个方向画到该行边框盒之外——向上盖住标题，向下盖住下一行。在实际发布的客户端上于 900x440 处实测：文案有 6.5px 落在行盒之外，视口高度降到 380px 时增至 10px，而 `.options` 报告的 `scrollHeight` 等于 `clientHeight`，因此始终不会给出滚动条。
只有文案会折行的选项行才能复现该问题。文案单行即可容纳的行，其内容与 42px 最小高度之间尚有余量，被压缩也看不出来——这正是既有 e2e fixture（测试前置数据）（选项为 `Blue`／`Green`，无描述）在任何尺寸下都渲染正常的原因。
## 决策
`.option` 与 `.custom` 声明 `flex-shrink: 0`。
在设有高度上限的卡片中，这些行是滚动内容；卡片的溢出归 `.options` 承担，它本就持有 `overflow-y: auto` 与 `min-height: 0`。把子元素固定住之后，高度不足会传导到那个滚动容器，而不再被行本身吸收，这正是该高度上限设计时想要的行为。另一种做法是允许行被压缩，但把文案约束在行内，那就必须在用户最需要阅读选项描述的尺寸上对其做裁剪或省略号处理。
`.header` 与 `.footer` 出于同样的原因，已在卡片层级带有 `flex-shrink: 0`；选项列表的子元素正是这条规则缺失的另一半。
## 曾考虑的替代方案
**在被压缩的行内裁剪文案或加省略号（对 `.option` 设 `overflow: hidden`）。** 这样一条声明就能消除重叠，且不必重新考虑布局。之所以否决：它把一个可见缺陷换成了一个无声缺陷——行仍保持 42px，而选项描述的第二行会在卡片最紧张的那些尺寸上直接消失。描述属于影响决策的内容，不是装饰。
**把 `align-items: center` 改为 `align-items: flex-start`。** 文案就只会向下生长，因此不再向上盖住标题。但这什么也没修好：被压缩的行依然会溢出到下一行上，而且这一改动会在所有尺寸下（包括常见尺寸）无声改变每个选项行的垂直对齐。
**移除卡片的 `max-height` 上限，使其永远不会被压缩。** 没有高度不足，就没有分配问题。之所以否决：正是这个上限保证成批提问时标题和底部操作按钮留在屏幕内；移除它会重新引入该上限本就为之存在的失败（composer 所处的容器是一个固定高度、`overflow: hidden` 的会话列，因此不设上限的卡片会连自己的提交按钮一起丢掉）。
**把折行文案限制为单行（对 `.description` 设 `white-space: nowrap` 加省略号）。** 行永远不会折行，因此被压缩时也永远不会溢出。否决理由与裁剪相同，此外它还为了修一个窄视口缺陷，而牺牲了空间充裕的宽视口渲染效果。
## 后果
- 被压缩的 composer 会滚动其选项列表，而不是让它互相重叠：在 900x380 处，该列表报告 `scrollHeight` 为 200、`clientHeight` 为 114，并给出滚动条；此前两者相等，不给滚动条。
- 选项行在任何视口尺寸下都保留完整的折行文案。不裁剪、不加省略号，宽视口下的渲染保持不变（该规则仅在 flex 盒子空间不足时才生效）。
- 由于高度不足不再被行部分吸收，卡片现在更早进入滚动状态。这正是该高度上限想要的行为，也意味着在此前只会无声画错列表的情形下，矮容器现在会显示滚动条。
- 该场景录制的问题，比它主要测试的那次往返所需的长度更长。这个代价是有意付出的：没有折行文案，该布局不变式无法被证伪，而为一条 CSS 规则再加一份 fixture 会更糟。
## 验证
Web e2e 的 composer 场景会在三个被压缩的容器高度（900x520／440／380）上，对活动的 composer 断言该运行时不变式：每个选项行的子元素都留在该行的边框盒之内。两道守卫防止该断言空洞地成立——必须至少有一行处于折行状态（这是唯一会溢出的形态），且 `.options` 必须确实处在滚动状态（证明容器确实触及了高度上限）。该场景录制的问题现在带有较长的选项描述，正是为此；没有折行文案，这条断言不可能失败。
在构建产物客户端上双向确认过：撤销 `flex-shrink: 0` 后该场景失败（`scrolls: false`，6.5px 溢出），恢复后通过。一次覆盖 340 种视口尺寸（420-1600 x 320-960）的独立几何遍历，从 86 种尺寸存在文案落在行盒之外，降到 0 种。
该断言仅在回放模式下执行：录制模式必须走到写入 fixture 那一步，而不是在布局检查处中断。另需注意，composer 以客户端模组包的形式发布，因此单跑 `pnpm run build:web` 不会带上对 `QuestionComposer.module.css` 的改动——必须执行包构建，浏览器测试通道才能看到它。
要复现这种空间不足，需要的是矮视口，而不是矮容器。高度上限为 `min(60vh, 520px)`，因此把会话列压到比卡片自身高度更矮，只会裁剪卡片，而不会让它空间不足——各行仍保持完整高度，也不会有任何溢出。凡是在 e2e 场景之外演示或测量该缺陷的手段，都必须改变视口。
`lib/` 陈旧会让浏览器测试通道对着一个比工作树更旧的客户端做断言，而中途失败的 `pnpm run build` 留下的正是这种状态：失败之前构建的那些包是新的，其余不是。在这种状态下刷新 golden，记录下来的是旧客户端的界面。抓取之前先确认构建以 0 退出；另需注意 `packages/` 下的未跟踪目录同样会被编译——来自另一个分支的遗留物可能以 diff 无法解释的原因让构建失败。

2
.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
View File

@@ -3,4 +3,4 @@
# 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-27-stable-snapshot-refresh-volatiles.md
2026-07-27-stable-snapshot-refresh-volatiles.md: e2e951cd9f78b319a701a3e60afba48786633f03
2026-07-27-stable-snapshot-refresh-volatiles.zh.md: 55302b509e28520f90f6cd820e4962be014318cc
2026-07-27-stable-snapshot-refresh-volatiles.zh.md: 8ba35f4bbc2a4b408a01e11f09bd767860964875

4
.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
View File

@@ -10,9 +10,9 @@ ACP（Agent Client Protocol）快照比较会归一化生成的 UUID、cwd 别
## 决策
刷新写回以 `normalizeSessionLog` 作为易变值的唯一判定依据。系统使用本次运行的 id、cwd 及全部 cwd 别名归一化原始收集记录，并使用 fixture header 上下文归一化 fixture 记录；字面量替换只影响要写入的原始值。现有记录完成对齐后，系统基于这些归一化记录，递归比较本次生成记录与现有记录的叶节点：归一化后等价的叶节点保留现有原始值，归一化后不同的叶节点则保留本次生成的语义值。
刷新写回以 `normalizeSessionLog` 作为易变值的唯一判定依据。系统使用本次运行的 id、cwd 及全部 cwd 别名归一化原始收集记录，并使用 fixture 头部上下文归一化 fixture 记录；字面量替换只影响要写入的原始值。现有记录完成对齐后，系统基于这些归一化记录，递归比较本次生成记录与现有记录的叶节点：归一化后等价的叶节点保留现有原始值，归一化后不同的叶节点则保留本次生成的语义值。
复用前必须确保完整逻辑记录布局对齐，现有的打包分片与插入标题等价情形除外。归一化后等价但发生变化的字符串在整份日志范围内形成双射：一个本次生成的字符串只映射到一个现有字符串，反向亦然，因此跨记录重复出现的 ID 仍保持关联。出现无法解释的记录不匹配或映射冲突时，该日志会停用规范化字符串复用。
复用前必须确保完整逻辑记录布局对齐，现有的打包分片与插入标题等价情形除外。归一化后等价但发生变化的字符串在整份日志范围内形成双射：一个本次生成的字符串只映射到一个现有字符串，反向亦然，因此跨记录重复出现的 ID 仍保持关联。出现无法解释的记录不匹配或映射冲突时，该日志会停用归一化字符串复用。
对象字段按键对齐。只有所有对应数组长度相同时，才对齐其元素；否则以本次生成的数组为准。字符串始终作为不可拆分的叶节点。现有的打包分片计时对齐与插入标题处理仍保持独立，因为它们对齐的是逻辑事件，而非单条记录内的值。

23
.agents/notes/implemented/bug-fix/2026-07-27-tool-card-single-row-fields-inline.md
View File

@@ -1,23 +0,0 @@
# Agent Note: Tool-card single-row fields render inline
Status: implemented
English | [中文](2026-07-27-tool-card-single-row-fields-inline.zh.md)
## Problem
A tool card's title, description, cwd, and pending `$ <command>` echo are each one logical row. The bash tool sets the card title (and description) directly from the model's command and description, which for a multi-line bash script contain real newlines. These fields were escaped with `displayText`, which deliberately preserves `\n` as structural layout. A multi-line title therefore broke onto extra terminal rows that the card's line accounting did not reserve, so the title's later lines overwrote the description, the output, or the editor's steering hint — the card rendered as garbled, overlapping text. Removing the gutter bar (see the [copyable-transcript note](../simplification/2026-07-27-copyable-transcript-no-gutter-bar.md)) made the collision visible because those rows no longer sat behind a per-line prefix.
## Decision
Single-row card fields use `displayInlineText` (which escapes `\n` to the literal `\x0a`) instead of `displayText`: the card title, the terminal-card `description` and `cwd` meta rows, and the pending `$ <command>` echo. Each stays on exactly one row, so a multi-line command can no longer break rows and collide with adjacent lines. Genuinely multi-line fields — captured command output and the `contentText` result body — keep `displayText` plus `split('\n')`, because those legitimately occupy multiple rows.
## Alternatives considered
- **Strip newlines from the presenter output** (in the bash tool) — hides the model's real command shape from any consumer of the view, and pushes a UI concern into the tool. The escape belongs at the single-row render site.
- **Let the title wrap to multiple rows deliberately** — a card title is a one-line identity; a wrapped multi-line title still collides with the following meta rows unless the whole card is re-laid-out, and it bloats the transcript.
## Consequences
- Multi-line bash commands render as a single inline title (`S=/tmp\x0aecho …`); the description, output, and exit rows below stay intact. Verified live in tmux for both the pending (`◌`) and completed (`✓`) states.
- A `multilineTerminal` tool-card case in `tui.spec.ts` asserts the inline-escaped form appears for a newline-bearing title and description.

23
.agents/notes/implemented/bug-fix/2026-07-27-tool-card-single-row-fields-inline.zh.md
View File

@@ -1,23 +0,0 @@
# Agent Note: 工具卡片的单行字段以内联方式渲染
Status: implemented
[English](2026-07-27-tool-card-single-row-fields-inline.md) | 中文
## Problem
工具卡片的标题、描述、cwd 以及待执行的 `$ <command>` 回显各自都是一个逻辑行。bash 工具直接用模型给出的命令与描述来设置卡片标题（和描述），而对于多行 bash 脚本，这些内容包含真实换行。这些字段此前用 `displayText` 转义，而 `displayText` 会刻意保留 `\n` 作为结构性布局。于是多行标题会换到卡片行数核算未预留的额外终端行上，标题后续的行便覆盖了描述、输出，或编辑器的 steering 提示——卡片渲染成互相重叠的乱码文本。移除 gutter bar（见[可复制 transcript 的 note](../simplification/2026-07-27-copyable-transcript-no-gutter-bar.md)）后，这些行不再位于逐行前缀之后，因而暴露了这一冲突。
## Decision
单行卡片字段改用 `displayInlineText`（将 `\n` 转义为字面量 `\x0a`）而非 `displayText`：包括卡片标题、terminal 卡片的 `description` 与 `cwd` 元数据行，以及待执行的 `$ <command>` 回显。每个字段都严格保持在一行内，因此多行命令不再会换行并与相邻行冲突。真正多行的字段——捕获的命令输出与 `contentText` 结果正文——仍保留 `displayText` 加 `split('\n')`，因为它们本就应占据多行。
## Alternatives considered
- **在 presenter 输出中剥除换行**（在 bash 工具里）—— 会对该视图的所有消费方隐藏模型真实的命令形态，并把 UI 关注点塞进工具。转义应发生在单行渲染处。
- **让标题刻意换到多行** —— 卡片标题是一行式身份标识；除非重排整个卡片，多行标题仍会与其后的元数据行冲突，还会让 transcript 膨胀。
## Consequences
- 多行 bash 命令渲染为单行内联标题（`S=/tmp\x0aecho …`）；其下的描述、输出与退出码行保持完整。已在 tmux 中对待执行（`◌`）与已完成（`✓`）两种状态实测验证。
- `tui.spec.ts` 中新增了一个 `multilineTerminal` 工具卡片用例，断言对含换行的标题与描述会出现内联转义后的形式。

37
.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md
View File

@@ -1,37 +0,0 @@
# Agent Note: TUI diff card dropped the duplicated file path
Status: implemented
English | [中文](2026-07-27-tui-diff-card-redundant-path-header.zh.md)
## Problem
The `edit` and `write` tool cards printed the target path twice. Each tool's `presentCall`/`presentResult` returns a diff card whose title is `Edit <path>`/`Write <path>` and whose single `FileDiff` carries the same `path`. The TUI's `diffLines` unconditionally rendered `palette.bold(diff.path)` as a per-file header, so a one-file edit rendered:
```
✓ Edit src/foo.ts
src/foo.ts
- old
+ new
```
The existing snapshot fixture hid the bug: it titled the edit card `Edit renderer` (no path) and gave the result two diffs, so the title never matched a diff path and the header never looked redundant.
## Decision
`diffLines` takes a `showPath` flag; `ToolCardComponent.renderBody` suppresses the per-file header for a diff card when there is exactly one diff and the effective card title (`resultView?.title ?? callView.title`) already contains that diff's path. Multi-file diff cards keep every per-file header. An empty or blank diff path collapses under the same `String.includes` check, which is the intended noise removal.
The suppression lives in the TUI renderer, not in each tool's presenter, because the redundancy is a presentation concern shared by every current and future single-file diff card; the tools keep emitting the path in both the title and the diff so non-TUI consumers still get it.
## Alternatives considered
- Drop the path from the `edit`/`write` card titles. Rejected: the title is the scannable summary line; removing the path weakens it, and it would have to be repeated per tool.
- Always drop the per-file header. Rejected: multi-file result diffs (and any future multi-file diff card) genuinely need per-file headers.
## Consequences
The heuristic is a substring match, so a title that happens to contain a single diff's path suppresses the header even if the match is incidental; for the real producers the title is exactly `Verb <path>`, so this is correct in practice. The snapshot `edit` fixture now mirrors production: one diff whose path the title names, proving the header is dropped, while multi-file header retention is covered by the `tui.spec.ts` `edit` fixture (`a.txt`/`b.txt` under an `Edit files` title).
## Testing
`tui.spec.ts` adds a focused case asserting the path appears exactly once for a single-diff card titled `Edit src/only.ts`. The `advanced-cards-*` keyless snapshots re-recorded to show the title line immediately followed by the diff body with no repeated path header.

37
.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.zh.md
View File

@@ -1,37 +0,0 @@
# Agent Note: TUI diff 卡片重复打印文件路径
Status: implemented
[English](2026-07-27-tui-diff-card-redundant-path-header.md) | 中文
## Problem
`edit` 与 `write` 工具卡片会把目标路径打印两次。两者的 `presentCall`/`presentResult` 返回的 diff 卡片，标题为 `Edit <path>`/`Write <path>`，而其唯一的 `FileDiff` 又携带相同的 `path`。TUI 的 `diffLines` 无条件地将 `palette.bold(diff.path)` 渲染为每文件的表头，因此单文件编辑会渲染成：
```
✓ Edit src/foo.ts
src/foo.ts
- old
+ new
```
既有的快照 fixture 掩盖了这个问题：它把编辑卡片标题设为 `Edit renderer`（不含路径），并让结果包含两个 diff，于是标题从未与某个 diff 路径匹配，表头也就不显得冗余。
## Decision
`diffLines` 新增 `showPath` 参数；当一个 diff 卡片只有一个 diff、且生效标题（`resultView?.title ?? callView.title`）已包含该 diff 的路径时，`ToolCardComponent.renderBody` 抑制每文件表头。多文件 diff 卡片保留全部每文件表头。空白或空路径同样落入这条 `String.includes` 判定之下，这正是有意去除的噪声。
抑制逻辑放在 TUI 渲染层，而非各工具的 present 方法中，因为这种冗余是所有当前及未来单文件 diff 卡片共有的展示问题；工具仍在标题和 diff 中同时给出路径，从而非 TUI 消费方依旧能拿到它。
## Alternatives considered
- 从 `edit`/`write` 卡片标题中去掉路径。已否决：标题是可快速扫读的摘要行，去掉路径会削弱它，而且需要在每个工具里重复处理。
- 一律去掉每文件表头。已否决：多文件结果 diff（以及未来任何多文件 diff 卡片）确实需要每文件表头。
## Consequences
该启发式是子串匹配，因此若标题恰好包含某个单一 diff 的路径，即便是偶然匹配也会抑制表头；对真实的产出方而言标题恰为 `Verb <path>`，故在实践中是正确的。快照 `edit` fixture 现在与生产一致：单个 diff，其路径正是标题所命名，从而证明表头被去除；而多文件表头保留由 `tui.spec.ts` 的 `edit` fixture（`Edit files` 标题下的 `a.txt`/`b.txt`）覆盖。
## Testing
`tui.spec.ts` 新增一个聚焦用例，断言标题为 `Edit src/only.ts` 的单 diff 卡片中路径恰好出现一次。`advanced-cards-*` 无密钥快照已重新录制，展示标题行紧接 diff 正文、不再有重复的路径表头。

6
.agents/notes/implemented/bug-fix/2026-07-27-tui-step-timing-trails-tool-cards.i18n.yaml
View File

@@ -1,6 +0,0 @@
# 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
2026-07-27-tui-step-timing-trails-tool-cards.md: 82f46b44d3b939ca89c4508eb948ed584082d9fd
2026-07-27-tui-step-timing-trails-tool-cards.zh.md: 885b232973d20013782dee7ec1e846e7a012b01e

28
.agents/notes/implemented/bug-fix/2026-07-27-tui-step-timing-trails-tool-cards.md
View File

@@ -1,28 +0,0 @@
# Agent Note: TUI step timing trails the step's last message
Status: implemented
English | [中文](2026-07-27-tui-step-timing-trails-tool-cards.zh.md)
## Problem
The per-step timing summary (`Model wait … · Completed …`) was a child of the assistant message component, so it rendered directly under the assistant text. When a step drove tool calls, the tool cards were appended to the chat *after* the assistant message, leaving the timing line stranded above them — one message before the step's actual last output. The summary is meant to close a step, so on any tool-calling step it appeared in the wrong place.
## Decision
The timing summary is its own `StepTimingComponent`, no longer a child of `AssistantMessageComponent`. `StreamingAssistantComponent` owns one and exposes it as `timing`, but the renderer attaches it to the chat as a sibling that follows the assistant message. Whenever a `tool/call` or `tool/result` of the open step appends a card, `trailStreamingTiming()` moves the footer back to the tail of the chat, so it always trails the step's last message. On `step/end` the footer is completed in place — already at the tail — and stays pinned while the next step's output follows. `removeStreaming` and the reasoning-toggle rebuild detach and reattach the footer together with its streaming component.
Event ordering makes this exact: within a step the loop appends `tool/call` and `tool/result` before `step/end`, so the footer is repositioned while `streaming` is still set, then frozen when the step ends.
## Alternatives considered
**Keep the timing inside the assistant message and reorder tool cards above it.** Rejected: tool cards belong after the assistant text that requested them; moving them above the assistant message to sit under the timing would misrepresent the transcript order.
**Recompute a single trailing footer for the whole turn instead of one per step.** Rejected: a multi-step turn shows each step's own completed timing, and collapsing them would drop the per-step buckets the existing timing tests pin.
**Reposition the footer from a `step/end`-only handler.** Rejected: tool cards render before `step/end`, so a footer moved only at step end would already be trailing but would not track a mid-step re-render, and the running (pre-completion) footer would still sit above the tool cards during streaming.
## Consequences
- On a tool-calling step the timing summary renders below the tool cards, both while the turn runs and after it completes; the package snapshots (`untrusted-controls`, `cordis-tools-pending`, `advanced-cards-*`, `code-mode-pending`, `dynamic-workflow-pending`, `surface-before-compaction`) and the example transcripts (`todo-plan`, `bash-terminal-card`, `code-mode`, `parallel-file-reads`, `dynamic-workflow`, `cordis-dynamic-toolchain`, `code-mode-dispatch-spill`) pin the new order.
- A unit test asserts the completed timing appears after a step's tool output; it fails on the pre-fix ordering.

28
.agents/notes/implemented/bug-fix/2026-07-27-tui-step-timing-trails-tool-cards.zh.md
View File

@@ -1,28 +0,0 @@
# Agent Note: TUI 步骤计时跟在该步骤最后一条消息之后
Status: implemented
[English](2026-07-27-tui-step-timing-trails-tool-cards.md) | 中文
## 问题
每步的计时摘要（`Model wait … · Completed …`）原本是助手消息组件的子节点，因此直接渲染在助手文本下方。当某一步触发 tool call 时，tool card（工具卡片）会在助手消息*之后*追加到聊天区，使计时行被搁在它们上方——落在该步骤真正的最后一条输出之前一条消息处。该摘要本意是收束一个步骤，因此在任何含 tool call 的步骤上都出现在了错误的位置。
## 决策
计时摘要现在是独立的 `StepTimingComponent`，不再是 `AssistantMessageComponent` 的子节点。`StreamingAssistantComponent` 持有一个并以 `timing` 暴露它，但渲染器把它作为紧随助手消息之后的同级节点挂到聊天区。每当当前打开步骤的 `tool/call` 或 `tool/result` 追加一张卡片，`trailStreamingTiming()` 就把该页脚移回聊天区末尾，使它始终跟在该步骤的最后一条消息之后。在 `step/end` 时该页脚就地定稿——此时已在末尾——并在后续步骤的输出接续时保持钉住。`removeStreaming` 与推理开关重建会把该页脚连同其流式组件一起摘除并重新挂上。
事件顺序让这一点精确成立：在一个步骤内，循环会先追加 `tool/call` 和 `tool/result`，再追加 `step/end`，因此页脚是在 `streaming` 仍被设置时重新定位的，随后在步骤结束时冻结。
## 备选方案
**把计时保留在助手消息内部，改为把 tool card 排到它上方。** 否决：tool card 应位于请求它们的助手文本之后；把它们移到助手消息上方以贴在计时下方，会歪曲 transcript（文本记录）的顺序。
**为整个轮次重算一个末尾页脚，而非每步一个。** 否决：多步轮次会显示各步自己的完成计时，合并它们会丢掉现有计时测试所固定的每步分桶。
**只在 `step/end` 处理器里重新定位页脚。** 否决：tool card 在 `step/end` 之前渲染，因此仅在步骤结束时移动的页脚虽已处于末尾，却无法跟踪步骤中途的重新渲染，而且流式过程中运行态（完成前）的页脚仍会落在 tool card 上方。
## 后果
- 在含 tool call 的步骤上，计时摘要渲染在 tool card 下方，轮次运行期间与完成之后皆如此；相关包快照（`untrusted-controls`、`cordis-tools-pending`、`advanced-cards-*`、`code-mode-pending`、`dynamic-workflow-pending`、`surface-before-compaction`）与示例 transcript（`todo-plan`、`bash-terminal-card`、`code-mode`、`parallel-file-reads`、`dynamic-workflow`、`cordis-dynamic-toolchain`、`code-mode-dispatch-spill`）固定了新顺序。
- 一个单元测试断言完成计时出现在某步骤的工具输出之后；在修复前的顺序下它会失败。

2
.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
View File

@@ -3,4 +3,4 @@
# 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-load-pre-identity-session-messages.md
2026-07-28-load-pre-identity-session-messages.md: 2901527658421b37576bdf5b49e66829104a3b41
2026-07-28-load-pre-identity-session-messages.zh.md: 61d57ac9f3318299b63faa659b6d155e8e89fae3
2026-07-28-load-pre-identity-session-messages.zh.md: 210064f6e7c1ea239da89c4542346e164c48e274

12
.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
View File

@@ -6,15 +6,15 @@ Status: implemented
## 问题
带标识的不可变消息变更将四种持久事件载荷替换为完整消息值。现有的 v0 JSONL 和 SQLite 会话仍保留紧邻该变更之前的形状：用户事件和 steering（中途引导）事件直接携带 `content`/`source`，assistant 事件携带 `content`/`provenance`，工具结果则携带 `callId`/`content`/`isError`。这些会话的 header 仍与 `SESSION_FORMAT_VERSION` 匹配，但当前形状验证会拒绝它们，导致恢复流程无法构造实时 `Session`。
带标识的不可变消息变更将四种持久化事件载荷替换为完整消息值。现有的 v0 JSONL 和 SQLite 会话仍保留紧邻该变更之前的形状：用户事件和 steering（中途引导）事件直接携带 `content`/`source`，assistant 事件携带 `content`/`provenance`，工具结果则携带 `callId`/`content`/`isError`。这些会话的标头仍与 `SESSION_FORMAT_VERSION` 匹配，但当前形状验证会拒绝它们，导致恢复流程无法构造活跃的 `Session`。
消息表示改变时没有提升版本，导致这些日志无法仅凭 header 与当前的 v0 日志区分。运行时需要一条范围受限的导入规则，既能恢复受支持的第一方后端所创建的数据，又不削弱对无关过时事件或格式错误事件的验证。
消息表示改变时没有提升版本，导致这些日志无法仅凭标头与当前的 v0 日志区分。运行时需要一条范围受限的导入规则，既能恢复受支持的第一方后端所创建的数据，又不削弱对无关过时事件或格式错误事件的验证。
## 决策
`PersistenceCoordinator` 会在后端解码之后、当前消息验证之前，规范化消息标识机制引入前的四种特定消息载荷。它将载荷现有的语义字段包装进当前按角色区分的消息形状，并为其分配确定性的导入 `MessageId`：`legacy-message:<session-id>:<event-seq>`。旧版 `tool/result` 的内容替换会继承替换目标导入后的 id，从而保持当前仅改写内容的不变量。
`PersistenceCoordinator` 会在后端解码之后、当前消息验证之前，规范化消息标识机制引入前的四种特定消息载荷。它将载荷现有的语义字段包装进当前按角色区分的消息形状，并为其分配确定性的导入用 `MessageId`：`legacy-message:<session-id>:<event-seq>`。旧版 `tool/result` 的内容替换会继承替换目标导入后的 id，从而保持当前仅改写内容的不变量。
同一项规范化也用于 `load`、`inspect`、无 owner 的已加载状态认领其实时会话，以及 HMR（热模块替换）前缀接管。因此，前缀比较会将实时的当前形状 seed 与同一份规范化存储视图进行比较。看似当前形状、但字段缺失或无效的包装层不会被修复；不受支持的事件词汇、请求 header、版本和 surface 关系仍沿用现有拒绝路径。
同一项规范化也用于 `load`、`inspect`、无 owner 的已加载状态认领其活跃会话，以及 HMR（热模块替换）前缀接管。因此，前缀比较会将活跃会话的当前形状 seed 与同一份规范化存储视图进行比较。看似当前形状、但字段缺失或无效的包装层不会被修复；不受支持的事件词汇、请求 header、版本和 surface 关系仍沿用现有拒绝路径。
这项升级只发生在读取时。存储中的旧版记录保持不变；会话恢复后，只会在其后追加当前形状的事件。确定性标识使重复加载以及新旧形状混合的日志无需执行后端专用的重写事务，也能复现相同的消息 id。
@@ -28,9 +28,9 @@ Status: implemented
## 后果
消息标识机制引入前的 JSONL 和 SQLite 会话可以恢复，并保留原始的消息内容、来源、提供方溯源信息、工具关联、错误、元数据和 surface 替换。除此之外，返回事件与当前导入的消息快照无法区分，并且仍然经过深度冻结。
消息标识机制引入前的 JSONL 和 SQLite 会话可以恢复，并保留原始的消息内容、来源、提供方溯源信息、工具调用关联、错误、元数据和 surface 替换。除此之外，返回事件与当前导入的消息快照无法区分，并且仍然经过深度冻结。
这是一个显式的同版本导入例外，而非通用的 v0 兼容层。若要增加另一个例外，必须在持久化边界提供另一套完整且无歧义的映射；当前数据若格式错误，系统仍会拒绝，而不会猜测如何将其变成有效数据。共享协调器契约会针对内存参考实现、JSONL 和 SQLite 后端验证这项升级，包括重新加载时的确定性，以及工具结果替换时的标识继承。
这是一个显式的同版本导入例外，而非通用的 v0 兼容层。若要增加另一个例外，必须在持久化边界提供另一套完整且无歧义的映射；当前数据若格式错误，系统仍会拒绝，而不会猜测如何将其变成有效数据。共享的协调器契约会在内存参考实现、JSONL 和 SQLite 后端上验证这项升级，包括重新加载时的确定性，以及工具结果替换时的标识继承。
## 相关

4
.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
View File

@@ -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-themed-scrollbars-and-reserved-gutter.md
2026-07-28-themed-scrollbars-and-reserved-gutter.md: b45f70b126d083916c756afb88a8b646a4e9bb85
2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 8afa36429ce7e6e061b014d63dcb20e5a642a84c
2026-07-28-themed-scrollbars-and-reserved-gutter.md: ba3d9d3c94cf9a775c43c14e292187b3a43935fe
2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 51d668f584ee254183d5d1cf709140df2556e8d0

4
.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
View File

@@ -20,7 +20,7 @@ The rules sit on `body`, not `html`. `design-platform.css` declares the `--dsw-a
The two renderings are mutually exclusive, and the exclusion is enforced rather than assumed. A non-`auto` `scrollbar-width` or `scrollbar-color` makes Chromium and Safari discard every `::-webkit-scrollbar*` rule for that element, `::-webkit-scrollbar-thumb:hover` included. Declaring both unconditionally therefore leaves the hover token rendering nowhere at all: the engines that implement the hover pseudo-element are exactly the ones the standard properties silence, and Firefox has no hover pseudo-element to fall back on. The standard properties consequently sit inside `@supports not selector(::-webkit-scrollbar)`, which is true only where the pseudo-element is unimplemented, so Firefox takes the standard path and WebKit-based engines take the pseudo-element path. The WebKit rules are not gated in turn: an engine without those pseudo-elements drops them as unknown selectors, so a gate would only restate what selector matching already does. An engine too old for the `selector()` function makes the condition invalid, which evaluates false and selects the pseudo-element path — the correct side for the pre-16.4 Safari that is the realistic case for that reading.
Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. The mechanically discoverable subset is owned by `packages/client/ui-theme/tests/scrollbar-styles.spec.ts`: any sheet that both scrolls and paints an elevated surface must rebind, so this note no longer maintains a complete surface inventory. Most declare the pair on the elevated card rather than on the scrolling descendant, because elevation belongs to the surface and custom properties inherit to whichever child actually scrolls.
Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. `transparent` is the pair's other legal target, added when the sidebar's bars [started following the pointer](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md); the gate below admits those two and nothing else. The mechanically discoverable subset is owned by `packages/client/ui-theme/tests/scrollbar-styles.spec.ts`: any sheet that both scrolls and paints an elevated surface must rebind, so this note no longer maintains a complete surface inventory. Most declare the pair on the elevated card rather than on the scrolling descendant, because elevation belongs to the surface and custom properties inherit to whichever child actually scrolls.
Four surfaces — `Menu`, `InputBar`, `QuestionComposer`, and `TodoPanel` — were missed in the first implementation and found in review, which is why the per-sheet rebinding contract is checked mechanically rather than by inspection.
@@ -54,7 +54,7 @@ The gutter and the sheet's `::-webkit-scrollbar` width are jointly necessary aga
## Consequences
- Every scroll container in the client draws the themed thumb: `rgb(229, 229, 229)` on a light base surface, `rgb(60, 60, 61)` on a dark one, and `rgb(84, 85, 87)` for a dark elevated surface that rebinds to the l2 pair.
- Every scroll container in the client draws the themed thumb: `rgb(229, 229, 229)` on a light base surface, `rgb(60, 60, 61)` on a dark one, and `rgb(84, 85, 87)` for a dark elevated surface that rebinds to the l2 pair. The sidebar's regions draw theirs only under the pointer, through the same indirection.
- The two renderings are separately specified, so a change to the thumb's geometry or hover behavior has to be made twice — once in `scrollbar-width`/`scrollbar-color`, once in the pseudo-elements. Routing both through the indirection pair confines that duplication to the properties Firefox and WebKit do not share.
- The hover tokens (`--dsw-alias-scrollbar-hover-l1`/`-l2`) render only on the pseudo-element path. Firefox states one thumb color through `scrollbar-color` and derives its own hover treatment, so a design change to the hover colors is visible in Chromium and Safari and not in Firefox. This is a limit of `scrollbar-color`, not of the sheet.
- `body *` matches every element, for two properties whose effect the user agent already limits to elements that actually scroll. The cost is a broad selector; the alternative was a rebinding contract that does not work.

4
.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
View File

@@ -20,7 +20,7 @@ Status: implemented
两种渲染互斥，而这种互斥是被强制的，不是假定的。`scrollbar-width` 或 `scrollbar-color` 只要取非 `auto` 值，Chromium 与 Safari 就会丢弃该元素上的全部 `::-webkit-scrollbar*` 规则，`::-webkit-scrollbar-thumb:hover` 也在其中。因此无条件地同时声明会让 hover token 在任何地方都得不到渲染：实现了 hover 伪元素的引擎，恰恰就是被标准属性静音的那些，而 Firefox 没有 hover 伪元素可作退路。于是标准属性写在 `@supports not selector(::-webkit-scrollbar)` 之内，该条件只在伪元素未被实现处为真，因此 Firefox 走标准属性路径，WebKit 系引擎走伪元素路径。WebKit 规则不再反向加门禁：不实现这些伪元素的引擎会把它们当作未知选择器丢弃，因此加门禁只是重述选择器匹配本身已经做的事。对于旧到不支持 `selector()` 函数的引擎，该条件无效，从而求值为假并选中伪元素路径——对于这条判断下现实存在的 16.4 之前的 Safari，这正是正确的一侧。
两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。这组变量另一个合法的目标是 `transparent`，它随侧边栏滚动条[改为跟随指针](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md)一并引入；下文的门禁只接受这两种目标。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定契约由机械检查而非人工审阅把关。
@@ -54,7 +54,7 @@ Status: implemented
## 后果
- 客户端的每个滚动容器都绘制带主题的滑块：亮色基础表面为 `rgb(229, 229, 229)`，暗色基础表面为 `rgb(60, 60, 61)`，重新绑定到 l2 的暗色抬升表面为 `rgb(84, 85, 87)`。
- 客户端的每个滚动容器都绘制带主题的滑块：亮色基础表面为 `rgb(229, 229, 229)`，暗色基础表面为 `rgb(60, 60, 61)`，重新绑定到 l2 的暗色抬升表面为 `rgb(84, 85, 87)`。侧边栏内的滚动区域经由同一组间接变量，只在指针到达时才绘制滑块。
- 两种渲染分别指定，因此改动滑块的几何或 hover 行为需要改两处：一处在 `scrollbar-width`／`scrollbar-color`，一处在伪元素。让两者都经由这组间接变量，把这份重复限制在 Firefox 与 WebKit 不共用的那些属性上。
- hover token（`--dsw-alias-scrollbar-hover-l1`／`-l2`）只在伪元素路径上渲染。Firefox 通过 `scrollbar-color` 只表述一个滑块颜色，其 hover 表现由引擎自行推导，因此对 hover 颜色的设计改动在 Chromium 与 Safari 上可见，在 Firefox 上不可见。这是 `scrollbar-color` 本身的限制，不是这张样式表的限制。
- `body *` 匹配所有元素，涉及的两个属性其效果本就被浏览器限制在实际会滚动的元素上。代价是一个覆盖面很宽的选择器；另一种选择是一个不生效的重新绑定契约。

6
.agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.i18n.yaml → .agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
View File

@@ -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 .agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.md
2026-07-30-web-details-default-closed.md: 658b6fc2c18dc67d8759bec78997f32dcba27914
2026-07-30-web-details-default-closed.zh.md: 5a1d0e4713e47ce3bc0cc68fa4c4f5f8c94c945f
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md
2026-07-28-web-agent-runtime-context.md: 6c2bb8faf0db56d2a29b47726ab295c3501cce2d
2026-07-28-web-agent-runtime-context.zh.md: 09cbbdeabc244c265381b1ad67c3629b4c0763f5

33
.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md Normal file
View File

@@ -0,0 +1,33 @@
# Agent Note: Web agents receive explicit runtime context
Status: implemented
English | [中文](2026-07-28-web-agent-runtime-context.zh.md)
## Problem
The shared CLI base configured an empty deployment persona, the Web overlay did not replace it, and the Web launcher added no source or interaction-surface section. A session header recorded its working directory for tools and persistence, but the model prompt did not state that directory or identify the DeepSeek Harness Web GUI. A request such as “change this page's theme” therefore made the agent search the selected project for an unspecified page, even when the user meant the GUI running the session.
## Decision
The Web profile composes the `dsh-base` and `dsh-web-app` bundles. The Web bundle supplies a concise coding-agent persona containing the resolved `{{model}}` and session `{{cwd}}`; its `web-runtime` plugin adds the `app:web-surface` section when `surfaceContext` is true. Before mounting the profile tree, the `dsh web` alias reads that same composed setting and installs the existing `harness:source` section only when the surface context is enabled. The headless bundle and a profile that owns its complete prompt set `surfaceContext: false`, suppressing the Web prompt and managed shell facts; the Web alias also suppresses the source section without checking an overlay path. Every mounted prompt contribution still activates before consumers such as the agent loop can emit a request header. The [source-checkout/workdir decision](2026-07-30-source-checkout-workdir-distinction.md) owns the source section's wording and its warning not to infer one path from the other.
The Web section treats unqualified references to “this page,” “this GUI,” or “this app” as references to the DeepSeek Harness Web GUI. It also states that the browser provides no implicit DOM, route, or screenshot context, so the model can identify the product without claiming visual state it did not receive. The assembled text is logged in `request/header`, preserving the model-visible/logged invariant.
## Verification
The Web runtime unit tests pin both enabled and disabled `surfaceContext` behavior, while the Web alias unit test pins default-on and explicit-off source-section gating from the composed row. The keyless fresh-round-trip Web scenario boots the shipped base plus Web bundle, runs a real session through the HTTP/SSE application, and snapshots the system-prompt prefix with source and working-directory paths normalized. The snapshot pins the harness identity, source checkout, Web orientation, and resolved coding-agent persona in request order. The Core Web snapshot applies the RL overlay and pins its complete system prompt with no source or Web section.
## Alternatives considered
**Send URL, DOM, or screenshots with every prompt.** The observed failure needed stable product orientation, while the current root URL does not identify a selected component and no visual capture exists in the message contract. Adding dynamic page state would require a separate logged model-input design and is not implied by this fix.
**Require the session Workspace to be the harness checkout.** Workspace cwd is the user's task target and may legitimately be an empty project or another repository. Conflating it with the application's source location would break that boundary and leave installed or externally launched sessions ambiguous.
**Put Web wording in the global harness identity.** `dsh-system-prompt` serves TUI, ACP, SDK, and custom deployments that do not run in a browser. The composing Web app owns this surface fact.
**Change the existing source-location section for every CLI surface.** The source section is shared with TUI and states only the checkout fact. Keeping Web orientation separate preserves that reusable contract and avoids telling headless or terminal agents that they are in a browser.
## Consequences
Ordinary Web requests gain a short stable prompt prefix and may invalidate provider prefix caches once when this change is deployed. Agents can distinguish the GUI source checkout from the selected Workspace and resolve ordinary references to the current app without a clarification round trip. References to a specific visual state remain bounded by the explicit no-DOM/no-route/no-screenshot statement and may still require a path, description, or attachment. Complete-prompt profiles can opt out through the Web runtime's composition setting without a launcher path check.

33
.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md Normal file
View File

@@ -0,0 +1,33 @@
# Agent Note: Web agent 获得显式运行时上下文
Status: implemented
[English](2026-07-28-web-agent-runtime-context.md) | 中文
## 问题
CLI 共享 base 配置了空的部署 persona，Web overlay 没有替换它，而 Web 启动器既未添加源码提示词段，也未添加交互界面提示词段。会话 header 会记录工作目录，供工具与持久化使用，但模型提示词既不说明该目录，也不标识 DeepSeek Harness Web GUI。因此，当用户提出「修改这个页面的主题」之类的请求时，即使用户指的是承载当前会话的 GUI，agent 也只能在所选项目中搜索一个未明确说明的页面。
## 决策
Web profile 会组合 `dsh-base` 与 `dsh-web-app` 两个组合包。Web 组合包提供一段简洁的编码 agent persona，其中包含解析后的 `{{model}}` 与会话 `{{cwd}}`；当 `surfaceContext` 为 true 时，其 `web-runtime` 插件会添加 `app:web-surface` 提示词段。挂载 profile 配置树前，`dsh web` 别名会读取组合后的同一项设置，并且仅在启用表层上下文时安装现有的 `harness:source` 提示词段。无头组合包和拥有完整提示词的 profile 都会设置 `surfaceContext: false`，从而抑制 Web 提示词与受管 shell 事实；Web 别名也会抑制源码提示词段，而无需检查 overlay 路径。每项已挂载的提示词贡献仍会在 agent loop（智能体循环）等消费方发出 request header 前激活。源码提示词段的措辞，以及其中不得从一条路径推断另一条路径的警告，均由另行记录的[源码 checkout 与工作目录区分决策](2026-07-30-source-checkout-workdir-distinction.md)负责。
Web 提示词段把未限定的「这个页面」「这个 GUI」或「这个应用」解释为 DeepSeek Harness Web GUI。同时，它会明确说明浏览器不会隐式提供 DOM、路由或截图上下文，使模型能够识别产品，但不会声称掌握未收到的视觉状态。组装后的文本会记录在 `request/header` 中，从而保持「模型可见内容必须有日志记录」这一不变量。
## 验证
Web 运行时单元测试会固定启用和禁用 `surfaceContext` 时的行为，Web 别名单元测试则会固定组合后配置行对源码提示词段的默认启用与显式禁用门控。无密钥的 Web fresh-round-trip 场景会启动已交付的 base 与 Web 组合包，通过 HTTP／SSE 应用运行一个真实会话，并在规范化源码路径与工作目录后对系统提示词前缀生成快照。该快照按请求顺序固定 harness 身份、源码 checkout、Web 界面定位，以及解析后的编码 agent persona。Core Web 快照会应用 RL overlay，并固定不含源码提示词段或 Web 提示词段的完整系统提示词。
## 考虑过的替代方案
**每次提示词都发送 URL、DOM 或截图。** 本次故障只需要稳定的产品定位；当前根 URL 无法标识所选组件，消息契约中也不存在视觉捕获内容。添加动态页面状态需要另行设计可记录的模型输入，不属于本次修复的隐含范围。
**要求会话 Workspace 必须是 harness checkout。** Workspace cwd 是用户任务的目标，可以合理地指向空项目或其他仓库。将其与应用源码位置混为一谈会破坏这一边界，并且仍无法消除已安装版本或外部启动会话中的歧义。
**把 Web 文案放入全局 harness 身份。** `dsh-system-prompt` 还服务于 TUI、ACP、SDK 和不在浏览器中运行的自定义部署。该界面事实应由组装 Web 应用负责。
**为所有 CLI 界面修改现有源码位置提示词段。** TUI 也复用源码位置提示词段，而该段只陈述 checkout 事实。单独保留 Web 界面定位可以维持这份可复用契约，避免错误地告诉无头或终端 agent 它们正处于浏览器中。
## 影响
常规 Web 请求会增加一段较短且稳定的提示词前缀；部署此变更时，模型提供方的前缀缓存可能失效一次。agent 可以区分 GUI 源码 checkout 与所选 Workspace，并且无需再经过一轮澄清即可解析对当前应用的一般指代。对特定视觉状态的指代仍受「无 DOM／无路由／无截图」这一显式边界约束，必要时仍需用户提供路径、描述或附件。拥有完整提示词的 profile 可以通过 Web 运行时的组合设置选择退出，而无需检查启动器路径。

37
.agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.md
View File

@@ -1,37 +0,0 @@
# Agent Note: Web conversation UI polish sweep
Status: implemented
English | [中文](2026-07-28-web-conversation-polish-sweep.zh.md)
## Problem
A design review of the web GUI's conversation surfaces found a batch of presentation defects: portal menus painted one frame at the wrong position before repositioning (visible open jump), the chat column split one tool run into several groups whenever a step message carried only tool-call heads, tool row summaries printed workspace-absolute paths that consumed most of the row, the running-row sweep was implemented as an alpha mask that dimmed the whole row, the hero workspace chip resurrected a deleted workspace's folder name from the session cwd, and the header showed a turns counter nobody asked for next to a 13px title.
## Decision
The sweep lands as presentation-layer changes only; nothing enters the session log.
- **Portal menus pre-render hidden and measure before paint.** The menu list mounts with `visibility: hidden` at (0,0), measures in `useLayoutEffect`, and becomes visible already at its final position. Menus keep 12px viewport clearance with internal scroll; workspace create actions pin in a non-scrolling footer.
- **The chat flow skips assistant nodes that render nothing.** A finalized assistant node whose blocks are only tool-call heads and blank text/reasoning is dropped from the flow derivation, so consecutive tool results merge into one group. Interrupted nodes always render (they carry the 已停止 marker).
- **Tool row summaries relativize workspace-rooted paths.** The session cwd threads through the toolview slot contract (`ToolRowOwnerProps.cwd`) and `toolRowModel` strips it from summaries that start with it; paths outside the workspace stay verbatim. Display-only — args and the log are untouched.
- **The running sweep is a glare-band overlay.** A fixed-width `::after` gradient band animates across the row (the deepsuite ShimmerText pattern), replacing the previous `mask-image` approach, in both ToolRow and the Bash toolview.
- **The hero workspace chip is a selector, not an echo.** With no live selection (cold start, or the workspace was deleted after the list settled) it shows a "Choose workspace" placeholder; the cwd-derived name only bridges the initial list load, and stale pending picks clear when their workspace leaves a ready list.
- **One 16px vertical rhythm.** The chat column gap and in-group tool-row gap are both 16px, replacing the 10px in-group gap plus a negative cross-group margin.
- **Header title reads 14/20 with no turns counter**; StateDot ongoing and the turn tail use a stepped pixel-chase loading language; `body` gets grayscale antialiasing (`-webkit-font-smoothing` and the Firefox macOS equivalent).
## Alternatives considered
- **Position menus synchronously from anchor rects before mount.** Rejected: the list's own size is unknown until it lays out, so clamping to the viewport still needs a post-layout measure; measuring a hidden mounted node is the pattern React and Floating UI document.
- **Filter empty assistant messages host-side.** Rejected: the node is real model output that Trajectory and replay must keep; only the chat presentation should skip it, and the web layer is pure presentation by contract.
- **Relativize paths in each tool's presenter.** Rejected: the redundancy is shared by every path-summarizing tool; one display-only pass in `toolRowModel` covers them all and non-chat consumers keep absolute paths.
- **Keep the mask-based sweep.** Rejected: the mask dims the entire row content including state dots, and its exit transition fought the hover icon crossfade; an overlay band composites above the content without touching its alpha.
- **Keep showing the deleted workspace's name in the chip.** Rejected: the chip is the selector for the *next* session; echoing a cwd whose workspace the user just deleted misrepresents the current pick.
## Consequences
Chat renders fewer flow items than the snapshot has nodes: anyone counting rendered blocks against nodes must account for skipped render-nothing assistants (the chat-view spec pins this). The path relativization is a prefix check against the session cwd, so a workspace rename mid-session shows absolute paths until the summary re-derives — accepted as display-only staleness. The uniform 16px rhythm retires the tighter 10px tool-run look; a future denser layout would reintroduce a second constant deliberately. The menu pre-render adds one hidden layout pass per open, negligible at menu sizes.
## Testing
`chat-view.spec.tsx` pins the render-nothing grouping (including the interrupted exception); `chat-tool-row.spec.tsx` pins cwd relativization inside/outside the workspace and with an empty cwd; `atoms.spec.tsx` and `workspace-picker.spec.tsx` cover the menu and chip states; the full ui-conversation, ui-primitives, and ui-workspace suites pass.

37
.agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.zh.md
View File

@@ -1,37 +0,0 @@
# Agent Note: Web conversation UI polish sweep
Status: implemented
[English](2026-07-28-web-conversation-polish-sweep.md) | 中文
## Problem
一次针对 web GUI 对话界面的设计评审发现了一批视觉呈现缺陷：portal 菜单在重新定位前会先在错误位置绘制一帧（打开时可见跳动）；只要某条步骤消息只携带工具调用头，聊天列就会把一次工具运行拆成好几组；工具行摘要打印以工作区为根的绝对路径，占掉行内大部分空间；运行中行的扫光效果用 alpha 遮罩实现，把整行都压暗；hero 区的工作区 chip 会从会话 cwd 里复现已删除工作区的文件夹名；标题栏还在 13px 的标题旁显示一个没人需要的轮次计数。
## Decision
本次修复全部为纯展示侧改动落地；不会有任何内容进入会话日志。
- **Portal 菜单先隐藏预渲染，绘制前完成测量。**菜单列表以 `visibility: hidden` 挂载在 (0,0)，在 `useLayoutEffect` 中测量，显示时已处于最终位置。菜单与视口保持 12px 间距并支持内部滚动；工作区创建操作固定在不滚动的页脚区。
- **聊天流跳过不渲染任何内容的助手节点。**已定稿的助手节点若其块仅含工具调用头和空白的文本／推理（reasoning）内容，就会从流推导中剔除，于是连续的工具结果合并为一组。被中断的节点始终渲染（它们携带「已停止」标记）。
- **工具行摘要把以工作区为根的路径转为相对路径。**会话 cwd 经由 toolview 插槽契约（`ToolRowOwnerProps.cwd`）逐层传递，`toolRowModel` 从以其开头的摘要中剥去该前缀；工作区之外的路径保持原样。这只影响显示：工具参数与日志均不受影响。
- **运行中的扫光效果改为高光带叠加层。**一条固定宽度的 `::after` 渐变光带横向扫过整行（即 deepsuite 的 ShimmerText 模式），取代先前的 `mask-image` 方案，ToolRow 与 Bash toolview 两处均已替换。
- **hero 区的工作区 chip 是选择器，而非回显。**没有有效选中项时（冷启动，或列表稳定后工作区被删除），它显示「Choose workspace」占位文案；由 cwd 推导的名称只用于衔接列表的首次加载，待定选择对应的工作区从已就绪的列表中消失时，该陈旧选择会被清除。
- **统一为 16px 的纵向节奏。**聊天列间距与分组内工具行间距统一为 16px，取代原先「分组内 10px 间距加跨分组负外边距」的做法。
- **标题栏标题改为 14/20，去掉轮次计数**；StateDot 的进行中状态与轮次尾部采用逐格推进的像素追逐式加载视觉语言；`body` 启用灰度抗锯齿（`-webkit-font-smoothing` 及 Firefox 在 macOS 上的等价设置）。
## Alternatives considered
- **挂载前根据锚点矩形同步定位菜单。**不予采纳：列表自身尺寸在布局完成前无从得知，向视口内收拢仍然需要布局后测量；对已挂载的隐藏节点做测量正是 React 与 Floating UI 文档记载的模式。
- **在宿主侧过滤空的助手消息。**不予采纳：该节点是真实的模型输出，Trajectory 与回放都必须保留它；只有聊天展示应当跳过它，且按契约 web 层只负责呈现。
- **在每个工具各自的展示器中做路径相对化。**不予采纳：这种冗余是所有输出路径摘要的工具共有的；在 `toolRowModel` 里做一次仅影响显示的处理即可覆盖全部工具，非聊天消费方仍拿到绝对路径。
- **保留基于遮罩的扫光。**不予采纳：遮罩会把包括状态圆点在内的整行内容压暗，其退出过渡还与悬停图标的交叉淡入淡出相互冲突；叠加光带在内容之上合成，完全不触碰内容的 alpha。
- **让 chip 继续显示已删除工作区的名称。**不予采纳：chip 是为*下一个*会话服务的选择器；用户刚删掉某个工作区，还回显它的 cwd，就是在错误呈现当前的选择。
## Consequences
聊天渲染出的流条目数少于快照中的节点数：凡是拿渲染出的块与节点数对账的人，都必须把被跳过的「不渲染任何内容」的助手节点计算在内（chat-view 规格测试固定了这一点）。路径相对化只是针对会话 cwd 的前缀检查，因此会话中途重命名工作区后，摘要在重新推导前会显示绝对路径，这被接受为仅影响显示的陈旧状态。统一的 16px 节奏淘汰了原先更紧凑的 10px 工具运行外观；将来若要更紧凑的布局，应当有意识地重新引入第二个常量。菜单预渲染让每次打开多一次隐藏布局计算，在菜单的尺寸量级下开销可忽略。
## Testing
`chat-view.spec.tsx` 固定了「不渲染任何内容」节点的分组行为（含被中断节点这一例外）；`chat-tool-row.spec.tsx` 固定了工作区内、工作区外以及 cwd 为空时的 cwd 相对化行为；`atoms.spec.tsx` 与 `workspace-picker.spec.tsx` 覆盖菜单与 chip 的各种状态；ui-conversation、ui-primitives 与 ui-workspace 的全量测试套件通过。

6
.agents/notes/implemented/bug-fix/2026-07-30-tui-adapter-registration-race.i18n.yaml → .agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
View File

@@ -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 .agents/notes/implemented/bug-fix/2026-07-30-tui-adapter-registration-race.md
2026-07-30-tui-adapter-registration-race.md: fd08e7b6130bc8f7e3cd5287a9970f5fb47244a8
2026-07-30-tui-adapter-registration-race.zh.md: 0c6bba4bbc8c3303d9c471c3164faa816438b333
# 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: aa488e1df087722c072d98c67d47cdf63a42f6b8
2026-07-28-web-gui-feedback-loop.zh.md: d9de988e5a2cc57794ff628b65eb050dee610747

39
.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md Normal file
View File

@@ -0,0 +1,39 @@
# Agent Note: Web GUI changes close the loop on the existing URL
Status: implemented
English | [中文](2026-07-28-web-gui-feedback-loop.zh.md)
## Problem
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 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
The ordinary `dsh web` composition mounts the Web bundle's `web-runtime` plugin, which 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. A complete-prompt profile sets the row's `surfaceContext` to false and receives neither the prompt section nor the managed variables; the Web launcher uses the same setting to suppress its source-checkout prompt section.
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.
No server restart or replacement is required merely because static artifacts changed. The host reads `index.html` and static assets on each request, while client bundles are also served from their current files with `no-cache`; a refresh of the existing URL is therefore the acceptance path after the relevant shell and plugin bundles are rebuilt. Starting a separate server proves only that a separate server works. If the user explicitly requests another long-running server, the existing managed background-task contract owns its lifecycle and completion notices; shell `&` is not an alternative lifecycle.
## Verification
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
**Extend only the system prompt.** Rejected because it would leave the target unavailable to tools, preserve the misleading bare-Vite path, and fail to prove how an existing process observes rebuilt artifacts.
**Remove the `apps/web` development script without guarding Vite.** Rejected because `npx vite`, the exact incident command, bypasses package scripts. Serve mode itself must fail.
**Automatically restart or replace the current Web process after every edit.** Rejected because the static server already reads current artifacts per request, a restart would interrupt the session that requested the edit, and plugin HMR has a separate explicit `dsh web --dev` composition.
**Send DOM, route, or screenshots with each request.** Deferred to a separate logged-input design. Stable URL identity closes this feedback loop without claiming browser state the host does not receive.
## Consequences
Ordinary Web prompts gain a dynamic URL-and-mode paragraph, so provider prefix reuse now varies by bound port and mode. Their 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. Profiles that disable `surfaceContext` also give up this feedback-loop guidance and shell context.

39
.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md Normal file
View File

@@ -0,0 +1,39 @@
# Agent Note: Web GUI 改动在现有 URL 上闭环
Status: implemented
[English](2026-07-28-web-gui-feedback-loop.md) | 中文
## 问题
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。
[事故复盘](../../../../docs/postmortem/0003-web-agent-gui-feedback-loop.md)集中记录事件日志时间线，并解释原有检查为何会接受错误的页面、进程和端口。
## 决策
常规 `dsh web` 组合会挂载 Web 组合包的 `web-runtime` 插件，由它发布一个规范的回环 URL 及其实际运行时模式，同时将二者作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 提示词段说明：未加限定的指代指向此 GUI，并给出 URL；`DSH_WEB_URL` 和 `DSH_WEB_MODE=production|development` 会把同样的事实传入每次前台或受管后台 bash 调用。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。拥有完整提示词的 profile 会把该配置行的 `surfaceContext` 设为 false，并且不会收到该提示词段和这些受管变量中的任何一个；Web 启动器也会使用同一项设置来抑制其源码 checkout 提示词段。
按模式区分的提示词让 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` 和 `$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 的成功声明。
## 考虑过的替代方案
**仅扩展系统提示词。** 不予采纳，因为这样会让工具仍然无法获得目标，保留具有误导性的裸 Vite 路径，并且无法证明现有进程如何观察重新构建的产物。
**删除 `apps/web` 开发脚本，但不为 Vite 添加防护。** 不予采纳，因为事故中实际使用的命令 `npx vite` 会绕过包脚本。服务模式本身必须失败。
**每次编辑后自动重启或替换当前 Web 进程。** 不予采纳，因为静态服务器本就会在每次请求时读取当前产物，重启还会中断发起编辑请求的会话，而插件 HMR 已有独立且显式的 `dsh web --dev` 组合。
**每次请求都发送 DOM、路由或截图。** 推迟到另行设计的已记录输入机制。稳定的 URL 身份足以闭合本次反馈循环，同时不会声称宿主掌握其未接收的浏览器状态。
## 影响
常规 Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。相应的 Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式契约会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。

4
.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
View File

@@ -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-29-human-transcript-append-origin.md
2026-07-29-human-transcript-append-origin.md: a47dd49dd831cdd32d520137417bf47d2c056a09
2026-07-29-human-transcript-append-origin.zh.md: 31639bd9aac5d6dace80392004f37c747bff2c36
2026-07-29-human-transcript-append-origin.md: 9804d3d8d67a4ad00c3d395c2081fd47e03c254a
2026-07-29-human-transcript-append-origin.zh.md: 909f0756dd29c9deddb840a188eb19a773f92d29

4
.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
View File

@@ -6,7 +6,7 @@ English | [中文](2026-07-29-human-transcript-append-origin.zh.md)
## Problem
The terminal and the host history gateway both treated the model-visible surface as the human transcript. A successful compaction replaces a surface range with one checkpoint node, so the moment that replacement landed the terminal dropped every message it shadowed — conversation the user had already read — and re-ran that destructive rebuild on any later replacement. The same confusion reached pagination: `maxMessages` counted every `user/message`, `assistant/message`, and `steering/message` in the window, so a model-only replacement copy consumed a page slot the human never filled, and the cut could land between a compaction's log-only provenance and the replacement that cites it.
The terminal and the host history gateway both treated the model-visible surface as the human transcript. A successful compaction replaces a surface range with one checkpoint node, so the moment that replacement landed the terminal dropped every message it shadowed — conversation the user had already read — and re-ran that destructive rebuild on any later replacement. The same confusion reached pagination: `maxMessages` counted every `user/message` and `assistant/message` in the window, so a model-only replacement copy consumed a page slot the human never filled, and the cut could land between a compaction's log-only provenance and the replacement that cites it.
Nothing was lost from the log. `Session.events` still held every original message and full tool result; the surface only decides what the model is sent next. The defect was entirely in the projection.
@@ -26,7 +26,7 @@ No persisted event, RPC envelope, compaction transaction, or model-visible surfa
The browser client is fixed separately, in [the web transcript projection note](2026-07-30-web-transcript-log-ordered-projection.md): it projects the same append-origin transcript in log order and renders a marker component, and it closes the pagination hole this change opened — because `session.history` no longer spends quota on the checkpoint, it never cuts on the checkpoint's provenance group, so a page can carry a checkpoint citing a `surfaceOp.start` outside the window, which the browser's surface fold rejected. That hole predates this change (counting could already run past a checkpoint into the range it shadows), but the old rule accidentally covered the case where the checkpoint was the oldest counted message and pulled the whole shadowed range onto its page.
The terminal's [live compaction progress decision](../feature/2026-07-30-compaction-progress-visibility.md) uses standalone bracket events to drive the existing one-cell indicator. It does not change the completion marker owned here or add scale: the checkpoint's `sourceEventSeqs` remain available for a separately justified count or range. Progress therefore needs neither marker-content changes nor a prerequisite `renderReplacement(event)` extraction.
The terminal's [archived live compaction progress decision](../../archived/feature/2026-07-30-compaction-progress-visibility.md) uses standalone bracket events to drive the existing one-cell indicator. It does not change the completion marker owned here or add scale: the checkpoint's `sourceEventSeqs` remain available for a separately justified count or range. Progress therefore needs neither marker-content changes nor a prerequisite `renderReplacement(event)` extraction.
## Alternatives considered

4
.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
View File

@@ -6,7 +6,7 @@ Status: implemented
## Problem
终端与宿主历史网关都把模型可见的 surface 当作人类可读记录（transcript）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message`、`assistant/message` 和 `steering/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志溯源信息与引用它的替换之间。
终端与宿主历史网关都把模型可见的 surface 当作人类可读记录（transcript）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message` 和 `assistant/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志溯源信息与引用它的替换之间。
日志本身没有丢失任何内容。`Session.events` 仍保存着每条原始消息和完整的工具结果；surface 只决定接下来发送给模型的内容。缺陷完全在投影层。
@@ -26,7 +26,7 @@ Status: implemented
浏览器客户端在[Web 记录投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份 append 来源记录并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝该范围。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，其溯源分组把整段被遮蔽的范围一起拉到该页。
终端的[实时压缩进度决策](../feature/2026-07-30-compaction-progress-visibility.md)使用独立标记对中的事件驱动现有的单格指示器。它既不改变本文所负责的完成标记，也不添加规模信息：检查点的 `sourceEventSeqs` 仍可供经另行论证的计数或区间使用。因此，进度显示既不需要修改标记内容，也不以提取 `renderReplacement(event)` 为前置条件。
终端的[已归档实时压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用独立标记对中的事件驱动现有的单格指示器。它既不改变本文所负责的完成标记，也不添加规模信息：检查点的 `sourceEventSeqs` 仍可供经另行论证的计数或区间使用。因此，进度显示既不需要修改标记内容，也不以提取 `renderReplacement(event)` 为前置条件。
## Alternatives considered

4
.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
View File

@@ -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-29-sticky-composer-conversation-scroll.md
2026-07-29-sticky-composer-conversation-scroll.md: 7ceae95dafffdb756ef49bb5612cd4e711eb59ca
2026-07-29-sticky-composer-conversation-scroll.zh.md: d925d82f94635b5fe67b0be119c041d003def393
2026-07-29-sticky-composer-conversation-scroll.md: 8657080078e475d6e90f17a6c0f8cb5b2fb1555d
2026-07-29-sticky-composer-conversation-scroll.zh.md: a588903adf51c6fcdd01f851d4f5e6570f695242

10
.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
View File

@@ -10,20 +10,24 @@ The active conversation column split scrolling: the chat (and trajectory) view o
## Decision
While a session exists, `ConversationRoot` always supplies a `wrapActiveBody` owner callback that wraps the view ring in a `data-conversation-scroll` body and places a `data-composer-seat` around the whole `'conversation.composer'` chain output (fallback + elected overlay siblings from `overlay: true`). Active CSS sticks that seat with `position: sticky; bottom: 0` so Question/Approval takeovers stay visible when the user is not pinned to the floor; hero CSS centers the fallback stack inside the scroll body. `ConversationSession` keeps a chrome-hidden header + body shell while blank so that tree seat does not change on the first send. The session header remains `flex: none` column chrome above the scrollport when visible. ChatView and Trajectory/Waterfall keep a local scroller only when mounted outside that host (unit tests); under the host they set `overflow: visible` and resolve bottom-follow / prepend anchoring through `closest('[data-conversation-scroll]')`.
`ConversationRoot` always owns one `data-conversation-scroll` body, with the strict `conversation.session` view outlet before a `data-composer-seat` around the whole `'conversation.composer'` chain output (fallback + elected overlay siblings from `overlay: true`). The separate strict `conversation.session.header` outlet remains `flex: none` column chrome above that scrollport and hides while the Session is blank. This fixed parent tree keeps the scroll body and composer seat mounted from no session through the blank Hero and active conversation. Active CSS sticks that seat with `position: sticky; bottom: 0` so Question/Approval takeovers stay visible when the user is not pinned to the floor; Hero CSS centers the fallback stack inside the scroll body. ChatView and Trajectory/Waterfall keep a local scroller only when mounted outside that host (unit tests); under the host they set `overflow: visible` and resolve bottom-follow / prepend anchoring through `closest('[data-conversation-scroll]')`.
Session stats live on `'conversation.composer.dock'` (above `'conversation.input.dock'`). The InputBar textarea, when inside the host, chains `wheel` with `{ passive: false }`: while the capped textarea can still scroll in that direction it keeps the native gesture; only at its own edge does it `preventDefault` and apply `deltaY` to the host.
Chat history prepend follows reader intent through stable rendered node/call identities rather than whole-scrollport height deltas. `ChatView` records the first visible `data-chat-anchor-key` and its top relative to the scrollport when paging starts, reselects the currently visible stable anchor after every reader scroll while the request is in flight, and compensates by that row's post-prepend rectangle delta. Reaching the bottom or appending the reader's own message cancels the paging anchor, so a late page cannot pull the view away from the newest content. Bottom follow is stored state rather than raw scroll geometry; how reader input is recognized — device-agnostic deviation from the observed-top ledger of the last delivered or written `scrollTop` — is owned by the [reader-scroll-attribution note](2026-08-06-reader-scroll-attribution-observed-top-ledger.md). ChatView's single `ResizeObserver` follows streaming, tool disclosure, and draft resize only while bottom ownership remains pinned, without a second per-chunk scroll write.
## Alternatives considered
**Sticky header and sticky composer inside one column scrollport.** Rejected for the header: it must occupy the top as fixed layout chrome, not participate in the scrollport's sticky layer.
**Fixed flex-none composer below the scrollport with wheel forwarding.** Rejected: the product requires the composer to stick inside the transcript scrollport so the footer is part of that scroll hit-testing surface, not a sibling that only forwards deltas.
**Portal the composer into ChatView's scroller.** Rejected: the composer is shared across view tabs; the wrap target is the Session body owned by the resident shell.
**Portal the composer into ChatView's scroller.** Rejected: the composer is shared across view tabs; its target is the root-owned scrollport in the resident shell.
**Keep StatsLine inside ChatView below the message column.** Rejected: outside the sticky composer it would scroll away while the input stayed pinned.
**Model every browser scroll input source.** Rejected for this narrow fix: the reproduced desktop path uses wheel/trackpad input. Pointer/touch scrolling, native-scrollbar dragging, keyboard scrolling, focus navigation, and nested overflow ownership were left outside the provenance model instead of adding a general input state machine. The [reader-scroll-attribution note](2026-08-06-reader-scroll-attribution-observed-top-ledger.md) later closed this deferral by generalizing attribution through the observed-top ledger, still without an input state machine.
## Consequences
Wheel over the footer scrolls the transcript; the visible layout is a fixed header, scrolling transcript, and sticky bottom composer. Stats appear on every active view tab. Nested view scrollers under the host are suppressed so sticky Turn headers in Trajectory stick to the column host. Hero → active keeps the same textarea DOM node (assembled slash-flow snapshot) and the InputHub draft.
Wheel over the footer scrolls the transcript; the visible layout is a fixed header, scrolling transcript, and sticky bottom composer. Stats appear on every active view tab. Nested view scrollers under the host are suppressed so sticky Turn headers in Trajectory stick to the column host. Concurrent history, streaming, tool expansion, and composer reflow preserve reader scroll decisions, including Chromium's compositor-first delivery and stream-finalization shrink clamp. Follow ownership extends to every reader input under the [reader-scroll-attribution note](2026-08-06-reader-scroll-attribution-observed-top-ledger.md). No session → blank Hero and Hero → active both keep the same textarea DOM node and InputHub draft.

10
.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md
View File

@@ -10,20 +10,24 @@ Status: implemented
## Decision
只要存在会话，`ConversationRoot` 就会始终提供 `wrapActiveBody` owner 回调，将视图环包进 `data-conversation-scroll` 主体，并用 `data-composer-seat` 包住整条 `'conversation.composer'` chain 输出（`overlay: true` 下的 fallback 与选举出的 overlay 兄弟节点）。活跃阶段 CSS 以 `position: sticky; bottom: 0` 钉住该 seat，使用户未贴底时 Question／Approval 接管仍可见；hero CSS 在滚动主体内居中 fallback 栈。`ConversationSession` 在 blank 时保留隐藏 chrome 的 header + body 壳，使首次发送时树座位不变。可见时会话标题栏仍是滚动容器之上的 `flex: none` 列 chrome。ChatView 与 Trajectory/Waterfall 仅在宿主之外挂载时（单元测试）保留本地 scroller；位于宿主下时设为 `overflow: visible`，并通过 `closest('[data-conversation-scroll]')` 解析贴底跟随与前置锚定。
`ConversationRoot` 始终拥有同一个 `data-conversation-scroll` 主体，其中严格 `conversation.session` view outlet 位于 `data-composer-seat` 之前；该 seat 包住整条 `'conversation.composer'` chain 输出（`overlay: true` 下的 fallback 与选举出的 overlay 兄弟节点）。独立的严格 `conversation.session.header` outlet 作为 `flex: none` 列 chrome 位于滚动容器上方，并在 Session 仍为 blank 时隐藏。固定的父级树让滚动主体与 composer seat 从无 session、blank Hero 到活跃对话始终保持挂载。活跃阶段 CSS 以 `position: sticky; bottom: 0` 钉住该 seat，使用户未贴底时 Question／Approval 接管仍可见；Hero CSS 在滚动主体内居中 fallback 栈。ChatView 与 Trajectory/Waterfall 仅在宿主之外挂载时（单元测试）保留本地 scroller；位于宿主下时设为 `overflow: visible`，并通过 `closest('[data-conversation-scroll]')` 解析贴底跟随与前置锚定。
会话统计挂在 `'conversation.composer.dock'`（位于 `'conversation.input.dock'` 之上）。InputBar 的 textarea 在宿主内以 `{ passive: false }` 链式处理 `wheel`：在限高 textarea 仍能沿该方向滚动时保留原生手势；仅在自身边缘才 `preventDefault` 并将 `deltaY` 施加到宿主。
Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图，而不是使用整个滚动容器的高度差。分页开始时，`ChatView` 记录第一个可见的 `data-chat-anchor-key` 及其相对滚动容器的顶部位置；请求在途期间，每次读者滚动都会重新选择当前可见的稳定锚点；页面到达后则按该行矩形的前后差值补偿。到达底部或追加读者自己的消息会取消分页锚点，因此迟到的页面不能把视图从最新内容拉走。贴底跟随采用存储状态，而不是原始滚动几何状态；读者输入如何被识别——即以与设备无关的方式偏离由最近一次交付或写入的 `scrollTop` 构成的 observed-top ledger——由[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)负责。`ChatView` 的单个 `ResizeObserver` 只会在贴底所有权仍保持时跟随流式输出、工具展开与草稿尺寸变化，且每个 chunk 不会触发第二次滚动写入。
## Alternatives considered
**标题栏与编辑器都在同一列滚动容器内 sticky。** 标题栏否决：它必须作为固定布局 chrome 占据顶部，而不是参与滚动容器的 sticky 层。
**滚动容器下方 flex-none 固定编辑器并转发滚轮。** 否决：产品要求编辑器 sticky 在 transcript 滚动容器内，使页脚成为该滚动命中面的一部分，而不是仅转发增量的兄弟节点。
**把编辑器 portal 进 ChatView 的 scroller。** 否决：编辑器跨视图标签共享；包装目标是常驻壳拥有的 Session 主体。
**把编辑器 portal 进 ChatView 的 scroller。** 否决：编辑器跨视图标签共享；其目标是常驻壳中由 root 持有的滚动容器。
**把 StatsLine 留在 ChatView 消息列下方。** 否决：落在 sticky 编辑器之外会随内容滚走，而输入区仍钉在底部。
**为每一种浏览器滚动输入来源建模。** 此次窄范围修复不采用：已复现的桌面端路径使用滚轮／触控板输入。指针／触控滚动、拖动原生滚动条、键盘滚动、焦点导航与嵌套 overflow 所有权当时被留在输入来源模型之外，也未为此新增通用输入状态机。[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)后来通过 observed-top ledger 泛化了归因，补上了这一延后事项，且仍未引入输入状态机。
## Consequences
在页脚上滚轮会滚动 transcript；可见布局是固定标题栏、可滚动 transcript 与 sticky 底部编辑器。统计出现在每一个活跃视图标签上。宿主下的嵌套视图 scroller 被抑制，因而 Trajectory 的 sticky Turn 标题贴在列宿主上。hero → active 保持同一 textarea DOM 节点（assembled slash-flow 快照）以及 InputHub 草稿。
在页脚上滚轮会滚动 transcript；可见布局是固定标题栏、可滚动 transcript 与 sticky 底部编辑器。统计出现在每一个活跃视图标签上。宿主下的嵌套视图 scroller 被抑制，因而 Trajectory 的 sticky Turn 标题贴在列宿主上。并发历史加载、流式输出、工具展开与编辑器重排会保留读者的滚动决定，包括 Chromium 先推进合成器几何状态再交付事件，以及流收尾阶段的收缩钳制。贴底跟随所有权依据[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)扩展到每一种读者输入。无 session → blank Hero 与 Hero → active 都保持同一 textarea DOM 节点以及 InputHub 草稿。

4
.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
View File

@@ -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-29-web-details-session-lifecycle.md
2026-07-29-web-details-session-lifecycle.md: cc1501440d50cb560291e416a0f2b0292e08e1c8
2026-07-29-web-details-session-lifecycle.zh.md: 1102530f288359ebc5fb04a36c2b813da41e1318
2026-07-29-web-details-session-lifecycle.md: 41b89fc059a02e56f53b27e5a5b48fb9488b93d7
2026-07-29-web-details-session-lifecycle.zh.md: 82fb5e0c2608cccbb786a21971a74958417b4f10

2
.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.md
View File

@@ -10,7 +10,7 @@ The details entry is Session-scoped, but its preferred grid width is root-scoped
## Decision
`AppFrame` reads the current Session id and its `blank` summary flag from the authoritative Session projection. It records the last non-blank selected id only when that Session can own details, so hero and other unselected states neither trigger closure nor replace the last Session owner; their rendered details track derives as zero without changing the stored preference. The first Session preserves the layout store's initial preference, whose [visibility default is now closed](2026-07-30-web-details-default-closed.md); returning to the same Session restores its current width, and selecting a different Session closes the root-scoped details preference through the layout store before paint. The per-Session chat selection remains owned by the session-scoped store described by the [slot system standard](../architecture/2026-07-22-slot-type-chain-implementation.md).
`AppFrame` reads the current Session id and its `blank` summary flag from the authoritative Session projection. It records the last non-blank selected id only when that Session can own details, so hero and other unselected states neither trigger closure nor replace the last Session owner; their rendered details track derives as zero without changing the stored preference. The first Session preserves the layout store's initial preference, whose [archived visibility-default decision](../../archived/bug-fix/2026-07-30-web-details-default-closed.md) chose closed; returning to the same Session restores its current width, and selecting a different Session closes the root-scoped details preference through the layout store before paint. The per-Session chat selection remains owned by the session-scoped store described by the [slot system standard](../architecture/2026-07-22-slot-type-chain-implementation.md).
The layout store is transient and starts details closed. It neither reads nor writes `localStorage`, so reload restores the sidebar default and details closed and needs no Session-baseline exception. Manual close and reopen inside one unchanged Session retain their existing behavior. The lifecycle effect changes neither the [Workspace-owned New Session flow](../feature/2026-07-25-workspace-ui-product-flow.md), composer drafts, Session navigation, nor concession-chain resizing.

2
.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
View File

@@ -10,7 +10,7 @@ Status: implemented
## 决策
`AppFrame` 从权威会话投影读取当前会话 id 及其摘要中的 `blank` 标志。它只在该会话能够拥有详情时记录最后一个选中的非 blank 会话 id，因此 hero 和其他未选中状态既不会触发关闭，也不会替换最后一个会话 owner；这些状态下，详情栏轨道的渲染宽度派生为零，但存储的首选宽度不变。首个会话保留布局 store 的初始首选值，该值的[可见性默认设置现为关闭](2026-07-30-web-details-default-closed.md)；返回同一会话时恢复其当前宽度；选择不同会话时，系统会先通过布局 store 关闭根作用域存储的详情栏首选宽度，再进行绘制。逐会话的聊天选中项继续由 [slot 体系标准](../architecture/2026-07-22-slot-type-chain-implementation.md)所述的会话作用域 store 拥有。
`AppFrame` 从权威会话投影读取当前会话 id 及其摘要中的 `blank` 标志。它只在该会话能够拥有详情时记录最后一个选中的非 blank 会话 id，因此 hero 和其他未选中状态既不会触发关闭，也不会替换最后一个会话 owner；这些状态下，详情栏轨道的渲染宽度派生为零，但存储的首选宽度不变。首个会话保留布局 store 的初始首选值，其[已归档的可见性默认值决策](../../archived/bug-fix/2026-07-30-web-details-default-closed.md)选择关闭；返回同一会话时恢复其当前宽度；选择不同会话时，系统会先通过布局 store 关闭根作用域存储的详情栏首选宽度，再进行绘制。逐会话的聊天选中项继续由 [slot 体系标准](../architecture/2026-07-22-slot-type-chain-implementation.md)所述的会话作用域 store 拥有。
布局 store 是瞬时状态，详情栏在启动时保持关闭。它既不读取也不写入 `localStorage`，因此重新加载会恢复侧边栏默认值，并使详情栏保持关闭，无需会话基线例外。在同一个未变化的会话内手动关闭和重新打开详情栏，仍保持原有行为。该生命周期 effect 不改变 [Workspace 拥有的 New Session 动线](../feature/2026-07-25-workspace-ui-product-flow.md)、composer 草稿、会话导航或让步链缩放。

4
.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml
View File

@@ -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-30-approval-panel-command-cap.md
2026-07-30-approval-panel-command-cap.md: 941f7eda187f263f2d8af6aa643d493c92a3669b
2026-07-30-approval-panel-command-cap.zh.md: 939a700934f6467947028d988da9a694169e203e
2026-07-30-approval-panel-command-cap.md: 1e4b75c106b71605a004ef35301445da76ec8cf0
2026-07-30-approval-panel-command-cap.zh.md: aa9f708b78c8ace735e1c96c0ff9ab0a7a4d526a

6
.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md
View File

@@ -14,7 +14,7 @@ The InputBar the panel replaces has always been capped (14 lines, then the texta
The panel's justification and command move into one scroll region (`data-approval-scroll`) capped at the same height as the composer's draft area; the amber strip and the action row sit outside it, so both buttons are in the card at every content length.
The cap is one value with two consumers, declared as `--dsh-composer-text-max-height: 336px` on `ConversationRoot`'s `.composerSeat` — the composer chain's only shared ancestor, since the fallback InputBar and an elected takeover render as siblings. `InputBar`'s mirror and the panel's scroll region both read it, so the seat cannot cap its two states differently: what the designer asked for ("unify it with the input box's max height") is now a fact of the stylesheet rather than a number repeated in two files. The region is `box-sizing: border-box` so the cap is its outer height, the same box the composer's draft area occupies.
The cap is one value with two consumers, declared as `--dsh-composer-text-max-height: 336px` on `ConversationRoot`'s `.composerSeat` — the composer chain's only shared ancestor, since the fallback InputBar and an elected takeover render as siblings. `InputBar`'s draft scrollport and the panel's scroll region both read it, so the seat cannot cap its two states differently: what the designer asked for ("unify it with the input box's max height") is now a fact of the stylesheet rather than a number repeated in two files. The region is `box-sizing: border-box` so the cap is its outer height, the same box the composer's draft area occupies.
The region is a tab stop (`tabIndex={0}`, named `role="group"`). Unlike the question composer's scroll body, whose option rows are focusable and pull the container along, this one holds nothing but text: without its own tab stop a keyboard-only user could reach the buttons and never the command's tail, and approve what they could not finish reading.
@@ -34,12 +34,12 @@ The panel's card rebinds `--dsh-scrollbar-thumb{,-hover}` to the l2 pair, as eve
- A long command scrolls inside the card and the refuse/allow buttons stay on screen. Measured on the built client at 900x1000 and 900x700: the region reports `scrollHeight` past `clientHeight`, and both buttons stay inside the card and inside the viewport.
- Electing the takeover no longer changes how tall the composer seat can get, so the transcript above it does not reflow by hundreds of pixels when an approval arrives or resolves.
- The InputBar's 14-line cap now resolves through a custom property inherited from `.composerSeat`. Rendering the bar outside that seat would drop the declaration (an unresolved `var()` with no fallback), so a future composer host has to carry the property — which is why it is declared on the shared seat rather than the app root.
- The InputBar's 14-line cap now resolves through a custom property inherited from `.composerSeat`, on the box that scrolls its draft ([one scrollport for both text layers](2026-07-31-composer-text-layers-share-one-scrollport.md) moved the declaration off the auto-grow mirror). Rendering the bar outside that seat would drop the declaration (an unresolved `var()` with no fallback), so a future composer host has to carry the property — which is why it is declared on the shared seat rather than the app root.
- The scenario's recorded command is a 200-token blob, far longer than a round trip needs. That cost is deliberate: the cap is unfalsifiable without content that passes it, and the model compresses any regular payload (the first recording turned "alpha 400 times" into `printf 'alpha %.0s' {1..400}`, a one-line command that proves nothing).
## Verification
`apps/web/tests/approval-composer.e2e.ts` drives the real composition: a read-only session, a denied write, the model's escalation retry, and the answer clicked through the panel. The geometry assertion runs on the live panel at two viewport heights and is guarded against holding vacuously — the region must actually be scrolling, and the measured cap must equal the composer's own, which the test reads off the live textarea before sending rather than hardcoding the px value.
`apps/web/tests/approval-composer.e2e.ts` drives the real composition: a read-only session, a denied write, the model's escalation retry, and the answer clicked through the panel. The geometry assertion runs on the live panel at two viewport heights and is guarded against holding vacuously — the region must actually be scrolling, and the measured cap must equal the composer's own, which the test reads off the live draft scrollport before sending rather than hardcoding the px value.
Confirmed both directions against the built client. With the cap reverted, the region reports `scrolls: false` and grows to the command's full height (1798px for the recorded blob at 900x1000, against 336px capped); at 900x700 the card is 680px tall against a 700px viewport and the action row's bottom lands at y=749 — below the fold, the designer's report exactly. With the cap restored the scenario passes in replay.

6
.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
View File

@@ -14,7 +14,7 @@ Status: implemented
面板的理由与命令移入同一个滚动区域（`data-approval-scroll`），其高度上限与 composer 的草稿区完全相同；琥珀色状态条与操作按钮行位于该区域之外，因此无论内容多长，两个按钮都留在卡片内。
这个上限是一个值、两个消费者，以 `--dsh-composer-text-max-height: 336px` 声明在 `ConversationRoot` 的 `.composerSeat` 上——它是 composer 链唯一的共同祖先，因为兜底的 InputBar 与被选中的接管面板是兄弟节点。`InputBar` 的 mirror 与面板的滚动区域都读取它，于是同一个容器不可能给它的两种状态设出不同上限：设计同学要求的"可以跟输入框最大高度统一"，如今是样式表中的一个事实，而不是抄在两个文件里的一个数字。该区域取 `box-sizing: border-box`，因此上限指的是它的外框高度，与 composer 草稿区占据的是同一个盒子。
这个上限是一个值、两个消费者，以 `--dsh-composer-text-max-height: 336px` 声明在 `ConversationRoot` 的 `.composerSeat` 上——它是 composer 链唯一的共同祖先，因为兜底的 InputBar 与被选中的接管面板是兄弟节点。`InputBar` 的草稿滚动容器与面板的滚动区域都读取它，于是同一个容器不可能给它的两种状态设出不同上限：设计同学要求的"可以跟输入框最大高度统一"，如今是样式表中的一个事实，而不是抄在两个文件里的一个数字。该区域取 `box-sizing: border-box`，因此上限指的是它的外框高度，与 composer 草稿区占据的是同一个盒子。
该区域自身是一个 Tab 停靠点（`tabIndex={0}`，带名称的 `role="group"`）。提问 composer 的滚动体不需要这样做——它的选项行本身可聚焦，会把容器一起带过去；而这里除文本之外别无内容：没有自己的停靠点，仅用键盘的用户能走到按钮却走不到命令尾部，于是可能批准了自己没读完的东西。
@@ -34,12 +34,12 @@ Status: implemented
- 长命令在卡片内滚动，拒绝／允许按钮留在屏幕内。在构建产物客户端上于 900x1000 与 900x700 实测：该区域报告的 `scrollHeight` 超过 `clientHeight`，两个按钮都留在卡片内、也都留在视口内。
- 选中接管面板不再改变 composer 容器能达到的高度，因此审批到来或解决时，上方的会话流不会有数百像素的重排。
- InputBar 的 14 行上限现在通过一个自 `.composerSeat` 继承而来的自定义属性解析。把输入栏渲染到该容器之外会丢掉这条声明（一个没有兜底值的未解析 `var()`），因此未来的 composer 宿主必须带上这个属性——这也正是它声明在共享容器上、而不是应用根节点上的原因。
- InputBar 的 14 行上限现在通过一个自 `.composerSeat` 继承而来的自定义属性解析，且落在真正滚动草稿的那个盒子上（[两层文本共用同一个滚动容器](2026-07-31-composer-text-layers-share-one-scrollport.md)把该声明从自增高镜像层移了出去）。把输入栏渲染到该容器之外会丢掉这条声明（一个没有兜底值的未解析 `var()`），因此未来的 composer 宿主必须带上这个属性——这也正是它声明在共享容器上、而不是应用根节点上的原因。
- 该场景录制的命令是一段 200 个 token 的字符块，远超一次往返所需。这个代价是有意付出的：没有能越过上限的内容，这个上限无法被证伪，而模型会把任何规整的载荷压缩掉（第一次录制时，模型把"alpha 重复 400 次"写成了 `printf 'alpha %.0s' {1..400}`，一条什么也证明不了的单行命令）。
## 验证
`apps/web/tests/approval-composer.e2e.ts` 驱动的是真实组合：一个只读会话、一次被拒绝的写入、模型的越权重试，以及在面板上点击完成的回应。几何断言在两个视口高度上针对活动面板执行，并有守卫防止它空洞地成立——该区域必须确实处在滚动状态，且实测上限必须等于 composer 自身的上限，后者由测试在发送之前从活动 textarea 上读出，而不是把该像素值写死。
`apps/web/tests/approval-composer.e2e.ts` 驱动的是真实组合：一个只读会话、一次被拒绝的写入、模型的越权重试，以及在面板上点击完成的回应。几何断言在两个视口高度上针对活动面板执行，并有守卫防止它空洞地成立——该区域必须确实处在滚动状态，且实测上限必须等于 composer 自身的上限，后者由测试在发送之前从活动的草稿滚动容器上读出，而不是把该像素值写死。
在构建产物客户端上双向确认过。撤销上限后，该区域报告 `scrolls: false`，并长到命令的完整高度（900x1000 下，录制的字符块为 1798px，而设上限后为 336px）；在 900x700 下卡片高 680px、视口高 700px，操作按钮行底边落在 y=749——正在折叠之下，与设计同学的反馈完全一致。恢复上限后，该场景在回放模式下通过。

4
.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
View File

@@ -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-30-composer-context-stack-order.md
2026-07-30-composer-context-stack-order.md: 9c269bcaf7fa360b6a5d0e16fd8cda48aa285d66
2026-07-30-composer-context-stack-order.zh.md: 47288141ea4591b29adde0f85e810fc797740488
2026-07-30-composer-context-stack-order.md: 150225ce27fa8459703170622cef754b7694e2fc
2026-07-30-composer-context-stack-order.zh.md: f13ffc3c1136707a86ba5636a5b69304a132df01

6
.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.md
View File

@@ -10,7 +10,7 @@ Goal, Todo, and Queue contribute independently to the same `conversation.input.d
## Decision
The composer context stack has one canonical ascending order: Goal at `0`, Todo at `10`, and Queue at `20`, followed by the composer bar outside the list. The gaps leave room for future entries to declare their intended position without relying on plugin activation order.
The [Todo-first alignment decision](2026-08-02-todo-first-composer-context-order.md) owns the current ascending order. This note retains the stack contract around that order: numeric gaps leave room for future entries to declare their intended position without relying on plugin activation order, and the composer bar follows the list.
`ConversationRoot` owns the 6px space between independent context cards. Goal is a standalone 752×36px card and collapsed Todo is a standalone 752×44px card. Queue is the terminal dock entry: its 776px wrapper contains the same 752px panel column and subtracts the shared gap plus a named 5px layout overlap, so the later composer card paints over only the queue edge. Empty entries render null and consume no gap.
@@ -18,7 +18,7 @@ The order and overlap are separate contracts. Registration order establishes sem
## Verification
Registration tests pin all three order values. Browser screenshots cover the full Goal/Todo/Queue matrix, Goal+Todo without Queue, and Queue alone; together they exercise every adjacency: Goal–Todo, Todo–Queue, and Queue–Composer.
Registration tests pin all three order values. The keyless Queue browser scenario renders Todo, Goal, and Queue together, pins their accessibility order, and checks their visible card edges; focused Goal and Queue scenarios cover their independent states.
## Alternatives considered
@@ -30,4 +30,4 @@ Registration tests pin all three order values. Browser screenshots cover the ful
## Consequences
The visual hierarchy is stable for every presence combination, and Queue is the only context surface joined to the composer. New input-dock plugins must choose an order relative to Goal `0`, Todo `10`, and Queue `20`; an entry after Queue also requires an explicit decision about which surface owns the composer boundary.
The visual hierarchy is stable for every presence combination, and Queue is the only context surface joined to the composer. New input-dock plugins must choose an order relative to Todo `0`, Goal `10`, and Queue `20`; an entry after Queue also requires an explicit decision about which surface owns the composer boundary.

6
.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
View File

@@ -10,7 +10,7 @@ Goal、Todo 与 Queue 独立注册到同一个 `conversation.input.dock` 列表
## 决策
composer 上下文堆栈采用唯一规范的升序排列：Goal 为 `0`，Todo 为 `10`，Queue 为 `20`，随后是位于列表外的 composer bar。顺序值之间的空档使未来条目可以声明预期位置，不必依赖插件激活顺序。
[Todo 优先的对齐决策](2026-08-02-todo-first-composer-context-order.md)规定当前的升序排列。本记录保留围绕该顺序的堆栈契约：数值间隔使未来条目可以声明预期位置，不必依赖插件激活顺序；composer bar 位于列表之后。
`ConversationRoot` 负责独立上下文卡片之间的 6px 间距。Goal 是一张独立的 752×36px 卡片，折叠后的 Todo 是一张独立的 752×44px 卡片。Queue 是末端 dock 条目：其 776px 包装层包含相同的 752px 面板列，并减去共享间距与具名的 5px 布局重叠量，因此后渲染的 composer 卡片只覆盖 Queue 边缘。空条目渲染为 null，不占用间距。
@@ -18,7 +18,7 @@ composer 上下文堆栈采用唯一规范的升序排列：Goal 为 `0`，Todo
## 验证
注册测试固定了三个顺序值。浏览器截图覆盖完整的 Goal／Todo／Queue 组合矩阵、没有 Queue 的 Goal+Todo，以及仅有 Queue 的情况；这些场景共同覆盖全部相邻关系：Goal–Todo、Todo–Queue 与 Queue–Composer。
注册测试固定了三个顺序值。无密钥 Queue 浏览器场景同时渲染 Todo、Goal 和 Queue，固定它们的无障碍顺序，并检查其可见卡片边缘；聚焦的 Goal 与 Queue 场景覆盖各自的独立状态。
## 考虑过的替代方案
@@ -30,4 +30,4 @@ composer 上下文堆栈采用唯一规范的升序排列：Goal 为 `0`，Todo
## 后果
所有存在组合下的视觉层级都保持稳定，Queue 是唯一与 composer 相接的上下文界面。新的 input-dock 插件必须相对于 Goal `0`、Todo `10` 与 Queue `20` 选择顺序；若条目位于 Queue 之后，还必须明确决定由哪个界面负责 composer 边界。
所有存在组合下的视觉层级都保持稳定，Queue 是唯一与 composer 相接的上下文界面。新的 input-dock 插件必须相对于 Todo `0`、Goal `10` 与 Queue `20` 选择顺序；若条目位于 Queue 之后，还必须明确决定由哪个界面负责 composer 边界。

6
.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml Normal file
View File

@@ -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-30-multi-select-custom-answer-composition.md
2026-07-30-multi-select-custom-answer-composition.md: 581beec89a0f0018ec2df687f5dfe1b1b5b86d22
2026-07-30-multi-select-custom-answer-composition.zh.md: 5c9cb59822aca3fbf49fbbdf522c76f963df3480

25
.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.md Normal file
View File

@@ -0,0 +1,25 @@
# Agent Note: Multi-select custom answer composition
Status: implemented
English | [中文](2026-07-30-multi-select-custom-answer-composition.zh.md)
## Problem
The user-interaction result vocabulary carries selected option labels and optional custom text in separate fields, but its original semantics made them mutually exclusive for every question. On a multi-select question, opening or typing the custom answer discarded labels the user had already selected. The TUI returned only the custom text, and the Web host rejected a client response that preserved both fields.
## Decision
For a question with `multiSelect: true`, one answer item may contain both a non-empty `selected` array and non-empty `custom` text. Web drafts preserve both values regardless of whether the user selects an option or types custom text first; the TUI retains pending custom text across option/custom mode switches and projects it with checked labels from either submit mode; and the Web host accepts the combined response after applying its existing id, label, uniqueness, batch, and non-empty-text validation.
Single-select and optionless questions keep exclusive semantics: custom text overrides any selected option. The result shape remains `{ id, selected, custom? }`, so no wire or tool-output schema changes.
## Alternatives considered
**Encode custom text as another `selected` label.** Rejected because it would erase the distinction between caller-provided option labels and human-authored text, weakening validation and forcing consumers to infer which value was custom.
**Allow `selected` and `custom` together for every question.** Rejected because a single-select question represents one answer; permitting a selected option plus custom text would make its cardinality ambiguous. The combined form is limited to questions that explicitly opt into multiple answers.
## Consequences
Multi-select UIs can represent the user's complete answer without discarding either source. Providers and consumers retain the existing DTO, while request-aware validators interpret the allowed combination from `multiSelect`. Web component and assembled-browser coverage, TUI coverage, host-response coverage, and tool-projection coverage pin the combined result. Web, TUI, and tool-projection coverage also retain labels-only answers; assembled keyless TUI coverage pins the combined terminal flow, and single-select host coverage pins the remaining exclusivity rule.

25
.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md Normal file
View File

@@ -0,0 +1,25 @@
# Agent Note: 多选题自定义答案组合
Status: implemented
[English](2026-07-30-multi-select-custom-answer-composition.md) | 中文
## 问题
用户交互结果的词汇分别通过不同字段携带选中的选项标签和可选的自定义文本，但最初的语义要求每个问题的这两个字段互斥。对于多选题，打开自定义答案或输入文本会丢弃用户已选中的标签。TUI 只返回自定义文本，而 Web 宿主会拒绝同时保留两个字段的客户端响应。
## 决策
对于 `multiSelect: true` 的问题，一个回答项可以同时包含非空 `selected` 数组与非空 `custom` 文本。无论用户先选择选项还是先输入自定义文本，Web 草稿都会保留两个值；TUI 在选项与自定义模式之间切换时会保留待提交的自定义文本，并在任一模式提交时将其与已勾选的标签一同投影；Web 宿主则在应用现有的 id、标签、唯一性、批次和非空文本校验后接受组合响应。
单选题和无选项问题仍保持互斥语义：自定义文本会覆盖任何已选中的选项。结果形状仍为 `{ id, selected, custom? }`，因此协议或工具输出 schema 均无需变更。
## 考虑过的替代方案
**把自定义文本编码为另一个 `selected` 标签。** 不予采纳，因为这样会抹去调用方提供的选项标签与用户填写文本之间的区别，削弱校验，并迫使消费方推断哪个值属于自定义内容。
**允许所有问题同时使用 `selected` 与 `custom`。** 不予采纳，因为单选题只表示一个回答；允许选中选项与自定义文本并存会使其基数含义模糊。组合形式仅适用于显式选择多项回答的问题。
## 后果
多选 UI 可以完整表达用户的回答，不会丢弃任一来源。提供方和消费方继续使用现有 DTO，而请求感知的校验器会根据 `multiSelect` 判断是否允许组合。Web 组件与组装浏览器的覆盖率、TUI 覆盖率、宿主响应覆盖率和工具投影覆盖率共同固定组合结果。Web、TUI 与工具投影覆盖率还固定了仅含标签的回答形态；组装后的无密钥 TUI 覆盖率固定终端中的组合回答流程，单选题的宿主覆盖率则固定其余的互斥规则。

6
.agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.i18n.yaml → .agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml
View File

@@ -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 .agents/notes/implemented/bug-fix/2026-07-27-tui-diff-card-redundant-path-header.md
2026-07-27-tui-diff-card-redundant-path-header.md: 708e543ff079828b4929d2a50ac697a9c846608a
2026-07-27-tui-diff-card-redundant-path-header.zh.md: 863868ae707f37689bbc202267c5470d8c3163e9
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.md
2026-07-30-source-checkout-workdir-distinction.md: ba6d9dd12b55a54d4ae8d2e91ad83ac3c1dc47fd
2026-07-30-source-checkout-workdir-distinction.zh.md: ffc2ac7baa2b1bb8ce54607638c35869fc338825

33
.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.md Normal file
View File

@@ -0,0 +1,33 @@
# Agent Note: Source checkout paths do not define working directories
Status: implemented
English | [中文](2026-07-30-source-checkout-workdir-distinction.zh.md)
## Problem
The `harness:source` prompt section follows the [source-location decision](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md), but its original wording called the checkout “your own source code” without distinguishing that path from the session workspace. In a normal TUI configuration that does not state `{{cwd}}` in its persona, this may be the only fixed absolute path near the start of the system prompt. DeepSeek V4 could therefore answer “what's the workdir?” with the harness checkout instead of determining the session's current working directory.
A blanket statement that the checkout is not the working directory would also be false. `dsh meta` intentionally makes the source checkout both values.
## Decision
The section identifies the path as the “DeepSeek Harness implementation checkout.” It says that the checkout location and current working directory are separate values that may differ, forbids inferring the working directory from the checkout path, directs the model to use `pwd`, and limits the checkout's purpose to inspecting or extending DSH itself.
The path derivation, global `harness:source` ownership, and `-99` ordering remain unchanged. Describing the values as conceptually separate rather than always unequal keeps the instruction accurate in both ordinary project sessions and `dsh meta`.
## Verification
The `dsh-app-boot` unit test pins the exact text and its ordering. The CLI keyless PTY smoke inspects the assembled request header. The TUI `source-checkout-workdir` snapshot mounts the section with `/opt/dsh-source`, asks “what's the workdir?” through a recorded DeepSeek V4 turn, and requires the replayed transcript to run `pwd` and report the generated workspace rather than the checkout.
## Alternatives considered
**Say that the checkout is never the working directory.** Rejected because `dsh meta` deliberately makes them the same path.
**Put the current working directory in the global source section.** Rejected because the source section is launcher-global while the working directory belongs to each session; combining them would duplicate the loop's `cwd` ownership and make a stable source fact vary per agent.
**Remove the source path from the prompt.** Rejected because self-referential DSH tools still need a reliable checkout location when the launcher starts from an unrelated project.
## Consequences
The prompt is longer and a direct working-directory question may spend one inexpensive `pwd` tool call. In exchange, the model no longer treats the harness implementation path as an implicit task workspace, while meta mode remains truthful when both values coincide.

33
.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md Normal file
View File

@@ -0,0 +1,33 @@
# Agent Note: 源码 checkout 路径不定义工作目录
Status: implemented
[English](2026-07-30-source-checkout-workdir-distinction.md) | 中文
## Problem
`harness:source` 提示词段遵循[源码位置决策](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md)，但原有措辞把 checkout 称为“你自己的源代码”，却没有区分该路径与会话 workspace。在 persona 不声明 `{{cwd}}` 的普通 TUI 配置中，这可能是系统提示词开头附近唯一固定的绝对路径。因此，DeepSeek V4 可能会直接用 harness checkout 回答“what's the workdir?”，而不是确定会话的当前工作目录。
直接断言 checkout 不是工作目录同样不准确。`dsh meta` 会有意让源码 checkout 同时充当这两个值。
## Decision
该提示词段将路径标识为“DeepSeek Harness implementation checkout”。它说明 checkout 位置与当前工作目录是两个可能不同的值，禁止从 checkout 路径推断工作目录，指示模型使用 `pwd`，并限定该 checkout 只用于检查或扩展 DSH 自身。
路径推导方式、全局 `harness:source` 所有权和 `-99` 顺序均保持不变。将两者描述为概念上独立、而不是始终不相等，使这条指令在普通项目会话和 `dsh meta` 中都准确。
## Verification
`dsh-app-boot` 单元测试固定了完整文本及其顺序。CLI 无密钥 PTY 冒烟测试检查组装后的请求 header。TUI 的 `source-checkout-workdir` 快照把该提示词段挂载为 `/opt/dsh-source`，通过录制的 DeepSeek V4 turn 提问“what's the workdir?”，并要求回放 transcript 运行 `pwd`，报告生成的 workspace 而不是 checkout。
## Alternatives considered
**声明 checkout 永远不是工作目录。**拒绝：`dsh meta` 会有意让它们指向同一路径。
**把当前工作目录写入全局源码提示词段。**拒绝：源码提示词段由 launcher 全局持有，而工作目录属于各个会话；将两者合并会重复 loop 对 `cwd` 的所有权，还会让稳定的源码事实随 agent 变化。
**从提示词中删除源码路径。**拒绝：launcher 从无关项目启动时，自引用 DSH 工具仍需要可靠的 checkout 位置。
## Consequences
提示词会变长，直接询问工作目录时可能多花一次廉价的 `pwd` 工具调用。作为交换，模型不再把 harness 实现路径当作隐含的任务 workspace；当 meta 模式使两个值重合时，提示词仍然准确。

29
.agents/notes/implemented/bug-fix/2026-07-30-tui-adapter-registration-race.md
View File

@@ -1,29 +0,0 @@
# Agent Note: TUI model-context resolution defers on the adapter-registration race
Status: implemented
English | [中文](2026-07-30-tui-adapter-registration-race.zh.md)
## Problem
Cordis activates plugins by service availability, not configuration order, so the TUI (whose `inject` requires only the `llm` service) can mount before a configured adapter plugin such as `dsh-llm-pi-ai` finishes registering its provider routes. The TUI's model controller resolves the selected model's context window immediately on mount; when the agent's route pointed at a not-yet-registered provider, `resolveModelInfo` rejected with `NO_ADAPTER` and every fresh session printed `Could not resolve model context: no adapter registered for provider "…"` — a spurious error for a fully working configuration (the adapter registered milliseconds later, and chatting worked).
## Decision
The TUI model controller treats a `NO_ADAPTER` rejection of its context-window resolution as a transient state rather than an error: it parks the resolution silently and re-resolves on the next `llm/adapters-updated` commit — the payload-free registry notification `LlmService` already fires at every route commit point. A commit that still lacks the route parks the wait again, so unrelated topology changes stay silent. Any target change re-enters the resolution and clears the pending wait, so the deferred state can never go stale against the current selection; every other resolution error still prints the notice.
## Alternatives considered
**Have the TUI wait for boot to settle before resolving.** The TUI has no Loader dependency (tests and embedders run without one) and "settled" is not observable from inside a plugin; adding a Loader coupling for one cosmetic resolution inverts the dependency direction.
**Poll or retry with a timer.** A timer guesses at activation latency, still mis-prints on a slow adapter, and adds a tunable with no owner. The registry already announces every commit through `llm/adapters-updated`; subscribing is precise and free.
**Order the config so adapters load first.** Row order carries no load semantics in the Loader (activation is service-driven by design), so this cannot be expressed in configuration.
**Suppress NO_ADAPTER errors entirely.** A permanently missing adapter (typo in the provider name) would then never surface in the context-window path. Deferring keeps the signal: a wrong provider name still shows `model unset`-like behavior in the selector and fails loudly at dispatch, while the startup race resolves itself.
**Resolve the context window per submitted message instead of at mount.** The send path already resolves per step (`prepareCall()`), and the indicator is displayed continuously, not only when sending; per-submit display resolution would leave the indicator blank until the first message and re-run adapter I/O for a value that only changes on route changes.
## Consequences
A genuinely misconfigured provider no longer prints the context-resolution error at startup — it surfaces at first dispatch instead, which is where the failure is actionable. The controller subscribes to every `llm/adapters-updated` commit but acts only while a wait is parked; the listener's disposer is released by the channel's `detachListeners()` through the controller's `detach()`, symmetric with the sibling channel listeners. Covered by three TUI tests: the deferred resolution stays silent through an unrelated commit and completes when the route's commit arrives, a target change drops the stale wait, and after channel detach a registry commit no longer re-enters resolution.

29
.agents/notes/implemented/bug-fix/2026-07-30-tui-adapter-registration-race.zh.md
View File

@@ -1,29 +0,0 @@
# Agent Note: TUI 模型上下文解析在适配器注册竞争时延后重试
Status: implemented
[English](2026-07-30-tui-adapter-registration-race.md) | 中文
## Problem
Cordis 按服务可用性而非配置顺序激活插件，因此 TUI（其 `inject` 只要求 `llm` 服务）可能在 `dsh-llm-pi-ai` 这类已配置的适配器插件完成提供方路由注册之前就挂载。TUI 的模型控制器在挂载时立即解析所选模型的上下文窗口；当 agent 的路由指向尚未注册的提供方时，`resolveModelInfo` 以 `NO_ADAPTER` 拒绝，于是每个新会话都会打印 `Could not resolve model context: no adapter registered for provider "…"` —— 对一份完全正常的配置报出的虚假错误（适配器几毫秒后就完成注册，对话也一切正常）。
## Decision
TUI 模型控制器把上下文窗口解析中的 `NO_ADAPTER` 拒绝视为瞬态状态而非错误：静默搁置这次解析，并在下一次 `llm/adapters-updated` 提交时重新解析——这是 `LlmService` 本就在每个路由提交点发出的无载荷注册表通知。若某次提交仍缺少该路由，等待会被再次搁置，因此无关的拓扑变化保持沉默。任何目标变更都会重新进入解析并清除挂起的等待，因此延后状态绝不会相对当前选择变陈旧；其他所有解析错误仍照常打印通知。
## Alternatives considered
**让 TUI 等启动结算后再解析。** TUI 不依赖 Loader（测试和嵌入方在没有 Loader 的环境下运行），而且"已结算"在插件内部不可观测；为一次外观性的解析引入 Loader 耦合会颠倒依赖方向。
**用定时器轮询或重试。** 定时器只能猜测激活延迟，遇到慢适配器仍会误报，还会引入一个没有归属者的可调参数。注册表本就通过 `llm/adapters-updated` 公告每次提交；订阅它既精确又零成本。
**调整配置顺序让适配器先加载。** Loader 中行顺序不承载加载语义（激活按设计由服务驱动），因此这无法用配置表达。
**彻底压制 NO_ADAPTER 错误。** 那样的话，永久缺失的适配器（提供方名字拼错）在上下文窗口路径上就永远不会暴露。延后重试保留了信号：错误的提供方名字仍会在选择器中表现出类似 `model unset` 的行为，并在分派时大声失败，而启动竞争则自行化解。
**改为在每次提交消息时解析上下文窗口，而不是在挂载时。** 发送路径本就按步解析（`prepareCall()`），且指示器是持续显示的，不只在发送时；按提交解析显示值会让指示器在首条消息之前一直空白，并为一个仅在路由变化时才变的值反复执行适配器 I/O。
## Consequences
真正配置错误的提供方不再在启动时打印上下文解析错误——它改在首次分派时暴露，那才是该失败可以被处理的地方。控制器订阅每次 `llm/adapters-updated` 提交，但只在有等待被搁置时才动作；监听器的 disposer 经由控制器的 `detach()` 在频道的 `detachListeners()` 中释放，与同级频道监听器保持对称。由三个 TUI 测试覆盖：延后的解析在无关提交中保持沉默、在该路由的提交到来时完成；目标变更丢弃陈旧等待；频道 detach 之后注册表提交不再重新进入解析。

27
.agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.md
View File

@@ -1,27 +0,0 @@
# Agent Note: Web details default closed
Status: implemented
English | [中文](2026-07-30-web-details-default-closed.zh.md)
## Problem
The transient layout store initialized details to its 360px contract width. The first connected Session and every full reload therefore reserved a right column before the user selected any detail content. Chat tool rows deliberately remain inline and do not open details, while Trajectory rows open the panel when an event is selected, so an open layout default did not represent an active detail selection.
## Decision
The layout store initializes details to zero while retaining the existing 360px contract default for `openDetails()`. `AppFrame` keeps the details slot mounted at zero width, so an explicit entry point such as Trajectory event selection can open the panel without remounting its subtree. The [Session ownership lifecycle](2026-07-29-web-details-session-lifecycle.md) remains authoritative: unselected surfaces derive zero width without taking ownership, returning to the same Session preserves an explicitly opened width, and selecting a different Session closes it.
Panel geometry remains transient. No browser storage key is introduced, and reload restores the sidebar default while details returns to zero. Component tests pin the store default, mounted zero-width slot, drag and concession behavior after explicit opening, and Session ownership transitions. The keyless shipped-composition regression pins the closed first Session, reload, new-session surface, and subsequent Session selections.
## Alternatives considered
**Persist the last open or closed preference.** Rejected because reload should have a deterministic closed baseline, and persisting geometry would reintroduce stale viewing state across browser sessions.
**Keep details open until Chat receives a replacement selection gesture.** Rejected because empty space is not useful detail content. Chat's inline tool-row interaction and any future detail-selection gesture are separate product decisions.
**Remove the details column and layout service.** Rejected because Trajectory already opens event details through this seam, and keeping the mounted slot preserves that working interaction.
## Consequences
New, restored, and reloaded Sessions use the full center area until an explicit details action opens the right column. Trajectory event selection can still open details at 360px and its close control returns the track to zero; Chat tool rows remain geometry-inert. Switching to another Session closes an opened panel, and no panel state survives reload.

27
.agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.zh.md
View File

@@ -1,27 +0,0 @@
# Agent Note: Web 详情栏默认关闭
Status: implemented
[English](2026-07-30-web-details-default-closed.md) | 中文
## 问题
瞬时布局 store 原本将详情栏初始化为 360px 的契约宽度。因此，首个已连接会话以及每次完整重新加载都会在用户选择任何详情内容之前预留右侧栏。Chat 工具行有意保持内联，不会打开详情栏；Trajectory 行则会在选中事件时打开详情栏。因此，布局默认打开并不表示存在有效的详情选中项。
## 决策
布局 store 将详情栏初始化为零，同时保留 `openDetails()` 现有的 360px 契约默认宽度。`AppFrame` 仍以零宽度挂载详情 slot，因此 Trajectory 事件选择等显式入口可以打开详情栏，而无需重新挂载其子树。[会话所有权生命周期](2026-07-29-web-details-session-lifecycle.md)仍是权威契约：未选中表面会派生零宽度而不取得所有权；返回同一会话时会保留显式打开后的宽度；选择不同会话时则会关闭详情栏。
面板几何信息仍是瞬时状态。系统不新增浏览器存储键；重新加载会恢复侧边栏默认值，并使详情栏回到零宽度。组件测试固定验证 store 默认值、保持挂载的零宽度 slot、显式打开后的拖动与让步行为，以及会话所有权过渡。无密钥的已交付组合回归测试固定验证首个会话保持关闭、重新加载、New Session 表面和后续会话选择。
## 考虑过的替代方案
**持久化最后一次打开或关闭的首选状态。** 之所以否决：重新加载必须具有确定的关闭基线，而持久化几何信息会在浏览器会话之间重新引入陈旧的查看状态。
**在 Chat 获得替代性的选择手势前保持详情栏打开。** 之所以否决：空白区域不是有用的详情内容。Chat 的内联工具行交互与未来可能增加的详情选择手势属于彼此独立的产品决策。
**移除详情栏和布局服务。** 之所以否决：Trajectory 已经通过该服务边界打开事件详情；继续挂载该 slot 可以保留这一正常工作的交互。
## 后果
新建、恢复和重新加载的会话会使用完整的中央区域，直至显式详情操作打开右侧栏。Trajectory 事件选择仍可将详情栏打开至 360px，其关闭控件会使轨道回到零；Chat 工具行仍不改变几何信息。切换到其他会话会关闭已打开的详情栏，并且任何面板状态都不会在重新加载后保留。

4
.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
View File

@@ -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-30-web-transcript-log-ordered-projection.md
2026-07-30-web-transcript-log-ordered-projection.md: 4bc629bfa619a2858ec0335a6136d3a5a24b025a
2026-07-30-web-transcript-log-ordered-projection.zh.md: d011ce9453bc1dbb9fdb62372aa1126c95ffb143
2026-07-30-web-transcript-log-ordered-projection.md: 558d60cf6f6638c3e776396dd754d31b95819b28
2026-07-30-web-transcript-log-ordered-projection.zh.md: 2eb216fd1970700fb54a2aa17ec5ce515869e5b0

2
.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
View File

@@ -69,4 +69,4 @@ The web e2e scenario now seeds a real compaction transaction over its recorded t
## Deferred
The terminal's [compaction progress decision](../feature/2026-07-30-compaction-progress-visibility.md) uses the live standalone bracket to drive a one-cell indicator and does not change this browser projection. The marker still carries no **scale**: the checkpoint's `sourceEventSeqs` hold the shadowed count, so a separately justified count or range can be added without coupling it to progress.
The terminal's [archived compaction progress decision](../../archived/feature/2026-07-30-compaction-progress-visibility.md) uses the live standalone bracket to drive a one-cell indicator and does not change this browser projection. The marker still carries no **scale**: the checkpoint's `sourceEventSeqs` hold the shadowed count, so a separately justified count or range can be added without coupling it to progress.

2
.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
View File

@@ -69,4 +69,4 @@ Web e2e 场景现在在它录制的那一轮之上播种一次真实的压缩事
## Deferred
终端的[压缩进度决策](../feature/2026-07-30-compaction-progress-visibility.md)使用实时独立标记对驱动单格指示器，并不改变此浏览器投影。标记仍不携带**规模**信息：检查点的 `sourceEventSeqs` 保存被遮蔽的数量，因此可以另行论证后添加计数或区间，而无须将其与进度耦合。
终端的[已归档压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用实时独立标记对驱动单格指示器，并不改变此浏览器投影。标记仍不携带**规模**信息：检查点的 `sourceEventSeqs` 保存被遮蔽的数量，因此可以另行论证后添加计数或区间，而无须将其与进度耦合。

6
.agents/notes/implemented/bug-fix/2026-07-31-composer-glyph-layer-tracks-the-textarea.i18n.yaml
View File

@@ -1,6 +0,0 @@
# 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-composer-glyph-layer-tracks-the-textarea.md
2026-07-31-composer-glyph-layer-tracks-the-textarea.md: d60a100be98683b5f7a7c88edf7585d275134730
2026-07-31-composer-glyph-layer-tracks-the-textarea.zh.md: eab3f9e3fe3bddb426836113d08f1839329119d5

77
.agents/notes/implemented/bug-fix/2026-07-31-composer-glyph-layer-tracks-the-textarea.md
View File

@@ -1,77 +0,0 @@
# Agent Note: The composer's glyph layer tracks the textarea's scroll offset
Status: implemented
English | [中文](2026-07-31-composer-glyph-layer-tracks-the-textarea.zh.md)
## Problem
A composer draft longer than the 14-line cap could not be scrolled. The caret moved and the selection moved, but the words stayed frozen at line 1 — no wheel gesture, drag, or arrow key brought the end of a long draft on screen, so the bottom of anything past ~14 lines was unreachable and unreadable while writing it.
The cap itself was working. The composer paints its text in two stacked layers ([InputBar](../../../../packages/client/ui-conversation/src/client/skeleton/InputBar.tsx)): the `<textarea>` owns the value, the selection, and the caret but renders its own glyphs `color: transparent`, and every visible character is painted by the `[data-input-backdrop]` div beneath it, which also carries the claim-token highlight, the chips, and the ghost hint. That split is what makes chips and highlights possible at all — a textarea cannot style a range of its own text.
The two layers were coupled in geometry but not in scroll. The backdrop is `position: absolute; inset: 0; overflow: hidden`: it is clipped, not scrolled, and nothing in the browser links its offset to the textarea's. Below the cap that is invisible, because both layers rest at offset 0 and the mirror div sizes the box to the draft. At the cap the textarea starts scrolling and the backdrop does not follow, so the layer the user actually reads never moves.
The defect is therefore exactly as old as the cap, and it hid behind the resting state: a short draft, the state every screenshot and every existing fixture captured, renders identically with and without the coupling.
## Decision
`InputBar` mirrors the textarea's `scrollTop` onto the backdrop from one `scroll` listener, registered beside the existing wheel-chaining listener in the same effect (the textarea is never unmounted — the inert state renders the same element disabled).
One listener is the whole coupling, because every way the box moves ends in a `scroll` event on the textarea. A gesture scrolls it; an edit scrolls the caret into view; a draft that shrinks past the current offset clamps it. The clamp case is the one that looks like it needs separate handling and does not: the two layers share an extent, so they clamp to the same maximum, and the textarea's clamp fires the `scroll` that mirrors it.
That shared extent is not free, and mirroring an offset is only correct while it holds. Two things break it, both discovered in review, both failing in the same direction — a backdrop shorter than the textarea, so the assignment clamps and the glyphs sit below the caret. A textarea reserves a line box for the caret after a final newline; `white-space: pre-wrap` collapses a text node's trailing newline and generates none. A draft ending in a newline therefore made the backdrop exactly one line shorter than the textarea — measured 628 against 652 — so the assignment clamped and the glyphs sat a line behind the caret at the very bottom. The backdrop now carries the same trailing-line sentinel the mirror div already did: its content is the decoration walk plus one `'\n'`, which the same collapse absorbs when the draft does not end in a newline and which supplies the missing line box when it does. Measured across plain, trailing-newline, soft-wrapping, unbreakable-run, and interior-blank-line drafts, the two extents now agree in every case.
The second premise is wrap width, and it is asserted rather than fixed. Only `.input` scrolls, so only `.input` can lose content width to a scrollbar that consumes layout space, and a narrower `.input` wraps a long draft onto more lines — worth 2 to 5 lines for an 8px difference, measured on a standalone harness, while at equal widths a textarea and a div agree exactly. Measured on the running app across the three engines Playwright ships, the widths agree on two and not on the third:
| engine | `.input` / `.backdrop` / `.mirror` wrap width | extents |
|---|---|---|
| chromium | 776 / 776 / 776 | equal |
| firefox | 776 / 776 / 776 | equal |
| WebKit | **768** / 776 / 776 | equal for the drafts measured |
WebKit's textarea loses 8px to its scrollbar while the clipped layers keep theirs. That gap predates this change and is not closed here; the mirror is unaffected on the drafts measured because the extents still agree, but a draft whose wrapping is sensitive at exactly that width would make `.input` taller and clamp the mirrored offset. The scenario asserts the equality on the lane's engine, so a regression into that state fails loudly rather than silently.
`scrollbar-gutter: stable` on the shared metrics block was tried and removed. WebKit applies it to `overflow-y: auto` but not to `overflow: hidden`, so it left `.input` at 768 against 776 — exactly the gap it was meant to close — while costing chromium 8px of text width unconditionally. Closing this needs one geometry every engine agrees on, not that property.
The mirror is one-directional: the textarea is the authority because it owns the caret, and the caret is what the browser scrolls to.
## Alternatives considered
**Give the backdrop `overflow: auto` and let it scroll itself.** It would then have a scroll offset of its own to keep in step, which is the same problem plus a second scrollbar painted over the input. The backdrop is a projection of the textarea, not an independently navigable surface.
**Drop the backdrop and style the textarea's own text.** This removes the layer split and the whole class of desync with it. Rejected because it is not implementable: a textarea renders one uniform text run, so the claim-token highlight, the chips, and the ghost hint — the reasons the backdrop exists — have no way to be expressed. Losing them to fix scrolling trades a bounded defect for a feature deletion.
**Render the draft in a `contenteditable` div instead of a textarea.** One element, one scroll offset, styleable ranges. Rejected as far out of proportion to the defect: `contenteditable` would put IME composition, undo/redo, selection semantics, and paste normalization back on us, all of which the textarea plus the input machine currently handle, and the machine already owns an undo log that assumes a textarea's value semantics.
**Scroll the backdrop from the existing wheel handler instead of a `scroll` listener.** The handler already runs on every wheel over the textarea, so it looks like the natural place. Rejected because it covers only one of the ways the box scrolls: typing at the end, `End`, arrow keys, drag-selection past the edge, and scrollbar drags all move the textarea without a wheel event. Listening to `scroll` is listening to the thing itself rather than to one of its causes.
**Reserve the scrollbar gutter on all three layers with `scrollbar-gutter: stable`.** Adopted, then reverted on measurement. The reasoning was that whatever a platform's scrollbar costs, three layers reserving it stay equal — and `overflow: hidden` is a scroll container, so the spec says the clipped layers honour it. Chromium agrees (8px reserved on each, widths 768/768/768). WebKit does not: it reserves for `overflow-y: auto` and not for `overflow: hidden`, leaving 768 against 776 — the same gap, unclosed — so the property bought nothing on the one engine where the divergence is observable while costing every chromium user 8px of text column. Reverted in favour of asserting the premise and recording the WebKit gap.
**Suppress the textarea's scrollbar instead of reserving a gutter on the other layers.** `scrollbar-width: none` on `.input` would equalize the widths without narrowing the text column. Rejected because the composer deliberately shows a thumb once the draft passes the cap — `.card` binds the l2 scrollbar tokens for exactly that — and removing it takes away the only affordance that says a long draft continues below.
**Translate the backdrop with `transform: translateY(-scrollTop)` instead of scrolling it.** A transform is not clamped by content height, so it would paper over any extent divergence — including the trailing-newline one — without matching the layers. Rejected because the divergence is the actual defect: unequal extents also mean the two layers disagree about where the last line sits, and hiding that behind an unclamped transform would leave a mismatch that resurfaces the moment anything measures the backdrop. Fixing the extent keeps one truth about the draft's height.
**Add a second mirror in a layout effect keyed on the committed draft.** This shipped in the first version of the change, on the theory that an edit reflows both layers without necessarily moving the textarea, and that a shrinking draft clamps each layer independently. Both premises are false, and it was removed after mutation-testing each hook alone against the built client: with only the layout effect disabled the browser scenario stays green, while disabling only the `scroll` listener fails it. Typing scrolls the caret into view, which is an ordinary `scroll`; a shrinking draft clamps both layers to the same maximum because their extents are equal, and the textarea's clamp fires `scroll` too. The specific hazard the effect was imagined to cover — React replacing the backdrop's children when the decoration set changes shape, resetting its offset — does not occur: measured in chromium, replacing every child of an `overflow: hidden` box preserves `scrollTop` (300 stays 300), and the only replacement that zeroes it is one that shrinks the content below the offset, which is the clamp case already covered.
**Sync in the `onChange` handler.** Rejected for the same reason plus one of its own: it fires before React commits the new draft to the backdrop, so it would mirror against the previous layout.
## Consequences
- A draft past the cap scrolls its glyphs. Measured in the browser scenario: after a wheel gesture over a 40-line draft the last line sits inside the visible box and the first has scrolled out above it; before, the last line stayed a full draft-height below the box while the textarea's own offset had moved.
- The coupling is one-directional and cheap — one assignment of one number, no measurement, no layout read beyond `scrollTop` — so it adds nothing to the typing path's cost.
- Chips, claim-token highlights, and text-ref marks stay aligned with their glyphs while scrolled, because they are positioned inside the backdrop and move with it. Nothing about the decoration walk changes.
- The composer's two-layer design keeps this hazard: any future layer added beside the backdrop needs the same mirroring, and any change to how a layer reserves its last line box breaks the extent equality the mirror depends on. The e2e scenario asserts both — the relation the user cares about (which line is on screen) and the extent equality underneath it — so a future divergence fails on the invariant rather than on a screenshot.
- Extent equality is asserted, not assumed. It is the premise that turns "mirror the offset" from correct into subtly wrong, and it failed for the trailing-newline shape before the sentinel.
- Wrap-width equality is the other premise, and it does NOT hold universally: WebKit lays `.input` out 8px narrower than the glyph layers. That predates this change and is left open, with the measurement recorded above and an assertion on the lane's engine. A draft whose wrapping turns on those 8px would clamp the mirror on WebKit.
- The composer's layout is unchanged. An earlier revision narrowed the text column by 8px on every platform to chase the wrap-width premise; measurement showed it did not buy the guarantee, so the metrics are the same as before this change.
## Testing
The unit spec in [input-bar.spec.tsx](../../../../packages/client/ui-conversation/tests/input-bar.spec.tsx) proves the mirroring path runs: it stubs both offsets, because jsdom reports `scrollHeight === clientHeight` for every element and never scrolls one, and asserts the backdrop follows the textarea to a new offset and back to the top. Reverting the `ref` makes it fail.
The user-visible fact needs a real engine, so [composer-draft-scroll.e2e.ts](../../../../apps/web/tests/composer-draft-scroll.e2e.ts) measures it in chromium against the built client: a 40-line draft in a fresh workspace's blank composer, zero model calls, with a DOM Range over the backdrop's own text reporting where the first and last lines sit relative to the visible box. A vacuity guard asserts the draft actually overflows the capped box first. A separate case drives the trailing-newline shape and asserts the two extents are equal before asserting the glyphs reach the end; each layer's maximum is observed by asking for an impossible offset and reading back the clamp, not computed from `scrollHeight`. A third asserts the gutter premise: equal wrap widths, and a reserved band greater than zero on each layer. The band is what keeps that assertion from being vacuous — the widths would also match with no reservation at all on this engine's overlay scrollbar, and it is the reservation, not the match, that carries the guarantee to a platform whose scrollbar takes real width.
Confirmed both directions against the built client. With the mirroring reverted and the packages rebuilt, the wheel case fails on the layer offsets, the typing case fails with it, and the golden diff reads `last draft line is on screen: false` while `textarea moved: true` — the reported symptom stated as a fixture. The resting-state case passes in both builds, which is the point: it is the state that hid the defect.
Note that the composer ships inside a client-module bundle, so `pnpm run build:web` alone does not pick up a change to `InputBar.tsx` — the package build must run for the browser lane to see it, and a scenario run against a stale `lib/` asserts against an older client than the tree.

77
.agents/notes/implemented/bug-fix/2026-07-31-composer-glyph-layer-tracks-the-textarea.zh.md
View File

@@ -1,77 +0,0 @@
# Agent Note: composer 的字形层跟随 textarea 的滚动偏移
Status: implemented
[English](2026-07-31-composer-glyph-layer-tracks-the-textarea.md) | 中文
## 问题
草稿一旦超过 14 行的高度上限，就无法再滚动。光标会动，选区会动，但文字始终冻结在第 1 行——无论滚轮、拖拽还是方向键，都无法把长草稿的末尾带到可见范围内，因此约 14 行之后的内容在书写过程中既够不着也读不到。
高度上限本身是正常工作的。composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/client/ui-conversation/src/client/skeleton/InputBar.tsx)）：`<textarea>` 持有取值、选区与光标，但它自己的字形以 `color: transparent` 渲染；用户看到的每一个字符都由其下的 `[data-input-backdrop]` 层绘制，该层同时承载 claim token 高亮、chip 与提示影子文本。这一拆分正是 chip 与高亮得以存在的前提——textarea 无法为自身文本的某个区间单独设置样式。
两层在几何上是耦合的，在滚动上却不是。backdrop 为 `position: absolute; inset: 0; overflow: hidden`：它只做裁剪，不做滚动，浏览器也不会把它的偏移与 textarea 关联起来。未达上限时这一点不可见，因为两层都停在偏移 0，且镜像层会把盒子撑到草稿的高度。一旦触及上限，textarea 开始滚动而 backdrop 不跟随，于是用户真正在读的那一层从不移动。
因此该缺陷与高度上限同龄，并且藏在静止状态背后：短草稿——也就是所有截图与既有 fixture（测试前置数据）所捕获的那个状态——在有无该耦合时渲染完全一致。
## 决策
`InputBar` 通过一个 `scroll` 监听把 textarea 的 `scrollTop` 镜像到 backdrop 上，该监听与既有的滚轮接力监听注册在同一个 effect 中（textarea 从不卸载——失效状态渲染的是同一个元素的 disabled 形态）。
一个监听即构成完整耦合，因为这个盒子移动的每一种方式最终都会在 textarea 上产生 `scroll` 事件：手势使它滚动；编辑会把光标滚入可见范围；草稿缩短到当前偏移之下时它会被钳位。看似需要单独处理、实则不需要的正是钳位这一种：两层共享同一滚动范围，因此它们会钳位到同一个最大值，而 textarea 的钳位本身就会触发那次完成镜像的 `scroll`。
这个「共享的滚动范围」并非白得，而镜像偏移只有在它成立时才是正确的。有两件事会破坏它，都是在审查中被发现的，且失效方向相同——backdrop 比 textarea 矮，于是赋值被钳制、字形落到光标之下。textarea 会在末尾换行之后为光标保留一个行盒，而 `white-space: pre-wrap` 会折叠文本节点的尾随换行、不生成任何行盒。因此以换行结尾的草稿会让 backdrop 恰好比 textarea 少一行——实测为 628 对 652——于是该赋值被钳制，滚到最底部时字形比光标落后一行。现在 backdrop 也带上了镜像层早已具备的同一枚尾行哨兵：其内容为装饰扫描的结果再加一个 `'\n'`；草稿不以换行结尾时它被同一次折叠吸收，以换行结尾时它补上缺失的那个行盒。对纯文本、尾随换行、软折行、不可断长串以及中间空行五类草稿实测，两侧范围在每种情形下均相等。
第二个前提是折行宽度，它是被断言的，而不是被修复的。只有 `.input` 会滚动，因此也只有 `.input` 会把内容宽度让给一条占布局宽度的滚动条；`.input` 一旦更窄，长草稿就会折出更多行——在独立环境实测，8px 的宽度差值 2 到 5 行，而宽度相等时 textarea 与 div 完全一致。在运行中的应用上、对 Playwright 自带的三个引擎实测，两个相等、一个不等：
| 引擎 | `.input` / `.backdrop` / `.mirror` 折行宽度 | 滚动范围 |
|---|---|---|
| chromium | 776 / 776 / 776 | 相等 |
| firefox | 776 / 776 / 776 | 相等 |
| WebKit | **768** / 776 / 776 | 所测草稿下相等 |
WebKit 的 textarea 把 8px 让给了自己的滚动条，而两个被裁剪的图层没有。该差距先于本次改动存在，本 PR 未予关闭；在所测草稿下滚动范围仍然相等，因此镜像不受影响，但一份恰好在该宽度上折行敏感的草稿会让 `.input` 更高、从而钳制镜像偏移。场景在测试通道所用引擎上断言了这项相等性，因此一旦回退到那种状态会显式失败，而不是悄然发生。
共享度量块上的 `scrollbar-gutter: stable` 曾被采用又被移除：WebKit 对 `overflow-y: auto` 应用它、对 `overflow: hidden` 不应用，于是 `.input` 仍是 768 对 776——正是它本想关闭的那个差距——同时又让 chromium 无条件损失 8px 文本宽度。要关闭它，需要一套所有引擎都认同的几何，而不是这个属性。
该镜像是单向的：textarea 是权威方，因为它持有光标，而浏览器滚动的目标正是光标。
## 曾考虑的替代方案
**给 backdrop 加 `overflow: auto`，让它自行滚动。** 那样它就有了一个属于自己的滚动偏移需要同步，问题原样保留，还额外多出一条画在输入框上的滚动条。backdrop 是 textarea 的投影，而不是一个可独立导航的界面。
**去掉 backdrop，直接为 textarea 自身文本设置样式。** 这会消除分层，连同整类失步问题一并消除。之所以否决，是因为它根本无法实现：textarea 只渲染一段统一的文本流，因此 claim token 高亮、chip 与提示影子文本——backdrop 存在的全部理由——都无从表达。为修滚动而放弃它们，是拿一个有界的缺陷去换一次功能删除。
**改用 `contenteditable` div 承载草稿，不再用 textarea。** 一个元素、一个滚动偏移、区间可设样式。之所以否决，是它与该缺陷的体量严重不相称：`contenteditable` 会把 IME 组词、撤销／重做、选区语义与粘贴规范化重新压回我们身上，而这些目前都由 textarea 加输入状态机处理，且状态机已持有一份以 textarea 取值语义为前提的撤销日志。
**在既有的滚轮处理函数里滚动 backdrop，而不是新增 `scroll` 监听。** 该处理函数本就在 textarea 上的每次滚轮时运行，看似是自然的落点。之所以否决，是它只覆盖了盒子滚动的其中一种成因：在末尾输入、`End`、方向键、拖选越过边缘、拖动滚动条，都会在没有滚轮事件的情况下移动 textarea。监听 `scroll` 是在监听事情本身，而不是它的某一个成因。
**用 `scrollbar-gutter: stable` 让三层一起预留滚动条 gutter。** 曾经采用，实测后回退。当初的推理是：无论平台滚动条占多少宽度，三层都预留同样多即可保持相等；而且 `overflow: hidden` 也是滚动容器，按规范应当遵守该声明。chromium 确实如此（三层各预留 8px，宽度 768/768/768）。WebKit 不然：它对 `overflow-y: auto` 预留、对 `overflow: hidden` 不预留，结果仍是 768 对 776——差距原样保留——于是该属性在唯一能观测到这一偏差的引擎上一无所获，却让每一位 chromium 用户损失 8px 文本列。改为断言该前提并记录 WebKit 的差距。
**改为抑制 textarea 的滚动条，而不是给另外两层预留 gutter。** 在 `.input` 上写 `scrollbar-width: none` 同样能让宽度相等，且不必收窄文本列。之所以否决：草稿超过上限后 composer 是有意显示滚动条滑块的——`.card` 正是为此绑定了 l2 滚动条 token——去掉它就等于拿走了「下面还有内容」这一唯一提示。
**改用 `transform: translateY(-scrollTop)` 平移 backdrop，而不是滚动它。** transform 不受内容高度钳制，因此它能把任何范围偏差——包括尾随换行这一种——一并掩盖，却并不让两层真正对齐。之所以否决，是因为这个偏差本身就是真正的缺陷：范围不等同时意味着两层对末行位置的判断不一致，把它藏在一个不受钳制的 transform 之后，只会让这一失配在任何人去测量 backdrop 的那一刻重新浮现。修正范围本身，才能让草稿高度只有一个事实来源。
**再加一个以已提交草稿为 key 的 layout effect 作为第二道镜像。** 该改动的第一版确实带着它，理由是：一次编辑会让两层重排却不一定让 textarea 移动，且草稿变短时两层各自独立地被钳位。这两个前提都不成立，因此在针对构建产物客户端逐个变异测试每个 hook 之后将其移除：仅禁用 layout effect 时浏览器场景全绿，而仅禁用 `scroll` 监听则会失败。输入会把光标滚入可见范围，那就是一次普通的 `scroll`；草稿变短时两层因范围相等而钳位到同一个最大值，且 textarea 的钳位同样会触发 `scroll`。该 effect 本想覆盖的那个具体隐患——React 在装饰集合形状变化时替换 backdrop 的全部子节点，从而重置其偏移——并不会发生：在 chromium 中实测，替换一个 `overflow: hidden` 盒子的全部子节点会保留 `scrollTop`（300 仍为 300），唯一会将其归零的替换是把内容缩短到偏移之下，而那正是已被覆盖的钳位情形。
**在 `onChange` 处理函数里同步。** 除上述同样的理由外还有其自身的问题：它在 React 把新草稿提交到 backdrop 之前触发，因而会按上一次的布局做镜像。
## 后果
- 超过上限的草稿会滚动其字形。浏览器场景实测：在 40 行草稿上做一次滚轮手势后，最后一行位于可见盒子之内，第一行已滚出上方；此前最后一行仍停在盒子下方整整一个草稿高度处，而 textarea 自身的偏移已经移动了。
- 该耦合是单向且廉价的——一次对一个数字的赋值，没有测量，除 `scrollTop` 外没有额外的布局读取——因此不会给输入路径增加开销。
- chip、claim token 高亮与文本引用标记在滚动时始终与其字形对齐，因为它们定位在 backdrop 内部并随之移动。装饰扫描本身没有任何改动。
- composer 的双层设计保留了这一隐患：日后在 backdrop 旁新增的任何一层都需要同样的镜像；而任何改变某一层如何保留其末行行盒的改动，都会破坏镜像所依赖的范围相等性。e2e 场景对两者都做了断言——用户真正关心的关系（哪一行在屏幕上），以及其下的范围相等性——因此日后一旦出现偏差，失败会落在不变量上，而不是落在某张截图上。
- 范围相等性是被断言的，而非被假定的。它正是那个能把「镜像偏移」从正确变为微妙错误的前提，并且在加入哨兵之前，它在尾随换行这一形态上确实不成立。
- 折行宽度相等是另一个前提，而它并非普遍成立：WebKit 把 `.input` 排得比字形层窄 8px。该问题先于本次改动存在，此处保持开放，上文记录了实测数值，并在测试通道所用引擎上加了断言。一份折行恰好取决于这 8px 的草稿会在 WebKit 上钳制镜像。
- composer 的布局没有变化。此前有一版为追求折行宽度前提而在所有平台把文本列收窄了 8px；实测表明它并不能带来该保证，因此度量与改动前保持一致。
## 验证
[input-bar.spec.tsx](../../../../packages/client/ui-conversation/tests/input-bar.spec.tsx) 中的单元用例证明镜像路径确实执行：它对两侧偏移都做了桩替换——因为 jsdom 对任何元素都报告 `scrollHeight === clientHeight` 且从不滚动任何元素——并断言 backdrop 既跟随 textarea 到新的偏移，也跟随它回到顶部。撤掉那个 `ref` 会让它失败。
用户可见的事实需要真实引擎，因此 [composer-draft-scroll.e2e.ts](../../../../apps/web/tests/composer-draft-scroll.e2e.ts) 在 chromium 中针对构建产物客户端测量它：在全新工作区空白会话的 composer 中放入 40 行草稿，零模型调用，用一个跨越 backdrop 自身文本的 DOM Range 报告首行与末行相对于可见盒子的位置。一个防空转守卫会先断言草稿确实溢出了设有上限的盒子。另有一个独立用例驱动尾随换行这一形态，先断言两侧范围相等，再断言字形确实抵达末尾；每一层的最大值都通过请求一个不可能的偏移再读回其钳位结果来观测，而非由 `scrollHeight` 计算得出。第三个用例断言 gutter 前提：折行宽度相等，且每层预留的带宽大于零。正是这条「带宽」使该断言不至于空转——在本引擎的 overlay 滚动条下，即使完全不预留，两侧宽度也会相等；把保证传递到滚动条真正占宽的平台上的，是那次预留，而不是这次相等。
已双向确认。撤掉镜像并重新构建各包后，滚轮用例在两层偏移上失败，输入用例随之失败，golden 差异读作 `last draft line is on screen: false` 而 `textarea moved: true`——即以 fixture（测试前置数据）形式陈述的原始现象。静止状态用例在两种构建下都通过，这正是要点所在：它就是掩盖了该缺陷的那个状态。
注意 composer 随客户端模块 bundle 一同发布，因此仅运行 `pnpm run build:web` 不会纳入对 `InputBar.tsx` 的改动——必须运行包构建，浏览器测试通道才能看到它；针对陈旧 `lib/` 运行的场景，断言的是比当前工作树更旧的客户端。

6
.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml Normal file
View File

@@ -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-composer-text-layers-share-one-scrollport.md
2026-07-31-composer-text-layers-share-one-scrollport.md: ba11384409714d6a64a964d63197705acf39d213
2026-07-31-composer-text-layers-share-one-scrollport.zh.md: 9a4a2bcc9f947d385d1ff9fc6367b9a3eab17733

82
.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.md Normal file
View File

@@ -0,0 +1,82 @@
# Agent Note: The composer's two text layers share one scrollport
Status: implemented
English | [中文](2026-07-31-composer-text-layers-share-one-scrollport.zh.md)
## Problem
The composer paints its text in two stacked layers ([InputBar](../../../../packages/client/ui-conversation/src/client/skeleton/InputBar.tsx)): the `<textarea>` owns the value, the selection, and the caret but renders its own glyphs `color: transparent`, and every visible character is painted by the `[data-input-backdrop]` div beneath it, which also carries the claim-token highlight, the chips, and the ghost hint. That split is what makes chips and highlights possible at all — a textarea cannot style a range of its own text. The draft box is capped at 14 lines, so past the cap something has to scroll.
Two layers with two scroll offsets fail in two stages, and this change is the second one.
The first was static. The backdrop is `position: absolute; inset: 0; overflow: hidden` — clipped, not scrolled — and nothing in the browser links its offset to the textarea's, so past the cap the caret moved and the words stayed frozen at line 1. Below the cap that is invisible, because both layers rest at 0; the defect was exactly as old as the cap and hid behind the resting state that every screenshot captured. It was fixed by mirroring the textarea's `scrollTop` onto the backdrop from a `scroll` listener, and that made the two layers agree **at rest**.
The second is what a user then reported: swiping quickly from the top of a long draft throws the caret up out of its own text, as though it carried momentum, and it settles back a moment later. The mirror is the cause. A wheel gesture scrolls the textarea on the compositor, off the main thread; the `scroll` event that drives the assignment is dispatched afterwards, so for the frames in between the caret sits at the new offset and every glyph sits at the old one. Measured on a standalone harness of the same geometry, moving the offset 200px and reading the caret's distance to its own glyphs before the task ends: chromium 203px, firefox 202px, WebKit 203px of separation, settling to the fixed line-box constant (3/2/3) a frame or two later. Every engine, every gesture, proportional to how fast the user scrolls.
No listener can close that gap, because the gap is the definition of a listener: it runs after the thing it reacts to. Anything that keeps two boxes equal in JavaScript is a frame behind a compositor that moves one of them without asking.
## Decision
One scrolling box, holding both layers.
`[data-input-scroll]` is the composer's only scrollport and carries the 14-line cap. Inside it, the auto-grow stack is as tall as the **whole** draft — the hidden mirror div is in normal flow and no longer capped, so it sizes the stack to the full text — and the backdrop and textarea ride that height absolutely. The textarea is `overflow: hidden` with no scrollable overflow of its own; it can no longer hold an offset at all.
The browser then applies one offset to both layers, in the same frame, on the same compositor. The caret is bound to its glyphs by construction rather than by upkeep: there is no code to run, no event to wait for, and no state that can be one frame stale. The wheel-chaining handler stays, retargeted from the textarea to the scrollport, and remains the only listener on the box.
Two things the previous mechanism needed are gone with it:
**The backdrop's trailing-line sentinel.** It existed to keep the two boxes' scroll extents equal — a textarea reserves a line box for the caret after a final newline while `white-space: pre-wrap` collapses a text node's trailing newline, so a draft ending in a newline made the backdrop one line shorter and clamped the mirrored offset a line above the caret. With one scrollport the backdrop's own extent decides nothing: the mirror div sizes the stack for both layers, both start at the same top, and a layer whose content ends earlier simply paints nothing on the last line. The shape is worth keeping in mind rather than the mechanism: it is the one that measured 628 against 652 when the two boxes had to agree on a height.
**The wrap-width premise.** All three layers now resolve their width inside the scrollport, so a scrollbar that consumes layout space costs them the same width by construction. This closes the divergence the superseded note recorded as open and unfixable by any property: WebKit reserved gutter space for the `overflow-y: auto` textarea and not for the `overflow: hidden` layers beside it, laying the textarea out 768 against 776 — worth 2 to 5 wrapped lines on a long draft, i.e. glyphs under the wrong caret on the one engine where it was observable. Measured on the harness after the change, all three layers report one width on all three engines Playwright ships.
**Edits the composer performs itself now ask for the reveal.** Paste and cut suppress the native edit — the machine owns the draft and the undo log — and restore the caret with `setSelectionRange`, which reveals nothing: measured in chromium and WebKit, pasting a long block leaves the view where it was while the caret sits at the end of what was pasted. That defect predates this change (Firefox happened to reveal it, in the old geometry only) and is fixed here because one scrollport is what finally makes the reveal ours to perform. The two restores share one helper that measures the caret against the hidden mirror — same draft, same metrics, same wrap width, so a Range collapsed at the caret's index reports where the caret is without a caret API — and scrolls the minimum that brings it inside, which is what the browser does for typing.
One shape needs a rule of its own, because the engines disagree about it: a caret straight after a newline sits on a line with nothing on it to measure, which is where a trailing-newline draft ends. chromium returns **no client rects at all** for the collapsed position — an all-zero box, which would send the reveal the wrong way — firefox reports the line above, and WebKit the right one. The helper therefore measures the newline the caret just left, whose box is the line it came from, and steps one line down; all three then land on the same offset (649 of 652, with the caret's line at 315 inside the 336px box). A non-collapsed Range over that newline returns a real rectangle on all three engines even when the draft ends in consecutive newlines, so each trailing blank line composes with the same rule.
Revealing the caret is the one thing that now depends on the browser rather than on us: with no offset of its own, the textarea's scroll-into-view has to walk up to the scrollport. It does, on every engine measured — typing at the draft's end brings the scrollport to the caret (625, 626 and 628 of a 628px maximum in chromium, firefox and WebKit), walking the caret back up with `ArrowUp` scrolls back to it, and typing after scrolling away returns to it.
## Alternatives considered
**Mirror `scrollTop` onto the backdrop from a `scroll` listener.** The superseded decision, and correct at rest: it is what made a long draft scrollable at all. Rejected now because it cannot be correct in motion — it is a main-thread reaction to a compositor-thread fact — and because it needed two premises to stay true that the single scrollport does not need at all (equal extents, equal wrap widths), each of which had already failed once.
**Translate the backdrop with `transform: translateY(-scrollTop)` instead of assigning an offset.** Same lag: still main-thread, still driven by the same event. It additionally papers over extent divergence rather than making the layers agree, so a mismatch resurfaces the moment anything measures the backdrop.
**Drive the backdrop from a scroll-driven animation (`animation-timeline: scroll()`).** This would run the coupling on the compositor and genuinely eliminate the lag while keeping two boxes. Rejected on support: Safari does not implement it and Firefox has only recently, so the composer would keep the reported defect on the engines that lack it, and the fallback path would be the mechanism being replaced.
**Scroll both layers from JavaScript, with the textarea `overflow: hidden` and a wheel handler assigning both offsets in one task.** No divergence during wheel gestures, since nothing scrolls without us. Rejected because it replaces native scrolling — momentum, trackpad rubber-banding, scrollbar dragging, keyboard scrolling — with a hand-written approximation, and the caret-reveal path (the browser setting the textarea's own offset) still lands asynchronously.
**Keep the cap on the mirror and just wrap today's structure in a scroller.** The layers would stay window-sized, not draft-sized: `inset: 0` on an absolutely positioned child resolves against the scrollport's padding box, not its scrollable overflow area, so both layers would scroll away from the content that is supposed to be underneath them. The stack has to be the full draft height for the arrangement to mean anything.
**Give the backdrop `overflow: auto` and let it scroll itself.** It would then have an offset of its own to keep in step, which is the same problem plus a second scrollbar painted over the input. The backdrop is a projection of the textarea, not an independently navigable surface.
**Drop the backdrop and style the textarea's own text.** This removes the layer split and the whole class of desync with it. Rejected because it is not implementable: a textarea renders one uniform text run, so the claim-token highlight, the chips, and the ghost hint — the reasons the backdrop exists — have no way to be expressed. Losing them to fix scrolling trades a bounded defect for a feature deletion.
**Render the draft in a `contenteditable` div.** One element, one offset, styleable ranges. Rejected as far out of proportion: `contenteditable` would put IME composition, undo/redo, selection semantics, and paste normalization back on us, all of which the textarea plus the input machine currently handle, and the machine already owns an undo log that assumes a textarea's value semantics.
**`scrollbar-gutter: stable` on all three layers.** Tried and reverted while the textarea was the scroller: WebKit applied it to `overflow-y: auto` and not to `overflow: hidden`, leaving the same 8px gap unclosed while costing every chromium user 8px of text column. Moot now — the layers share a containing block, so there is nothing to reserve.
**`scrollbar-width: none` on the scrolling layer.** Would equalize widths by hiding the thumb. Rejected: the composer deliberately shows one once the draft passes the cap — `.card` binds the l2 scrollbar tokens for exactly that — and it is the only affordance saying a long draft continues below.
## Consequences
- The caret cannot leave its glyphs. The browser scrolls one box, so the separation between where the textarea puts a line and where the backdrop paints it is a fixed line-box constant at every offset, mid-gesture included. The scenario measures exactly that number.
- The scrollbar moved from the textarea to the scrollport — the same visual place, one box out. The `.card` l2 token binding still inherits down to it.
- Chips, claim-token highlights, and text-ref marks stay aligned with their glyphs while scrolled, because they are positioned inside the backdrop and move with it. The decoration walk is unchanged apart from the dropped sentinel.
- On Firefox and WebKit, clicking into a composer whose draft overflows the cap now also scrolls the conversation transcript to its bottom: the caret's scroll-into-view walks past the composer's scrollport up to the transcript scrollport, which a textarea shorter than its box never made it do. Chromium does not. Measured, with `overscroll-behavior: contain` and `contain: paint` both tried and neither stopping the walk — there is no CSS that ends scroll-into-view chaining. Accepted: it scrolls toward the bottom, where the composer already sits, and the alternative is a caret visibly detached from its text on every engine.
- Paging and drag-selection are unchanged, both measured old against new. `PageDown`/`PageUp` never moved a textarea's caret in the first place — chromium scrolls a page and leaves `selectionStart` where it was, in both geometries; only the box that scrolls differs. Drag-selecting past the bottom edge still auto-scrolls, and to the same place (chromium 628/628, firefox 625/620, WebKit 170/170 — WebKit's slower autoscroll is equally slow before and after).
- The composer's own `focus()` calls pass `preventScroll` — the unlock/session-switch effect and the focus-keeping mousedown on the toolbar buttons — so a focus nobody gestured for cannot move the transcript through the taller textarea's reveal chain. Suppressing that walk hands the caret back to us on the one path where it matters: the composer DOM is reused across sessions, so switching to a longer draft keeps the previous offset while the value swap puts the caret at the new draft's end. Measured on all three engines, that leaves the caret 940px below a box sitting at 0; the effect therefore reveals it in its own scrollport, landing at 625 of 628 — what the old geometry reached at 628 through the browser. The mousedown path needs no reveal: the caret has not moved, and the next keystroke gets the browser's native one. A separate reveal-only effect handles a non-empty draft that arrives after render: `ConversationSession` seeds a persisted draft in its own mount effect, which runs AFTER this component's, so the first reveal would otherwise measure an empty mirror and never run again for the draft that then appeared. The second effect never focuses, so ordinary empty/non-empty transitions such as send-clear or failed-send restore cannot take focus from another control.
- Undo and redo can change the draft without a caret restore or reveal: the machine replays a previous draft and the DOM selection stays where the browser clamps it. That predates this change and is unchanged by it — named here because the two restores that DO reveal make the omission look deliberate, and the helper is sitting right there if it is ever reported.
- Any layer added beside the backdrop belongs INSIDE the scrollport and must be as tall as the draft, or it reintroduces exactly this defect. This is the composer's standing hazard: the two-layer split is load-bearing for chips and highlights, so the coupling has to be structural, not maintained.
## Testing
The unit spec in [input-bar.spec.tsx](../../../../packages/client/ui-conversation/tests/input-bar.spec.tsx) asserts what jsdom can see: that one scrolling box contains both the textarea and the backdrop, that the backdrop's text is now the draft and nothing else, and that a late persisted draft reveals its caret without taking focus from another control. jsdom reports `scrollHeight === clientHeight` for every element and never scrolls one, so the geometry belongs to the browser scenario; the wheel-chaining cases stub the scrollport's metrics rather than the textarea's.
[composer-draft-scroll.e2e.ts](../../../../apps/web/tests/composer-draft-scroll.e2e.ts) measures the rest in chromium against the built client: a 40-line draft in a fresh workspace's blank composer, zero model calls. Every metric is read in the caret's own coordinate frame — where the textarea places line n, offset included — against a DOM Range over the backdrop's text for the same line, because that difference is what a user sees. The decisive case changes the offset and re-reads that difference **before the task ends**, which is before any `scroll` listener could have run: 0 with one scrollport, and the full delta with a mirror. A vacuity guard asserts the draft overflows the capped box first, and separate cases cover the cap, one wrap width across all three layers, a wheel gesture, a trailing-newline draft, and the caret-reveal path that the textarea's own scrolling used to handle — typing after scrolling away must bring the scrollport back to the caret.
A separate case covers the paste path end to end: a short draft, the caret at its end, and one `paste` event carrying real clipboard data — the same event a Cmd-V delivers, through the same handler — then the offset and the last pasted line. It waits on the offset rather than on the draft overflowing, because the restore lands one frame after the machine commits the draft; a build without the reveal fails that wait.
The two-geometry comparison behind the decision was measured on a standalone harness before implementing, since the old and new arrangements cannot both exist in the app at once: the same-task separation is 203/202/203px old against 3/2/3px new (chromium/firefox/WebKit), the wrap widths 768-against-776 old on WebKit against 1264/1264/1264 new on all three, and the textarea's own scrollable overflow 0 in the new geometry, which is what makes a second offset impossible rather than merely equal.
Note that the composer ships inside a client-module bundle, so `pnpm run build:web` alone does not pick up a change to `InputBar.tsx` — the package build must run for the browser lane to see it, and a scenario run against a stale `lib/` asserts against an older client than the tree.

82
.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md Normal file
View File

@@ -0,0 +1,82 @@
# Agent Note: composer 的两层文本共用同一个滚动容器
Status: implemented
[English](2026-07-31-composer-text-layers-share-one-scrollport.md) | 中文
## 问题
composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/client/ui-conversation/src/client/skeleton/InputBar.tsx)）：`<textarea>` 持有取值、选区与光标，但它自己的字形以 `color: transparent` 渲染；用户看到的每一个字符都由其下的 `[data-input-backdrop]` 层绘制，该层同时承载 claim token 高亮、chip 与提示影子文本。这一拆分正是 chip 与高亮得以存在的前提——textarea 无法为自身文本的某个区间单独设置样式。草稿框的高度上限为 14 行，因此超过上限之后总得有东西滚动。
两层各自持有一个滚动偏移，会分两个阶段失效，本次改动是其中的第二个。
第一个阶段是静态的。backdrop 为 `position: absolute; inset: 0; overflow: hidden`——只裁剪、不滚动——浏览器也不会把它的偏移与 textarea 关联起来，于是超过上限之后光标在动而文字冻结在第 1 行。未达上限时这一点不可见，因为两层都停在 0；该缺陷与高度上限同龄，藏在所有截图所捕获的那个静止状态背后。当时的修复是用一个 `scroll` 监听把 textarea 的 `scrollTop` 镜像到 backdrop 上，这让两层在**静止时**保持一致。
第二个阶段正是随后被用户报告的现象：从长草稿的顶部快速滑到底部时，光标像带着惯性一样从自己的文字里往上飞出去，过一会儿又落回原位。原因就是那个镜像。滚轮手势在合成线程上滚动 textarea，不经过主线程；而驱动赋值的 `scroll` 事件在其后才派发，因此中间这些帧里光标位于新偏移、每一个字形却仍位于旧偏移。在同一套几何的独立环境上实测：把偏移改变 200px 并在本任务结束之前读取光标与其字形之间的距离，chromium 分离 203px、firefox 202px、WebKit 203px，一两帧之后才收敛到固定的行盒常量（3/2/3）。每个引擎、每次手势都如此，且滑动越快分离越远。
任何监听都无法消除这个间隙，因为这个间隙正是监听的定义：它在自己所响应的那件事之后才运行。凡是用 JavaScript 维持两个盒子相等的做法，都会落后于那个不经询问就搬动其中一个盒子的合成器一帧。
## 决策
只保留一个滚动盒，让它同时装下两层。
`[data-input-scroll]` 是 composer 唯一的滚动容器，14 行的高度上限落在它身上。容器内部的自增高栈与**整份**草稿等高——隐藏的镜像层处于常规流中且不再设上限，因此由它把栈撑到完整文本高度——backdrop 与 textarea 以绝对定位骑在这个高度上。textarea 为 `overflow: hidden`，自身没有可滚动溢出，也就再无法持有任何偏移。
于是浏览器在同一帧、同一个合成器上，把同一个偏移施加给两层。光标与字形的绑定来自结构本身，而不是来自持续维护：没有代码要跑，没有事件要等，也没有任何状态可能落后一帧。滚轮接力处理器保留，只是从 textarea 改挂到滚动容器上，并且仍是这个盒子上唯一的监听。
上一版机制所需要的两样东西随它一起消失：
**backdrop 的尾行哨兵。** 它的存在只是为了让两个盒子的滚动范围相等——textarea 会在末尾换行之后为光标保留一个行盒，而 `white-space: pre-wrap` 会折叠文本节点的尾随换行，因此以换行结尾的草稿会让 backdrop 少一行，把镜像偏移钳制在光标上方一行。改为单一滚动容器后，backdrop 自身的范围不再决定任何事：镜像层为两层统一定高，两层顶端对齐，内容更早结束的那一层只是在最后一行什么都不画。值得记住的是这类草稿形状而不是那套机制：正是它在「两个盒子必须就高度达成一致」的时代量出了 628 对 652。
**折行宽度这一前提。** 现在三层都在滚动容器内部解析自身宽度，因此一条占布局宽度的滚动条对它们的代价由结构保证相等。这也就关闭了被取代的那篇笔记记录为「悬置且没有任何属性能修」的分歧：WebKit 会为 `overflow-y: auto` 的 textarea 预留槽位，却不为它旁边 `overflow: hidden` 的层预留，把 textarea 排成 768 对 776——在长草稿上值 2 到 5 个折行，也就是在唯一能观察到它的那个引擎上把字形放到了错误的光标之下。改动后在独立环境实测，Playwright 自带的三个引擎上三层宽度均一致。
**由 composer 自己完成的编辑，现在会主动请求回视。** 粘贴与剪切都会抑制原生编辑——草稿与撤销日志归状态机所有——再用 `setSelectionRange` 恢复光标，而这不会带来任何回视：在 chromium 与 WebKit 上实测，粘贴一大段之后视图停在原处，光标却落在所粘内容的末尾。该缺陷早于本次改动（Firefox 只在旧几何下恰好会回视），在此修复，是因为单一滚动容器才终于让「回视」成为我们能自己做的事。两处恢复共用一个 helper：它以隐藏的镜像层为标尺——同一份草稿、同一套度量、同一折行宽度，因此在光标索引处折叠一个 Range 就能报出光标位置，无需任何 caret API——并且只滚动到刚好把该行带进可见范围为止，与浏览器为输入所做的一致。
有一种形状需要单独的规则，因为引擎之间在这里并不一致：紧跟在换行之后的光标，落在一条没有任何内容可供度量的行上——以换行结尾的草稿正是终止于此。chromium 对这个折叠位置**根本不返回任何 client rect**（一个全零盒子，会把回视带向反方向），firefox 报的是上一行，WebKit 报的才是对的那一行。因此该 helper 改为度量光标刚离开的那个换行——它的盒子就是光标来的那一行——再往下走一行；三者随即落在同一个偏移上（649/652，光标所在行位于 336px 盒内的 315）。即使草稿以连续换行结尾，覆盖该换行的非折叠 Range 在三个引擎上都会返回真实矩形，因此每个尾随空行都能沿用同一条规则定位。
现在唯一依赖浏览器而非依赖我们自己的，是把光标滚入可见范围：textarea 没有了自己的偏移，它的 scroll-into-view 必须向上走到滚动容器。实测的每个引擎都会这么做——在草稿末尾输入会把滚动容器带到光标处（chromium、firefox、WebKit 分别为 625、626、628，最大值 628），用 `ArrowUp` 把光标一路走回去会滚回去，滚离光标后再输入也会回到光标。
## 备选方案
**用 `scroll` 监听把 `scrollTop` 镜像到 backdrop 上。** 被取代的那个决策，静止时是正确的：正是它让长草稿第一次可以滚动。现在被否决，是因为它在运动中不可能正确——它是主线程对合成线程事实的响应——并且它需要两个前提持续成立（范围相等、折行宽度相等），而单一滚动容器根本不需要这两个前提，其中每一个都已经失效过一次。
**用 `transform: translateY(-scrollTop)` 平移 backdrop，而不是赋一个偏移。** 延迟相同：仍在主线程，仍由同一个事件驱动。它还会把范围分歧盖住而不是让两层真正一致，于是只要有什么东西去测量 backdrop，错配就会重新浮现。
**用滚动驱动动画（`animation-timeline: scroll()`）驱动 backdrop。** 这会把耦合放到合成器上运行，在保留两个盒子的前提下确实能消除延迟。因支持度被否决：Safari 尚未实现、Firefox 也是近期才有，因此在缺少它的引擎上 composer 会保留被报告的缺陷，而其回退路径正是这次要替换掉的机制。
**两层都由 JavaScript 驱动滚动：textarea 设 `overflow: hidden`，滚轮处理器在同一个任务里给两个偏移赋值。** 滚轮手势期间不会分离，因为没有我们就没有东西会滚动。被否决，是因为它用手写近似替换了原生滚动——惯性、触控板回弹、拖拽滚动条、键盘滚动——而且光标回视路径（浏览器设置 textarea 自己的偏移）仍然是异步落地的。
**把上限留在镜像层上，只在今天的结构外面套一个滚动容器。** 那样两层仍是「窗口大小」而非「草稿大小」：绝对定位子元素的 `inset: 0` 是相对滚动容器的 padding box 解析的，而不是相对其可滚动溢出区域，于是两层会从本该垫在它们下面的内容上滚开。栈必须与整份草稿等高，这套排布才有意义。
**给 backdrop 加 `overflow: auto`，让它自己滚动。** 那样它就有了一个自己的偏移需要保持同步，即同一个问题再加一条画在输入框上的滚动条。backdrop 是 textarea 的投影，不是一个可独立导航的界面。
**去掉 backdrop，直接给 textarea 自己的文本上样式。** 这会消除分层，也一并消除这一整类失步。被否决是因为它不可实现：textarea 只渲染一段统一的文本，claim token 高亮、chip 与提示影子文本——backdrop 存在的理由——无从表达。为修滚动而失去它们，是拿一个有界缺陷换一次功能删除。
**用 `contenteditable` div 渲染草稿。** 一个元素、一个偏移、区间可上样式。因代价与缺陷严重不成比例被否决：`contenteditable` 会把输入法组合、撤销/重做、选区语义与粘贴规范化重新压回我们身上，而这些目前都由 textarea 加输入状态机处理，且状态机已经持有一份假定 textarea 取值语义的撤销日志。
**给三层都加 `scrollbar-gutter: stable`。** 在 textarea 还是滚动者时试过并已回退：WebKit 只对 `overflow-y: auto` 生效、不对 `overflow: hidden` 生效，那 8px 的差距原样留着，却让每个 chromium 用户无条件损失 8px 文本列宽。现在已无意义——三层共享同一包含块，没有什么需要预留。
**给滚动的那一层加 `scrollbar-width: none`。** 靠隐藏滑块来抹平宽度。被否决：草稿超过上限时 composer 是有意显示滑块的——`.card` 绑定 l2 滚动条 token 正是为此——而它是唯一提示「长草稿在下面还有」的可供性。
## 影响
- 光标不可能离开自己的字形。浏览器滚动的是同一个盒子，因此「textarea 把某一行放在哪」与「backdrop 把这一行画在哪」之间的距离在任何偏移下都是一个固定的行盒常量，手势进行中也不例外。场景测试度量的正是这个数。
- 滚动条从 textarea 移到了滚动容器上——视觉位置相同，只是外移了一层。`.card` 的 l2 token 绑定仍会继承下去。
- chip、claim token 高亮与文本引用标记在滚动时仍与其字形对齐，因为它们定位在 backdrop 内部、随之移动。除去掉哨兵之外，装饰扫描没有变化。
- 在 Firefox 与 WebKit 上，点进一个草稿超过上限的 composer 现在还会把会话记录滚动到底部：光标的 scroll-into-view 会越过 composer 的滚动容器一路走到会话记录的滚动容器，而一个比自身盒子矮的 textarea 从不会引发这一步。chromium 不会。已实测，并试过 `overscroll-behavior: contain` 与 `contain: paint`，两者都拦不住这次上行——没有任何 CSS 能终止 scroll-into-view 的接力。接受：它滚向底部，而 composer 本来就在底部，而其替代方案是在每个引擎上都出现光标与文字明显分离。
- 翻页与拖拽选区的行为未变，二者均做了新旧对照实测。`PageDown`/`PageUp` 本来就不会移动 textarea 的插入点——chromium 是滚动一页并保持 `selectionStart` 不变，新旧几何皆然，区别只在于滚的是哪个盒子。拖拽选区越过下边缘仍会自动滚动，且落点一致（chromium 628/628、firefox 625/620、WebKit 170/170——WebKit 自动滚动较慢，但改动前后一样慢）。
- composer 自己发起的 `focus()` 全部加了 `preventScroll`——解锁/切会话的 effect，以及工具栏按钮上那个保持焦点的 mousedown——因此一次没有任何手势要求的聚焦，不会再通过更高的 textarea 的回视链把 transcript 挪走。抑制这条链之后，光标就回到了我们手上，而这在一条路径上确实要紧：composer 的 DOM 跨会话复用，因此切到更长的草稿时旧偏移会留着，而换值会把光标放到新草稿的末尾。三引擎实测，这会让光标落在停在 0 的盒子下方 940px 处；于是该 effect 会在自己的滚动容器里把它带回来，落点 625/628——正是旧几何靠浏览器达到的 628。mousedown 那条不需要回视：光标没动过，而下一次敲键会拿到浏览器原生的回视。另一个只负责回视的 effect 会处理渲染后才到达的非空草稿：`ConversationSession` 在自己的 mount effect 中注入持久化草稿，而该 effect 在本组件的 effect 之后运行，否则第一次回视会量到空镜像，且不会再为随后出现的草稿重跑。第二个 effect 从不聚焦，因此发送后清空或发送失败后恢复这类普通的空/非空转换不会从其他控件夺走焦点。
- 撤销/重做可以在不恢复光标、也不回视的情况下改动草稿：状态机重放上一版草稿，DOM 选区停在浏览器钳位后的位置。这早于本次改动且未被改动——在此点名，是因为另外两处恢复都会回视，会让这处遗漏看起来像有意为之；真被报告时 helper 就在旁边。
- 任何新增在 backdrop 旁边的层都属于滚动容器**内部**，并且必须与草稿等高，否则就会重新引入这一缺陷。这是 composer 长期存在的风险点：两层拆分对 chip 与高亮是承重的，因此耦合必须来自结构，而不是靠维护。
## 测试
[input-bar.spec.tsx](../../../../packages/client/ui-conversation/tests/input-bar.spec.tsx) 中的单元用例断言 jsdom 能看见的部分：同一个滚动盒同时包含 textarea 与 backdrop，backdrop 的文本现在就是草稿本身、不多不少，且渲染后才到达的持久化草稿会回视其光标，同时不从其他控件夺走焦点。jsdom 对任何元素都报告 `scrollHeight === clientHeight` 且从不滚动，因此几何属于浏览器场景；滚轮接力用例改为桩接滚动容器的度量，而非 textarea 的。
[composer-draft-scroll.e2e.ts](../../../../apps/web/tests/composer-draft-scroll.e2e.ts) 在 chromium 中针对构建产物度量其余部分：全新工作区空会话的 composer 中一份 40 行草稿，零模型调用。每个度量都在光标自己的坐标系里读取——即 textarea 把第 n 行放在哪，含其自身偏移——再与 backdrop 同一行文本上的 DOM Range 相比，因为这个差值正是用户看到的东西。决定性的用例改变偏移，并**在本任务结束之前**重新读取该差值，也就是在任何 `scroll` 监听可能运行之前：单一滚动容器下为 0，镜像方案下则是整个增量。空洞性保护先断言草稿确实超过了带上限的盒子；其余用例分别覆盖高度上限、三层同一折行宽度、滚轮手势、以换行结尾的草稿，以及过去由 textarea 自身滚动承担的光标回视路径——滚离光标后输入，必须把滚动容器带回光标处。
另有一个用例端到端覆盖粘贴路径：短草稿、光标停在末尾，然后派发一个携带真实剪贴板数据的 `paste` 事件——与 Cmd-V 送达的是同一个事件，走同一个处理器——再检查偏移与所粘内容的最后一行。它等待的是偏移而不是「草稿是否溢出」，因为恢复发生在状态机提交草稿之后的下一帧；没有这次回视的构建会卡在这个等待上失败。
支撑该决策的两套几何对比是在实现之前于独立环境度量的，因为新旧排布无法在应用里同时存在：同任务分离度旧为 203/202/203px、新为 3/2/3px（chromium/firefox/WebKit），折行宽度旧在 WebKit 上为 768 对 776、新在三个引擎上均为 1264/1264/1264，而新几何下 textarea 自身的可滚动溢出为 0——正是这一点让第二个偏移不可能存在，而不只是碰巧相等。
注意 composer 打包在 client-module bundle 内，因此只跑 `pnpm run build:web` 并不会带上 `InputBar.tsx` 的改动——必须先跑包构建，浏览器泳道才看得到；对着过期 `lib/` 跑场景，断言的是比当前代码树更旧的客户端。

6
.agents/notes/implemented/bug-fix/2026-07-27-tool-card-single-row-fields-inline.i18n.yaml → .agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
View File

@@ -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 .agents/notes/implemented/bug-fix/2026-07-27-tool-card-single-row-fields-inline.md
2026-07-27-tool-card-single-row-fields-inline.md: e04110ed74b68afffc6ea45fc2cb52c4063268e7
2026-07-27-tool-card-single-row-fields-inline.zh.md: ac532ec6eb51d42a529e0816d1204cb2729a074a
# 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

59
.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md Normal file
View File

@@ -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.

59
.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md Normal file
View File

@@ -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` 路径保留其原有断言，确认正常退出时同样会出现该重置序列。

6
.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml Normal file
View File

@@ -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-fork-anchor-floors-to-event-seq.md
2026-07-31-fork-anchor-floors-to-event-seq.md: 2cc8d66942442aca69c930be880cc41d56bced13
2026-07-31-fork-anchor-floors-to-event-seq.zh.md: 9f443f3d5165c01c6585d33bd6a37e90e9b3bf95

35
.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.md Normal file
View File

@@ -0,0 +1,35 @@
# Agent Note: Fork anchor floors to an event seq
Status: implemented
English | [中文](2026-07-31-fork-anchor-floors-to-event-seq.zh.md)
## Problem
The fork button on a stopped assistant message did nothing at all — no child session, no error, no visible reaction.
The frozen node behind that message is not a log event. Both the live projection and the history replay mint it with a flow-ordering seq of `turnEnd.seq - 0.9`, placing it strictly after every event of the aborted turn and before the next one, and the chat view hands that node seq to the fork entry point unchanged. `session.fork` accepts a non-negative integer on the wire, so a fractional anchor is rejected as invalid-params before the request reaches the host, and the chat entry's fork call swallows failures. Nothing distinguished the rejection from an inert button.
The host's cut rule was never the obstacle. An aborted turn ends with a logged `turn/end` carrying reason `aborted`, so it is a completed prefix like any other and the anchor simply never arrived.
## Decision
`SessionsService.fork` floors `atSeq` before the RPC. The fractional-seq convention belongs to `dsh-client-runtime`, which mints it in both the live and replay projections, so the same package converts it back to a real event seq at the wire boundary instead of every UI caller remembering to. Integer anchors are unaffected.
Flooring lands inside the anchor's own turn rather than clipping backward: every turn opens with `turn/start`, so `turnEnd.seq - 1` cannot itself be an earlier turn's `turn/end`. The host's first-`turn/end`-at-or-after rule then closes on the turn the reader clicked, matching the whole-turn semantics the message-level fork button already promised for completed turns.
The apiproxy fork suite pins the host half of the contract: a floored anchor inside an aborted turn cuts through that turn and seeds the child with it.
## Alternatives considered
**Accept fractional `atSeq` on the wire.** Rejected because the host contract is an event seq, not a position on a continuum; the fractional form is one client's rendering convention, and admitting it would leave `atSeq` alone among the seq-carrying payloads in taking non-integers.
**Hide the fork button on interrupted messages.** Rejected because forking a turn the reader deliberately stopped is one of the strongest reasons to fork at all, and the capability worked host-side the whole time.
**Floor in the chat entry's `forkAt` adapter.** Rejected because `ui-conversation` consumes the fractional convention without owning it; any second fork entry point would have to rediscover the same conversion.
## Consequences
Forking from a stopped turn produces a child seeded through that turn's `turn/end`. The frozen partial text is reconstructed from chunk events and was never an `assistant/message`, so it stays out of the child's model transcript exactly as it stays out of the source's on resume — the child resumes from the same context the source would.
Fork failures stay silent in the chat entry. This bug survived because that call site discards its rejection; surfacing fork errors in the UI is a separate change.

35
.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md Normal file
View File

@@ -0,0 +1,35 @@
# Agent Note: fork 锚点向下取整到事件 seq
Status: implemented
[English](2026-07-31-fork-anchor-floors-to-event-seq.md) | 中文
## 问题
在已停止的助手消息上点 fork 毫无反应——没有子会话，没有报错，也没有任何可见变化。
这条消息背后的冻结节点并不是日志事件。实时投影和历史回放都用 `turnEnd.seq - 0.9` 这个排序坐标来生成它，让它严格落在被中断轮次的所有事件之后、下一轮之前，而 chat 视图原样把这个节点 seq 交给 fork 入口。`session.fork` 在 wire 上只接受非负整数，因此分数锚点在抵达 host 之前就被判为 invalid-params，而 chat 入口的 fork 调用又吞掉了失败。于是被拒绝和按钮失灵在表现上毫无区别。
host 的切分规则从来不是障碍。被中止的轮次会记录一条 reason 为 `aborted` 的 `turn/end`，它和其他轮次一样是可切分的完整前缀——只是锚点根本没送到。
## 决策
`SessionsService.fork` 在发起 RPC 前对 `atSeq` 向下取整。分数 seq 这个约定属于 `dsh-client-runtime`，实时投影和回放投影都由它生成，因此也由同一个包在跨出 wire 边界时把它换回真实事件 seq，而不是要求每个 UI 调用方各自记得转换。整数锚点不受影响。
向下取整落在锚点自身所在的轮次内，不会回退：每一轮都以 `turn/start` 开头，所以 `turnEnd.seq - 1` 不可能是上一轮的 `turn/end`。host 随后按「首个位于锚点或其之后的 `turn/end`」收口，命中的正是读者点击的那一轮，与消息级 fork 按钮在已完成轮次上一贯承诺的整轮语义一致。
apiproxy 的 fork 用例固定了 host 这一侧的契约：落在被中止轮次内的取整锚点会切穿该轮，并把它种进子会话。
## 备选方案
**让 wire 接受分数 `atSeq`。** 否决：host 契约要的是事件 seq，而不是连续坐标上的某个位置；分数形式只是某一个客户端的渲染约定，一旦放行，`atSeq` 会成为所有携带 seq 的载荷中唯一容忍非整数的字段。
**在已中断的消息上隐藏 fork 按钮。** 否决：从读者主动叫停的那一轮分叉，恰恰是最需要 fork 的场景之一，而 host 侧这个能力一直是好的。
**在 chat 入口的 `forkAt` 适配器里取整。** 否决：`ui-conversation` 只是分数约定的消费方，并不拥有它；将来任何第二个 fork 入口都得把同样的转换重新发现一遍。
## 影响
从已停止的轮次 fork 会得到一个种子切到该轮 `turn/end` 的子会话。被冻结的残缺文本是从 chunk 事件重建出来的，从未成为 `assistant/message`，因此它不会进入子会话的模型上下文——正如源会话恢复时它也不会进入一样，子会话拿到的上下文与源会话一致。
fork 失败在 chat 入口仍然是静默的。这个 bug 能存活至今，正是因为该调用点丢弃了自己的 rejection；把 fork 错误呈现到 UI 上是另一件事。

6
.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml
View File

@@ -1,6 +0,0 @@
# 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-hero-visible-while-blank-session-opens.md
2026-07-31-hero-visible-while-blank-session-opens.md: b39963beffa403ef6fa44735aa88395a99139751
2026-07-31-hero-visible-while-blank-session-opens.zh.md: b451d7c00ec7eb8d736134e738d72e5e07fd1b04

35
.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md
View File

@@ -1,35 +0,0 @@
# Agent Note: Hero stays visible while a blank session opens
Status: implemented
English | [中文](2026-07-31-hero-visible-while-blank-session-opens.zh.md)
## Problem
The conversation root has a `settling` phase for a session that is still opening while its composer reads `blank`: the hero-versus-docked outcome is unknowable until history arrives, so the composer seat is hidden (`visibility:hidden`) rather than flashing the centered hero and snapping to the docked bar. Startup auto-selection turned that guard into the defect it was meant to prevent. From the no-workspace hero, `WorkspacesService.startInitialSelection` connects the most recent workspace and opens its blank session; `openState` flips to `loading` the moment `open()` lands, so the center column went blank for the whole history round-trip and then repainted, which reads as a full-page refresh on every launch.
## Decision
`ConversationRoot` reads the session list summary's `blank` flag alongside the conversation snapshot and exempts summary-proven blank sessions from settling: `settling` additionally requires `summaryBlank !== true`, and `hero` accepts a blank composer whenever the summary proves the session blank, in every open state rather than only `loading`. A session the list already reports as blank can only land on the hero, so hiding buys nothing and costs the visible flash; the same proof holds before the open starts (`cold`) and after one fails (`error`), where the previous conditions fell through to the active phase and rendered a docked bare composer under chrome `ConversationSession` hides for blank sessions. Whenever the summary does not prove the session blank — a row reporting `blank: false`, or no row at all because the list has not caught up — `summaryBlank` is not `true` and the conservative settling hide is unchanged.
The summary flag and the snapshot's own `blank` are distinct sources: the snapshot describes the session being opened, the summary is the list row that already exists before the open resolves. Only the latter is available early enough to decide the phase.
## Alternatives considered
**Drop the settling phase entirely.** Rejected because it still earns its keep for a session with no summary row: without a prior claim about emptiness, hero-versus-docked is genuinely unknowable and the flash it prevents is the worse one.
**Delay the `loading` flip until history returns.** Rejected because `openState` is authoritative about the open operation; deferring it to suppress a presentation artifact would misreport the data state to every other consumer.
**Cross-fade or otherwise animate the settling hide.** Rejected because the column has nothing to show during the round-trip either way — the fix is to not hide content whose outcome is already known, not to decorate the hiding.
## Deferred
The no-session→session tree relocation in `ConversationRoot` (the hero/composer subtree moves into the `conversation.session` outlet) still rebuilds the composer DOM on the same transition; removing it means moving `conversation.session` to `session-maybe` scope, a slot-contract change that needs its own proposal.
Object-layer reference churn found while diagnosing this — no-op projections minting fresh snapshots, the create path projecting twice, `select()` using `notifyNow` from async continuations — is real but independent of the visible flash.
## Consequences
Startup auto-selection renders the hero immediately and keeps the composer seat and header visible through the history round-trip, so launching into a recent workspace no longer looks like a page reload. Sessions whose summary does not prove them blank keep the previous settling behavior, so the guard still covers the case it was written for. Skeleton tests pin all three summary shapes: a row reporting `blank: false` settles, an absent row settles, and a summary-proven blank session opening under `loading` renders hero chrome with a live textarea.
The assembled coverage is `apps/web/tests/startup-auto-selection.e2e.ts` (keyless web browser lane): it registers a workspace, holds the `session.history` response open at the browser's network boundary, and asserts the visible frame while the auto-selected open is in flight — hero phase, hero title, painted composer — plus a recorded phase timeline of exactly `['hero']` for the whole load. Holding the round-trip is what makes it a regression test rather than a race: against a loopback host the open settles too fast to sample, and with the exemption reverted the held window is precisely when the root reports `settling`.

35
.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md
View File

@@ -1,35 +0,0 @@
# Agent Note: 空白会话打开期间保持 hero 可见
Status: implemented
[English](2026-07-31-hero-visible-while-blank-session-opens.md) | 中文
## 问题
会话根节点为"正在打开且 composer 处于 `blank`"的会话保留了一个 `settling` 阶段：在历史记录返回之前，hero 与 docked 的归属不可知，因此宁可隐藏 composer 座位（`visibility:hidden`），也不要先闪出居中的 hero 再跳到底部输入条。启动时的自动选择把这道防护变成了它本要防止的缺陷。从无工作区的 hero 进入时，`WorkspacesService.startInitialSelection` 会连接最近的工作区并打开其空白会话；`open()` 一落地 `openState` 立即翻为 `loading`，中间栏因此在整个历史往返期间保持空白，随后重绘一次——每次启动看起来都像整页刷新。
## 决策
`ConversationRoot` 在读取会话快照的同时读取会话列表摘要的 `blank` 标志，并让"摘要已证明为空白"的会话豁免 settling：`settling` 额外要求 `summaryBlank !== true`，而 `hero` 在摘要证明会话为空白时接受处于 blank 的 composer——覆盖全部 open state，而非仅 `loading`。列表已报告为空白的会话只可能落到 hero，因此隐藏毫无收益，只换来一次可见闪烁；同一份证明在打开开始之前（`cold`）与打开失败之后（`error`）同样成立，而此前的条件会在这两种状态下落到 active 阶段，在 `ConversationSession` 为空白会话隐藏的外壳之下渲染出一条停靠的裸 composer。只要摘要没有证明会话为空白——无论是报告 `blank: false` 的行，还是列表尚未跟上因而根本没有该行——`summaryBlank` 都不为 `true`，保守的 settling 隐藏行为保持不变。
摘要标志与快照自身的 `blank` 是两个不同来源：快照描述正在打开的这个会话，摘要则是在打开操作完成之前就已存在的列表行。只有后者足够早，可用于决定阶段。
## 备选方案
**彻底移除 settling 阶段。** 否决，因为对没有摘要行的会话它仍有价值：在缺少任何关于"是否为空"的先验断言时，hero 与 docked 的归属确实不可知，而它所防止的那种闪烁更糟糕。
**推迟 `loading` 的翻转，直到历史返回。** 否决，因为 `openState` 是打开操作的权威状态；为了压制一个呈现层瑕疵而推迟它，会向其他所有消费者误报数据状态。
**为 settling 的隐藏加交叉淡入或其他动画。** 否决，因为无论如何该栏在往返期间都没有内容可展示——正确的修复是不隐藏结局已知的内容，而不是把隐藏装饰得好看些。
## 推迟事项
`ConversationRoot` 中"无会话→有会话"的树位置迁移（hero/composer 子树移入 `conversation.session` 出口）仍会在同一次转换中重建 composer 的 DOM；消除它意味着把 `conversation.session` 移到 `session-maybe` 作用域，这是一次插槽契约变更，需要单独立项。
诊断期间发现的对象层引用抖动——空操作投影铸造出新的快照、创建路径重复投影一次、`select()` 在异步续体中使用 `notifyNow`——确实存在，但与这次可见闪烁相互独立。
## 影响
启动自动选择会立即渲染 hero，并在整个历史往返期间保持 composer 座位与 header 可见，因此启动进入最近工作区不再像页面重载。摘要未证明为空白的会话保持原有的 settling 行为，这道防护仍覆盖它当初针对的场景。骨架测试固定了摘要的三种形态：报告 `blank: false` 的行进入 settling；根本没有该行同样进入 settling；摘要已证明为空白的会话在 `loading` 期间渲染 hero 外壳与可用的文本框。
组装级覆盖是 `apps/web/tests/startup-auto-selection.e2e.ts`（无密钥的 Web 浏览器泳道）：它注册一个工作区，在浏览器网络边界上扣住 `session.history` 的响应，并在自动选择的打开仍在飞行途中断言可见画面——hero 阶段、hero 标题、已绘制的 composer——外加整次加载记录到的阶段时间线恰好为 `['hero']`。扣住这次往返正是它成为回归测试而非竞态的原因：对着回环主机，打开会快到无从采样；而一旦回退这条豁免，被扣住的这段窗口恰恰就是根节点报告 `settling` 的时刻。

6
.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml Normal file
View File

@@ -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-resume-selector-batch-projection.md
2026-07-31-resume-selector-batch-projection.md: 39146527f13b20813bb6f5d5f1349ecab5724662
2026-07-31-resume-selector-batch-projection.zh.md: 3f824a3063849306e5c1c21699f6a19eefcfefe5

35
.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md Normal file
View File

@@ -0,0 +1,35 @@
# Agent Note: Resume selector folds titles only
Status: implemented
English | [中文](2026-07-31-resume-selector-batch-projection.zh.md)
## Problem
Opening the TUI `/resume` selector called `sessionQuery.readSession()` once per listed session under an unbounded `Promise.all`. Each call re-listed the whole persistence store inside `SessionCorpus.load()` (O(N²) listings), read and decompressed the complete log, replay-validated every event through the `Session` constructor, and deep-cloned the header and events up to three times — all to derive one selector row's title, last-activity time, last `turn/end` label, provider/model route, and goal phase. On a real store (185 sessions, 87 MB compressed, ~353k events) the selector took tens of seconds to open, and the cost grew with total log size rather than session count.
## Decision
Selector rows fold nothing but titles, and everything else a row shows comes from metadata:
- Titles come from the projection system: `session-title` already registers a `title` unit, so a live row reads the registry snapshot, a persisted row reads the durable checkpoint row (`sessionProjectionCache.cachedSnapshot`, zero I/O), and only a row without a usable checkpoint pays a `coldSnapshot` — checkpoint plus a `readFrom` tail, written back so the next scan is zero-I/O. Cold reads are bounded by the TUI `resumeScanConcurrency` config. A composition without the cache falls back to one bounded `readTitleSnapshots` batch over the logs; either path isolates a per-row failure into the disabled "Unreadable session" fallback.
- The activity timestamp never reads a log: a live session uses its last in-memory event time; a persisted session stats the artifact named by the optional `sessionPersistence.locate()` (mtime), falling back to the header's creation time when the backend locates no per-session artifact (SQLite) or the stat fails. Any append moves the mtime, so a mere pickup boundary now floats a browsed session up — accepted as the price of a metadata-only timestamp.
- The last-turn label, provider/model route, and goal phase columns are gone from rows. Route availability is now enforced by the Enter-time preflight, which fully reads and replay-validates the one chosen log through `readSession` before handoff.
The selector overlay opens synchronously when `/resume` dispatches, before the scan settles: an `undefined` candidate set renders a "Loading sessions…" placeholder, the picker owns terminal input from its first frame, Enter reports that sessions are still loading, and Escape cancels. Closing the overlay aborts the scan through the `AbortSignal` the query methods accept; a signal-ignoring backend's late settlement is dropped by a staleness check. The finished scan swaps rows in through `setCandidates` (clearing a stale still-loading error) without replacing the overlay; a queued activation behind a closing predecessor receives an already-scanned set at construction; one catch spans listing, titles, and mtimes, so any scan failure closes the overlay and reports a notice rather than stranding the loading placeholder.
No session-query or session-persistence surface changed. The shipped TUI composition gains the projection registry, storage, and projection-cache rows (mirroring the web overlay over the same `storages` root, so checkpoints written by either surface serve both); the first scan over a pre-existing store still reads each log once to seed checkpoints, and every later scan is metadata-only.
## Alternatives considered
**Keep per-row route/turn/goal columns via a generic batch projection (`projectSessions`).** Implemented first, then rejected: it still decompressed and parsed every log on every `/resume`, so browsing cost stayed O(total log bytes), and it grew the session-query public API for one consumer. The public seam was reverted; `readTitleSnapshots` keeps using the internal `projectMany` unchanged.
**Fix only the O(N²) listing inside `SessionCorpus.load()`.** Rejected as the primary fix: the per-candidate full decompress, replay validation, and triple clone dominated on large logs. The redundant pre-listing in `load()` remains a candidate cleanup with error-semantics implications.
**Surface a last-modified time through `listSnapshots`/`SessionRecord`.** Cleanest seam-wise, but touches the persistence contract, both backends, and the query record shape for what the TUI can already derive from `locate()` plus one stat. Reintroduce if a second consumer needs metadata activity times.
**A bespoke persisted title index or TUI-local title cache.** Rejected: the session-projection cache already is the owned durable checkpoint system with an invalidation contract (`stateVersion`, identity binding, shrunk-log anchoring); mounting it beats adding a parallel cache.
## Consequences
Opening `/resume` performs one listing, one stat per persisted row, and per-row title reads that touch only checkpoint rows and log tails once checkpoints exist — O(session count) metadata instead of O(total log bytes); the fallback path without the cache remains one bounded title pass. Rows show title, timestamp, status, and id only; route problems surface as an Enter-time preflight error instead of a disabled row, and a session that fails replay is caught by preflight rather than the listing. Browsed-then-abandoned sessions float up on their pickup mtime. Fake `sessionQuery` services in TUI tests provide `readTitleSnapshots` alongside `listSessions`/`readSession`, and the test harness forwards an optional `locate`. Because the picker takes focus immediately, starting a second scan requires dismissing the current overlay first — a second `/resume` typed during a scan lands in the search field, which is the intended input capture.

35
.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md Normal file
View File

@@ -0,0 +1,35 @@
# Agent Note: 恢复选择器只折叠标题
Status: implemented
[English](2026-07-31-resume-selector-batch-projection.md) | 中文
## Problem
打开 TUI `/resume` 选择器时，会在一个无界 `Promise.all` 中对每个列出的会话调用一次 `sessionQuery.readSession()`。每次调用都会在 `SessionCorpus.load()` 内部重新列出整个持久化存储（O(N²) 次列表查询）、读取并解压完整日志、通过 `Session` 构造函数对每个事件做回放验证，并将 header 和事件深克隆多达三次——而这一切只为推导一行选择器条目的标题、最近活动时间、最后一个 `turn/end` 标签、提供方/模型路由和目标阶段。在真实存储上（185 个会话、压缩后 87 MB、约 35.3 万个事件），选择器需要数十秒才能打开，且开销随日志总大小而非会话数量增长。
## Decision
选择器行除标题外不折叠任何内容，行内其余信息全部来自元数据：
- 标题来自投影系统：`session-title` 已注册 `title` 投影单元，因此实时行读取注册表快照，持久化行读取持久 checkpoint 行（`sessionProjectionCache.cachedSnapshot`，零 I/O），只有没有可用 checkpoint 的行才付出一次 `coldSnapshot`——checkpoint 加 `readFrom` 尾部折叠，并写回使下次扫描零 I/O。冷读取受 TUI `resumeScanConcurrency` 配置约束。未挂载缓存的组合回退到一次对日志的有界 `readTitleSnapshots` 批量读取；两条路径都把单行失败隔离为禁用的"Unreadable session"回退。
- 活动时间戳从不读取日志：实时会话取内存中最后一个事件的时间；持久化会话对可选 `sessionPersistence.locate()` 命名的产物做 stat（mtime），当后端定位不到按会话的产物（SQLite）或 stat 失败时回退到 header 的创建时间。任何追加都会移动 mtime，因此仅仅一次 pickup 边界也会让浏览过的会话上浮——这是元数据时间戳的代价，予以接受。
- 行内不再有最后轮次标签、提供方/模型路由和目标阶段列。路由可用性改由 Enter 时的预检强制：预检通过 `readSession` 完整读取并回放验证选中的那一份日志后才移交。
选择器 overlay 在 `/resume` 分发时同步打开，早于扫描结算：`undefined` 候选集渲染"Loading sessions…"加载占位符，选择器从第一帧起就拥有终端输入，Enter 提示会话仍在加载，Escape 取消。关闭 overlay 会通过查询方法接受的 `AbortSignal` 中止扫描；忽略信号的后端的迟到结算由过期检查丢弃。扫描完成后通过 `setCandidates`（同时清除过期的仍在加载错误）换入行数据，不替换 overlay；排在正在关闭的前任之后的排队激活会在构造时直接收到已扫描的集合；列表查询、标题与 mtime 共用同一个 catch，因此任何扫描失败都会关闭 overlay 并报告通知，而不会让加载占位符悬置。
session-query 与 session-persistence 的任何表面都未改变。随附的 TUI 组合新增投影注册表、storage 与投影缓存行（镜像 web overlay，共用同一 `storages` 根，因此任一表面写下的 checkpoint 都服务两者）；对既有存储的首次扫描仍会各读取一次日志以播种 checkpoint，之后的每次扫描都只读元数据。
## Alternatives considered
**通过通用批量投影（`projectSessions`）保留每行的路由/轮次/目标列。** 先实现后否决：它仍在每次 `/resume` 时解压并解析全部日志，浏览开销依旧是 O(日志总字节数)，且为单一消费者扩大了 session-query 公开 API。该公开 seam 已回退；`readTitleSnapshots` 继续使用内部 `projectMany`，保持不变。
**只修复 `SessionCorpus.load()` 内部的 O(N²) 列表查询。** 作为主要修复被否决：在大日志上，按候选行执行的完整解压、回放验证和三重克隆才是主要开销。`load()` 中的冗余预列表查询仍是一个候选清理项，但涉及错误语义。
**通过 `listSnapshots`/`SessionRecord` 暴露最后修改时间。** 从 seam 角度最干净，但要触碰持久化契约、两个后端和查询记录形状，而 TUI 已能用 `locate()` 加一次 stat 得到同样的信息。若出现第二个需要元数据活动时间的消费者再引入。
**专门的持久化标题索引或 TUI 本地标题缓存。** 否决：session-projection 缓存本身就是自有的持久 checkpoint 系统，并已带失效契约（`stateVersion`、身份绑定、日志收缩锚定）；挂载它优于再造一套并行缓存。
## Consequences
打开 `/resume` 只执行一次列表查询、每个持久化行一次 stat，标题读取在 checkpoint 就绪后只触碰 checkpoint 行和日志尾部——O(会话数) 的元数据开销，而非 O(日志总字节数)；无缓存的回退路径仍是一次有界标题扫描。行内只显示标题、时间戳、状态和 id；路由问题以 Enter 时预检错误的形式出现，而不再是禁用行；回放会失败的会话由预检而非列表阶段拦截。浏览后放弃的会话会因 pickup 的 mtime 上浮。TUI 测试中的伪造 `sessionQuery` 服务在 `listSessions`/`readSession` 之外提供 `readTitleSnapshots`，测试 harness 会转发可选的 `locate`。由于选择器立即接管焦点，启动第二次扫描需要先关闭当前 overlay——扫描期间输入的第二个 `/resume` 会落入搜索字段，这正是预期的输入捕获行为。

6
.agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.i18n.yaml → .agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
View File

@@ -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 .agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.md
2026-07-28-web-conversation-polish-sweep.md: cae52217d66017509c025a5d8d37b1e1e8173c6a
2026-07-28-web-conversation-polish-sweep.zh.md: d19a5f75937e9ae9f553b2c941594db118fa434e
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.md
2026-07-31-web-stop-preserves-queue.md: b8bba45009c126495a8b03ee36d6eb2cccac9a93
2026-07-31-web-stop-preserves-queue.zh.md: 0e1fffae8819bea81b91fae10c76dbadc78474fe

37
.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.md Normal file
View File

@@ -0,0 +1,37 @@
# Agent Note: Web stop preserves pending Queue
Status: implemented
English | [中文](2026-07-31-web-stop-preserves-queue.zh.md)
## Problem
The Web stop button reached `session.cancel`, which mapped to broad `agent.cancel({ kind: 'user' })`. During an active turn, ordinary composer submissions are already accepted as independently addressable Queue occurrences. Broad cancellation discarded every occurrence when the user intended to stop only the current generation, conflating turn interruption with the Queue's explicit delete operation.
The browser cannot repair that loss by resending visible rows. It does not own their live `InboxItemId`, wake policy, or claim race, and a resend can duplicate work that the Host has already claimed.
## Decision
`session.cancel` is the Web Host API's active-turn stop for ordinary sessions. It rejects session-backed subagents with `agent-busy`; otherwise it calls `agent.cancel({ kind: 'user' }, { keepInbox: true })`, preserving pending inbox work while cooperatively aborting the current turn. The underlying option preserves queued and steering entries; the Web Queue projection continues to expose only queued entries.
The AgentLoop starts no concurrent replacement turn. It closes and flushes the interrupted turn, reaches cancellation quiescence, and then claims the next waking queued occurrence through its existing FIFO driver. That claim emits `agent/inbox/dequeue`, so the Host's authoritative `session/queue` snapshot retires the claimed row and leaves the remaining tail visible. The browser neither resends nor promotes any row. Work that ignores cancellation delays this handoff until it settles.
This mapping changes only the Host `session.cancel` endpoint used by Web clients. The default `Agent.cancel()` contract remains broad, ACP and TUI retain their existing cancellation policies, and `AgentHandle.dispose()` still clears pending work during teardown. Queue row removal remains the explicit Web action for discarding one pending occurrence.
## Alternatives considered
**Keep broad cancellation for the stop button.** Rejected because stopping one generation should not destroy independently queued user intent; the Queue already owns explicit deletion.
**Resend the next row from the browser after cancellation.** Rejected because the Host owns occurrence identity and claim order. Client resubmission can duplicate work, reorder the FIFO, or race an authoritative dequeue.
**Start the next turn before cancelled work reaches quiescence.** Rejected because two turns would concurrently mutate one session log and share Agent-owned resources. Cooperative cancellation waits truthfully for the active work to settle.
**Add a wire option for broad versus preserving cancellation.** Rejected until the Web product has a separate “stop and clear Queue” interaction. The existing stop button has one policy, while per-row delete already supplies the current discard control.
## Verification
AgentLoop coverage holds an active model stream, queues two waking turns, cancels with `keepInbox`, and pins the aborted-then-completed turn reasons, FIFO user-message order, absence of discard events, and eventual idle state. The keyless Web scenario drives the built composition over HTTP/SSE: it stops one hung turn, observes the next queued occurrence start while the tail remains visible, stops that turn, and observes the final queued occurrence complete. Its accessibility snapshot pins the intermediate preserved-Queue state.
## Consequences
Web stop preserves accepted queued intent and advances it automatically after truthful cancellation settlement. Queue rows may remain visible while uncooperative active work winds down, and external steering preserved by the same inbox option can enter the next admitted turn even though Web does not render steering in QueueDock. A future bulk-clear interaction requires an explicit product action rather than overloading stop.

37
.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md Normal file
View File

@@ -0,0 +1,37 @@
# Agent Note: Web 停止操作保留待处理 Queue
Status: implemented
[English](2026-07-31-web-stop-preserves-queue.md) | 中文
## 问题
Web 停止按钮调用 `session.cancel`，后者映射到广义 `agent.cancel({ kind: 'user' })`。在活动轮次期间，普通 composer 提交已经被接纳为可独立寻址的 Queue 入队项。用户只想停止当前生成时，广义取消却会丢弃所有入队项，混淆了轮次中断与 Queue 的显式删除操作。
浏览器无法通过重发可见行修复这一损失。它不拥有这些行的实时 `InboxItemId`、唤醒策略或认领竞态；重发还可能重复 Host 已认领的工作。
## 决策
`session.cancel` 是 Web Host API 面向普通会话的活动轮次停止操作。它会以 `agent-busy` 拒绝由会话支撑的 subagent；否则会调用 `agent.cancel({ kind: 'user' }, { keepInbox: true })`，在协作式中止当前轮次的同时保留待处理 inbox 工作。底层选项会保留 queued 和 steering 入队项；Web Queue 投影继续只暴露 queued 入队项。
AgentLoop 不会启动并发的替代轮次。它会关闭并 flush 被中断的轮次，达到取消的完全停稳，然后通过现有 FIFO 驱动器认领下一个可唤醒的 queued 入队项。该认领会发出 `agent/inbox/dequeue`，因此 Host 的权威 `session/queue` 快照会退役已认领行，并使剩余队尾保持可见。浏览器既不重发，也不提升任何行。忽略取消的工作会延迟这一交接，直到该工作结算。
该映射只更改 Web 客户端使用的 Host `session.cancel` 端点。`Agent.cancel()` 默认契约仍为广义取消，ACP 和 TUI 保留既有取消策略，`AgentHandle.dispose()` 在拆卸期间仍会清除待处理工作。移除 Queue 行仍是用于丢弃单个待处理入队项的显式 Web 操作。
## 考虑过的替代方案
**停止按钮继续使用广义取消。** 之所以否决：停止一次生成不应销毁已独立排队的用户意图；Queue 已拥有显式删除操作。
**取消后由浏览器重发下一行。** 之所以否决：Host 拥有入队项标识和认领顺序。客户端重新提交可能重复工作、重排 FIFO，或与权威出队产生竞态。
**被取消工作达到完全停稳之前启动下一轮次。** 之所以否决：两个轮次会并发修改同一会话日志，并共享 Agent 拥有的资源。协作式取消会如实等待活动工作结算。
**为广义取消与保留式取消添加协议选项。** 之所以否决：在 Web 产品提供独立的「停止并清空 Queue」交互之前，不需要此选项。现有停止按钮只有一项策略，而逐行删除已提供当前的丢弃控件。
## 验证
AgentLoop 覆盖会保持一个活动模型流，将两个可唤醒轮次排队，使用 `keepInbox` 取消，并固定验证先中止、后完成的轮次原因，FIFO 用户消息顺序，不存在 discard 事件，以及最终空闲状态。无密钥 Web 场景通过 HTTP／SSE 驱动已组装组合：它停止一个卡住的轮次，观察队尾保持可见时下一个 queued 入队项开始，再停止该轮次，并观察最后一个 queued 入队项完成。其可访问性快照固定了中间的 Queue 保留状态。
## 后果
Web 停止会保留已接纳的排队意图，并在取消如实结算后自动推进。不配合取消的活动工作收尾时，Queue 行可能仍保持可见；由同一 inbox 选项保留的外部 steering 可以进入下一个已接纳轮次，尽管 Web 不会在 QueueDock 中渲染 steering。未来的批量清空交互需要显式的产品操作，而不是过载停止。

6
.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml Normal file
View File

@@ -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-goal-round-wrapup-message.md
2026-08-02-goal-round-wrapup-message.md: c6bc3d5912b0789efde55880c2be892e98e34a5b
2026-08-02-goal-round-wrapup-message.zh.md: 0a504b4dcc61feb932775b3d9ffd8424f3b0597d

Some files were not shown because too many files have changed in this diff Show More