Merge current subagent naming stack into Team session UI

2026-10-25 15:45:40 +08:00
commit 80f70969d9
@@ -9,8 +9,8 @@
  en: c8b932b02a4e1c80
  zh: 96c466be1a521f3f
 /agent-note-web-capability-seam-stable-tools-over-multiple-providers/decision:
-  en: b57eb0f268033ff1
-  zh: 4143382a50181414
+  en: 2e08d801099cbe18
+  zh: 8c5ab162ada9cc41
 /agent-note-web-capability-seam-stable-tools-over-multiple-providers/package-topology:
  en: 5ea3ddfae82df181
  zh: 2d05d95e51081696
@@ -32,7 +32,7 @@ Search and fetch are separate tools but one web-access seam. `ctx.web` owns prov
 - A tool is never unregistered merely because its selected provider is missing, misconfigured, missing credentials, ambiguous, or temporarily unavailable.
 - The provider is resolved at execution time, and a structured `WebError` is returned when the selected capability cannot run.

-This keeps the model schema stable without making plugin load order, credential state, or HMR timing part of the model-facing contract. If web search is enabled but no usable search provider exists, `web_search` remains visible and execution fails with a structured `WebError` such as `WEB_PROVIDER_UNAVAILABLE` or `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`. If a provider appears after `dsh-tool-web`, the next execution can use it without changing the schema. If a provider disappears mid-call, execution fails with a structured `WebError` instead of silently choosing another provider or falling through to `UNKNOWN_TOOL`.
+This keeps the model schema stable without making plugin load order, credential state, or HMR timing part of the model-facing contract. If web search is enabled but no usable search provider exists, `web_search` remains visible and execution fails with a structured `WebError` such as `WEB_PROVIDER_UNAVAILABLE` or `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`. `dsh-tool-web` narrows this per model request: it [withholds `web_search` while the selected provider reports that the request's search cannot authenticate](2026-09-27-web-search-offered-by-provider-readiness.md). If a provider appears after `dsh-tool-web`, the next execution can use it without changing the schema. If a provider disappears mid-call, execution fails with a structured `WebError` instead of silently choosing another provider or falling through to `UNKNOWN_TOOL`.

 The seam deliberately exposes no observation surface — no registry-change event and no aggregated capability-status query. Unavailability is a fact a caller observes by executing: `search()`/`fetch()` resolve the provider at call time and throw the structured `WebError` that names what failed. [The observation-surface Agent Note](../../archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md) records that judgment: derived-on-call selection and enablement-based registration leave no consumer that needs a change signal or an availability probe distinct from executing and routing the error, and a future provider-status panel reintroduces the smallest signal or query it actually consumes.

@@ -32,7 +32,7 @@ Web 访问是一个一等能力 seam，遵循[能力 seam Agent Note](2026-06-13
 - 工具绝不会仅仅因为其选定的提供方缺失、配置错误、缺少凭证、存在歧义或暂时不可用就被注销。
 - 提供方在执行时解析，当选定的能力无法运行时返回结构化的 `WebError`。

-这使模型 schema 保持稳定，而不将插件加载顺序、凭证状态或 HMR（热模块替换）时序纳入面向模型的约定。如果 web 搜索已启用但不存在可用的搜索提供方，`web_search` 仍然可见，执行时以结构化的 `WebError`（如 `WEB_PROVIDER_UNAVAILABLE` 或 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`）失败。如果某个提供方在 `dsh-tool-web` 之后出现，下一次执行即可使用它而无需更改 schema。如果某个提供方在调用过程中消失，执行以结构化的 `WebError` 失败，而不是静默选择另一个提供方或回退到 `UNKNOWN_TOOL`。
+这使模型 schema 保持稳定，而不将插件加载顺序、凭证状态或 HMR（热模块替换）时序纳入面向模型的约定。如果 web 搜索已启用但不存在可用的搜索提供方，`web_search` 仍然可见，执行时以结构化的 `WebError`（如 `WEB_PROVIDER_UNAVAILABLE` 或 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`）失败。发行版的 `dsh-tool-web` 按模型请求收窄了这一点：选中的提供方报告该请求的搜索无法鉴权时，它会[撤下 `web_search`](2026-09-27-web-search-offered-by-provider-readiness.zh.md)。如果某个提供方在 `dsh-tool-web` 之后出现，下一次执行即可使用它而无需更改 schema。如果某个提供方在调用过程中消失，执行以结构化的 `WebError` 失败，而不是静默选择另一个提供方或回退到 `UNKNOWN_TOOL`。

 该 seam 刻意不暴露任何观察面——没有注册表变更事件，也没有聚合的能力状态查询。不可用性是调用方通过执行观察到的事实：`search()`/`fetch()` 在调用时解析提供方，并抛出命名了失败原因的结构化 `WebError`。[观察面 Agent Note](../../archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md) 记录了这一判断：基于调用的派生选择与基于启用的注册使得没有消费方需要变更信号或独立于执行和错误路由的可用性探测；未来的提供方状态面板会重新引入它实际消费的最小信号或查询。

@@ -21,8 +21,8 @@
  en: 985e0eb63f3d1fd6
  zh: 337cc44fadc6227e
 /agent-note-single-file-executable-sdk-runtime-distribution-single-exe/decision/build-pipeline-and-artifacts:
-  en: 9d885e8d58bc8bbb
-  zh: 41a9779fbdea8a1a
+  en: 9a4ba22142a7be24
+  zh: 8553b02a923641a3
 /agent-note-single-file-executable-sdk-runtime-distribution-single-exe/decision/python-sdk-distribution-two-carriers-exe-for-production-node-for-development:
  en: b2a740a1ab7a5002
  zh: a48be6ca6fc65912
@@ -48,7 +48,7 @@ The [Office kit](2026-09-14-independent-libreoffice-kit.md) and its installed de

 ### Build pipeline and artifacts

-[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.allow-unused-patches=true --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true --config.hoist-workspace-packages=false` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`, including [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) as the carrier-root `runtime-bootstrap.mjs` → restore direct workspace packages omitted by legacy deploy and reject any remaining manifest gap → replace staged dependency symlinks with their target bytes, remove package-manager `.bin` links, and fail if any symlink remains → verify the deployed bootstrap and inject pkg configuration with that bin plus assets covering dynamic profile, bundle, frontend, preset, native-library, and configuration reads → stage the target `node-pty` addon → invoke `pkg --sea --compress Brotli` once per target → write `deepseek-harness-sdk-runtime-<platform>-<arch>` under `dist-exe/` and copy it with its lightweight resource manifest and Office skill assets into the runtime directory. The Python runtime owns that bootstrap. It calls the public CLI export for ordinary launches and dispatches a provider-private selection to the same `@deepseek-ai/dsh-subprocess-local/runner` core without changing CLI grammar or adding another executable; the [native-containment reference](../../../../packages/subprocess/subprocess-local/README.md) owns that private path. Linux CI rebuilds `pty.node` inside the matching manylinux 2.28 container because legacy deploy omits that install side effect. Every target copies its native `@vscode/ripgrep` binary beside the executable as the required `-rg` sidecar; pkg runtimes select that sidecar through `process.pkg`, while ordinary Node execution uses `@vscode/ripgrep` directly. macOS uses its target prebuild and also emits the required `-spawn-helper`. The deploy flags preserve the measured runtime layout: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted supplies package directories that staging makes symlink-free; staging removes nested workspace copies only when pnpm records the same dependency identity at the payload root, preserving singleton services; disabling workspace hoisting excludes unrelated workspace source packages; disabling automatic peer installation prevents undeclared peers from expanding the closure; link-workspace-packages selects direct workspace dependencies. [`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) overrides the transitive `@deepseek-ai/cosmokit` and `@deepseek-ai/schemastery` semver requests to the pinned vendor sources so legacy deploy never resolves those unpublished names from a registry. Production deployment permits unused workspace patches because development-only tools can be absent from its closure; included-package patch failures still fail deployment. Workspace installs retain strict unused-patch validation.
+[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.allow-unused-patches=true --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true --config.hoist-workspace-packages=false` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`, including [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) as the carrier-root `runtime-bootstrap.mjs` → restore direct workspace packages omitted by legacy deploy and reject any remaining manifest gap → replace staged dependency symlinks with their target bytes, remove package-manager `.bin` links, and fail if any symlink remains → verify the deployed bootstrap and inject pkg configuration with that bin plus assets covering dynamic profile, bundle, frontend, preset, native-library, and configuration reads → stage the target `node-pty` addon → invoke `pkg --sea --compress Brotli` once per target, where the vendored pkg patch pins Brotli's quality to 6: pkg passes no options, so its default quality 11 measured 132.8 s against 3.2 s at quality 6 for an archive 12% larger → write `deepseek-harness-sdk-runtime-<platform>-<arch>` under `dist-exe/` and copy it with its lightweight resource manifest and Office skill assets into the runtime directory. The Python runtime owns that bootstrap. It calls the public CLI export for ordinary launches and dispatches a provider-private selection to the same `@deepseek-ai/dsh-subprocess-local/runner` core without changing CLI grammar or adding another executable; the [native-containment reference](../../../../packages/subprocess/subprocess-local/README.md) owns that private path. Linux CI rebuilds `pty.node` inside the matching manylinux 2.28 container because legacy deploy omits that install side effect. Every target copies its native `@vscode/ripgrep` binary beside the executable as the required `-rg` sidecar; pkg runtimes select that sidecar through `process.pkg`, while ordinary Node execution uses `@vscode/ripgrep` directly. macOS uses its target prebuild and also emits the required `-spawn-helper`. The deploy flags preserve the measured runtime layout: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted supplies package directories that staging makes symlink-free; staging removes nested workspace copies only when pnpm records the same dependency identity at the payload root, preserving singleton services; disabling workspace hoisting excludes unrelated workspace source packages; disabling automatic peer installation prevents undeclared peers from expanding the closure; link-workspace-packages selects direct workspace dependencies. [`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) overrides the transitive `@deepseek-ai/cosmokit` and `@deepseek-ai/schemastery` semver requests to the pinned vendor sources so legacy deploy never resolves those unpublished names from a registry. Production deployment permits unused workspace patches because development-only tools can be absent from its closure; included-package patch failures still fail deployment. Workspace installs retain strict unused-patch validation.

 CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml) runs [installed-wheel validation](../testing/2026-08-23-installed-python-wheel-black-box-ci.md) on Linux/Windows x64 for pull requests and Linux ARM64 plus both macOS architectures for master pushes. The [public publication workflow](../../archived/process/2026-08-11-python-publication-workflow.md) calls it for all five targets; `workflow_dispatch` can still select a subset. Native builds run on linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64 / macos-x64 (`macos-15-intel`) / win-x64 (`windows-2025`), with `~/.pkg-cache` cached where applicable, and pkg handles macOS ad-hoc signing. Each leg installs the release-shaped SDK and runtime wheels into a clean venv outside the checkout, verifies their package and executable origin, then drives the complete keyless scenario set through the public SDK and direct NDJSON JSON-RPC. Trusted pull requests and master pushes additionally run a real DeepSeek two-turn tool smoke on their selected targets; fork and Dependabot heads receive no key. Linux inspects the executable and native addon's GLIBC requirements and runs an additional manylinux 2.28 smoke, while macOS checks the runtime, ripgrep, and PTY helper architectures and verifies that all three deployment targets fit the wheel tag. A full five-target run retains six artifacts, each containing one release file: the platform-independent SDK wheel and five native runtime wheels; a subset dispatch retains the SDK wheel and selected runtime wheels. Bare executables and source bundles remain intermediate test inputs. [`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) accepts `python-v<repository-version>` tag pipelines whose version matches the root `package.json`, builds one SDK wheel and five native runtime wheels, then a single serialized job checks and publishes all six to the project PyPI registry. The [`python/sdk-runtime` README](../../../../python/sdk-runtime/README.md) owns the Windows target and the explicit exclusion of Windows arm64.

@@ -48,7 +48,7 @@ exe 的 VFS 内是**构建产物形态的真实包树**（各包的 `lib/` + 真

 ### 构建流水线与产物

-[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：运行时闭包校验 → `pnpm run build` →（清空后）`pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.allow-unused-patches=true --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true --config.hoist-workspace-packages=false` **直接写入** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`，其中包含作为载体根目录 `runtime-bootstrap.mjs` 的 [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) → 恢复 legacy deploy 遗漏的直接工作区包，并拒绝剩余的 manifest 缺口 → 将暂存依赖中的符号链接替换为目标文件内容，删除包管理器的 `.bin` 链接，并在仍有任何符号链接时失败 → 验证已部署的 bootstrap，并注入以该文件为 bin 的 pkg 配置及覆盖动态读取 profile、bundle、前端、preset、原生库与配置文件的 assets → 暂存目标平台的 `node-pty` addon → 每个构建目标调用一次 `pkg --sea --compress Brotli` → 将 `deepseek-harness-sdk-runtime-<platform>-<arch>` 写入 `dist-exe/`，并将它与轻量资源清单及 Office skill 资源一同拷回运行时目录。该 bootstrap 由 Python runtime 拥有；普通启动时它调用公开 CLI export，而提供方私有选择会分派到同一个 `@deepseek-ai/dsh-subprocess-local/runner` 核心，不改变 CLI 语法，也不增加另一个可执行文件；[原生 containment 参考](../../../../packages/subprocess/subprocess-local/README.zh.md)负责这条私有路径。Linux CI 会在匹配的 manylinux 2.28 容器中重新构建 `pty.node`，因为 legacy deploy 会遗漏这一安装副作用。每个目标都会把对应的原生 `@vscode/ripgrep` 二进制复制到可执行文件旁，作为必需的 `-rg` 伴随文件；pkg 运行时通过 `process.pkg` 选择该伴随文件，普通 Node 执行则直接使用 `@vscode/ripgrep`。macOS 使用对应目标的预构建产物，并额外生成所需的 `-spawn-helper`。部署标志都有实测依据：未启用 `inject-workspace-packages` 时必须使用 `--legacy`；`hoisted` 提供包目录，再由暂存步骤消除符号链接；只有 pnpm 在载荷根目录记录了相同依赖标识时，暂存步骤才删除对应的嵌套工作区副本，以保留服务单例；关闭工作区提升可排除无关的工作区源码包；关闭对等依赖自动安装可防止未声明的对等依赖扩大闭包；`link-workspace-packages` 选择直接工作区依赖。[`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) 将传递的 `@deepseek-ai/cosmokit` 与 `@deepseek-ai/schemastery` semver 请求覆盖到固定的 vendor 源码，使 legacy deploy 不会从注册表解析这些未发布名称。 生产部署允许未使用的工作区补丁，因为开发工具可能不属于运行时闭包；闭包内包的补丁应用失败仍会中止部署。工作区安装继续严格校验未使用的补丁。
+[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：运行时闭包校验 → `pnpm run build` →（清空后）`pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.allow-unused-patches=true --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true --config.hoist-workspace-packages=false` **直接写入** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`，其中包含作为载体根目录 `runtime-bootstrap.mjs` 的 [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) → 恢复 legacy deploy 遗漏的直接工作区包，并拒绝剩余的 manifest 缺口 → 将暂存依赖中的符号链接替换为目标文件内容，删除包管理器的 `.bin` 链接，并在仍有任何符号链接时失败 → 验证已部署的 bootstrap，并注入以该文件为 bin 的 pkg 配置及覆盖动态读取 profile、bundle、前端、preset、原生库与配置文件的 assets → 暂存目标平台的 `node-pty` addon → 每个构建目标调用一次 `pkg --sea --compress Brotli`，其中 vendor 的 pkg 补丁把 Brotli 质量固定为 6：pkg 不传参数时默认质量 11，同一载荷实测 132.8 s，质量 6 为 3.2 s，产物大 12% → 将 `deepseek-harness-sdk-runtime-<platform>-<arch>` 写入 `dist-exe/`，并将它与轻量资源清单及 Office skill 资源一同拷回运行时目录。该 bootstrap 由 Python runtime 拥有；普通启动时它调用公开 CLI export，而提供方私有选择会分派到同一个 `@deepseek-ai/dsh-subprocess-local/runner` 核心，不改变 CLI 语法，也不增加另一个可执行文件；[原生 containment 参考](../../../../packages/subprocess/subprocess-local/README.zh.md)负责这条私有路径。Linux CI 会在匹配的 manylinux 2.28 容器中重新构建 `pty.node`，因为 legacy deploy 会遗漏这一安装副作用。每个目标都会把对应的原生 `@vscode/ripgrep` 二进制复制到可执行文件旁，作为必需的 `-rg` 伴随文件；pkg 运行时通过 `process.pkg` 选择该伴随文件，普通 Node 执行则直接使用 `@vscode/ripgrep`。macOS 使用对应目标的预构建产物，并额外生成所需的 `-spawn-helper`。部署标志都有实测依据：未启用 `inject-workspace-packages` 时必须使用 `--legacy`；`hoisted` 提供包目录，再由暂存步骤消除符号链接；只有 pnpm 在载荷根目录记录了相同依赖标识时，暂存步骤才删除对应的嵌套工作区副本，以保留服务单例；关闭工作区提升可排除无关的工作区源码包；关闭对等依赖自动安装可防止未声明的对等依赖扩大闭包；`link-workspace-packages` 选择直接工作区依赖。[`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) 将传递的 `@deepseek-ai/cosmokit` 与 `@deepseek-ai/schemastery` semver 请求覆盖到固定的 vendor 源码，使 legacy deploy 不会从注册表解析这些未发布名称。 生产部署允许未使用的工作区补丁，因为开发工具可能不属于运行时闭包；闭包内包的补丁应用失败仍会中止部署。工作区安装继续严格校验未使用的补丁。

 CI 使用 [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml)：[安装后 wheel 包验证](../testing/2026-08-23-installed-python-wheel-black-box-ci.zh.md)在拉取请求上运行 Linux/Windows x64，在 master 推送上运行 Linux ARM64 与两种 macOS 架构。[公开发布工作流](../../archived/process/2026-08-11-python-publication-workflow.md)调用它构建全部五个目标；`workflow_dispatch` 仍可选择部分目标。linux-x64、linux-arm64（`ubuntu-24.04-arm`）、macos-arm64、macos-x64（`macos-15-intel`）与 win-x64（`windows-2025`）分别进行原生构建，并在适用平台缓存 `~/.pkg-cache`；macOS 的 ad-hoc 签名由 pkg 处理。每个平台都把发布形态的 SDK wheel 包与运行时 wheel 包安装到 checkout 外的干净 venv，证明包与可执行文件来源，再通过公开 SDK 与直接 NDJSON JSON-RPC 运行完整 keyless 场景。可信拉取请求与 master 推送还会在各自选定的目标上运行真实 DeepSeek 双轮工具冒烟测试；fork 与 Dependabot head 不会获得密钥。Linux 会检查可执行文件和原生 addon 各自的 GLIBC 依赖，并额外运行 manylinux 2.28 冒烟测试；macOS 则检查 runtime、ripgrep 与 PTY helper 的架构，并验证三个载荷的部署目标都符合 wheel 包标签。完整构建五个目标时保留 6 个产物，每个产物只含一个发布文件：平台无关的 SDK wheel 包与 5 个原生运行时 wheel 包；手动选择部分目标时保留 SDK wheel 与所选运行时 wheel。裸 exe 与源码包只作为测试中间输入。[`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) 只接受版本与根目录 `package.json` 匹配的 `python-v<repository-version>` 标签流水线，构建一个 SDK wheel 包和 5 个原生运行时 wheel 包，再由单个串行任务校验并将这 6 个文件发布到项目的 PyPI 注册表。[`python/sdk-runtime` README](../../../../python/sdk-runtime/README.zh.md)负责 Windows 目标及对 Windows arm64 的明确排除。

@@ -24,8 +24,8 @@
  en: 26e4b71366bebd1b
  zh: 10598e12b28c586e
 /agent-note-cooperative-tool-cancellation-at-the-registry-boundary/verification:
-  en: fbd101d4576afa92
-  zh: 35f5d3c2f6cad6a8
+  en: 983da6d0c09f5c10
+  zh: ca7c86117a1a4d5f
 /agent-note-cooperative-tool-cancellation-at-the-registry-boundary/alternatives-considered:
  en: c4d86feb135d2ac4
  zh: 67c56c0bc2213949
@@ -46,7 +46,7 @@ This decision requires cancellation at the tool invocation boundary only. Making

 ## Verification

-[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) proves the required exact signal types, readonly observer and tool views, mutable-but-required around-dispatch view, and `defineTool()` inference. [`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) covers pre-aborted materialization, phase skipping, policy and wrapper races, body invocation classification, caller-signal fusion, error precedence, context retention, and quiescent drainage. [`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) and [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) cover balanced durable results for undispatched siblings. [`ptc.spec.ts`](../../../../packages/core/tools/tests/ptc.spec.ts) and first-party integration suites cover explicit forwarding, while [`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) preserves timeout ownership.
+[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) proves the required exact signal types, readonly observer and tool views, mutable-but-required around-dispatch view, and `defineTool()` inference. [`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) covers pre-aborted materialization, phase skipping, policy and wrapper races, body invocation classification, caller-signal fusion, error precedence, context retention, and quiescent drainage. [`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) and [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) cover balanced durable results for undispatched siblings. [`ptc.spec.ts`](../../../../packages/core/tool-executor-ptc/tests/ptc.spec.ts) and first-party integration suites cover explicit forwarding, while [`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) preserves timeout ownership.

 No registry test can prove that arbitrary third-party same-process code observes the signal or stops in bounded time. Capability tests continue to prove cancellation and quiescence at the boundary that owns each side effect.

@@ -46,7 +46,7 @@ Status: implemented

 ## 验证

-[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) 证明必填的精确信号类型、观察者与工具的只读视图、环绕调度可替换但不可删除的视图，以及 `defineTool()` 推断。[`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) 覆盖进入时已中止的物化与阶段跳过、策略和包装层竞态、工具主体调用分类、调用方信号融合、错误优先级、上下文保留和完全停稳。[`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) 与 [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) 覆盖为未调度的同批调用补齐持久化结果。[`ptc.spec.ts`](../../../../packages/core/tools/tests/ptc.spec.ts) 和第一方集成测试覆盖显式转发，[`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) 保持超时归属。
+[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) 证明必填的精确信号类型、观察者与工具的只读视图、环绕调度可替换但不可删除的视图，以及 `defineTool()` 推断。[`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) 覆盖进入时已中止的物化与阶段跳过、策略和包装层竞态、工具主体调用分类、调用方信号融合、错误优先级、上下文保留和完全停稳。[`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) 与 [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) 覆盖为未调度的同批调用补齐持久化结果。[`ptc.spec.ts`](../../../../packages/core/tool-executor-ptc/tests/ptc.spec.ts) 和第一方集成测试覆盖显式转发，[`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) 保持超时归属。

 任何注册表测试都无法证明任意第三方同进程代码会观察信号或在有界时间内停止。各能力的测试仍需在拥有相应副作用的边界证明取消与完全停稳。

@@ -3,8 +3,8 @@
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.md
 /agent-note-adjacent-agents-share-one-steer-send-message-operation:
-  en: 4784b23b16ce0d58
-  zh: 7fb5755eebab37b0
+  en: 9d0af2bae38b1eec
+  zh: 8a6e8502a5195548
 /agent-note-adjacent-agents-share-one-steer-send-message-operation/problem:
  en: 5dc4c218f648c27e
  zh: b48531fac94b25db
@@ -4,7 +4,7 @@ Status: implemented

 English | [中文](2026-08-27-adjacent-agent-steer-messaging.zh.md)

-The adjacency, discovery, and parent-lifetime restrictions below are superseded by [tree-wide communication](2026-10-16-tree-wide-agent-communication.md); the remaining decisions stay active.
+The adjacency, discovery, and parent-lifetime restrictions below are superseded by [tree-wide communication](2026-10-16-tree-wide-agent-communication.md); the remaining decisions stay active. The tool identity marker and initial-task communication guidance below are superseded by [tool-owned communication](2026-10-22-subagent-tool-owned-communication.md).

 ## Problem

@@ -4,7 +4,7 @@ Status: implemented

 [English](2026-08-27-adjacent-agent-steer-messaging.md) | 中文

-邻接消息、发现范围和父子生命周期限制已由[整树通信](2026-10-16-tree-wide-agent-communication.zh.md)替代；其余决策仍然有效。
+邻接消息、发现范围和父子生命周期限制已由[整树通信](2026-10-16-tree-wide-agent-communication.zh.md)替代；其余决策仍然有效。 下文的工具身份标记和初始任务通信指导由[工具拥有通信指导](2026-10-22-subagent-tool-owned-communication.zh.md)取代。

 ## 问题

@@ -9,14 +9,14 @@
  en: 98b49b900b8d2f84
  zh: 557faac2976592be
 /agent-note-explicit-agent-identity-at-runtime-boundaries/decision:
-  en: 1c628cf9c743c639
-  zh: d969b2475fe4a155
+  en: 4a3ab5108f37520f
+  zh: d13fcd448101a95d
 /agent-note-explicit-agent-identity-at-runtime-boundaries/verification:
-  en: 85130faaa171036b
-  zh: 06e5e9fab32dbfb4
+  en: ce1733edf03f0387
+  zh: 8e1ca2b69e81968e
 /agent-note-explicit-agent-identity-at-runtime-boundaries/alternatives-considered:
-  en: 2c41456509d54d21
-  zh: 5704ee9a2274e300
+  en: 34f5f8571b21897c
+  zh: cf16094bc0027ca1
 /agent-note-explicit-agent-identity-at-runtime-boundaries/consequences:
-  en: 08ab86b89fc3ec6f
-  zh: 3866e6557858543a
+  en: 0b5914067f14282e
+  zh: c41d21aeb28e357f
@@ -14,34 +14,34 @@ Without an explicit owner, `SubagentManager` creates and resumes children throug

 ## Decision

-Runtime interfaces carry Agent identity at the point that owns it. `AgentSetup` receives `(agentCtx, agent)`; Agent creation and resume options carry `parentAgent` for a runtime child; scoped events carry their Agent in the payload; Remote forwarding verifies that `request.agent` is the carrier key; and Host Typert Context resolution maps wire identity to a live Agent Context without a reverse scan. `agent.ctx` remains the registration and lifecycle owner and exposes no reverse Agent property.
+Runtime interfaces carry Agent identity at the point that owns it. `AgentSetup` receives `(agentCtx, agent)`; each subagent Activation retains its exact runtime root; scoped events carry their Agent in the payload; Remote forwarding verifies that `request.agent` is the carrier key; and Host Typert Context resolution maps wire identity to a live Agent Context without a reverse scan. `agent.ctx` remains the registration and lifecycle owner and exposes no reverse Agent property.

-Scope-aware registries continue to use the opaque scope key only for registration membership. Tool-subagent does not classify that key or resolve an Agent from Context. A direct `AgentSetup` passes the unpublished Session explicitly and installs through the supplied Context before publication. For a settings-backed standing preset, the event payload supplies the Agent, its Session supplies the policy target, and its Context owns the registrations.
+Scope-aware registries continue to use the opaque scope key only for registration membership. Tool-subagent does not classify that key or resolve an Agent from Context. A direct `AgentSetup` receives the Agent explicitly and installs through the supplied Context before Agent publication. For a settings-backed standing preset, the event payload supplies the Agent, its Session supplies the policy target, and its Context owns the registrations.

-`SubagentManager` puts the exact parent in both fresh-creation and cold-resume options. A live continuable child is therefore excluded from `AgentRegistry.roots()` and satisfies `isOwnedBy(child.id, parent)`. Durable `parentSession` metadata does not substitute for this relation: a fork or resumed Session may be a runtime root when no live Agent owns it.
+`SubagentManager.rootOf(agent)` reads runtime membership from existing Activations; both the child and root must match their live registry objects. Ordinary Sessions resolve to themselves, and unmanaged subagent headers grant no membership. Durable `parentSession` describes creation edges; an Activation retains the exact root while intermediate creators are offline, and same-id replacements cannot inherit it. Root-only consumers classify the explicit subagent origin.

 The [scope reference](../../../../packages/core/scope/README.md) and [Agent loop reference](../../../../packages/core/agent-loop/README.md) document registration and lifecycle behavior. The [initiator-scope decision](2026-07-15-agent-initiator-scope.md) owns private-chain rationale; explicit runtime ownership does not change causal initiation or registration lifetime.

 ## Verification

-Agent creation tests pin explicit root and child ownership. Continuation integration tests keep a real child live long enough to assert both `roots()` exclusion and `isOwnedBy()` membership. Existing Schedule tests verify that root-only registrations stay absent from an explicitly owned child.
+Managed-child tests verify intermediate-creator disposal and exact-instance checks after child or root replacement. SDK approval tests verify routing during a turn after the direct creator exits. Schedule and user-question tests reject delegated Sessions while ordinary historical forks remain independent.

-Remote-event tests reject a missing or mismatched Agent before forwarding a scoped waterfall. Tool-subagent tests verify that direct setup installs before Session publication; standing-preset tests verify per-Session policy sampling and inheritance.
+Remote-event tests reject a missing or mismatched Agent before forwarding a scoped waterfall. Tool-subagent tests verify that direct setup installs before Agent publication; standing-preset tests verify per-Session policy sampling and inheritance.

 ## Alternatives considered

 **Keep `Context.agent`.** A reverse accessor makes registration ownership look like operation identity and requires every Context derivation, adapter, and test double to preserve an association unrelated to Cordis service selection or effect cleanup.

-**Infer runtime ownership from the caller Context.** A private manager Context, an Agent Context, and a standing preset Context can all call the same factory. Context ancestry therefore does not state which live Agent owns the result; the creator must put the parent it already knows in the request options.
+**Infer runtime ownership from the caller Context.** A private manager Context, an Agent Context, and a standing preset Context can all call the same factory. Context ancestry therefore does not state which live Agent owns the result; the subagent Activation retains the exact root supplied at admission.

 **Classify Agent scope keys.** An opaque scope key states routing membership, not domain identity. Classifying it would make Agent the center of composition and would still couple a plugin's effect owner to the Session whose policy it needs.

 **Use the initiating Agent as creation ownership.** Initiator scope records causal asynchronous execution, not lifetime ownership. A parent may initiate work that intentionally creates a root, and setup remains outside the child's driver boundary.

-**Use durable Session lineage.** `parentSession` records conversation ancestry across process lifetimes. Runtime ownership controls live roots and teardown, so equating the two would prevent a legitimately resumed fork from becoming a top-level Agent.
+**Use durable Session lineage.** `parentSession` records creation ancestry across process lifetimes. An intermediate creator can be offline while its descendant remains managed by a live root; durable ids also cannot distinguish replaced Agent instances. Historical ordinary forks may retain parent metadata without being delegated.

 ## Consequences

 Lifecycle options, events, service requests, and transport requests carry explicit Agent identities, so each operation states the identity it uses and TypeScript checks both sides. Context remains reusable for dependency access and effect ownership without becoming an alternate domain-object locator.

-Continuable children have the same runtime parent relation as one-shot in-process children. Root-only consumers exclude them, parent teardown can reason from one live ownership graph, and durable lineage remains free to describe history rather than process-local lifetime.
+Continuable children have one runtime root independent of creator residency. The subagent manager owns tree teardown and local membership; the core factory and registry retain only instance creation, publication, and disposal. Third-party callers create managed children through the subagent service rather than assigning ownership to arbitrary factory-created Agents.
@@ -14,34 +14,34 @@ Agent 的 Cordis Context 拥有注册及其清理。Agent 身份则为某项操

 ## 决策

-运行时接口在拥有身份的位置携带 Agent 身份。`AgentSetup` 接收 `(agentCtx, agent)`；创建与恢复 Agent 的 options 通过 `parentAgent` 标识运行时子级；作用域事件在 payload 中携带 Agent；Remote 转发校验 `request.agent` 就是 carrier key；Host Typert Context 解析则把协议身份映射到存活 Agent Context，不执行反向扫描。`agent.ctx` 继续拥有注册和生命周期，不暴露反向 Agent 属性。
+运行时接口在拥有身份的位置携带 Agent 身份。`AgentSetup` 接收 `(agentCtx, agent)`；每个 subagent Activation 保留其确切运行时树根；作用域事件在 payload 中携带 Agent；Remote 转发校验 `request.agent` 就是 carrier key；Host Typert Context 解析则把协议身份映射到存活 Agent Context，不执行反向扫描。`agent.ctx` 继续拥有注册和生命周期，不暴露反向 Agent 属性。

-感知作用域的注册表继续仅使用不透明作用域键判断注册成员关系。tool-subagent 不会分类该键，也不会从 Context 解析 Agent。直接 `AgentSetup` 显式传入尚未发布的 Session，并在发布前通过所给 Context 完成安装。对于由设置控制的常驻 preset，事件 payload 提供 Agent，其 Session 提供策略目标，其 Context 拥有注册项。
+感知作用域的注册表继续仅使用不透明作用域键判断注册成员关系。tool-subagent 不会分类该键，也不会从 Context 解析 Agent。直接 `AgentSetup` 显式接收 Agent，并在 Agent 发布前通过所给 Context 完成安装。对于由设置控制的常驻 preset，事件 payload 提供 Agent，其 Session 提供策略目标，其 Context 拥有注册项。

-`SubagentManager` 会把确切父级放进全新创建与冷恢复的 options。因此，存活的可续跑子级不会出现在 `AgentRegistry.roots()` 中，并且满足 `isOwnedBy(child.id, parent)`。持久化 `parentSession` 元数据不能代替这项关系：没有存活 Agent 拥有 fork 或已恢复会话时，它仍可成为 runtime root。
+`SubagentManager.rootOf(agent)` 从已有 Activation 读取运行时成员关系；子级和树根都必须匹配注册表中的存活对象。普通 Session 返回自身，非托管的 subagent header 不授予成员身份。持久化 `parentSession` 描述创建关系；中间创建者离线时，Activation 保留确切树根，同 id 替代实例不能继承它。仅限根级的消费方依据显式 subagent 来源分类。

 [作用域参考](../../../../packages/core/scope/README.zh.md)与 [Agent loop 参考](../../../../packages/core/agent-loop/README.zh.md)说明注册和生命周期行为。[发起方作用域决策](2026-07-15-agent-initiator-scope.zh.md)负责私有调用链理由；显式运行时归属不改变因果发起关系或注册生命周期。

 ## 验证

-Agent 创建测试锁定显式的根级与子级归属。continuation 集成测试让一个真实子级保持存活，直到断言其既不属于 `roots()`、又满足 `isOwnedBy()`。现有 Schedule 测试验证仅限根级的注册项不会出现在显式归属的子级中。
+托管子级测试验证中间创建者释放，以及子级或树根替换后的确切实例检查。SDK 审批测试验证直接创建者退出后的轮次内路由。Schedule 与用户问题测试拒绝委派 Session，历史普通 fork 则保持独立。

-Remote 事件测试会在转发作用域 waterfall 前拒绝缺失或不匹配的 Agent。tool-subagent 测试验证 direct setup 会在 Session 发布前完成安装；常驻 preset 测试验证逐 Session 的策略读取与继承。
+Remote 事件测试会在转发作用域 waterfall 前拒绝缺失或不匹配的 Agent。tool-subagent 测试验证 direct setup 会在 Agent 发布前完成安装；常驻 preset 测试验证逐 Session 的策略读取与继承。

 ## 考虑过的替代方案

 **保留 `Context.agent`。** 反向 accessor 会让注册所有权看起来等同于操作身份，还要求每个 Context 派生、适配器和测试替身保留一项与 Cordis 服务选择或 effect 清理无关的关联。

-**从调用方 Context 推断运行时归属。** 私有管理器 Context、Agent Context 和常驻 preset Context 都能调用同一个工厂。因此，Context 祖先关系无法说明由哪个存活 Agent 拥有结果；创建方必须把它已知的父级放进请求 options。
+**从调用方 Context 推断运行时归属。** 私有管理器 Context、Agent Context 和常驻 preset Context 都能调用同一个工厂。因此，Context 祖先关系无法说明由哪个存活 Agent 拥有结果；subagent Activation 保留准入时传入的确切树根。

 **分类 Agent 作用域键。** 不透明作用域键表达路由成员关系，而不是领域身份。分类该键会让 Agent 成为组合中心，也仍会把插件的 effect 所有者与策略所需的 Session 耦合起来。

 **使用发起 Agent 作为创建归属。** 发起方作用域记录异步执行的因果关系，而非生命周期归属。父级可能发起有意创建根级 Agent 的工作，而 setup 仍位于子级驱动边界之外。

-**使用持久化会话谱系。** `parentSession` 跨进程生命周期记录对话祖先关系。运行时归属控制存活根级和 teardown，因此把二者等同会阻止合法恢复的 fork 成为顶层 Agent。
+**使用持久化会话谱系。** `parentSession` 跨进程生命周期记录创建祖先关系。中间创建者可以离线，而后代仍由存活树根管理；持久 id 也无法区分替换后的 Agent 实例。历史普通 fork 可能保留父级元数据，但并不属于委派。

 ## 后果

 生命周期 options、事件、服务请求和传输请求会携带显式 Agent 身份，因此每项操作都会声明自身使用的身份，TypeScript 也会检查两侧。Context 可以继续复用于依赖访问与 effect 所有权，而不会成为另一种领域对象定位器。

-可续跑子级与一次性进程内子级使用同一种运行时父级关系。仅限根级的消费方会排除这些子级，父级 teardown 可以依据唯一的存活归属图推理，而持久化谱系仍可描述历史，不必承担进程内生命周期语义。
+可续跑子级拥有独立于创建者驻留状态的唯一运行时树根。subagent 管理器拥有整树 teardown 和本地成员关系；核心工厂与注册表仅保留实例创建、发布和释放。第三方调用方通过 subagent 服务创建托管子级，而非给任意工厂创建的 Agent 指定归属。
@@ -9,8 +9,8 @@
  en: 6bb727a659ba1503
  zh: d2ebf5c8164a807e
 /agent-note-current-profile-plugin-management-shares-cli-transactions/decision:
-  en: 863b4369c39f3933
-  zh: 7dd44a91ccaaef8f
+  en: d2e13562b5aef903
+  zh: 07face30189c07fc
 /agent-note-current-profile-plugin-management-shares-cli-transactions/alternatives-considered:
  en: 30c609de89084351
  zh: 27f2747ad9d9b752
@@ -16,7 +16,7 @@ Configuration watches use Chokidar write stabilization by default. Its ordinary

 Profile files remain the persisted state: entry toggles edit only `disabled` in the last override matching the entry id and any module-name assertion, appending when none matches, and bundle toggles edit the ordered string list. Dependency updates do not reactivate retained disabled bundles. A service removal first applies the composition without the bundle and waits for old fibers to finish before deleting the dependency. Saved configuration, pnpm completion and runtime activation have separate outcomes; a failed removal preserves the actual partial state and a diagnostic path, while a failed or cancelled installation restores the profile files it snapshotted.

-This extends the [profile bundle composition decision](2026-08-05-profile-plugin-bundles.md). Profiles without HMR keep their process composition, and Desktop package management remains shell-owned. Web controls and explicitly enabled agent tools call the same service. Management operations return results to callers without adding messages to live Agents. The agent tool is enabled in Creator mode and disabled by default in the base bundle and other shipped presets. The browser-only worker preview has no host package installer; its module-proxy table refuses `execa` calls explicitly while retaining the management module for inventory discovery.
+This extends the [profile bundle composition decision](2026-08-05-profile-plugin-bundles.md). Profiles without HMR keep their process composition, and Desktop package management remains shell-owned. Web controls and explicitly enabled agent tools call the same service. Management operations return results to callers without adding messages to live Agents. The agent tool is enabled in Standard and Creator modes and disabled by default in the base bundle and other shipped presets. The browser-only worker preview has no host package installer; its module-proxy table refuses `execa` calls explicitly while retaining the management module for inventory discovery.

 CLI calls inherit the terminal and authentication environment; service calls retain the subprocess credential scrub and bounded diagnostics. Management records carry error codes and parameters for locale-owned Web presentation. Reconciliation compares entry identity, fiber identity, configuration and diagnostics before and after updating: unchanged inactive entries remain warnings, while newly affected failures reject the operation. Explicit enablement targets must activate.

@@ -16,7 +16,7 @@ Web 和 Agent 控件需要修改运行中的 profile，同时避免另建包安

 profile 文件保持为持久状态：条目开关只修改最后一条符合条目 id 及模块名称断言的覆盖项中的 `disabled`，没有匹配项时追加，组合包开关修改有序字符串列表。更新依赖不会重新激活保留的已停用组合包。service 删除组合包时，先应用去掉该组合包的配置，等待旧 fiber 完成卸载后再删除依赖。已保存配置、pnpm 完成状态与运行时激活分别报告；失败的删除保留实际的部分状态与诊断路径，失败或被取消的安装则恢复它快照的 profile 文件。

-这扩展了[profile 组合包决策](2026-08-05-profile-plugin-bundles.zh.md)。startup profile 保留进程组合，Desktop 包管理仍由 shell 持有。Web 控件与显式启用的 Agent 工具调用同一 service。管理操作向调用方返回结果，不向存活 Agent 添加消息。创造模式启用该 Agent 工具；base 组合包和其他内置预设默认禁用。纯浏览器 worker 预览没有宿主包安装器；其模块代理表明确拒绝 `execa` 调用，同时保留管理模块用于清单发现。
+这扩展了[profile 组合包决策](2026-08-05-profile-plugin-bundles.zh.md)。startup profile 保留进程组合，Desktop 包管理仍由 shell 持有。Web 控件与显式启用的 Agent 工具调用同一 service。管理操作向调用方返回结果，不向存活 Agent 添加消息。标准模式和创造模式启用该 Agent 工具；base 组合包和其他内置预设默认禁用。纯浏览器 worker 预览没有宿主包安装器；其模块代理表明确拒绝 `execa` 调用，同时保留管理模块用于清单发现。

 CLI 调用继承终端和认证环境；service 调用保留子进程凭据清理与有界诊断。管理结果提供错误码和参数，由 Web 词典呈现文案。重载前后比较 entry、fiber、配置与诊断：未变化的已有故障保留为警告，本次影响到的新故障使操作失败。显式启用的目标必须成功激活。

@@ -9,8 +9,8 @@
  en: 44615a7a0939054e
  zh: b8efa721321ba0d7
 /agent-note-creator-mode-installs-persistent-plugin-bundles/decision:
-  en: c0d74db1b2b16576
-  zh: b8713a6aadf007f9
+  en: 38ecabc170c418c7
+  zh: d380f53fa508328e
 /agent-note-creator-mode-installs-persistent-plugin-bundles/alternatives-considered:
  en: af527d8aabdfd59c
  zh: 34388da992d2ab56
@@ -12,6 +12,8 @@ Agents need to install capabilities and use them during the same conversation. G

 Creator mode enables the existing `plugin_manager` tool. Agents author packages and Loader YAML patches as workspace files, then install them through `install_bundle`. An MCP connection is a configuration-only bundle inserting the installed `dsh-mcp-client`; a UI bundle includes a Host entry and a Client artifact. Profile locking, package installation, enablement and HMR remain owned by the existing manager. The entire management tool requires `danger-full-access` or approval for one call: profile changes can load code with host permissions and affect other sessions. Each execution, including inventory reads, uses the shared sandbox escalation helper and approval service before accessing the manager. Under lower sandbox modes, `ask` requests approval and `never` denies; a full-access session needs no additional approval. A grant does not change session permissions, but its profile changes persist. This keeps shell-equivalent Host access explicit without requiring a permanent session-wide elevation. Human-operated Web and CLI controls retain their existing behavior.

+The default Standard mode enables the same tool under the same profile condition and approval gate. Without it, Standard sessions did not install plugins directly and spent extra turns and tokens working around the missing tool; the change also moves Standard and Creator toward one capability set. A full-access Standard session can therefore install Host code without a separate prompt, as its shell already can. PTC and Minimal keep the tool disabled.
+
 The model sees two read-only Cordis inspection tools. Generated-code define/run/stop/undefine and dynamic self-inspection tool APIs are absent. Existing runtime and Client consumers retain their services; historical session cards remain readable. This supersedes only the model-facing mutation workflow in the [self-referential toolset reference](../../../../packages/extensions/cordis-host-runner/README.md); its runtime ownership and sandbox rationale remain independently relevant. The [profile transaction decision](2026-09-14-current-profile-plugin-management.md) continues to govern locking, package installation, and partial failures.

 Visual creation requests default to an installed Client plugin rendered in the current Web page unless the user names another destination. The development skill supplies a minimal package and effect-owned Client registration. Discovery ends when the required APIs are known; a working first version is installed before optional visual refinement. Verification uses the connected page where available. Browser authentication or operating-system setup is not a prerequisite for plugin installation, and a mock preview cannot establish an in-app result.
@@ -12,6 +12,8 @@ agent 需要安装能力并在同一段对话中使用。生成代码工具在

 创造模式启用现有的 `plugin_manager` 工具。agent 将包和 Loader YAML patch 写入工作区文件，再通过 `install_bundle` 安装。MCP 连接是插入已安装 `dsh-mcp-client` 的纯配置组合包；UI 组合包包含 Host 入口和 Client 产物。profile 锁、包安装、启停和 HMR 继续由现有管理器负责。 整个管理工具要求 `danger-full-access` 或单次调用的批准：profile 变更能以宿主权限加载代码，并影响其他会话。每次执行（包括查询列表）都会先使用共享沙箱提权函数和审批服务，再访问管理器。在较低沙箱模式下，`ask` 请求审批，`never` 拒绝；完整权限会话无需额外审批。批准不改变会话权限，但本次操作的 profile 变更会持久化。这让与 shell 等价的宿主访问需要明确授权，同时不必永久提升整个会话的权限。由用户直接操作的 Web 和 CLI 控件保持原有行为。

+默认的标准模式以相同的 profile 条件和审批门槛启用同一工具。缺少该工具时，标准模式会话不会直接安装插件，而要额外花费轮次和 token 绕过；此改动也让标准模式和创造模式朝同一能力集收敛。因此，完整权限的标准模式会话无需单独审批即可安装 Host 代码，与其 shell 已有的能力一致。PTC 和 Minimal 仍禁用该工具。
+
 模型可见两个只读 Cordis 检查工具，不再提供生成代码的 define/run/stop/undefine 和动态自省工具 API。现有运行时和 Client 消费者保留其服务；历史会话卡片仍然可读。这仅取代[自引用工具集参考](../../../../packages/extensions/cordis-host-runner/README.zh.md)中的模型侧变更流程；其运行时所有权和沙箱依据仍有独立价值。[profile 事务决策](2026-09-14-current-profile-plugin-management.zh.md)继续规定锁、包安装和部分失败行为。

 除非用户指定其他目标，视觉创建请求默认通过已安装的 Client 插件显示在当前 Web 页面。开发 skill 提供最小包和由 effect 管理的 Client 注册示例。已知所需 API 后结束探查，在可选视觉优化之前先安装能工作的初版。有条件时使用已连接页面验证。浏览器认证或操作系统设置不是安装插件的前提，mock 预览不能证明应用内结果。
@@ -15,5 +15,5 @@
  en: b78785f2a603eba8
  zh: b8c268228da7e2e7
 /agent-note-active-tool-headers-and-stateful-request-projection/consequences:
-  en: 93c32b795b71a1cc
-  zh: d42b5c563341c898
+  en: 60d7bf28fa5a8fd1
+  zh: a17b222e7aca01e2
@@ -30,7 +30,7 @@ DeepSeek translates projected updates into system-role `tool_addition` and `tool

 ## Consequences

-Tool lists and logical update events are capability-independent; only outgoing declarations and messages vary. Calls to removed retained tools fail through the existing `UNKNOWN_TOOL` path. Changed definitions and incomplete auxiliary prefixes sacrifice prefix reuse for coherent declarations; unchanged restoration keeps the cached prefix on `in-history` routes only while the request series continues. Routes supporting tool updates and in-history system prompts preserve earlier messages when tools are added alongside a changed prompt or after an earlier prompt update. Routes without tool-update support still consolidate on tool changes; explicit series starts and surface replacements still consolidate on every route. No persisted fields or Session format revision are added.
+Tool lists and logical update events are capability-independent; only outgoing declarations and messages vary. Calls to removed retained tools fail through the existing `UNKNOWN_TOOL` path. Changed definitions and incomplete auxiliary prefixes sacrifice prefix reuse for coherent declarations; unchanged restoration keeps the cached prefix on `in-history` routes only while the request series continues. Routes supporting tool updates and in-history system prompts preserve earlier messages when tools are added alongside a changed prompt or after an earlier prompt update. Routes without tool-update support still start a new series on tool changes; explicit series starts and surface replacements consolidate the prompt only when the effective text differs, and otherwise leave the surviving prompt node in place. No persisted fields or Session format revision are added.

 The authored [headless prompt/tool scenario](../../../../snapshots/session/dynamic-tool-prompt-updates/snapshot.yml) pins an appended prompt beside a deferred tool addition and verifies that the first request's messages stay unchanged. It shares the stable-prompt scenario's tool lifecycle and schema expectations.

@@ -30,7 +30,7 @@ DeepSeek 把投影后的更新转换为 system 角色的 `tool_addition` 和 `to

 ## Consequences

-工具列表和逻辑更新事件不依赖能力；只有发出的声明和消息不同。调用已移除但保留声明的工具时，通过现有 `UNKNOWN_TOOL` 路径失败。定义变化和不完整辅助前缀为保证声明一致而放弃前缀复用；仅当请求序列继续时，未变化的恢复才在 `in-history` 路由上保留缓存前缀。同时支持工具更新和历史内系统提示词的路由，在工具添加与提示词变化同时发生或晚于此前提示词更新时，保留此前消息。不支持工具更新的路由仍在工具变化时归并提示词；所有路由仍在显式新序列和 surface 替换时归并。不增加持久字段或 Session 格式版本。
+工具列表和逻辑更新事件不依赖能力；只有发出的声明和消息不同。调用已移除但保留声明的工具时，通过现有 `UNKNOWN_TOOL` 路径失败。定义变化和不完整辅助前缀为保证声明一致而放弃前缀复用；仅当请求序列继续时，未变化的恢复才在 `in-history` 路由上保留缓存前缀。同时支持工具更新和历史内系统提示词的路由，在工具添加与提示词变化同时发生或晚于此前提示词更新时，保留此前消息。不支持工具更新的路由仍在工具变化时开启新序列；显式新序列和 surface 替换只在有效文本不同时归并提示词，否则保留存活的提示词节点。不增加持久字段或 Session 格式版本。

 手写的[无界面提示词／工具场景](../../../../snapshots/session/dynamic-tool-prompt-updates/snapshot.yml)钉住追加提示词与延迟工具添加同时发生的行为，并验证首次请求的消息保持不变。它复用稳定提示词场景的工具生命周期和 schema 期望值。

@@ -9,8 +9,8 @@
  en: 2ba6c43b20a3d347
  zh: 5647179ddaa38ad9
 /agent-note-ship-experimental-capabilities-as-optional-bundles/decision:
-  en: d6328ba2b218f2ac
-  zh: 3731561313b1ad5e
+  en: 191ca8bffb101db2
+  zh: 1365bef5cd830a5c
 /agent-note-ship-experimental-capabilities-as-optional-bundles/alternatives-considered:
  en: d6f40bf02df37ab7
  zh: e5b85ce9d41e8754
@@ -10,7 +10,7 @@ The Web plugin page offered two optional bundles, Agent Teams and voice input. A

 ## Decision

-`OPTIONAL_BUNDLES` owns the installation's default-off selections, including maintained optional capabilities and experimental capabilities. Every bundle declares `icon` and exports `./locale/*.json` with `meta.title` and `meta.description`; the Official group displays that metadata. A bundle's presentation does not determine its [experimental status](../../../../packages/experimental/README.md#status). The isolation check validates admission and still rejects experimental dependencies of nonexperimental bundles.
+`OPTIONAL_BUNDLES` owns the installation's default-off selections, including maintained optional capabilities and experimental capabilities. Every bundle declares `icon` and exports `./locale/*.json` with `meta.title` and `meta.description`; the [plugin manager page](../../../../packages/client/ui-plugin-manager/README.md#use-this-package) displays that metadata for eligible bundles and retains explicit activation for default-hidden ones. A bundle's presentation does not determine its [experimental status](../../../../packages/experimental/README.md#status). The isolation check validates admission and still rejects experimental dependencies of nonexperimental bundles.

 An optional bundle's dependencies are downloaded with every `dsh` installation. [Reasoning translation](2026-10-05-anonymous-reasoning-translation.md) uses three experimental packages without adding third-party runtime dependencies. Admission therefore considers installation cost and whether a switch supplies a usable composition without an additional configuration form. External browser and Cua Driver providers remain explicit compositions because they add substantial runtimes or require an external executable. Stagehand requires model credentials; Python PTC replaces a core provider and conflicts with TypeScript workflow consumers. Demonstrative hooks, webhooks, and mods stay outside the list. [Session Inspector](../feature/2026-09-24-session-inspector.md) owns the Inspector's distinct activation behavior.

@@ -10,7 +10,7 @@ Web 插件页只提供两个可选 bundle：Agent Teams 与语音输入。Auto r

 ## 决策

-`OPTIONAL_BUNDLES` 管理安装随附且默认关闭的选项，包括维护中的可选能力与实验性能力。每个 bundle 声明 `icon`，并导出带 `meta.title` 与 `meta.description` 的 `./locale/*.json`；官方分组显示这些元数据。Bundle 的展示方式不决定其[实验性状态](../../../../packages/experimental/README.zh.md#status)。隔离检查校验准入，并继续拒绝非实验 bundle 的实验性依赖。
+`OPTIONAL_BUNDLES` 管理安装随附且默认关闭的选项，包括维护中的可选能力与实验性能力。每个 bundle 声明 `icon`，并导出带 `meta.title` 与 `meta.description` 的 `./locale/*.json`；[插件管理页](../../../../packages/client/ui-plugin-manager/README.zh.md#use-this-package)为符合展示条件的组合包显示这些元数据，并保留默认隐藏项的显式启用入口。Bundle 的展示方式不决定其[实验性状态](../../../../packages/experimental/README.zh.md#status)。隔离检查校验准入，并继续拒绝非实验 bundle 的实验性依赖。

 可选 bundle 的依赖随每次 `dsh` 安装下载。[思考过程翻译](2026-10-05-anonymous-reasoning-translation.zh.md)使用三个实验包，不增加第三方运行时依赖。因此准入需要考虑安装成本，以及开关能否在不增加配置表单的情况下提供可用组合。外部浏览器与 Cua Driver 提供方仍使用显式组合，因为它们会增加较大的运行时或要求外部可执行文件。Stagehand 需要模型凭据；Python PTC 替换核心提供方，并与 TypeScript workflow 消费方冲突。演示性钩子、webhook 与模组不进入名单。[Session Inspector](../feature/2026-09-24-session-inspector.zh.md) 管理 Inspector 特有的激活行为。

@@ -9,8 +9,8 @@
  en: 2eeb916eb65c66e7
  zh: 7bf5c0abb8bb61e4
 /agent-note-deepseek-account-models-come-from-the-account-listing-and-gate-by-client-version/decision:
-  en: 42e800c4cd3b6ebe
-  zh: 06fabe5a9681fa27
+  en: 0125e33ba966c8ac
+  zh: bf6af389336999af
 /agent-note-deepseek-account-models-come-from-the-account-listing-and-gate-by-client-version/alternatives-considered:
  en: 7c7880fdb0cc95f6
  zh: 2b8a539192626789
@@ -12,8 +12,8 @@ The account route's catalog was deployment configuration: a build advertised the

 - [`llm-deepseek-account`](../../../../packages/llm/llm-deepseek-account/README.md) loads the listing lazily for each credential, waits for it once up to `modelsTimeoutMs`, refreshes it in the background after `modelsMaxAgeMs`, keeps the last good listing when a load fails or returns no model, and serves the bundled catalog before any listing loads. The cache lives in memory and is keyed by endpoint and token fingerprint, so per-account rollouts stay separate.
 - A listed model is available when its `client_requirements["deepseek-harness"].min_version` is at most the current DeepSeek Harness version in semantic-version order. Without that declaration, only ids the built-in catalog knows are available; the others stay hidden, because a client cannot tell which future version supports them. A request for a refused listed model fails before network I/O with `CLIENT_UPGRADE_REQUIRED` or `MODEL_UNSUPPORTED`.
- Listed capabilities replace bundled ones field by field; the bundled entry keeps client-side knowledge such as tool-update mode and image budgets; `modelOverrides` applies last and reuses the `models` entry fields and validation. `max_output_tokens` bounds the request default instead of becoming it.
- The shared transport gains only two provider hooks, `connect` and `admit`; listing, gating, and merging stay in the account package.
+- Listed capabilities replace bundled ones field by field; the bundled entry keeps client-side knowledge the listing does not declare, such as image budgets and a protocol mode the listing omits or sets to `null`; `modelOverrides` applies last and reuses the `models` entry fields and validation. `max_output_tokens` bounds the request default instead of becoming it.
+- The shared transport gains only two provider hooks, `connect` and `admit`. Listing, gating, and merging live in the shared transport, which the [official route](2026-10-22-deepseek-official-model-listing.md) also uses.

 ## Alternatives considered

@@ -12,8 +12,8 @@ Status: implemented

 - [`llm-deepseek-account`](../../../../packages/llm/llm-deepseek-account/README.zh.md) 按凭据懒加载列表，首次访问最多等待 `modelsTimeoutMs`，超过 `modelsMaxAgeMs` 后在后台刷新；获取失败或返回的列表中没有模型时保留上一份，还没有加载到任何列表时使用内置目录。缓存只在内存中，以端点和 token 指纹为键，因此按账号灰度互不干扰。
 - 列出的模型在其 `client_requirements["deepseek-harness"].min_version` 按 semver 顺序不高于当前 DeepSeek Harness 版本时可用。没有这个声明时，只有内置目录认识的 id 可用，其余保持隐藏，因为客户端无法判断将来哪个版本会支持它们。请求被拒绝的已列出模型时，在网络请求之前以 `CLIENT_UPGRADE_REQUIRED` 或 `MODEL_UNSUPPORTED` 失败。
- 列表中的能力逐字段覆盖内置能力；内置条目保留工具更新模式、图片预算等客户端知识；`modelOverrides` 最后叠加，复用 `models` 条目的字段与校验。`max_output_tokens` 只限制请求默认值，不直接成为默认值。
- 共享传输层只新增 `connect` 与 `admit` 两个提供方钩子；列表、门控与合并都留在账号包中。
+- 列表中的能力逐字段覆盖内置能力；内置条目保留列表没有声明的客户端知识，例如图片预算，以及列表没有给出或设为 `null` 的协议模式；`modelOverrides` 最后叠加，复用 `models` 条目的字段与校验。`max_output_tokens` 只限制请求默认值，不直接成为默认值。
+- 共享传输层只新增 `connect` 与 `admit` 两个提供方钩子。列表、门控与合并位于共享传输包中，[官方路由](2026-10-22-deepseek-official-model-listing.zh.md)也使用它们。

 ## 考虑过的替代方案

@@ -9,11 +9,11 @@
  en: abd0263d14861926
  zh: e1736cd08e87f795
 /agent-note-shared-time-vocabulary-for-wall-clock-selectors/decision:
-  en: 52b45f1ac62e65ab
-  zh: 7f83cd4fb8dd09a6
+  en: fdd39b7e8fa89d70
+  zh: 4a0dfc81509e5485
 /agent-note-shared-time-vocabulary-for-wall-clock-selectors/alternatives-considered:
  en: 1737484c099fab52
  zh: 303b144c52d167bd
 /agent-note-shared-time-vocabulary-for-wall-clock-selectors/consequences:
-  en: 6ec74e7ac065bd5e
-  zh: 04d029059dea732b
+  en: 79d8d66071453d1f
+  zh: f940f0b6d74148d6
@@ -20,6 +20,8 @@ Schedule consumes it and keeps every domain decision. `canonicalizeTimeZone`, `d

 `Duration` holds one span as a single millisecond count, and it is a class rather than a branded number because TypeScript's arithmetic erases a brand: adding two differently branded numbers answers an unbranded `number`, so a brand cannot stop seconds and milliseconds from being mixed, while an instance can. The unit is milliseconds because every producer and consumer in this repository already uses it (`Date.now()`, `SessionEvent.time`, the session log, the client), and because a double holds every millisecond of the whole `Date` range exactly, so no precision is spent on the unit. Instances are frozen, no coercion hook is overridden, and a span is bounded by the exactly representable millisecond range, which is what makes the split exact. The published surface is `fromMilliseconds` and a whole-part `decompose()`, the two entries the migrated consumer calls.

+The last copy of the canonical instant profile moves too. `packages/session/session-format-v0-to-v1/src/payload-validation.ts` validated a stored schedule instant with its own regular expression and round trip; the shared `fourDigitYearEpoch` owns that same profile, so the migration now asks it and keeps its own error type and message. Because that migration reads released logs, its accepted set is a compatibility promise: `packages/session/session-format-v0-to-v1/tests/validation.spec.ts` accepts the four-digit-year bounds and refuses each spelling a regular expression alone would admit (`0000`, `2026-02-30`, a four-digit fraction, a numeric offset, surrounding whitespace).
+
 The maintained `@js-temporal/polyfill` 0.5.1 becomes a runtime dependency of `dsh-util-time` as well as of `dsh-schedule`. Local resolution continues to use it, so the Host's IANA data still decides gaps and overlaps and no caller owns offset sampling. `util/time`'s own description and README drop the `zero-dependency` phrase as ambiguous: the group's charter forbids harness dependencies so any group may depend on util, and does not ban external packages, which is why `packages/README.md` and the `util/` line in `AGENTS.md` keep the phrase while `packages/util/README.md` and this package's own description name what it loads.

 Observable behavior does not change. Every accepted input resolves to the same epoch, every refused input raises the same `ScheduleInputError` or `ScheduleLogError` code and the same message, and the stored `scheduledAt` profile is unchanged, so no durable record and no recorded snapshot is re-recorded. Schedule's suites assert error codes and a few unrelated message substrings, so the assertion this change adds to `packages/schedule/schedule/tests/domain.spec.ts` is the only place that pins the three local-calendar message strings. `packages/util/time/tests/instant.spec.ts` covers the new entries directly, per-file 100% included.
@@ -48,4 +50,4 @@ A value type publishes what its consumers call, so the span exposes the construc

 The elapsed reading keeps its split in the library and its wording in the consumer: `dsh-time-context` still decides that a backward clock reading clamps to zero and how the compact line reads, while `Duration.decompose()` answers the whole parts. That swap is byte-identical for every finite sample, measured over more than eight thousand inputs including negatives, fractions, and values past a year. That measurement is not a committed test: the consumer's own suite pins the readings it renders (`1d 1h 1m 1s`, `1m 1s`, `4m 2s`, and the clamped zero). Two samples do change: `NaN` rendered `NaNs` and `+Infinity` rendered `Infinityd NaNs`, and both now throw from the span constructor, so a reading that is not a finite number fails where it is produced instead of rendering text. A `-Infinity` sample is unchanged, because the consumer clamps it to zero before the span is built.

-Time-context keeps the two policies this change did not touch: its ISO-shaped timestamp rendering in `packages/context/time-context/src/timestamp.ts`, which is that package's durable reading format, and the elapsed-duration wording in its own plugin. The browser client keeps its own localized date rendering and its own UTC-offset reading, which serve a different purpose (a reader's locale) from a boundary value; unifying those means deciding whether the shared library should also own display formatting, and which package then owns the durable reading format. `packages/session/session-format-v0-to-v1/src/payload-validation.ts` also validates the canonical four-digit-year UTC instant with its own regular expression and round trip, which is a remaining copy of the instant profile this change did not touch.
+Time-context keeps the two policies this change did not touch: its ISO-shaped timestamp rendering in `packages/context/time-context/src/timestamp.ts`, which is that package's durable reading format, and the elapsed-duration wording in its own plugin. The browser client keeps its own localized date rendering and its own offset reading for display, which serve a different purpose (a reader's locale) from a boundary value; unifying those means deciding whether the shared library should also own display formatting, and which package then owns the durable reading format. Five time sites keep their own code, each for a different reason. `packages/experimental/tool-session-query/src/input.ts` parses a wider profile than the shared entry — seconds optional, any number of fractional digits, and the digits below the millisecond kept so two instants can be compared exactly — so substituting the shared parser would narrow what it accepts, and moving that profile into the library is a design step of its own. The `Date.parse(record.scheduledAt)` reads in `dsh-schedule` parse a value the write path already validated, so a discriminated decode would add a rejection branch that cannot occur in practice and change what a corrupt record reports. The `everySeconds`, `afterSeconds`, and `refreshMarginSeconds` multiplications each sit beside a validation that raises the package's own error, so routing them through a constructor that throws its own type would change the failure a caller sees. The UTC offset a client reports is computed in `packages/client/ui-settings-account/src/client/client-metadata.ts` instead of shared: the client bundle admits a cross-plugin value import only for the packages it lists as inline-safe, `dsh-util-time` is not one of them, and it imports the `Temporal` polyfill at module scope, so inlining it would ship that polyfill to the browser. The Desktop host computes the same offset from the shared library, where no such rule applies. `dsh-workspace` writes its record timestamps with the platform's `toISOString`, which is the canonical rendering for every representable epoch: the extended-year and fractional-truncation cases a shared writer would refuse are unreachable from `Date.now()` and from a `SessionHeader` epoch, so adopting the shared formatter there would add a module and a dependency without changing a byte.
@@ -20,6 +20,8 @@ Schedule 消费它，并保留全部域内决策。`canonicalizeTimeZone`、`dec

 `Duration` 以单一毫秒计数保存一段时间；它做成类而不是 branded number，是因为 TypeScript 的算术会抹掉 brand：两个不同品牌的数字相加得到的是无品牌的 `number`，所以 brand 挡不住秒与毫秒的混用，而实例可以。单位选毫秒，是因为本仓库的每个生产者与消费者本来就用它（`Date.now()`、`SessionEvent.time`、Session 日志、客户端），也因为 double 能精确表示 `Date` 全范围内的每一个毫秒，这个单位不消耗任何精度。实例被冻结，不覆盖任何强制转换钩子，且时间段受可精确表示的毫秒范围约束——这正是拆分精确的前提。公开面就是 `fromMilliseconds` 与整数量拆解 `decompose()`，即已迁移消费方所调用的两个入口。

+最后一份规范时刻剖面副本也一并迁移。`packages/session/session-format-v0-to-v1/src/payload-validation.ts` 原本用自己的一段正则与往返比对校验持久记录里的调度时刻；共享的 `fourDigitYearEpoch` 拥有同一剖面，因此该迁移改为询问它，并保留自己的错误类型与文案。由于这个迁移要读取已发布的日志，其接受集是兼容性承诺：`packages/session/session-format-v0-to-v1/tests/validation.spec.ts` 接受四位年份两端，并拒绝只靠正则会放进来的每种拼写（`0000`、`2026-02-30`、四位小数、数字偏移、首尾空白）。
+
 受维护的 `@js-temporal/polyfill` 0.5.1 在成为 `dsh-schedule` 运行时依赖之外，也成为 `dsh-util-time` 的运行时依赖。本地解析继续使用它，因此缺口与重叠仍由宿主 IANA 数据决定，也没有调用方需要自己实现偏移采样。`util/time` 自身的描述与 README 去掉了 `zero-dependency` 这一说法，因为它容易被误读：该组的约定禁止的是 harness 依赖（以便任何组都能依赖 util），并不禁止外部包；因此 `packages/README.md` 与 `AGENTS.md` 里的 `util/` 一行保留该说法，而 `packages/util/README.md` 与本包自己的描述写明它加载了什么。

 可观察行为不变。每个被接受的输入解析出相同的纪元值，每个被拒绝的输入抛出相同的 `ScheduleInputError` 或 `ScheduleLogError` 错误码与相同的消息，存储的 `scheduledAt` 剖面不变，因此没有持久记录或录制快照需要重录。Schedule 的测试断言错误码以及少量无关的消息子串，因此本次在 `packages/schedule/schedule/tests/domain.spec.ts` 新增的断言是唯一固定这三条本地日历消息的地方。`packages/util/time/tests/instant.spec.ts` 直接覆盖新增入口，包含逐文件 100% 覆盖。
@@ -48,4 +50,4 @@ Schedule 消费它，并保留全部域内决策。`canonicalizeTimeZone`、`dec

 耗时读数的拆分上收到库、措辞留在一侧：`dsh-time-context` 仍然决定回退的时钟读数钳到零、以及那行紧凑文本怎么写，而 `Duration.decompose()` 回答整数量。这次替换对每个有限样本都逐字不变，用一份覆盖八千多个输入（含负数、小数与一年以上的值）的差分测得。该测量不是提交进仓库的测试：消费方自己那套测试固定了它渲染出的读数（`1d 1h 1m 1s`、`1m 1s`、`4m 2s`，以及被钳到零的那次）。有两个样本会变：`NaN` 原本渲染出 `NaNs`、`+Infinity` 原本渲染出 `Infinityd NaNs`，现在两者都由时间段构造函数抛出，于是非有限的读数在产生它的地方失败，而不是渲染出一段文本。`-Infinity` 样本不变，因为消费方在构造时间段之前已把它钳到零。

-本次未触及、仍归 time-context 的两项：`packages/context/time-context/src/timestamp.ts` 中的 ISO 形状时间戳渲染（那是该包的持久读数字格式），以及其插件内的耗时措辞。浏览器客户端也保留自己的本地化日期渲染与自己的 UTC 偏移读取——它们服务的目的（读者的区域设置）与边界值不同；统一它们意味着先决定共享库是否也要拥有展示格式化，以及届时由谁拥有持久读数字格式。`packages/session/session-format-v0-to-v1/src/payload-validation.ts` 也用自己的一段正则与往返比对校验规范的四位年份 UTC 时刻，这是本次未触及、仍然存在的时刻剖面副本。
+本次未触及、仍归 time-context 的两项：`packages/context/time-context/src/timestamp.ts` 中的 ISO 形状时间戳渲染（那是该包的持久读数字格式），以及其插件内的耗时措辞。浏览器客户端也保留自己的本地化日期渲染与用于展示的偏移读取——它们服务的目的（读者的区域设置）与边界值不同；统一它们意味着先决定共享库是否也要拥有展示格式化，以及届时由谁拥有持久读数字格式。有五处时间代码各自保留实现，原因各不相同。`packages/experimental/tool-session-query/src/input.ts` 解析的剖面比共享入口更宽——秒可省略、小数位不限、并保留下毫秒数字以便精确比较两个时刻——因此换成共享解析器会收窄它接受的输入，而把那条剖面搬进本库是另一项独立的设计。`dsh-schedule` 里的 `Date.parse(record.scheduledAt)` 读的是写入路径已经校验过的值，换成带判别值的解码会在每个读取点新增一个实际不可能发生的拒绝分支，并改变损坏记录的报告方式。`everySeconds`、`afterSeconds` 与 `refreshMarginSeconds` 三处乘法旁边都紧跟一条抛本包自有错误的校验，因此把它们改走会抛自身错误类型的构造函数，会改变调用方看到的失败。客户端上报的 UTC 偏移由 `packages/client/ui-settings-account/src/client/client-metadata.ts` 自行计算而不共享：客户端 bundle 只允许对列入 inline-safe 的包做跨插件值导入，`dsh-util-time` 不在其中，而且它在模块顶层静态导入 `Temporal` polyfill，内联它等于把该 polyfill 打进浏览器；Desktop 的宿主侧则用共享库计算同一个偏移，那里没有这条限制。`dsh-workspace` 用平台的 `toISOString` 写记录时间戳，对每个可表示的纪元那已是规范渲染：共享写入器会拒绝的扩展年份与小数截断两种情形，从 `Date.now()` 与 `SessionHeader` 的纪元出发都不可达，因此在那边采用共享格式化器只会增加一个模块与一条依赖，却不会改变任何字节。
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-09-27-web-search-offered-by-provider-readiness.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-27-web-search-offered-by-provider-readiness.md
+/agent-note-offer-web-search-and-web-fetch-only-while-the-selected-provider-is-ready:
+  en: 9163af91ea0e030d
+  zh: 92e44043b999d32f
+/agent-note-offer-web-search-and-web-fetch-only-while-the-selected-provider-is-ready/problem:
+  en: 6fac3c73a4415c83
+  zh: f65b61cc1705348b
+/agent-note-offer-web-search-and-web-fetch-only-while-the-selected-provider-is-ready/decision:
+  en: 458416ed7e47f644
+  zh: 8b4dd820228e9dfd
+/agent-note-offer-web-search-and-web-fetch-only-while-the-selected-provider-is-ready/alternatives-considered:
+  en: b731254983be656d
+  zh: 5dee2b09f7faa537
+/agent-note-offer-web-search-and-web-fetch-only-while-the-selected-provider-is-ready/consequences:
+  en: 798faeaa0b406eac
+  zh: 97bbfdaebc84b1d4
@@ -0,0 +1,51 @@
+# Agent Note: Offer web_search and web_fetch only while the selected provider is ready
+
+Status: implemented
+
+English | [中文](2026-09-27-web-search-offered-by-provider-readiness.zh.md)
+
+## Problem
+
+`dsh-tool-web` registers `web_search` whenever search is enabled, and the [web capability seam decision](2026-06-24-web-capability-seam.md) keeps it visible while the selected provider cannot run. The shipped search provider, `dsh-web-search-deepseek`, authenticates a search with the DeepSeek account token only for a model request on the `deepseek-account` route; every other route needs a configured API key. A Session on an API-key route without a search key was therefore offered a tool whose every call failed with `WEB_PROVIDER_CREDENTIAL_MISSING`. Sessions in one Host can use different routes, a Session can switch routes between requests, and the Web app registers `web_search` once per agent preset, so no registration decision matches every request. The Search and Fetch APIs of `dsh-web-deepseek-api`, which the Web search settings switch selects together, need that credential for both operations, so the same Session was also offered a `web_fetch` whose every call failed.
+
+## Decision
+
+Each role of the web capability seam owns one part of a per-step check:
+
+- **Service Definition.** `WebSearchProvider` and `WebFetchProvider` have an optional `ready(llmProvider)` that answers whether an operation made for a model request on that chat route has a credential to send. It checks configuration only and makes no network calls. `ctx.web.searchReady(llmProvider?)` and `ctx.web.fetchReady(llmProvider?)` resolve the provider with the same rules as `search()` and `fetch()` and return its answer. A provider without `ready()` counts as ready, and a selection failure answers true because the operation reports that failure as a structured `WebError`.
+- **Service Provider.** `dsh-web-search-deepseek` answers true when the route is `deepseek-account` and `ctx.deepseekAccount.resolveToken()` returns a token for the configured search endpoint, when the section carries a literal `apiKey`, or when `ctx.credentials.describe()` reports the `apiKeyEnv` reference configured (without that service, when the launching environment carries it). It checks credentials in the order `search()` resolves them, and a failed account-token or credential-store read answers false, because `search()` fails on that read instead of trying the next credential. The Search and Fetch API providers of `dsh-web-deepseek-api` share one credential and answer the same way for their API base; their transport repeats these checks, so neither package depends on the other. The providers name no tool or prompt section.
+- **Consumer.** `dsh-tool-web` registers `web_search` and `web_fetch` with [step activation conditions](../../../../packages/core/tools/README.md#conditional-tools) that ask `ctx.web.searchReady()` and `ctx.web.fetchReady()` about the route of the step's model selection. The agent loop resolves conditions before it assembles the step, so the declared tools, the `tool:web_search` and `tool:web_fetch` prompt sections, PTC program bindings, and dispatch all read the same admitted set.
+
+The route decides only whether the account token is checked before the API key, which happens on the `deepseek-account` route; an API key counts on every route, so a conversation on another provider's model is offered the DeepSeek web tools whenever a DeepSeek key is configured. The providers do not compare the chat route's endpoint with their own: each operation sends the configured key, `DEEPSEEK_API_KEY` by default, to the configured endpoint, even when the official route chats through a gateway.
+
+Only presence decides: no API key value is read and no endpoint is contacted, so a wrong key or an endpoint that does not serve the native `web_search_20250305` server tool keeps the tool admitted. A step that does not admit a web tool also refuses calls to it as `UNKNOWN_TOOL`, so a model that repeats an earlier call reaches no provider; an operation made outside a model step resolves its credential when it runs and fails with `WEB_PROVIDER_CREDENTIAL_MISSING` when there is none.
+
+The request header records the assembled tools, so the agent loop announces each change through tool-registry updates. A route switch, a stored key, or a removed key changes the next request; DeepSeek routes load a returning tool as a deferred addition, and routes without tool-update support receive the complete tool list.
+
+## Alternatives considered
+
+**Let the DeepSeek provider remove `web_search` in its own assemble listener.** The seam stays unchanged, but the provider then names another package's tool, prompt section, and PTC transport, and it removes the tool even when the deployment selects another search provider, such as Exa, whose searches would succeed.
+
+**Extend `available()`.** It is synchronous and takes no request, while this check reads an asynchronous credential store and depends on the request's route. A route-dependent `available()` would also make provider selection depend on the conversation.
+
+**Read the route from the Session's latest `request/context` event instead of passing it.** That event records the previous request, so a new Session's first request and the first request after a model switch would be decided for the wrong route or for none.
+
+**Register or unregister `web_search` in `dsh-tool-web`.** Registration is shared by every Session of an agent preset, while credentials depend on each request's route. Unregistering would also make `toolOrder` entries and subagent `toolFilter` restrictions that name `web_search` fail.
+
+**Remove `web_search` from the assembled request.** A `system-prompt/assemble` listener could drop the declaration and its section, but the tool would stay executable, so a model that repeats an earlier call would still run it, and PTC programs would still bind it. Prompt assembly also no longer carries tool declarations.
+
+**Offer search only on the DeepSeek account route.** Account tokens are issued only for the official endpoint, so a gateway key could never reach DeepSeek. But every shipped profile defaults to the `deepseek-official` route, so search would be off by default, including the official API-key case.
+
+**Withhold the tools from other providers' conversations unless search has a key of its own.** A search from another model's conversation bills the DeepSeek key, but DeepSeek search is one of the services that key pays for, and a user who configured it expects search to work whatever model chats. The Web search settings page saves its key under `apiKeyEnv`, `DEEPSEEK_API_KEY` by default, which the chat route also reads, so a key entered there could never serve another model; a `routes` setting that opens them would be one more thing a user has to find.
+
+**Compare the official chat route's endpoint with the search endpoint.** Withholding the tools or the key when the two endpoints differ in origin keeps a gateway's key away from DeepSeek, but the providers would have to find the chat route's configuration themselves. Taking the first active `dsh-llm-deepseek-api-key` Loader row answers for an unrelated instance when a composition isolates several, which disables a correct route or lets a gateway key through; only the route's owner knows which endpoint serves a request, and an endpoint field in `dsh-llm` would reach the browser through the Remote `listProviders()`. The check would also withhold search from users who chat through a proxy or development endpoint with a key the official search endpoint accepts. Without it, a gateway user's search fails at the configured endpoint.
+
+**Keep the tool offered and fail at execution.** The model spends a call on a search that cannot authenticate, and the failure repeats on every attempt.
+
+**Probe the key or endpoint before offering the tool.** A network request per model request adds latency and cost; the user controls configuration, not its validity at that moment.
+
+## Consequences
+
+`dsh-web` gains public members: the optional `ready()` of both provider interfaces, `WebRuntime.searchReady()`, and `WebRuntime.fetchReady()`. Each readiness method is the smallest query its one consumer needs, which is how the [observation-surface decision](../../archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md) lets a status query return; neither reports availability or selection failures. The Exa, Perplexity, and HTTP fetch providers implement no `ready()`, so their behavior is unchanged, and `web_fetch` stays admitted whenever the switch leaves HTTP fetch selected. A step that does not admit a web tool leaves it out of PTC program bindings too. An endpoint that cannot serve the native server tool keeps the tool admitted and fails each call. Removing a tool on an unchanged route changes the declared tools and misses the prompt cache once; a model switch already invalidates it. Searches and fetches from other providers' conversations bill the configured DeepSeek key, and a deployment whose official route chats through a gateway sends the gateway's key to the configured endpoint, the official one by default, where each operation fails unless that endpoint accepts the key. The DeepSeek web packages read no Loader rows and depend on no LLM package.
+
+Unit tests pin each role: `packages/web/web/tests/web.spec.ts` covers which provider `searchReady()` and `fetchReady()` ask and their answer on selection failure, `packages/web/web-search-deepseek/tests/deepseek.spec.ts` and `packages/web/web-deepseek-api/tests/readiness.spec.ts` cover each credential case of `ready()` on the account route and on other routes, and `packages/web/tool-web/tests/tool-web.spec.ts` resolves step admission of both tools through the real prompt, tool, and executor services, including the `UNKNOWN_TOOL` refusal of a call in a step that withheld the tool. In real compositions, the shipped headless keyless smoke test and the `web-search-unconfigured` recorded-session snapshot, whose search key references are unset, pin the withheld search tool. Snapshot replays supply a placeholder DeepSeek key, so their tool lists do not depend on the runner's environment; with it, the `pi-ai-conversation-updates` conversation on a pi-ai route keeps `web_search`.
@@ -0,0 +1,51 @@
+# Agent Note: 仅在选中的提供方就绪时提供 web_search 与 web_fetch
+
+Status: implemented
+
+[English](2026-09-27-web-search-offered-by-provider-readiness.md) | 中文
+
+## Problem
+
+`dsh-tool-web` 在启用搜索时总会注册 `web_search`，而 [web 能力 seam 决策](2026-06-24-web-capability-seam.zh.md)让它在选中的提供方无法运行时仍然可见。发行版的搜索提供方 `dsh-web-search-deepseek` 只对 `deepseek-account` 路由上的模型请求使用 DeepSeek 账号 token 鉴权；其他路由都需要已配置的 API 密钥。因此，API 密钥路由上没有搜索密钥的会话会获得一个每次调用都以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败的工具。同一 Host 中的会话可以使用不同路由，一个会话可以在请求之间切换路由，而 Web 应用按 agent preset 只注册一次 `web_search`，因此任何注册层面的决定都无法与每个请求相符。Web 搜索设置开关会同时选中 `dsh-web-deepseek-api` 的 Search 与 Fetch API，两个操作都需要这份凭据，因此同一会话还会获得一个每次调用都失败的 `web_fetch`。
+
+## Decision
+
+web 能力 seam 的每个角色各负责逐步骤检查的一部分：
+
+- **Service Definition。** `WebSearchProvider` 与 `WebFetchProvider` 有一个可选的 `ready(llmProvider)`，回答为该对话路由上的模型请求发起的操作是否有可发送的凭据。它只检查配置，不发起网络调用。`ctx.web.searchReady(llmProvider?)` 与 `ctx.web.fetchReady(llmProvider?)` 按与 `search()`、`fetch()` 相同的规则解析提供方并返回其回答。没有 `ready()` 的提供方视为就绪；选择失败时回答 true，因为对应操作会把该失败报告为结构化 `WebError`。
+- **Service Provider。** `dsh-web-search-deepseek` 在以下任一情况下回答 true：路由为 `deepseek-account` 且 `ctx.deepseekAccount.resolveToken()` 为配置的搜索端点返回 token；配置段带有字面 `apiKey`；或 `ctx.credentials.describe()` 报告 `apiKeyEnv` 引用已配置（没有该服务时，启动环境中存在该变量）。它按 `search()` 解析凭据的顺序检查凭据，读取账号 token 或凭据存储失败时回答 false，因为 `search()` 会在该次读取上失败，而不会尝试下一种凭据。`dsh-web-deepseek-api` 的 Search 与 Fetch API 提供方共用一份凭据，并对其 API 基础地址以同样方式回答；它们的传输层重复了这些检查，因此两个包互不依赖。提供方不点名任何工具或提示词段落。
+- **Consumer。** `dsh-tool-web` 注册 `web_search` 与 `web_fetch` 时各带一个[步骤激活条件](../../../../packages/core/tools/README.zh.md#conditional-tools)，以该步骤模型选择的路由询问 `ctx.web.searchReady()` 与 `ctx.web.fetchReady()`。agent loop 在组装该步骤之前解析各条件，因此声明的工具、`tool:web_search` 与 `tool:web_fetch` 提示词段落、PTC 程序绑定与派发都读取同一个准入集合。
+
+路由只决定是否在 API 密钥之前检查账号 token，这只发生在 `deepseek-account` 路由上；API 密钥在任何路由上都算数，因此只要配置了 DeepSeek 密钥，使用其他提供方模型的对话也会获得 DeepSeek Web 工具。提供方不比较聊天路由的地址与自己的端点：即使官方路由经网关聊天，每次操作也把配置的密钥（默认 `DEEPSEEK_API_KEY`）发往配置的端点。
+
+只看凭据是否存在：不读取 API 密钥的值，也不访问任何端点，因此错误的密钥，或不提供原生 `web_search_20250305` 服务器工具的端点，仍会让该工具保持准入。未准入某个 Web 工具的步骤也会以 `UNKNOWN_TOOL` 拒绝对它的调用，因此模型重复先前的调用也到达不了任何提供方；在模型步骤之外发起的操作在运行时解析凭据，没有凭据时以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败。
+
+请求头记录组装后的工具，因此 agent loop（智能体循环）通过工具注册表更新宣告每次变化。路由切换、存储密钥或删除密钥都会改变下一个请求；DeepSeek 路由以延迟加载的新增方式载入重新提供的工具，不支持工具更新的路由则接收完整工具列表。
+
+## Alternatives considered
+
+**让 DeepSeek 提供方在自己的 assemble 监听器中移除 `web_search`。** seam 保持不变，但提供方因此要点名另一个包的工具、提示词段落与 PTC 传输工具；而且即使部署选择了另一个搜索成功的提供方（例如 Exa），它也会移除该工具。
+
+**扩展 `available()`。** 它是同步的且不接收请求，而这项检查要读取异步凭据存储，并取决于请求的路由。依赖路由的 `available()` 还会让提供方选择取决于对话。
+
+**从会话最近的 `request/context` 事件读取路由，而不是传入路由。** 该事件记录的是上一个请求，因此新会话的首个请求，以及模型切换后的首个请求，会按错误的路由判断，或根本没有路由可用。
+
+**在 `dsh-tool-web` 中注册或注销 `web_search`。** 注册由同一 agent preset 的所有会话共享，而凭据取决于每个请求的路由。注销还会使点名 `web_search` 的 `toolOrder` 条目和 subagent `toolFilter` 限制失败。
+
+**从组装好的请求中移除 `web_search`。** `system-prompt/assemble` 监听器可以删掉该声明及其段落，但工具仍可执行，因此模型重复先前的调用时仍会运行它，PTC 程序也仍能绑定它。提示词组装也已不再携带工具声明。
+
+**只在 DeepSeek 账号路由上提供搜索。** 账号 token 只对官方端点签发，因此网关的密钥不可能到达 DeepSeek。但所有发行 profile 的默认路由都是 `deepseek-official`，搜索会因此默认关闭，连官方 API 密钥的情况也一并关闭。
+
+**除非搜索有自己的密钥，否则不向其他提供方的对话提供这些工具。** 其他模型对话中的搜索会由 DeepSeek 密钥计费，但 DeepSeek 搜索本就是该密钥付费使用的服务之一，配置了它的用户也期望无论用哪个模型对话，搜索都能用。Web 搜索设置页把密钥存在 `apiKeyEnv` 指向的引用下，默认是聊天路由也在读取的 `DEEPSEEK_API_KEY`，因此在那里输入的密钥永远无法服务其他模型；再加一个开放这些路由的 `routes` 配置项，只会让用户多找一样东西。
+
+**比较官方聊天路由的端点与搜索端点。** 两个端点不同源时撤下工具或不发送密钥，能让网关的密钥远离 DeepSeek，但提供方得自己找出聊天路由的配置。取第一条激活的 `dsh-llm-deepseek-api-key` Loader 行时，如果组合隔离了多个实例，回答的可能是无关的实例，从而关掉正确的路由，或放过网关的密钥；只有路由的所有者知道哪个端点服务某个请求，而在 `dsh-llm` 加地址字段会让它经 Remote 方法 `listProviders()` 进入浏览器。这项检查还会让经代理或开发端点对话、而密钥能被官方搜索端点接受的用户失去搜索。不做这项检查时，网关用户的搜索会在配置的端点上失败。
+
+**保持工具可见，在执行时失败。** 模型会把一次调用花在无法鉴权的搜索上，并且每次尝试都会重复失败。
+
+**提供工具前探测密钥或端点。** 每个模型请求都发起一次网络请求会增加延迟与成本；用户控制的是配置本身，而不是它在那一刻是否有效。
+
+## Consequences
+
+`dsh-web` 增加以下公共成员：两个提供方接口上可选的 `ready()`、`WebRuntime.searchReady()` 与 `WebRuntime.fetchReady()`。每个就绪方法都是其唯一消费方所需的最小查询，这正是[观测接口决策](../../archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md)允许状态查询回归的方式；它们既不报告可用性，也不报告选择失败。Exa、Perplexity 与 HTTP 抓取提供方没有实现 `ready()`，其行为不变；只要开关让 HTTP 抓取保持选中，`web_fetch` 就始终准入。未准入某个 Web 工具的步骤，其 PTC 程序绑定中也没有它。无法提供原生服务器工具的端点仍会让工具保持准入，并使每次调用失败。在路由不变时移除工具会改变声明的工具，并使提示词缓存失效一次；模型切换本身已经使缓存失效。其他提供方对话中的搜索与抓取由配置的 DeepSeek 密钥计费；官方路由经网关对话的部署会把网关的密钥发往配置的端点（默认是官方端点），除非该端点接受这个密钥，否则每次操作都会失败。DeepSeek Web 包不读取 Loader 的行，也不依赖任何 LLM 包。
+
+单元测试分别固定每个角色：`packages/web/web/tests/web.spec.ts` 覆盖 `searchReady()` 与 `fetchReady()` 询问哪个提供方以及选择失败时的回答，`packages/web/web-search-deepseek/tests/deepseek.spec.ts` 与 `packages/web/web-deepseek-api/tests/readiness.spec.ts` 覆盖 `ready()` 在账号路由与其他路由上的每种凭据情况，`packages/web/tool-web/tests/tool-web.spec.ts` 通过真实的提示词、工具与执行器服务解析两个工具的步骤准入，包括在撤下该工具的步骤中调用它时以 `UNKNOWN_TOOL` 拒绝。在真实组合中，发行版 headless 无密钥冒烟测试与 `web-search-unconfigured` 录制会话快照的搜索密钥引用都未设置，二者固定了搜索工具的撤下行为。快照回放提供占位 DeepSeek 密钥，因此其工具列表不依赖运行环境；借助该密钥，`pi-ai-conversation-updates` 中 pi-ai 路由上的对话保留 `web_search`。
@@ -27,17 +27,17 @@
  en: a01ac57fc71a84f0
  zh: 3e488ef3da5e4b8c
 /agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control:
-  en: a55516339b0d49dd
-  zh: 3281df9ea7878fc0
+  en: 725a2d4145c0a75e
+  zh: b98a64532cadeaba
 /agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/correspondence-with-rbac:
  en: a78a2410eb52f777
  zh: a868bf1b0e690c9f
 /agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/resources-and-resource-readers-deepseek-ai-dsh-typert-protocol-deepseek-ai-dsh-typert-registry:
-  en: 625b20552962e268
-  zh: 1136c0fd7cdc6901
+  en: d50ae22978165c57
+  zh: 8c1fcfb7dc2d3367
 /agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/endpoint-resources:
-  en: ec1677d8e338e115
-  zh: 6bedd163f208eaa9
+  en: 056a141b31270cba
+  zh: 3f6caafb3a13c192
 /agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/roles-bindings-and-policies-deepseek-ai-dsh-api-remote-access:
  en: e57f396239ea9f56
  zh: ddb26278b1521ceb
@@ -45,8 +45,8 @@
  en: 3c911f57f0f6ca4b
  zh: 1509781eeda4c922
 /agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/host-access-check-order:
-  en: 6c58dc8777e107ef
-  zh: bc14605c96e4d8f3
+  en: 2d97a251cc4c9db0
+  zh: df072d5a96a9e82f
 /agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/forwarded-events:
  en: 5fe34ee5ec31942a
  zh: ef39b020b0539b8f
@@ -54,8 +54,8 @@
  en: 7865e159528e2d30
  zh: 1399d54632f4d926
 /agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/access-snapshot-stream:
-  en: 41d7ac1faf2448d7
-  zh: 6d523895a9abae68
+  en: a928a63e8c36177c
+  zh: c943c1fdc8c4bb45
 /agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/client-face:
  en: 7be28cd7e19e5377
  zh: 30b5aee957271d6c
@@ -75,14 +75,14 @@
  en: 305ec45a7cd85ed7
  zh: d2cd4209a56b1d0c
 /agent-note-peer-principals-and-method-level-remote-access-control/alternatives-considered:
-  en: 130df2981ba550df
-  zh: e9a0a89af6fb50a3
+  en: 60da38bca6e9c3d6
+  zh: 61ea578fe8185b61
 /agent-note-peer-principals-and-method-level-remote-access-control/consequences:
  en: 89452c3c3f042e75
  zh: 9bcad00a60c65303
 /agent-note-peer-principals-and-method-level-remote-access-control/consequences/verification:
-  en: 048067eb02e6bf8a
-  zh: 12508b59f6b206b8
+  en: d7d0909974609247
+  zh: 6ebf20714f8d545b
 /agent-note-peer-principals-and-method-level-remote-access-control/consequences/costs-and-limits:
  en: 1e254cec680b1a37
  zh: 06a31e057ba965aa
@@ -131,7 +131,7 @@ The single read point is `this.ctx.invocation.peer.principal`; an owner test is

 ### Method-level access control

-Resource types and the `resources` readers of `@Remote` live in `@deepseek-ai/dsh-typert-protocol`; resource kinds live in typert beside lookups and Contexts: `TypertResourceMap` declares the kinds, `typert.resources` holds each kind's default wire field, and lookups and Host Context adapters declare the resource kind their wire identity names. The Gateway resolves one call or forwarded event to the resources it touches. Decisions, list filtering, and the access snapshot live in the new package `@deepseek-ai/dsh-api-remote-access` (`packages/api/remote-access`), which reads no argument field. The Gateway and domain packages depend on remote-access only for types and inject `remoteAccess`; their only value dependency is `dsh-typert-protocol`, so `package-dependency-policy` gains no remote-access entry. Business packages define and register roles, bindings, and policies; liveshare is the first user. Apart from the built-in `global`, no resource-kind name appears in remote-access or the Gateway, which follows the [`packages/api` carries generic orchestration only](../../../../docs/defensive-patterns/remote-and-api.md) review rule.
+Resource types and the `resources` readers of `@Remote` live in `@deepseek-ai/dsh-typert-protocol`; resource kinds live in typert beside lookups and Contexts: `TypertResourceMap` declares the kinds, `typert.resources` holds each kind's default wire field or resolver, and lookups and Host Context adapters declare the resource kind their wire identity names. The Gateway resolves one call or forwarded event to the resources it touches. Decisions, list filtering, and the access snapshot live in the new package `@deepseek-ai/dsh-api-remote-access` (`packages/api/remote-access`), which reads no argument field. The Gateway and domain packages depend on remote-access only for types and inject `remoteAccess`; their only value dependency is `dsh-typert-protocol`, so `package-dependency-policy` gains no remote-access entry. Business packages define and register roles, bindings, and policies; liveshare is the first user. Apart from the built-in `global`, no resource-kind name appears in remote-access or the Gateway, which follows the [`packages/api` carries generic orchestration only](../../../../docs/defensive-patterns/remote-and-api.md) review rule.

 #### Correspondence with RBAC

@@ -165,7 +165,7 @@ export interface TypertResourceMap {}
 //   @deepseek-ai/dsh-workspace/types: workspace: TypertResource<WorkspaceId>

 // Runtime registries in typert
-ctx.typert.resources.register(kind, { field }): TypertDisposer
+ctx.typert.resources.register(kind, { field } | { resolve }): TypertDisposer
 ctx.typert.lookups.register(key, { parameter, wire, resource?, … })   // resource: the kind its wire id names
 ctx.typert.contexts.registerHost(key, { wire, resource?, … })         // a TypertHostContextAdapter

@@ -213,11 +213,11 @@ export function RemoteScope<This extends object, Args extends unknown[], Result>

 | Rule | Content |
 |---|---|
-| Syntax | `@Remote({ name: 'page', resources: { session: (request) => request.address.kind === 'session' ? request.address.sessionId : request.address.childSessionId } })`; a Context method writes `@RemoteScope('agent')` and gets its Session resource from the Agent Context's `resource: 'session'`, and writes `@RemoteScope('agent', { resources: { workspace: (request) => request.workspaceId } })` when it needs another resource. Most methods write no `resources` and get their resources from automatic resolution |
+| Syntax | `@Remote({ name: 'prompt', resources: { session: (request) => request.sessionId } })` when a method must name its resource by hand; `session/page` and `session/follow` instead rely on the registered `session` default resolver; a Context method writes `@RemoteScope('agent')` and gets its Session resource from the Agent Context's `resource: 'session'`, and writes `@RemoteScope('agent', { resources: { workspace: (request) => request.workspaceId } })` when it needs another resource. Most methods write no `resources` and get their resources from automatic resolution |
 | Resource kinds | The lower-level packages that declare the identity types merge the resource kinds: `session: TypertResource<SessionId>` in `@deepseek-ai/dsh-session/types` and `workspace: TypertResource<WorkspaceId>` in `@deepseek-ai/dsh-workspace/types`. session-controller references the commands package, so a merge in session-controller would make commands reference session-controller and form a project-reference cycle. remote-access builds in `global`, which has no id and stays out of `TypertResourceMap`; typert reserves the name, and `typert.resources.register('global', …)` throws |
-| Default fields and declarations | The domain that owns a kind registers its default wire field when its controller is constructed: the `SessionController` constructor calls `typert.resources.register('session', { field: 'sessionId' })` and the `WorkspaceController` constructor registers `workspace` → `workspaceId`; registering a kind twice throws. The Agent, Session, and `workspaceFileScope` lookups declare `resource: 'session'`, and the agent package's Agent Context declares `resource: 'session'` |
-| Resolution precedence | Each resource kind takes, in order: ① that kind's reader in the method's `resources`; ② every lookup parameter that declares that kind as its `resource` contributes its wire identity, and an omitted optional lookup parameter contributes none; when the Context of a Context method declares that kind as its `resource`, the Context's wire identity contributes too; ③ that kind's default field: a top-level named argument of that name when one exists, otherwise that field of the first object argument. A default field names one identity, so an array there is an invalid value |
-| Argument values | Resource resolution and the `args` of `decide()` read the named arguments validated against their Typert-compiled types: each JSON argument is decoded once by its codec, which drops object fields its type does not declare, and dispatch reuses that value, so a caller cannot change the resources with an undeclared field; lookup parameters and the Context identity keep their wire identities, and no lookup or Agent is resolved at that point |
+| Default extraction declarations | The owning domain registers either `{ field }` or `{ resolve }`, never both. SessionController registers `resolveSessionResource`; WorkspaceController registers `workspaceId`. Duplicate kinds are rejected. Lookup and Host Context resource declarations remain independent of these defaults |
+| Resolution precedence | Per kind: explicit method reader, then lookup and Host Context identities, then the registered default field or resolver. A field reads the named top-level parameter or the first object argument. A resolver receives validated named `args` and ordered parameter descriptions once before lookup resolution. Defaults return one non-empty string or undefined; arrays are invalid |
+| Argument values | Compiled codecs strip undeclared object fields; SRC fallback checks JSON safety without stripping them. Resolution and dispatch use the same validated values. The Session resolver rejects a request object containing both sessionId and address, even when equal. Lookup and Context identities remain wire values until after authorization |
 | Resolution result | The resources of every kind together are the resources the call touches; with none, the call touches `[global]`; when resources resolve, only those are used and `global` is not added |
 | Readers | Called with the method's positional arguments: the named arguments mapped by the descriptor back to the method's parameter order (the validated value in a JSON position, the wire identity in a lookup position, and the call's signal in the cancellation position); return one id, an id array (every one must be allowed), or `undefined` (no resource of that kind) |
 | Invalid values | A reader that throws or returns an empty array, or a read value (including a Context's wire identity) that is not a non-empty string, makes the resources invalid: the Gateway refuses the call with `remote-access/denied` (reason `resource-invalid`) without asking `decide()` |
@@ -228,7 +228,7 @@ export function RemoteScope<This extends object, Args extends unknown[], Result>

 #### Endpoint resources

-The table lists the endpoints #3854 viewers use and where their resources come from. Only `session/page` and `session/follow` need explicit `resources`; the rest rely on a lookup's `resource` or the default field:
+The table lists the endpoints #3854 viewers use and where their resources come from. Session history endpoints use the registered Session resolver; special method readers can override defaults:

 | Endpoint | Resource | Resolution source | Filtering inside the method |
 |---|---|---|---|
@@ -241,14 +241,14 @@ The table lists the endpoints #3854 viewers use and where their resources come f
 | `llm/listProviders` | `global` | no resource | no |
 | `commands/list` | session: `args.agentId` (the Agent lookup's wire field) | Agent lookup `resource: 'session'` | no |
 | `goals/get` | session: `args.agentId` | Agent lookup `resource: 'session'` | no |
-| `session/attachment` | session: `args.request.sessionId` | default field | no |
-| `skills/list` | session: `args.request.sessionId` | default field | no |
-| `session/fork` | session: `args.request.sessionId` | default field | no |
-| `session/prompt` | session: `args.request.sessionId` | default field | no |
-| `session/cancel` | session: `args.request.sessionId` | default field | no |
-| `session/projections` | session: `args.request.sessionId` | default field | no |
-| `session/page` | session: `args.request.address.sessionId` for a Session address; `args.request.address.childSessionId` for a subagent address | `resources` | no |
-| `session/follow` | same as above | `resources` | no |
+| `session/attachment` | session: `args.request.sessionId` | default resolver | no |
+| `skills/list` | session: `args.request.sessionId` | default resolver | no |
+| `session/fork` | session: `args.request.sessionId` | default resolver | no |
+| `session/prompt` | session: `args.request.sessionId` | default resolver | no |
+| `session/cancel` | session: `args.request.sessionId` | default resolver | no |
+| `session/projections` | session: `args.request.sessionId` | default resolver | no |
+| `session/page` | session: `args.request.address.sessionId` for a Session address; `args.request.address.childSessionId` for a subagent address | default resolver | no |
+| `session/follow` | same as above | default resolver | no |
 | `remoteAccess/follow` | `global` | no resource; remote-access allows it for every principal | no |

 A subagent address reads the child transcript, so its resource is the child Session. A Client rereads the projections of known Sessions after a reconnect, including the parent of a subagent Session; a reader without a grant on that parent has its projection read refused. Whether a grant on a parent Session covers its subagent children is the policy's decision, that is, whether it gives a binding for the child Session; the generic layer derives no parent resource.
@@ -392,7 +392,7 @@ Every call path (HTTP `/api`, WebSocket streams, in-process `fetch(request, peer
 | 1 | Admission yields the Peer: network paths from Connection `admit()` (`browserPeer`), in-process paths from the caller. The Gateway checks `peer.signal` before it reads the wire payload | Failed network admission answers HTTP 401 / 403 without entering the Gateway; a disposed Peer: `gateway/peer-disposed` |
 | 2 | Resolve the endpoint and validate the argument field set (`resolveDescriptor`, `assertExactArguments`), then validate the JSON arguments against their Typert-compiled types, decoding each once | `gateway/invocation-unavailable`, `gateway/ambiguous-endpoint`, `gateway/definition-unavailable`; extra or missing fields: `gateway/arguments-invalid`; a JSON argument failing validation: `gateway/input-invalid` (for owners and non-owners alike, before the access check) |
 | 3 | Owner pass-through: for `principal.kind === 'owner'` go straight to step 5 | — |
-| 4 | Non-owner: the Gateway resolves resources from the arguments validated in step 2 (`resources` readers, then lookup parameters and the `resource` a Context declares, then default fields; lookup and Context identities are wire identities, and neither a lookup nor the Context is resolved), then asks `remoteAccess.decide({ principal, action: endpoint, resources, args })` with the validated arguments as `args`; invalid resources are refused with `resource-invalid` without asking `decide()`; a `deny` decision becomes the thrown error | `remote-access/denied` with details `{ action, reason }` |
+| 4 | Non-owner: the Gateway resolves resources from the arguments validated in step 2 (`resources` readers, then lookup parameters and the `resource` a Context declares, then the registered default field or resolver; lookup and Context identities are wire identities, and neither a lookup nor the Context is resolved), then asks `remoteAccess.decide({ principal, action: endpoint, resources, args })` with the validated arguments as `args`; invalid resources are refused with `resource-invalid` without asking `decide()`; a `deny` decision becomes the thrown error | `remote-access/denied` with details `{ action, reason }` |
 | 5 | Dispatch: `resolveReceiverContext` (which can activate an Agent), lookup resolution (JSON arguments reuse the step 2 values), and the method call | Existing codes unchanged, such as `gateway/lookup-not-found`, `gateway/context-not-found`, `gateway/input-invalid`, `gateway/service-unavailable`, `gateway/method-unavailable`, and business errors |

 The access check (steps 3–4) precedes lookup and Context resolution, so a refused call activates no Session and causes no other side effect. The only new Gateway error code is `gateway/peer-disposed`; remote-access declares the refusal code `remote-access/denied`.
@@ -446,7 +446,7 @@ export const REMOTE_ACCESS_SNAPSHOT_KEY = '__DSH_REMOTE_ACCESS__'

 | Behavior | Detail |
 |---|---|
-| First snapshot | `snapshotFor(principal)` computes a page's opening baseline. remote-access adds the global `REMOTE_ACCESS_SNAPSHOT_KEY`, set to the owner baseline `{ type: 'baseline', owner: true }`, to every index the webServer renders, through `webserver/index-inject`. A business package that renders a non-owner page (such as liveshare on the owner Host) places an assignment of that global to `snapshotFor(principal)` after every index injection row; the later assignment wins, and the Client reads the global when it mounts |
+| First snapshot | `snapshotFor(principal)` computes a page's opening baseline. The webServer renders each index for the Peer the page speaks for, and `webserver/index-inject` passes that Peer to listeners; remote-access adds the global `REMOTE_ACCESS_SNAPSHOT_KEY`, set to `snapshotFor(peer.principal)`, to every index, so the owner's page receives the owner baseline `{ type: 'baseline', owner: true }` and a page rendered for a non-owner Peer (such as a liveshare viewer page on the owner Host) receives that principal's grants. The Client reads the global when it mounts |
 | Subscription | Each Peer subscribes to one access snapshot stream, whose baseline replaces the injected one |
 | Computation | All bindings of the policy for the principal's kind are merged by equal resource; each resource's `actions` are the endpoint actions of those bindings' roles that the same decision as a call allows (one resource, without args, conditions called without args); only a resource with at least one allowed endpoint action gets a grant. Decisions and snapshots share one source: for the same principal, action, and resource (without arguments), the snapshot answer equals `decide()` |
 | Endpoint actions only | `event:<name>` actions do not enter the snapshot; the frontend decides entry visibility from endpoint actions only |
@@ -600,7 +600,7 @@ The review rule's home is the "`@Remote` marks capability methods" section of [R

 **Refusal reasons from conditions only.** Without a binding there is no condition to give a reason, so a viewer page could not tell "share expired" from "share not writable"; `explain` gives a reason only after the decision is already a refusal and never changes it.

-**A global resource-resolver registry (domain packages register recognizers by field name).** Field recognition separates from the method, nothing flags a method signature change, and same-named fields in other packages are misread; resource resolution uses a default convention on the method plus per-method `resources`, and a domain package registers only its own kind's default field.
+**A global resource-resolver registry (domain packages register recognizers by field name).** Field recognition separates from the method, nothing flags a method signature change, and same-named fields in other packages are misread; resource resolution uses a default convention on the method plus per-method `resources`, and a domain package registers only its own kind's default field or resolver.

 **Dot-path resource declarations (`'request.address.sessionId'`).** Types cannot constrain a path; the parameter types of `resources` readers are inferred from the decorated method, so a typo fails compilation.

@@ -635,10 +635,10 @@ The review rule's home is the "`@Remote` marks capability methods" section of [R
 | Check order | The owner calls any method normally without reading a policy; a method no role lists refuses non-owners with `remote-access/denied` (`no-allow`); the access check precedes lookups, so a refused call activates no Session | Gateway host spec |
 | Policy registration | One policy per non-owner principal kind, and a second registration throws; once the disposer withdraws it, that kind is refused with `no-allow`; it is withdrawn with its fiber | remote-access host spec |
 | Decisions | Every resource needs a matching binding (AND); a role without the action, an unequal resource, or a refusing condition does not allow; the refusal reason follows condition > `explain` > `no-allow`; `explain` never changes the decision; conditions receive args for calls but not for snapshots and list filtering; a throwing `bindings()`, condition, or `explain()` refuses with `policy-failed`, each policy is logged once between `invalidate()` calls, and on the event path the owner stream and the shared event source continue; `remoteAccess/follow` is allowed for every principal | remote-access host spec, Gateway host spec |
-| Resource resolution | A default field (top-level or first object argument) yields its resource; a lookup parameter that declares that kind as its `resource` yields its wire identity; a Context method gets its Session resource from the Agent Context identity in args without activating the Agent, and may declare other resources through `resources`; a `resources` reader overrides its kind, an array yields several resources, and `undefined` none; with nothing the call is `[global]`; a throw, an empty array, or a value that is not a non-empty string (including a Context identity) is invalid, refused by the Gateway with `resource-invalid` without asking `decide()`; a Context that declares no `resource` resolves by the ordinary rules; resources and `args` read the validated arguments, so an undeclared nested field changes no resource and no condition sees it, and a JSON argument failing validation returns `gateway/input-invalid` before the access check | Gateway host spec (gateway-access) |
-| Resource registry | `typert.resources` registers one default field per kind, rejects a second registration and `global`, and withdraws the registration with its fiber; a configured lookup resolver keeps the provider's `resource`; a Host Context adapter keeps its `resource` | typert-registry spec |
+| Resource resolution | A default field or resolver yields one resource; a default resolver returning an array is invalid; a lookup parameter that declares that kind as its `resource` yields its wire identity; a Context method gets its Session resource from the Agent Context identity in args without activating the Agent, and may declare other resources through `resources`; a `resources` reader overrides its kind, an array yields several resources, and `undefined` none; with nothing the call is `[global]`; a throw, an empty array, or a value that is not a non-empty string (including a Context identity) is invalid, refused by the Gateway with `resource-invalid` without asking `decide()`; a Context that declares no `resource` resolves by the ordinary rules; resources and `args` read the validated arguments, with undeclared fields stripped only by compiled codecs, and a JSON argument failing validation returns `gateway/input-invalid` before the access check | Gateway host spec (gateway-access) |
+| Resource registry | `typert.resources` registers one default field or resolver per kind, rejects a second registration and `global`, and withdraws the registration with its fiber; a configured lookup resolver keeps the provider's `resource`; a Host Context adapter keeps its `resource` | typert-registry spec |
 | Forwarded events | A non-owner `$events` stream receives an event, whole, only when `event:<name>` is granted on its resources; an event that declares no resources is decided on `global`; an event whose reader returns `undefined` does not reach non-owners, and `decide()` is not asked; the owner receives all | Gateway host spec (gateway-access) |
-| First snapshot | `snapshotFor()` returns the owner baseline or the principal's grants; remote-access injects the owner baseline into every rendered index; the Client starts from the injected baseline and rejects a malformed one | remote-access host and client specs |
+| First snapshot | `snapshotFor()` returns the owner baseline or the principal's grants; remote-access injects the snapshot of the Peer each index speaks for; the Client starts from the injected baseline and rejects a malformed one | remote-access host and client specs |
 | Type inference | The parameter types of `resources` readers are inferred from the method; lookup positions have wire types; a missing property, more parameters than the method has, and a `global` key fail compilation; a binding whose resource kind differs from its role's fails compilation | typert-protocol spec, remote-access spec (type tests) |
 | List filtering | `session/list`, `session/search`, `session/control`, and `workspace/follow` return non-owners only items for which `allows()` is true; `workspace/follow` sends a `replace` increment when a delivered Workspace loses visibility, and the Workspace reappears once access returns; owner results are unchanged | session-controller / workspace-controller host spec |
 | Access snapshots | The allowed set in a snapshot equals the Host decision for the same principal, action, and resource without arguments; it contains endpoint actions only; a resource with no allowed action gets no grant, and one whose allowed set becomes empty is removed; `invalidate()` and policy registration or removal push increments; a wait that a change ends leaves no abort listener behind; unloading the service ends every open snapshot stream; the owner receives only `{ owner: true }` | remote-access host spec |
@@ -131,7 +131,7 @@ export function principalOf(invocation: RemoteInvocation | undefined): Principal

 ### 方法级访问控制

-资源类型与 `@Remote` 的 `resources` 读取函数在 `@deepseek-ai/dsh-typert-protocol`；资源种类在 typert 中与 lookups、Contexts 并列：`TypertResourceMap` 声明种类，`typert.resources` 保存每个种类的默认 wire 字段，lookup 与 Host Context adapter 声明其 wire 身份所属的资源种类。Gateway 把一次调用或一个转发事件解析为它访问的资源。判定、列表过滤与访问快照在新包 `@deepseek-ai/dsh-api-remote-access`（`packages/api/remote-access`），该包不读取任何参数字段。Gateway 与领域包对 remote-access 只做 type-only 依赖并 inject `remoteAccess`，值依赖只有 `dsh-typert-protocol`，不为 remote-access 新增 `package-dependency-policy` 条目。role、binding 与 policy 由业务包定义和注册，liveshare 为首个使用方。除内置的 `global` 外，remote-access 与 Gateway 中不出现任何资源种类名，符合 [`packages/api` 只承载通用编排](../../../../docs/defensive-patterns/remote-and-api.zh.md) 的评审规则。
+资源类型与 `@Remote` 的 `resources` 读取函数在 `@deepseek-ai/dsh-typert-protocol`；资源种类在 typert 中与 lookups、Contexts 并列：`TypertResourceMap` 声明种类，`typert.resources` 保存每个种类的默认 wire 字段或 resolver，lookup 与 Host Context adapter 声明其 wire 身份所属的资源种类。Gateway 把一次调用或一个转发事件解析为它访问的资源。判定、列表过滤与访问快照在新包 `@deepseek-ai/dsh-api-remote-access`（`packages/api/remote-access`），该包不读取任何参数字段。Gateway 与领域包对 remote-access 只做 type-only 依赖并 inject `remoteAccess`，值依赖只有 `dsh-typert-protocol`，不为 remote-access 新增 `package-dependency-policy` 条目。role、binding 与 policy 由业务包定义和注册，liveshare 为首个使用方。除内置的 `global` 外，remote-access 与 Gateway 中不出现任何资源种类名，符合 [`packages/api` 只承载通用编排](../../../../docs/defensive-patterns/remote-and-api.zh.md) 的评审规则。

 #### 与 RBAC 的对应

@@ -165,7 +165,7 @@ export interface TypertResourceMap {}
 //   @deepseek-ai/dsh-workspace/types: workspace: TypertResource<WorkspaceId>

 // Runtime registries in typert
-ctx.typert.resources.register(kind, { field }): TypertDisposer
+ctx.typert.resources.register(kind, { field } | { resolve }): TypertDisposer
 ctx.typert.lookups.register(key, { parameter, wire, resource?, … })   // resource: the kind its wire id names
 ctx.typert.contexts.registerHost(key, { wire, resource?, … })         // a TypertHostContextAdapter

@@ -213,11 +213,11 @@ export function RemoteScope<This extends object, Args extends unknown[], Result>

 | 规则 | 内容 |
 |---|---|
-| 写法 | `@Remote({ name: 'page', resources: { session: (request) => request.address.kind === 'session' ? request.address.sessionId : request.address.childSessionId } })`；Context 方法写 `@RemoteScope('agent')`，由 Agent Context 的 `resource: 'session'` 得到会话资源，需要其他资源时写 `@RemoteScope('agent', { resources: { workspace: (request) => request.workspaceId } })`。多数方法不写 `resources`，由自动解析得到资源 |
+| 写法 | 方法必须手工点名资源时写 `@Remote({ name: 'prompt', resources: { session: (request) => request.sessionId } })`；`session/page` 与 `session/follow` 则依赖已注册的 `session` 默认 resolver；Context 方法写 `@RemoteScope('agent')`，由 Agent Context 的 `resource: 'session'` 得到会话资源，需要其他资源时写 `@RemoteScope('agent', { resources: { workspace: (request) => request.workspaceId } })`。多数方法不写 `resources`，由自动解析得到资源 |
 | 资源种类 | 资源种类由声明 id 类型的底层包合并：`session: TypertResource<SessionId>` 在 `@deepseek-ai/dsh-session/types`，`workspace: TypertResource<WorkspaceId>` 在 `@deepseek-ai/dsh-workspace/types`。session-controller 引用 commands 包，若在 session-controller 合并，commands 要引用 session-controller，形成 project reference 环。`global` 由 remote-access 内置，没有 id，不进 `TypertResourceMap`；typert 保留该名，`typert.resources.register('global', …)` 抛错 |
-| 默认字段与声明 | 拥有该种类的领域在控制器构造时登记默认 wire 字段：`SessionController` 构造函数调用 `typert.resources.register('session', { field: 'sessionId' })`，`WorkspaceController` 构造函数登记 `workspace` → `workspaceId`；同一种类重复登记即抛错。Agent、Session 与 `workspaceFileScope` lookup 声明 `resource: 'session'`，agent 包的 Agent Context 声明 `resource: 'session'` |
-| 解析优先级 | 对每个资源种类依次取：① 该方法 `resources` 中该种类的读取函数；② 声明了该种类 `resource` 的每个 lookup 参数贡献其 wire 身份，省略的可选 lookup 参数不贡献；Context 方法的 Context 声明了该种类 `resource` 时，其 wire 身份同样贡献；③ 该种类的默认字段：命名参数中有同名顶层参数就读它，否则读第一个对象参数的同名字段。默认字段只表示一个身份，读到数组即为非法值 |
-| 参数来源 | 资源解析与 `decide()` 的 `args` 读取经 Typert 编译类型校验后的命名参数：每个 JSON 参数由其 codec 解码一次，类型未声明的对象字段被移除，分派复用该值，因此调用方无法用未声明字段改变资源；lookup 参数与 Context 身份取 wire 身份，此时不解析 lookup、不激活 Agent |
+| 默认提取声明 | 资源所属领域登记 `{ field }` 或 `{ resolve }`，两者互斥。SessionController 登记 `resolveSessionResource`；WorkspaceController 登记 `workspaceId`。重复种类被拒绝；lookup 和 Host Context 的资源声明独立于默认规则 |
+| 解析优先级 | 每个种类依次采用方法显式 reader、lookup 与 Host Context 身份、注册的默认字段或 resolver。字段读取同名顶层参数或首个对象参数。resolver 在 lookup 解析前调用一次，接收已校验的命名 `args` 及有序参数描述。默认规则返回一个非空字符串或 undefined，数组非法 |
+| 参数来源 | 编译 codec 移除未声明的对象字段；SRC fallback 只检查 JSON 安全性，不移除字段。解析和分派使用相同的已校验值。Session resolver 拒绝同时包含 sessionId 与 address 的请求对象，即使两者相同。lookup 和 Context 身份在授权完成前保持 wire 值 |
 | 解析结果 | 各种类的资源合在一起即本次调用访问的资源；一个都没有即 `[global]`；解析出资源时只用这些资源，不附加 `global` |
 | 读取函数 | 以方法的位置参数调用：按描述符把命名参数映射回方法参数顺序（JSON 位为校验后的值，lookup 位为 wire 身份，取消参数位为调用的 signal）；返回一个 id、id 数组（每个都须被允许）或 `undefined`（该种类无资源） |
 | 非法值 | 读取函数抛错或返回空数组，或读到的值（含 Context 的 wire 身份）不是非空字符串即资源非法：Gateway 不询问 `decide()`，直接以 `remote-access/denied`（reason `resource-invalid`）拒绝调用 |
@@ -228,7 +228,7 @@ export function RemoteScope<This extends object, Args extends unknown[], Result>

 #### 端点的资源

-下表列出 #3854 读者用到的端点及其资源来源。只有 `session/page` 与 `session/follow` 需要显式 `resources`，其余靠 lookup 的 `resource` 或默认字段：
+下表列出 #3854 读者用到的端点及其资源来源。Session 历史端点使用注册的 Session resolver；特殊方法可用显式 reader 覆盖默认规则：

 | 端点 | 资源 | 解析来源 | 方法内过滤 |
 |---|---|---|---|
@@ -241,14 +241,14 @@ export function RemoteScope<This extends object, Args extends unknown[], Result>
 | `llm/listProviders` | `global` | 无资源 | 否 |
 | `commands/list` | session：`args.agentId`（Agent lookup 的 wire 字段） | Agent lookup `resource: 'session'` | 否 |
 | `goals/get` | session：`args.agentId` | Agent lookup `resource: 'session'` | 否 |
-| `session/attachment` | session：`args.request.sessionId` | 默认字段 | 否 |
-| `skills/list` | session：`args.request.sessionId` | 默认字段 | 否 |
-| `session/fork` | session：`args.request.sessionId` | 默认字段 | 否 |
-| `session/prompt` | session：`args.request.sessionId` | 默认字段 | 否 |
-| `session/cancel` | session：`args.request.sessionId` | 默认字段 | 否 |
-| `session/projections` | session：`args.request.sessionId` | 默认字段 | 否 |
-| `session/page` | session：Session 地址读 `args.request.address.sessionId`；subagent 地址读 `args.request.address.childSessionId` | `resources` | 否 |
-| `session/follow` | 同上 | `resources` | 否 |
+| `session/attachment` | session：`args.request.sessionId` | 默认 resolver | 否 |
+| `skills/list` | session：`args.request.sessionId` | 默认 resolver | 否 |
+| `session/fork` | session：`args.request.sessionId` | 默认 resolver | 否 |
+| `session/prompt` | session：`args.request.sessionId` | 默认 resolver | 否 |
+| `session/cancel` | session：`args.request.sessionId` | 默认 resolver | 否 |
+| `session/projections` | session：`args.request.sessionId` | 默认 resolver | 否 |
+| `session/page` | session：Session 地址读 `args.request.address.sessionId`；subagent 地址读 `args.request.address.childSessionId` | 默认 resolver | 否 |
+| `session/follow` | 同上 | 默认 resolver | 否 |
 | `remoteAccess/follow` | `global` | 无资源；remote-access 对任何 principal 放行 | 否 |

 subagent 地址读取的是子会话转录，因此其资源是子会话。Client 在重连后会重新读取已知会话的 projections，其中包括 subagent 会话的父会话；没有该父会话授权的读者，其 projection 读取被拒。父会话的授权是否覆盖其 subagent 子会话由 policy 决定，即是否为子会话给出 binding；通用层不推导父资源。
@@ -392,7 +392,7 @@ const childPrompt = child => ({ action, args }) =>
 | 1 | 准入得到 Peer：网络路径由 Connection `admit()` 给出（`browserPeer`）；进程内路径由调用方传入。Gateway 在读取 wire payload 之前检查 `peer.signal` | 网络准入失败返回 HTTP 401 / 403（不进入 Gateway）；Peer 已 dispose：`gateway/peer-disposed` |
 | 2 | 解析端点并做参数字段集校验（`resolveDescriptor`、`assertExactArguments`），再按 Typert 编译类型校验 JSON 参数，每个参数解码一次 | `gateway/invocation-unavailable`、`gateway/ambiguous-endpoint`、`gateway/definition-unavailable`；字段多余或缺失：`gateway/arguments-invalid`；JSON 参数校验失败：`gateway/input-invalid`（owner 与非 owner 相同，先于访问检查） |
 | 3 | owner 直通：`principal.kind === 'owner'` 时直接进入第 5 步 | — |
-| 4 | 非 owner：Gateway 从第 2 步校验后的参数解析资源（`resources` 读取函数、其次 lookup 参数与 Context 声明的 `resource`、再次默认字段；lookup 与 Context 身份取 wire 身份，不解析 lookup 与 Context），再以校验后的参数为 `args` 询问 `remoteAccess.decide({ principal, action: endpoint, resources, args })`；资源非法时不询问 `decide()`，直接以 `resource-invalid` 拒绝；`deny` 结论变为抛出的错误 | `remote-access/denied`，details `{ action, reason }` |
+| 4 | 非 owner：Gateway 从第 2 步校验后的参数解析资源（`resources` 读取函数、其次 lookup 参数与 Context 声明的 `resource`、再次注册的默认字段或 resolver；lookup 与 Context 身份取 wire 身份，不解析 lookup 与 Context），再以校验后的参数为 `args` 询问 `remoteAccess.decide({ principal, action: endpoint, resources, args })`；资源非法时不询问 `decide()`，直接以 `resource-invalid` 拒绝；`deny` 结论变为抛出的错误 | `remote-access/denied`，details `{ action, reason }` |
 | 5 | 分派：`resolveReceiverContext`（可能激活 Agent）、lookup 解析（JSON 参数复用第 2 步的值）、调用方法 | 既有错误码不变，如 `gateway/lookup-not-found`、`gateway/context-not-found`、`gateway/input-invalid`、`gateway/service-unavailable`、`gateway/method-unavailable` 与业务错误 |

 鉴权（第 3–4 步）位于 lookup 与 Context 解析之前，未授权调用不会激活会话或产生其他副作用。Gateway 新增的错误码只有 `gateway/peer-disposed`；拒绝码 `remote-access/denied` 由 remote-access 声明。
@@ -446,7 +446,7 @@ export const REMOTE_ACCESS_SNAPSHOT_KEY = '__DSH_REMOTE_ACCESS__'

 | 行为 | 说明 |
 |---|---|
-| 首份快照 | `snapshotFor(principal)` 计算页面打开时的 baseline。remote-access 经 `webserver/index-inject` 为 webServer 渲染的每个 index 加入全局变量 `REMOTE_ACCESS_SNAPSHOT_KEY`，值为 owner baseline `{ type: 'baseline', owner: true }`。渲染非 owner 页面的业务包（例如 owner Host 上的 liveshare）在所有 index 注入行之后放置一条把该全局变量赋值为 `snapshotFor(principal)` 的语句；后写的赋值生效，Client 在挂载时读取该全局变量 |
+| 首份快照 | `snapshotFor(principal)` 计算页面打开时的 baseline。webServer 按页面所代表的 Peer 渲染 index，`webserver/index-inject` 把该 Peer 传给监听方；remote-access 为每个 index 加入全局变量 `REMOTE_ACCESS_SNAPSHOT_KEY`，值为 `snapshotFor(peer.principal)`，owner 页面因此得到 owner baseline `{ type: 'baseline', owner: true }`，为非 owner Peer 渲染的页面（例如 owner Host 上的 liveshare 读者页）得到该 principal 的 grant。Client 在挂载时读取该全局变量 |
 | 订阅 | 每个 Peer 订阅一条访问快照流，其 baseline 取代注入的快照 |
 | 计算 | 取该 principal kind 的 policy 的全部 binding，按资源相等归并；每个资源的 `actions` 为这些 binding 的 role 中、经与调用相同的判定（单个资源、不带 args，condition 以无 args 调用）放行的端点 action；只为至少放行一个端点 action 的资源给出 grant。判定与快照同源：同一 principal、action 与资源（不带参数）上，快照答案与 `decide()` 一致 |
 | 只含端点 action | `event:<name>` action 不进入快照；前端只据端点 action 决定入口显隐 |
@@ -600,7 +600,7 @@ GlobalStandardProps.useWorkspaceAccess: (workspaceId: WorkspaceId, action: Remot

 **拒绝原因只由 condition 给出。** 没有 binding 时没有 condition 可以给出原因，读者页面无法区分「分享已过期」「分享不允许写入」等情况；`explain` 只在结论已为拒绝后给出原因，不改变结论。

-**全局资源 resolver 注册表（领域包按字段名注册识别函数）。** 字段识别与方法分离，方法改签名时无人提醒，跨包同名字段也会被误认；资源解析采用方法上的默认约定加 per-method `resources`，领域包只登记自己种类的默认字段。
+**全局资源 resolver 注册表（领域包按字段名注册识别函数）。** 字段识别与方法分离，方法改签名时无人提醒，跨包同名字段也会被误认；资源解析采用方法上的默认约定加 per-method `resources`，领域包只登记自己种类的默认字段或 resolver。

 **按点路径声明资源（`'request.address.sessionId'`）。** 路径无法由类型推导约束；`resources` 读取函数的参数类型从被装饰方法推断，拼错即编译失败。

@@ -635,10 +635,10 @@ GlobalStandardProps.useWorkspaceAccess: (workspaceId: WorkspaceId, action: Remot
 | 鉴权顺序 | owner 调用任何方法照常分派且不读取 policy；没有 role 列出的方法对非 owner 以 `remote-access/denied`（`no-allow`）拒绝；访问检查早于 lookup，被拒调用不激活会话 | Gateway host spec |
 | policy 注册 | 每个非 owner principal kind 一个 policy，重复注册抛错；disposer 撤回后该 kind 以 `no-allow` 拒绝；随 fiber 撤回 | remote-access host spec |
 | 判定 | 每个资源都需要匹配的 binding（AND）；role 不含该 action、资源不相等或 condition 拒绝都不放行；拒绝原因按 condition > `explain` > `no-allow` 取；`explain` 不改变结论；condition 在调用时收到 args，在快照与列表过滤时不收；`bindings()`、condition 或 `explain()` 抛错以 `policy-failed` 拒绝，每个 policy 在两次 `invalidate()` 之间只记录一次日志，事件路径上 owner 流与共享事件源照常；`remoteAccess/follow` 对任何 principal 放行 | remote-access host spec、Gateway host spec |
-| 资源解析 | 默认字段（顶层或首个对象参数）得到对应资源；声明了该种类 `resource` 的 lookup 参数得到其 wire 身份；Context 方法从 args 中的 Agent Context 身份得到其 session 资源且不激活 Agent，另可经 `resources` 声明其他资源；`resources` 读取函数覆盖该种类，数组为多个资源，`undefined` 为无；都没有为 `[global]`；抛错、空数组或非非空字符串（含 Context 身份）为非法，Gateway 以 `resource-invalid` 拒绝且不询问 `decide()`；未声明 `resource` 的 Context 按普通规则解析；资源与 `args` 读取校验后的参数，未声明的嵌套字段不改变资源、condition 也读不到它，JSON 参数校验失败在访问检查前返回 `gateway/input-invalid` | Gateway host spec（gateway-access） |
-| 资源注册表 | `typert.resources` 每个种类登记一个默认字段，拒绝重复登记与 `global`，并随 fiber 撤回；配置的 lookup resolver 保留 provider 的 `resource`；Host Context adapter 保留其 `resource` | typert-registry spec |
+| 资源解析 | 默认字段或 resolver 得到一个资源，默认 resolver 返回数组为非法；声明了该种类 `resource` 的 lookup 参数得到其 wire 身份；Context 方法从 args 中的 Agent Context 身份得到其 session 资源且不激活 Agent，另可经 `resources` 声明其他资源；`resources` 读取函数覆盖该种类，数组为多个资源，`undefined` 为无；都没有为 `[global]`；抛错、空数组或非非空字符串（含 Context 身份）为非法，Gateway 以 `resource-invalid` 拒绝且不询问 `decide()`；未声明 `resource` 的 Context 按普通规则解析；资源与 `args` 读取校验后的参数，只有编译 codec 才移除未声明字段，JSON 参数校验失败在访问检查前返回 `gateway/input-invalid` | Gateway host spec（gateway-access） |
+| 资源注册表 | `typert.resources` 每个种类登记一个默认字段或 resolver，拒绝重复登记与 `global`，并随 fiber 撤回；配置的 lookup resolver 保留 provider 的 `resource`；Host Context adapter 保留其 `resource` | typert-registry spec |
 | 转发事件 | 非 owner 的 `$events` 流只在 `event:<name>` 于其资源上被授权时整条收到事件；未声明资源的事件按 `global` 判定；读取函数返回 `undefined` 的事件不送达非 owner，且不询问 `decide()`；owner 全部收到 | Gateway host spec（gateway-access） |
-| 首份快照 | `snapshotFor()` 返回 owner baseline 或该 principal 的 grant；remote-access 为渲染的每个 index 注入 owner baseline；Client 从注入的 baseline 起步并拒绝格式错误的快照 | remote-access host 与 client spec |
+| 首份快照 | `snapshotFor()` 返回 owner baseline 或该 principal 的 grant；remote-access 为每个 index 注入其所代表 Peer 的快照；Client 从注入的 baseline 起步并拒绝格式错误的快照 | remote-access host 与 client spec |
 | 类型推断 | `resources` 读取函数的参数类型从方法推断；lookup 位为 wire 类型；访问不存在的属性、参数多于方法参数与 `global` 键编译失败；binding 的资源种类与 role 不符编译失败 | typert-protocol spec、remote-access spec（类型测试） |
 | 列表过滤 | `session/list`、`session/search`、`session/control`、`workspace/follow` 对非 owner 只返回 `allows()` 为 true 的项；已下发工作区失去可见性时 `workspace/follow` 发送 `replace` 增量帧，访问恢复后该工作区重新出现；owner 结果不变 | session-controller / workspace-controller host spec |
 | 访问快照 | 快照中的允许集合与 Host 对同一 principal、action、资源（不带参数）的判定一致；只含端点 action；没有放行 action 的资源不出 grant，放行集合变空时推送 `remove`；`invalidate()` 与 policy 注册、撤回后推送增量；被变化结束的等待不残留 abort 监听器；卸载服务即结束所有打开的快照流；owner 只收 `{ owner: true }` | remote-access host spec |
@@ -9,8 +9,8 @@
  en: f96bf1ebc0719fb0
  zh: e9a1144f0e76572d
 /agent-note-background-hover-and-screenshot-coordinates/decision:
-  en: 0cdd295d5f1872ed
-  zh: fe03ec9f7df94a4a
+  en: 0f45528ea6c5988c
+  zh: 9bde9df417ddb1ce
 /agent-note-background-hover-and-screenshot-coordinates/alternatives-considered:
  en: 5fc4beaf79761c50
  zh: 4948333b0020be28
@@ -12,7 +12,7 @@ Hover-only controls can sometimes be revealed without moving the user's pointer.

 Native hover first uses a same-window element or ancestor advertising both `AXShowAlternateUI` and `AXShowDefaultUI`. Entering its revealed descendants preserves the parent UI; leaving restores it. An unavailable route falls back to the real system pointer. An AX action failure propagates because received effects may be uncertain. The result records the route and whether the system pointer moved. System movement requires the selected foreground app and AppKit's mouse hit test, which excludes input-transparent overlays. No route grants [cross-call ownership](2026-10-13-cua-continuous-hover.md).

-Model-facing coordinate input defaults to pixels in the returned screenshot. `relative: true` accepts integer thousandths from 0 to 1000 for click, hover, scroll and drag; it does not apply to AX indices. The Host owns the mapping to native window points. An application-wide observation refreshes its inventory; a scoped observation preserves other windows' image mappings. Window resizing invalidates the old image, while movement preserves local coordinates. Relative endpoints remain inside the window and do not depend on screenshot resolution.
+Model-facing coordinate input defaults to pixels in the returned screenshot. `relative: true` accepts integer thousandths from 0 to 999 for click, hover, scroll and drag; it does not apply to AX indices. The Host owns the mapping to native window points. An application-wide observation refreshes its inventory; a scoped observation preserves other windows' image mappings. Window resizing invalidates the old image, while movement preserves local coordinates. Relative endpoints remain inside the window and do not depend on screenshot resolution.

 `LlmAdapter.imageRequestTarget` exposes the same dimensions and byte target used by image serialization. DeepSeek and pi-ai share their existing projection functions with this method. Other adapters preserve normalized images unless they declare resizing. Screenshot bytes returned to programs match the request image; its durable source is admitted and stored once. The native PNG metadata is checked against decoded source dimensions before any input mapping is published.

@@ -12,7 +12,7 @@ Status: implemented

 原生悬停优先寻找同一窗口内同时声明 `AXShowAlternateUI` 和 `AXShowDefaultUI` 的元素或祖先。进入其展开区域的子控件时保持父控件展开，离开后恢复。没有可用路径时回退到真实系统鼠标。AX 动作失败直接返回，因为已产生的效果可能不确定。结果记录实际路径及是否移动系统鼠标。系统移动要求所选应用处于前台，并使用 AppKit 的鼠标命中查询排除不接收输入的覆盖窗口。所有路径都遵守[跨调用不分配所有权](2026-10-13-cua-continuous-hover.zh.md)的决定。

-面向模型的坐标默认使用返回截图中的像素。click、hover、scroll 和 drag 传入 `relative: true` 时接受 0～1000 的千分比整数，不适用于 AX 索引。Host 负责换算原生窗口 point。应用级观察刷新窗口清单，单窗口观察保留其他窗口的图片映射。窗口尺寸变化使旧图片失效，移动窗口保留局部坐标。相对坐标的端点保持在窗口内，不随截图分辨率改变。
+面向模型的坐标默认使用返回截图中的像素。click、hover、scroll 和 drag 传入 `relative: true` 时接受 0～999 的千分比整数，不适用于 AX 索引。Host 负责换算原生窗口 point。应用级观察刷新窗口清单，单窗口观察保留其他窗口的图片映射。窗口尺寸变化使旧图片失效，移动窗口保留局部坐标。相对坐标的端点保持在窗口内，不随截图分辨率改变。

 `LlmAdapter.imageRequestTarget` 提供与图片序列化相同的尺寸和字节目标。DeepSeek 和 pi-ai 在该方法中复用已有投影函数。其他适配器除非声明缩放，否则保留归一化图片。返回程序的截图字节与模型请求图片一致，持久原图只接入并保存一次。发布输入映射前，原生 PNG 元数据必须与解码后的原图尺寸一致。

@@ -12,8 +12,8 @@
  en: a15c7c13f167e5ac
  zh: 63bcc2ef60c2f344
 /agent-note-boot-the-preview-worker-from-the-shipped-profile-and-fetch-lazy-chunks-on-demand/decision/boot-the-same-profile-as-the-served-web-deployment:
-  en: caf1ca77192dcb20
-  zh: d663e2cbb05fe4fc
+  en: 9b957e37f290abaf
+  zh: 06a4599c8fe449ad
 /agent-note-boot-the-preview-worker-from-the-shipped-profile-and-fetch-lazy-chunks-on-demand/decision/node-internal-module-interfaces-in-the-worker:
  en: 37d8e809eaa21d25
  zh: 8c7c31bd6f45c823
@@ -23,7 +23,7 @@ Measured: with no bundle enabled, the two compositions differ in only one of 188
 The served launch path (apps/cli, app-boot) carries no Preview-specific code; the webworker packages reproduce it:

 - **packer**
-  - Package roster = `PROFILE_TEMPLATES[profile].bundles` + `OPTIONAL_BUNDLES` + the rows named in those bundles' patch files; the bundle packages themselves also enter the image (patches, locale, and icon through the publish view). Both tables are read from app-boot, the same source the Plugins page uses.
+  - Package roster = `PROFILE_TEMPLATES[profile].bundles` + `OPTIONAL_BUNDLES` + the rows named in those bundles' patch files; the bundle packages themselves also enter the image (patches, locale, and icon through the publish view). Both tables are read from `@deepseek-ai/dsh-official-bundles`, the same source the Plugins page uses.
  - The image carries a manifest-only `node_modules/@deepseek-ai/dsh/package.json` (a verbatim copy of `apps/cli/package.json`) as the installation anchor, and the image manifest names it in `installation`.
  - The image carries no composed configuration and no `config/cordis.yml`; the image manifest records the `profile` the Worker boots.
  - The image carries a home patch, `home/cordis.patch.yml`: for each row the runtime's `PLATFORM_ENTRY_CONFIG` names (`session-persistence-jsonl`), the config the template's bundle layers compose with the required fields over it (`compression: none`). A patch replaces a row's whole config, so the composed fields stay; the bundle files read at pack time are the ones in the image.
@@ -23,7 +23,7 @@ Status: implemented
 正式启动链路（apps/cli、app-boot）不含 Preview 专用代码；由 webworker 包复现这条链路：

 - **packer**
-  - 收包清单 = `PROFILE_TEMPLATES[profile].bundles` + `OPTIONAL_BUNDLES` + 这些 bundle 补丁文件里的行；bundle 包本身也打进镜像（补丁、locale、icon 走 publish view）。两张表从 app-boot 读，与插件页同一来源。
+  - 收包清单 = `PROFILE_TEMPLATES[profile].bundles` + `OPTIONAL_BUNDLES` + 这些 bundle 补丁文件里的行；bundle 包本身也打进镜像（补丁、locale、icon 走 publish view）。两张表从 `@deepseek-ai/dsh-official-bundles` 读，与插件页同一来源。
  - 镜像里放一份只含清单的 `node_modules/@deepseek-ai/dsh/package.json`（原样复制 `apps/cli/package.json`），作为安装锚点，镜像 manifest 在 `installation` 里记录它。
  - 镜像不带组合好的配置，也没有 `config/cordis.yml`；镜像 manifest 记录 Worker 要启动的 `profile`。
  - 镜像带一份 home patch `home/cordis.patch.yml`：对运行时 `PLATFORM_ENTRY_CONFIG` 列出的每一行（`session-persistence-jsonl`），写入模板各 bundle 层合成出的配置，并在其上设置所需字段（`compression: none`）。补丁会整体替换一行的配置，所以保留合成出的字段；打包时读取的 bundle 文件就是镜像里的那些。
@@ -3,14 +3,14 @@
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-15-agent-teams-as-subagents.md
 /agent-note-agent-teams-teammates-are-subagents:
-  en: d74a90e6568d278a
-  zh: 538f5fa098e2e925
+  en: 51e2fc51a6e1622a
+  zh: 7e09ea6292e5921d
 /agent-note-agent-teams-teammates-are-subagents/problem:
  en: ca2848e3bbc3a009
  zh: 0551e32ff6d187d0
 /agent-note-agent-teams-teammates-are-subagents/decision:
-  en: 6e1d8ea634e8e3fc
-  zh: c9af24066de755a5
+  en: 9da65aee28d19268
+  zh: 20191b1ec59697b1
 /agent-note-agent-teams-teammates-are-subagents/alternatives-considered:
  en: ef0cf648ff54784f
  zh: 2a0b3745a54e7072
@@ -4,7 +4,7 @@ Status: implemented

 English | [中文](2026-10-15-agent-teams-as-subagents.zh.md)

-The name-free model interface below is superseded by [hierarchical agent names](2026-10-17-hierarchical-agent-names.md). Session identity, lineage authority, and Team reuse remain current. The adjacency and parent-lifetime restrictions are superseded by [tree-wide communication](2026-10-16-tree-wide-agent-communication.md). [Task-board inbox coordination](2026-10-19-team-task-board-inbox.md) supersedes the separate roster and Team-owned wait; the single subagent identity decision remains active.
+The adjacency and parent-lifetime restrictions are superseded by [tree-wide communication](2026-10-16-tree-wide-agent-communication.md). [Task-board inbox coordination](2026-10-19-team-task-board-inbox.md) supersedes the separate roster and Team-owned wait; the single subagent identity decision remains active.

 ## Problem

@@ -18,7 +18,7 @@ Use one subagent identity: the Session id. The existing `description` tool argum

 Every root Agent and its descendants form the Team identified by the root Session id. Team creates no agents and contributes task tools, task policy, and required Team identity. Ordinary subagent controls supply discovery, messaging, interruption, and inbox waiting. Parent and fork children receive identical tool schemas and shared policies.

-Model-facing task ownership uses `ownerName`; host ownership retains `ownerId`; root reassignment accepts itself or any reachable continuable descendant. Historical roster records remain decode-only. Team persists task changes and signals active waits after commit without starting idle turns. Historical `team/message/*` records remain readable but are never delivered or acknowledged.
+Task ownership uses `ownerId`; root reassignment accepts itself or any reachable continuable descendant. Historical roster records remain decode-only. Team persists task changes and signals active waits after commit without starting idle turns. Historical `team/message/*` records remain readable but are never delivered or acknowledged.

 This supersedes the roster, provisioning, recovery, and messaging decisions in [Agent Teams](../feature/2026-08-05-agent-teams.md) and the [Team direct inbox decision](../../archived/simplification/2026-09-26-team-direct-inbox.md). The task-board and shared-checkout decisions remain active. [Adjacent Agent messaging](2026-08-27-adjacent-agent-steer-messaging.md) includes sibling routing, while [required runtime-context identity](2026-10-13-team-identity-runtime-context.md) owns the role statement. The [upgrade guide](../../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.md) lists removed tools, methods, and configuration.

@@ -4,7 +4,7 @@ Status: implemented

 [English](2026-10-15-agent-teams-as-subagents.md) | 中文

-下述不使用名字的模型接口由[分层 agent 名字](2026-10-17-hierarchical-agent-names.zh.md)取代。Session 身份、谱系权限和 Team 复用仍然有效。邻接和父级生命周期限制由[整树通信](2026-10-16-tree-wide-agent-communication.zh.md)取代。[任务板收件箱协调](2026-10-19-team-task-board-inbox.zh.md)取代独立名册和 Team 所有的等待；单一 subagent 身份决策仍有效。
+邻接和父级生命周期限制由[整树通信](2026-10-16-tree-wide-agent-communication.zh.md)取代。[任务板收件箱协调](2026-10-19-team-task-board-inbox.zh.md)取代独立名册和 Team 所有的等待；单一 subagent 身份决策仍有效。

 ## Problem

@@ -18,7 +18,7 @@ Status: implemented

 每个根 Agent 及其后代组成以根 Session id 标识的 Team。Team 不创建 agent，提供任务工具、任务策略和必需 Team 身份。普通 subagent 控制工具提供发现、通信、中断和收件箱等待。父级和 fork 子级接收相同工具 schema 和共享策略。

-面向模型的任务归属使用 `ownerName`；host 归属保留 `ownerId`；根重新分配可指定自身或任意可达的可继续执行后代。历史名册记录仅供解码。Team 持久化任务变更，并在提交后通知当前等待，不启动空闲轮次。历史 `team/message/*` 记录仍可读取，但绝不再投递或确认。
+任务归属使用 `ownerId`；根重新分配可指定自身或任意可达的可继续执行后代。历史名册记录仅供解码。Team 持久化任务变更，并在提交后通知当前等待，不启动空闲轮次。历史 `team/message/*` 记录仍可读取，但绝不再投递或确认。

 本决策取代 [Agent Teams](../feature/2026-08-05-agent-teams.zh.md) 的成员列表、创建、恢复和消息决策，以及 [Team 直接收件箱决策](../../archived/simplification/2026-09-26-team-direct-inbox.md)。任务板和共享工作树决策仍有效。[相邻 Agent 消息](2026-08-27-adjacent-agent-steer-messaging.zh.md)纳入同级路由，[必需运行时身份](2026-10-13-team-identity-runtime-context.zh.md)负责角色声明。[升级指南](../../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.zh.md)列出移除的工具、方法和配置。

@@ -9,8 +9,8 @@
  en: c583c3cdb894e417
  zh: 6edc0354b79f4f26
 /agent-note-communication-follows-the-subagent-tree/decision:
-  en: d613dd690cb06596
-  zh: fab70b2107e33054
+  en: da35a75e069fa1e4
+  zh: 7edf62ad66ab04ec
 /agent-note-communication-follows-the-subagent-tree/alternatives-considered:
  en: 470f9cf8c3e32af9
  zh: 73bbe29767c5d02a
@@ -10,13 +10,13 @@ A Team shares one task board across the root's entire subagent tree. Restricting

 ## Decision

-`list_agents` starts at the caller's live root and lists that root and all reachable continuable descendants, including the caller. Parent paths and depth remain relative to the root. The existing parent catalogs remain authoritative; no Team directory is stored separately.
+`list_agents` starts at the caller's live root and lists that root and all reachable continuable descendants, including the caller. Parent ids and depth remain relative to the root. The existing parent catalogs remain authoritative; no Team directory is stored separately.

 `send_message` accepts another root or continuable member of the same tree. The sender must be the exact live root or a resident continuable subagent. Cross-branch delivery verifies the target descriptor and creation catalogs, then restores only the target under the Team root. Final inbox admission rechecks the sender and root. Cancellation or rejection before acceptance releases the new target instance; accepted input follows normal Agent persistence.

 The existing Agent registry records runtime ownership by the Team root. Creation parent ids and catalogs preserve ancestry for discovery and interrupt authority. A member finishing or being released affects only its own instance; Team-root shutdown joins all startup and cleanup. This removes ancestor restoration, parent retention, and recursive disposal without adding a Team runtime registry. Saved target presets and permission events supply restoration configuration.

-This supersedes the adjacency, discovery, and parent-lifetime restrictions in [adjacent messaging](2026-08-27-adjacent-agent-steer-messaging.md) and [subagent teammates](2026-10-15-agent-teams-as-subagents.md). Their shared inbox, scheduling, attribution, and Team reuse decisions remain active. Model tools use [hierarchical agent paths](2026-10-17-hierarchical-agent-names.md); host delivery and authorization use Session ids; ordinary Session forks lead independent Teams.
+This supersedes the adjacency, discovery, and parent-lifetime restrictions in [adjacent messaging](2026-08-27-adjacent-agent-steer-messaging.md) and [subagent teammates](2026-10-15-agent-teams-as-subagents.md). Their shared inbox, scheduling, attribution, and Team reuse decisions remain active. Members use Session ids for addressing; ordinary Session forks lead independent Teams.

 ## Alternatives considered

@@ -10,13 +10,13 @@ Status: implemented

 ## Decision

-`list_agents` 从调用方的在线根开始，列出该根与所有可达的可继续后代，包括调用方。父级路径和深度始终相对根计算。现有父级目录仍是权威来源；不单独存储 Team 目录。
+`list_agents` 从调用方的在线根开始，列出该根与所有可达的可继续后代，包括调用方。父级 id 和深度始终相对根计算。现有父级目录仍是权威来源；不单独存储 Team 目录。

 `send_message` 接受同一棵树中的其他根或可继续成员。发送者必须是确切在线根或驻留的可继续子代理。跨分支投递验证目标描述符和创建目录后，仅在 Team 根下恢复目标。最终收件箱准入重新检查发送者与根。接受前的取消或拒绝释放新建目标实例；已接受输入遵循普通 Agent 持久化。

 现有 Agent 注册表记录 Team 根对运行时实例的所有权。创建父级 id 和目录保留用于发现及中断授权的祖先关系。成员完成或释放只影响自身实例；关闭 Team 根会等待全部启动和清理。这删除了祖先恢复、父级保留和递归释放，无需增加 Team 运行时注册表。目标保存的 preset 和权限事件提供恢复配置。

-本决策替代[相邻消息](2026-08-27-adjacent-agent-steer-messaging.zh.md)与[子代理队友](2026-10-15-agent-teams-as-subagents.zh.md)中的邻接、发现及父子生命周期限制。它们的共享收件箱、调度、发送者归属和 Team 复用决策仍有效。模型工具使用[分层 agent 路径](2026-10-17-hierarchical-agent-names.zh.md)；host 投递与授权使用 Session id；普通 Session 分叉领导独立 Team。
+本决策替代[相邻消息](2026-08-27-adjacent-agent-steer-messaging.zh.md)与[子代理队友](2026-10-15-agent-teams-as-subagents.zh.md)中的邻接、发现及父子生命周期限制。它们的共享收件箱、调度、发送者归属和 Team 复用决策仍有效。成员使用 Session id 寻址；普通 Session 分叉领导独立 Team。

 ## Alternatives considered

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for 2026-10-17-agent-controller-message-delivery.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-17-agent-controller-message-delivery.md
-/agent-note-delivering-messages-from-outside-an-agent-through-the-agent-controller:
-  en: 9105f8148e107f43
-  zh: a160e87bb0605da4
-/agent-note-delivering-messages-from-outside-an-agent-through-the-agent-controller/problem:
-  en: 5071232d9743096c
-  zh: b553a626538b3466
-/agent-note-delivering-messages-from-outside-an-agent-through-the-agent-controller/decision:
-  en: 1b61d351c4d2bdf1
-  zh: d6f8180b30d97b34
-/agent-note-delivering-messages-from-outside-an-agent-through-the-agent-controller/alternatives-considered:
-  en: acc465cfe02b624c
-  zh: db1d06574f647130
-/agent-note-delivering-messages-from-outside-an-agent-through-the-agent-controller/consequences:
-  en: 9d8486586d044709
-  zh: 24c7249421fd2541
@@ -1,51 +0,0 @@
-# Agent Note: Delivering messages from outside an Agent through the Agent controller
-
-Status: implemented
-
-English | [中文](2026-10-17-agent-controller-message-delivery.zh.md)
-
-## Problem
-
-Plugins need to decide, with Host context, whether a message someone sends may enter a Session now. The experimental forge panel must create a requested worktree before the first message reaches the Agent, and must stop a message after the Session's worktree was removed. The Host had no point for that decision. `session/prompt` appended a prompt to the Agent inbox synchronously, and the only seam every sender passes, `agent/pre-step`, runs after the inbox accepted the message and the client already showed it as sent. A pre-step rejection ends the turn without returning the message to its sender, and a queued message reaches pre-step only when its turn starts. A gate in the Web composer, tried first, had no Host context and was bypassed by every other client.
-
-## Decision
-
-The core package `dsh-agent-controller` owns how a message from outside an Agent enters its inbox. The base bundle mounts it as `ctx.agentController`, so every base-backed profile can deliver through it; `dsh-agent` and `agent-loop` keep their inbox methods unchanged.
-
-| Part | Contract |
-|---|---|
-| Entry | `ctx.agentController.deliver(agent, { mode, source, signal, prepare, beforeInsert })` prepares the content, builds the message, asks the `agent-controller/admission` waterfall for an `AdmissionDecision`, checks the sender's cancellation and that the Agent is still registered, calls `beforeInsert`, then `followup()` or `steer()`, and resolves with the message id once the message is in the inbox |
-| Sender work | `prepare` turns the sender's content into durable message content inside the Agent's delivery order; the optional `beforeInsert` runs synchronously immediately before the append, for bookkeeping that must precede the Agent's wake |
-| Listeners | Run in registration order with Agent scope filtering and receive the Agent, the message, and a signal that aborts when the sender cancels or the controller stops; return the decision of `next()` to admit, await before `next()` to hold, and return `{ kind: 'reject', reason, message, presented }` to refuse without asking later listeners; throw only when the check itself fails |
-| Delivery mode | Stays with the sender; listeners do not see it, because no admission policy depends on it |
-| Order | Messages to one Agent are prepared, decided, and appended one at a time in arrival order; a sender that cancels before the append is not admitted and stops waiting at once, even behind a held message; disposing the controller stops every message that has not entered an inbox and finishes once those deliveries settled |
-| Failures | A rejection raises `AgentAdmissionRejected`, a `HarnessError` with code `AGENT_ADMISSION_REJECTED`, with its reason and `presented`; senders recognize it by that code rather than its class and import only types from this package; a thrown listener error raises it with `agent-controller/admission-failed`, and an Agent that left the registry with `agent-controller/agent-gone`; errors from `prepare`, `beforeInsert`, `followup()`, and `steer()` pass through; no listener runs after the message entered the inbox |
-
-Only senders that deliver work on someone's behalf call `deliver()`. Messages the Agent's own machinery produces, such as job results, goal rounds, plan transitions, and question answers, keep `followup()`, `steer()`, and `inject()`: they belong to work that was already admitted. A listener must not wait for a person when the message source is unattended, such as a schedule or a webhook; it passes or refuses such a message.
-
-`presented` tells an interactive client that the refusing plugin explains the refusal in its own interface, so the client adds no generic notice.
-
-The Web Session Remote adopts the controller first. `session/prompt` resolves or resumes the Agent, acknowledges a repeated `requestId` itself, and delivers with a `prepare` that checks image input against the Session model, resolves upload receipts, and stores attachments, and a `beforeInsert` that binds the receipts to the request. It maps a refusal to `session/prompt-rejected` with `reason` and `presented`. The call stays open while a listener holds the message, and the client's cancellation stops it. The SDK server, ACP, headless runs, schedules, webhooks, and subagent prompts move to `deliver()` in later changes, each mapping a refusal to its own protocol. Until they do, a plugin that must cover them keeps an `agent/pre-step` check.
-
-Request deduplication stays in the Session Remote. It reads the Session history synchronously, and the [synchronous-read decision](2026-09-09-deprecate-synchronous-session-event-reads.md) prohibits copying such a read into new production code; the controller can take over deduplication once a projection records accepted request ids.
-
-The Web client keeps its existing echo: Enter clears the composer and shows the message at once, and a refusal reaches the client as an ordinary prompt failure, which retires the echo and restores the draft unless new text was typed meanwhile.
-
-## Alternatives considered
-
- **An admission stage in `dsh-agent`.** `ctx.agents.admit()` with an `agent/admission` event reaches every sender as well, but it adds a delivery concern and a new extension point to the Agent core, whose contract the loop implements. A package composed in the base bundle reaches the same senders without changing that contract.
- **A Session Remote event, or a layer inside the Session Controller.** It fits the Web path, but the Session Controller is composed only in the Web profile, so ACP, SDK, and headless senders could never reach it.
- **`agent/pre-step`.** It covers every sender, but it runs after the inbox accepted the message and the client showed it as sent, a refusal drops the message instead of returning it, and a queued message is checked only when its turn starts.
- **Gated, asynchronous `followup()` and `steer()`.** Every internal sender would pass listeners meant for outside input, and their callers rely on synchronous enqueueing.
- **A composer gate in the Web client.** It has no Host context, and other clients and `ctx.conversation.send` bypass it.
- **Appending in the innermost step, with refusals thrown.** Listeners could act once `next()` returned with the message already in the inbox, but that capability, which no listener uses, cost three special cases: a listener failure after the append could only be logged, the inbox's own refusal had to be told apart from a listener failure, and a refusal thrown from another module copy of the error class needed a structural check. A returned decision keeps the stage a pure decision, as `agent/pre-step` is; a plugin that reacts to admitted messages listens to `agent/inbox/inserted`.
-
-The liveshare proposal in PR #3854 also introduced an admission hook, for caller identity. [Peer principals](2026-10-12-peer-principal-and-remote-access.md) replaced it; this stage decides whether the Agent can take a message now, independent of who sent it.
-
-## Consequences
-
- A listener that holds one message keeps later messages to the same Agent waiting; other Agents proceed.
- While a listener holds a Web prompt, the client already shows its echo; a refusal then retires the echo and returns the draft.
- `prepare` stores attachments before the decision, so a refused prompt can leave a stored attachment unreferenced.
- Image prompts deliver inside the Session Remote's image admission chain, so a model switch waits while a listener holds an image prompt.
- Until every outside sender adopts `deliver()`, the stage is not a complete enforcement point.
@@ -1,51 +0,0 @@
-# Agent Note：经 Agent 控制器投递来自 Agent 外部的消息
-
-Status: implemented
-
-[English](2026-10-17-agent-controller-message-delivery.md) | 中文
-
-## 问题
-
-插件需要借助 Host 侧的上下文，判断别人发来的一条消息现在能否进入 Session。实验性的 forge 面板必须在第一条消息到达 Agent 之前建好所请求的工作树，并在 Session 的工作树被删除后拦下消息。Host 此前没有做这个判断的位置：`session/prompt` 同步地把提示词追加进 Agent 收件箱，而所有发送方都会经过的唯一扩展点 `agent/pre-step` 运行在收件箱接受消息、客户端已显示为已发送之后。pre-step 拒绝会结束本轮，却不会把消息退回给发送方；排队的消息也要等到它的轮次开始才会到达 pre-step。最初尝试的 Web 输入框闸门拿不到 Host 上下文，其他客户端也都会绕过它。
-
-## 决策
-
-core 包 `dsh-agent-controller` 负责来自 Agent 外部的消息如何进入其收件箱。base 组合包把它挂载为 `ctx.agentController`，因此每个基于 base 的 profile 都能经它投递；`dsh-agent` 与 `agent-loop` 的收件箱方法保持不变。
-
-| 部分 | 约定 |
-|---|---|
-| 入口 | `ctx.agentController.deliver(agent, { mode, source, signal, prepare, beforeInsert })` 准备内容、构造消息、向 `agent-controller/admission` waterfall 要一个 `AdmissionDecision`，检查发送方是否取消、Agent 是否仍在注册表中，调用 `beforeInsert`，再调用 `followup()` 或 `steer()`，消息进入收件箱后返回消息 id |
-| 发送方的工作 | `prepare` 在该 Agent 的投递顺序内把发送方的内容转成持久的消息内容；可选的 `beforeInsert` 紧挨在放入之前同步运行，用于必须先于 Agent 唤醒完成的登记 |
-| 监听器 | 按注册顺序运行，按 Agent 作用域过滤，拿到 Agent、消息和一个在发送方取消或控制器停止时中止的信号；返回 `next()` 的决定即放行，在 `next()` 前 await 即暂留，返回 `{ kind: 'reject', reason, message, presented }` 即拒绝且不再询问后面的监听器；只在检查本身执行失败时抛出异常 |
-| 投递方式 | 留在发送方，监听器看不到，因为目前没有按投递方式区分的准入策略 |
-| 顺序 | 同一个 Agent 的消息按到达顺序逐条准备、决定并放入；在放入之前取消的发送方不会被接纳，并立即结束等待，即使排在被暂留的消息之后；销毁控制器会停止所有尚未进入收件箱的消息，并在这些投递结束后才完成 |
-| 失败 | 拒绝时抛出带其 reason 与 `presented` 的 `AgentAdmissionRejected`，它是 code 为 `AGENT_ADMISSION_REJECTED` 的 `HarnessError`；发送方按这个 code 而不是按类识别拒绝，对本包只导入类型；监听器抛出异常时 reason 为 `agent-controller/admission-failed`，Agent 离开注册表时为 `agent-controller/agent-gone`；`prepare`、`beforeInsert`、`followup()` 与 `steer()` 的错误原样抛出；消息进入收件箱之后不再有监听器运行 |
-
-只有代表他人送来工作的发送方调用 `deliver()`。Agent 自身机制产生的消息，例如后台任务结果、goal 轮次、plan 切换和问题答复，继续使用 `followup()`、`steer()` 与 `inject()`：它们属于已经接纳的工作。消息来源无人值守时（例如定时任务或 webhook），监听器不得等待人来处理，只能放行或拒绝。
-
-`presented` 告诉交互式客户端，拒绝它的插件会在自己的界面里给出说明，客户端因此不再追加通用提示。
-
-Web Session Remote 首先接入控制器。`session/prompt` 自己解析或恢复 Agent、确认重复的 `requestId`，再调用投递：`prepare` 按 Session 模型检查图片输入、解析上传凭证并存储附件，`beforeInsert` 把凭证绑定到该请求。它把拒绝映射为带 `reason` 与 `presented` 的 `session/prompt-rejected`。监听器暂留消息期间调用保持未完成，客户端取消会让它停止。SDK 服务端、ACP、headless 运行、定时任务、webhook 与子代理提示词在后续改动中改用 `deliver()`，各自把拒绝映射到自己的协议。在此之前，必须覆盖它们的插件仍保留一个 `agent/pre-step` 检查。
-
-请求去重留在 Session Remote。它同步读取 Session 历史，而[同步读取决策](2026-09-09-deprecate-synchronous-session-event-reads.zh.md)禁止把这类读取复制到新的生产代码；等有投影记录已接收的请求 id 后，控制器才能接管去重。
-
-Web 客户端保留现有的回显方式：Enter 立即清空 composer 并显示消息；拒绝在客户端表现为一次普通的提示词失败，回显撤下，草稿回到 composer，除非期间已经输入了新内容。
-
-## 备选方案
-
- **在 `dsh-agent` 里加接纳阶段。** `ctx.agents.admit()` 加 `agent/admission` 事件同样能覆盖所有发送方，但它把投递职责和一个新扩展点加进了 Agent 核心，而 Agent 的约定由循环实现。组合在 base 组合包里的独立包能覆盖同样的发送方，又不改变这项约定。
- **Session Remote 自己的事件，或 Session Controller 内部的一层。** 它适合 Web 路径，但 Session Controller 只在 Web profile 中组合，ACP、SDK 与 headless 发送方永远无法使用它。
- **`agent/pre-step`。** 它覆盖所有发送方，但运行在收件箱接受消息、客户端显示为已发送之后；拒绝会丢掉消息而不是退回；排队的消息要到轮次开始才会被检查。
- **让 `followup()` 与 `steer()` 异步并经过闸门。** 每个内部发送方都会经过为外部输入准备的监听器，而它们的调用方依赖同步入队。
- **Web 客户端的输入框闸门。** 它拿不到 Host 上下文，其他客户端和 `ctx.conversation.send` 都会绕过它。
- **在最内层步骤放入消息，并以抛出异常表示拒绝。** 监听器能在 `next()` 返回、消息已进入收件箱之后继续执行，但这项没有监听器使用的能力带来三处特殊处理：放入之后的监听器失败只能记录日志；要把收件箱自身的拒绝与监听器失败区分开；另一个模块副本抛出的错误类需要按结构识别。返回决定让这个阶段和 `agent/pre-step` 一样只做决定；需要对已接纳消息作出反应的插件监听 `agent/inbox/inserted`。
-
-PR #3854 中的 liveshare 方案也引入过一个接纳钩子，用于调用方身份。[Peer principals](2026-10-12-peer-principal-and-remote-access.zh.md) 取代了它；本阶段判断 Agent 现在能否接收一条消息，与发送者是谁无关。
-
-## 影响
-
- 监听器暂留一条消息时，同一 Agent 之后的消息都要等待；其他 Agent 不受影响。
- 监听器暂留一条 Web 提示词期间，客户端已经显示其回显；随后被拒绝时，回显撤下，草稿回到 composer。
- `prepare` 在决定之前存储附件，因此被拒绝的提示词可能留下一个无人引用的已存附件。
- 图片提示词在 Session Remote 的图片接纳链内投递，因此监听器暂留图片提示词期间，切换模型要等待。
- 在所有外部发送方都改用 `deliver()` 之前，这个阶段还不是完整的强制执行点。
@@ -1,22 +0,0 @@
-# Bilingual-pair consistency record for 2026-10-17-hierarchical-agent-names.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-17-hierarchical-agent-names.md
-/agent-note-hierarchical-agent-names:
-  en: 4a1223d881f03a6f
-  zh: acced71e5ee769b2
-/agent-note-hierarchical-agent-names/problem:
-  en: 78696f33320218ec
-  zh: 13d8aa85ef049e6e
-/agent-note-hierarchical-agent-names/decision:
-  en: fca6ce3d6dcbf86e
-  zh: b6d0405e91ddcf90
-/agent-note-hierarchical-agent-names/alternatives-considered:
-  en: 1447580f9c1f10e5
-  zh: 147e2cc7062af05c
-/agent-note-hierarchical-agent-names/consequences:
-  en: 691ef7ee95e422cc
-  zh: 20eb55b79e416eb8
-/agent-note-hierarchical-agent-names/testing:
-  en: 8cff7c7e8b903b20
-  zh: 8e20b00864f8f3d8
@@ -1,31 +0,0 @@
-# Agent Note: Hierarchical agent names
-
-Status: implemented
-
-English | [中文](2026-10-17-hierarchical-agent-names.zh.md)
-
-## Problem
-
-Session ids are durable execution identities but difficult to read in model coordination. Descriptions may repeat. Flat tree-wide names require every parent to coordinate reservations and publish descendant assignments in the root, introducing a second Session write and incomplete-registration recovery.
-
-## Decision
-
-Keep Session ids for persistence and authorization. Each child has an immutable name segment unique among its direct siblings. Model tools return and accept full paths rooted at `lead`, such as `lead/reviewer` and `lead/explore/alice`. Parent catalogs retain the segment and relationship, including external caller-delivery work. Tools and host callers can omit the segment: runtime reserves the first unused `agent-N`, starting at `agent-1`, across committed and pending siblings before any asynchronous preparation. No persisted counter or descriptor copy is needed. Path lookup reads only intermediate parent catalogs. Temporary reservations belong to the exact live parent and reject concurrent sibling duplicates before provider dispatch. A parent catalog append commits creation, and committed names survive settlement and restart.
-
-This supersedes the name-free interface in [Agent Teams as subagents](2026-10-15-agent-teams-as-subagents.md). Its lineage authority and shared subagent lifecycle remain current. Resolution grants no messaging, interruption, or assignment authority. Historical unnamed children use `legacy:<session-id>` segments; historical Team members without a catalog grant no assignment authority.
-
-## Alternatives considered
-
-**Flat tree-wide names.** Short addresses are convenient and root registration avoids intermediate catalog reads. That convenience requires shared name admission, a root assignment record, and recovery when the parent write succeeds but root registration fails. Paths give every caller the same unambiguous address while reusing parent-owned records. Reintroducing a flat namespace would require a demonstrated need for globally unique short aliases that outweighs these costs.
-
-**Recyclable names.** Reuse could redirect delayed work after the original agent settles. Retaining assignments keeps recipient identity stable.
-
-**Checking only before asynchronous startup.** Two concurrent sibling creations could both pass. Parent-local temporary reservations prevent duplicate external work before it starts; failed creation releases the reservation.
-
-## Consequences
-
-Creation accepts an optional segment; tool results, child guidance, message prefixes, task owners, and settlement notices use full paths. Different parents and independent roots can reuse segments. Cold path lookup depends on intermediate catalogs, but not unrelated branches. A failed parent catalog append can leave a local descriptor; a child cannot resume without its parent catalog entry. Internal Session and task-owner ids stay stable. The [upgrade guide](../../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.md) describes caller changes.
-
-## Testing
-
-Focused tests cover automatic allocation, pending-name release, restart stability, same-name children in separate branches, concurrent sibling rejection before dispatch, failed-start release, parent catalog failure, restoration, fork isolation, legacy paths, and ambiguous persisted names. Recorded Headless and SDK sessions cover creation, nested paths, messages, listing, and completion notices; Team tests reject historical membership as assignment or message authority.
@@ -1,31 +0,0 @@
-# Agent Note: 分层 agent 名字
-
-Status: implemented
-
-[English](2026-10-17-hierarchical-agent-names.md) | 中文
-
-## 问题
-
-Session id 是持久执行身份，但不便于阅读模型协作内容。描述可以重复。树内全局短名要求所有父级协调名字预留，并将后代分配发布到根，引入第二次 Session 写入和不完整登记恢复。
-
-## 决策
-
-保留 Session id 用于持久化和授权。每个子级有一个不可变的名字路径段，只在直接同级中唯一。模型工具返回并接受以 `lead` 为根的完整路径，如 `lead/reviewer` 和 `lead/explore/alice`。父级 catalog 保留路径段及关系，包括 caller 交付的外部工作。工具和 host 调用方均可省略路径段：runtime 在任何异步准备之前，从 `agent-1` 开始预留已提交与临时预留的同级中第一个未占用的 `agent-N`。无需持久计数器或 descriptor 副本。路径查找只读取沿途父级 catalog。临时预留属于确切在线的父级，在 provider 派发前拒绝并发同级重名。父级 catalog 追加提交创建，已提交名字在执行结束和重启后保留。
-
-本记录取代 [Agent Teams 作为 subagent](2026-10-15-agent-teams-as-subagents.zh.md) 中不使用名字的接口。其谱系权限与共享 subagent 生命周期仍然有效。解析不授予消息、中断或分配权限。历史无名子级使用 `legacy:<session-id>` 路径段；没有 catalog 的历史 Team 成员不授予分配权限。
-
-## 考虑的替代方案
-
-**树内全局短名。** 短地址便于使用，根登记避免读取中间 catalog。但这要求共享名字准入、根分配记录，以及父级写入成功但根登记失败后的恢复。路径复用父级已有记录，仍为所有调用方提供相同的无歧义地址。重新引入全局短名空间需要证明确有足以抵偿这些成本的短别名需求。
-
-**可回收名字。** 执行结束后复用名字，可能让延迟工作转向另一个接收方。保留分配可维持接收方身份稳定。
-
-**只在异步启动前检查。** 两个并发同级创建都可能通过检查。父级局部临时预留在外部工作开始前阻止重复派发；创建失败会释放预留。
-
-## 影响
-
-创建接受可选路径段；工具结果、子级指引、消息前缀、任务负责人和完成通知使用完整路径。不同父级和独立根可复用路径段。冷路径查找依赖沿途中间 catalog，不依赖无关分支。父级 catalog 追加失败可能留下本地 descriptor；子级缺少父级 catalog 条目时无法恢复。内部 Session 和任务负责人 id 保持稳定。[升级指南](../../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.zh.md) 说明调用方变更。
-
-## 测试
-
-定向测试覆盖自动分配、临时名字释放、重启稳定性、不同分支同名子级、派发前拒绝并发同级重名、启动失败释放、父级 catalog 失败、恢复、fork 隔离、legacy 路径和有歧义的持久化名字。录制的 Headless 与 SDK 会话覆盖创建、嵌套路径、消息、列表和完成通知；Team 测试拒绝将历史成员关系作为分配或消息权限。
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-19-file-drag-plugin-ownership.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-19-file-drag-plugin-ownership.md
+/agent-note-file-drag-ownership-outside-the-application-layout:
+  en: 951575b08912a949
+  zh: f33e8e6bcb9240bd
+/agent-note-file-drag-ownership-outside-the-application-layout/problem:
+  en: 557edc1db9bee8d8
+  zh: 20f47c78c8b0078b
+/agent-note-file-drag-ownership-outside-the-application-layout/decision:
+  en: 1dfea60901d6e6ae
+  zh: e4fc534dbe01b0d5
+/agent-note-file-drag-ownership-outside-the-application-layout/alternatives-considered:
+  en: 571eabab132ce4c1
+  zh: b5f8207015aeb3be
+/agent-note-file-drag-ownership-outside-the-application-layout/consequences:
+  en: 56ebb7c25911fd61
+  zh: 88120d2af74785ef
@@ -0,0 +1,25 @@
+# Agent Note: File drag ownership outside the application layout
+
+Status: implemented
+
+English | [中文](2026-10-19-file-drag-plugin-ownership.zh.md)
+
+## Problem
+
+Image dragging spans conversation images, sidebar previews, and composer drop targets. Original files must survive source unmount during a drag, and failures must remain visible after the originating panel closes. An application-root image provider puts feature state in layout and makes independent image entries depend on an undeclared React ancestor.
+
+## Decision
+
+The [file-drag plugin](../../../../packages/client/ui-file-drag/README.md) owns generic file preparation, browser transfer tokens, retained original files, desktop bridge selection, and transient failure feedback. Consumers receive preparation and error callbacks through their slot or Factory injection. The plugin registers its feedback through `shell.overlay`; layout declares the generic slot and has no image dependency. The shared image primitive owns gestures and cancellation. Images are the first consumer, while MIME naming and transport accept other files.
+
+## Alternatives considered
+
+**Root React provider.** It preserves transfer lifetime but adds image-specific assembly to the layout package and hides dependencies from slot registration. Moving the same wrapper into the renderer would move the feature coupling into another generic owner.
+
+**State on each image.** It avoids shared assembly but cannot deliver the retained file after the source unmounts or keep a late failure visible after the panel closes.
+
+**Direct browser File only.** Manual macOS Chrome 154.0.8037.93 drags of PNG and PDF fixtures produced a populated `dataTransfer.files` in trusted `dragstart`, but empty files in trusted same-page and cross-window drops. Finder received filename-only text clippings. These measured failures require the application-local token path; they do not establish behavior in untested browsers or cross-tab delivery. Desktop retains Electron native file dragging.
+
+## Consequences
+
+One plugin lifetime governs transfer state, a native source-node end listener, and drop completion. The source listener remains attached after React unmount. Independent render roots can share a transfer without sharing a React ancestor. Custom compositions must load the service and declare the feedback slot; custom image Factory registrations supply the required callbacks. Application-local browser tokens are accepted only over the composer; native Desktop files retain the full-page drop overlay. Plugin disposal removes feedback and clears retained files. Loader-backed browser scenarios cover source removal and delivery, while focused tests cover local resource authorization and cleanup failures.
@@ -0,0 +1,25 @@
+# Agent Note: 应用布局之外的文件拖放归属
+
+Status: implemented
+
+[English](2026-10-19-file-drag-plugin-ownership.md) | 中文
+
+## Problem
+
+图片拖放跨越会话图片、侧栏预览和输入框接收区。拖动期间原始文件必须在源组件卸载后继续保留，发起操作的面板关闭后失败提示也必须可见。应用根部的图片 Provider 把功能状态放进布局，并使独立图片入口依赖未声明的 React 祖先组件。
+
+## Decision
+
+[文件拖放插件](../../../../packages/client/ui-file-drag/README.zh.md) 持有通用文件准备、浏览器传递令牌、原始文件、桌面桥接选择和临时失败提示。消费方通过 slot 或 Factory 注入接收准备及错误回调。插件通过 `shell.overlay` 注册提示，布局只声明通用插槽，不依赖图片功能。共享图片原语负责手势与取消。图片是首个调用方，MIME 命名与传输也接受其他文件。
+
+## Alternatives considered
+
+**根部 React Provider。** 它能保留传递生命周期，但会把图片专属组合放进布局包，并对 slot 注册隐藏依赖。把同一个包裹组件移到渲染器，只会把功能耦合转移到另一个通用模块。
+
+**每张图片独立持有状态。** 这能避免共享组合，却不能在源组件卸载后交付保留文件，也不能在面板关闭后继续显示延迟到达的失败提示。
+
+**仅直接传递浏览器 File。** 在 macOS Chrome 154.0.8037.93 中手动拖放 PNG 与 PDF 时，可信 `dragstart` 中 `dataTransfer.files` 有文件，同页与跨窗口的可信 drop 却收到空文件列表。Finder 收到仅含文件名的文本摘录。这些实测失败要求保留应用内令牌路径，但不能据此判定未测试浏览器或跨标签页交付的行为。Desktop 保留 Electron 原生文件拖放。
+
+## Consequences
+
+一个插件生命周期管理传递状态、源节点上的原生结束监听器与投放完成。React 卸载后，监听器仍绑定源节点。独立渲染根可以共享传递，而不共享 React 祖先组件。自定义组合必须加载服务并声明反馈插槽，自定义图片 Factory 注册提供所需回调。应用内浏览器令牌仅在输入框范围接受；Desktop 原生文件保留全页投放遮罩。插件卸载会移除提示并清除保留文件。通过 Loader 启动的浏览器场景覆盖源图移除与交付，定向测试覆盖本地资源授权和清理失败。
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-19-pi-ai-system-reminder-fallback.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-19-pi-ai-system-reminder-fallback.md
+/agent-note-pi-ai-system-reminder-fallback:
+  en: f43b5c6974289180
+  zh: abc0a86b1d137189
+/agent-note-pi-ai-system-reminder-fallback/problem:
+  en: 5247278483ca4e7a
+  zh: ca711671a43fae76
+/agent-note-pi-ai-system-reminder-fallback/decision:
+  en: 604eb72704c73328
+  zh: 6661d1065f65ecf9
+/agent-note-pi-ai-system-reminder-fallback/alternatives-considered:
+  en: 0e2aaf897587ebb0
+  zh: 0a7f9a9cb7ddffaf
+/agent-note-pi-ai-system-reminder-fallback/consequences:
+  en: 8a0c53289a04c64a
+  zh: 591e602eb2036a1a
@@ -0,0 +1,25 @@
+# Agent Note: Pi-ai system reminder fallback
+
+Status: implemented
+
+English | [中文](2026-10-19-pi-ai-system-reminder-fallback.zh.md)
+
+## Problem
+
+Pi-ai concatenates later system messages into the initial prompt for models without native mid-conversation system support. Later system messages supplied to the adapter therefore invalidate the preceding conversation cache prefix.
+
+## Decision
+
+The pi-ai adapter uses the prepared model's existing `supportsMidConvoSystemMessages` capability mapping. It preserves native system messages on capable models and converts each non-empty later system message into a user message wrapped in `<system-reminder>` otherwise, before pi-ai receives the context. Leading system text remains in the initial prompt. Message order, repeated updates, and existing text-block concatenation remain intact. Durable messages retain their original roles.
+
+The fallback belongs to the adapter because it depends on the selected protocol capability. Prompt admission remains owned by the agent loop, which consolidates system-prompt updates on routes without native support; this fallback only handles later system messages present in the supplied request.
+
+## Alternatives considered
+
+**Let pi-ai concatenate updates.** Retains system-role priority but changes the initial prompt whenever later system text changes, defeating prefix reuse.
+
+**Advertise native support or send developer messages.** Misstates model capability or relies on another unsupported instruction role. The fallback uses ordinary user messages and does not change capability metadata.
+
+## Consequences
+
+The wrapper does not confer system-role authority, so reminders have user-role priority. Cache hits remain provider-dependent; tool changes and compaction can still invalidate prefixes. Both text-only and attachment-aware conversion apply the same fallback, and wire tests inspect the real pi-ai serializer output.
@@ -0,0 +1,25 @@
+# Agent Note: Pi-ai 系统提醒回退
+
+Status: implemented
+
+[English](2026-10-19-pi-ai-system-reminder-fallback.md) | 中文
+
+## 问题
+
+对于不原生支持对话中系统消息的模型，pi-ai 会把后续系统消息拼接进初始提示词。因此，传给适配器的后续系统消息会使此前的对话缓存前缀失效。
+
+## 决策
+
+pi-ai 适配器使用已准备模型的现有 `supportsMidConvoSystemMessages` 能力映射。对于具备该能力的模型，适配器保留原生系统消息；否则，在 pi-ai 接收上下文之前，将每条非空的后续系统消息转换为以 `<system-reminder>` 包裹的用户消息。开头的系统文本仍位于初始提示词中。消息顺序、重复更新和现有文本块拼接方式均保持不变。持久消息保留原始角色。
+
+回退由适配器负责，因为它取决于所选协议的能力。提示词纳入仍由 Agent loop 负责，它在不支持原生更新的路由上合并系统提示词更新；此回退仅处理传入请求中已有的后续系统消息。
+
+## 考虑过的替代方案
+
+**让 pi-ai 拼接更新。** 保留系统角色优先级，但后续系统文本每次变化都会改变初始提示词，破坏前缀复用。
+
+**宣称原生支持或发送 developer 消息。** 错报模型能力，或依赖另一种不受支持的指令角色。回退使用普通用户消息，不改变能力元数据。
+
+## 后果
+
+包裹文本不会赋予系统角色权限，因此提醒具有用户角色优先级。缓存命中仍取决于提供方；工具变化和压缩仍可能使前缀失效。纯文本与附件感知转换使用相同的回退，线协议测试检查真实 pi-ai 序列化器的输出。
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-21-replaceable-icon-sprite.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-21-replaceable-icon-sprite.md
+/agent-note-replaceable-product-icons-through-an-svg-sprite:
+  en: 2b527e550e071451
+  zh: 7de256912270cae0
+/agent-note-replaceable-product-icons-through-an-svg-sprite/problem:
+  en: d55557fe41ab87c8
+  zh: eea3f7d0c82561bf
+/agent-note-replaceable-product-icons-through-an-svg-sprite/decision:
+  en: 6ddd80eae56693dd
+  zh: 4d654a76eb64c50a
+/agent-note-replaceable-product-icons-through-an-svg-sprite/alternatives-considered:
+  en: 2e25ece88bccdb22
+  zh: bb24a28bef7ea7ce
+/agent-note-replaceable-product-icons-through-an-svg-sprite/consequences:
+  en: 0ad6db37bbb76ddb
+  zh: 0ca09d55a2167970
@@ -0,0 +1,29 @@
+# Agent Note: Replaceable product icons through an SVG sprite
+
+Status: implemented
+
+English | [中文](2026-10-21-replaceable-icon-sprite.zh.md)
+
+## Problem
+
+Long-term skin customization needs themes to replace icons, not only colors. Product icons were React components that drew inline SVG paths, so a theme registered through `ctx.theme` could recolor them through `currentColor` but could not change their artwork. About 150 Client files import these components.
+
+## Decision
+
+Each product glyph weight is one sprite symbol, `dsw-icon-<glyph>-<weight>`. ui-primitives keeps the default SVG documents as `ICON_SYMBOLS`; an icon component keeps its export name, `size`, and `className`, and renders an `<svg>` box with one `<use>` of its symbol. ui-theme keeps one hidden sprite in the document whose `<symbol>` children come from the active theme's `ThemeDefinition.icons` replacements or the defaults. Artwork reached through `<use>` inherits `currentColor` and CSS custom properties from the use site, so a replacement can be multi-color, can paint with `--dsw-*` color tokens, and follows light and dark palettes without separate values.
+
+## Alternatives considered
+
+- **Icons as CSS image tokens painted through `mask-image`.** Rejected after design review: a mask keeps only the image's alpha, so every icon stays one color, and a `url()` image cannot read CSS variables, so multi-color artwork could not follow color tokens. It would have reused the token override layer without a new theme field.
+- **A runtime icon registry service with React components as values.** Rejected: components cannot read services or React context, so every icon import site would need a new prop or slot.
+- **A slot per icon.** Rejected for the same caller cost; slots carry composition, not artwork.
+
+## Consequences
+
+- Icon DOM contains a `<use>` reference instead of paths; tests identify glyphs through `data-icon` and inspect artwork through `ICON_SYMBOLS`.
+- Without ui-theme, the sprite is absent and icons render nothing.
+- Every symbol shares the document id space, so `register` requires element ids inside a replacement to start with `<symbol id>-`; `<use>` in another document, such as an iframe, cannot reach the sprite.
+- Replacement markup is trusted like the registering plugin's code; `register` rejects `<style>` and `<script>` only because they would apply to the whole document.
+- Gradients and other paint servers resolve their stops where the sprite sits, so they follow palette tokens but not use-site color overrides.
+- Default and token-colored replacement symbols render pixel-identically through `<use>` and inline in Chromium, WebKit, and Firefox.
+- File-type, plugin, site, and brand artwork still render inline and are not replaceable yet.
@@ -0,0 +1,29 @@
+# Agent Note: 通过 SVG sprite 实现可替换的产品图标
+
+Status: implemented
+
+[English](2026-10-21-replaceable-icon-sprite.md) | 中文
+
+## 问题
+
+长期的皮肤定制需要主题能替换图标，而不只是颜色。产品图标原先是绘制内联 SVG 路径的 React 组件，因此通过 `ctx.theme` 注册的主题可以借助 `currentColor` 给它们换色，却无法更换图形。约 150 个 Client 文件导入了这些组件。
+
+## 决策
+
+每个产品图形的每种线重对应一个 sprite symbol `dsw-icon-<glyph>-<weight>`。ui-primitives 以 `ICON_SYMBOLS` 保存默认 SVG 文档；图标组件保留导出名、`size` 与 `className`，渲染一个 `<svg>` 框，其中包含一个引用自身 symbol 的 `<use>`。ui-theme 在文档中保留一个隐藏的 sprite，其 `<symbol>` 子元素来自活动主题的 `ThemeDefinition.icons` 替换项或默认值。通过 `<use>` 引用的图形会从使用处继承 `currentColor` 与 CSS 自定义属性，因此替换图形可以是多色的，可以用 `--dsw-*` 颜色 token 绘制，并且无需单独的值就能跟随浅色与深色调色板。
+
+## 考虑过的替代方案
+
+- **把图标作为通过 `mask-image` 绘制的 CSS 图像 token。** 经设计评审后否决：遮罩只保留图像的 alpha，因此每个图标都只能是单色；`url()` 图像无法读取 CSS 变量，因此多色图形无法跟随颜色 token。该方案本可复用 token 覆盖层，而无需新增主题字段。
+- **以 React 组件为值的运行时图标注册服务。** 否决：组件无法读取服务或 React context，因此每个图标导入处都需要新的 prop 或 slot。
+- **每个图标一个 slot。** 因同样的调用方成本而否决；slot 承载的是组合，而不是图形。
+
+## 后果
+
+- 图标 DOM 包含 `<use>` 引用而不是路径；测试通过 `data-icon` 识别图形，通过 `ICON_SYMBOLS` 检查图形。
+- 没有 ui-theme 时，sprite 不存在，图标不渲染任何内容。
+- 所有 symbol 共享文档的 id 空间，因此 `register` 要求替换图形内的元素 id 以 `<symbol id>-` 开头；另一个文档（例如 iframe）中的 `<use>` 无法引用该 sprite。
+- 替换标记与注册它的插件代码同等受信任；`register` 仅拒绝 `<style>` 与 `<script>`，因为它们会作用于整个文档。
+- 渐变及其他绘制服务器在 sprite 所在位置解析其色标，因此它们跟随调色板 token，但不跟随使用处的颜色覆盖。
+- 默认 symbol 与使用 token 着色的替换 symbol 在 Chromium、WebKit 与 Firefox 中通过 `<use>` 渲染与内联渲染的结果逐像素一致。
+- 文件类型、插件、站点与品牌图形仍以内联方式渲染，暂不可替换。
@@ -0,0 +1,28 @@
+# Bilingual-pair consistency record for 2026-10-21-when-access.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-21-when-access.md
+/agent-note-whenaccess-registration-that-follows-access:
+  en: 2ef7cfef514c138a
+  zh: 064e3aecbfafcd9c
+/agent-note-whenaccess-registration-that-follows-access/problem:
+  en: 4f88d3ee7868eaa5
+  zh: 72a4ce2dde13bef7
+/agent-note-whenaccess-registration-that-follows-access/decision:
+  en: a15c7c13f167e5ac
+  zh: 63bcc2ef60c2f344
+/agent-note-whenaccess-registration-that-follows-access/decision/whenaccess:
+  en: c168de20989cf9a4
+  zh: bf3b0361beea083d
+/agent-note-whenaccess-registration-that-follows-access/decision/plugin-migration:
+  en: 73577ed282c656f3
+  zh: 2f60a6824218e693
+/agent-note-whenaccess-registration-that-follows-access/alternatives-considered:
+  en: ddc432b693608163
+  zh: 620294d8812b0a31
+/agent-note-whenaccess-registration-that-follows-access/consequences:
+  en: de44fa92c49bc335
+  zh: 34436fe971ab013f
+/agent-note-whenaccess-registration-that-follows-access/related:
+  en: 89073ffbfcff0641
+  zh: 736a180d13a08981
@@ -0,0 +1,88 @@
+# Agent Note: whenAccess registration that follows access
+
+Status: implemented
+
+English | [中文](2026-10-21-when-access.zh.md)
+
+## Problem
+
+Client plugins need to switch their own registrations on and off with the current Peer's access: sidebar entries, main panels, overlays, and data streams. The existing Client access surface covers only rendering:
+
+| Where | Existing capability | Gap |
+|---|---|---|
+| Components | `useRemoteAccess(action)` (global), `useSessionAccess(sessionId, action)`, `useWorkspaceAccess(workspaceId, action)`, and the Session-scope `useAccess(action)` | Readable only during render; a changed answer re-renders automatically |
+| JS (`apply`, services) | `ctx.remoteAccess.source(kind, id, action)` returns a `HostObservable<boolean>` | A plugin must read `getSnapshot` and subscribe to changes itself, then register and dispose by hand |
+
+Without a JS entry point, a plugin can only decide its registrations once by identity at `apply`, and they do not follow an access change.
+
+## Decision
+
+### whenAccess
+
+The JS side has a `whenAccess` for each of the three access Hooks, from the package that publishes that Hook:
+
+| Interface | Provider | Matching Hook |
+|---|---|---|
+| `ctx.remoteAccess.whenAccess(action, callback)` | remote-access | `useRemoteAccess(action)` |
+| `ctx.uiSession.whenAccess(sessionId, action, callback)` | ui-session | `useSessionAccess(sessionId, action)` |
+| `ctx.uiWorkspace.whenAccess(workspaceId, action, callback)` | ui-workspace | `useWorkspaceAccess(workspaceId, action)` |
+
+```ts ignore-check
+import type { AccessEffect, RemoteEndpoint } from '@deepseek-ai/dsh-api-remote-access/client'
+
+/** The global-resource member; the Session and Workspace versions take the resource id first. */
+export interface WhenAccess {
+  /**
+   * Keep `callback`'s effects installed while the current Peer may call `action`
+   * on the resource: run it when the answer becomes true, dispose its effects in
+   * reverse order when it becomes false, and run it again on the next true.
+   * @returns disposer for the observation and any installed effects.
+   */
+  whenAccess(action: RemoteEndpoint, callback: () => AccessEffect): () => void
+}
+```
+
+`AccessEffect` is `(() => void) | Iterable<() => void, void, void>`.
+
+| Rule | Content |
+|---|---|
+| Semantics | Same as `ctx.slots.inject`: the callback returns one disposer or an iterable of disposers; an iterable installs as one transaction and disposes in reverse order; the controller belongs to the caller's fiber and disposes when the plugin unloads |
+| Synchronous run | When the answer is already true, the callback runs synchronously; the owner's answer is always true, so registration order matches direct registration |
+| Stream failure | A non-owner's answer turns false and the installed effects dispose |
+| Callback failure | A setup failure at the call throws synchronously; a setup failure on a later grant stops the controller and is rethrown in a microtask |
+| Layering | remote-access knows only `global`; the Session and Workspace versions are built over remote-access's lower-level `whenResourceAccess(kind, id, action, callback)`, as their Hooks are built over `source(kind, id, action)`. Only the package that owns a resource kind calls `source` and `whenResourceAccess`; other plugins use only the access Hooks and `whenAccess` and pass no kind. All four entry points share [`when-allowed.ts`](../../../../packages/api/remote-access/src/client/when-allowed.ts) |
+
+### Plugin migration
+
+| Plugin | Change | Action |
+|---|---|---|
+| ui-schedule | The task catalog source, delete toast overlay, right-sidebar task tab and title, main panel, sidebar entry, turn-tail card, Session-header reminder catalog, and Session row mark and hover list move into `remoteAccess.whenAccess`; the Session-header catalog reads the per-Session `schedule.list`, so its component also decides through the Session-scope `useAccess` whether to render; the task tab type and the turn definition stay registered outside | `schedule/catalog`, `schedule/list` |
+| ui-plugin-manager | Host change subscriptions, refresh toast overlay, main panel (including `pluginNavigation`), and sidebar entry move into `remoteAccess.whenAccess`, and each grant refreshes a list already loaded; the controller and `pluginChanges` stay outside, and `pluginChanges` receives no updates while access is withdrawn. ui-entry-customization and voice-input use `pluginNavigation` optionally: without the service they hide the browse-plugins and open/details buttons and still start | `pluginManager/listBundles` |
+| ui-settings-general | The settings shell `sidebar.settings` and the `settings.open` shortcut move into `remoteAccess.whenAccess` | `settings/describe` |
+| ui-settings-account | The account state stream (including default model initialization), quota notice, settings launcher, account settings section, and `settings.models.sign-in` move into `remoteAccess.whenAccess`. On revocation the stream's disposer synchronously invalidates the account reads this grant started, closes the pending authorization tab, clears the account view, details, picture, and sign-in dialog state, ends this generation's bonus notices, which a frame of that stream begins, and then closes the stream; a frame delivered before the revocation but not yet handled is dropped. The notice controller stays outside and begins again under the next grant; the account section appears once the new stream's first frame arrives | `account/watch` |
+| ui-directory-picker-native | Both directory flows move into `remoteAccess.whenAccess` | `directoryPicker/pick` |
+| ui-message-feedback | The message feedback buttons stay registered and the component decides whether to render through the Session-scope `useAccess`; `messageFeedback/*` requests carry `sessionId`, which the Gateway resolves to that Session through the `session` resource's default field, so they declare nothing. The `/feedback` decoration has no Client check: the decoration registry is global while `sessionFeedback/record` is decided per Session, so without access the dialog still opens and the Host refuses the submission, which the dialog reports with its failure code | `messageFeedback/put` |
+| ui-deliverables, ui-open-in-app | Unchanged: an owner-only HTTP route that cannot be read falls back as before | — |
+
+## Alternatives considered
+
+**Return after an owner check at the start of `apply` (the #6486 approach)**: fixed on identity; does not follow an access change.
+
+**Trim the plugin list per connection**: a plugin cannot reload at once when access changes.
+
+**Declare access in the plugin package manifest**: defines an access-control concept in the package manifest.
+
+**One generic method with a resource parameter, or all three versions on remote-access**: business code would pass a kind, and remote-access would name the Session and Workspace resource kinds.
+
+## Consequences
+
+| Consequence | Note |
+|---|---|
+| Registrations follow access changes | Without a grant, a migrated plugin registers none of the corresponding entries for a non-owner; they appear after a grant and disappear after a revocation; the owner's answer is always true, so its registrations match direct registration |
+| The callback must hand back disposers | An effect registered through the plugin's `ctx` inside the callback also hangs on the plugin fiber; a registration whose disposer is not yielded does not dispose on access loss, only when the plugin unloads |
+| Readers receive all plugin code | Plugins load as before; the Gateway decides each call, and `whenAccess` and the Hooks control the UI |
+| Test stand-ins | [`dsh-client-test-runtime`](../../../../packages/test-support/client-runtime/README.md) replaces remote-access with fixed answers through `StaticRemoteAccess`, `staticAccessPlugin`, and `TestClientOptions.access`, so plugin specs cover the refused path |
+
+## Related
+
+- [Peer, principal, and remote access](2026-10-12-peer-principal-and-remote-access.md): this Note extends its Client access face.
@@ -0,0 +1,88 @@
+# Agent Note: 按访问状态注册的 whenAccess
+
+Status: implemented
+
+[English](2026-10-21-when-access.md) | 中文
+
+## 问题
+
+Client 插件需要按当前 Peer 的访问状态开关自己的注册：侧栏入口、主面板、浮层、数据流。现有 Client 访问面只覆盖渲染：
+
+| 位置 | 现有能力 | 缺口 |
+|---|---|---|
+| 组件 | `useRemoteAccess(action)`（global）、`useSessionAccess(sessionId, action)`、`useWorkspaceAccess(workspaceId, action)`、会话作用域的 `useAccess(action)` | 只能在渲染时读，答案变化时自动重渲染 |
+| JS（`apply`、服务） | `ctx.remoteAccess.source(kind, id, action)` 返回 `HostObservable<boolean>` | 插件要自己读 `getSnapshot`、订阅变化，再手动注册与撤销 |
+
+没有 JS 侧入口时，插件只能在 `apply` 时按身份一次性决定注册与否，授权变化后注册不跟随。
+
+## 决策
+
+### whenAccess
+
+JS 侧有与三个访问 Hook 一一对应的 `whenAccess`，由各自 Hook 的发布者提供：
+
+| 接口 | 提供者 | 对应 Hook |
+|---|---|---|
+| `ctx.remoteAccess.whenAccess(action, callback)` | remote-access | `useRemoteAccess(action)` |
+| `ctx.uiSession.whenAccess(sessionId, action, callback)` | ui-session | `useSessionAccess(sessionId, action)` |
+| `ctx.uiWorkspace.whenAccess(workspaceId, action, callback)` | ui-workspace | `useWorkspaceAccess(workspaceId, action)` |
+
+```ts ignore-check
+import type { AccessEffect, RemoteEndpoint } from '@deepseek-ai/dsh-api-remote-access/client'
+
+/** The global-resource member; the Session and Workspace versions take the resource id first. */
+export interface WhenAccess {
+  /**
+   * Keep `callback`'s effects installed while the current Peer may call `action`
+   * on the resource: run it when the answer becomes true, dispose its effects in
+   * reverse order when it becomes false, and run it again on the next true.
+   * @returns disposer for the observation and any installed effects.
+   */
+  whenAccess(action: RemoteEndpoint, callback: () => AccessEffect): () => void
+}
+```
+
+`AccessEffect` 为 `(() => void) | Iterable<() => void, void, void>`。
+
+| 规则 | 内容 |
+|---|---|
+| 语义 | 与 `ctx.slots.inject` 相同：回调返回一个 disposer 或一组 disposer；一组时按事务安装、逆序撤销；控制器属于调用方 fiber，插件卸载时撤销 |
+| 同步执行 | 调用时答案为 true 则回调同步执行；owner 的答案恒为 true，注册顺序与直接注册相同 |
+| 快照流失败 | 非 owner 的答案变为 false，已安装的效果撤销 |
+| 回调失败 | 调用时安装失败同步抛出；之后重新授权时安装失败，控制器停止并在微任务中抛出 |
+| 分层 | remote-access 只认识 global；会话版与工作区版经 remote-access 的底层方法 `whenResourceAccess(kind, id, action, callback)` 实现，与它们用 `source(kind, id, action)` 构造 Hook 相同。`source` 与 `whenResourceAccess` 只由拥有该资源种类的包调用，其他插件只用访问 Hook 与 `whenAccess`，不传 kind。四个入口共用 [`when-allowed.ts`](../../../../packages/api/remote-access/src/client/when-allowed.ts) |
+
+### 插件迁移
+
+| 插件 | 改法 | action |
+|---|---|---|
+| ui-schedule | 任务列表数据源、删除提示浮层、右栏任务 tab 与标题、主面板、侧栏入口、turn 尾部卡片、会话头部提醒、会话行标记与悬浮列表包进 `remoteAccess.whenAccess`；会话头部提醒读取按会话判定的 `schedule.list`，组件另在会话作用域里用 `useAccess` 决定是否渲染；任务 tab 类型与 turn 定义的注册留在外面 | `schedule/catalog`、`schedule/list` |
+| ui-plugin-manager | Host 变更订阅、刷新提示浮层、主面板（含 `pluginNavigation`）、侧栏入口包进 `remoteAccess.whenAccess`，每次授权时刷新已加载过的列表；controller 与 `pluginChanges` 留在外面，撤权期间 `pluginChanges` 不更新。依赖 `pluginNavigation` 的 ui-entry-customization 与 voice-input 改为可选使用：服务不在时隐藏「浏览插件」与「打开 / 查看详情」按钮，插件照常启动 | `pluginManager/listBundles` |
+| ui-settings-general | 设置外壳 `sidebar.settings` 与 `settings.open` 快捷键包进 `remoteAccess.whenAccess` | `settings/describe` |
+| ui-settings-account | 账号状态流（含默认模型初始化）、额度提醒、设置启动器、账号设置分区与 `settings.models.sign-in` 包进 `remoteAccess.whenAccess`。撤权时账号流的 disposer 同步作废这一轮发出的账号读取，关闭待授权的浏览器标签页，清空账号视图、详情、头像与登录对话框状态，结束本轮奖励提示（提示由该流的帧开始），再关闭流；撤权前已交付但尚未处理的帧被丢弃。提示控制器留在外面，下次授权时重新开始；账号分区等新流的第一帧到达后才出现 | `account/watch` |
+| ui-directory-picker-native | 两个目录选择流程包进 `remoteAccess.whenAccess` | `directoryPicker/pick` |
+| ui-message-feedback | 消息反馈按钮照常注册，组件在会话作用域里用 `useAccess` 判断是否渲染；`messageFeedback/*` 的请求带 `sessionId`，Gateway 按 `session` 资源的默认字段自动解析为该 Session，无需声明。`/feedback` 装饰不做前端判断：装饰注册表是全局的，而 `sessionFeedback/record` 按会话判定；没有权限时对话框照常打开，提交被 Host 拒绝并显示失败码 | `messageFeedback/put` |
+| ui-deliverables、ui-open-in-app | 不动：owner 专用 HTTP 路由读不到时走已有回退 | — |
+
+## 考虑过的替代方案
+
+**插件 `apply` 开头判断 owner 后 return（#6486 的做法）**：按身份写死，授权变化后不跟随。
+
+**按连接裁剪插件列表**：授权变化后插件无法立即重新加载。
+
+**插件包清单声明访问性**：在包清单上定义访问控制概念。
+
+**一个带资源参数的通用方法，或三个版本都挂在 remote-access 上**：业务代码要传 kind，且 remote-access 会出现会话、工作区的资源种类名。
+
+## 后果
+
+| 后果 | 说明 |
+|---|---|
+| 注册跟随授权变化 | 迁移的插件在非 owner 无授权时不注册相应入口，授予后出现，撤销后消失；owner 的答案恒为 true，注册与直接注册相同 |
+| 回调必须交还 disposer | 回调里经插件 `ctx` 注册的效果也挂在插件 fiber 上；不 yield 其 disposer 的注册在失权时不会撤销，只在插件卸载时撤销 |
+| 读者拿到全部插件代码 | 插件照常加载；访问由 Gateway 逐次判定，界面由 `whenAccess` 与 Hook 控制 |
+| 测试替身 | [`dsh-client-test-runtime`](../../../../packages/test-support/client-runtime/README.zh.md) 的 `StaticRemoteAccess`、`staticAccessPlugin` 与 `TestClientOptions.access` 以固定答案替换 remote-access，供插件测试无权限路径 |
+
+## 相关
+
+- [Peer、principal 与 remote-access](2026-10-12-peer-principal-and-remote-access.zh.md)：本 Note 扩展其 Client 访问面。
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-22-deepseek-official-model-listing.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-22-deepseek-official-model-listing.md
+/agent-note-the-official-deepseek-route-follows-the-official-model-listing-until-its-catalog-is-customized:
+  en: 20de6c2a1bc643b4
+  zh: 2fe21450cebf7f32
+/agent-note-the-official-deepseek-route-follows-the-official-model-listing-until-its-catalog-is-customized/problem:
+  en: 51a513e6134e6ad9
+  zh: e0b19412c9b88e24
+/agent-note-the-official-deepseek-route-follows-the-official-model-listing-until-its-catalog-is-customized/decision:
+  en: ceb2f960085577c3
+  zh: 1bbc833b7cf24070
+/agent-note-the-official-deepseek-route-follows-the-official-model-listing-until-its-catalog-is-customized/alternatives-considered:
+  en: fa126e4f4e0790b4
+  zh: c4f6d266d1ba6753
+/agent-note-the-official-deepseek-route-follows-the-official-model-listing-until-its-catalog-is-customized/consequences:
+  en: 047e30a0f55acb24
+  zh: 804e15532d172157
@@ -0,0 +1,36 @@
+# Agent Note: The official DeepSeek route follows the official model listing until its catalog is customized
+
+Status: implemented
+
+English | [中文](2026-10-22-deepseek-official-model-listing.zh.md)
+
+## Problem
+
+The `deepseek-official` route offered whatever its `models` setting held, and that setting defaults to the catalog bundled with each build. A model the DeepSeek API added reached API-key users only through a release, while the account route already followed the service's `GET /models` listing at the same origin. Unlike the account route's catalog, the official route's catalog is user-editable: the Models page stores an edited catalog in `models`, and a gateway behind `baseURL` declares its models there.
+
+## Decision
+
+- [`llm-deepseek-api-key`](../../../../packages/llm/llm-deepseek-api-key/README.md) follows `GET https://api.deepseek.com/models`, authenticated with the API key in `x-api-key`, only while the Messages origin is `https://api.deepseek.com` and `models` equals the built-in catalog. Any other endpoint or catalog sends no listing request.
+- Loading, refresh, fallback, merging, and the client-version gate are the [account route's](2026-09-24-deepseek-account-remote-model-catalog.md): a first access waits up to `modelsTimeoutMs`, a listing older than `modelsMaxAgeMs` refreshes in the background on the next access, a failure keeps the last good listing or the built-in catalog, and the cache lives in memory, keyed by endpoint and key fingerprint.
+- A customized `models` list wins whole: it replaces the catalog and stops listing requests. A list is customized when it resolves differently from the built-in catalog, because the schema default materializes an absent `models` as the built-in list and the Models page shows that default as its inherited rows.
+- Switching between a customized catalog and the listing invalidates the cache from a `loader/volatile-update` listener, so Restore defaults reloads the listing on the next access even when the cached listing is fresh.
+- The listing request, its cache, catalog resolution, and the gate live in the shared [Messages transport](../../../../packages/llm/llm-deepseek/README.md) because two routes consume them; the transport's provider hooks remain `connect` and `admit`.
+
+## Alternatives considered
+
+**Follow the listing on every endpoint.** A gateway that publishes an OpenAI-style `/models` returns entries without `api_capabilities.anthropic_messages`, which the decoder hides, so the route would offer no models. Every such gateway would also receive an extra request carrying the key.
+
+**Merge the customized catalog with the listing by model id.** Customized users would keep receiving new listed models, but a model the user deleted would return, and the Models page cannot hide one listed model.
+
+**Mark an unset `models` by removing its schema default.** An absent value would select the listing without comparing catalogs, but the Models page would lose the inherited rows it shows and copies, with their hidden `systemPromptUpdate` and `toolUpdate` fields, into a customized catalog. Rows copied from the generic model-discovery API would drop those fields.
+
+**Fetch once per process, or refresh on a timer.** A single fetch leaves a long-running Web or desktop host on its startup catalog, and one transient failure pins it to the built-in catalog. A timer sends requests while the route is idle. Access-triggered background refresh matches the account route.
+
+**Reuse the cached listing after Restore defaults.** The cache could serve a listing loaded before the customization for up to `modelsMaxAgeMs`; the request is cheap, so restoring always reloads it. The reload starts on the next access rather than inside the listener, which keeps credential lookup and its failures on the request path; the Web page's settings refresh makes that access right after the save.
+
+## Consequences
+
+- API-key users on the official endpoint receive listed models without a release, and an older build hides or refuses a model that needs a newer client, as account users' builds do.
+- A customized catalog receives no later listed models until Restore defaults, and a `models` list identical to the built-in catalog counts as uncustomized. The comparison uses the running version's built-in catalog, so a saved list equal to an earlier version's built-in catalog counts as customized once the built-in catalog changes.
+- The Models page shows the built-in rows while the listing is followed, so a model only the listing offers appears only in model selectors, and editing the page's catalog drops it.
+- The first catalog access on the official endpoint can wait up to `modelsTimeoutMs`, and a suite that boots the route there must answer the listing itself to stay off the network.
@@ -0,0 +1,36 @@
+# Agent Note: DeepSeek 官方路由在目录未自定义时跟随官方模型列表
+
+Status: implemented
+
+[English](2026-10-22-deepseek-official-model-listing.md) | 中文
+
+## 问题
+
+`deepseek-official` 路由提供的是 `models` 设置里的内容，而这个设置默认是每个构建自带的目录。DeepSeek API 新增的模型只能随发版到达 API key 用户，而账号路由已经在同一个 origin 上跟随服务端的 `GET /models` 列表。与账号路由不同，官方路由的目录可以由用户编辑：模型页把编辑后的目录存进 `models`，`baseURL` 后面的网关也在这里声明自己的模型。
+
+## 决策
+
+- [`llm-deepseek-api-key`](../../../../packages/llm/llm-deepseek-api-key/README.zh.md) 只在 Messages 的 origin 是 `https://api.deepseek.com`、且 `models` 等于内置目录时，跟随 `GET https://api.deepseek.com/models`，并用 `x-api-key` 携带 API key 鉴权。其他端点或目录不发列表请求。
+- 加载、刷新、兜底、合并与客户端版本门控沿用[账号路由](2026-09-24-deepseek-account-remote-model-catalog.zh.md)的规则：首次访问最多等待 `modelsTimeoutMs`，列表超过 `modelsMaxAgeMs` 后在下一次访问时后台刷新，失败时保留上一份成功的列表或使用内置目录，缓存只在内存中，以端点和 key 指纹为键。
+- 自定义的 `models` 列表整份优先：它替换目录，并停止列表请求。解析结果与内置目录不同的列表才算自定义，因为 schema 默认值会把缺省的 `models` 物化为内置列表，模型页也把这个默认值显示为继承的行。
+- 在自定义目录与列表之间切换时，一个 `loader/volatile-update` 监听器会让缓存失效，因此点恢复默认后，即使缓存的列表尚未过期，下一次访问也会重新加载。
+- 列表请求、缓存、目录解析和门控放在共享的 [Messages 传输包](../../../../packages/llm/llm-deepseek/README.zh.md)中，因为现在有两条路由使用它们；传输层的提供方钩子仍然只有 `connect` 和 `admit`。
+
+## 考虑过的替代方案
+
+**在所有端点上跟随列表。** 发布 OpenAI 风格 `/models` 的网关返回的条目没有 `api_capabilities.anthropic_messages`，解码器会隐藏它们，路由就不提供任何模型。每个这样的网关还会多收到一个携带 key 的请求。
+
+**按模型 id 合并自定义目录与列表。** 自定义用户会继续收到新列出的模型，但用户删掉的模型会重新出现，而模型页无法隐藏某一个列出的模型。
+
+**去掉 `models` 的 schema 默认值来标记未设置。** 缺省值不用比较目录就能选中列表，但模型页会失去它显示的继承行；这些行连同隐藏的 `systemPromptUpdate`、`toolUpdate` 字段会被复制进自定义目录。从通用模型发现 API 复制的行会丢掉这些字段。
+
+**每个进程只获取一次，或按定时器刷新。** 只获取一次会让常驻的 Web 或桌面宿主停留在启动时的目录，一次偶发失败就会让它固定在内置目录。定时器会在路由空闲时发请求。由访问触发的后台刷新与账号路由一致。
+
+**恢复默认后沿用缓存的列表。** 缓存可能在 `modelsMaxAgeMs` 内一直提供自定义之前加载的列表；列表请求代价很小，所以恢复默认总是重新加载。重新加载从下一次访问开始，而不是在监听器里进行，这样凭据查询及其失败都留在请求路径上；Web 页面保存后的设置刷新会立即发起这次访问。
+
+## 影响
+
+- 使用官方端点的 API key 用户无需发版就能看到列出的模型，旧构建会像账号用户的构建一样隐藏或拒绝需要新版客户端的模型。
+- 自定义目录在恢复默认之前收不到之后列出的模型；与内置目录完全相同的 `models` 列表视为未自定义。比较的是当前版本的内置目录，所以保存的列表若等于旧版本的内置目录，内置目录变化后就算作自定义。
+- 跟随列表期间，模型页仍显示内置的行，因此只有列表提供的模型只出现在模型选择器里，在模型页编辑目录会丢掉它。
+- 官方端点上的第一次目录访问可能等待最多 `modelsTimeoutMs`，在该端点上启动路由的测试套件必须自己应答列表请求，才能不访问网络。
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-22-subagent-target-user-controls.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-22-subagent-target-user-controls.md
+/agent-note-user-controls-address-the-target-subagent:
+  en: d7dcf54ddb311881
+  zh: 5f388447737c5414
+/agent-note-user-controls-address-the-target-subagent/problem:
+  en: 962c75771235903c
+  zh: 203b651c0830310e
+/agent-note-user-controls-address-the-target-subagent/decision:
+  en: 13a2617e28445744
+  zh: 75d193ef7d8c7804
+/agent-note-user-controls-address-the-target-subagent/alternatives-considered:
+  en: 447adb24280bf2bb
+  zh: 08d95a93b14aa5c7
+/agent-note-user-controls-address-the-target-subagent/consequences:
+  en: 98e784f55775247d
+  zh: 1c62d2ebc71b658f
@@ -0,0 +1,33 @@
+# Agent Note: User controls address the target subagent
+
+Status: implemented
+
+English | [中文](2026-10-22-subagent-target-user-controls.zh.md)
+
+## Problem
+
+A browser knows the subagent it is displaying, but requiring its direct creator and a continuable marker makes every control caller repeat history metadata. A caller-supplied parent id checks address consistency without establishing the caller's identity or permission. Calls that resolve only the global access resource also cannot express a grant on one target Session.
+
+## Decision
+
+Browser prompts and `interruptByUser` address only the target child Session. Each Remote method explicitly declares that Session as its access resource; the Gateway checks the invocation's principal before attachment admission, restoration, or cancellation. A global or parent Session grant does not imply a child Session grant. Policies decide whether to grant both actions, either action, or inherited access. Same-process user interruption trusts its caller and does not accept a wire-supplied principal.
+
+Prompt delivery derives the live root from the resident Activation or verified persisted creation edges. Only the cold target resumes; its creator can remain offline. Shared delivery retains exact live root checks, shutdown admission, cancellation, capacity, and final inbox acceptance. A root Session is not a target of the browser subagent prompt endpoint. User interruption addresses a resident Activation without persistence reads or restoration; an absent target remains a no-op, and interruption preserves parked input.
+
+Model messages retain the exact live sender and same-tree rule from [tree-wide communication](2026-10-16-tree-wide-agent-communication.md). Model interruption retains its stricter ancestor rule. Creation parents still determine catalog edges, history-address consistency, ancestry, and completion recipients; they are not browser control credentials.
+
+This supersedes the direct-parent addressing requirement for human continuation in [continuable subagents](../feature/2026-07-28-continuable-subagent-conversations.md). That record retains its inbox and durable continuation rationale; tree-wide communication owns its superseded model adjacency and runtime ownership restrictions. No Session format changes.
+
+## Alternatives considered
+
+**Keep the parent check as authorization.** The client supplies the parent id and can obtain it from history. Matching that id does not authorize the principal, and requiring it couples controls to discovery metadata.
+
+**Require a root id from the browser.** The server already derives the runtime owner from the target. Another supplied id adds a consistency check without granting permission; Agent senders still need an independently resolved root to enforce same-tree messaging.
+
+**Unify user and Agent interruption permissions.** A user with a target grant can stop that target, while an Agent may stop only its descendants. Same-tree collaboration does not grant members control over each other's execution.
+
+## Consequences
+
+Remote callers update their prompt fields, interrupt endpoint, and non-owner policy actions and resources; the [upgrade guide](../../../../docs/upgrade-guide/v0.2.1-rc.2/subagent-user-controls/guide.md) owns the migration. History URLs retain parent ids for consistency checks. Cold host prompts may read creation ancestry twice, once to find the live root and again during restoration; no verified-ancestry cache is retained across asynchronous work.
+
+Gateway tests cover target grants, global-only and parent-only refusal, separate send and interrupt actions, owner access, and refusal before side effects. Continuation tests cover nested and cold targets with online or offline creators, unavailable roots, and rejection of a root as a subagent target. The Web interrupt scenario exercises the renamed endpoint and parked-input behavior through the shipped composition.
@@ -0,0 +1,33 @@
+# Agent Note: 用户控制按目标子代理寻址
+
+Status: implemented
+
+[English](2026-10-22-subagent-target-user-controls.md) | 中文
+
+## 问题
+
+浏览器知道当前展示的子代理，但要求提供直接创建者和 continuable 标记，使每个控制调用方都要重复历史元数据。调用方提供的父级 id 只能检查地址一致性，不能确定调用者身份或权限。仅解析出 global 访问资源的调用也无法表达对单个目标 Session 的授权。
+
+## 决策
+
+浏览器提示词和 `interruptByUser` 仅按目标子 Session 寻址。每个 Remote 方法显式声明该 Session 为访问资源；Gateway 在附件接纳、恢复或取消之前检查调用的 principal。global 或父 Session 授权不意味着子 Session 授权。策略决定授予两个操作、其中一个操作，或继承访问权。同进程用户中断信任其调用方，不接受从线上传入的 principal。
+
+提示词投递从驻留 Activation 或经过验证的持久化创建关系中解析在线根。仅恢复冷目标，创建者可以保持离线。共享投递保留精确在线根检查、关闭准入、取消、容量和最终 inbox 接纳。根 Session 不是浏览器子代理提示词端点的目标。用户中断直接寻址驻留 Activation，不读取持久化数据，也不恢复目标；目标缺席仍为无操作，中断保留停放的输入。
+
+模型消息保留[整树通信](2026-10-16-tree-wide-agent-communication.zh.md)中的精确在线发送者和同树规则。模型中断保留更严格的祖先规则。创建父级仍决定目录关系、历史地址一致性、祖先关系和完成通知接收者；它们不是浏览器控制凭证。
+
+本决策取代[可继续的 subagent](../feature/2026-07-28-continuable-subagent-conversations.zh.md)对人工继续执行要求直接父级地址的部分。旧记录保留 inbox 和持久化继续执行的理由；整树通信决策拥有其中已取代的模型相邻关系和运行时所有权限制。Session 格式不变。
+
+## 考虑过的替代方案
+
+**保留父级检查作为授权。** 客户端提供父级 id，也能从历史中取得它。匹配该 id 不能授权 principal，还使控制依赖于发现元数据。
+
+**要求浏览器提供根 id。** 服务端已经能从目标解析运行时所有者。再提供一个 id 只会增加一致性检查，不会授予权限；Agent 发送者仍需要独立解析的根来约束同树消息。
+
+**统一用户和 Agent 的中断权限。** 用户获得目标授权后可以停止该目标，而 Agent 只能停止自己的后代。同树协作不赋予成员控制彼此执行的权限。
+
+## 影响
+
+Remote 调用方需要更新提示词字段、中断端点，以及非 owner 策略的操作和资源；迁移步骤由[升级指南](../../../../docs/upgrade-guide/v0.2.1-rc.2/subagent-user-controls/guide.zh.md)拥有。历史 URL 保留父级 id 用于一致性检查。冷目标的宿主提示词可能读取两次创建祖先：先查找在线根，再在恢复期间验证；不跨异步操作保留已验证祖先缓存。
+
+Gateway 测试覆盖目标授权、仅 global 和仅父级授权的拒绝、独立的发送和中断操作、owner 访问，以及副作用前拒绝。继续执行测试覆盖创建者在线或离线时的嵌套和冷目标、根不可用，以及拒绝把根当作子代理目标。Web 中断场景通过交付组合验证重命名后的端点和输入停放行为。
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-22-subagent-tool-owned-communication.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-22-subagent-tool-owned-communication.md
+/agent-note-subagent-tools-own-communication-guidance:
+  en: 0bd031aa81fbc18d
+  zh: c530e980826698ed
+/agent-note-subagent-tools-own-communication-guidance/problem:
+  en: ac391b569d2bc7e9
+  zh: a95f613aa2b330b8
+/agent-note-subagent-tools-own-communication-guidance/decision:
+  en: 52fb33963bedfe07
+  zh: 75fe66d80f47323f
+/agent-note-subagent-tools-own-communication-guidance/alternatives-considered:
+  en: c55d44c6414e0c4c
+  zh: 9fa2ab31843e259b
+/agent-note-subagent-tools-own-communication-guidance/consequences:
+  en: 52f7234664c515ec
+  zh: 55ec7b54c044e9af
@@ -0,0 +1,27 @@
+# Agent Note: Subagent tools own communication guidance
+
+Status: implemented
+
+English | [中文](2026-10-22-subagent-tool-owned-communication.zh.md)
+
+## Problem
+
+The continuation manager inspected a Symbol on the standard messaging tool before adding tool instructions and parent addressing to the initial task. This coupled orchestration to one tool implementation and made result-delivery guidance depend on tool installation. A published internal entry point carried both that marker and a host prompt adapter used only by tests.
+
+## Decision
+
+`tool-subagent-control` owns messaging instructions and parent addressing. Its logged runtime context gives delegated children their direct creator’s id from the Session header, explains when to send findings, and states that sending does not finish a turn. The context is emitted only for delegated children when the plugin’s own tool definition is admitted in the current scope and step; roots and ordinary Session forks receive none. Communication guidance follows inherited history without changing the shared system prompt or tool schema.
+
+The manager owns result delivery. Local activations with `delivery: 'parent'` receive automatic-result guidance even without messaging tools; caller-owned activations receive no parent-delivery promise. Settlement timing, recipients, output, and suppression of closing text after a final message to the parent remain unchanged. Tool visibility grants no messaging authority.
+
+This supersedes the Symbol identity and initial-task communication-guidance choices in [adjacent messaging](2026-08-27-adjacent-agent-steer-messaging.md). Its message attribution, fixed Steer delivery, and rejection of a separate report operation remain active. The internal entry point and prompt adapter are removed; the [upgrade guide](../../../../docs/upgrade-guide/v0.2.1-rc.2/subagent-user-controls/guide.md) owns caller migration.
+
+## Alternatives considered
+
+**Keep a cross-package marker or add a service hook.** Tool registration already gives its owner the exact definition, and prompt assembly already supplies the current Agent. Another protocol or stored identity has no independent consumer.
+
+**Move all return guidance into the tool.** Automatic parent notification depends on activation delivery, not on messaging capability. The tool must not promise it to caller-owned activations or withhold it from children without tools.
+
+## Consequences
+
+Tests cover visible, hidden and replaced definitions, logged identity, plugin disposal, fork prefix reuse, and parent versus caller result delivery. Recorded-session snapshots cover the assembled prompt and durable runtime context. Tests needing host input use the existing private manager test helper; no production adapter exists solely to expose that helper.
@@ -0,0 +1,27 @@
+# Agent Note: Subagent 工具拥有通信指导
+
+Status: implemented
+
+[English](2026-10-22-subagent-tool-owned-communication.md) | 中文
+
+## 问题
+
+继续执行管理器检查标准通信工具上的 Symbol，随后在初始任务中加入工具说明和父级地址。这让编排依赖一个工具实现，也让结果交付指导取决于是否安装工具。已发布的内部入口同时承载该标记和仅供测试使用的宿主 prompt 适配器。
+
+## 决策
+
+`tool-subagent-control` 拥有通信说明和父级寻址。持久记录的运行时上下文从 Session header 读取委派子级的直接创建者 id，说明何时发送发现，并指出发送不会结束轮次。仅当本插件的工具定义在当前作用域和 step 中可用时，才向委派子级提供上下文；根代理和普通 Session fork 不接收。通信指导位于继承历史之后，不改变共享系统提示词或工具 schema。
+
+管理器拥有结果交付。采用 `delivery: 'parent'` 的本地 activation 即使没有通信工具，也会收到自动结果交付指导；调用方拥有的 activation 不会收到父级交付承诺。结算时序、接收方、输出，以及最后向父级发送消息后省略结束文本的规则保持不变。工具可见性不授予通信权限。
+
+本决策取代[相邻代理通信](2026-08-27-adjacent-agent-steer-messaging.zh.md)中的 Symbol 身份和初始任务通信指导选择。该记录的消息来源归属、固定 Steer 投递，以及不另设 report 操作的决策继续有效。内部入口和 prompt 适配器已删除；调用方迁移由[升级指南](../../../../docs/upgrade-guide/v0.2.1-rc.2/subagent-user-controls/guide.zh.md)说明。
+
+## 考虑过的替代方案
+
+**保留跨包标记或增加 service hook。** 工具注册已经向所有者提供确切定义，提示词组装也已提供当前 Agent。另一套协议或身份存储没有独立消费者。
+
+**把全部返回指导移入工具。** 自动父级通知取决于 activation 的交付方式，而非通信能力。工具不能向调用方拥有的 activation 承诺自动通知，也不能让没有工具的子级缺少交付说明。
+
+## 后果
+
+测试覆盖可见、隐藏及替换的定义、持久记录的身份、插件释放、fork 前缀复用，以及父级与调用方结果交付。录制会话快照覆盖组装后的提示词和持久运行时上下文。需要宿主输入的测试使用现有的私有 manager 测试帮助函数；生产代码不再仅为暴露该帮助函数而保留适配器。
@@ -0,0 +1,22 @@
+# Bilingual-pair consistency record for 2026-10-23-independent-session-forks.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-23-independent-session-forks.md
+/agent-note-ordinary-forks-have-no-durable-creator-relationship:
+  en: 543a84d51e8aea24
+  zh: 24aeec7c3cdf5900
+/agent-note-ordinary-forks-have-no-durable-creator-relationship/problem:
+  en: d2edaafdd83e5974
+  zh: 57ce9ad368c404c2
+/agent-note-ordinary-forks-have-no-durable-creator-relationship/decision:
+  en: aae0053e9dc3be9f
+  zh: bd37095fd5c43c3d
+/agent-note-ordinary-forks-have-no-durable-creator-relationship/compatibility:
+  en: 8393e8526f927134
+  zh: c957cbde9dc6712d
+/agent-note-ordinary-forks-have-no-durable-creator-relationship/alternatives-considered:
+  en: 748aa21283186e02
+  zh: 51d3b0207b250784
+/agent-note-ordinary-forks-have-no-durable-creator-relationship/consequences:
+  en: adcb06ccf7503e55
+  zh: 30e02c6104eefe01
@@ -0,0 +1,35 @@
+# Agent Note: Ordinary forks have no durable creator relationship
+
+Status: implemented
+
+English | [中文](2026-10-23-independent-session-forks.zh.md)
+
+## Problem
+
+Using `parentSession` for both copied history and delegation makes an ordinary fork appear to be a subagent. Consumers can emit false child-start notifications, hide resumable sessions, or impose source-relative ordering. Removing the writer alone leaves historical ordinary forks misclassified and exposes a V4 reader assumption: inherited delivery acknowledgements require a parent id even though the validated seed range already identifies copied events.
+
+## Decision
+
+Ordinary forks preserve their complete selected prefix, `isSeeded`, `inheritedEventCount`, and inherited end-seed marker, but record no source id. Subagents retain their direct creator, including when their backend copies history. `origin: subagent` supplies coarse classification; a valid own-range descriptor separately supplies continuation identity. Historical parent metadata remains readable and unchanged. Runtime Agent ownership remains governed by the [explicit identity decision](2026-08-31-explicit-agent-runtime-identity.md).
+
+The V4 reader permits another Session's delivery id only inside the validated inherited range. Own-range markers still require the current id, and every active-generation `throughSeq` must precede its marker. These checks do not require a persistent source relationship.
+
+## Compatibility
+
+This is a same-version behavior change with no declared persistence-type change. The generated inventory reports no schema transitions, so no new type acknowledgement or finalization checkpoint is needed. Existing ordinary forks and subagent logs retain their meanings, and the new reader accepts both parent-bearing and parentless seeds without rewriting either. Frozen schemas and historical generations remain untouched.
+
+The released `dsh-v0.2.0-rc.2` validator and the reviewed master baseline share the parent-dependent delivery check. Before changing that check, real plain and compressed JSONL probes verified rejection through both read and write opens for parentless ordinary and nested forks, with byte-identical files afterward. Rejection occurs during completed-log relationship validation, before a handle is granted or tail repair runs. Older readers report corruption rather than an upgrade diagnostic; that diagnostic limitation is explicit in the [upgrade guide](../../../../docs/upgrade-guide/v0.2.1-rc.3/independent-session-forks/guide.md). Parentless seeds without active inherited delivery markers remain readable. This observed admission behavior meets the [safe-refusal rule](../process/2026-10-08-session-reader-compatibility-review.md); optionality alone is not the justification.
+
+## Alternatives considered
+
+**Keep the source under another field.** A replacement such as `forkSourceId` preserves the durable relationship the user chose to remove, along with its downstream maintenance cost.
+
+**Erase parent metadata from existing logs.** Historical mutation loses recorded information and violates immutable-generation guarantees. Consumers distinguish old ordinary forks without cleanup.
+
+**Bump the format solely because older readers reject some new logs.** The existing inherited range and complete-log check prevent unsafe execution and truncation. A global bump and adjacent copy add no protection to this transition; same-version refusal has a documented diagnostic limitation.
+
+## Consequences
+
+Ordinary-fork source tracing is intentionally unavailable in new data. Manual ordering preserves saved positions and treats new forks like other ordinary sessions. Operation-local source access preserves title increments and workspace selection. The [side-session proposal](../../proposed/feature/2026-07-08-interactive-side-sessions.md) retains its separate handback idea but cannot use a stored ordinary-fork parent. Runtime ownership, projection-cache identity, and Team membership decisions remain independently useful and are not superseded.
+
+Verification covers real fork/persist/reopen paths for ordinary, nested, historical, and subagent seeds, rejection without writes for foreign own-range delivery and invalid coordinates, SDK notification classification, ACP resume, client ordering, and title generation. TypeScript and Python recorded SDK scenarios create ordinary and nested forks plus historical parent-bearing metadata while retaining the expected real-subagent lifecycle.
@@ -0,0 +1,35 @@
+# Agent Note: 普通 fork 不保留持久创建者关系
+
+Status: implemented
+
+[English](2026-10-23-independent-session-forks.md) | 中文
+
+## 问题
+
+同时用 `parentSession` 表示复制历史和委派，会让普通 fork 看起来像子代理。消费方可能发送错误的子代理启动通知、隐藏可恢复会话，或施加相对来源的排序。仅删除写入仍会误分类历史普通 fork，并暴露 V4 reader 的一项假设：继承投递确认要求父 ID，尽管已验证的 seed 区间已经标识复制事件。
+
+## 决策
+
+普通 fork 保留完整的选定前缀、`isSeeded`、`inheritedEventCount` 及继承结束标记，但不记录来源 ID。子代理保留直接创建者，包括 backend 复制历史的情况。`origin: subagent` 提供粗粒度分类；有效的自身区间 descriptor 单独提供继续运行身份。历史父元数据保持可读且不变。运行时 Agent 归属仍遵循[显式身份决策](2026-08-31-explicit-agent-runtime-identity.zh.md)。
+
+V4 reader 仅在已验证的继承区间中允许其他 Session 的投递 ID。自身区间标记仍要求当前 ID，每个活动代际的 `throughSeq` 必须早于其标记。这些检查不需要持久来源关系。
+
+## 兼容性
+
+这是没有声明持久化类型变化的同版本行为变更。生成清单报告没有 schema 转换，因此不需要新增类型确认或定稿检查点。已有普通 fork 和子代理日志保留其含义，新 reader 接受有父关系及无父关系的 seed，且不改写任一种。冻结 schema 与历史代际保持不变。
+
+已发布的 `dsh-v0.2.0-rc.2` 校验器与所审查 master 基线具有相同的依赖父关系的投递检查。修改此检查之前，真实的普通及压缩 JSONL 探针验证：无父关系的普通和嵌套 fork 在 read、write 打开时都被拒绝，之后文件字节完全一致。拒绝发生在完整日志的关系校验期间，早于授予句柄或尾部修复。旧 reader 报告损坏而非升级诊断；[升级指南](../../../../docs/upgrade-guide/v0.2.1-rc.3/independent-session-forks/guide.zh.md)明确说明这一诊断限制。没有活动继承投递标记的无父关系 seed 仍然可读。这一已观察到的接纳行为满足[安全拒绝规则](../process/2026-10-08-session-reader-compatibility-review.zh.md)；可选字段本身不是依据。
+
+## 考虑过的替代方案
+
+**用其他字段保留来源。** `forkSourceId` 等替代字段保留了用户决定移除的持久关系及其下游维护成本。
+
+**清除已有日志的父元数据。** 修改历史会丢失已记录信息，并违反代际不可变保证。消费方可以在不清理的情况下区分旧普通 fork。
+
+**仅因旧 reader 拒绝部分新日志就升级格式。** 现有继承区间和完整日志检查阻止不安全执行与截断。全局升级和相邻复制不会为这次转换增加保护；同版本拒绝的诊断限制已有明确记录。
+
+## 影响
+
+新数据有意不支持普通 fork 的来源追踪。手动排序保留已保存位置，将新 fork 当作其他普通会话处理。操作期间访问来源保留标题递增和工作区选择。[侧会话提案](../../proposed/feature/2026-07-08-interactive-side-sessions.zh.md)保留独立的交回设想，但不能使用普通 fork 的持久父字段。运行时归属、投影缓存身份和 Team 成员关系决策仍分别有用，未被取代。
+
+验证覆盖普通、嵌套、历史及子代理 seed 的真实 fork／持久化／重新打开路径，自身区间外来投递及非法坐标的无写入拒绝，SDK 通知分类、ACP 恢复、客户端排序与标题生成。TypeScript 和 Python 录制 SDK 场景创建普通及嵌套 fork 和携带历史父元数据的会话，同时保留真正子代理的预期生命周期。
@@ -0,0 +1,22 @@
+# Bilingual-pair consistency record for 2026-09-17-multiline-display-dollar-math.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-17-multiline-display-dollar-math.md
+/agent-note-multi-line-display-dollar-math:
+  en: 8f57c77aa43fbd6c
+  zh: ef5192184e4923d5
+/agent-note-multi-line-display-dollar-math/problem:
+  en: e4b73644a982844c
+  zh: 48f86358242d6ccc
+/agent-note-multi-line-display-dollar-math/decision:
+  en: d6b136b1f62285b7
+  zh: aba323bfdb800162
+/agent-note-multi-line-display-dollar-math/alternatives-considered:
+  en: e0833b5674e648e7
+  zh: b0472020b07099b9
+/agent-note-multi-line-display-dollar-math/consequences:
+  en: 70f16597bd640e93
+  zh: 0e0c9005f331e514
+/agent-note-multi-line-display-dollar-math/testing:
+  en: f17a1453df91ce88
+  zh: 4f15be0139e8b694
@@ -0,0 +1,66 @@
+# Agent Note: Multi-line display-dollar math
+
+Status: implemented
+
+English | [中文](2026-09-17-multiline-display-dollar-math.zh.md)
+
+## Problem
+
+Authors and models write `$$` display math in three shapes. The settled grammar rendered two of them: `$$math$$` on one line, and an opening `$$` alone on its line closed by `$$` alone on its line. The third shape — math on the opening line, a closing `$$` at the end of the last math line — did not:
+
+```markdown
+$$f(x)=x
+\text{continued}$$
+```
+
+`micromark-extension-math` treats text after an opening `$$` as fence meta and accepts a closing fence only on a line whose content is exactly `$$` (after optional whitespace). The [markdown compatibility layer](../../archived/feature/2026-07-23-web-assistant-markdown.md) claimed only the same-line shape, and the settled renderer passes `node.value` to KaTeX while ignoring `node.meta`. The block therefore never closed: it consumed the document text that followed, `value` retained the literal `$$`, KaTeX raised `Can't use function '$' in math mode`, and [katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)'s error arm painted the TeX source plus the swallowed prose in red.
+
+In the session that surfaced this, one chat reply lost lines 22–55 of 55 to a single error span, and six note files lost every line after such a block (up to 500 lines) to one. A second defect shared the mechanism: when a later lone `$$` did close the flow, the opening line had already been assigned to `meta`, so the renderer silently dropped the first line of the formula.
+
+## Decision
+
+[mathCompatibility.ts](../../../../packages/client/ui-primitives/src/markdown/mathCompatibility.ts) gains multi-line display-dollar blocks. Its dollar construct keeps the opening line's text in `mathFlowValue` instead of fence meta and closes at a trailing `$$` on any later content line, so `$$a+b` continued by `c+d$$` becomes one math node.
+
+A `$$` sequence that fails to close ends the candidate: immediately on a later line, and at that line's ending on the opening line (`$$x$$ trailing` fails there). Within the opening line the scan continues, so a later `$$` there still closes (`$$\verb*a$$a$$`). Scanning past either point would consume a later block's closing fence. A solitary `$` is content rather than a failed fence, so a formula that uses one — `$$P = \begin{cases} 1 & \text{if $x>0$} \end{cases}$$` — keeps the block open and closes normally wherever this flow owns the block. A trailing backslash escapes the line ending, not the next line's first character, so the escape run ends at the line ending instead of reaching into the next candidate. An unescaped `%` starts a TeX comment that runs to the line ending, so a `$$` at the end of a later line closes nothing when the comment holds text before it. A `%` whose text before the fence is empty or whitespace (`95%$$`, `95 %$$`) holds no comment text, and a block that opens and closes on one line keeps closing at that line's `$$`, as it did before this flow spanned lines. That state and its gate on the closing check belong to the dollar flow. The characters right after `\verb` or `\verb*` are that command's delimiter rather than a fence, so the delimiter and, when the region is empty, the `$` closing it are content; that tail is cleared at a line ending and after an escaped backslash (`\\verb` is a line break followed by letters), and a comment holds no commands. Otherwise verbatim regions are not parsed, which keeps `\verb`-bearing formulas on the same value path as every other input.
+
+Its paragraph-interruption check declines instead of consuming the line ending, for the dollar construct only. Consuming it there keeps the paragraph open across the line boundary, so the document layer keeps the container and counts the next line lazy for every construct tried afterwards; that made upstream's `mathFlow`, the construct tried after this one, end empty inside a list item. Declining also leaves the interruption decision to that upstream flow, whose own check short-circuits without consuming and claims only the fences it accepts, so a candidate neither construct accepts (`**before` followed by `$$a\$b`) leaves its paragraph intact. The backslash construct has no competing upstream construct and keeps consuming there.
+
+[parse.ts](../../../../packages/client/ui-primitives/src/markdown/parse.ts) registers `mathCompatibility()` after `math()`: micromark dispatches the extension registered last first, so the dollar flow above takes precedence over upstream's `mathFlow` while `math()` still owns inline `$…$`.
+
+## Alternatives considered
+
+**Keep the compatibility layer at same-line `$$…$$`.** The multi-line shape is what GitHub, KaTeX's auto-render, VS Code, and Typora accept, and the form models emit for multi-case formulas; leaving it unparsed means a red error span in place of the formula plus the rest of the document.
+
+**Repair the parsed tree afterwards.** The flow consumes the swallowed text into `mathFlowValue`, where it is indistinguishable from math source; `meta` and `value` cannot be reassembled into the intended block, and the following blocks were never parsed at all.
+
+**Rewrite `$$` fences in the source text before parsing.** The compatibility layer is a grammar extension by design; a text pass would need to locate code spans, fences, and escapes itself, and would change author text rather than parse it.
+
+**Continue the dollar flow after a failed close.** That is what a plain `multiline` flag produces: `$$x$$ trailing\n\n$$y$$` then scans to the second block's `$$` and renders one math node holding both lines' text, where upstream inline math renders `x`, the prose, and `y` separately. Existing behavior for `$$x$$ trailing` already pinned the fallback, so the flow declines the candidate instead. Declining on any `$` rather than a full `$$` sequence also broke formulas that use a solitary `$` inside `\text{}`.
+
+**End the attempt as soon as one line resists parsing.** Declining every failed same-line close swallows nothing but turns `$$a$b` lines into a quadratic scan and drops the solitary-`$` formulas above. The condition is the full `$$` sequence, not the character.
+
+**Claim the paragraph interruption in the check.** Returning success there, as upstream's flow does for the fences it accepts, prevents the lazy bookkeeping that broke the list case, but it also ends the paragraph for candidates that later fail (`**before\n$$a\$b\nafter**` split in two and exposed its `**`). Declining instead lets upstream's own check decide.
+
+**Apply the interruption guard to the backslash construct too.** The guard exists to protect the construct tried after this one; `\[`/`\(` have no second construct, and an unconditional guard dropped their multi-line blocks (`Prose line` followed by `\[`).
+
+## Consequences
+
+The three shapes now produce the same math node, so formulas stop truncating at the opening line and stop swallowing the prose after them. `$$` fence meta is no longer honored: `$$asciimath$$` parses as a formula whose value is `asciimath`, which upstream's flow treats as fence meta and drops. That spelling has no user in this repository, and the renderer never read `meta` anyway.
+
+Six inputs still reach upstream's flow or stay in the surrounding paragraph, because the compatibility flow declines them. Trailing text after a closing `$$` (`$$x$$ trailing`, or a CJK quote mark closing a line of prose) resolves through upstream inline math, as the existing `markdown.client.spec.tsx` case pins — including when a later `$$` block follows. A `$$` sequence the line does not end after declines the block: immediately on a later line, and at that line's ending on the opening line. A `$$` block left open runs to the next lone `$$` or to EOF exactly as it did before this change, because the upstream flow closes at EOF.
+
+The fourth is a multi-line block whose opening line carries a solitary `$` and that must interrupt a paragraph, with no blank line before it. Both flows decline the interruption there — this one by design, upstream because its fence meta stops at the `$` — so the block stays inside the paragraph and renders as inline math or not at all. Separating the block from the paragraph with a blank line makes this flow own it and render the display block.
+
+The fifth follows from the comment gate: a block whose only closing fence sits behind a comment that holds text keeps scanning instead of closing there, so when nothing else closes it the block reaches the upstream flow as the shapes above do. A fence behind a whitespace-only comment closes the block there, which leaves a following lone `$$` as its own empty block where the flow it replaced kept one node.
+
+The sixth is a multi-line block inside a container whose continuation line falls back to the container's indentation. `- Define:` followed by `$$f(x)=x` at the item's indentation and then a de-indented continuation line gives upstream's flow a fence meta and no value, so the reader sees an empty display block and the continuation as prose — the opening line is gone. Keeping the continuation at the same indentation, or moving the block out of the list, renders it normally. Both flow behaviors match the grammar this replaced; only the multi-line blocks this flow owns are new.
+
+One further limitation is not a fallback: the flow reads the six characters before a fence and does not parse verbatim regions, so a fence inside an unterminated region (`\verb|$$`) closes the block there, and a region whose text ends in `\verb` (`\verb**\verb*$$`) has its fence read as that text's delimiter. The six characters before either fence are locally identical, so no rule that reads only that tail separates them.
+
+Repeated unclosed candidates keep linear parser work: an open candidate declines at the next line that starts with a full `$$` it cannot close, rather than scanning each candidate to EOF, which would make 9.6 KB of `$$a$b` lines take ~4 s instead of ~16 ms. KaTeX-level failures in a formula's own source, such as `\arccot`, remain errors by design.
+
+## Testing
+
+`packages/client/ui-primitives/tests/markdown.client.spec.tsx` adds the multi-line case — opening-line math closed on a content line, closed by a lone fence, after a paragraph, inside a list item, and at column zero after a list item — and that case fails without the change. The same file also pins a multi-line formula that uses a solitary `$`, which like the case above renders only with this change. Further cases pin one condition each: a trailing-text candidate ahead of a later block (the flow must decline a full `$$` the line does not end after), a solitary `$` inside a single-line display formula (the flow must not decline on a single `$`), an escaped-dollar candidate that leaves its paragraph intact (the interruption check must not claim the paragraph), an unclosed `\[` candidate that leaves its paragraph intact (the guard must not apply to the backslash construct), a candidate ending in an odd backslash (the escape run must end at the line ending), a closing fence inside a TeX comment, a `%` the fence follows immediately or after whitespace, a second `%` inside an open comment, a `%` inside `\verb|…|`, the delimiter right after `\verb` and `\verb*` together with its empty region, an escaped backslash before `verb`, a verb tail that crosses no line ending, a comment ending in `verb`, a later-line trailing fence whose following prose upstream takes, a failed fence inside a comment, and bounded-work cases for repeated candidates with that backslash, without it, and ending in a verb tail.
+
+The DOM compatibility corpus adds `math-multiline-display` with its `.settled.txt` and `.streaming.txt` fixtures, which also pin that a column-zero `$$` after a list item stays outside the list item. `apps/web/tests/math-rendering.e2e.ts` renders the multi-line shape in the browser lane.
@@ -0,0 +1,66 @@
+# Agent Note: Multi-line display-dollar math
+
+Status: implemented
+
+[English](2026-09-17-multiline-display-dollar-math.md) | 中文
+
+## Problem
+
+作者和模型写 `$$` 行间公式时有三种写法。定稿语法只渲染其中两种：一行内开闭的 `$$math$$`，以及 `$$` 独占一行、由独占一行的 `$$` 闭合。第三种——开围栏同一行就带公式内容，闭合 `$$` 落在最后一行公式行行尾——不渲染：
+
+```markdown
+$$f(x)=x
+\text{continued}$$
+```
+
+`micromark-extension-math` 把开围栏 `$$` 之后的同一行文本当作围栏 meta，并且只接受内容恰为 `$$`（后接可选空白）的行作为闭合围栏。[markdown 兼容层](../../archived/feature/2026-07-23-web-assistant-markdown.md)只认同一行开闭这一种形状，而定稿渲染器把 `node.value` 交给 KaTeX，不读 `node.meta`。于是该块始终不闭合：它吞掉后续正文，`value` 里残留字面 `$$`，KaTeX 抛出 `Can't use function '$' in math mode`，[katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx) 的错误分支把 TeX 原文连同被吞掉的正文一起显示为红色。
+
+在暴露该问题的会话中，一条聊天回复 55 行里有 34 行（第 22–55 行）变成同一个错误块，六个笔记文件从出错点起的所有行（最多约 500 行）同样变成一个错误块。同一机制还带出第二个缺陷：当更靠后的独占行 `$$` 恰好闭合了这个流时，开围栏那一行已经归给 `meta`，渲染器于是静默丢掉公式的第一行。
+
+## Decision
+
+[mathCompatibility.ts](../../../../packages/client/ui-primitives/src/markdown/mathCompatibility.ts) 现在支持跨行的显示美元块。dollar 构造把开围栏同一行的文本留在 `mathFlowValue` 里而不是当作围栏 meta，并在后续任意内容行行尾的 `$$` 处闭合，于是 `$$a+b` 接 `c+d$$` 成为一个 math 节点。
+
+闭合失败的 `$$` 序列会结束该候选：出现在后续行时立即结束；出现在开围栏行时在该行行尾结束（`$$x$$ trailing` 即在此放弃）。在开围栏行内扫描继续，因此同一行更靠后的 `$$` 仍能闭合（`$$\verb*a$$a$$`）。越过这两点继续扫描都会吞掉更靠后一个块的闭合围栏。孤立的一个 `$` 属于公式内容而不是失败的围栏，所以凡是本 flow 拥有该块的场合，用到它的公式——`$$P = \begin{cases} 1 & \text{if $x>0$} \end{cases}$$`——保持块打开并正常闭合。行尾反斜杠转义的是换行本身，不是下一行的第一个字符，因此转义状态在换行处结束，不会延续到下一个候选。未转义的 `%` 会开启延续到行尾的 TeX 注释：当注释在围栏之前还有文本时，块后续行行尾的 `$$` 不闭合任何东西；而围栏之前只有空白或什么都没有的 `%`（`95%$$`、`95 %$$`）不含注释文本，且在一行内开闭的块仍在该行的 `$$` 处闭合，与它跨行之前的行为一致。该状态及其对闭合判定的门控属于 dollar flow。`\verb` 或 `\verb*` 之后的那个字符是该命令的分隔符而不是围栏，因此该分隔符、以及区域为空时紧随其后的那个 `$` 都属于内容；这段尾部状态在换行处、以及在被转义的反斜杠之后清空（`\\verb` 是换行加字母，不是该命令），注释里也不识别命令。除此之外不解析原样文本区域，使含 `\verb` 的公式与其它输入走同一条 value 路径。
+
+它的段落打断检查改为「不认领」，且只作用于 dollar 构造。在那里消耗换行会让段落跨行边界保持打开，document 层因此保留容器并把下一行对随后尝试的所有构造计为 lazy；这正是上游 `mathFlow`（本构造之后被尝试的构造）在列表项内以空块结束的原因。不认领同时把打断决定交给上游 flow：它自己的检查不消耗换行就短路返回，并且只认领它接受的围栏，因此两个构造都不接受的候选（`**before` 后接 `$$a\$b`）保持原段落。反斜杠构造没有竞争的上游构造，仍然照旧消耗换行。
+
+[parse.ts](../../../../packages/client/ui-primitives/src/markdown/parse.ts) 把 `mathCompatibility()` 注册在 `math()` 之后：micromark 先派发最后注册的扩展，上面的 dollar flow 因此优先于上游 `mathFlow`，而行内 `$…$` 仍由 `math()` 负责。
+
+## Alternatives considered
+
+**兼容层维持只处理同一行 `$$…$$`。** 多行写法是 GitHub、KaTeX auto-render、VS Code、Typora 都接受的形状，也是模型写多分支公式时实际采用的形状；不解析它意味着公式位置显示为红色错误块，并连带吞掉后文。
+
+**解析后修补语法树。** 被吞掉的正文已经进入 `mathFlowValue`，与数学源码无法区分；`meta` 和 `value` 无法还原成原意的块，而且后面的块根本没有被解析。
+
+**解析前用文本替换改写 `$$` 围栏。** 兼容层的设计就是语法扩展；文本替换需要自己定位代码 span、围栏和转义，而且改的是作者原文而不是解析它。
+
+**闭合失败后继续扫描。** 这正是单纯打开 `multiline` 会得到的行为：`$$x$$ trailing\n\n$$y$$` 会一路扫到第二个块的 `$$`，渲染成一个同时含着两行文本的 math 节点；而上游行内数学会把 `x`、正文和 `y` 分开渲染。`$$x$$ trailing` 的既有行为已经固定了这条回退，因此该构造放弃这个候选。对任意一个 `$`（而不是完整的 `$$` 序列）就放弃，还会破坏在 `\text{}` 内使用单个 `$` 的公式。
+
+**只要有一行解析不下去就结束尝试。** 对每次同一行闭合失败都放弃虽然不再吞文，却会让 `$$a$b` 这类行变成平方级扫描，并丢掉上面那些含单个 `$` 的公式。判据是完整的 `$$` 序列，不是那个字符。
+
+**在检查阶段认领段落打断。** 像上游 flow 那样返回成功可以避免破坏列表用例的 lazy 记账，但也会让最终失败的候选提前结束段落（`**before\n$$a\$b\nafter**` 被拆成两段并暴露 `**`）。改为不认领，把决定交给上游自己的检查。
+
+**把打断守卫也用在反斜杠构造上。** 这个守卫是为了保护随后被尝试的构造；`\[`/`\(` 没有第二个构造，无条件套用会丢掉它们的跨行块（`Prose line` 后接 `\[`）。
+
+## Consequences
+
+三种写法现在产生同一个 math 节点，公式不再在开围栏那一行被截断，也不再吞掉其后的正文。`$$` 围栏 meta 不再生效：`$$asciimath$$` 会解析成 value 为 `asciimath` 的公式，而上游 flow 会把该段当作 fence meta 丢弃。这种写法在本仓库没有使用者，且渲染器本来就从不读 `meta`。
+
+有六种输入仍会走到上游 flow，或留在所属段落里，因为兼容 flow 主动放弃它们。闭合 `$$` 之后还有文本时（`$$x$$ trailing`，或用中文引号收尾的散文行）走上游行内数学，这一点由 `markdown.client.spec.tsx` 中已有用例固定，后面还有别的 `$$` 块时同样如此。「后面不是行尾」的 `$$` 序列会让块放弃：出现在后续行时立即放弃，出现在开围栏行时在该行行尾放弃。未闭合的 `$$` 块仍像本次改动之前那样延伸到下一个独占行 `$$` 或文件结尾，因为上游 flow 在 EOF 处闭合。
+
+第四种是「开围栏行含孤立 `$`、且需要打断段落、前面又没有空行」的多行块。两个 flow 都不认领这次打断——本 flow 出于设计，上游则因为它的围栏 meta 在 `$` 处即停止——该块因此留在段落里，渲染成行内数学或根本不渲染。用空行把块与段落分开，本 flow 就会拥有它并渲染 display。
+
+第五种来自注释门控：当块唯一的闭合围栏位于「带文本的注释」之后时，块继续扫描而不是在那里闭合，若再没有别的围栏闭合它，就会像上面几种一样走到上游 flow。若围栏之前只有空白，则块在该处闭合，此后单独一行的 `$$` 会成为它自己的空块——而被替换掉的语法那时只给出一个节点。
+
+第六种是容器内续行退回容器缩进的多行块。`- Define:` 之后以列表项缩进写 `$$f(x)=x`，再接一行不缩进的续行，上游 flow 会得到有 meta、无 value 的结果：读者看到一个空的 display 块加一行散文，公式首行无声消失。续行保持同样缩进，或把整块移到列表之外，即可正常渲染。这两种 flow 行为都与本次替换掉的语法一致；真正新增的只是「本 flow 拥有的多行块」。
+
+另有一项不属于回退的限制：flow 只读取围栏之前的六个字符、不解析原样文本区域，因此未闭合区域内部的围栏（`\verb|$$`）会在那里闭合块，而内容以文本 `\verb` 结尾的区域（`\verb**\verb*$$`）其围栏会被读成该文本的分隔符。两种情况下围栏前的六个字符在局部完全相同，仅凭这段尾部无法区分。
+
+重复的未闭合候选保持线性解析开销：未闭合的候选会在下一行遇到无法闭合的完整 `$$` 时放弃，而不是把每个候选都扫到 EOF——否则 9.6 KB 的 `$$a$b` 行会花约 4 秒而不是约 16 毫秒。公式自身源码层面的 KaTeX 失败，例如 `\arccot`，仍按设计报错。
+
+## Testing
+
+`packages/client/ui-primitives/tests/markdown.client.spec.tsx` 新增多行用例——开围栏行内容由内容行行尾 `$$` 闭合、由独占行 `$$` 闭合、出现在段落之后、出现在列表项内，以及列表项之后的零缩进围栏——该用例去掉改动即失败。同一文件还固定了「使用单个 `$` 的多行公式」，它与上面的多行用例一样只有本次改动才会渲染成 display。另有一组用例各自对应一个条件：后面还有块时的尾随文本候选（flow 必须放弃「后面不是行尾」的完整 `$$`）、单行显示公式内的单个 `$`（不得因为一个 `$` 就放弃）、保持段落完整性的转义美元候选（打断检查不得认领段落）、保持段落完整性的未闭合 `\[` 候选（守卫不得作用于反斜杠构造）、以奇数个反斜杠结尾的候选（转义状态必须在换行处结束）、TeX 注释内的闭合围栏、紧邻围栏或只隔空白的 `%`、已开启注释内的第二个 `%`、`\verb|…|` 内的 `%`、`\verb` 与 `\verb*` 之后的分隔符及其空区域、`verb` 之前的转义反斜杠、不跨行的 verb 尾部、以 `verb` 结尾的注释、后续行尾随文本围栏（其后正文由上游接管）、注释内失败的围栏，以及带该反斜杠、不带该反斜杠、以 verb 尾部结尾三种重复候选的有界解析开销。
+
+DOM 兼容语料新增 `math-multiline-display` 及其 `.settled.txt`、`.streaming.txt`，同时固定了「列表项之后的零缩进 `$$` 不进入列表项内」。`apps/web/tests/math-rendering.e2e.ts` 在浏览器 lane 渲染多行写法。
@@ -0,0 +1,22 @@
+# Bilingual-pair consistency record for 2026-10-21-subagent-end-turn-guidance.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-10-21-subagent-end-turn-guidance.md
+/agent-note-subagent-end-turn-guidance-stays-in-the-delegation-paragraph:
+  en: bfafb6d348cf2d21
+  zh: 191bedbfa12b6329
+/agent-note-subagent-end-turn-guidance-stays-in-the-delegation-paragraph/problem:
+  en: 36ff1fff46915956
+  zh: 198c8ca7efaeb5b6
+/agent-note-subagent-end-turn-guidance-stays-in-the-delegation-paragraph/decision:
+  en: 47b44ed9313c2ccf
+  zh: 7ad254f8ef88351d
+/agent-note-subagent-end-turn-guidance-stays-in-the-delegation-paragraph/alternatives-considered:
+  en: d52fa1af379dea5b
+  zh: 4e404994f7a607dc
+/agent-note-subagent-end-turn-guidance-stays-in-the-delegation-paragraph/verification:
+  en: be076216381ea64d
+  zh: 2da8d9819c20e2fe
+/agent-note-subagent-end-turn-guidance-stays-in-the-delegation-paragraph/consequences:
+  en: d7c144cbe750a873
+  zh: 602c06d08572481c
@@ -0,0 +1,44 @@
+# Agent Note: Subagent end-turn guidance stays in the delegation paragraph
+
+Status: implemented
+
+English | [中文](2026-10-21-subagent-end-turn-guidance.zh.md)
+
+## Problem
+
+The delegation guidance paragraph ended with `When only waiting for their results remains, end your turn instead of sleeping or polling; the next result starts a new turn.` A later prompt revert removed that sentence together with unrelated prompt changes.
+
+Before the sentence existed, one long Session slept seven times for 150–240 seconds each (about 25 minutes) waiting for review subagents that finished in 2–9 minutes (#6057). A controlled probe on 2026-10-21 measured the sentence's effect on the model's next message after a child starts: `deepseek-v4-flash` and `deepseek-v4-pro`, 150 requests per arm per model, minimal system prompt, real `subagent` and `bash` schemas, history ending with `started subagent reviewer-1`.
+
+| Arm | Sleep call | Any bash call | Ended turn |
+|---|---|---|---|
+| With the sentence | 0/300 | 7/300 | 291/300 |
+| Without the sentence | 29/300 | 120/300 | 179/300 |
+
+The per-model difference is `0/150` vs `6/150` for flash (p=0.030) and `0/150` vs `23/150` for pro (p=9.6e-8), two-sided Fisher exact. The two remaining samples in the with-sentence arm called `subagent` again instead of ending the turn.
+
+## Decision
+
+The delegation paragraph keeps the end-turn sentence, byte-identical to the text introduced for #6057. Ending the turn does not lose the result: a settled child delivers a user-role notice to its parent, and a notice that reaches an idle parent starts one independent model request ([`dsh-subagent`](../../../../packages/subagent/subagent/README.md)). Hosts that keep children progressing alternate `agent.whenIdle()` and `waitForChildren(agent)` ([ACP `session.ts`](../../../../packages/acp/acp/src/session.ts)), and `dsh-goal-round-driver` waits for running descendants before starting the next goal round.
+
+The sentence stays one literal line. Rewording `the next result starts a new turn` to `each result starts a new turn` would re-render 83 prompt sidecars without a measured behavior change.
+
+## Alternatives considered
+
+**Rely on the tool description.** The `subagent` tool description states that the runtime notifies the model when the child finishes. The probe measured 29/300 sleep calls without the paragraph sentence, so the tool description does not replace it.
+
+**Move the guidance into the tool description.** The paragraph is assembled from the set of visible delegation tools and lists their names; the tool description describes one tool. Moving the sentence changes ownership without changing the behavior it prevents.
+
+**Restore every prompt phrase reverted together with this sentence.** The read guidance and the `run_code` argument order are separate decisions with their own evidence; this note records only the delegation paragraph.
+
+## Verification
+
+- `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` asserts the rendered paragraph for each visible-tool combination, including the restored sentence (9 expectations).
+- 83 `snapshots/**/system-prompt*.expected.md` sidecars carry the restored text and replay through the shipped headless profile in `test:snapshot`.
+- The probe is a one-off controlled measurement and is not committed; its two arms differ only in the guidance sentence.
+
+## Consequences
+
+- Every request with a visible delegation tool carries one more sentence, about 30 tokens.
+- The model ends its turn while only waiting for a delegated result instead of calling `bash sleep` or polling.
+- A future prompt-slimming pass must treat this sentence as load-bearing; the probe table above is the evidence for keeping it.
@@ -0,0 +1,44 @@
+# Agent Note: 委派指导段保留结束本轮说明
+
+Status: implemented
+
+[English](2026-10-21-subagent-end-turn-guidance.md) | 中文
+
+## 问题
+
+委派指导段以 `When only waiting for their results remains, end your turn instead of sleeping or polling; the next result starts a new turn.` 结尾。后来的一次提示词回退把这句和不相关的提示词改动一起删掉了。
+
+这句出现之前，一个长 Session 为了等待 2–9 分钟就结束的 review 子代理，七次 `sleep` 150–240 秒，累计约 25 分钟（#6057）。2026-10-21 的受控探针测量了这句对「子代理启动后模型下一条消息」的影响：`deepseek-v4-flash` 与 `deepseek-v4-pro`，每臂每模型 150 次请求，最小 system prompt，真实 `subagent` 与 `bash` schema，历史以 `started subagent reviewer-1` 结束。
+
+| 组 | sleep 调用 | 任何 bash 调用 | 结束本轮 |
+|---|---|---|---|
+| 有这句 | 0/300 | 7/300 | 291/300 |
+| 无这句 | 29/300 | 120/300 | 179/300 |
+
+分模型差异：flash `0/150` vs `6/150`（p=0.030），pro `0/150` vs `23/150`（p=9.6e-8），双侧 Fisher 精确检验。有这句的一组里剩余 2 次是重新调用 `subagent`，而不是结束本轮。
+
+## 决策
+
+委派段保留结束本轮这句，文本与 #6057 引入的版本逐字一致。结束本轮不会丢失结果：子代理结束后会向父级投递 user-role 通知，通知到达空闲父级会起一次独立的模型请求（[`dsh-subagent`](../../../../packages/subagent/subagent/README.zh.md)）。在子代理继续推进期间，宿主交替等待 `agent.whenIdle()` 与 `waitForChildren(agent)`（[ACP `session.ts`](../../../../packages/acp/acp/src/session.ts)），`dsh-goal-round-driver` 也会等运行中的后代结束再开下一轮 goal。
+
+这句保持为一行字面文本。把 `the next result starts a new turn` 改成 `each result starts a new turn` 会重录 83 个提示词 sidecar，而测不到行为变化。
+
+## 考虑过的替代方案
+
+**只依赖工具描述。** `subagent` 工具描述写明运行时会在子代理结束时通知模型。探针测得没有这句时 sleep 为 29/300，说明工具描述替代不了它。
+
+**把说明移进工具描述。** 这段指导按可见委派工具集合组装并列出工具名，工具描述只描述单个工具。移动这句会改变归属，但不改变它阻止的行为。
+
+**把与这句一起被回退的所有提示词都恢复。** read 指导与 `run_code` 参数顺序是各自有证据的独立决定；本记录只覆盖委派段。
+
+## 验证
+
+- `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 对每种可见工具组合断言渲染出的指导段，包含恢复后的这句（9 条断言）。
+- 83 个 `snapshots/**/system-prompt*.expected.md` sidecar 带有恢复后的文本，由 `test:snapshot` 通过随附 headless profile 回放。
+- 探针是一次性受控测量，未入库；两组只差这一句指导。
+
+## 影响
+
+- 只要存在可见委派工具，每个请求多一句，约 30 token。
+- 模型在只剩等待委派结果时结束本轮，不再调用 `bash sleep` 或轮询。
+- 后续的提示词精简必须把这句当作承重文本；上面的探针表是保留它的证据。
@@ -0,0 +1,22 @@
+# Bilingual-pair consistency record for 2026-10-22-series-start-unchanged-prompt-prefix.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-10-22-series-start-unchanged-prompt-prefix.md
+/agent-note-a-series-start-with-an-unchanged-prompt-keeps-the-surviving-system-node:
+  en: f62e2980951e0cb3
+  zh: 3cd4fd49a89fae40
+/agent-note-a-series-start-with-an-unchanged-prompt-keeps-the-surviving-system-node/problem:
+  en: b2b7d5e9a4850ece
+  zh: cbd91b67969bca02
+/agent-note-a-series-start-with-an-unchanged-prompt-keeps-the-surviving-system-node/decision:
+  en: 8a3404207a36ecfb
+  zh: d8bc1decefa60a20
+/agent-note-a-series-start-with-an-unchanged-prompt-keeps-the-surviving-system-node/verification:
+  en: 1970ea84337ce9b5
+  zh: da5b9928606c07c6
+/agent-note-a-series-start-with-an-unchanged-prompt-keeps-the-surviving-system-node/alternatives-considered:
+  en: 2e87f55619f04607
+  zh: 7ca5a8e9a42a799a
+/agent-note-a-series-start-with-an-unchanged-prompt-keeps-the-surviving-system-node/consequences:
+  en: bf8a9d6c56722efd
+  zh: 18dfdf8a7b9bcb5c
@@ -0,0 +1,39 @@
+# Agent Note: A series start with an unchanged prompt keeps the surviving system node
+
+Status: implemented
+
+English | [中文](2026-10-22-series-start-unchanged-prompt-prefix.zh.md)
+
+## Problem
+
+On an in-history route, a prompt change is appended as a later `system/message`, so node 0 stays stale while the latest surviving node carries the rendering. A surface replacement (compaction, tool-result prune, image offload) starts a new request series. Re-baselining node 0 at a series start while the rendering already matched that latest node emptied the later node and wrote the identical text into node 0. The wire request then differed at its first message, so the provider prefix cache missed from the first token although no prompt text changed.
+
+Real session `session-da55bbc9-…`, turn 710 step 2: `compaction/prune` replaced one tool result (seq 34669, 34670); the next request wrote 7,618 characters identical to the node it emptied (seq 34672, 34673), `request/header` logged reason `series` (seq 34674), and the step billed 722,332 uncached input tokens with 1,152 cache-read tokens (0.16% hit) against about 99.9% on the neighboring steps. A build update at turn 707 had appended the prompt node; nothing changed the rendering at turn 710.
+
+## Decision
+
+`SystemPromptProjection.project` re-baselines node 0 only when the effective text must move: an incapable route, an empty rendering, or a series start whose latest surviving non-empty node text differs from the rendering. When the route is in-history, the rendering is non-empty, and the latest surviving node already holds it, the projection returns no updates and the node stays where the cached history carried it. The loop still records the request series through `request/header` (`series`, or `change` with `startsSeries: true`) and rebuilds declarations as before; when the unchanged-rendering skip coincides with a tool-schema series start, the header records the declaration change without `startsSeries`.
+
+Retry recovery keeps its guarantee: when a retry compaction shadows the latest node, the effective text falls back to an older node, differs from the rendering, and the head is rewritten before users are admitted again. The projection never appends an update after already-admitted users.
+
+## Verification
+
+- [`system-prompt-projection.spec.ts`](../../../../packages/core/agent-loop/tests/system-prompt-projection.spec.ts) pins the no-operation decision for a capable series start whose surviving node already matches.
+- [`system-prompt-admission.spec.ts`](../../../../packages/core/agent-loop/tests/system-prompt-admission.spec.ts) pins the wire request: a compaction replacement with an unchanged rendering keeps both system messages, the previous request messages remain a prefix, and the neighboring steps regain the provider prefix.
+- The [`in-history-series-start`](../../../../snapshots/session/in-history-series-start/) recorded session replays the shipped headless profile through a prompt change and a later surface replacement, pinning the unchanged-rendering series start to two retained prompt versions and no `system/message` event.
+
+## Alternatives considered
+
+**Always keep the appended node and never re-baseline.** Simpler, but a route that cannot append prompts, or a prompt that must clear, still needs a single current head, and a changed rendering at a series start must not append after users already admitted by a failed attempt. Rejected.
+
+**Skip consolidation whenever the head differs.** A stale head is authoritative again on an incapable destination route, because that route ignores later system nodes; the route capability, not the head text, decides whether the later node is effective. Rejected.
+
+**Stop treating local surface replacements as series starts.** A prune changes one tool result, so the cache loss is local, but image-offload and compaction decisions still legitimately start a series; the projection must not depend on which replacement produced the boundary. Rejected: the projection owns the prompt decision.
+
+**Compare reconstructed requests instead of surface text.** The loop derives requests from surface events, so comparing past wire messages would duplicate request reconstruction and still need the same effective-text comparison. Rejected.
+
+## Consequences
+
+- A capable route can retain earlier prompt versions in model history after a series start; they cost input tokens until a later consolidation or compaction shadows them.
+- A tool-schema series start on a route without tool updates no longer writes a `system/message` event, so its header records the declaration change without `startsSeries`. The request still carries the complete active declaration set through the unsupported-route projection (`projectToolUpdates`), while `Session.toolHistory()` keeps its incremental baseline instead of resetting.
+- Consolidation still applies when the rendering actually differs: route switches, prompt updates concurrent with compaction, and retries that shadow the latest node.
@@ -0,0 +1,39 @@
+# Agent Note: 渲染未变的新序列保留存活的系统节点
+
+Status: implemented
+
+[English](2026-10-22-series-start-unchanged-prompt-prefix.md) | 中文
+
+## Problem
+
+在 in-history 路由上，提示词变化会追加为后续的 `system/message`，因此 node 0 保持陈旧，由最新存活节点承载渲染文本。surface 替换（压缩、工具结果剪枝、图片省略）会开启新的请求序列。在渲染文本已经与该最新节点一致时重写 node 0，会清空该节点并把完全相同的文本写进 node 0。于是 wire 请求的第一条消息发生变化，提供方前缀缓存从第一个 token 起未命中，尽管提示词文本没有任何变化。
+
+真实会话 `session-da55bbc9-…` 第 710 轮第 2 步：`compaction/prune` 替换了一条工具结果（seq 34669、34670）；下一次请求写入的 7,618 个字符与它清空的节点完全相同（seq 34672、34673），`request/header` 记录 reason `series`（seq 34674），该步计费 722,332 个未命中输入 token、1,152 个缓存读取 token（命中率 0.16%），而相邻步骤约为 99.9%。第 707 轮的构建更新追加了提示词节点；第 710 轮没有任何东西改变渲染文本。
+
+## Decision
+
+`SystemPromptProjection.project` 只在有效文本必须移动时重写 node 0：不具备能力的路由、空渲染文本，或最新存活非空节点文本与渲染文本不同的新序列开始。当路由为 in-history、渲染文本非空、且最新存活节点已经持有它时，投影不产生任何更新，节点保持在已缓存历史携带它的位置。loop 仍通过 `request/header` 记录请求序列（`series`，或带 `startsSeries: true` 的 `change`），并照旧重建声明；当「渲染未变则跳过」与工具 schema 起因的新序列重合时，header 记录声明变化但不带 `startsSeries`。
+
+重试恢复保持原有保证：重试压缩遮蔽最新节点后，有效文本回退到更旧的节点，与渲染文本不同，于是头节点在用户消息再次被接纳之前重写。投影从不会在已接纳的用户消息之后追加更新。
+
+## Verification
+
+- [`system-prompt-projection.spec.ts`](../../../../packages/core/agent-loop/tests/system-prompt-projection.spec.ts) 固定「能力路由的新序列开始时存活节点文本已一致则不产生操作」的决策。
+- [`system-prompt-admission.spec.ts`](../../../../packages/core/agent-loop/tests/system-prompt-admission.spec.ts) 固定 wire 请求：渲染文本未变的压缩替换保留两条系统消息，上一次请求的消息仍构成前缀，相邻步骤重新获得提供方前缀。
+- [`in-history-series-start`](../../../../snapshots/session/in-history-series-start/) 录制会话通过 shipped headless profile 回放「提示词变化 + 后续 surface 替换」，固定渲染未变的新序列保留两份提示词版本且不写 `system/message` 事件。
+
+## Alternatives considered
+
+**永远保留追加节点、从不重写。** 更简单，但无法追加提示词的路由、或必须清空的提示词仍需要单一当前头节点；新序列开始时若渲染文本确实变化，也不能在失败尝试已接纳的用户消息之后追加。拒绝。
+
+**只要 head 不同就跳过归并。** 在目标路由变为不具备能力时，陈旧 head 会重新成为权威，因为该路由忽略后续系统节点；决定后续节点是否生效的是路由能力，而不是 head 文本。拒绝。
+
+**让局部 surface 替换不再算新序列。** 剪枝只改一条工具结果的文本，缓存损失是局部的，但图片省略与压缩决定仍合理地开启新序列；投影不应依赖是哪种替换制造了边界。拒绝：提示词决策属于投影。
+
+**比较重建后的请求而不是 surface 文本。** loop 从 surface 事件派生请求，比较历史 wire 消息会重复请求重建，而且仍然需要同样的有效文本比较。拒绝。
+
+## Consequences
+
+- 具备能力的路由在新序列开始后可能在模型历史中保留更早的提示词版本；在被后续归并或压缩遮蔽之前，它们会计入输入 token。
+- 不支持工具更新的路由上，工具 schema 变化开启的新序列不再写出 `system/message` 事件，因此其 header 记录声明变化但不带 `startsSeries`。请求仍通过不支持更新的路由投影（`projectToolUpdates`）携带完整的生效声明集合，而 `Session.toolHistory()` 保留其增量基线、不再重置。
+- 渲染文本确实不同时归并仍然生效：路由切换、与压缩同时发生的提示词更新，以及遮蔽最新节点的重试。
@@ -15,8 +15,8 @@
  en: da694641e1d009de
  zh: 9d7492d39039af66
 /agent-note-ptc-mode-the-model-writes-typescript-against-the-tool-registry/decision/the-registry-owns-the-mode:
-  en: 091b7bc49b027353
-  zh: 42dc77a810202694
+  en: 4cd76a34f4712e1a
+  zh: 303ef72a18644d7c
 /agent-note-ptc-mode-the-model-writes-typescript-against-the-tool-registry/decision/the-run-code-tool-and-the-dispatch-bridge:
  en: 6a0e2698b082978e
  zh: fbb03503520b30e9
@@ -40,7 +40,7 @@ The [Node execution decision](../architecture/2026-09-11-sandboxed-node-ptc-runt

 **SDK prompt section.** In `'ptc'`, the lazy `tools:sdk` section in the tool-guidance order band renders the loaded runtime's language declarations plus fixed usage instructions for the scope's visible capabilities (TypeScript by default; the [language-dispatch note](../../archived/feature/2026-07-31-ptc-language-dispatch.md) added Python and the `ctx.ptcRuntime.language` renderer table). It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.

-**Assembly ownership.** `run_code` and `tools:sdk` enter the trusted `system-prompt/assemble` waterfall as normal assembly inputs. A scoped `tools:sdk` section may shadow the global default before dispatch, and a listener may remove or replace either contribution. The waterfall's returned assembly is final, so whoever changes these inputs owns preserving a viable PTC mode protocol when the deployment expects PTC mode to remain usable; no restoration pass overrides deliberate composition.
+**Assembly ownership.** `tools:sdk` enters the trusted `system-prompt/assemble` presentation waterfall as a normal section, while `run_code` stays a provider-owned declaration that the waterfall cannot remove or replace. A scoped `tools:sdk` section may shadow the global default before dispatch, and a listener may remove or replace the section. Whoever changes it owns preserving a viable PTC mode protocol when the deployment expects PTC mode to remain usable; no restoration pass overrides deliberate composition.

 **Codegen.** `jsonSchemaToTs()` maps the `defineTool` JSON-Schema subset to TypeScript, carries schema descriptions into JSDoc, and degrades unsupported constructs to `unknown`. The SDK exposes tools as quoted object keys, supporting arbitrary names without aliases or collisions. Typing is advisory because the runtime strips types before execution.

@@ -40,7 +40,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一

 **SDK 提示词段。** 在 `'ptc'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染所加载运行时语言的声明加固定的使用说明（默认 TypeScript；[语言分发 note](../../archived/feature/2026-07-31-ptc-language-dispatch.md) 加入了 Python 与按 `ctx.ptcRuntime.language` 选择的渲染器表）。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。

-**组装所有权。** `run_code` 和 `tools:sdk` 作为正常的组装输入进入受信任的 `system-prompt/assemble` waterfall。一个 scoped 的 `tools:sdk` 段可以在分发前遮蔽全局默认值，监听器也可以移除或替换任一贡献。waterfall 返回的组装结果是最终的，因此修改这些输入的人有责任在部署期望 PTC mode 可用时保持协议面的完整性；没有恢复 pass 会覆盖有意的组合。
+**组装所有权。** `tools:sdk` 作为正常段进入受信任的 `system-prompt/assemble` 展示 waterfall，而 `run_code` 仍是提供方持有的声明，waterfall 不能移除或替换它。一个 scoped 的 `tools:sdk` 段可以在分发前遮蔽全局默认值，监听器也可以移除或替换该段。修改它的人有责任在部署期望 PTC mode 可用时保持协议面的完整性；没有恢复 pass 会覆盖有意的组合。

 **代码生成。** `jsonSchemaToTs()` 将 `defineTool` 的 JSON Schema 子集映射为 TypeScript，将 schema 描述带入 JSDoc，不支持的构造降级为 `unknown`。SDK 将工具暴露为带引号的对象键，支持任意名称而无需别名或冲突处理。类型是建议性的，因为运行时在执行前会剥离类型。

@@ -12,8 +12,8 @@
  en: 532bb7268d9b93ce
  zh: ad47162233222ab0
 /agent-note-parallel-tool-call-execution-by-per-call-safety/scheduling-and-ordering:
-  en: 4e85280cc5eb8697
-  zh: 8e6b09b1527784fa
+  en: 47010d626ab15117
+  zh: a5b77385d7a3e781
 /agent-note-parallel-tool-call-execution-by-per-call-safety/safety-contract:
  en: 16c4ee08b65ead23
  zh: df80d6e49982615b
@@ -21,11 +21,11 @@
  en: e112957ed8a48039
  zh: 37d63f9ea4968fb2
 /agent-note-parallel-tool-call-execution-by-per-call-safety/verification:
-  en: eb5a6aa84980f0ab
-  zh: eed2680a160e8ed2
+  en: 224b6838130c113f
+  zh: f3d7eb68ab5932fb
 /agent-note-parallel-tool-call-execution-by-per-call-safety/alternatives-considered:
  en: 17becc038bb7df7c
  zh: 673d9a9bdfa39edf
 /agent-note-parallel-tool-call-execution-by-per-call-safety/consequences:
-  en: a5508057bc03f4f6
-  zh: 96b46c59402474c3
+  en: 20a3e29931e01aa0
+  zh: acbfc61dd710d960
@@ -26,7 +26,7 @@ A tagged mode, rather than a public boolean scheduler API, keeps resource-aware

 ## Scheduling and ordering

-The loop waits for the complete assistant message, parses every call once, creates a distinct `ToolExecution` for each call, and scans them in model order. Consecutive parallel calls form one group; every exclusive call forms a singleton group and an ordering barrier. Groups execute sequentially. Classification is lazy: the scheduler resolves the next call after each barrier and reclassifies every later call before replenishing a parallel pool. If a registry mutation makes that call exclusive, the current pool drains before the call starts as the next barrier.
+The loop waits for the complete assistant message, parses every call once, creates a distinct `ToolExecution` for each call, and scans them in model order. Consecutive parallel calls form one group; every exclusive call forms a singleton group and an ordering barrier. Groups execute sequentially. Classification is lazy: the scheduler resolves the next call after each barrier and reclassifies every later call before replenishing a parallel pool. Calls resolve through the step's admitted tool set, so replacing or removing a call's registration makes that unstarted call fail as `UNKNOWN_TOOL`; the scheduler classifies it as exclusive, and the current pool drains before it settles as the next barrier.

 For example:

@@ -66,7 +66,7 @@ Filesystem read relies on a narrow recorder exception: its synchronous observati

 ## Verification

-Unit coverage pins fail-closed classification, typed argument validation, grouping, barriers, live reclassification after registry replacement, the rolling cap, distinct execution objects, middleware order, ordered results and context, abort draining, and scheduler-failure quiescence. First-party tests pin each parallel declaration.
+Unit coverage pins fail-closed classification, typed argument validation, grouping, barriers, rejection of unstarted calls after registry replacement, the rolling cap, distinct execution objects, middleware order, ordered results and context, abort draining, and scheduler-failure quiescence. First-party tests pin each parallel declaration.

 Snapshot coverage pins the visible multi-call transcript: pending calls may overlap while completed results remain model-ordered. PTC mode coverage pins its serial boundary. No provider-backed e2e is required because scheduling is deterministic loop behavior.

@@ -102,6 +102,6 @@ Ordered commits may hold a fast result behind a slow earlier sibling. This prese

 Concurrent external calls can compete for quota or process capacity. Providers own their capacity controls; the loop cap only limits calls from one agent step.

-Tool registration is a scheduling boundary. Registry mutations affect not-yet-started calls because the scheduler reclassifies after each barrier and before every pool replenishment. Already-started calls retain the scheduling decision under which they entered the pool.
+Tool registration is a scheduling boundary. Registry mutations affect not-yet-started calls because the scheduler reclassifies after each barrier and before every pool replenishment. A call runs only the registration its step declared ([conditional tools](../../../../packages/core/tools/README.md)), so a hot reload, MCP reconnect, or skill reload that re-registers a tool mid-step fails that step's unstarted calls of it; the next step declares and runs the new registration. Already-started calls retain the scheduling decision under which they entered the pool.

 A terminal scheduler failure reaches step recovery only after live dispatches settle. Recovery reports uncommitted outcomes as unknown, preserving quiescence and the original failure while keeping later model history usable.
@@ -26,7 +26,7 @@ Status: implemented

 ## 调度与顺序

-循环会等待完整的 assistant 消息，对每个调用只解析一次，为每个调用创建独立的 `ToolExecution`，再按模型顺序扫描。连续的并行调用组成一组；每个独占调用单独组成一组，并构成顺序屏障。各组按顺序执行。分类采用惰性方式：每经过一个屏障，调度器都会解析下一个调用；补充并行池之前，还会重新分类每个后续调用。如果注册表变更使该调用变为独占，当前池会先完全排空，然后该调用才作为下一个屏障启动。
+循环会等待完整的 assistant 消息，对每个调用只解析一次，为每个调用创建独立的 `ToolExecution`，再按模型顺序扫描。连续的并行调用组成一组；每个独占调用单独组成一组，并构成顺序屏障。各组按顺序执行。分类采用惰性方式：每经过一个屏障，调度器都会解析下一个调用；补充并行池之前，还会重新分类每个后续调用。调用通过本步骤的准入工具集合解析，因此替换或移除某个调用的注册后，该尚未开始的调用会以 `UNKNOWN_TOOL` 失败；调度器把它分类为独占，当前池会先完全排空，然后它才作为下一个屏障结束。

 例如：

@@ -66,7 +66,7 @@ Status: implemented

 ## 验证

-单元测试固定了按安全侧原则进行的分类、类型化参数验证、分组、屏障、注册表替换后的运行时重新分类、滚动上限、独立执行对象、中间件顺序、有序结果与上下文、中止排空，以及调度器故障后的完全停稳。第一方测试固定了每项并行声明。
+单元测试固定了按安全侧原则进行的分类、类型化参数验证、分组、屏障、注册表替换后拒绝尚未开始的调用、滚动上限、独立执行对象、中间件顺序、有序结果与上下文、中止排空，以及调度器故障后的完全停稳。第一方测试固定了每项并行声明。

 快照测试固定了可见的多调用 transcript（文本记录）：待处理调用可以重叠执行，已完成结果仍按模型顺序排列。PTC mode 测试固定了其串行边界。此调度属于确定性循环行为，因此无需依赖提供方的 e2e 测试。

@@ -102,6 +102,6 @@ Status: implemented

 并发外部调用可能会争用配额或进程容量。提供方负责自身容量控制；循环上限只限制一个 agent 步骤中的调用数量。

-工具注册是调度边界。调度器会在每个屏障之后以及每次补充池之前重新分类，因此注册表变更会影响尚未启动的调用。已启动的调用保留它们进入池时所依据的调度决策。
+工具注册是调度边界。调度器会在每个屏障之后以及每次补充池之前重新分类，因此注册表变更会影响尚未启动的调用。调用只执行其步骤所声明的注册（[条件工具](../../../../packages/core/tools/README.zh.md)），因此在步骤中途重新注册工具的热重载、MCP 重连或 skill 重载会让该步骤里这个工具尚未开始的调用失败；下一个步骤声明并执行新的注册。已启动的调用保留它们进入池时所依据的调度决策。

 终态调度器故障只有在运行中的派发结算后才会进入步骤恢复。恢复将未提交的执行结果报告为未知，保留完全停稳与原始失败，同时让后续模型历史保持可用。
@@ -9,8 +9,8 @@
  en: a72071eeedb77402
  zh: 818d16ce429fd610
 /agent-note-continuable-subagents/decision:
-  en: 3420195435e02a8f
-  zh: 6156eedb3c23d360
+  en: 6ba1bf6184794aa8
+  zh: 71b4e41556dafb93
 /agent-note-continuable-subagents/decision/materialization-and-public-operations:
  en: c3a83ff748a02143
  zh: 468bf62c8ddabf70
@@ -18,6 +18,8 @@ Parent Agents need to send later work to the same live child without changing it

 ## Decision

+Human control addressing and permissions are superseded by [target Session user controls](../architecture/2026-10-22-subagent-target-user-controls.md); model-message adjacency and parent-owned runtime restrictions are superseded by [tree-wide communication](../architecture/2026-10-16-tree-wide-agent-communication.md). The direct-parent authorization statements below do not govern those current operations.
+
 The shared activation entry point, external execution ownership, and caller-versus-parent result delivery are governed by [Unified subagent activations](../simplification/2026-09-17-unified-subagent-activations.md). This record retains the independent rationale described below.

 A continuable subagent has one durable Session and at most one process-local Activation:
@@ -18,6 +18,8 @@ parent Agent 还需要在不改变当前轮次的前提下，向同一个在线

 ## 决策

+人工控制的地址和权限由[目标 Session 用户控制](../architecture/2026-10-22-subagent-target-user-controls.zh.md)取代；模型消息的相邻关系限制和父级运行时所有权限制由[整树通信](../architecture/2026-10-16-tree-wide-agent-communication.zh.md)取代。下文的直接父级授权表述不约束这些当前操作。
+
 共享 activation 入口、外部执行所有权，以及调用方与父级之间的结果投递选择由[统一 subagent activation](../simplification/2026-09-17-unified-subagent-activations.zh.md) 决策拥有。本记录保留下述独立理由。

 一个可继续 subagent 拥有一个持久化会话，并且至多拥有一个进程内激活：
@@ -9,8 +9,8 @@
  en: e7c3b5d7702714fe
  zh: 268f162b553b37d1
 /agent-note-generic-file-upload/decision:
-  en: 31c7ad96c6ab82c8
-  zh: 806922fc8fcd1242
+  en: 1769950d73d30dca
+  zh: bf296b920ea9b997
 /agent-note-generic-file-upload/alternatives-considered:
  en: 23f386b05e4e79ef
  zh: 0756c4fa30e8d0eb
@@ -21,5 +21,5 @@
  en: 3a50ac370d51cda9
  zh: d490f58922f8795b
 /agent-note-generic-file-upload/related:
-  en: 7579c49eefdb8488
-  zh: 68ad384fd9d2f8f9
+  en: 14e8659b89dc08a8
+  zh: dec5baa11f168e91