před 2 týdny · 112daedd54
--- a/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.md
			
 
				-2026-07-30-client-locale-full-rollout.md: dedfe98ca2b3e64a56518dfa6157244e4d4c16df
			
 
				-2026-07-30-client-locale-full-rollout.zh.md: e9bd1ed19e8b485d812140ab044c779a2ce6e9d3
			
 
				+2026-07-30-client-locale-full-rollout.md: 2d7c919d420f5681007843d5b8aae5c9c53cc275
			
 
				+2026-07-30-client-locale-full-rollout.zh.md: 8546d06a365cabad50cd26c0f50e45e762671588
			
--- a/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.md
@@ -16,7 +16,7 @@ After the typed locale standard seat landed (`locale:` on register → framework
 
				 
			
 
				 **The built-in locale set is closed; the language catalog is extensible.** The package contributes only `zh` and `en`, and typed namespace registration continues to require that bilingual pair. An external client plugin adds a language through `ctx.effect(() => ctx.locale.addLanguage({ id, label, fallback }))` and contributes partial translations through the existing single-locale dictionary registration; language definitions and dictionaries may register in either order. An external language id is its validated BCP 47 tag for preference storage, dictionary lookup, browser matching, and `<html lang>`; `LocaleId` remains a string because the tag carries interoperable language semantics rather than opaque identity. The built-in `zh` definition retains its internal `zh-CN` document tag. Every added language names a registered fallback whose own definition supplies the next fallback, and the chain must terminate at `en`; unknown targets and cycles fail at registration. For each key, lookup walks that chain in the requested namespace, then repeats it in `common`, before displaying the key itself. The Host stores an open string preference; an unavailable saved id remains pending until its language registers, while removal returns an active selection to the available browser match or `en`. Catalog changes advance the `LocaleFace` revision so the Language row follows registration and disposal.
			
 
				 
			
 
				-**Zero-Cordis atoms (ui-primitives) take copy as required props.** `HoverCard`, structured Tool blocks, JSON/Markdown renderers, `ConnectionBanner`, and modal chrome remain runtime-independent; localized plugins pass complete dictionary-driven label objects from their own `t` seat and memoize cache-sensitive objects on the `t` identity. The removal of language-bearing defaults and the complete prop inventory are owned by the [locale-owned copy decision](2026-08-23-locale-owned-client-ui-copy.md).
			
 
				+**Zero-Cordis atoms (ui-primitives) take copy as required props.** `HoverCard`, structured Tool blocks, JSON/Markdown renderers, `ConnectionIndicator`, and modal chrome remain runtime-independent; localized plugins pass complete dictionary-driven label objects from their own `t` seat and memoize cache-sensitive objects on the `t` identity. The removal of language-bearing defaults and the complete prop inventory are owned by the [locale-owned copy decision](2026-08-23-locale-owned-client-ui-copy.md).
			
 
				 
			
 
				 **Every product-authored UI phrase is translated.** Client fallbacks, design labels, trajectory inspection, accessibility names, and formatter units are dictionary-owned under the [locale-owned copy decision](2026-08-23-locale-owned-client-ui-copy.md). User/model/provider/wire text and protocol or code tokens remain verbatim data. Framework-free boot markup still runs before the locale service; the localized application replaces its product copy after activation.
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.zh.md
@@ -16,7 +16,7 @@ typed locale 标准席位（`locale:` 注册声明 → 框架注入强类型 `t`
 
				 
			
 
				 **内置 locale 集合封闭，语言目录可扩展。** 本包只提供 `zh` 与 `en`，类型化命名空间注册仍要求这对双语字典。外部 client 插件通过 `ctx.effect(() => ctx.locale.addLanguage({ id, label, fallback }))` 增加语言，并通过既有的单 locale 字典注册贡献不完整翻译；语言定义与字典可以按任意顺序注册。外部语言 id 是经过校验的 BCP 47 标签，同时用于偏好存储、字典查找、浏览器匹配和 `<html lang>`；该标签承载可互操作的语言语义而非不透明身份，因此 `LocaleId` 保持 string。内置 `zh` 定义继续使用内部 `zh-CN` 文档标签。每个新增语言都声明一个已注册的 fallback，fallback 自身的定义给出下一层 fallback，整条链必须终止于 `en`；未知目标和循环在注册时失败。每个 key 先在请求的命名空间中沿链查找，再在 `common` 中重复同一条链，最后显示 key 本身。Host 存储开放字符串偏好；不可用的已保存 id 会保持待采用，直至对应语言注册；定义移除后，正在使用的选择会回落到可用的浏览器匹配或 `en`。目录变更推进 `LocaleFace` revision，使语言设置行跟随注册和 dispose。
			
 
				 
			
 
				-**zero-Cordis 原子组件（ui-primitives）通过必填 prop 接收文案。** `HoverCard`、结构化工具块、JSON/Markdown 渲染器、`ConnectionBanner` 和 modal chrome 均保持运行时独立；已本地化插件从自己的 `t` 席位传入完整的字典驱动 label 对象，对缓存敏感的对象按 `t` 身份 memo。移除带语言默认值以及完整 prop 清单由 [locale 归属文案决策](2026-08-23-locale-owned-client-ui-copy.zh.md)负责。
			
 
				+**zero-Cordis 原子组件（ui-primitives）通过必填 prop 接收文案。** `HoverCard`、结构化工具块、JSON/Markdown 渲染器、`ConnectionIndicator` 和 modal chrome 均保持运行时独立；已本地化插件从自己的 `t` 席位传入完整的字典驱动 label 对象，对缓存敏感的对象按 `t` 身份 memo。移除带语言默认值以及完整 prop 清单由 [locale 归属文案决策](2026-08-23-locale-owned-client-ui-copy.zh.md)负责。
			
 
				 
			
 
				 **所有产品编写的 UI 短语都翻译。** client 兜底文案、设计 label、trajectory 检查面、无障碍名称和格式化单位均按 [locale 归属文案决策](2026-08-23-locale-owned-client-ui-copy.zh.md)进入字典。用户/模型/提供方/wire 文本以及协议或代码 token 仍作为数据原样呈现。不依赖框架的 boot 标记仍早于 locale 服务运行；本地化应用激活后会替换其中的产品文案。
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
			
 
				-2026-08-02-typert-remote-method-calls.md: b95e3f0dec56287cbec2586921477284d0489a40
			
 
				-2026-08-02-typert-remote-method-calls.zh.md: 50f04fd44a06ae3914998f0337fef09c75fe707c
			
 
				+2026-08-02-typert-remote-method-calls.md: 9102d04266626a8692e1d3ec5cb8f529d8c34d13
			
 
				+2026-08-02-typert-remote-method-calls.zh.md: bf9ec58b28c1e1e833d92d76737890d49f0487a3
			
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-02-typert-remote-method-calls.zh.md)
 
				 
			
 
				 ## Problem
			
 
				 
			
 
				-The Host API Proxy handles direct method calls, stateful interactions, and Session event streams. These concerns have different lifecycles, routing semantics, and client programming interfaces. Continuing to export all business operations through one package would couple business Services, transport protocols, state machines, and client types.
			
 
				+The Host API Proxy handled direct method calls, stateful interactions, and Session event streams in one package. These concerns have different lifecycles, routing semantics, and client programming interfaces. Continuing to export all business operations through one package would couple business Services, transport protocols, state machines, and client types.
			
 
				 
			
 
				 This decision covers only targeted method calls in which one request produces one result. Stateful interactions such as Permission and Approval, as well as Session event streams, remain separate designs.
			
 
				 
			
@@ -22,7 +22,7 @@ The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. T
 
				 
			
 
				 `@deepseek-ai/dsh-api-gateway`, located at `packages/api/gateway`, provides two symmetric faces: its default entry provides Host `ctx.typertGateway`, while its `/client` entry provides consumer-side `ctx.remote`. Each side consumes a locally generated `InvocationDescriptor` from the same model; descriptors are not sent over the wire. The Remote data protocol runs over Connection's shared `/api` RPC channel. The business calling interface does not change when Connection migrates from HTTP to WebSocket.
			
 
				 
			
 
				-`@deepseek-ai/dsh-api-remotes`, located at `packages/api/remotes`, is the BFF layer above the Gateway. Its Host entry owns Agent/Session identity resolution and Typert lookup configuration; its `/client` entry selects the generated Remote contributions exposed by the application. The Client entry consumes the shared `TypertClientRemote` contract through Cordis rather than importing the concrete Gateway implementation.
			
 
				+`@deepseek-ai/dsh-api-remotes`, located at `packages/api/remotes`, is the BFF layer above the Gateway. Its Host entry registers the application's forwarded Cordis event source and the Host facts carried by generation readiness; its `/client` entry selects the generated Remote contributions exposed by the application. The Client entry consumes the shared `TypertClientRemote` contract through Cordis rather than importing the concrete Gateway implementation.
			
 
				 
			
 
				 ## Components and Cordis services
			
 
				 
			
@@ -32,7 +32,7 @@ The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. T
 
				 | Typert registry | `ctx.typert` | Separately stores reflection for the current environment, imported Remote contributions, lookup providers, and Context providers |
			
 
				 | Typert generator/loader | No new business service | Generates three kinds of `lib` artifacts from the Host/Client Programs and registers the current environment's artifacts with `ctx.typert` |
			
 
				 | API Gateway's Host face | `ctx.typertGateway` | Associates Host definitions with live Services, decodes parameters, resolves receivers, invokes methods, and encodes results |
			
 
				-| Connection | `ctx.connection` | Exclusively owns the HTTP Server/future WebSocket, the shared `/api` route, RPC envelope, rpcId, serialization, trust, error transport, Typert interception, and legacy API Proxy fallback |
			
 
				+| Connection | `ctx.connection` | Exclusively owns the HTTP Server/future WebSocket, the shared `/api` route, RPC envelope, rpcId, serialization, trust, error transport, Typert interception, and owner-registered exact Fetch routes on the same channel |
			
 
				 | API Gateway's Client face | `ctx.remote`, `ctx.remote.<namespace>` | Mounts Remote contributions, materializes each namespace as a traced `remote.<namespace>` child Service, and delegates canonical calls to `ctx.connection.rpc` |
			
 
				 | API Remotes | No new service | Owns Host Agent/Session lookup policy and serves as the only Client business facade, selecting and mounting `/remote` contributions while exposing the selected API declarations |
			
 
				 | Agent/Session owning packages | Existing domain services | Provide both static interface merges and runtime lookup/Context providers |
			
@@ -162,9 +162,9 @@ ctx.typert.contexts  Host Context resolvers and Client Context binders
 
				 
			
 
				 Every registration returns a disposer owned by the caller's Cordis fiber. Client contribution mounting registers the descriptor set and concrete methods as one owned operation. The Host Gateway caches only the set of SRC-owned endpoint names and discards it whenever the Cordis Service set changes; it retains no descriptor, Service, or provider. Invocation resolves all live objects from current state, so removing a strict definition, Service, or provider makes the corresponding call unavailable without leaving a stale live object.
			
 
				 
			
 
				-The lookup registry retains the stable wire declaration after its live resolver unloads. SRC parsing continues to classify the parameter as a lookup, while invocation fails with `lookup-unavailable`; it never reclassifies the incoming ID as an ordinary JSON business object. Re-registering the same key with different parameter, wire, or canonical type symbols fails for the lifetime of that Typert Service.
			
 
				+The lookup registry retains the stable wire declaration after its live resolver unloads. SRC parsing continues to classify the parameter as a lookup, while invocation fails with `gateway/lookup-unavailable`; it never reclassifies the incoming ID as an ordinary JSON business object. Re-registering the same key with different parameter, wire, or canonical type symbols fails for the lifetime of that Typert Service.
			
 
				 
			
 
				-Business-object and scoped-Context packages own stable declarations and default resolvers through `lookups.register()` and `contexts.registerHost()`; Host composition supplies effect-scoped asynchronous policies through `lookups.configure()` and `contexts.configureHost()`. Configuration may precede provider registration, but does not by itself make an identity available without a live provider; unloading the configuration restores the provider's default resolver. API Remotes creates the shared `agentFor()` resolver for `agent` and `session` lookups and the `agent` Host Context: live Agents are reused, ordinary cold sessions are resumed automatically, concurrent resumes are deduplicated by Session ID, and the subagent ownership fence returns the existing `agent-busy`. The standard Web API Proxy supplies its Agent defaults and scope setup and consumes that resolver for legacy methods. The `session` lookup returns the resolved Agent's Session, while the `agent` Host Context returns its Context, so all three projections share one resume lifecycle.
			
 
				+Business-object and scoped-Context packages own stable declarations and default resolvers through `lookups.register()` and `contexts.registerHost()`; Host composition supplies effect-scoped asynchronous policies through `lookups.configure()` and `contexts.configureHost()`. Configuration may precede provider registration, but does not by itself make an identity available without a live provider; unloading the configuration restores the provider's default resolver. The Session Controller's `ApiSessionAgentController` configures one shared resolver for the `agent` and `session` lookups and the `agent` Host Context: live Agents are reused, ordinary cold sessions are resumed automatically, concurrent resumes are deduplicated by Session ID, and the subagent ownership fence returns `session/agent-busy`. The `session` lookup returns the resolved Agent's Session, while the `agent` Host Context returns its Context, so all three projections share one resume lifecycle.
			
 
				 
			
 
				 The registry's Host root entry has the complete `TypertRegistryContract` interface merge. The registry implementation shared by Host and Client lives in a separate module without environment declarations. The registry's `/client` entry imports only that shared implementation and does not pass through the Host root entry, so it cannot bring Host Cordis declarations into the Client Program.
			
 
				 
			
@@ -254,7 +254,7 @@ interface TypertRemoteNamespace$676f616c73 {
 
				     agentId: SessionId,
			
 
				     request: CreateGoalRequest,
			
 
				     signal?: AbortSignal,
			
 
				-  ) => Promise<CreateGoalResult>
			
 
				+  ) => Promise<RemoteResult<CreateGoalResult>>
			
 
				 }
			
 
				 
			
 
				 interface TypertRemoteMap {
			
@@ -262,7 +262,7 @@ interface TypertRemoteMap {
 
				     agentId: SessionId,
			
 
				     request: CreateGoalRequest,
			
 
				     signal?: AbortSignal,
			
 
				-  ) => Promise<CreateGoalResult>
			
 
				+  ) => Promise<RemoteResult<CreateGoalResult>>
			
 
				 }
			
 
				 
			
 
				 interface TypertRemoteNamespaceMap {
			
@@ -273,7 +273,7 @@ interface TypertRemoteScopeMap {
 
				   'agent:goals/create': (
			
 
				     request: CreateGoalRequest,
			
 
				     signal?: AbortSignal,
			
 
				-  ) => Promise<CreateGoalResult>
			
 
				+  ) => Promise<RemoteResult<CreateGoalResult>>
			
 
				 }
			
 
				 ```
			
 
				 
			
@@ -288,7 +288,9 @@ agentCtx.remote.goals.create(request)
 
				 
			
 
				 The Agent Scope supplies its own `SessionId` automatically. A `@Remote` method with an `agent` lookup can therefore generate both root and scoped consumer signatures. A `@RemoteScope('agent')` method also omits a separate Scope identity, but generates only the scoped signature. The root `Context` exposes direct namespaces through `ctx.remote`, while `AgentContext.remote` intersects that direct surface with the scoped surface. A future TUI must preserve the same distinction.
			
 
				 
			
 
				-`TypertClientRemote` remains platform-independent, and the Browser Client exposes it as `ctx.remote`. If a future TUI reuses this type, it must likewise access it through a dedicated Remote object and Agent Scope rather than treating the Host `Context` as a broader Service collection. Public Service methods without Remote markers do not enter the Remote maps.
			
 
				+Every generated method resolves to `Promise<RemoteResult<T>>`: a call reports its outcome in the result's `ok` branch instead of rejecting, and only an assembly fault (arity, an unmounted method, a missing Context adapter) still throws. A consumer branches on `result.ok`, and reads `result.error.code` when it must distinguish failures; the failure vocabulary itself is [one Remote failure class plus a merged code table](2026-08-28-ctx-remote-failure-vocabulary.md).
			
 
				+
			
 
				+`TypertClientRemote` remains platform-independent, and the Browser Client exposes it as `ctx.remote`. If a future TUI reuses this type, it must likewise access it through a dedicated Remote object and Agent Scope rather than treating the Host `Context` as a broader Service collection. Public Service methods without Remote markers do not enter the Remote maps. Beside the generated namespaces, the Gateway's client face adds `$mount`, `$on`, `$stream`, and `$host` — the last exposing the connection's fixed Host facts (`home`, `isLoopback`) as plain reads, so a consumer never injects the carrier to learn them.
			
 
				 
			
 
				 ## Client Typert and the API Gateway Client face
			
 
				 
			
@@ -361,7 +363,7 @@ CI and releases use LIB. Moving all repository coverage to LIB is separate follo
 
				 
			
 
				 ## Host Gateway resolution
			
 
				 
			
 
				-The Host Gateway registers one `/api` interceptor with Connection and does not maintain a second endpoint registry. Its ownership matcher checks the current Typert local registry first, then consults an invalidation-aware set populated by scanning current Cordis Services for `typertGateway` bindings and SRC Remote markers. A Cordis Service change discards the set, so Typert definitions and business Services may arrive in either order without making legacy `/api` traffic rescan every Service on each request or letting arbitrary request paths grow the cache.
			
 
				+The Host Gateway registers one `/api` interceptor with Connection and does not maintain a second endpoint registry. Its ownership matcher checks the current Typert local registry first, then consults an invalidation-aware set populated by scanning current Cordis Services for `typertGateway` bindings and SRC Remote markers. A Cordis Service change discards the set, so Typert definitions and business Services may arrive in either order without rescanning every Service on each request or letting arbitrary request paths grow the cache.
			
 
				 
			
 
				 Invocation resolves the descriptor, receiver, lookup providers, and Context provider again from current state. A current strict descriptor takes precedence over SRC. After a strict endpoint has appeared, `TypertLocalRegistry.hasSeen()` keeps it owned when that descriptor is withdrawn and forbids SRC fallback for the remainder of the registry lifetime; re-registering the strict descriptor restores calls. Removing a Service or provider makes invocation fail explicitly, and the Gateway neither retains invalid objects nor invokes a method with a raw lookup ID.
			
 
				 
			
@@ -399,9 +401,9 @@ ctx.connection.rpc.intercept(
 
				 )
			
 
				 ```
			
 
				 
			
 
				-The Gateway claims an endpoint when the Host registry contains its strict descriptor, remembers a withdrawn strict descriptor, or finds a matching `@Remote` marker on an active SRC Service binding. A claimed endpoint stays in the Gateway after payload decoding, descriptor resolution, or invocation fails; only an endpoint that is not Remote-owned reaches the legacy API Proxy fallback.
			
 
				+The Gateway claims an endpoint when the Host registry contains its strict descriptor, remembers a withdrawn strict descriptor, or finds a matching `@Remote` marker on an active SRC Service binding. A claimed endpoint stays in the Gateway after payload decoding, descriptor resolution, or invocation fails; an endpoint that neither an exact Fetch route nor the Gateway claims answers 404.
			
 
				 
			
 
				-The Connection Host half passes one composite FetchHandler to the HTTP bridge. After the bridge creates a standard `Request`, that handler selects either the Gateway RPC FetchHandler or the API Proxy FetchHandler. Both paths reuse the same request/response envelope, rpcId, serialization, trust, transport errors, and `RpcError`. The current physical mapping is:
			
 
				+The Connection Host half passes one composite FetchHandler to the HTTP bridge. After the bridge creates a standard `Request`, that handler matches the pathname against the exact Fetch routes owners registered on the channel, then against the channel's single interceptor — the Gateway — and answers 404 when neither claims it. Every path on the channel reuses the same request/response envelope, rpcId, serialization, trust, and error transport, and a failure carries the shared `{ code, message, details }` data. The current physical mapping is:
			
 
				 
			
 
				 ```text
			
 
				 POST /api/<namespace>/<method>
			
@@ -438,15 +440,15 @@ ctx.remote.goals.create(sessionId, request, signal?)
 
				 → Client result codec 验证并返回 CreateGoalResult
			
 
				 ```
			
 
				 
			
 
				-Remote does not define a second-layer `{ ok, value/error }` response. Successful values and Gateway errors use the existing RPC response's `result` directly. The adapter converts ordinary Gateway and business-invocation failures to the existing `RpcError` envelope with `code: 'internal'`; an existing RPC error carried by a resolver in `TypertLookupFailure` is returned unchanged, preserving stable error codes for cold-resume failures and ownership fences. The Gateway's structured error category remains available only in-process, while the message carries the diagnostic across Connection.
			
 
				+Remote does not define a second-layer `{ ok, value/error }` response on the wire. Successful values and failures use the existing RPC response's `result` directly, and the failure branch carries the shared `{ code, message, details }` data. Owners, resolvers, and the Gateway all raise one class, `RemoteError`, whose code comes from the merged `RemoteErrorDetailsMap`: the Host encodes a structurally identified `RemoteError` onto the wire unchanged — including the Gateway's own `gateway/*` assembly codes and a resolver's `session/not-found` or `session/agent-busy` — and folds only an unclassified throw into `gateway/internal`, keeping its diagnostic in the message. The Client face rebuilds an instance for the `RemoteResult` error branch, so `throw result.error` keeps throw semantics. [The failure-vocabulary Agent Note](2026-08-28-ctx-remote-failure-vocabulary.md) owns the code table, its ownership rules, and why discrimination reads `code` instead of `instanceof`.
			
 
				 
			
 
				-The Gateway does not handle per-method permissions, caller identity, idempotency, or long-lived connection state. It only propagates cooperative cancellation from Connection into explicitly cancellation-aware business methods. Typert endpoints use Connection's trusted-host policy; unclaimed endpoints retain the legacy API Proxy's trust and privileged-method policies. Connection's WebSocket migration remains separate follow-up work.
			
 
				+The Gateway does not handle per-method permissions, caller identity, idempotency, or long-lived connection state. It only propagates cooperative cancellation from Connection into explicitly cancellation-aware business methods. Every request on the shared channel, Typert endpoint or exact Fetch route alike, passes Connection's browser authentication and trusted-host policy before dispatch; the Gateway adds no second policy. Connection's WebSocket migration remains separate follow-up work.
			
 
				 
			
 
				 ## Connection and protocol boundaries
			
 
				 
			
 
				 The Client Remote Service owns Remote contributions, namespace Service materialization, Scope binding, and the correspondence between positional parameters and descriptors. The Gateway owns Host descriptors, endpoint ownership, lookup, Context, and business invocation. Connection sends `/api`, the endpoint, and `{ args }` as one RPC call to the target and returns the existing RPC result; it does not understand Goal, Agent, lookup, descriptors, or Client Remote types.
			
 
				 
			
 
				-The Gateway registers only its ownership matcher and RPC handler with Connection; it does not register an HTTP route. Connection mounts the shared `/api` route into the HTTP Server and gives the bridge one composite FetchHandler; that handler dispatches claimed endpoints to Gateway and unclaimed endpoints to API Proxy. A future Connection transport can preserve this order without changing the Remote payload, business decorators, generated DTS, Remote API types, or Agent Scope programming interface.
			
 
				+The Gateway registers only its ownership matcher and RPC handler with Connection; it does not register an HTTP route. Connection mounts the shared `/api` route into the HTTP Server and gives the bridge one composite FetchHandler; that handler dispatches an exact registered path to its route owner, a claimed endpoint to the Gateway, and anything else to 404. A future Connection transport can preserve this order without changing the Remote payload, business decorators, generated DTS, Remote API types, or Agent Scope programming interface.
			
 
				 
			
 
				 ## Package boundaries
			
 
				 
			
@@ -454,19 +456,19 @@ The Gateway registers only its ownership matcher and RPC handler with Connection
 
				 - Typert generator: analyzes Host/Client Programs, generates local faces and Remote consumer projections, and emits canonical symbol/Zod information.
			
 
				 - Typert runtime: separately stores the current environment's local reflection and imported Remote contributions.
			
 
				 - `@deepseek-ai/dsh-api-gateway`: its default entry associates Host definitions with Services, claims Remote endpoints, performs lookup, resolves Context receivers, invokes methods, encodes results, and registers an `/api` interceptor with Connection; its `/client` entry mounts Remote contributions, creates strict Remote namespace Services and methods, and delegates calls to `ctx.connection.rpc`. The entries share the Remote protocol but do not import each other's Cordis interface merges.
			
 
				-- `@deepseek-ai/dsh-api-remotes`: the BFF layer; owns the Host Agent/Session resolver, selects Client `/remote` contributions, and exposes the merged Remote types to business packages through the shared `TypertClientRemote` contract.
			
 
				-- Connection: owns the single HTTP Server/future WebSocket carrier, shared `/api` route and composite FetchHandler, API Proxy fallback, RPC envelope, rpcId, serialization, trust, and error transport.
			
 
				+- `@deepseek-ai/dsh-api-remotes`: the BFF layer; registers the application's forwarded Cordis event source and the Host home carried by generation readiness, selects Client `/remote` contributions, and exposes the merged Remote types to business packages through the shared `TypertClientRemote` contract.
			
 
				+- Connection: owns the single HTTP Server/future WebSocket carrier, the shared `/api` route and its composite FetchHandler, owner-registered exact Fetch routes, the RPC envelope, rpcId, serialization, trust, and error transport.
			
 
				 - Business-object packages such as Agent/Session: own lookup, Context providers, canonical ID types, and public type-only entries.
			
 
				-- API Proxy Host composition: supplies Web Agent defaults and scope setup to API Remotes and consumes the same `agentFor()` for legacy methods.
			
 
				+- `@deepseek-ai/dsh-api-session-controller`: configures the shared `agent`/`session` lookup and `agent` Host Context resolver, so every Remote endpoint that accepts one of those objects shares one resume and ownership-fence policy.
			
 
				 - Business Service packages: declare bindings, Remote methods, and their request/result types, and export the generated `/remote` subpath.
			
 
				 
			
 
				 ## Shipped scope and deferred work
			
 
				 
			
 
				-The shipped vertical path is `@deepseek-ai/dsh-goal/remote → Browser Client Remote → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`. The same direct descriptor with an Agent lookup supports both `ctx.remote.goals.create(agentId, request)` and `agentCtx.remote.goals.create(request)`. Ordinary cold sessions are resumed through `agentFor()` during lookup, while subagent-owned identities retain the existing `agent-busy` fence; `@RemoteScope('agent')` remains the distinct scoped-receiver mode.
			
 
				+The shipped vertical path is `@deepseek-ai/dsh-goal/remote → Browser Client Remote → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`. The same direct descriptor with an Agent lookup supports both `ctx.remote.goals.create(agentId, request)` and `agentCtx.remote.goals.create(request)`. Ordinary cold sessions are resumed by the shared lookup resolver, while subagent-owned identities retain the `session/agent-busy` fence; `@RemoteScope('agent')` remains the distinct scoped-receiver mode.
			
 
				 
			
 
				 Connection supplies the shared-channel interceptor and current HTTP carrier mapping. WebSocket migration, the TUI runtime and carrier, TUI Agent Scope wiring, Permission/Approval state machines, Session event streams, call authorization, retries, idempotency, and cross-version protocol compatibility remain outside this decision.
			
 
				 
			
 
				-The package topology is `api/remotes → api/gateway → client/connection → host/webserver`. Connection and WebServer retain their existing paths in this change; moving them later to `api/connection` and `api/webserver` changes package placement rather than these service boundaries. The legacy API Proxy likewise remains under `host/apiproxy` as the fallback for methods not yet migrated to Remote.
			
 
				+The package topology is `api/remotes → api/gateway → client/connection → host/webserver`. Connection and WebServer retain their existing paths in this change; moving them later to `api/connection` and `api/webserver` changes package placement rather than these service boundaries.
			
 
				 
			
 
				 ## Alternatives considered
			
 
				 
			
@@ -486,7 +488,7 @@ The package topology is `api/remotes → api/gateway → client/connection → h
 
				 
			
 
				 **Let a top-level `/remote` import register global state implicitly.** The target Cordis Context may not exist when ESM evaluation occurs, and ownership becomes ambiguous across multiple Contexts, HMR, and disposal. A normal value import therefore returns only a contribution, which the environment assembly explicitly mounts through the Client Remote Service.
			
 
				 
			
 
				-**Create a separate transport, HTTP route, or `/api2` channel for Remote.** This would duplicate or split Connection's Server ownership, rpcId, serialization, trust, errors, and future WebSocket lifecycle. The shared `/api` interceptor instead keeps one physical route and lets Connection preserve API Proxy as the fallback FetchHandler.
			
 
				+**Create a separate transport, HTTP route, or `/api2` channel for Remote.** This would duplicate or split Connection's Server ownership, rpcId, serialization, trust, errors, and future WebSocket lifecycle. The shared `/api` interceptor instead keeps one physical route and lets Connection compose it from owner-registered exact Fetch routes and the channel's single interceptor.
			
 
				 
			
 
				 ## Verification
			
 
				 
			
@@ -496,11 +498,11 @@ The package topology is `api/remotes → api/gateway → client/connection → h
 
				 - Importing `@deepseek-ai/dsh-goal/remote` adds the strict `ctx.remote.goals.create(...)` type and declaration navigation to `remoteExportCreate`; omitting that import omits the namespace.
			
 
				 - Mounting the same import's JS contribution supplies endpoint, parameter, result, lookup, Context, and Zod reflection and materializes the call without a handwritten stub.
			
 
				 - Root and Agent-scoped calls cross the real shared `/api` carrier, resolve `agentId` to the live Agent, invoke the original Goal receiver, and return through the existing RPC envelope.
			
 
				-- Agent and Session lookups share a single in-flight cold-session resume; ordinary cold sessions receive restored objects, while both cold and live subagent identities return `agent-busy` before business invocation.
			
 
				+- Agent and Session lookups share a single in-flight cold-session resume; ordinary cold sessions receive restored objects, while both cold and live subagent identities return `session/agent-busy` before business invocation.
			
 
				 - The Remote artifacts and maps contain only marked methods and no Browser dependency, preserving the same consumer boundary for a future TUI.
			
 
				 - Lifecycle tests withdraw and remount descriptors, Services, lookups, Context providers, and Client namespaces; unavailable dependencies fail without stale calls or raw-ID fallback.
			
 
				 - Cancellation tests cover strict generation, SRC final-name recognition, Client signal fusion, Connection-to-Gateway propagation, and Host injection outside wire `args`.
			
 
				-- Unclaimed endpoints continue through the existing API Proxy path with its trust, privileged-method, Permission/Approval, and Session event-stream behavior unchanged.
			
 
				+- A request that matches neither an exact Fetch route nor a claimed Remote endpoint answers 404 on the same channel, while a withdrawn route stops being served.
			
 
				 
			
 
				 ## Consequences
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
				 
			
 
				 ## Problem
			
 
				 
			
 
				-Host API Proxy 同时承担直接方法调用、带状态交互和 Session 事件流。三者的生命周期、路由语义和客户端编程界面不同，继续共用一个业务导出包会让业务 Service、传输协议、状态机和客户端类型彼此耦合。
			
 
				+Host API Proxy 当时在一个包里同时承担直接方法调用、带状态交互和 Session 事件流。三者的生命周期、路由语义和客户端编程界面不同，继续共用一个业务导出包会让业务 Service、传输协议、状态机和客户端类型彼此耦合。
			
 
				 
			
 
				 本决策只涵盖一次请求对应一次结果的定向方法调用。Permission、Approval 等带状态交互以及 Session 事件流仍采用独立设计。
			
 
				 
			
@@ -22,7 +22,7 @@ Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只
 
				 
			
 
				 `@deepseek-ai/dsh-api-gateway` 位于 `packages/api/gateway`，提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.remote`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在 Connection 共享的 `/api` RPC channel 上；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
			
 
				 
			
 
				-`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 Typert lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypertClientRemote` 约定，而不导入具体 Gateway 实现。
			
 
				+`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口注册本应用转发的 Cordis 事件源与随 generation readiness 携带的 Host 事实；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypertClientRemote` 约定，而不导入具体 Gateway 实现。
			
 
				 
			
 
				 ## 组件和 Cordis 服务
			
 
				 
			
@@ -32,7 +32,7 @@ Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只
 
				 | Typert registry | `ctx.typert` | 分开保存当前环境 reflection、导入的 Remote contribution、lookup provider 和 Context provider |
			
 
				 | Typert generator/loader | 无新增业务服务 | 从 Host/Client Program 生成三类 `lib` 产物，并把当前环境产物注册到 `ctx.typert` |
			
 
				 | API Gateway 的 Host face | `ctx.typertGateway` | 关联 Host definition 与活 Service，解码参数、解析 receiver、调用方法和编码结果 |
			
 
				-| Connection | `ctx.connection` | 独占 HTTP Server/未来 WebSocket、共享 `/api` route、RPC envelope、rpcId、序列化、trust、错误传输、Typert 拦截和旧 API Proxy 回退 |
			
 
				+| Connection | `ctx.connection` | 独占 HTTP Server/未来 WebSocket、共享 `/api` route、RPC envelope、rpcId、序列化、trust、错误传输、Typert 拦截，以及各 owner 在同一 channel 上注册的精确 Fetch route |
			
 
				 | API Gateway 的 Client face | `ctx.remote`、`ctx.remote.<namespace>` | mount Remote contribution，把每个 namespace 实体化为可追踪的 `remote.<namespace>` 子 Service，并把规范调用交给 `ctx.connection.rpc` |
			
 
				 | API Remotes | 无新增服务 | 负责 Host Agent/Session lookup 策略，并作为 Client 业务的唯一 facade，选择并挂载 `/remote` contribution，同时暴露所选 API 声明 |
			
 
				 | Agent/Session owning 包 | 既有领域服务 | 同时提供静态 interface merge 与运行时 lookup/Context provider |
			
@@ -162,9 +162,9 @@ ctx.typert.contexts  Host Context resolvers and Client Context binders
 
				 
			
 
				 每次注册都返回由调用方 Cordis fiber 持有的 disposer。挂载 Client contribution 时，descriptor 集与具体方法会作为一项有明确所有者的操作统一注册。Host Gateway 只缓存 SRC 所认领的 endpoint 名称集合，并在 Cordis Service 集合发生变化时整体丢弃该集合；它不保留 descriptor、Service 或提供方。调用时会从当前状态解析所有活对象，因此移除 strict definition、Service 或提供方会使相应调用不可用，且不会留下陈旧的活对象。
			
 
				 
			
 
				-lookup 注册表会在活 resolver 卸载后保留稳定的 wire 声明。SRC 解析仍会把该参数归类为 lookup，而调用会以 `lookup-unavailable` 失败；系统绝不会把传入的 ID 重新归类为普通 JSON 业务对象。在同一个 Typert Service 的生命周期内，以不同参数、wire 或规范类型 symbol 重新注册同一 key 会直接失败。
			
 
				+lookup 注册表会在活 resolver 卸载后保留稳定的 wire 声明。SRC 解析仍会把该参数归类为 lookup，而调用会以 `gateway/lookup-unavailable` 失败；系统绝不会把传入的 ID 重新归类为普通 JSON 业务对象。在同一个 Typert Service 的生命周期内，以不同参数、wire 或规范类型 symbol 重新注册同一 key 会直接失败。
			
 
				 
			
 
				-业务对象包和 scoped Context 包通过 `lookups.register()` 与 `contexts.registerHost()` 拥有稳定声明和默认 resolver；Host 组合通过 `lookups.configure()` 与 `contexts.configureHost()` 提供 effect-scoped 异步策略。配置可以先于 provider 注册，但没有活 provider 时不会单独形成可用身份；配置卸载后恢复 provider 默认 resolver。API Remotes 为 `agent`、`session` lookup 和 `agent` Host Context 创建共享的 `agentFor()` resolver：live Agent 直接复用，普通冷会话自动恢复，并发恢复按 Session ID 去重，subagent ownership fence 则返回既有 `agent-busy`。标准 Web API Proxy 提供 Agent 默认值和 scope 设置，并让旧方法使用该 resolver。`session` lookup 返回解析所得 Agent 的 Session，`agent` Host Context 返回其 Context，因此三种投影共用一个恢复生命周期。
			
 
				+业务对象包和 scoped Context 包通过 `lookups.register()` 与 `contexts.registerHost()` 拥有稳定声明和默认 resolver；Host 组合通过 `lookups.configure()` 与 `contexts.configureHost()` 提供 effect-scoped 异步策略。配置可以先于 provider 注册，但没有活 provider 时不会单独形成可用身份；配置卸载后恢复 provider 默认 resolver。Session Controller 的 `ApiSessionAgentController` 为 `agent`、`session` lookup 和 `agent` Host Context 配置同一个共享 resolver：live Agent 直接复用，普通冷会话自动恢复，并发恢复按 Session ID 去重，subagent ownership fence 则返回 `session/agent-busy`。`session` lookup 返回解析所得 Agent 的 Session，`agent` Host Context 返回其 Context，因此三种投影共用一个恢复生命周期。
			
 
				 
			
 
				 Registry 的 Host 根入口拥有完整 `TypertRegistryContract` interface merge；Host 与 Client 共用的 registry 实现位于无环境声明的独立模块。Registry `/client` 入口只引用该共享实现，不经过 Host 根入口，因此不会把 Host Cordis 声明带入 Client Program。
			
 
				 
			
@@ -254,7 +254,7 @@ interface TypertRemoteNamespace$676f616c73 {
 
				     agentId: SessionId,
			
 
				     request: CreateGoalRequest,
			
 
				     signal?: AbortSignal,
			
 
				-  ) => Promise<CreateGoalResult>
			
 
				+  ) => Promise<RemoteResult<CreateGoalResult>>
			
 
				 }
			
 
				 
			
 
				 interface TypertRemoteMap {
			
@@ -262,7 +262,7 @@ interface TypertRemoteMap {
 
				     agentId: SessionId,
			
 
				     request: CreateGoalRequest,
			
 
				     signal?: AbortSignal,
			
 
				-  ) => Promise<CreateGoalResult>
			
 
				+  ) => Promise<RemoteResult<CreateGoalResult>>
			
 
				 }
			
 
				 
			
 
				 interface TypertRemoteNamespaceMap {
			
@@ -273,7 +273,7 @@ interface TypertRemoteScopeMap {
 
				   'agent:goals/create': (
			
 
				     request: CreateGoalRequest,
			
 
				     signal?: AbortSignal,
			
 
				-  ) => Promise<CreateGoalResult>
			
 
				+  ) => Promise<RemoteResult<CreateGoalResult>>
			
 
				 }
			
 
				 ```
			
 
				 
			
@@ -288,7 +288,9 @@ agentCtx.remote.goals.create(request)
 
				 
			
 
				 Agent Scope 自动提供自己的 `SessionId`。因此带 `agent` lookup 的 `@Remote` 方法可以同时生成 root 和 scoped 两种消费端签名；`@RemoteScope('agent')` 方法也省略独立的 Scope identity，但只生成 scoped 签名。根 `Context` 通过 `ctx.remote` 暴露 direct namespace，`AgentContext.remote` 则把该 direct surface 与 scoped surface 取交集。未来 TUI 复用时必须维持相同区分。
			
 
				 
			
 
				-`TypertClientRemote` 保持平台无关，Browser Client 通过 `ctx.remote` 暴露它。未来 TUI 若复用该类型，也必须通过专用 Remote 对象和 Agent Scope 使用它，不能把 Host `Context` 当成更宽的 Service 集合；未标记的 public Service 方法不会进入 Remote maps。
			
 
				+每个生成方法都解析为 `Promise<RemoteResult<T>>`：调用把结果报告在 `ok` 分支里而不是 reject，只有装配故障（arity、未挂载的方法、缺失的 Context adapter）仍然抛出。消费方按 `result.ok` 分支，需要区分失败时读 `result.error.code`；失败词汇本身是[单一 Remote 失败类加一张合并码表](2026-08-28-ctx-remote-failure-vocabulary.zh.md)。
			
 
				+
			
 
				+`TypertClientRemote` 保持平台无关，Browser Client 通过 `ctx.remote` 暴露它。未来 TUI 若复用该类型，也必须通过专用 Remote 对象和 Agent Scope 使用它，不能把 Host `Context` 当成更宽的 Service 集合；未标记的 public Service 方法不会进入 Remote maps。除生成的 namespace 之外，Gateway client face 还提供 `$mount`、`$on`、`$stream` 与 `$host`——最后这项把连接的固定 Host 事实（`home`、`isLoopback`）作为普通值读取暴露，消费方无需为此注入载体。
			
 
				 
			
 
				 ## Client Typert 与 API Gateway Client face
			
 
				 
			
@@ -361,7 +363,7 @@ CI 和发布运行 LIB。全仓 coverage 全部切换到 LIB 是独立后续工
 
				 
			
 
				 ## Host Gateway 解析
			
 
				 
			
 
				-Host Gateway 向 Connection 注册一个 `/api` interceptor，不维护第二份 endpoint 注册表。ownership matcher 会先检查当前 Typert local 注册表，再查询一份可失效的集合；该集合通过扫描当前 Cordis Service 中的 `typertGateway` binding 与 SRC Remote 标记生成。Cordis Service 发生变化时会整体丢弃该集合，因此 Typert definition 与业务 Service 可以按任意顺序到达，同时既不会让旧 API Proxy 的 `/api` 流量在每次请求时重新扫描所有 Service，也不会因任意请求路径而扩大缓存。
			
 
				+Host Gateway 向 Connection 注册一个 `/api` interceptor，不维护第二份 endpoint 注册表。ownership matcher 会先检查当前 Typert local 注册表，再查询一份可失效的集合；该集合通过扫描当前 Cordis Service 中的 `typertGateway` binding 与 SRC Remote 标记生成。Cordis Service 发生变化时会整体丢弃该集合，因此 Typert definition 与业务 Service 可以按任意顺序到达，同时既不会在每次请求时重新扫描所有 Service，也不会因任意请求路径而扩大缓存。
			
 
				 
			
 
				 每次调用都会重新从当前状态解析 descriptor、receiver、lookup 提供方与 Context 提供方。当前 strict descriptor 优先于 SRC。strict endpoint 一旦出现，即使随后撤回对应 descriptor，`TypertLocalRegistry.hasSeen()` 仍会在注册表剩余生命周期内保持对它的认领并禁止回退 SRC；重新注册 strict descriptor 即可恢复调用。移除 Service 或提供方会让调用明确失败；Gateway 既不保留失效对象，也不会以原始 lookup ID 调用方法。
			
 
				 
			
@@ -399,9 +401,9 @@ ctx.connection.rpc.intercept(
 
				 )
			
 
				 ```
			
 
				 
			
 
				-Host registry 中存在 strict descriptor、记录过已撤回的 strict descriptor，或 active SRC Service binding 上存在匹配的 `@Remote` 标记时，Gateway 认领该 endpoint。endpoint 一旦被认领，即使 payload 解码、descriptor 解析或调用失败也继续由 Gateway 返回错误；只有不属于 Remote 的 endpoint 才进入旧 API Proxy 回退。
			
 
				+Host registry 中存在 strict descriptor、记录过已撤回的 strict descriptor，或 active SRC Service binding 上存在匹配的 `@Remote` 标记时，Gateway 认领该 endpoint。endpoint 一旦被认领，即使 payload 解码、descriptor 解析或调用失败也继续由 Gateway 返回错误；既不匹配精确 Fetch route、也不被 Gateway 认领的 endpoint 返回 404。
			
 
				 
			
 
				-Connection Host half 把一个复合 FetchHandler 交给 HTTP bridge。bridge 创建标准 `Request` 后，该 handler 再选择 Gateway RPC FetchHandler 或 API Proxy FetchHandler；两条路径复用同一 request/response envelope、rpcId、序列化、trust、transport error 和 `RpcError`。当前物理映射是：
			
 
				+Connection Host half 把一个复合 FetchHandler 交给 HTTP bridge。bridge 创建标准 `Request` 后，该 handler 先用 pathname 匹配各 owner 在该 channel 上注册的精确 Fetch route，再匹配该 channel 唯一的 interceptor——即 Gateway——两者都不认领时返回 404。该 channel 上的每条路径复用同一 request/response envelope、rpcId、序列化、trust 与错误传输，失败则携带共享的 `{ code, message, details }` 数据。当前物理映射是：
			
 
				 
			
 
				 ```text
			
 
				 POST /api/<namespace>/<method>
			
@@ -438,15 +440,15 @@ ctx.remote.goals.create(sessionId, request, signal?)
 
				 → Client result codec 验证并返回 CreateGoalResult
			
 
				 ```
			
 
				 
			
 
				-Remote 不定义第二层 `{ ok, value/error }` response。成功值和 Gateway 错误直接使用既有 RPC response 的 `result`。adapter 把普通 Gateway 与业务调用失败转换为既有 `RpcError` envelope，并统一使用 `code: 'internal'`；resolver 通过 `TypertLookupFailure` 携带的既有 RPC error 则原样返回，使冷恢复失败和 ownership fence 保持稳定错误码。Gateway 的结构化错误分类仅在进程内保留，诊断信息则通过 message 跨 Connection 传递。
			
 
				+Remote 不在 wire 上定义第二层 `{ ok, value/error }` response。成功值与失败都直接使用既有 RPC response 的 `result`，失败分支携带共享的 `{ code, message, details }` 数据。owner、resolver 与 Gateway 抛的都是同一个类 `RemoteError`，其码来自合并后的 `RemoteErrorDetailsMap`：Host 把结构识别出的 `RemoteError` 原样编码上 wire——包括 Gateway 自己的 `gateway/*` 装配码，以及 resolver 的 `session/not-found`、`session/agent-busy`——只把未归类的 throw 折成 `gateway/internal`，并把诊断串留在 message 里。Client face 为 `RemoteResult` 的错误分支重建实例，因此 `throw result.error` 的 throw 语义成立。[失败词汇 Agent Note](2026-08-28-ctx-remote-failure-vocabulary.zh.md) 持有码表、落点规则，以及为什么判别读 `code` 而不用 `instanceof`。
			
 
				 
			
 
				-Gateway 不处理逐方法权限、调用者身份、幂等或长连接状态。它只把 Connection 的协作式取消传播给显式支持取消的业务方法。Typert endpoint 使用 Connection 的 trusted-host 策略；未认领 endpoint 保留旧 API Proxy 的 trust 和 privileged-method 策略。Connection/WebSocket 迁移后续独立完成。
			
 
				+Gateway 不处理逐方法权限、调用者身份、幂等或长连接状态。它只把 Connection 的协作式取消传播给显式支持取消的业务方法。共享 channel 上的每个请求——无论是 Typert endpoint 还是精确 Fetch route——都先过 Connection 的浏览器认证与 trusted-host 策略再分发；Gateway 不叠加第二套策略。Connection/WebSocket 迁移后续独立完成。
			
 
				 
			
 
				 ## Connection 与协议边界
			
 
				 
			
 
				 Client Remote Service 负责 Remote contribution、namespace Service 实体化、Scope 绑定以及位置参数与 descriptor 的对应。Gateway 负责 Host descriptor、endpoint ownership、lookup、Context 和业务调用。Connection 把 `/api`、endpoint 和 `{ args }` 作为一个 RPC 调用发送到目标并返回既有 RPC result；它不理解 Goal、Agent、lookup、descriptor 或 Client Remote 类型。
			
 
				 
			
 
				-Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 HTTP route。Connection 把共享 `/api` route 挂到 HTTP Server，并把一个复合 FetchHandler 交给 bridge；该 handler 将已认领 endpoint 分发给 Gateway，未认领 endpoint 则交给 API Proxy。未来 Connection transport 可以保留相同顺序，而不改变 Remote payload、业务 decorator、生成的 DTS、Remote API 类型或 Agent Scope 编程界面。
			
 
				+Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 HTTP route。Connection 把共享 `/api` route 挂到 HTTP Server，并把一个复合 FetchHandler 交给 bridge；该 handler 把精确注册路径分发给它的 route owner、把已认领 endpoint 分发给 Gateway，其余一律 404。未来 Connection transport 可以保留相同顺序，而不改变 Remote payload、业务 decorator、生成的 DTS、Remote API 类型或 Agent Scope 编程界面。
			
 
				 
			
 
				 ## 包边界
			
 
				 
			
@@ -454,19 +456,19 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 
				 - Typert generator：分析 Host/Client Program，生成本地 face 和 Remote 消费端投影，并生成规范 symbol/Zod 信息。
			
 
				 - Typert runtime：分别保存当前环境的 local reflection 与导入的 Remote contribution。
			
 
				 - `@deepseek-ai/dsh-api-gateway`：默认入口关联 Host definition 与 Service，认领 Remote endpoint，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api` interceptor；`/client` 入口挂载 Remote contribution，创建严格 Remote namespace Service 和方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
			
 
				-- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypertClientRemote` 约定向业务包暴露合并后的 Remote 类型。
			
 
				-- Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、共享 `/api` route 与复合 FetchHandler、API Proxy 回退、RPC envelope、rpcId、序列化、trust 和错误传输。
			
 
				+- `@deepseek-ai/dsh-api-remotes`：BFF 层；注册本应用转发的 Cordis 事件源与随 generation readiness 携带的 Host home，选择 Client `/remote` contribution，并通过共享的 `TypertClientRemote` 约定向业务包暴露合并后的 Remote 类型。
			
 
				+- Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、共享 `/api` route 与其复合 FetchHandler、各 owner 注册的精确 Fetch route、RPC envelope、rpcId、序列化、trust 和错误传输。
			
 
				 - Agent/Session 等业务对象包：拥有 lookup、Context provider、唯一 ID 类型和纯类型公共出口。
			
 
				-- API Proxy Host 组合：向 API Remotes 提供 Web Agent 默认值和 scope 设置，并让旧方法使用同一个 `agentFor()`。
			
 
				+- `@deepseek-ai/dsh-api-session-controller`：配置共享的 `agent`/`session` lookup 与 `agent` Host Context resolver，因此每个接收这些对象的 Remote endpoint 共用同一套恢复与 ownership fence 策略。
			
 
				 - 业务 Service 包：声明 binding、Remote 方法及其 request/result 类型，并导出生成的 `/remote` 子路径。
			
 
				 
			
 
				 ## 已交付范围与后续工作
			
 
				 
			
 
				-已交付的纵向链路是 `@deepseek-ai/dsh-goal/remote → Browser Client Remote → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`。同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.remote.goals.create(agentId, request)` 与 `agentCtx.remote.goals.create(request)`。普通冷会话在 lookup 时通过 `agentFor()` 恢复，subagent-owned identity 保持既有 `agent-busy` fence；`@RemoteScope('agent')` 仍是独立的 scoped receiver 模式。
			
 
				+已交付的纵向链路是 `@deepseek-ai/dsh-goal/remote → Browser Client Remote → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`。同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.remote.goals.create(agentId, request)` 与 `agentCtx.remote.goals.create(request)`。普通冷会话在 lookup 时由该共享 resolver 恢复，subagent-owned identity 保持 `session/agent-busy` fence；`@RemoteScope('agent')` 仍是独立的 scoped receiver 模式。
			
 
				 
			
 
				 Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebSocket 迁移、TUI runtime 与 carrier、TUI Agent Scope 接线、Permission/Approval 状态机、Session 事件流、调用授权、重试、幂等及跨版本协议兼容均不属于本决策。
			
 
				 
			
 
				-包拓扑为 `api/remotes → api/gateway → client/connection → host/webserver`。Connection 与 WebServer 在本次变更中保留既有路径；后续将它们移到 `api/connection` 和 `api/webserver` 只会改变包位置，不会改变这些服务边界。旧 API Proxy 同样保留在 `host/apiproxy` 下，作为尚未迁移到 Remote 的方法的回退路径。
			
 
				+包拓扑为 `api/remotes → api/gateway → client/connection → host/webserver`。Connection 与 WebServer 在本次变更中保留既有路径；后续将它们移到 `api/connection` 和 `api/webserver` 只会改变包位置，不会改变这些服务边界。
			
 
				 
			
 
				 ## Alternatives considered
			
 
				 
			
@@ -486,7 +488,7 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
				 
			
 
				 **让 `/remote` 的顶层 import 偷偷注册全局状态。** ESM 求值时未必已有目标 Cordis Context，多个 Context、HMR 和 dispose 也无法明确归属，因此普通 value import 只返回 contribution，由环境 assembly 的 Client Remote Service 显式挂载。
			
 
				 
			
 
				-**为 Remote 新建独立 transport、HTTP route 或 `/api2` channel。** 这会复制或拆分 Connection 的 Server ownership、rpcId、序列化、trust、错误和未来 WebSocket 生命周期。共享 `/api` interceptor 保留唯一物理 route，并让 Connection 继续以 API Proxy 作为回退 FetchHandler。
			
 
				+**为 Remote 新建独立 transport、HTTP route 或 `/api2` channel。** 这会复制或拆分 Connection 的 Server ownership、rpcId、序列化、trust、错误和未来 WebSocket 生命周期。共享 `/api` interceptor 保留唯一物理 route，并让 Connection 用各 owner 注册的精确 Fetch route 与该 channel 唯一的 interceptor 组合出它。
			
 
				 
			
 
				 ## 验证
			
 
				 
			
@@ -496,11 +498,11 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
				 - 导入 `@deepseek-ai/dsh-goal/remote` 会加入严格的 `ctx.remote.goals.create(...)` 类型，并可通过 declaration 导航到 `remoteExportCreate`；不导入时不会出现该 namespace。
			
 
				 - 挂载同一次 import 得到的 JS contribution 会提供 endpoint、参数、结果、lookup、Context 和 Zod 反射，并在无需手写 stub 的情况下实体化调用。
			
 
				 - Root 与 Agent-scoped 调用会经过真实的共享 `/api` carrier，将 `agentId` 解析为活 Agent，调用原始 Goal receiver，并通过既有 RPC envelope 返回。
			
 
				-- Agent 与 Session lookup 会共享同一次并发冷恢复；普通冷会话得到恢复后的对象，冷态或 live subagent identity 均在业务调用前返回 `agent-busy`。
			
 
				+- Agent 与 Session lookup 会共享同一次并发冷恢复；普通冷会话得到恢复后的对象，冷态或 live subagent identity 均在业务调用前返回 `session/agent-busy`。
			
 
				 - Remote 产物与 map 仅包含已标记的方法，不依赖 Browser，从而为未来 TUI 保留相同的消费方边界。
			
 
				 - 生命周期测试会撤回并重新挂载 descriptor、Service、lookup、Context 提供方和 Client namespace；依赖不可用时，调用会失败，且不会使用陈旧调用或回退原始 ID。
			
 
				 - 取消测试覆盖严格生成、SRC 末位参数名识别、Client signal 合并、Connection 到 Gateway 的传播，以及 Host 在 wire `args` 之外的注入。
			
 
				-- 未认领 endpoint 继续使用既有 API Proxy 路径，其 trust、privileged-method、Permission/Approval 与 Session 事件流行为保持不变。
			
 
				+- 既不匹配精确 Fetch route、也不属于已认领 Remote endpoint 的请求在同一 channel 上返回 404，而已撤回的 route 随即停止服务。
			
 
				 
			
 
				 ## 后果
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-08-10-unary-apiproxy-remote-migration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-10-unary-apiproxy-remote-migration.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-10-unary-apiproxy-remote-migration.md
			
 
				-2026-08-10-unary-apiproxy-remote-migration.md: b98c7ee95b61ec00a5cab3106e812a6f17fc0a15
			
 
				-2026-08-10-unary-apiproxy-remote-migration.zh.md: 74bca8fd72f3e41075f5a44eba116fe127343bb2
			
 
				+2026-08-10-unary-apiproxy-remote-migration.md: ee93276b08e204b8c10c22c9fbb890a73691c5a9
			
 
				+2026-08-10-unary-apiproxy-remote-migration.zh.md: 63eb30a1c079c4f5beb3c6aa328ae31f9dbc51b2
			
--- a/.agents/notes/implemented/architecture/2026-08-10-unary-apiproxy-remote-migration.md
+++ b/.agents/notes/implemented/architecture/2026-08-10-unary-apiproxy-remote-migration.md
@@ -31,10 +31,10 @@ Simple unary operations live on their natural business Remote owner. The busines
 
				 | `skill.list` | `skills/list` | `SessionSkillCatalog` observes the Session and its recorded preset, uses a live Agent only when one already exists, and never activates an Agent for listing. |
			
 
				 | `fileReferences/list` | `fileReferences/list` | `SessionFileReferences` supplies the Session Controller's established Agent lookup to the provider; cold lookup behavior remains unchanged. |
			
 
				 | `host.openPath` | `session/openWorkspacePath` | The Session-aware Client resolves relative paths against the known workspace before `SessionController` hands them to the native opener. |
			
 
				-| `host.describe` | `$events` ready frame plus capability queries | API Remotes sends the Host home with generation readiness; Settings and Session controllers report their native-open capabilities when the corresponding page appears. Unused process metadata is not sent. |
			
 
				+| `host.describe` | `$events` ready frame plus capability queries | API Remotes sends the Host home with generation readiness, and consumers read it as a plain value through `ctx.remote.$host.home` beside `$host.isLoopback`; Settings and Session controllers report their native-open capabilities when the corresponding page appears. Unused process metadata is not sent. |
			
 
				 | `session.export` | `GET`/`HEAD /api/session.export` | `session-log-export` registers an exact Connection Fetch route and streams the ZIP without a JSON Remote envelope. |
			
 
				 
			
 
				-The shared Agent and Session resolver remains the authority for endpoints that accept those objects. It provides the same live reuse, cold restoration, concurrent deduplication, preset setup, persistence failures, and subagent ownership fence that legacy API Proxy calls used. `TypertLookupFailure` preserves resolver-owned RPC errors instead of collapsing them into `internal`.
			
 
				+The shared Agent and Session resolver remains the authority for endpoints that accept those objects. It provides the same live reuse, cold restoration, concurrent deduplication, preset setup, persistence failures, and subagent ownership fence that legacy API Proxy calls used. The resolver raises a `RemoteError` carrying its own code — `session/not-found` or `session/agent-busy` — and the Gateway encodes that code, message, and details onto the wire unchanged, so a lookup refusal stays distinguishable from `gateway/internal` ([failure vocabulary](2026-08-28-ctx-remote-failure-vocabulary.md)).
			
 
				 
			
 
				 The native path implementation lives in `@deepseek-ai/dsh-native-command`. Settings controllers select Host-owned targets, while Session-aware Clients resolve workspace paths before calling `SessionController`; the utility only performs platform detection, WSL translation, browser preference, text-editor intent, and shell-free command execution.
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-08-10-unary-apiproxy-remote-migration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-10-unary-apiproxy-remote-migration.zh.md
@@ -31,10 +31,10 @@ Host API Proxy 曾在业务 Service、API Proxy interface、Zod schema、路由
 
				 | `skill.list` | `skills/list` | `SessionSkillCatalog` 观察 Session 及其记录的 preset，仅在 live Agent 已存在时使用它，列表查询绝不激活 Agent。 |
			
 
				 | `fileReferences/list` | `fileReferences/list` | `SessionFileReferences` 向 provider 提供 Session Controller 的既有 Agent lookup；冷 lookup 行为保持不变。 |
			
 
				 | `host.openPath` | `session/openWorkspacePath` | Session-aware Client 先基于已知 workspace 解析相对路径，再由 `SessionController` 交给原生打开器。 |
			
 
				-| `host.describe` | `$events` ready frame 与 capability 查询 | API Remotes 随 generation readiness 发送 Host home；Settings 与 Session controller 在对应页面显示时报告各自的原生打开能力。不发送无人使用的进程元数据。 |
			
 
				+| `host.describe` | `$events` ready frame 与 capability 查询 | API Remotes 随 generation readiness 发送 Host home，消费方通过 `ctx.remote.$host.home` 与并列的 `$host.isLoopback` 以普通值读取；Settings 与 Session controller 在对应页面显示时报告各自的原生打开能力。不发送无人使用的进程元数据。 |
			
 
				 | `session.export` | `GET`/`HEAD /api/session.export` | `session-log-export` 注册精确的 Connection Fetch 路由，并在没有 JSON Remote envelope 的情况下流式传输 ZIP。 |
			
 
				 
			
 
				-共享 Agent 与 Session resolver 仍是接收这些对象的 endpoint 的权威。它提供与旧 API Proxy 调用相同的 live 复用、冷恢复、并发去重、preset setup、持久化失败与 subagent ownership fence。`TypertLookupFailure` 保留 resolver 持有的 RPC error，而不把它们归并为 `internal`。
			
 
				+共享 Agent 与 Session resolver 仍是接收这些对象的 endpoint 的权威。它提供与旧 API Proxy 调用相同的 live 复用、冷恢复、并发去重、preset setup、持久化失败与 subagent ownership fence。resolver 抛出携带自有码的 `RemoteError`——`session/not-found` 或 `session/agent-busy`——Gateway 把该码、message 与 details 原样编码上 wire，因此 lookup 拒绝与 `gateway/internal` 始终可区分（[失败词汇](2026-08-28-ctx-remote-failure-vocabulary.zh.md)）。
			
 
				 
			
 
				 原生路径实现在 `@deepseek-ai/dsh-native-command` 中。Settings controller 选择 Host 持有的目标，Session-aware Client 则在调用 `SessionController` 前解析 workspace 路径；该工具仅负责平台探测、WSL 转换、浏览器偏好、文本编辑器意图与无 shell 命令执行。
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.md
			
 
				-2026-08-15-client-shells-and-dynamic-packages.md: 016314d10f55e0b590e98944ca417bae658ab56a
			
 
				-2026-08-15-client-shells-and-dynamic-packages.zh.md: 4e0277d1becab8467521dc21d0e5b7509d1ee993
			
 
				+2026-08-15-client-shells-and-dynamic-packages.md: 1d67c778b6a06849324dd6095a98d57dc41b94f9
			
 
				+2026-08-15-client-shells-and-dynamic-packages.zh.md: db1e4e7e7b319c283ae39a94535d88d4dc71d60a
			
--- a/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.md
+++ b/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.md
@@ -57,11 +57,11 @@ After the `immediately` tier has registered its factories, the kernel creates al
 
				 
			
 
				 ### Dependency declarations
			
 
				 
			
 
				-Every client package keeps Cordis in matching `peerDependencies` and `devDependencies`. A dynamic package that imports, re-exports, augments, or names an internal dynamic package in `dsh.client.inject` keeps that package as matching peer and development dependencies. Static client inputs and React modules are development-only inputs for a dynamic package because the shell supplies their runtime identities.
			
 
				+Every Client package keeps Cordis in matching `peerDependencies` and `devDependencies`; Cordis is its only peer. Browser imports, type references, module augmentations, and `dsh.client.inject` are development inputs because the Client build and shipped profile supply their runtime identities. A package that also publishes a Host entry keeps that entry's runtime value imports in `dependencies`. [Published dependency faces](../process/2026-08-26-published-dependency-faces.md) owns package discovery, exceptions, and the explicit Host roster.
			
 
				 
			
 
				 Ordinary installed libraries remain `dependencies`: a dynamic build may bundle a private implementation, while a `staticLinked` library retains its bare import for the final host. Each build face decides externality independently from npm sections. Published file lists cover every runtime entry, relative asset, and declaration file reached by the artifact.
			
 
				 
			
 
				-`verify-client-packages` enforces these classifications, dependency sections, build forms, parser-preload alignment, shared-module requests, and module-graph acyclicity. The repository publint pass enforces publication closure. The verifier's `--fix` mode repairs only unambiguous manifest drift.
			
 
				+`verify-package-dependencies` enforces and repairs dependency sections. `verify-client-packages` enforces build forms, parser-preload alignment, shared-module requests, and module-graph acyclicity. The repository publint pass enforces publication closure.
			
 
				 
			
 
				 ## Alternatives considered
			
 
				 
			
@@ -77,7 +77,7 @@ Ordinary installed libraries remain `dependencies`: a dynamic build may bundle a
 
				 
			
 
				 ## Consequences
			
 
				 
			
 
				-Bundle contents stay stable when an npm dependency moves between peer and development sections, because each build face declares externality directly. Static libraries remain host-assembled, while dynamic packages retain uniform artifacts and lifecycle governance.
			
 
				+Bundle contents stay stable when an internal DSH relationship is development-only, because each build face declares externality directly. Static libraries remain host-assembled, while dynamic packages retain uniform artifacts and lifecycle governance. The shipped profile owns the complete Client package roster, so individual Client packages do not ask npm to solve the same graph again through peer placement.
			
 
				 
			
 
				 The startup protocol depends on the modules package id, and modules must remain self-contained at runtime. Combo generation preserves its ordinary package artifact and gives every other row one shared initial transport; HMR uses the same route with that row as its sole resource. A missing bootstrap registration fails before Cordis starts; later plugin import, apply, and service-wait failures remain visible through the boot page's ACTIVE scan.
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.zh.md
@@ -57,11 +57,11 @@ Bootstrap combo 当前只登记 modules factory。启动内核把原始图与外
 
				 
			
 
				 ### 依赖声明
			
 
				 
			
 
				-每个 client 包都把 Cordis 保持为 matching `peerDependencies` 和 `devDependencies`。动态包若 import、re-export、augment 内部动态包，或在 `dsh.client.inject` 中命名它，就把该包保持为 matching peer 与开发依赖。静态 client 输入和 React 模块对动态包只是开发依赖，因为外壳提供其运行期身份。
			
 
				+每个 Client 包都把 Cordis 保持为范围一致的 `peerDependencies` 和 `devDependencies`；Cordis 是唯一的 peer。Browser import、类型引用、模块扩充与 `dsh.client.inject` 都是开发输入，因为 Client 构建与发布 profile 会提供其运行期身份。同时发布 Host 入口的包把该入口的运行期 value import 放在 `dependencies`。[发布依赖门面](../process/2026-08-26-published-dependency-faces.zh.md)负责包发现、例外与显式 Host 名册。
			
 
				 
			
 
				 普通安装库仍放在 `dependencies`：动态构建可以内联私有实现，而 `staticLinked` 库会保留 bare import 交给最终宿主。各构建 face 独立决定 external，不由 npm 区段推导。发布文件列表覆盖产物实际可达的每个运行期入口、相对资产和声明文件。
			
 
				 
			
 
				-`verify-client-packages` 会检查这些分类、依赖区段、构建形态、parser preload 对齐、共享模块请求和模块图无环性。仓库 publint pass 负责检查发布闭包。该验证器的 `--fix` 模式只修复无歧义的 manifest 漂移。
			
 
				+`verify-package-dependencies` 检查并修复依赖区段。`verify-client-packages` 检查构建形态、parser preload 对齐、共享模块请求和模块图无环性。仓库 publint pass 负责检查发布闭包。
			
 
				 
			
 
				 ## Alternatives considered
			
 
				 
			
@@ -77,7 +77,7 @@ Bootstrap combo 当前只登记 modules factory。启动内核把原始图与外
 
				 
			
 
				 ## Consequences
			
 
				 
			
 
				-Npm 依赖在 peer 与开发区段间移动时，bundle 内容保持稳定，因为每个构建 face 都直接声明 external。静态库继续由宿主装配，动态包则保留统一产物与生命周期治理。
			
 
				+内部 DSH 关系仅放在开发区段时，bundle 内容仍保持稳定，因为每个构建 face 都直接声明 external。静态库继续由宿主装配，动态包则保留统一产物与生命周期治理。发布 profile 拥有完整 Client 包名册，因此各 Client 包不再要求 npm 通过 peer placement 重复求解同一张图。
			
 
				 
			
 
				 启动协议依赖 modules 的 package id，modules 还必须保持运行期自包含。Combo 生成保留其普通 package 产物，并为其他全部 row 提供一条共享初始传输；HMR 使用同一条路由，并只把该 row 作为资源。缺少 bootstrap registration 会在 Cordis 启动前失败；后续插件 import、apply 与 service 等待失败仍由启动页的 ACTIVE 扫描呈现。
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md
			
 
				-2026-08-18-session-history-and-event-transport.md: 8f26b2977dceeb2085bf270ae603cd21d48157f5
			
 
				-2026-08-18-session-history-and-event-transport.zh.md: 10edeff16695cac265f2026b300eb206838a53e4
			
 
				+2026-08-18-session-history-and-event-transport.md: d35ed79dedd5592d15a27b0e1b952e66d80b268f
			
 
				+2026-08-18-session-history-and-event-transport.zh.md: 6e6ccf53e28c9a7ce76bb4aa5d80d94f39e11f10
			
--- a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md
+++ b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.md
@@ -60,11 +60,13 @@ API Proxy owns neither the Session or Workspace Remote namespace nor the Host do
 
				 
			
 
				 ### Connection generation and physical connections
			
 
				 
			
 
				-The browser's Client Remote plugin starts `RemoteStreamMuxClient` idempotently on activation and connects to `/api/remote.mux` immediately. The physical WebSocket remains resident even when there is no business logical stream.
			
 
				+The browser's Client Remote plugin starts `RemoteStreamMuxClient` idempotently on activation and connects to `/api/remote.mux` immediately. The physical WebSocket remains resident even when there is no business logical stream, but the mux performs no independent retry scheduling.
			
 
				 
			
 
				-The Host sends one RFC 6455 Ping control frame to every open mux socket at the configured `websocketHeartbeatIntervalMs` interval (30 seconds by default). The browser replies with Pong at the protocol layer; neither control frame enters the Remote stream JSON union or changes Connection generation state. The Host imposes no Pong deadline, so half-open detection remains with TCP and network intermediaries.
			
 
				+The Host sends one RFC 6455 Ping control frame to every open mux socket at the configured `websocketHeartbeatIntervalMs` interval (two seconds by default). The browser replies with Pong at the protocol layer; neither control frame enters the Remote stream JSON union or changes Connection generation state. Before each Ping, the Host marks the socket as awaiting Pong and terminates it at the next interval if no Pong arrived.
			
 
				 
			
 
				-After an initial connection failure or the loss of a connected socket, the mux rebuilds the physical connection with capped jittered backoff. Logical streams not yet opened share that reconnect loop; streams already open end their current physical generation with `RemoteStreamCarrierError`.
			
 
				+After an initial connection failure or the loss of a connected socket, open logical streams end their current physical generation with `RemoteStreamCarrierError`. `ConnectionController` owns the bounded exponential retry schedule; each attempt asks the mux to replace any candidate or active socket exactly once before reopening `$events`. A user-requested reconnect resets the attempt sequence and bypasses the delay through the same path ([decision](../feature/2026-08-28-web-connection-recovery-control.md)).
			
 
				+
			
 
				+The browser's network-status events are inputs to the same Controller. `offline` withdraws the Connection generation and suspends automatic retries; the next `online` transition restarts the base backoff. These events never establish connectivity: only a fresh `$events` ready frame publishes a Connection generation.
			
 
				 
			
 
				 In-process `connection.rpc.open` uses the same logical endpoint semantics while bypassing the browser WebSocket mux.
			
 
				 
			
@@ -74,11 +76,11 @@ The Host event source installs incremental listeners synchronously before return
 
				 
			
 
				 `ConnectionController` publishes `connected` only after `$events` readiness, so a Session or Workspace baseline cannot be read before Host incremental listeners are ready.
			
 
				 
			
 
				-Unexpected normal completion of `$events`, a Host error, a malformed opening frame, or a carrier failure ends the current Connection generation. Connection withdraws the generation, then re-establishes `$events` after backoff.
			
 
				+Unexpected normal completion of `$events`, a Host error, a malformed opening frame, or a carrier failure ends the current Connection generation. Connection withdraws the generation, then re-establishes `$events` under its bounded backoff unless the browser is offline or a user requests an immediate retry.
			
 
				 
			
 
				 Gateway stream generation, Connection generation, and a Session business open epoch are three independent counters: the first identifies physical replacement of one logical stream, the second identifies a Host-availability handshake, and the last prevents an obsolete Session open from writing into current state.
			
 
				 
			
 
				-Host plugin disposal stops the heartbeat timer, terminates mux sockets, and waits for active iterators. Client plugin disposal stops backoff, cancels candidate and active sockets, ends logical streams, and awaits quiescence of background loops and consumers.
			
 
				+Host plugin disposal stops the heartbeat timer, terminates mux sockets, and waits for active iterators. Client plugin disposal stops retry delays, cancels candidate and active sockets, ends logical streams, and awaits quiescence of background loops and consumers.
			
 
				 
			
 
				 ### General Remote stream model
			
 
				 
			
@@ -330,7 +332,7 @@ API Proxy carries only independent business APIs it owns. Session, Workspace, Re
 
				 
			
 
				 ## Verification
			
 
				 
			
 
				-Gateway mux tests pin connection without logical streams, idle residency, configurable Ping/Pong without application messages, initial-failure and disconnect recovery, active-stream carrier failure, cancellation, and no reconnect after disposal.
			
 
				+Gateway mux tests pin connection without logical streams, idle residency, one physical attempt per request, configurable Ping/Pong without application messages, active-stream carrier failure, cancellation, and no reconnect after disposal.
			
 
				 
			
 
				 Connection tests pin missing, duplicate, and withdrawn generation sources, readiness timeout, and generation withdrawal and rebuilding after failure.
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-18-session-history-and-event-transport.zh.md
@@ -60,11 +60,13 @@ API Proxy 不拥有 Session 或 Workspace Remote namespace，也不拥有 Host
 
				 
			
 
				 ### Connection generation 与物理连接
			
 
				 
			
 
				-浏览器的 Client Remote 插件激活时幂等启动 `RemoteStreamMuxClient`，并立即连接 `/api/remote.mux`。没有业务 logical stream 时物理 WebSocket 仍保持常驻。
			
 
				+浏览器的 Client Remote 插件激活时幂等启动 `RemoteStreamMuxClient`，并立即连接 `/api/remote.mux`。没有业务 logical stream 时物理 WebSocket 仍保持常驻，但 mux 不运行独立的 retry 调度。
			
 
				 
			
 
				-Host 按配置的 `websocketHeartbeatIntervalMs` 间隔（默认 30 秒）向每条已打开的 mux socket 发送一个 RFC 6455 Ping 控制帧；浏览器在协议层回复 Pong。两种控制帧都不进入 Remote stream JSON union，也不改变 Connection generation 状态。Host 不设置 Pong deadline，因此半开检测仍由 TCP 与网络中间层承担。
			
 
				+Host 按配置的 `websocketHeartbeatIntervalMs` 间隔（默认 2 秒）向每条已打开的 mux socket 发送一个 RFC 6455 Ping 控制帧；浏览器在协议层回复 Pong。两种控制帧都不进入 Remote stream JSON union，也不改变 Connection generation 状态。每次 Ping 前，Host 把 socket 标记为等待 Pong；若到下一间隔仍未收到 Pong，Host 会终止该 socket。
			
 
				 
			
 
				-首次建连失败或已连接 socket 丢失后，mux 使用有上限的抖动退避重建物理连接。尚未打开的 logical stream 共享该重连循环；已经打开的 stream 以 `RemoteStreamCarrierError` 结束当前物理 generation。
			
 
				+首次建连失败或已连接 socket 丢失后，已打开的 logical stream 会以 `RemoteStreamCarrierError` 结束当前物理 generation。`ConnectionController` 拥有有界的指数 retry 调度；每次尝试都要求 mux 恰好一次替换候选或活动 socket，再重开 `$events`。用户要求的重连通过同一路径重置 attempt 序列并跳过等待（见[决策](../feature/2026-08-28-web-connection-recovery-control.zh.md)）。
			
 
				+
			
 
				+浏览器网络状态事件是同一 Controller 的输入。`offline` 会撤回 Connection generation 并暂停自动 retry；下一次 `online` 转换会从基础退避档重新开始。这些事件不会建立连接；只有新的 `$events` ready 帧才会发布 Connection generation。
			
 
				 
			
 
				 进程内 `connection.rpc.open` 使用同一 logical endpoint 语义，但绕过浏览器 WebSocket mux。
			
 
				 
			
@@ -74,11 +76,11 @@ Host event source 在返回首帧前同步安装增量 listener。Gateway 随后
 
				 
			
 
				 `ConnectionController` 只有在 `$events` ready 后才发布 `connected`，所以 Session 或 Workspace baseline 不会在 Host 增量 listener 就绪前开始读取。
			
 
				 
			
 
				-`$events` 正常意外结束、Host 错误、畸形首帧或 carrier 失败都会结束当前 Connection generation。Connection 撤回该 generation，退避后重新建立 `$events`。
			
 
				+`$events` 正常意外结束、Host 错误、畸形首帧或 carrier 失败都会结束当前 Connection generation。Connection 撤回该 generation，随后按有界退避重新建立 `$events`；浏览器离线时暂停，用户要求立即重试时则跳过等待。
			
 
				 
			
 
				 Gateway stream、Connection generation 与 Session 业务 open epoch 是三个独立计数：前者表示某条 logical stream 的物理替换，第二个表示 Host 可用性握手，最后一个防止已淘汰的 Session open 写回当前状态。
			
 
				 
			
 
				-Host 插件销毁会停止心跳定时器、终止 mux socket，并等待活跃 iterator 完成。Client 插件销毁会停止退避，取消候选与活动 socket，终止 logical stream，并等待后台循环和 consumer 完全停稳。
			
 
				+Host 插件销毁会停止心跳定时器、终止 mux socket，并等待活跃 iterator 完成。Client 插件销毁会停止重试等待，取消候选与活动 socket，终止 logical stream，并等待后台循环和 consumer 完全停稳。
			
 
				 
			
 
				 ### 通用 Remote stream 模型
			
 
				 
			
@@ -330,7 +332,7 @@ API Proxy 只承接自身拥有的独立业务 API，不是 Session、Workspace
 
				 
			
 
				 ## 验证
			
 
				 
			
 
				-Gateway mux 测试固定无 logical stream 时建连、空闲常驻、可配置且不产生应用消息的 Ping/Pong、初始失败与断线重连、活动 stream carrier failure、取消和 dispose 后不再重连。
			
 
				+Gateway mux 测试固定无 logical stream 时建连、空闲常驻、每次请求只做一次物理尝试、可配置且不产生应用消息的 Ping/Pong、活动 stream carrier failure、取消和 dispose 后不再重连。
			
 
				 
			
 
				 Connection 测试固定 generation source 缺失、重复注册、撤回、ready 超时，以及 generation 失败后的撤回和重建。
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md
			
 
				-2026-08-23-locale-owned-client-ui-copy.md: 7fa2d60f14253a74b2bd3df4398471905a32509b
			
 
				-2026-08-23-locale-owned-client-ui-copy.zh.md: 5515699bb1702d41726c57435b19a2256ee0b896
			
 
				+2026-08-23-locale-owned-client-ui-copy.md: 5f645a34c386ba340c5a8d52e8bdef2258dd77bd
			
 
				+2026-08-23-locale-owned-client-ui-copy.zh.md: 996ef56b17637a4ca60b8793075e9975faf0e1e1
			
--- a/.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md
+++ b/.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md
@@ -12,7 +12,7 @@ Typed locale namespaces and bilingual dictionary parity proved that registered d
 
				 
			
 
				 **Locale dictionaries own all product-authored client UI wording.** Visible text, accessibility names, tooltips, placeholders, empty states, status labels, units, and formatting templates reach presentation through a typed `t` seat or an already-localized prop. A value authored by a user, model, provider, plugin, wire peer, or operating system remains data and renders verbatim; protocol tags, tool names, paths, URLs, JSON/JavaScript literals, and stable internal ids are not translated.
			
 
				 
			
 
				-**Cordis-free primitives require complete localized copy props and own no language fallback.** `MarkdownText`, `JsonTree`, `TerminalBlock`, `DiffBlock`, `ReadBlock`, `SearchBlock`, `WebBlock`, `CodeBlock`, `JsonBlock`, `HoverCard`, and `ConnectionBanner` receive their chrome from the feature render site. This preserves the primitive package's runtime independence while making omission a type error instead of silently selecting Chinese or English. Shared words live in the `common` namespace; feature-specific phrases stay with the feature that decides their meaning.
			
 
				+**Cordis-free primitives require complete localized copy props and own no language fallback.** `MarkdownText`, `JsonTree`, `TerminalBlock`, `DiffBlock`, `ReadBlock`, `SearchBlock`, `WebBlock`, `CodeBlock`, `JsonBlock`, `HoverCard`, and `ConnectionIndicator` receive their chrome from the feature render site. This preserves the primitive package's runtime independence while making omission a type error instead of silently selecting Chinese or English. Shared words live in the `common` namespace; feature-specific phrases stay with the feature that decides their meaning.
			
 
				 
			
 
				 **Localized display text is never an identity.** Models and stores retain discriminants, stable ids, and non-display markers. Renderers translate after matching, and request maps carry stable group membership into the trajectory ledger. A client-synthesized error that must survive in a view model uses a stable marker and is translated only when displayed. Language switching therefore changes wording without changing selection, grouping, search identity, or lifecycle state.
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.zh.md
@@ -12,7 +12,7 @@ typed locale namespace 与双语字典对等性可以证明已注册字典完整
 
				 
			
 
				 **所有产品编写的 client UI 措辞都由 locale 字典持有。** 可见文本、无障碍名称、tooltip、placeholder、空状态、状态标签、单位和格式模板必须经 typed `t` 席位或已本地化 prop 到达展示层。由用户、模型、提供方、插件、wire 对端或操作系统编写的值仍是数据并原样渲染；协议 tag、工具名称、路径、URL、JSON/JavaScript 字面量和稳定内部 id 不翻译。
			
 
				 
			
 
				-**Cordis-free 原子组件要求完整的本地化文案 prop，且自身不持有语言回落值。** `MarkdownText`、`JsonTree`、`TerminalBlock`、`DiffBlock`、`ReadBlock`、`SearchBlock`、`WebBlock`、`CodeBlock`、`JsonBlock`、`HoverCard` 与 `ConnectionBanner` 的 chrome 均由功能渲染点传入。这样既保留原子组件包的运行时独立性，也让遗漏成为类型错误，而不是静默选择中文或英文。共享用词进入 `common` namespace；功能专属短语留在决定其语义的功能侧。
			
 
				+**Cordis-free 原子组件要求完整的本地化文案 prop，且自身不持有语言回落值。** `MarkdownText`、`JsonTree`、`TerminalBlock`、`DiffBlock`、`ReadBlock`、`SearchBlock`、`WebBlock`、`CodeBlock`、`JsonBlock`、`HoverCard` 与 `ConnectionIndicator` 的 chrome 均由功能渲染点传入。这样既保留原子组件包的运行时独立性，也让遗漏成为类型错误，而不是静默选择中文或英文。共享用词进入 `common` namespace；功能专属短语留在决定其语义的功能侧。
			
 
				 
			
 
				 **本地化展示文本绝不承担身份。** 模型与存储保留判别字段、稳定 id 和非展示 marker。渲染器先匹配再翻译，请求映射通过稳定的组成员关系进入 trajectory ledger。必须保存在视图模型中的 client 合成错误使用稳定 marker，只在展示时翻译。因此语言切换只改变措辞，不改变选择、分组、搜索身份或生命周期状态。
			
 
				 
			
--- a/.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.i18n.yaml
@@ -0,0 +1,6 @@
 
				+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				+# side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				+# after editing either side, bring the other along and re-record with:
			
 
				+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.md
			
 
				+2026-08-28-ctx-remote-failure-vocabulary.md: fe8cafb6116d73797e1dae07fb28fe52d42c9285
			
 
				+2026-08-28-ctx-remote-failure-vocabulary.zh.md: 6b75aae454fb9e4d7c4622525220d1949c45404d
			
--- a/.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.md
+++ b/.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.md
@@ -0,0 +1,88 @@
 
				+# Agent Note: One Remote failure vocabulary for ctx.remote
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+English | [中文](2026-08-28-ctx-remote-failure-vocabulary.zh.md)
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+Every Remote owner package maintained its own failure surface: an `XxxErrorDetailsMap` interface, an `XxxError` union derived from it, and an exit mapping function that translated domain error classes (`UnknownPresetError`, `PresetMountError`, `SessionTitleInvalidError`, and their peers) into a wire failure value. `@deepseek-ai/dsh-typert-protocol` carried two failure classes at once — `TypertRemoteFailure` for a failure an owner reported and `TypertLookupFailure` for one a lookup resolver produced — while `@deepseek-ai/dsh-client-connection` kept a second typed view, `RpcErrorDetailsMap`, that hardcoded domain codes such as `agent-preset-not-found` and `session-not-found` into the carrier.
			
 
				+
			
 
				+One code therefore existed in three places: the owner's table, the carrier's typed view, and whatever union or cast a consumer wrote to narrow it (`result.error as SessionError`). Adding a domain code meant editing all three, and relaying another domain's code meant copying that code into your own table — `SessionErrorDetailsMap` had absorbed five foreign codes this way, across `agent-preset-*`, `subagent-*`, and `workspace-not-found`.
			
 
				+
			
 
				+Failure information was flattened in two places as well. All 17 of the Gateway's own assembly failures (an unmounted method, an ambiguous endpoint, a lookup provider mismatch, a result that fails its codec) reached the wire as `code: 'internal'`, so a client could not separate an assembly fault from a business refusal; owners defensively pre-folded unrelated exceptions into their own domain codes, so a genuine Host bug arrived at the caller as a plausible-looking domain failure.
			
 
				+
			
 
				+Fixed Host facts bypassed `ctx.remote` too: the Host home came from `(ctx.get('connection') as ConnectionHandle).generation.getSnapshot()?.host.home`, so every page that needed one fixed fact injected the carrier and understood its generation store.
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+`@deepseek-ai/dsh-typert-protocol` exports one failure class, `RemoteError<Code>`: a real `Error` carrying readonly `code` and `details`, the structural marker `isDSHRemoteError`, and standard `ErrorOptions` (`cause` holds in-process only). The correspondence between codes and details lives in one merge-extensible `RemoteErrorDetailsMap`; `RemoteFailure` is the code-distributed union of instances, and `RemoteResult<T>` keeps its shape.
			
 
				+
			
 
				+```text
			
 
				+export class RemoteError<Code extends RemoteErrorCode = RemoteErrorCode> extends Error {
			
 
				+  readonly isDSHRemoteError: true = true
			
 
				+  constructor(readonly code: Code, message: string,
			
 
				+    readonly details: RemoteErrorDetailsMap[Code], options?: ErrorOptions)
			
 
				+}
			
 
				+export type RemoteFailure = { [C in RemoteErrorCode]: RemoteError<C> }[RemoteErrorCode]
			
 
				+export type RemoteResult<T> = { ok: true; value: T } | { ok: false; error: RemoteFailure }
			
 
				+```
			
 
				+
			
 
				+A failure point throws directly: `throw new RemoteError(code, message, details)`. A domain builds no error-class family and writes no exit mapping function; only the "classify any provider exception" case keeps one `catch`, and inside it `throw new RemoteError(code, messageOf(error), details, { cause: error })`. An existing exception class that an in-process flow still consumes (`ApiSessionCwdConflict` and its peers) stays as a non-exported private class and converts to a `RemoteError` in one line at the exit.
			
 
				+
			
 
				+A code is a `<domain>/<reason>` string: `session/not-found`, `gateway/cancelled`, `workspace/invalid-path`, `agent-preset/locked`. The prefix follows the wire-namespace style, so the code itself says who owns it, and relaying another domain's code no longer needs an awkward unprefixed name.
			
 
				+
			
 
				+## Code ownership
			
 
				+
			
 
				+A code has exactly one declaration site, and the site follows from both who produces it and who can see the declaration — declaration merging only applies where the augmenting file enters the current program, so the home must be a package every producer already sees:
			
 
				+
			
 
				+- **Carrier codes**: `gateway/bad-request`, `gateway/cancelled`, and `gateway/internal` are declared by the protocol and reachable everywhere.
			
 
				+- **Gateway assembly codes**: the 17 `gateway/*` codes are declared in `packages/api/gateway/src/remote-error-codes.ts` with the uniform `TypertGatewayFaultDetails { endpoint, field? }` details; that module is face-neutral and each face imports it, so both programs see the same entries.
			
 
				+- **Produced by several packages**: when two or more packages throw the same code, the declaration lands in the lowest layer both already depend on. `session/not-found` lands in `@deepseek-ai/dsh-session` (session-controller and workspace-controller both depend on it), and `workspace/not-found` lands in `@deepseek-ai/dsh-workspace` (no dependency edge exists between the two API packages, so the capability package is their only shared layer).
			
 
				+- **Single producer**: a code only one package throws lands in that producer. `subagent/not-found` and `agent-preset/conflict` therefore live in session-controller — it is their only thrower in the repository, and neither the subagent nor the agent-presets table declares them.
			
 
				+
			
 
				+What two domains share is validation logic, not a code. `session/invalid-time-zone` and `subagent/invalid-time-zone` are two codes each declared and thrown by its own domain, and both endpoints canonicalize through `canonicalClientTimeZone()` from `@deepseek-ai/dsh-util-time`; no client branches on this code, so splitting it costs nothing while merging it would recreate the reachability problem.
			
 
				+
			
 
				+## Discrimination by code
			
 
				+
			
 
				+Discrimination always reads `code` and never uses `instanceof`. Client and Host are separately bundled programs, and a worker transport bundles the page half once more, so several copies of the same class exist and prototype identity across copies does not hold. The mechanism layer reads the structural marker plus a string `code` through the protocol's `remoteErrorOf(value)`, and the Gateway client face additionally exports `isRemoteFailure(error)` for a consumer's catch site; both read those fields, never the class — the test does not even require `instanceof Error`, because an Error thrown in another realm fails that too.
			
 
				+
			
 
				+Business code usually needs neither function: the `ok: false` branch of `RemoteResult` is already a typed `RemoteFailure`, so `if (result.error.code === 'session/not-found')` narrows `details` to that code's shape with no cast. A site that must propagate the failure writes `throw result.error` — it is a real `Error`, with a working stack and `message`.
			
 
				+
			
 
				+The client plane does not construct `RemoteError`; the one exception is the Gateway's own client face, which rebuilds an instance from wire data in `invoke()` and folds carrier throws at stream boundaries into the same vocabulary. A test double that needs a failure value takes `RemoteError` from `@deepseek-ai/dsh-client-test-runtime` instead of making a client package import the protocol as a value. Assertions match the code (plus details fields where they matter) with `toMatchObject`: `RemoteError` is an `Error`, its own-key set differs from the former literal, and `toEqual` fails on it.
			
 
				+
			
 
				+## Fixed Host facts
			
 
				+
			
 
				+`ctx.remote.$host` exposes two fixed facts: `home: string | undefined` and `isLoopback: boolean`. It is a getter on the Client Remote service reading the connection handle captured at service construction — `home` comes from the ready frame in the generation snapshot (`undefined` before ready), `isLoopback` from the carrier. There is no store, no subscription, and no generation counter.
			
 
				+
			
 
				+Refresh after a reconnect rides the existing signal: the Client Remote emits `connection/reset` when it connects, and a consumer that must re-read listens for that or for its own domain's remote event rather than turning `$host` into a subscribable object. Consumers therefore no longer inject `connection`: the `@deepseek-ai/dsh-client-connection` consumer allowlist shrinks to hmr, frontend-static, bundle/web-app, session-log-export, webworker-runtime, and the gateway and api-remotes assemblies.
			
 
				+
			
 
				+## What the wire carries
			
 
				+
			
 
				+The envelope is unchanged: the wire still carries `{ code, message, details }` data, and `RemoteError` is each side's in-process carrier for it. On the Host, `rpcFailure()` collapses to two branches — a structurally identified `RemoteError` is encoded as-is, everything else folds into `gateway/internal` — and carrier-signal cancellation uses the same vocabulary (the `RemoteInvocationCancelled` class is deleted, and its four throw points raise `RemoteError('gateway/cancelled', …)`).
			
 
				+
			
 
				+Three wire-visible behaviors follow. The Gateway's 17 assembly codes travel as themselves, so a client can handle "method not mounted" separately from a business refusal. Owners do not pre-fold unrelated exceptions: an unclassified throw reaches the Gateway, which folds it into `gateway/internal` once and keeps the diagnostic chain in `message`. A client unary call aborted by its caller answers `gateway/cancelled`, matching the code the Host would have produced even when the local throw wins the race against the wire round-trip.
			
 
				+
			
 
				+The carrier keeps only the open wire shape. `ConnectionRpcFailure` and `ConnectionRpcResult` in `@deepseek-ai/dsh-client-connection` carry no domain-code knowledge, and its `transportError()` produces `gateway/internal`; the only home for the typed view is now the protocol's `RemoteFailure`.
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**A `RemoteFault` error-class family per domain.** Giving each domain (or each code) its own `Error` subclass reads as more object-oriented, but it splits one fact — the code — across class identity and a field, and cross-realm discrimination has to fall back to the field anyway. Class identity then becomes pure overhead: every domain maintains a subclass, exports it, and explains it in prose, while consumers still branch on `code`. One class plus one code table trades that weight for a single declaration line.
			
 
				+
			
 
				+**`attempt` / `unwrap` / `remoteFailureOf` wrappers at call sites.** A wrapper saves one `if` per call site, but it turns `RemoteResult` from the canonical shape into "first pass it through a library function," and both styles then coexist indefinitely; `unwrap` additionally turns "failure is a normal result" back into an exception flow, against the Remote face's contract of never rejecting. The `remoteErrorOf` that survives serves the mechanism layer and test assertions only — business code holds either a typed `result.error` or a failure it threw itself.
			
 
				+
			
 
				+**A `host/updated` event with a subscribed `$host` store.** A subscription would refresh automatically when the Host home changes, but `home` and `isLoopback` are fixed for the lifetime of one connection, so a store, generation, and subscription lifecycle would tax every page that only wants one read. Reconnection already has a signal (`connection/reset`) and business invalidation rides each domain's remote event, so fixed facts stay plain reads.
			
 
				+
			
 
				+**Putting local, non-wire failures in the code table.** ui-goal's `no-current-goal` never crosses a process boundary; admitting it would mix entries only one client package cares about into a shared vocabulary and would suggest it has wire semantics. Local failures keep their own local types, and the code table describes the Remote vocabulary alone.
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+Adding a domain code is one declaration merge plus one throw: no mapping function, error class, and carrier typed view to keep in step. The cost is that the home now requires a judgment — it must be reachable from every producer — and that judgment only surfaces once a second producer appears; `workspace/not-found` moved from workspace-controller to the capability package exactly that way, which also gave `@deepseek-ai/dsh-workspace` a type-only protocol dependency.
			
 
				+
			
 
				+Prefixing the code strings changes the wire strings wholesale, so codes embedded in connection fixtures, assertions on both the Host and Client sides, and spec-local declarations all move in one pass. The pre-release stance accepts that single cut; the same rename after a release would need a compatibility window.
			
 
				+
			
 
				+The type of `details` follows from the code, so a code-and-details mismatch is rejected at compile time. The other face of that is every throw site having to supply the code's required detail fields: the protocol makes `issues` optional on `gateway/bad-request` precisely so a business validation point with no codec issues still writes `{}`.
			
 
				+
			
 
				+`RemoteError` is an `Error`, so it keeps `message` and `cause` through any logger and through `errorChain()`; but `cause` holds only in-process, and the wire carries exactly `code`, `message`, and `details`. Cross-realm discrimination always reads the structural marker, and any new transport (a worker, a bundle split) must carry that marker or an equivalent marker frame across, or failure values degrade into plain `Error`s.
			
 
				+
			
 
				+Consumer signatures for Remote methods are uniformly `Promise<RemoteResult<T>>`, matching the generated projection described in [the method-call surface](2026-08-02-typert-remote-method-calls.md); the ledger for the unary endpoints is [the unary endpoint migration](2026-08-10-unary-apiproxy-remote-migration.md).
			
--- a/.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.zh.md
@@ -0,0 +1,88 @@
 
				+# Agent Note: One Remote failure vocabulary for ctx.remote
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+[English](2026-08-28-ctx-remote-failure-vocabulary.md) | 中文
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+每个 Remote owner 包各自维护一套失败面：一个 `XxxErrorDetailsMap` 接口、由它派生的 `XxxError` union，以及一个出口映射函数，把域内错误类（`UnknownPresetError`、`PresetMountError`、`SessionTitleInvalidError` 等）翻译成 wire 失败值。`@deepseek-ai/dsh-typert-protocol` 同时携带两个失败类——owner 主动上报用 `TypertRemoteFailure`，lookup resolver 产生的用 `TypertLookupFailure`——而 `@deepseek-ai/dsh-client-connection` 又保留了第二份 typed 视图 `RpcErrorDetailsMap`，把 `agent-preset-not-found`、`session-not-found` 这类域码硬编码进载体层。
			
 
				+
			
 
				+于是一个码同时存在三处：owner 的表、载体的 typed 视图、以及消费方为窄化而写的 union 或 cast（`result.error as SessionError`）。新增一个域码要改三处，跨域转述一个别人的码则要把对方的码复制进自己的表——`SessionErrorDetailsMap` 就收编了 `agent-preset-*`、`subagent-*`、`workspace-not-found` 五个他域码。
			
 
				+
			
 
				+失败信息也在两处被压平。Gateway 自己的 17 个装配失败（未挂载的方法、歧义 endpoint、lookup provider 不匹配、结果未过 codec 等）一律以 `code: 'internal'` 上 wire，client 无法把装配 bug 与业务拒绝区分开；owner 又出于防御把无关异常预折成自己的域码，于是一个真正的 Host bug 会以一个看起来合理的域失败到达调用方。
			
 
				+
			
 
				+Host 固定事实同样绕过了 `ctx.remote`：Host home 取自 `(ctx.get('connection') as ConnectionHandle).generation.getSnapshot()?.host.home`，任何只需要一条固定事实的页面都得注入载体并理解它的 generation store。
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+`@deepseek-ai/dsh-typert-protocol` 导出唯一的失败类 `RemoteError<Code>`：一个真 `Error`，带只读 `code` 与 `details`、结构标记 `isDSHRemoteError`，以及标准 `ErrorOptions`（`cause` 只在进程内有效）。码与 details 的对应关系收进一张 merge-extensible 的 `RemoteErrorDetailsMap`；`RemoteFailure` 是按码分布的实例 union，`RemoteResult<T>` 形状不变。
			
 
				+
			
 
				+```text
			
 
				+export class RemoteError<Code extends RemoteErrorCode = RemoteErrorCode> extends Error {
			
 
				+  readonly isDSHRemoteError: true = true
			
 
				+  constructor(readonly code: Code, message: string,
			
 
				+    readonly details: RemoteErrorDetailsMap[Code], options?: ErrorOptions)
			
 
				+}
			
 
				+export type RemoteFailure = { [C in RemoteErrorCode]: RemoteError<C> }[RemoteErrorCode]
			
 
				+export type RemoteResult<T> = { ok: true; value: T } | { ok: false; error: RemoteFailure }
			
 
				+```
			
 
				+
			
 
				+失败点直接 `throw new RemoteError(code, message, details)`。域内不再建错误类家族，也不再写出口映射函数；只有「把任意 provider 异常归类」这一种场景保留一个 `catch`，并在其中 `throw new RemoteError(code, messageOf(error), details, { cause: error })`。进程内仍需消费的既有异常类（`ApiSessionCwdConflict` 等）保留为不导出的私有类，在出口一行转成 `RemoteError`。
			
 
				+
			
 
				+码是 `<语义域>/<理由>` 形式的字符串：`session/not-found`、`gateway/cancelled`、`workspace/invalid-path`、`agent-preset/locked`。前缀与 wire namespace 同风格，读者从码本身就能看出它属于谁，跨域转述时也不再需要一个别扭的无前缀名。
			
 
				+
			
 
				+## Code ownership
			
 
				+
			
 
				+一个码只有一个声明处，落点由「谁生产它」和「声明对谁可达」共同决定——声明合并只在增补文件进入当前 program 时生效，所以正家必须是每个生产者都能看见的包：
			
 
				+
			
 
				+- **载体码**：`gateway/bad-request`、`gateway/cancelled`、`gateway/internal` 由 protocol 声明，人人可达。
			
 
				+- **Gateway 装配码**：17 个 `gateway/*` 由 `packages/api/gateway/src/remote-error-codes.ts` 声明，details 统一为 `TypertGatewayFaultDetails { endpoint, field? }`；该模块 face-neutral，Host 与 Client 两面各自 import，因此两个 program 看到同一批条目。
			
 
				+- **跨包共产**：两个及以上不同包抛同一个码时，声明落到双方都已依赖的最低层。`session/not-found` 落 `@deepseek-ai/dsh-session`（session-controller 与 workspace-controller 都依赖它），`workspace/not-found` 落 `@deepseek-ai/dsh-workspace`（session-controller 与 workspace-controller 之间没有依赖边，能力包是唯一共同下层）。
			
 
				+- **单一生产者**：只有一个包抛的码落生产者包。`subagent/not-found` 与 `agent-preset/conflict` 因此落 session-controller——全仓只有它抛这两个码，subagent 与 agent-presets 的码表里都没有它们。
			
 
				+
			
 
				+共享的是校验逻辑，不是码。`session/invalid-time-zone` 与 `subagent/invalid-time-zone` 是两个域各自声明、各自抛出的两个码，两个端点共用 `@deepseek-ai/dsh-util-time` 的 `canonicalClientTimeZone()` 做规范化；client 对这个码没有分支语义，拆码的成本是零，而合成一个码就会重新制造可达性问题。
			
 
				+
			
 
				+## Discrimination by code
			
 
				+
			
 
				+判别一律读 `code`，从不用 `instanceof`。Client 与 Host 是两个独立打包的 program，worker 传输还会把页面侧再分一次包，因此同一个类会存在多份副本，跨副本的原型链身份不成立。机制层用 protocol 的 `remoteErrorOf(value)` 读结构标记加一个字符串 `code`，Gateway client face 另外导出 `isRemoteFailure(error)` 供消费方在 catch 里判别；两者都只看这两个字段、不看类——连 `instanceof Error` 都不要求，因为另一个 realm 抛出的 Error 同样通不过它。
			
 
				+
			
 
				+业务代码通常连这两个函数都不需要：`RemoteResult` 的 `ok: false` 分支已经是类型化的 `RemoteFailure`，`if (result.error.code === 'session/not-found')` 就把 `details` 窄化到该码的形状，无需 cast。需要向上抛的站点直接 `throw result.error`——它是真 `Error`，栈与 `message` 都成立。
			
 
				+
			
 
				+client 面不构造 `RemoteError`：唯一例外是 Gateway 的 client face 本身，它在 `invoke()` 里按 wire 数据重建实例、在流边界把载体 throw 折进同一词汇。测试替身要构造失败值时从 `@deepseek-ai/dsh-client-test-runtime` 取 `RemoteError`，而不是让 client 包值引入 protocol。断言用 `toMatchObject` 判 code（必要时加 details 字段）：`RemoteError` 是 `Error`，own key 集合与旧字面量不同，`toEqual` 会失败。
			
 
				+
			
 
				+## Fixed Host facts
			
 
				+
			
 
				+`ctx.remote.$host` 暴露两条固定事实：`home: string | undefined` 与 `isLoopback: boolean`。它是 Client Remote service 上的 getter，读的是 service 构造期取得的 connection 句柄——`home` 来自 generation 快照的 ready frame（ready 之前是 `undefined`），`isLoopback` 来自载体。没有 store、没有订阅、没有 generation 计数器。
			
 
				+
			
 
				+重连后的刷新走既有信号：Client Remote 在连上时 emit `connection/reset`，需要重取的消费方监听它或各域自己的 remote event，而不是让 `$host` 变成一个可订阅对象。因此消费方不再注入 `connection`：`@deepseek-ai/dsh-client-connection` 的消费白名单收缩到 hmr、frontend-static、bundle/web-app、session-log-export、webworker-runtime、gateway 与 api-remotes 装配。
			
 
				+
			
 
				+## What the wire carries
			
 
				+
			
 
				+envelope 不变：wire 上仍是 `{ code, message, details }` 数据，`RemoteError` 是两端各自的进程内载体。Host 侧 `rpcFailure()` 收敛为两分支——结构识别出的 `RemoteError` 原样编码，其余折成 `gateway/internal`；载体信号取消也走同一词汇（`RemoteInvocationCancelled` 类整体删除，四个 throw 点改抛 `RemoteError('gateway/cancelled', …)`）。
			
 
				+
			
 
				+三条 wire 可见行为随之确定。Gateway 的 17 个装配码按语义上 wire，client 因此能把「方法未挂载」与「业务拒绝」分开处理。owner 不预折无关异常：未归类的 throw 交给 Gateway 折一次 `gateway/internal`，诊断串保留在 `message` 里。client 一元调用被调用方 abort 时答 `gateway/cancelled`，即使本地 throw 抢在 wire 往返之前赢得竞争，也与 Host 会给出的码一致。
			
 
				+
			
 
				+载体层只保留开放的 wire 形状。`@deepseek-ai/dsh-client-connection` 的 `ConnectionRpcFailure`/`ConnectionRpcResult` 不含任何域码知识，其 `transportError()` 产出 `gateway/internal`；typed 视图的正家从此只有 protocol 的 `RemoteFailure`。
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**每域一套 `RemoteFault` 错误类家族。** 让每个域（或每个码）有自己的 `Error` 子类，看起来更 OO，但它把「码」这一条信息拆成了类身份加字段两处，跨 realm 又只能退回判字段——于是类身份成为纯粹的负担：每个域要维护子类、导出它、在文档里解释它，而消费方仍然只能判 code。单类加一张码表把这份重量换成了一行声明。
			
 
				+
			
 
				+**在调用点加 `attempt` / `unwrap` / `remoteFailureOf` 包装函数。** 包装能让调用点少写一个 `if`，但它把 `RemoteResult` 这个 canonical 形状变成了「先过一层库函数」，两种风格会长期并存；`unwrap` 还会把「失败是正常结果」重新变成异常流，与 Remote 面不 reject 的契约背道而驰。被保留的 `remoteErrorOf` 只服务机制层与测试断言，业务代码拿到的要么是已类型化的 `result.error`、要么是自己抛的，不需要它。
			
 
				+
			
 
				+**`host/updated` 事件加订阅式 `$host` store。** 订阅能在 Host home 变化时自动刷新，但 home 与 isLoopback 在一条连接内是固定事实，为它引入 store、generation 与订阅生命周期，等于让每个只想读一次的页面都承担一套状态管理。重连是已有信号（`connection/reset`），业务失效走各域 remote event，固定事实保持普通值读取。
			
 
				+
			
 
				+**把不上 wire 的本地失败也纳入码表。** 例如 ui-goal 的 `no-current-goal`：它从不跨进程，纳入码表会让共享词汇混入只有一个 client 包关心的条目，还会误导读者以为它有 wire 语义。本地失败保持各自的本地类型，码表只描述 Remote 词汇。
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+新增一个域码是一处 declaration merging 加一个 throw：不再有映射函数、错误类、载体 typed 视图三处联动。代价是落点需要判断——正家必须对每个生产者可达，而这条判断只有在真的出现第二个生产者时才显现；`workspace/not-found` 就是这样从 workspace-controller 迁到能力包的，并为此给 `@deepseek-ai/dsh-workspace` 加了一条 type-only 的 protocol 依赖。
			
 
				+
			
 
				+码字符串带前缀后，wire 字符串整体变化，connection fixture 内嵌的码、host 与 client 两侧断言、spec 本地 declare 一次性同步。发布前阶段接受这次一波切；发布后同样的改名需要一个兼容期。
			
 
				+
			
 
				+`details` 的类型由码决定，因此码与 details 的搭配错误在编译期就被拒。反面是每个抛点都要给全 details 的必填字段：protocol 把 `gateway/bad-request` 的 `issues` 设为可选，正是为了让没有 codec issues 的业务校验点仍然只写 `{}`。
			
 
				+
			
 
				+`RemoteError` 是 `Error`，所以它进任何日志与 `errorChain()` 都保留 `message` 与 `cause`；但 `cause` 只在进程内成立，wire 上只有 `code`、`message`、`details` 三个字段。跨 realm 的判别永远读结构标记，任何新增的传输（worker、bundle 分片）都必须把标记或等价的 marker 帧带过去，否则失败值会退化为普通 `Error`。
			
 
				+
			
 
				+Remote 方法的消费端签名统一为 `Promise<RemoteResult<T>>`，与[方法调用面](2026-08-02-typert-remote-method-calls.zh.md)描述的生成投影一致；一元调用的迁移账本见[一元端点迁移](2026-08-10-unary-apiproxy-remote-migration.zh.md)。
			
--- a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
@@ -1,37 +0,0 @@
 
				-# Agent Note: The conversation column scrolls on one axis
			
 
				-
			
 
				-Status: implemented
			
 
				-
			
 
				-English | [中文](2026-08-04-conversation-column-one-axis-scroll.zh.md)
			
 
				-
			
 
				-## Problem
			
 
				-
			
 
				-Narrowing the center column — by the window or by the sidebar drag — put a horizontal scrollbar under the whole conversation column on the hero. The bleeding element is the hero's decorative backdrop ellipse: `.heroGlow` is sized `1051/776` of the hero box so its blur scales in userSpace with the input card, which means it reaches past the column whenever the column is narrower than the glow.
			
 
				-
			
 
				-That bleed is by construction and stays. What made it user-visible is the scroll container it sits in. `[data-conversation-scroll]` declared `overflow-y: auto` and left the other axis at its initial `visible`, and a box that scrolls in one axis computes `visible` to `auto` in the other. Every column narrower than the glow therefore offered a real horizontal scroll range — measured at 24–95px across the widths a laptop actually produces.
			
 
				-
			
 
				-## Decision
			
 
				-
			
 
				-`.scrollBody` declares `overflow-x: hidden`. The column states that it is a one-axis scroller instead of leaving the second axis to be derived.
			
 
				-
			
 
				-Clipping does not change. `overflow-y: auto` had already made the box a scroll container that clips both axes, so the declaration withdraws only the scrollbar and the user gesture; the glow keeps its bleed, its blur radius, and the same painted extent, and the column keeps its vertical scroll. Nothing in the composer chain moves.
			
 
				-
			
 
				-## Alternatives considered
			
 
				-
			
 
				-**Size the glow to fit the column.** Rejected. The glow's width is what scales its `stdDeviation="50"` blur with the input card (figma 313:14109); constraining it would make the blur tighten as the column narrows, which is a visual regression to fix a scrollbar.
			
 
				-
			
 
				-**Wrap the glow in a clipping box.** Rejected. It adds a box whose only job is to undo an overflow the column already clips, and it leaves the derived `overflow-x: auto` in place for the next element that bleeds — the transcript is full of candidates.
			
 
				-
			
 
				-**Rely on the frame's `.centerCol { overflow: hidden }`.** It cannot help. That clip is outside the scroll container, so it hides the glow's overhang at the column border while the container inside it still scrolls to reach it. The reported bar was that container's.
			
 
				-
			
 
				-**Assert `scrollWidth === clientWidth` in the test.** Rejected as the signal, because it does not distinguish the states: `hidden` clips the bleed rather than reflowing it away, so the scroll range reads the same on both sides of the fix. Only refusing a user gesture differs, which is what the scenario measures.
			
 
				-
			
 
				-## Testing
			
 
				-
			
 
				-[apps/web/tests/conversation-column-overflow.e2e.ts](../../../../apps/web/tests/conversation-column-overflow.e2e.ts) sweeps viewport widths bracketing the glow and, at each stop, wheels horizontally over the column and reads `scrollLeft`. The committed golden records the relation per stop; the widest stop is the control where the glow does not bleed at all.
			
 
				-
			
 
				-Two guards keep the scenario honest. The vacuity guard asserts the glow still reaches past the column at the narrow stops, so the claim cannot pass by the symptom having disappeared for an unrelated reason. The mutation control forces `overflow-x: auto` back on in the page and shows the same gesture, at the same timing, carrying the column to its positive scroll boundary; the test measures that boundary directly because a stable scrollbar gutter can leave some overflow on the negative side of the scroll origin. Without the control, a `scrollLeft` of 0 could equally mean the wheel never arrived.
			
 
				-
			
 
				-## Consequences
			
 
				-
			
 
				-The conversation column no longer offers a horizontal scrollbar at any width, and decorative bleed in the composer chain is now clipped rather than exposed as scroll range. The cost is that genuinely wide content under this column is clipped instead of reachable by scrolling: any such surface owns its own scroller, as the markdown code block and the trajectory table already do.
			
--- a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
@@ -1,37 +0,0 @@
 
				-# Agent Note: 会话列只在一个轴上滚动
			
 
				-
			
 
				-Status: implemented
			
 
				-
			
 
				-[English](2026-08-04-conversation-column-one-axis-scroll.md) | 中文
			
 
				-
			
 
				-## 问题
			
 
				-
			
 
				-当中间列被拉窄——无论是拖窗口还是拖侧边栏——hero 态的整条会话列下方就会出现一条横向滚动条。溢出的元素是 hero 的装饰性背景椭圆：`.heroGlow` 的宽度取 hero 盒子的 `1051/776`，好让它的模糊在 userSpace 中随输入卡片一同缩放；这也意味着只要列比它窄，它就会伸出列外。
			
 
				-
			
 
				-这处外溢是设计使然，保持不变。真正让它对用户可见的是它所处的滚动容器。`[data-conversation-scroll]` 只声明了 `overflow-y: auto`，另一个轴留在初始值 `visible`；而一个在某一轴上滚动的盒子，会把另一轴的 `visible` 计算为 `auto`。于是每一条比该椭圆窄的列都真的给出了一段横向滚动范围——在笔记本实际会产生的几档宽度上，实测为 24–95px。
			
 
				-
			
 
				-## 决策
			
 
				-
			
 
				-`.scrollBody` 声明 `overflow-x: hidden`。这条列明确声明自己是单轴滚动容器，而不是把第二个轴交给推导。
			
 
				-
			
 
				-裁剪行为不变。`overflow-y: auto` 早已使该盒子成为在两个轴上都裁剪的滚动容器，因此这条声明收回的只是滚动条和用户手势；椭圆保留它的外溢、模糊半径和同样的绘制范围，列也保留纵向滚动。输入区那条链路上没有任何东西移动。
			
 
				-
			
 
				-## 曾考虑的替代方案
			
 
				-
			
 
				-**把椭圆缩到列内。** 否决。椭圆的宽度正是让它 `stdDeviation="50"` 的模糊随输入卡片缩放的依据（figma 313:14109）；约束宽度会使列越窄模糊越紧，等于为修一条滚动条而制造一处视觉回归。
			
 
				-
			
 
				-**给椭圆套一层裁剪盒。** 否决。这层盒子唯一的职责是抵消列本就会裁剪的溢出，而推导出的 `overflow-x: auto` 仍然留在原处，等着下一个外溢的元素——transcript（文本记录）里这样的候选者不少。
			
 
				-
			
 
				-**依赖外框的 `.centerCol { overflow: hidden }`。** 它帮不上忙。那处裁剪在滚动容器之外，只能在列边界处遮住椭圆探出的部分，而里面的容器照样可以滚过去够到它。用户报告的那条滚动条属于内层容器。
			
 
				-
			
 
				-**在测试里断言 `scrollWidth === clientWidth`。** 作为判据被否决，因为它区分不出两种状态：`hidden` 裁剪外溢，而不是把它重排掉，所以修复前后读到的滚动范围一样。唯一有差别的是拒绝用户手势，这正是该场景所测量的。
			
 
				-
			
 
				-## 测试
			
 
				-
			
 
				-[apps/web/tests/conversation-column-overflow.e2e.ts](../../../../apps/web/tests/conversation-column-overflow.e2e.ts) 扫过一组把椭圆宽度夹在中间的视口宽度，在每一档上于列上触发横向滚轮事件并读取 `scrollLeft`。提交的 golden 逐档记录该关系；最宽的一档是椭圆根本不外溢的对照。
			
 
				-
			
 
				-两道防线保证该场景不流于形式。空断言防线断言窄档上椭圆确实仍伸出列外，使这项主张不可能因为症状出于无关原因消失而通过。变异对照则在页面内把 `overflow-x: auto` 强制改回，证明同一手势在同一时序下能把列带到正向滚动边界。测试直接测量该边界，因为稳定的滚动条槽可能让部分外溢处于滚动原点的负向。没有这项对照，`scrollLeft` 读到 0 同样可以解释为滚轮事件根本没送达。
			
 
				-
			
 
				-## 后果
			
 
				-
			
 
				-会话列在任何宽度下都不再给出横向滚动条，输入区链路上的装饰性外溢从暴露为滚动范围改为被裁剪。代价是这条列下真正过宽的内容会被裁掉而非可滚动够到：这类界面各自拥有自己的滚动容器，markdown 代码块和轨迹表格已经如此。
			
--- a/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.md
			
 
				-2026-08-28-linear-stream-queue-drain.md: e92dd03ef52ead44b083f997f83746cee03af97f
			
 
				-2026-08-28-linear-stream-queue-drain.zh.md: 1d0ff4813b8a7e61e196cbdc63bab0c501d49e11
			
 
				+2026-08-28-linear-stream-queue-drain.md: 3ec9ff3ae0f4df1265bc38dd86e44c126ea7e3e9
			
 
				+2026-08-28-linear-stream-queue-drain.zh.md: c71b1da07408a8c502a60c84a38d8f009721d7bc
			
--- a/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.md
@@ -14,7 +14,7 @@ The affected streams have different wake-up, failure, cancellation, and disposal
 
				 
			
 
				 `@deepseek-ai/dsh-deque` owns one zero-dependency circular array for Host and browser consumers. `pushBack()`, `pushFront()`, and `popFront()` change indices instead of moving the live range. A removal clears its slot immediately. The backing array doubles when full and halves when a non-empty deque reaches one quarter of capacity, so growth and compaction copy work remains amortized constant time and vacant storage stays bounded over interleaved queue use.
			
 
				 
			
 
				-The package has no singleton state, symbols, or class identity shared between Client plugins, so the Client bundle purity rule treats it as an inline-safe library. The Gateway browser artifact carries its deque implementation without introducing a module-table entry or a Cordis service.
			
 
				+The package has no singleton state, symbols, or class identity shared between consumers. Each consumer constructs and confines its own deque, so duplicate npm copies preserve runtime behavior and the published dependency policy treats `Deque` as a safe Host export. The Client bundle purity rule also treats the package as an inline-safe library. The Gateway browser artifact carries its deque implementation without introducing a module-table entry or a Cordis service.
			
 
				 
			
 
				 The Host Remote event source, each connected Client Remote event queue, the browser Remote stream inbox, each Session history follower, each Session control stream, and each Workspace follower store frames in this deque. Their owning classes retain all wake-up, failure, cancellation, buffered-drain, and disposal behavior. Session history uses front insertion to place constructor-seed events before live events received during its opening observation.
			
 
				 
			
--- a/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
				 
			
 
				 `@deepseek-ai/dsh-deque` 为 Host 和浏览器消费方拥有一个零依赖环形数组。`pushBack()`、`pushFront()` 和 `popFront()` 改变索引，而不移动存活区间。移除会立即清空对应槽位。后备数组在满载时翻倍，在非空双端队列达到四分之一容量时减半，因此扩容和压缩的复制工作保持摊销常数时间，且交错队列使用期间的空闲存储保持有界。
			
 
				 
			
 
				-该包没有 Client 插件之间共享的 singleton 状态、符号或类身份，因此 Client bundle purity 规则把它视为可内联库。Gateway 浏览器产物携带其双端队列实现，而不引入 module-table 条目或 Cordis 服务。
			
 
				+该包没有消费方之间共享的 singleton 状态、符号或类身份。每个消费方都会构造并独占自己的双端队列，因此 npm 中存在重复包副本不会改变运行时行为，发布依赖策略也会把 `Deque` 视为安全的 Host 导出。Client bundle purity 规则同样把该包视为可内联库。Gateway 浏览器产物携带其双端队列实现，而不引入 module-table 条目或 Cordis 服务。
			
 
				 
			
 
				 Host Remote 事件源、每个已连接 Client 的 Remote 事件队列、浏览器 Remote 流 inbox、每个会话历史 follower、每个会话控制流和每个 Workspace follower 都在此双端队列中存储帧。它们的所属类保留全部唤醒、失败、取消、缓冲排空和 disposal 行为。会话历史使用前插，把构造器种子事件放在打开观察期间收到的 live 事件之前。
			
 
				 
			
--- a/.agents/notes/implemented/bug-fix/2026-08-28-trigger-menu-stale-while-revalidate.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-28-trigger-menu-stale-while-revalidate.i18n.yaml
@@ -1,6 +1,6 @@
 
				 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				-#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
			
 
				-2026-08-04-conversation-column-one-axis-scroll.md: 9a487c506a75033d0854f08e95da24704309003d
			
 
				-2026-08-04-conversation-column-one-axis-scroll.zh.md: b86f86f55757dff4fddab4c4e2ac64fa7c19fe59
			
 
				+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-28-trigger-menu-stale-while-revalidate.md
			
 
				+2026-08-28-trigger-menu-stale-while-revalidate.md: 12541ba3ec6ee82ac6c12da85f99c0d8e044b9e8
			
 
				+2026-08-28-trigger-menu-stale-while-revalidate.zh.md: 69b3d1b6a304562e1bb1835b1de2f09f8f38c5a4
			
--- a/.agents/notes/implemented/bug-fix/2026-08-28-trigger-menu-stale-while-revalidate.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-28-trigger-menu-stale-while-revalidate.md
@@ -0,0 +1,27 @@
 
				+# Agent Note: The trigger menu keeps previous rows through refinement
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+English | [中文](2026-08-28-trigger-menu-stale-while-revalidate.zh.md)
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+Every keystroke inside an open `@`/`/` trigger menu launches a new candidates fetch. The menu reducer's `hit` case used to reseed the groups to pending-empty, so the list collapsed to a skeleton for the 100–460ms fetch round trip and repainted on every character — a visible flicker on each refinement keystroke (#3234).
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+The reducer's `hit` case (`core/menu.ts`) now retains the previous query's rows and highlight, marking each group `pending` — stale-while-revalidate. Fresh opens (`seedGroups`) still start empty, so the first paint keeps its skeleton; `allReadyEmpty` still auto-closes after settle.
			
 
				+
			
 
				+Stale rows are display-only. `pick()` requires the candidate's group to be `ready`, and the `enter` arbitration checks the highlighted group's status before picking: during the pending window Enter is an explicit no-op (`'consumed'`) — it neither picks the stale row nor falls through to submit the draft. Tab already carried the same `ready` check for drilling.
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**Clear to a skeleton on every refinement.** Rejected; this was the flickering status quo. The production chat frontend's conversation search does clear (results and active index reset per debounced query), which keeps its Enter trivially safe — but its list is in a dedicated dialog, whereas this menu repaints directly under the caret on every keystroke, where the flicker is what users reported.
			
 
				+
			
 
				+**Pass Enter through to submit during the pending window.** Rejected. Before this change the window showed an empty skeleton, so Enter falling through to send was visually consistent; with retained rows the user is looking at a highlighted candidate, and sending the whole draft under it is a worse mis-fire than a few hundred milliseconds of dead key. The production search's pending-window Enter is likewise a no-op.
			
 
				+
			
 
				+**Queue the Enter and pick when the fetch settles.** Rejected. Acting on a keypress against rows the user has not seen yet reintroduces the stale-pick race with extra timing machinery.
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+Refinement keystrokes no longer flicker; the list content swaps in place when the fetch settles. The costs: Enter is dead for the pending window (pressing it again after settle picks normally), and rows are index-keyed, so a settle swaps DOM node content in place — pointer tests must wait for a stale-only row to disappear before clicking (`reference-composer.e2e.ts` polls `folderx/` away). A pre-existing highlight blink during refinement remains open and is deferred to a follow-up.
			
--- a/.agents/notes/implemented/bug-fix/2026-08-28-trigger-menu-stale-while-revalidate.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-28-trigger-menu-stale-while-revalidate.zh.md
@@ -0,0 +1,27 @@
 
				+# Agent Note: The trigger menu keeps previous rows through refinement
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+[English](2026-08-28-trigger-menu-stale-while-revalidate.md) | 中文
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+在已打开的 `@`/`/` 触发菜单里,每个按键都会发起一次新的候选请求。菜单 reducer 的 `hit` 分支过去会把各组重置为 pending-空,于是列表在 100–460ms 的请求往返期间塌缩成骨架屏,每输入一个字符就重绘一次——细化查询时肉眼可见的闪烁(#3234)。
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+reducer 的 `hit` 分支(`core/menu.ts`)现在保留上一次查询的行和高亮,并把各组标记为 `pending`——即 stale-while-revalidate。首次打开(`seedGroups`)仍从空开始,首帧保持骨架屏;`allReadyEmpty` 仍在结算后自动关闭。
			
 
				+
			
 
				+旧行仅用于显示。`pick()` 要求候选所在组为 `ready`,`enter` 仲裁在 pick 前检查高亮组的状态:pending 窗口内 Enter 是显式 no-op(`'consumed'`)——既不选中旧行,也不落到草稿发送。Tab 的下钻早已带有相同的 `ready` 检查。
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**每次细化都清空为骨架屏。** 拒绝;这正是闪烁的现状。线上 chat 前端的会话搜索确实是清空(每次防抖查询重置结果和活动索引),其 Enter 因此天然安全——但那个列表在独立弹窗里,而本菜单直接在光标下随每个按键重绘,闪烁正是用户所报告的问题。
			
 
				+
			
 
				+**pending 窗口内让 Enter 透传到发送。** 拒绝。改动前该窗口显示空骨架屏,Enter 落到发送在视觉上是自洽的;保留旧行后用户正看着一个高亮候选,此时把整条草稿发出去比几百毫秒的按键失效是更糟的误触。线上搜索在 pending 窗口的 Enter 同样是 no-op。
			
 
				+
			
 
				+**把 Enter 排队,请求结算后再选中。** 拒绝。对用户尚未见到的行执行按键会重新引入选中旧数据的竞态,还额外增加时序机制。
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+细化按键不再闪烁;请求结算时列表内容原位替换。代价:pending 窗口内 Enter 失效(结算后再按即正常选中);行按 index 作为 key,结算时 DOM 节点内容原位替换——指针类测试点击前必须等待仅旧查询匹配的行消失(`reference-composer.e2e.ts` 轮询 `folderx/` 消失)。细化期间已存在的高亮闪动问题仍未解决,留待后续 PR。
			
--- a/.agents/notes/implemented/bug-fix/2026-08-29-windows-atomic-replace-retry.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-29-windows-atomic-replace-retry.i18n.yaml
@@ -0,0 +1,6 @@
 
				+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				+# side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				+# after editing either side, bring the other along and re-record with:
			
 
				+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-29-windows-atomic-replace-retry.md
			
 
				+2026-08-29-windows-atomic-replace-retry.md: 4db5de6403be7ec39a1568a11d8877cba1ed5838
			
 
				+2026-08-29-windows-atomic-replace-retry.zh.md: 0138727ac0fe12af51b5a383b60859977300353c
			
--- a/.agents/notes/implemented/bug-fix/2026-08-29-windows-atomic-replace-retry.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-29-windows-atomic-replace-retry.md
@@ -0,0 +1,27 @@
 
				+# Agent Note: Retry transient Windows atomic replacements
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+English | [中文](2026-08-29-windows-atomic-replace-retry.zh.md)
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+Windows can temporarily reject a rename that replaces an existing file with `EACCES`, `EBUSY`, or `EPERM` while another system component holds the target. The cross-process writer lock orders cooperating application writers but cannot release that external handle, so treating the first error as permanent makes an otherwise valid settings or credentials update fail nondeterministically.
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+`writeFileAtomic` owns replacement retry because every file-backed store needs the same guarantee. On Windows only, it retries `EACCES`, `EBUSY`, and `EPERM` up to eight times with exponential delays from 20 to 200 milliseconds. The same fully written temporary sibling remains the rename source throughout, and a caller-held writer lock remains held until `writeFileAtomic` settles.
			
 
				+
			
 
				+Other error codes and other operating systems fail immediately. Exhausting the retry budget rethrows the final filesystem error after removing the temporary sibling; the existing target remains unchanged because no attempt deletes or truncates it.
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**Retry the credentials mutation.** A consumer-level retry would leave settings and future stores exposed, and replaying a read-modify-write operation can repeat work outside the atomic replacement. The shared primitive is the narrow owner of replacement-only retry.
			
 
				+
			
 
				+**Delete the target before rename.** Removing the target can make readers observe an absent file and forfeits atomic replacement, so it cannot be a recovery step.
			
 
				+
			
 
				+**Retry indefinitely.** A permanent permission error would then hang the writer and any lock contender. A bounded delay absorbs transient file use while preserving a predictable failure outcome.
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+A transient Windows handle can delay one replacement by at most 1.1 seconds before the final attempt fails. During that interval readers continue to see the complete old target, and success still consists of one atomic rename. Regression tests inject every retried code, permanent and non-Windows failures, and retry exhaustion; they observe rename attempts and advance fake timers rather than depending on wall-clock sleeps.
			
--- a/.agents/notes/implemented/bug-fix/2026-08-29-windows-atomic-replace-retry.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-29-windows-atomic-replace-retry.zh.md
@@ -0,0 +1,27 @@
 
				+# Agent Note: 重试 Windows 上的瞬时原子替换失败
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+[English](2026-08-29-windows-atomic-replace-retry.md) | 中文
			
 
				+
			
 
				+## 问题
			
 
				+
			
 
				+当另一个系统组件持有目标文件时，Windows 可能以 `EACCES`、`EBUSY` 或 `EPERM` 暂时拒绝替换已有文件的 rename。跨进程写锁能够排序应用内互相协作的写入方，却无法释放该外部句柄，因此把第一次错误当作永久失败会让本来有效的设置或凭据更新随机失败。
			
 
				+
			
 
				+## 决策
			
 
				+
			
 
				+`writeFileAtomic` 负责替换重试，因为每个文件型存储都需要相同保证。它仅在 Windows 上重试 `EACCES`、`EBUSY` 与 `EPERM`，最多八次，延迟从 20 毫秒指数增长至 200 毫秒。整个过程中，同一份已经完整写入的临时兄弟文件始终作为 rename 来源；调用方持有的写锁也会保持到 `writeFileAtomic` 结束。
			
 
				+
			
 
				+其他错误码和其他操作系统会立即失败。重试预算耗尽后，函数移除临时兄弟文件并重新抛出最后一个文件系统错误；由于任何尝试都不会删除或截断现有目标，目标内容保持不变。
			
 
				+
			
 
				+## 考虑过的替代方案
			
 
				+
			
 
				+**重试凭据变更。** 消费方级重试仍会让设置和未来存储暴露于同一问题，而且重放一次读-修改-写操作可能重复原子替换之外的工作。共享原语是只负责替换重试的最窄所有者。
			
 
				+
			
 
				+**在 rename 前删除目标。** 删除目标会让读取方观察到文件缺失，并放弃原子替换，因此不能作为恢复步骤。
			
 
				+
			
 
				+**无限重试。** 永久权限错误会由此挂住写入方与所有锁竞争者。有界延迟可以吸收瞬时文件占用，同时保留可预测的失败结果。
			
 
				+
			
 
				+## 后果
			
 
				+
			
 
				+一个瞬时 Windows 句柄最多会让单次替换多等待 1.1 秒，随后最终尝试失败。在此期间，读取方继续看到完整的旧目标；成功仍由一次原子 rename 完成。回归测试注入每种可重试错误、永久错误、非 Windows 错误与重试耗尽，并观察 rename 尝试和推进伪时钟，而不依赖真实时间 sleep。
			
--- a/.agents/notes/implemented/feature/2026-08-12-hero-fish-hover-swim-morph.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-12-hero-fish-hover-swim-morph.i18n.yaml
@@ -0,0 +1,6 @@
 
				+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				+# side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				+# after editing either side, bring the other along and re-record with:
			
 
				+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-12-hero-fish-hover-swim-morph.md
			
 
				+2026-08-12-hero-fish-hover-swim-morph.md: c485f94e244040d7e72838065f977e698391c00d
			
 
				+2026-08-12-hero-fish-hover-swim-morph.zh.md: 46fa50732bf98aa5e3afb503e84f8e23001499b2
			
--- a/.agents/notes/implemented/feature/2026-08-12-hero-fish-hover-swim-morph.md
+++ b/.agents/notes/implemented/feature/2026-08-12-hero-fish-hover-swim-morph.md
@@ -0,0 +1,27 @@
 
				+# Agent Note: Hero fish hover swim morph
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+English | [中文](2026-08-12-hero-fish-hover-swim-morph.zh.md)
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+Hovering the New Session hero fish (`EmptyHero.tsx` in `dsh-client-ui-conversation`) played a one-shot rigid CSS sway of the whole svg. The user wanted the whale to visibly swim — the tail wagging and the mouth curve lifting — which requires deforming the path geometry itself. CSS transforms cannot bend a subset of a path's curves, and the logo ships as one `FISH_LOGO_PATH` string in `dsh-client-ui-primitives`.
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+Real curve deformation via SMIL `<animate attributeName="d">` cycling `rest → tail-up → rest → tail-down → rest` on the same 1.6s period as the CSS sway, which becomes continuous (`infinite`) for as long as the pointer stays. The two morph targets are generated programmatically (`/tmp`-run script, not checked in): parse `FISH_LOGO_PATH`'s absolute M/C/L/Z commands, rotate the tail region about a pivot with smoothstep falloff weights, bend the mouth/fin swoosh vertically with weight-squared falloff from its body anchor (a smile lift, not a rigid swing — rigid rotation read as detached), and emit structure-identical command strings SMIL can interpolate. The baked path constants live next to the component with the generation parameters documented. SMIL cannot ride CSS media queries, so a `hovering` state gated by `matchMedia('(prefers-reduced-motion: reduce)')` mounts the morph, while the CSS sway sits under `@media (hover: hover) and (prefers-reduced-motion: no-preference)`.
			
 
				+
			
 
				+The morphing fish reaches the hero as the fallback of the `conversation.hero.brand.mark` slot; no shipped package occupies it — `dsh-client-ui-brand-official` fills only the sidebar slots, since a feature plugin may not value-import `HeroFish` across packages ([client cross-package rule](../process/2026-08-23-client-cross-package-value-dependencies.md)) and the fallback already is the official mark. `FISH_LOGO_PATH` and `FISH_LOGO_VIEWBOX` are exported from `dsh-client-ui-primitives` for consumers that compose their own svg around the same geometry.
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**Vector-tool path editing for the morphs.** No interactive tool in the loop; programmatic weighted deformation was chosen because it guarantees the identical command structure SMIL `d` interpolation requires and makes amplitudes reviewable numbers.
			
 
				+
			
 
				+**Blowhole spout on hover.** Removed at the user's request; hover keeps only shape morph and sway.
			
 
				+
			
 
				+**Occupying the hero slot with the official mark.** The previous arrangement; rejected because the static occupant shadowed the animated fallback, and animating the occupant instead would need the forbidden cross-package value import.
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+The hover swim is decorative (`aria-hidden`) and reduced-motion-safe (static logo on hover). The sway CSS targets the stationary `.fishHitbox` wrapper, so a slot occupant would sway too; the body morph lives only in the fallback `HeroFish`. Coverage is the `skeleton.client.spec.tsx` suite asserting slot contract (name, owner props, fallback existence); the keyless snapshot harness records transcripts, not browser animation, so visual verification of the morph stays manual. Regenerating the morph targets requires re-running the (uncommitted) deformation script against `FISH_LOGO_PATH`; if the logo geometry ever changes, the baked constants must be regenerated with it.
			
--- a/.agents/notes/implemented/feature/2026-08-12-hero-fish-hover-swim-morph.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-12-hero-fish-hover-swim-morph.zh.md
@@ -0,0 +1,27 @@
 
				+# Agent Note：主页鲸鱼 hover 游动变形
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+[English](2026-08-12-hero-fish-hover-swim-morph.md) | 中文
			
 
				+
			
 
				+## 问题
			
 
				+
			
 
				+hover New Session 主页的鲸鱼（`dsh-client-ui-conversation` 的 `EmptyHero.tsx`）原本只播放一次整个 svg 的刚性 CSS 摇摆。用户希望鲸鱼有真实的游动感——尾巴摆动、嘴巴曲线上扬，这要求对路径几何本身做变形。CSS transform 无法弯曲路径中的部分曲线，且 logo 以单一 `FISH_LOGO_PATH` 字符串存放在 `dsh-client-ui-primitives`。
			
 
				+
			
 
				+## 决定
			
 
				+
			
 
				+通过 SMIL `<animate attributeName="d">` 做真实曲线变形，按与 CSS 摇摆相同的 1.6s 周期循环 `静止 → 尾上摆 → 静止 → 尾下压 → 静止`；CSS 摇摆改为持续循环（`infinite`），指针停留多久就游多久。两个变形目标由程序生成（在 `/tmp` 运行的脚本，未入库）：解析 `FISH_LOGO_PATH` 的绝对 M/C/L/Z 命令，尾部区域绕支点做带 smoothstep 衰减权重的旋转，嘴巴/鳍的内侧曲线以距身体锚点的权重平方做竖直弯曲（微笑式上扬，而非刚性摆动——刚性旋转看起来与身体脱节），并输出结构完全一致、SMIL 可插值的命令串。烘焙出的路径常量与组件放在一起，并在注释中记录生成参数。SMIL 无法响应 CSS 媒体查询，因此用经 `matchMedia('(prefers-reduced-motion: reduce)')` 判定的 `hovering` 状态控制变形挂载，CSS 摇摆则在 `@media (hover: hover) and (prefers-reduced-motion: no-preference)` 之下。
			
 
				+
			
 
				+变形鲸鱼以 `conversation.hero.brand.mark` slot 的 fallback 身份进入主页；没有任何发布包占据该 slot——`dsh-client-ui-brand-official` 只填充侧栏槽位，因为 feature 插件不得跨包 value-import `HeroFish`（[client 跨包规则](../process/2026-08-23-client-cross-package-value-dependencies.zh.md)），而 fallback 本身就是官方标志。`FISH_LOGO_PATH` 与 `FISH_LOGO_VIEWBOX` 从 `dsh-client-ui-primitives` 导出，供围绕同一几何自行组装 svg 的消费方使用。
			
 
				+
			
 
				+## 考虑过的替代方案
			
 
				+
			
 
				+**用矢量工具编辑路径做变形。** 流程中没有可交互的工具；选择程序化加权变形，因为它保证 SMIL `d` 插值所要求的完全一致的命令结构，且振幅是可评审的数字。
			
 
				+
			
 
				+**hover 气孔喷水。** 按用户要求移除；hover 只保留形状变形与摇摆。
			
 
				+
			
 
				+**让官方标志占据主页 slot。** 即先前的安排；否决，因为静态 occupant 会遮住动画 fallback，而给 occupant 加动画又需要被禁止的跨包 value import。
			
 
				+
			
 
				+## 影响
			
 
				+
			
 
				+hover 游动是纯装饰（`aria-hidden`）且对 reduced-motion 安全（hover 保持静态 logo）。摇摆 CSS 作用于外层静止的 `.fishHitbox`，因此换成 slot occupant 也会摇摆；身体变形只存在于 fallback 的 `HeroFish` 中。覆盖由 `skeleton.client.spec.tsx` 断言 slot 合约（名称、owner props、fallback 存在性）；keyless 快照体系记录对话转录而非浏览器动画，变形的视觉验证仍需人工。重新生成变形目标需要对 `FISH_LOGO_PATH` 重跑（未入库的）变形脚本；若 logo 几何将来变化，烘焙常量必须随之重新生成。
			
--- a/.agents/notes/implemented/feature/2026-08-28-web-connection-recovery-control.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-28-web-connection-recovery-control.i18n.yaml
@@ -0,0 +1,6 @@
 
				+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				+# side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				+# after editing either side, bring the other along and re-record with:
			
 
				+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-28-web-connection-recovery-control.md
			
 
				+2026-08-28-web-connection-recovery-control.md: 6fec265c8e166836a5ab9413f1612cdaa6461a1d
			
 
				+2026-08-28-web-connection-recovery-control.zh.md: e45119b272c297a783a650b71743e4f81c1a1565
			
--- a/.agents/notes/implemented/feature/2026-08-28-web-connection-recovery-control.md
+++ b/.agents/notes/implemented/feature/2026-08-28-web-connection-recovery-control.md
@@ -0,0 +1,41 @@
 
				+# Agent Note: Web connection recovery control
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+English | [中文](2026-08-28-web-connection-recovery-control.zh.md)
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+The Web Client automatically rebuilt its Remote event generation and physical WebSocket after a failure, but the page exposed neither the outage nor a user recovery action. Its logical-generation and physical-socket retry loops could also drift: a `retry #N` message could describe another logical generation while the browser still waited on the same physical connection candidate. The Host sent an idle WebSocket Ping only every 30 seconds, and a user could not request a fresh attempt after restoring the Host or network.
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+The Host sends WebSocket Ping control frames every two seconds by default through the existing validated `websocketHeartbeatIntervalMs` configuration. Before each Ping it marks the socket as awaiting Pong; a socket still awaiting Pong at the next interval is terminated. `ConnectionController` is the sole retry scheduler. Online transport failures enter jittered exponential backoff whose cap starts at 500ms, doubles through 1s, 2s, 4s, and 8s, and stops growing at 10s; the actual delay is 50–100% of the cap. The failed retry in the 10s tier ends automatic recovery and publishes `disconnected`. Each physical retry publishes `connecting`, writes one `retry #N` warning, asks Gateway mux to replace any candidate or active socket exactly once, and reopens the internal `$events` stream.
			
 
				+
			
 
				+The Client Connection service exposes the identity-stable `ctx.connection.state` observable and `ctx.connection.reconnect()`. Its snapshot is undefined until the first connection outcome, then carries `disconnected`, `connecting`, or `connected`; equivalent states do not notify. Manual reconnect interrupts the current generation or retry delay, resets the attempt number, and starts retry 1 immediately through the same physical and logical path as automatic recovery. The browser's `offline` event immediately aborts active connection work, publishes `disconnected`, and suspends automatic retries. The next `online` transition publishes `connecting`, resets the attempt number, and starts again at the 500ms backoff tier; duplicate events do not create another loop. A fresh `$events` ready frame, rather than `navigator.onLine`, proves Host connectivity. Logical streams continue to own their baseline, cursor, and replay semantics after the replacement generation.
			
 
				+
			
 
				+The [Web Client architecture](../architecture/2026-07-19-gui-web-client-architecture.md), [Remote event delivery](../architecture/2026-08-10-remote-event-delivery.md), and [Session event transport](../architecture/2026-08-18-session-history-and-event-transport.md) retain their broader ownership decisions; this note supersedes only their former retry timing.
			
 
				+
			
 
				+The Settings shell is a recovery-specific consumer and therefore injects Connection directly; ordinary feature code continues to use `ctx.remote`. Its private hooks compartment binds the state observable and reconnect command. The expanded sidebar renders `ConnectionIndicator` immediately to the right of Settings: `disconnected` is a pale-yellow **Disconnected** action, `connecting` stays yellow while one to three dots advance every 500ms independently of retry timing, and a recovered connection displays pale-green **Connected** for two seconds. Hover or keyboard focus on either yellow state changes only the text to **Reconnect now**; press feedback uses a small warning-color transition, and no native title tooltip is present. Every visible state reserves the widest localized label and uses fixed icon and left-aligned text columns, so state changes do not move or resize the control. Initial startup and uninterrupted healthy operation render nothing.
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**Retry every two seconds without a terminal state.** Rejected because a long outage would create continuous connection traffic. The retained exponential policy retries quickly at first, becomes progressively quieter, and leaves a stable recovery action after the 10s tier fails.
			
 
				+
			
 
				+**Render a full-width `ConnectionBanner` at the top of the viewport.** Rejected because the status belongs beside the recovery action the user named, and a global overlay consumes unrelated page chrome. The primitive is the inline `ConnectionIndicator`; no `ConnectionBanner` compatibility export exists before the first tagged release.
			
 
				+
			
 
				+**Expose lifecycle control through `ctx.remote.$connection`.** Rejected because retry state and commands belong to the Connection service rather than the Remote method namespace. Direct `ctx.connection` use remains exceptional and is appropriate here because the indicator itself controls reconnection.
			
 
				+
			
 
				+**Retry only when the user clicks.** Rejected because recovery must remain automatic when the user is not watching the page; the button resets the backoff and bypasses its current wait.
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+Idle browser connections generate more frequent heartbeat traffic than the former default, while long outages stop generating connection attempts after the capped retry fails. Deployments may override the Host Ping interval. Gateway mux owns no second retry timer, so every `retry #N` warning corresponds to one Controller-requested physical attempt.
			
 
				+
			
 
				+A manual reconnect intentionally disrupts every logical Remote stream sharing the physical socket. Their existing generation supervisors restore state through fresh baselines or cursors, and one-way notifications remain non-replayed.
			
 
				+
			
 
				+The connection state and browser-network input stay in the React-free transport layer. The Settings component receives a framework-bound selector hook and a plain callback, so no UI store duplicates transport state; only the two-second success presentation and 500ms dot animation are presentation-local.
			
 
				+
			
 
				+## Testing
			
 
				+
			
 
				+Connection and Gateway tests pin the two-second heartbeat and Pong deadline, exponential retry limits and logs, browser offline suspension and online reset, manual sequence reset, one socket replacement per requested attempt, state deduplication, listener isolation, and disposal. Component tests pin healthy-state absence, hover/action copy, the independent dot animation, click behavior, and the two-second success state. The assembled Web test drives browser offline/online transitions, failed WebSocket attempts, stable indicator geometry, manual recovery, and the success confirmation through the shipped application.
			
--- a/.agents/notes/implemented/feature/2026-08-28-web-connection-recovery-control.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-28-web-connection-recovery-control.zh.md
@@ -0,0 +1,41 @@
 
				+# Agent Note: Web 连接恢复控件
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+[English](2026-08-28-web-connection-recovery-control.md) | 中文
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+Web Client 会在故障后自动重建 Remote event generation 与物理 WebSocket，但页面既不显示断联，也不提供用户恢复操作。logical generation 与 physical socket 的重试循环还可能错位：`retry #N` 消息可能描述另一个 logical generation，而浏览器仍在等待同一个物理连接候选。Host 每 30 秒才发送一次空闲 WebSocket Ping，用户在恢复 Host 或网络后也无法主动要求一次全新尝试。
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+Host 默认通过既有且经过校验的 `websocketHeartbeatIntervalMs` 配置，每 2 秒发送一次 WebSocket Ping 控制帧。每次 Ping 前，它把 socket 标记为等待 Pong；到下一间隔仍未收到 Pong 的 socket 会被终止。`ConnectionController` 是唯一的 retry 调度器。在线状态下的传输失败进入带抖动的指数退避：上限从 500ms 开始，依次翻倍为 1s、2s、4s、8s，最终封顶 10s；实际延迟是上限的 50%–100%。10s 档的 retry 仍失败后，自动恢复结束并发布 `disconnected`。每次物理 retry 都发布 `connecting`、写一条 `retry #N` warning、要求 Gateway mux 恰好一次替换候选或活动 socket，再重开内部 `$events` stream。
			
 
				+
			
 
				+Client Connection 服务暴露 identity 稳定的 `ctx.connection.state` observable 与 `ctx.connection.reconnect()`。snapshot 在首次连接结果前为 undefined，此后为 `disconnected`、`connecting` 或 `connected`；等价状态不触发通知。手动重连会中断当前 generation 或重试等待、重置 attempt 序号，并通过与自动恢复相同的物理和逻辑路径立即开始 retry 1。浏览器的 `offline` 事件会立即中断活动连接工作、发布 `disconnected` 并暂停自动 retry；下一次 `online` 转换会发布 `connecting`、重置 attempt 序号，并从 500ms 退避档重新开始；重复事件不会创建另一条循环。Host 是否可达由新的 `$events` ready 帧证明，而不是由 `navigator.onLine` 证明。替换 generation 建立后，各 logical stream 仍自行持有 baseline、cursor 与 replay 语义。
			
 
				+
			
 
				+[Web Client 架构](../architecture/2026-07-19-gui-web-client-architecture.zh.md)、[Remote 事件投递](../architecture/2026-08-10-remote-event-delivery.zh.md)和[会话事件传输](../architecture/2026-08-18-session-history-and-event-transport.zh.md)继续持有各自更宽的所有权决策；本笔记只取代其中原有的重试时序。
			
 
				+
			
 
				+Settings 外壳是恢复功能专用消费方，因此直接注入 Connection；普通功能代码仍使用 `ctx.remote`。它的私有 hooks compartment 绑定状态 observable 与重连命令。展开的侧边栏在 Settings 右侧渲染 `ConnectionIndicator`：`disconnected` 是浅黄色的**连接异常**操作；`connecting` 保持黄色，其中一至三个点每 500ms 前进一次，与 retry 时序无关；恢复后则以浅绿色显示**连接成功**并驻留 2 秒。鼠标悬浮或键盘聚焦任一黄色状态时只把文字改为**立即重连**；按压反馈采用轻微的警告色过渡，不使用原生 title tooltip。所有可见状态都为最宽的本地化文字预留空间，并使用固定的图标列和左对齐文字列，因此状态变化不会移动控件或改变其宽度。首次启动和未曾中断的健康连接都不渲染。
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**固定每 2 秒重试且不进入终态。**不采用，因为长时间故障会持续产生连接流量。保留的指数策略先快速重试，再逐步降低频率，并在 10s 档失败后留下稳定的恢复操作。
			
 
				+
			
 
				+**在视口顶部渲染全宽 `ConnectionBanner`。**不采用，因为状态应放在用户指定的恢复操作旁，全局覆盖层还会占用无关页面界面框架。该原语是内联 `ConnectionIndicator`；首次标签发布前不存在 `ConnectionBanner` 兼容导出。
			
 
				+
			
 
				+**通过 `ctx.remote.$connection` 暴露生命周期控制。**不采用，因为 retry 状态与命令属于 Connection 服务，而不是 Remote 方法 namespace。直接使用 `ctx.connection` 仍是例外；本指示器本身负责控制重连，因此符合该例外。
			
 
				+
			
 
				+**仅在用户点击时重试。**不采用，因为用户没有观察页面时仍必须自动恢复；按钮会重置退避并跳过当前等待。
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+空闲浏览器连接的心跳流量会高于原默认值；长时间故障则在封顶档 retry 失败后停止产生连接尝试。部署仍可覆盖 Host Ping 间隔。Gateway mux 不拥有第二个 retry timer，因此每条 `retry #N` warning 都对应一次由 Controller 请求的物理尝试。
			
 
				+
			
 
				+手动重连会刻意中断共享物理 socket 的全部 logical Remote stream。它们既有的 generation supervisor 会通过新 baseline 或 cursor 恢复状态；单向通知仍不重放。
			
 
				+
			
 
				+连接状态与浏览器网络输入都位于 React-free 传输层。Settings 组件只接收框架绑定的 selector hook 与普通回调，因此没有 UI store 复制传输状态；只有 2 秒成功提示和 500ms 点动画属于展示层本地状态。
			
 
				+
			
 
				+## Testing
			
 
				+
			
 
				+Connection 与 Gateway 测试固定 2 秒心跳及 Pong deadline、指数 retry 上限与日志、浏览器离线暂停和在线重置、手动重置序列、每次请求只替换一个 socket、状态去重、listener 隔离与 dispose。组件测试固定健康状态下不显示、悬浮与操作文案、独立点动画、点击行为与 2 秒成功状态。组装 Web 测试通过随附浏览器应用驱动浏览器 offline/online 转换、失败的 WebSocket 尝试、稳定的指示器几何、手动恢复与成功确认。
			
--- a/.agents/notes/implemented/feature/2026-08-28-web-turn-stat-pills.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-28-web-turn-stat-pills.i18n.yaml
@@ -0,0 +1,6 @@
 
				+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				+# side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				+# after editing either side, bring the other along and re-record with:
			
 
				+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-28-web-turn-stat-pills.md
			
 
				+2026-08-28-web-turn-stat-pills.md: 2661c228b9a5a7b55ba3698cf3ee2b4c76701bbc
			
 
				+2026-08-28-web-turn-stat-pills.zh.md: 5cc889b9f743eefeac1343b70743c23392efc908
			
--- a/.agents/notes/implemented/feature/2026-08-28-web-turn-stat-pills.md
+++ b/.agents/notes/implemented/feature/2026-08-28-web-turn-stat-pills.md
@@ -0,0 +1,27 @@
 
				+# Agent Note: Turn-tail stat pills with anchored dialogs
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+English | [中文](2026-08-28-web-turn-stat-pills.zh.md)
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+A completed assistant Turn ended with two stacked footer rows: a `Turn usage` DisclosureRow above the icon actions, and a meta line inside the actions row carrying clock, run time, TTFT, and decode speed as plain text. The disclosure expanded inline and shifted the transcript below it, the meta line mixed audience tiers — casual readers want the clock and run time while token buckets and latency percentiles are diagnostic — and the two-row footprint repeated under every Turn of a long transcript.
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+The tail keeps one `MessageIconActions` row. Two stat pills sit right of the branch action: a database pill labelled with the compact Turn total (`Usage 15.8K tok`) and a clock pill labelled with the wall time (`Ran for 19s`); the message clock stays plain text at the row end. Each pill is an `aria-haspopup="dialog"` trigger that portals a fixed-position dialog to `document.body`, placed above the trigger by `useAnchoredPosition` with a 12px viewport clamp and closed by outside pointerdown or Escape (ContextMeter's pattern). The usage dialog holds the exact total, provider/model routes, cache-hit rate, token buckets, and the reasoning subset inline in Output; the time dialog holds total run time, decode TPS, and the Turn's first-token latency (the first step's TTFT). Facts absent from the fold render no row, and a window without publishable Turn usage renders no usage pill; the token-meter fold and `turn/start` gating are unchanged from [exact per-Turn usage](2026-08-24-web-per-turn-token-usage.md).
			
 
				+
			
 
				+Row visibility follows recency: turn tails and user rows tag `data-actions-reveal`, the latest of each kind stays `always` visible, earlier rows reveal on hover or focus-within under `@media (hover: hover)`, and no-hover devices keep every row visible. Below 480px the pill labels hide and each pill takes the sibling action-button geometry — 28px width, 6px padding, centered glyph, and no adjacent-pill margin rebate — so the bare icons keep the row's 8px rhythm.
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**One flat whole-line trigger.** A TEMPORARY `?usage-variant=flat` switch shipped both layouts to a live A/B session; the flat line exposing TTFT, TPS, and cache hit inline read as plain metadata with a weak click affordance, and its single dialog stacked two unrelated sections. The twin pills won the comparison and the switch, its locale keys, and its tests were deleted.
			
 
				+
			
 
				+**Keep the inline disclosure.** Rejected: expansion shifts the transcript, and the summary row spends a permanent second line on diagnostic data under every Turn.
			
 
				+
			
 
				+**Hover tooltips instead of dialogs.** Rejected: seven facts need a persistent, focusable surface, and hover cannot serve touch devices that the reveal gate already exempts.
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+`TurnUsageDisclosure` and its stylesheet are deleted; `TurnUsagePanel` owns both pills and dialogs, and `ui-chat` gains a `react-dom` dependency for the portal. Every web ARIA golden containing an assistant tail changed mechanically from `text: Ran for …` to a labelled button. Component tests pin trigger copy, dialog content, omission of absent facts, and both close paths; style-contract tests pin the secondary-tier pill typography, the recency gate, and the 480px collapse; the turn-tail e2e drives both dialogs on a recorded session and keeps tok/s and TTFT out of the tail row.
			
--- a/.agents/notes/implemented/feature/2026-08-28-web-turn-stat-pills.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-28-web-turn-stat-pills.zh.md
@@ -0,0 +1,27 @@
 
				+# Agent Note：Turn 尾部统计 pill 与锚定弹层
			
 
				+
			
 
				+状态：已实现
			
 
				+
			
 
				+[English](2026-08-28-web-turn-stat-pills.md) | 中文
			
 
				+
			
 
				+## 问题
			
 
				+
			
 
				+助手 Turn 完成后尾部有上下两行 footer：图标操作行上方的 `本轮用量` DisclosureRow，加上操作行内以纯文字承载时钟、用时、首 token、解码速度的 meta 行。折叠行行内展开会推移下方的对话内容；meta 行混杂了两级受众——普通读者只关心时钟和用时，token 分桶与延迟数据属于诊断信息；长对话里每个 Turn 下都重复这两行占位。
			
 
				+
			
 
				+## 决定
			
 
				+
			
 
				+尾部只保留一行 `MessageIconActions`。分叉操作右侧放两个统计 pill：数据库图标 pill 标注紧凑的本轮总量（`用量 15.8K tok`），时钟图标 pill 标注墙钟用时（`用时 19秒`）；消息时钟保持纯文字置于行尾。每个 pill 是 `aria-haspopup="dialog"` 触发器，把固定定位的弹层 portal 到 `document.body`，由 `useAnchoredPosition` 锚定在触发器上方并保持 12px 视口边距，外部 pointerdown 或 Escape 关闭（沿用 ContextMeter 模式）。用量弹层承载精确总量、提供方/模型路由、缓存命中率、token 分桶及输出内联的推理子集；用时弹层承载本轮总用时、解码 TPS、本轮首 token 用时（取首个 step 的 TTFT）。fold 未产出的事实不渲染行，窗口内无可发布的 Turn 用量则不渲染用量 pill；token-meter fold 与 `turn/start` 门控沿用[精确 per-Turn 用量](2026-08-24-web-per-turn-token-usage.zh.md)，未做改动。
			
 
				+
			
 
				+行可见性按新近度门控：turn 尾行与用户行标记 `data-actions-reveal`，各自最新一行保持 `always` 常显，更早的行在 `@media (hover: hover)` 下 hover 或 focus-within 才显示，无 hover 设备恒显示。480px 以下 pill 隐藏文字并取同排操作按钮的几何——28px 宽、6px 内边距、图标居中、取消相邻 pill 的边距补偿——让裸图标保持行的 8px 节奏。
			
 
				+
			
 
				+## 备选方案
			
 
				+
			
 
				+**整行扁平触发器。** TEMPORARY `?usage-variant=flat` 开关曾把两种布局同时交付真实 A/B 会话；扁平行把首 token、TPS、缓存命中率全部外露，读起来像普通元数据、点击暗示弱，且单一弹层堆叠两段无关内容。双 pill 胜出后，开关、其 locale key 与其测试一并删除。
			
 
				+
			
 
				+**保留行内折叠行。** 否决：展开推移对话内容，且摘要行让诊断数据在每个 Turn 下永久占据第二行。
			
 
				+
			
 
				+**用 hover tooltip 替代弹层。** 否决：七项事实需要可持久、可聚焦的面板，且 hover 无法服务 reveal 门控已豁免的触屏设备。
			
 
				+
			
 
				+## 影响
			
 
				+
			
 
				+`TurnUsageDisclosure` 及其样式表删除；`TurnUsagePanel` 拥有两个 pill 与弹层，`ui-chat` 为 portal 新增 `react-dom` 依赖。所有含助手尾行的 web ARIA golden 由 `text: Ran for …` 机械变为带标签按钮。组件测试钉住触发器文案、弹层内容、缺失事实的省略与两条关闭路径；样式契约测试钉住 pill 的次级字号、新近度门控与 480px 收缩；turn-tail e2e 在录制会话上驱动两个弹层，并确保 tok/s 与 TTFT 不出现在尾行。
			
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
			
 
				-2026-08-10-npm-release-sequences.md: 014bfe3abb2548a369cbfc6a5f11263303e0656a
			
 
				-2026-08-10-npm-release-sequences.zh.md: a67311afd93d3f4f9f0a396237c9ce0b04db0a06
			
 
				+2026-08-10-npm-release-sequences.md: f83bce914bae4cfc5a047bf975b623579dc9156f
			
 
				+2026-08-10-npm-release-sequences.zh.md: c24e5c0a29af2f875136d439ce3fe06577c061b1
			
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
@@ -80,6 +80,12 @@ Every reference to a workspace member uses `workspace:^`, so `pnpm pack` substit
 
				 
			
 
				 `scripts/check-workspace-constraints.ts` requires the protocol, so a new package cannot reintroduce a hand-written range; the invariant-companion rule requires `workspace:^` for `@deepseek-ai/dsh-invariants` for the same reason.
			
 
				 
			
 
				+### Published dependency faces use an explicit policy
			
 
				+
			
 
				+[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) classifies workspace relationships by their published Client and Host use, keeps only Cordis as a peer in covered packages, and applies a small explicit Host roster. [Published dependency faces and bounded peer relays](2026-08-26-published-dependency-faces.md) owns the selection rules and rationale.
			
 
				+
			
 
				+`pnpm run benchmark:npm-resolution` measures this graph manually with the installed npm executable. `pnpm run benchmark:npm-resolution:next` additionally tries each reachable unconfigured Host package and serially remeasures the leading candidates. Both commands use a loopback metadata registry and reject archive requests, so their duration excludes package downloads. Neither command is an aggregate gate because scheduler load and metadata completion order make wall-clock thresholds nondeterministic.
			
 
				+
			
 
				 ### An optional dependency is never loaded at module scope
			
 
				 
			
 
				 A dependency in `optionalDependencies`, or a peer carrying `peerDependenciesMeta.<name>.optional`, may be absent from an installed tree — that absence is the whole promise of "optional". A static import is evaluated when the importing module loads, so one absent package stops being "this capability is unavailable" and becomes a load failure for everything that reaches the importing module. The failure appears only in an installed tree missing that package, and no test here constructs one: a workspace install always has every package, so the unit tests, the snapshots, and the packed-install probe all pass while the published package is broken for the consumer who declined the optional peer.
			
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md
@@ -80,6 +80,12 @@ registry 的两个行为决定了「怎么尝试一次发布」。写入之间
 
				 
			
 
				 `scripts/check-workspace-constraints.ts` 要求这个协议，所以新包无法再引入硬写的范围；同理，invariant companion 规则要求 `@deepseek-ai/dsh-invariants` 用 `workspace:^`。
			
 
				 
			
 
				+### 发布依赖门面使用显式策略
			
 
				+
			
 
				+[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) 按已发布的 Client 与 Host 用法分类 workspace 关系，让受管包只保留 Cordis peer，并应用一份较小的显式 Host 名册。[发布依赖门面与有限 peer 中继](2026-08-26-published-dependency-faces.zh.md)记录选包规则与理由。
			
 
				+
			
 
				+`pnpm run benchmark:npm-resolution` 使用当前安装的 npm 手动测量该依赖图。`pnpm run benchmark:npm-resolution:next` 还会逐个尝试每个可达且未配置的 Host 包，再串行复测领先候选。两个命令都使用回环 metadata registry 并拒绝包归档请求，因此耗时不包含包下载。调度器负载与 metadata 完成顺序会使墙钟阈值失去确定性，所以两个命令都不进入聚合门禁。
			
 
				+
			
 
				 ### optional 依赖绝不在模块作用域被加载
			
 
				 
			
 
				 `optionalDependencies` 里的依赖，或带 `peerDependenciesMeta.<name>.optional` 的 peer，在安装出来的树里可以不存在——这份「可以不存在」正是 optional 的全部承诺。而静态 import 在引入方模块加载时就求值，于是一个缺失的包不再表现为「这个能力不可用」，而是变成所有能走到该模块的代码的加载失败。这种失败只在「缺了该包的安装树」里出现，而本仓没有任何测试构造这种树：workspace 安装总是把每个包都装上，所以单测、快照、打包安装探针全都会过，而那个拒绝了这个 optional peer 的消费者拿到的却是坏的包。
			
--- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml
@@ -0,0 +1,6 @@
 
				+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				+# side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				+# after editing either side, bring the other along and re-record with:
			
 
				+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-26-published-dependency-faces.md
			
 
				+2026-08-26-published-dependency-faces.md: 668d4c721446a87388ae50951156d1b24f91138c
			
 
				+2026-08-26-published-dependency-faces.zh.md: b10a285a81490f8eb66d70d3e73c2f676ad1b35c
			
--- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md
+++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md
@@ -0,0 +1,93 @@
 
				+# Agent Note: Published dependency faces and bounded peer relays
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+English | [中文](2026-08-26-published-dependency-faces.zh.md)
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+A package may contain a browser bundle, a Host entry, shared TypeScript declarations, and Cordis injection metadata. Encoding all of those relationships as required npm peers made the published CLI expensive to install: npm installs peers automatically and repeatedly evaluates placement through deep, converging peer paths. Changing ranges or making the peers optional did not remove that traversal.
			
 
				+
			
 
				+The package that chooses a Client build input is the shipped profile, while a Host value import is loaded by Node from the importing package. Those relationships need different npm sections. Applying one rule to every Host package would reduce the graph but would also create a large migration with no corresponding installation benefit.
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+### Package selection
			
 
				+
			
 
				+[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) owns dependency-section policy. It always covers packages under `packages/client/` and every non-experimental package that declares `dsh.client`. Inside the directory, `dsh.client` marks a Client/Host package whose Host entry is scanned; a package without that declaration is a Client-only static build input. Outside the directory, `dsh.client` selects the same Client/Host scan. A `"./client"` export alone is an API and does not select npm dependency policy.
			
 
				+
			
 
				+[`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) provides explicit Client-face include and exclude lists. An include handles an exceptional package without `dsh.client`, while an exclude removes an automatically discovered dual-face package outside `packages/client/`. The verifier rejects unknown, stale, redundant, duplicate, overlapping, and ineffective entries. The include list is empty; the exclude list contains `@deepseek-ai/dsh-api-session-controller` and `@deepseek-ai/dsh-api-workspace-controller`. Adding Session Controller back would migrate nine more Host edges while its five-run candidate retest improved median resolution by only 0.15 seconds.
			
 
				+
			
 
				+Host-only packages join the same policy through a separate explicit list. The list contains `@deepseek-ai/dsh-llm` and `@deepseek-ai/dsh-session`; source imports do not expand it.
			
 
				+
			
 
				+### Dependency sections
			
 
				+
			
 
				+Every covered package keeps `@deepseek-ai/cordis` in matching `peerDependencies` and `devDependencies`. Cordis is the shared plugin runtime whose identity the application controls.
			
 
				+
			
 
				+A workspace package reached by a runtime value import from the Host entry closure belongs only in `dependencies` when every imported runtime export appears in the policy's `safeHostDependencyExports` table. An export whose constructor identity or module state must be shared appears in `peerRequiredHostExports`; importing one such export keeps the whole package edge in matching `peerDependencies` and `devDependencies`. Each table key is an exact module specifier and each value is a reviewed export set. The verifier follows runtime local imports from the Host entry, records named and default imports and re-exports, and rejects exports present in neither table; namespace, dynamic, and side-effect imports remain unbounded and cannot enter either table.
			
 
				+
			
 
				+Workspace imports used by the Client bundle, type-only imports, module augmentations, `dsh.client.inject`, invariant companions, and existing metadata-only peers belong only in `devDependencies`. Ordinary third-party packages imported by the Host runtime belong in `dependencies`; other third-party relationships keep their declared section. Workspace references use `workspace:^`.
			
 
				+
			
 
				+Some development relationships exist only in `dsh.client.inject` or TypeScript project references. The policy's `configurationOnlyDevDependencies` table names only those reviewed edges and keeps them in `devDependencies`.
			
 
				+
			
 
				+The verifier reads source manifests and source files, so it runs on a clean tree without built `lib/`. Every selected Host face must have `src/index.ts`. An unclassified Host runtime export is a policy violation that blocks all `--fix` writes; a maintainer must review the export and classify it, change the source relationship, or change the package selection. Once source safety passes, `--fix` performs only the section and range changes implied by the classification and removes stale peer metadata.
			
 
				+
			
 
				+### Maintainer workflow
			
 
				+
			
 
				+Run the verifier without `--fix` for a read-only check of package selection, export classifications, dependency sections, workspace ranges, and peer metadata. An unclassified runtime import reports one clickable `path:line:column` diagnostic per imported export.
			
 
				+
			
 
				+```sh
			
 
				+pnpm run verify-package-dependencies
			
 
				+```
			
 
				+
			
 
				+Classify each new Host runtime export in [`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) before generating manifests. `safeHostDependencyExports` permits an ordinary dependency; `peerRequiredHostExports` keeps the whole provider package edge in matching peer and development sections. An export may appear in exactly one table. After refactoring a peer-required export so duplicate package copies are safe, move that exact specifier and export to the safe table; an edge becomes an ordinary dependency only after none of its imported exports remain peer-required.
			
 
				+
			
 
				+Generate the managed manifests and every directly derived artifact with one command. `--fix` writes nothing while a policy violation exists; after success it refreshes `pnpm-lock.yaml`, regenerates both module-graph languages and their pairing record, and prints the ordinary-dependency and peer-required edge lists.
			
 
				+
			
 
				+```sh
			
 
				+pnpm run verify-package-dependencies -- --fix
			
 
				+git diff -- packages pnpm-lock.yaml docs/module-graph.md docs/module-graph.zh.md docs/module-graph.i18n.yaml
			
 
				+```
			
 
				+
			
 
				+Measure the working-tree graph and a Git ref through the local metadata-only registry. Each run creates a fresh consumer and npm cache, replaces inherited npm configuration with explicit peer, hoisting, and registry settings, executes `npm install --package-lock-only`, rejects archive downloads, and leaves the repository unchanged. `--runs` controls repetitions, `--timeout-ms` terminates the npm process tree after its deadline, and optional `--max-ms` makes the command fail when the slowest run exceeds a threshold.
			
 
				+
			
 
				+```sh
			
 
				+pnpm run benchmark:npm-resolution -- --runs=5 --timeout-ms=300000
			
 
				+pnpm run benchmark:npm-resolution -- --ref=origin/master --runs=5 --timeout-ms=300000
			
 
				+```
			
 
				+
			
 
				+Verify package placement through two incompatible synthetic DSH releases. The verifier copies every current DSH manifest into `0.1.0` and `0.2.0`, asks npm for a package lock only, and rejects cross-release DSH resolution, unexpected DSH locations, unequal release inventories, multiple Cordis installations, and package archive requests. The local index contains only installed current-platform metadata, so npm-accepted probes for unavailable optional packages are reported without failing the check.
			
 
				+
			
 
				+```sh
			
 
				+pnpm run verify-npm-install-layout
			
 
				+```
			
 
				+
			
 
				+Rank the next Host package by applying the current policy in memory, measuring a baseline, trying each reachable unconfigured package, and serially retesting the fastest coarse candidates. Positive `gainSeconds` is `baseline median - candidate median`; `--candidates` limits the roster, `--jobs` controls coarse concurrency, and neither phase writes manifests. A selected candidate still requires export classification before it joins `hostPackages`.
			
 
				+
			
 
				+```sh
			
 
				+pnpm run benchmark:npm-resolution:next -- --runs=1 --finalist-runs=5 --finalists=5 --jobs=8 --timeout-ms=120000
			
 
				+```
			
 
				+
			
 
				+### Performance verification
			
 
				+
			
 
				+[`verify-npm-install-layout`](../../../../scripts/verify-npm-install-layout.ts) is a deterministic package-path and version check in the `Release (dsh)` workflow on every pull request and master push; it does not enforce resolver duration. [`benchmark-npm-resolution`](../../../../scripts/benchmark-npm-resolution.ts) and [`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) remain manual because resolver time varies with machine load and metadata completion order. Their fresh-consumer, metadata-only runs isolate npm's dependency-tree calculation from registry latency and archive downloads, so relative results identify peer relays without creating a release-time performance promise.
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**Keep internal relationships as peers.** npm must place and validate each required peer along converging ancestry paths, which recreates the reported install-time failure even when all internal versions are compatible.
			
 
				+
			
 
				+**Use the `"./client"` export as the Client-face roster.** A package may publish Client-facing types or a browser API without contributing a dynamically loaded row. Selecting that package broadens the migration to unrelated Host packages such as Goal, Session Title, and Todo. `dsh.client` identifies dynamic rows, while the `packages/client/` directory independently covers static Client inputs.
			
 
				+
			
 
				+**Flatten every Host package.** This removes more peer work but expands the migration to packages whose individual benchmark result is negligible. The explicit Host list preserves the remaining peer contracts until measurement justifies another entry.
			
 
				+
			
 
				+**Move every Client-related declaration to development-only.** A dual-face package's Host value imports remain real Node loads. Omitting them from the published dependency graph makes the package depend on accidental hoisting by a profile.
			
 
				+
			
 
				+**Enforce a wall-clock threshold in CI.** Resolver time varies with machine load and metadata completion order. Deterministic manifest classification belongs in CI; timing remains a maintainer benchmark.
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+The published dependency graph follows artifact ownership instead of source-directory coupling. Client bundles and shipped profiles provide browser identities, Host modules install duplicate-safe values they load, and Cordis plus explicitly peer-required Host exports retain shared package instances.
			
 
				+
			
 
				+Moving a public type-only relationship to `devDependencies` means a standalone TypeScript consumer must install the referenced type package when it consumes that declaration. The shipped profiles install the complete supported package family; supporting independently assembled TypeScript consumers would require a different policy.
			
 
				+
			
 
				+The explicit overrides, Host list, and export classifications are reviewable decisions. Class constructors used by `instanceof`, symbols, and accessors for module-private registries require peers when their identity or state crosses package boundaries; being a value import alone does not make an export duplicate-safe. Changing a classification changes the installed graph and requires the focused verifier tests, the two-release layout check, and a fresh next-package benchmark. The metadata-only benchmark is diagnostic evidence, not a release-time performance promise.
			
--- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md
+++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md
@@ -0,0 +1,93 @@
 
				+# Agent Note: 发布依赖门面与有限 peer 中继
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+[English](2026-08-26-published-dependency-faces.md) | 中文
			
 
				+
			
 
				+## 问题
			
 
				+
			
 
				+一个包可能同时包含浏览器 bundle、Host 入口、共享 TypeScript 声明和 Cordis 注入元数据。把这些关系全部编码成必需 npm peer 会使已发布 CLI 的安装代价过高：npm 会自动安装 peer，并沿深层、反复汇合的 peer 路径重复执行放置检查。修改版本范围或把 peer 标成 optional 都不会消除这类遍历。
			
 
				+
			
 
				+Client 构建输入由发布 profile 选择，而 Host value import 由导入它的包通过 Node 加载；两者需要不同的 npm 区段。把规则应用到每个 Host 包虽然也能缩小依赖图，却会制造一个没有对应安装收益的大范围迁移。
			
 
				+
			
 
				+## 决策
			
 
				+
			
 
				+### 包选择
			
 
				+
			
 
				+[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) 统一负责依赖区段策略。它始终覆盖 `packages/client/` 下的包，以及声明 `dsh.client` 的每个非实验包。在该目录内，`dsh.client` 标记需要扫描 Host 入口的 Client/Host 包；没有该声明的包是仅供 Client 编译的静态输入。在目录外，`dsh.client` 选择相同的 Client/Host 扫描。仅有 `"./client"` export 只是 API，不参与 npm 依赖策略选包。
			
 
				+
			
 
				+[`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) 提供显式 Client 门面 include 与 exclude 列表。include 用于没有 `dsh.client` 的例外包，exclude 用于移除 `packages/client/` 之外自动发现的双面包。验证器拒绝未知、失效、冗余、重复、相互重叠和无法生效的配置项。include 列表为空；exclude 列表包含 `@deepseek-ai/dsh-api-session-controller` 和 `@deepseek-ai/dsh-api-workspace-controller`。把 Session Controller 加回会多迁移九条 Host 边，而五次候选复测的 resolver 中位数仅改善 0.15 秒。
			
 
				+
			
 
				+Host-only 包通过另一份显式列表加入同一策略。该列表包含 `@deepseek-ai/dsh-llm` 和 `@deepseek-ai/dsh-session`；源码 import 不会自动扩大列表。
			
 
				+
			
 
				+### 依赖区段
			
 
				+
			
 
				+每个受管包都把 `@deepseek-ai/cordis` 保持在范围一致的 `peerDependencies` 和 `devDependencies` 中。Cordis 是由应用控制身份的共享插件运行时。
			
 
				+
			
 
				+Host 入口闭包中的运行期 value import 所到达的 workspace 包，只有在每个运行期导出都列入策略的 `safeHostDependencyExports` 表时才只属于 `dependencies`。constructor 身份或模块状态必须共享的导出列入 `peerRequiredHostExports`；一旦使用这类导出，整条包依赖边就保留在范围一致的 `peerDependencies` 与 `devDependencies` 中。表的每个 key 都是精确 module specifier，每个 value 都是经审查的导出集合。验证器从 Host 入口沿运行期本地 import 扫描，记录具名与默认 import 和 re-export，并拒绝两个表都未收录的导出；namespace、dynamic 和 side-effect import 无法限定导出范围，因此不能进入任一表。
			
 
				+
			
 
				+Client bundle 使用的 workspace import、纯类型 import、模块扩充、`dsh.client.inject`、invariant companion 和仅有元数据的现存 peer 只属于 `devDependencies`。Host 运行时导入的普通第三方包属于 `dependencies`；其他第三方关系保持原区段。Workspace 引用使用 `workspace:^`。
			
 
				+
			
 
				+部分开发期关系只存在于 `dsh.client.inject` 或 TypeScript project reference 中。策略的 `configurationOnlyDevDependencies` 表只列出这些已评审的依赖边，并将它们保留在 `devDependencies` 中。
			
 
				+
			
 
				+验证器读取源码 manifest 和源码文件，因此可以在没有已构建 `lib/` 的干净工作树上运行。每个被选中的 Host face 都必须存在 `src/index.ts`。未分类的 Host 运行期导出属于策略违规，会阻止 `--fix` 的全部写入；维护者必须审查该导出，并选择分类该导出、修改源码关系或修改选包范围。源码安全检查通过后，`--fix` 只执行分类所确定的区段与范围变更，并删除失效的 peer 元数据。
			
 
				+
			
 
				+### 维护流程
			
 
				+
			
 
				+不带 `--fix` 运行验证器，会以只读方式检查选包范围、导出分类、依赖区段、workspace range 与 peer metadata。未分类的运行期 import 会按每个导出分别报告可点击的 `path:line:column` 诊断。
			
 
				+
			
 
				+```sh
			
 
				+pnpm run verify-package-dependencies
			
 
				+```
			
 
				+
			
 
				+生成 manifest 前，在 [`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) 中分类每个新增 Host 运行期导出。`safeHostDependencyExports` 允许普通 dependency；`peerRequiredHostExports` 让整个提供包依赖边保留在范围一致的 peer 与开发区段。一个导出只能出现在一个表中。把 peer-required 导出重构到重复安装安全后，将该精确 specifier 与导出移入 safe 表；只有当一条依赖边的所有 import 都不再使用 peer-required 导出时，它才会成为普通 dependency。
			
 
				+
			
 
				+用一条命令生成受管 manifest 和所有直接派生产物。存在策略违规时，`--fix` 不写任何文件；成功后，它会刷新 `pnpm-lock.yaml`、重新生成中英文 module graph 及其配对记录，并打印普通 dependency 与 peer-required 依赖边。
			
 
				+
			
 
				+```sh
			
 
				+pnpm run verify-package-dependencies -- --fix
			
 
				+git diff -- packages pnpm-lock.yaml docs/module-graph.md docs/module-graph.zh.md docs/module-graph.i18n.yaml
			
 
				+```
			
 
				+
			
 
				+通过仅 metadata 的本地 registry 测量工作树依赖图与 Git ref。每轮都会创建全新 consumer 与 npm cache，用明确的 peer、hoisting 和 registry 设置替换继承的 npm 配置，执行 `npm install --package-lock-only`，拒绝下载包归档，并保持仓库不变。`--runs` 控制重复次数，`--timeout-ms` 会在期限到达后终止 npm 进程树，可选 `--max-ms` 会在最慢一轮超过阈值时让命令失败。
			
 
				+
			
 
				+```sh
			
 
				+pnpm run benchmark:npm-resolution -- --runs=5 --timeout-ms=300000
			
 
				+pnpm run benchmark:npm-resolution -- --ref=origin/master --runs=5 --timeout-ms=300000
			
 
				+```
			
 
				+
			
 
				+通过两个互不兼容的 DSH 合成版本验证包落位。验证器把每份当前 DSH manifest 分别复制为 `0.1.0` 和 `0.2.0`，只要求 npm 生成 package lock，并拒绝跨版本 DSH 解析、非预期 DSH 路径、两套版本清单不一致、多个 Cordis 实例以及包归档请求。本地索引只包含当前平台已安装的 metadata，因此只报告而不拒绝 npm 已接受的不可用可选包探测。
			
 
				+
			
 
				+```sh
			
 
				+pnpm run verify-npm-install-layout
			
 
				+```
			
 
				+
			
 
				+计算下一项 Host 包时，命令会在内存中应用当前策略、测量 baseline、逐个尝试可达且未配置的包，并串行复测粗筛中最快的候选。正数 `gainSeconds` 等于 `baseline median - candidate median`；`--candidates` 限定名册，`--jobs` 控制粗筛并发度，两个阶段都不写 manifest。选中的候选仍需先完成导出分类，才能加入 `hostPackages`。
			
 
				+
			
 
				+```sh
			
 
				+pnpm run benchmark:npm-resolution:next -- --runs=1 --finalist-runs=5 --finalists=5 --jobs=8 --timeout-ms=120000
			
 
				+```
			
 
				+
			
 
				+### 性能验证
			
 
				+
			
 
				+[`verify-npm-install-layout`](../../../../scripts/verify-npm-install-layout.ts) 是 `Release (dsh)` workflow 在每个 pull request 和 master push 上运行的确定性包路径与版本检查；它不限制 resolver 耗时。[`benchmark-npm-resolution`](../../../../scripts/benchmark-npm-resolution.ts) 与 [`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) 保持为手动工具，因为 resolver 耗时会随机器负载和 metadata 完成顺序变化。它们通过全新 consumer 和仅 metadata 的运行，把 npm 依赖树计算与 registry 延迟、包归档下载分离，因此相对结果可以定位 peer 中继，但不构成发布时性能承诺。
			
 
				+
			
 
				+## 考虑过的替代方案
			
 
				+
			
 
				+**把内部关系继续保留为 peer。** npm 必须沿汇合的祖先路径放置并验证每个必需 peer；即使内部版本全部兼容，也会重新产生已报告的安装耗时问题。
			
 
				+
			
 
				+**用 `"./client"` export 作为 Client 门面名册。** 包可能发布 Client 类型或浏览器 API，却不贡献动态装载 row。选中这类包会把迁移扩大到 Goal、Session Title 和 Todo 等无关 Host 包。`dsh.client` 标识动态 row，而 `packages/client/` 目录独立覆盖静态 Client 输入。
			
 
				+
			
 
				+**拍平全部 Host 包。** 这会移除更多 peer 工作，却把迁移扩大到单包 benchmark 收益可忽略的包。显式 Host 列表会保留其余 peer 约束，直到测量结果证明应增加新成员。
			
 
				+
			
 
				+**把所有 Client 相关声明都改为仅开发依赖。** 双面包的 Host value import 仍是实际的 Node 加载；从发布依赖图中删掉它们，会让包依赖 profile 的偶然提升。
			
 
				+
			
 
				+**在 CI 中强制墙钟阈值。** Resolver 耗时会随机器负载和 metadata 完成顺序变化。确定性的 manifest 分类进入 CI，耗时测量保留为维护者 benchmark。
			
 
				+
			
 
				+## 结果
			
 
				+
			
 
				+发布依赖图按产物归属而不是源码目录耦合分类。Client bundle 与发布 profile 提供浏览器运行时身份，Host 模块安装自己加载的可重复实体，而 Cordis 和显式标为 peer-required 的 Host 导出继续共享包实例。
			
 
				+
			
 
				+把公开纯类型关系放进 `devDependencies`，意味着独立 TypeScript 消费者在使用该声明时必须自行安装被引用的类型包。发布 profile 会安装完整的受支持包族；若要支持独立组装的 TypeScript 消费者，需要另一套策略。
			
 
				+
			
 
				+显式 override、Host 列表与导出分类都是需要评审的决策。当 class constructor、symbol 和访问模块私有 registry 的函数跨包传递身份或状态时，它们要求 peer；仅仅属于 value import 并不能证明导出可重复安装。修改分类会改变安装图，因此需要运行聚焦 verifier 测试、双版本布局检查并重新执行 next-package benchmark。仅 metadata benchmark 是诊断证据，不是发布时安装耗时承诺。
			
--- a/.agents/notes/implemented/simplification/2026-08-28-remove-hero-input-glow.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-28-remove-hero-input-glow.i18n.yaml
@@ -0,0 +1,6 @@
 
				+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				+# side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				+# after editing either side, bring the other along and re-record with:
			
 
				+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-28-remove-hero-input-glow.md
			
 
				+2026-08-28-remove-hero-input-glow.md: 929fce91d38ed5436421e91666e91328389a1302
			
 
				+2026-08-28-remove-hero-input-glow.zh.md: e8a32c8dc60feae344be587e4bcc4b8a4f8a2d87
			
--- a/.agents/notes/implemented/simplification/2026-08-28-remove-hero-input-glow.md
+++ b/.agents/notes/implemented/simplification/2026-08-28-remove-hero-input-glow.md
@@ -0,0 +1,29 @@
 
				+# Agent Note: The hero input glow is removed
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+English | [中文](2026-08-28-remove-hero-input-glow.zh.md)
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+The New Session hero painted a decorative backdrop ellipse (`HeroGlow`, figma 313:14109) under the input card: a blurred blue gradient sized `1051/776` of the hero box so its `stdDeviation="50"` blur scaled with the card. On the shipped token sheets the ellipse read as stray blue tint rather than intentional chrome, and its by-construction bleed past the conversation column forced clipping scaffolding onto the column itself.
			
 
				+
			
 
				+That scaffolding existed because a box that scrolls in one axis computes the other axis's initial `visible` to `auto`: the glow's overhang gave `[data-conversation-scroll]` a real 24–95px horizontal scroll range on laptop widths, patched by declaring `overflow-x: hidden` on `.scrollBody` (2026-08-04). This note supersedes and consolidates that bug-fix note.
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+`HeroGlow` is deleted with its positioning scaffolding: the component and its seat in `EmptyHero.tsx`, the glow z-index carve-outs in `ConversationRoot.module.css`, and the `.scrollBody { overflow-x: hidden }` clip, which had no owner other than the glow's bleed. The scroll body's horizontal axis returns to its derived value, and nothing under the column currently bleeds past it.
			
 
				+
			
 
				+The e2e scenario `conversation-column-overflow.e2e.ts` and its golden are deleted with the glow: the test's vacuity guard asserted the glow still bled past the column at narrow stops, so it cannot pass — by design — once nothing bleeds.
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**Keep the glow and retune its color.** Rejected. The tint was not a token mistake to correct; the product read is that the homepage input carries no backdrop chrome at all.
			
 
				+
			
 
				+**Keep `overflow-x: hidden` as a defensive clip.** Rejected. With the glow gone the declaration has no current owner, and the repo requires one; a silent clip would also hide the next accidental bleed instead of surfacing it in review.
			
 
				+
			
 
				+**Keep the overflow test against future bleed.** Rejected. Its vacuity guard requires a presently-bleeding element, so the scenario cannot express "nothing bleeds" without inverting into a different test; the composer geometry golden already pins the scroll body's `overflow` axes per tab.
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+The hero stack is plain chrome above the shared input card, and 67 lines of glow component, seat wiring, and clip scaffolding are gone. The cost is the standing guard: the conversation column is again a one-axis scroller only by construction, so a future decorative element that bleeds past the column will re-derive `overflow-x: auto` and surface a horizontal scrollbar. Whoever reintroduces bleed must restore an explicit one-axis clip on `.scrollBody` and a gesture-level regression test — asserting `scrollWidth === clientWidth` is not a substitute, because a clip hides the range without reflowing it away and only the refused wheel gesture distinguishes the states. The composer tab geometry golden records the current `overflow auto/auto` reading and will flag the derivation flipping back.
			
--- a/.agents/notes/implemented/simplification/2026-08-28-remove-hero-input-glow.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-28-remove-hero-input-glow.zh.md
@@ -0,0 +1,29 @@
 
				+# Agent Note: The hero input glow is removed
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+[English](2026-08-28-remove-hero-input-glow.md) | 中文
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+New Session 首页曾在输入卡片下方绘制一个装饰性背景椭圆(`HeroGlow`,figma 313:14109):一个模糊的蓝色渐变,尺寸为 hero 盒子的 `1051/776`,使其 `stdDeviation="50"` 模糊随卡片缩放。在实际交付的 token 表下,这个椭圆看起来是意外的蓝色沾染而非有意的装饰,并且它按构造就会溢出会话列,迫使列本身背上裁剪脚手架。
			
 
				+
			
 
				+脚手架的由来:单轴滚动的盒子会把另一轴初始的 `visible` 推导为 `auto`,glow 的溢出让 `[data-conversation-scroll]` 在笔记本宽度下出现 24–95px 的真实横向滚动范围,当时(2026-08-04)靠在 `.scrollBody` 上声明 `overflow-x: hidden` 修补。本 note 取代并合并了那个 bug-fix note。
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+`HeroGlow` 连同其定位脚手架一并删除:组件本体及其在 `EmptyHero.tsx` 中的座位、`ConversationRoot.module.css` 中为 glow 开的 z-index 例外,以及 `.scrollBody { overflow-x: hidden }` 裁剪——后者除 glow 的溢出外没有任何持有者。滚动主体的横轴回到推导值,当前列下没有任何元素溢出。
			
 
				+
			
 
				+e2e 场景 `conversation-column-overflow.e2e.ts` 及其 golden 随 glow 一并删除:该测试的空洞防护(vacuity guard)断言 glow 在窄档位仍然溢出列,因此一旦没有任何东西溢出,它按设计就无法通过。
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**保留 glow 只调整颜色。** 拒绝。这不是一个待修正的 token 错误;产品判断是首页输入卡片根本不应携带背景装饰。
			
 
				+
			
 
				+**保留 `overflow-x: hidden` 作为防御性裁剪。** 拒绝。glow 删除后该声明没有当前持有者,而仓库要求每项内容都有;静默裁剪还会把下一次意外溢出藏起来,而不是在评审中暴露它。
			
 
				+
			
 
				+**保留 overflow 测试防范未来溢出。** 拒绝。它的空洞防护要求当下存在一个正在溢出的元素,场景无法在不改写成另一个测试的前提下表达"没有东西溢出";composer 几何 golden 已经按 tab 钉住了滚动主体的 `overflow` 两轴取值。
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+hero 栈成为共享输入卡片上方的朴素装饰,glow 组件、座位接线和裁剪脚手架共 67 行被删除。代价是失去常驻防线:会话列重新只靠构造保持单轴滚动,未来任何溢出列的装饰元素都会重新推导出 `overflow-x: auto` 并出现横向滚动条。重新引入溢出者必须在 `.scrollBody` 上恢复显式单轴裁剪并补上手势级回归测试——断言 `scrollWidth === clientWidth` 不能替代,因为裁剪只是隐藏范围而非将其回流消除,只有被拒绝的滚轮手势能区分两种状态。composer tab 几何 golden 记录了当前 `overflow auto/auto` 的读数,推导翻转回去时会报警。
			
--- a/.agents/notes/implemented/testing/2026-08-24-session-log-snapshot-corpus.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-08-24-session-log-snapshot-corpus.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-08-24-session-log-snapshot-corpus.md
			
 
				-2026-08-24-session-log-snapshot-corpus.md: 328f0346554158d531dbda4b31a28277e37cc6dc
			
 
				-2026-08-24-session-log-snapshot-corpus.zh.md: 374ea2a1939e6e063f348e21fb74642371c345ac
			
 
				+2026-08-24-session-log-snapshot-corpus.md: 8b2f98e0a691e3085ff2286af3183048209f7ab8
			
 
				+2026-08-24-session-log-snapshot-corpus.zh.md: 19952f05c4803d50a6e3c7c987cadd9482d5e87b
			
--- a/.agents/notes/implemented/testing/2026-08-24-session-log-snapshot-corpus.md
+++ b/.agents/notes/implemented/testing/2026-08-24-session-log-snapshot-corpus.md
@@ -18,6 +18,8 @@ This decision supersedes the ACP-specific placement and controller ownership in
 
				 
			
 
				 The recorded session remains the primary input and expected output. Human-originated messages drive the selected public interface, recorded assistant chunks drive deterministic model replay, and the normalized persisted result must equal the fixture. Parent and child sessions share one typed redaction map. Committed fixtures contain relationship-preserving identity tokens and replace request system prompts and tool schemas with tokens; each distinct header class retains one explicit sidecar owner.
			
 
				 
			
 
				+Scenario-owned HTTP fixtures separate the stable authority recorded in the session from their transport listener. Each fixture binds loopback port `0`, lets the operating system allocate and bind the port atomically, and maps the recorded URL or endpoint through the real provider to that listener. Any process-global transport interception matches only the recorded endpoint, is owned by the fixture fiber, and is restored before the listener closes.
			
 
				+
			
 
				 Every existing ACP scenario receives a behavior-preserving destination. Ordinary one-shot behavior uses the headless profile, persistent machine control uses the SDK profile, and only ACP protocol behavior remains ACP-owned. Web scenarios driven by a recorded session join the corpus and retain their ARIA or geometry expected output as secondary evidence. Web and package tests without a recorded-session source keep owner-local expected output and stop using snapshot paths or filenames.
			
 
				 
			
 
				 Workspace inputs remain scenario-local. A mutating scenario compares a complete expected final workspace that record and refresh never rewrite, so a model or tool self-report cannot satisfy the test. Existing intentional session reuse remains an explicit acyclic owner reference; the corpus adds no workspace inheritance or general fixture-merging mechanism.
			
@@ -34,6 +36,10 @@ Workspace inputs remain scenario-local. A mutating scenario compares a complete
 
				 
			
 
				 **Deduplicate workspaces and recorded sessions automatically.** The current workspace duplication is small and intentional locality is easier to review. Only existing semantic session reuse justifies an explicit reference.
			
 
				 
			
 
				+**Bind the recorded URL's numeric port.** A stable listener port keeps transport and transcript values identical, but concurrent snapshot jobs on one host share the network namespace and race for that port.
			
 
				+
			
 
				+**Probe an unused port before launching the scenario.** Releasing a probed port before the child binds it creates a time-of-check/time-of-use race. Binding port `0` inside the owning process keeps allocation and ownership atomic.
			
 
				+
			
 
				 ## Invariants
			
 
				 
			
 
				 - Every existing recorded-session scenario has one passing replacement before its old owner is removed.
			
@@ -43,11 +49,12 @@ Workspace inputs remain scenario-local. A mutating scenario compares a complete
 
				 - Mutating scenarios verify their final workspace externally.
			
 
				 - Owner-local process expectations use `*.expected.e2e.ts` and a separate built-output gate.
			
 
				 - Source and built adapters install replay-only packages in isolated profile fallbacks; distinct prompt-section orders keep their request headers byte-identical.
			
 
				+- Scenario HTTP fixtures bind OS-assigned loopback ports while preserving their recorded model-visible authorities.
			
 
				 - Source and built launch modes, browser replay, SDK projections, packaged Python runtime cases, documentation gates, and repository hygiene pass.
			
 
				 
			
 
				 ## Consequences
			
 
				 
			
 
				-The corpus makes controller ownership visible: ordinary Agent behavior no longer inherits ACP protocol output, SDK and Web projections retain their interface-specific evidence, and only ACP cancellation and permission exchanges remain ACP-owned. Contributors review one normalized session diff plus the sidecars or UI expectations that add independent evidence. Adding a composition requires a manifest class pin; adding a volatile identity requires a typed relationship-preserving redaction rule rather than a broader text scrubber.
			
 
				+The corpus makes controller ownership visible: ordinary Agent behavior no longer inherits ACP protocol output, SDK and Web projections retain their interface-specific evidence, and only ACP cancellation and permission exchanges remain ACP-owned. Contributors review one normalized session diff plus the sidecars or UI expectations that add independent evidence. Adding a composition requires a manifest class pin; adding a volatile identity requires a typed relationship-preserving redaction rule rather than a broader text scrubber. Concurrent jobs can replay network-backed fixtures without reserving repository-wide ports, at the cost of a fixture-local mapping between the recorded authority and its transport listener.
			
 
				 
			
 
				 ## Risks
			
 
				 
			
--- a/.agents/notes/implemented/testing/2026-08-24-session-log-snapshot-corpus.zh.md
+++ b/.agents/notes/implemented/testing/2026-08-24-session-log-snapshot-corpus.zh.md
@@ -18,6 +18,8 @@ Status: implemented
 
				 
			
 
				 录制会话仍是主要输入和预期输出。来自用户的消息驱动所选公开接口，录制的 assistant chunk 驱动确定性模型回放，规范化后的持久化结果必须等于 fixture。父会话和子会话共享同一类型化脱敏映射。提交的 fixture 使用保留关系的身份 token，并将请求 system prompt 和工具 schema 替换为 token；每个不同 header 类仍保留一个显式 sidecar 所有者。
			
 
				 
			
 
				+场景拥有的 HTTP fixture 将会话中录制的稳定 authority 与传输 listener 分离。每个 fixture 在回环地址上绑定端口 `0`，由操作系统以一次原子操作分配并绑定端口，再将录制的 URL 或 endpoint 通过真实 provider 映射到该 listener。任何进程全局传输拦截只匹配录制 endpoint，由 fixture fiber 拥有，并在关闭 listener 前恢复。
			
 
				+
			
 
				 每个现有 ACP 场景都获得一个保留行为的目标。普通单次行为使用 headless profile，需要持久机器控制的行为使用 SDK profile，只有 ACP 协议行为继续归 ACP 所有。由录制会话驱动的 Web 场景加入该语料，并保留其 ARIA 或几何预期输出作为辅助证据。没有录制会话来源的 Web 和包级测试保留归属方本地的预期输出，并停止使用快照路径或文件名。
			
 
				 
			
 
				 Workspace 输入继续归各场景本地所有。变更文件的场景比较完整的预期最终 workspace，record 与 refresh 绝不改写该预期，因此模型或工具的自报结果无法满足测试。现有的有意会话复用继续使用显式、无环的所有者引用；语料不增加 workspace 继承或通用 fixture 合并机制。
			
@@ -34,6 +36,10 @@ Workspace 输入继续归各场景本地所有。变更文件的场景比较完
 
				 
			
 
				 **自动去重 workspace 和录制会话。** 当前 workspace 重复很少，有意保持本地性更易审查。只有现有的语义会话复用值得显式引用。
			
 
				 
			
 
				+**直接绑定录制 URL 的数值端口。** 稳定 listener 端口使传输值与 transcript 值一致，但同一主机上的并发快照 job 共享网络命名空间，会争用该端口。
			
 
				+
			
 
				+**在启动场景前探测未使用端口。** 子进程绑定前释放已探测端口会产生检查时间与使用时间竞态。在拥有该端口的进程内绑定端口 `0`，可使分配与所有权保持原子性。
			
 
				+
			
 
				 ## Invariants
			
 
				 
			
 
				 - 每个现有录制会话场景都在移除旧所有者之前拥有一个通过的替代场景。
			
@@ -43,11 +49,12 @@ Workspace 输入继续归各场景本地所有。变更文件的场景比较完
 
				 - 变更内容的场景从外部验证最终 workspace。
			
 
				 - 所属位置的进程预期使用 `*.expected.e2e.ts`，并由单独的构建产物门禁运行。
			
 
				 - 源码与构建适配器在隔离的 profile fallback 中安装仅回放包；不同的提示词 section 顺序值使两种模式的请求 header 保持字节一致。
			
 
				+- 场景 HTTP fixture 绑定由操作系统分配的回环端口，同时保留录制的模型可见 authority。
			
 
				 - 源码和构建启动模式、浏览器回放、SDK 投影、打包 Python 运行时场景、文档门禁和仓库卫生检查通过。
			
 
				 
			
 
				 ## Consequences
			
 
				 
			
 
				-该语料让控制器所有权可见：普通 Agent 行为不再继承 ACP 协议输出，SDK 和 Web 投影保留各自接口专有的证据，只有 ACP 取消与权限交换仍归 ACP 所有。贡献者审查一份规范化会话差异，以及提供独立证据的 sidecar 或 UI 预期。新增组合必须提供 manifest 类别 pin；新增易变身份必须添加保留关系的带类型脱敏规则，而不是扩大文本清洗范围。
			
 
				+该语料让控制器所有权可见：普通 Agent 行为不再继承 ACP 协议输出，SDK 和 Web 投影保留各自接口专有的证据，只有 ACP 取消与权限交换仍归 ACP 所有。贡献者审查一份规范化会话差异，以及提供独立证据的 sidecar 或 UI 预期。新增组合必须提供 manifest 类别 pin；新增易变身份必须添加保留关系的带类型脱敏规则，而不是扩大文本清洗范围。并发 job 可以回放依赖网络的 fixture，而无需预留仓库级端口，代价是 fixture 内需要维护录制 authority 与传输 listener 的映射。
			
 
				 
			
 
				 ## Risks
			
 
				 
			
--- a/.agents/notes/implemented/testing/2026-08-27-translation-pairing-merge-budget.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-08-27-translation-pairing-merge-budget.i18n.yaml
@@ -0,0 +1,6 @@
 
				+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				+# side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				+# after editing either side, bring the other along and re-record with:
			
 
				+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-08-27-translation-pairing-merge-budget.md
			
 
				+2026-08-27-translation-pairing-merge-budget.md: 296e71fbbebf136602e02d2d8d64dbbfd8a336a3
			
 
				+2026-08-27-translation-pairing-merge-budget.zh.md: 8bdac5902301d7105b7851e3c446a9a327b69819
			
--- a/.agents/notes/implemented/testing/2026-08-27-translation-pairing-merge-budget.md
+++ b/.agents/notes/implemented/testing/2026-08-27-translation-pairing-merge-budget.md
@@ -0,0 +1,31 @@
 
				+# Agent Note: Coverage-lane budget for the translation-pairing-merge suite
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+English | [中文](2026-08-27-translation-pairing-merge-budget.zh.md)
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+[`scripts/translation-pairing-merge.spec.ts`](../../../../scripts/translation-pairing-merge.spec.ts) took a `describe`-level `{ timeout: 15_000 }`. All 23 of its cases inherit that value; none carries an allowance of its own.
			
 
				+
			
 
				+Every case builds a scratch repository and drives it through spawned `git` invocations, so the suite is bound by process creation rather than by its assertions. On the self-hosted Windows runners all instances share one volume, and process creation there shows occasional multi-second spikes rather than a uniform slowdown. Under that contention this suite has been observed reporting `Test timed out in 15000ms` on a branch that did not touch the file, so the budget rather than the change under test decided the outcome.
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+The suite takes `{ timeout: 90_000 }`, matching `DSH_COVERAGE_TEST_TIMEOUT_MS` in [`.github/workflows/ci.yml`](../../../../.github/workflows/ci.yml), which the Windows coverage lane passes as `--testTimeout`.
			
 
				+
			
 
				+A `describe` value takes precedence over that flag rather than deferring to it. A smaller one therefore lowers what the lane already grants, and because no case here carries its own allowance, every one of the 23 was capped at 15 s while the lane offered 90 s.
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+The suite tolerates a multi-second `git` spawn spike on the shared-volume runners and defers to the budget the coverage lane provides. The value is not a measurement of how long these cases need: the slowest three complete in roughly 0.7-1.2 s depending on the host, and raising the ceiling does not slow a passing run.
			
 
				+
			
 
				+A raised ceiling does not weaken the assertions: with the budget raised sixfold a suite still fails through its own assertions rather than through a timeout, because the ceiling only decides when waiting stops. It does widen what counts as acceptable duration, so a real slowdown from a few hundred milliseconds to tens of seconds now passes where the previous 15 s would have caught it. That detection is traded away deliberately: the 15 s ceiling was firing on contention rather than on regressions, so what it caught was the shared volume, not the code.
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**Raise `testTimeout` for the whole unit lane.** That would change every suite in the repository to fix one whose cost is specific to spawning `git`.
			
 
				+
			
 
				+**Give each case its own allowance.** Twenty-three separate values restate one property of the machine, and a later case added without one would silently inherit the lower ceiling again.
			
 
				+
			
 
				+**Leave the value and retry on failure.** A retry moves the failure to another case or another run and leaves a red gate that carries no information about the code under test.
			
--- a/.agents/notes/implemented/testing/2026-08-27-translation-pairing-merge-budget.zh.md
+++ b/.agents/notes/implemented/testing/2026-08-27-translation-pairing-merge-budget.zh.md
@@ -0,0 +1,31 @@
 
				+# Agent Note: translation-pairing-merge 套件的 coverage lane 预算
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+[English](2026-08-27-translation-pairing-merge-budget.md) | 中文
			
 
				+
			
 
				+## 问题
			
 
				+
			
 
				+[`scripts/translation-pairing-merge.spec.ts`](../../../../scripts/translation-pairing-merge.spec.ts) 在 `describe` 层加了 `{ timeout: 15_000 }`。它的 23 个用例全部继承这个值，没有任何一个自带余量。
			
 
				+
			
 
				+每个用例都会建一个临时仓库并通过 spawn 的 `git` 驱动它，因此这个套件受进程创建约束，而不是受它的断言约束。在自托管 Windows runner 上所有实例共用一个卷，而那里的进程创建表现为偶发的数秒尖峰，不是均匀变慢。在那种争抢下，这个套件曾在一个没有改动该文件的分支上报出 `Test timed out in 15000ms`，也就是说决定结果的是预算而不是被测改动。
			
 
				+
			
 
				+## 决定
			
 
				+
			
 
				+套件取 `{ timeout: 90_000 }`，与 [`.github/workflows/ci.yml`](../../../../.github/workflows/ci.yml) 里的 `DSH_COVERAGE_TEST_TIMEOUT_MS` 一致，Windows 覆盖率 lane 把它作为 `--testTimeout` 传入。
			
 
				+
			
 
				+`describe` 层的取值优先于那个 flag，而不是让位于它。所以更小的值会压低 lane 已经给出的预算；又因为这里没有任何用例自带余量，23 个用例全部被限制在 15 秒，而 lane 提供的是 90 秒。
			
 
				+
			
 
				+## 后果
			
 
				+
			
 
				+套件能容忍共享卷 runner 上一次数秒的 `git` spawn 尖峰，并让位于 coverage lane 提供的预算。这个值不是对「这些用例需要多久」的测量：最慢的三个用例视主机而定约为 0.7–1.2 秒，而抬高上限不会让一次通过的运行变慢。
			
 
				+
			
 
				+抬高上限不会削弱断言：把预算抬到六倍之后，套件仍然通过它自己的断言失败而不是通过超时失败，因为上限只决定何时停止等待。但它确实放宽了「多长算可接受」——一个从几百毫秒退化到几十秒的真实变慢现在会通过，而此前的 15 秒会拦住它。这项检测能力是有意换掉的：15 秒上限触发的是争抢而不是回归，所以它拦住的是共享卷，不是代码。
			
 
				+
			
 
				+## 备选方案
			
 
				+
			
 
				+**给整个 unit lane 抬高 `testTimeout`。** 那会为了修一个成本特定于 spawn `git` 的套件而改变仓库里的每一个套件。
			
 
				+
			
 
				+**给每个用例各自加余量。** 23 个分散的取值重复表达同一个机器属性，而后续新增的用例若没写，又会静默继承较低的上限。
			
 
				+
			
 
				+**保留取值、失败时重跑。** 重跑只是把失败挪到另一个用例或另一次运行，同时留下一个不携带被测代码信息的红灯。
			
--- a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.i18n.yaml
@@ -0,0 +1,6 @@
 
				+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				+# side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				+# after editing either side, bring the other along and re-record with:
			
 
				+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.md
			
 
				+2026-08-28-ci-test-reliability-skill.md: 1c8e0389dfa6e3eb3a6e04e994e6400d19a673ac
			
 
				+2026-08-28-ci-test-reliability-skill.zh.md: ef36eab497bee874cd117488ddf4895c7edd0ed1
			
--- a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.md
+++ b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.md
@@ -0,0 +1,43 @@
 
				+# Agent Note: CI test reliability skill
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+English | [中文](2026-08-28-ci-test-reliability-skill.zh.md)
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+DeepSeek Harness runs tests across concurrent Vitest files, worker processes, repository gates, and Actions jobs. Process isolation does not isolate host ports, predictable paths, external namespaces, or inherited children, while process-global mutations and incomplete teardown can contaminate later tests. A test can select the correct tier and still pass only when it runs alone.
			
 
				+
			
 
				+The testing policy owns test tiers, defensive patterns own runtime lifecycle rules, pre-push guidance selects commands, and code review evaluates completed diffs. None of them gives an agent a focused workflow for designing resource-owning tests against the real CI topology or classifying an existing probabilistic failure before changing code.
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+[dsh-ci-test-reliability](../../../skills/dsh-ci-test-reliability/SKILL.md) owns test isolation and CI-flake diagnosis guidance. It applies when tests or fixtures acquire host resources, mutate process-global state, depend on asynchronous readiness, own subprocesses or network listeners, or exhibit probabilistic CI failures.
			
 
				+
			
 
				+The skill requires agents to model concurrency beyond one Vitest process, allocate live resources atomically, separate stable fixture identities from ephemeral transport addresses, synchronize on observable state, restore global mutations exactly, and await teardown to quiescence. Regression evidence matches the owned risk: negative controls for guards, deterministic barriers for races, concurrent independent processes for host-resource isolation, and external observations instead of component self-reports.
			
 
				+
			
 
				+Two rules cover the failures the repository has actually paid for. A value the operating system owns is not guaranteed to return as written, so a test may write one back only where the assertion tolerates that write-back failing; where the assertion depends on it, the expected value comes from a fresh read. And a suite timeout overrides the runner flag rather than yielding to it, so a suite bound by process creation takes the lane budget, raises the hook budget with it, and keeps an outer wait far larger than any timeout under test. Restoring a granted budget or sizing a bounded retry to measured contention is therefore not a masking fix.
			
 
				+
			
 
				+The diagnosis-only workflow lives in a separate reference so ordinary authoring does not load Actions triage procedure. It compares passing and failing evidence before classifying host collisions, incomplete lifecycle, global contamination, load-sensitive synchronization, platform or entry-path failures, product races, provider transience, or runner infrastructure.
			
 
				+
			
 
				+[dsh-pre-push-checks](../../../skills/dsh-pre-push-checks/SKILL.md) conditionally consults the reliability skill before selecting commands, while [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) applies it when reviewing risky tests. Command selection and general PR review remain with those existing skills.
			
 
				+
			
 
				+This decision partially overlaps the [deterministic and stress testing proposal](../../proposed/testing/2026-06-11-deterministic-and-stress-testing.md). The skill ships authoring and diagnosis guidance; it does not implement that proposal's lint rule, universal replay fixture, or nightly stress job, so the proposal remains active.
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**Expand dsh-pre-push-checks.** Pre-push guidance runs after test design and owns evidence selection. Making it also own resource allocation, synchronization, teardown, and CI diagnosis would mix two different decisions and load reliability procedure for ordinary pushes.
			
 
				+
			
 
				+**Expand dsh-code-review.** Review guidance can detect unreliable tests after a diff exists, but it cannot guide the agent while the fixture is being designed or while a failure is being diagnosed without a PR.
			
 
				+
			
 
				+**Put the complete workflow in the standing testing policy.** The testing policy must remain the concise authority for tiers and placement. Loading detailed Actions diagnosis and resource-specific procedure for every test task would duplicate situational guidance and make that policy harder to scan.
			
 
				+
			
 
				+**Add a generic stress runner or regex gate immediately.** Repeated green runs do not prove a race is controlled, and literal ports, paths, sleeps, and URLs can be valid parser inputs or expected values. A later high-signal defect class can justify a narrow executed check without making broad textual matches policy.
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+Agents receive the reliability rules while designing or diagnosing the tests that need them, and pre-push and review workflows share the same criteria without duplicating the procedure. Pure deterministic tests continue to use the normal focused evidence path.
			
 
				+
			
 
				+The skill is advisory, so it cannot mechanically prevent every resource collision. A repeated, statically identifiable defect can still justify an executed repository check. The repository also retains one additional active Skill and reference whose links and statements must remain current with the actual CI topology.
			
 
				+
			
 
				+The existing deterministic-and-stress proposal remains open, and this change does not audit or rewrite the current test corpus.
			
--- a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md
+++ b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md
@@ -0,0 +1,43 @@
 
				+# Agent Note: CI 测试可靠性 Skill
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+[English](2026-08-28-ci-test-reliability-skill.md) | 中文
			
 
				+
			
 
				+## 问题
			
 
				+
			
 
				+DeepSeek Harness 会在并发的 Vitest 文件、worker 进程、仓库 gate 与 Actions job 中运行测试。进程隔离不会隔离宿主机端口、可预测路径、外部命名空间或继承的子进程，而进程全局状态变更与未完成的 teardown 可能污染后续测试。即使测试选择了正确层级，也可能只在独占运行时通过。
			
 
				+
			
 
				+测试政策负责测试层级，防御性模式负责运行时生命周期规则，pre-push 指引负责选择命令，代码 review 负责检查已完成的 diff。它们都没有为 agent 提供一个聚焦流程，用于按照真实 CI 拓扑设计会占用资源的测试，或在修改代码前对已有概率性失败进行分类。
			
 
				+
			
 
				+## 决策
			
 
				+
			
 
				+[dsh-ci-test-reliability](../../../skills/dsh-ci-test-reliability/SKILL.md) 负责测试隔离与 CI 概率性失败诊断指引。测试或 fixture 占用宿主机资源、修改进程全局状态、依赖异步就绪、持有子进程或网络 listener，或出现概率性 CI 失败时，使用该 Skill。
			
 
				+
			
 
				+该 Skill 要求 agent 建模单个 Vitest 进程之外的并发，原子分配实时资源，把稳定 fixture 标识与临时传输地址分开，按可观察状态同步，精确恢复全局变更，并等待 teardown 达到静止状态。回归证据与所持有的风险匹配：guard 使用负向控制，竞态使用确定性 barrier，宿主机资源隔离使用并发独立进程，并以外部观察代替组件自述。
			
 
				+
			
 
				+另有两条规则覆盖仓库已经付出过代价的失败。操作系统拥有的值不保证按写入的样子返回，因此只有在断言容忍写回失败时，测试才可以把它写回去；断言依赖写回成功时，期望值取自重新读取。以及套件级 timeout 覆盖而不是让位于 runner 的 flag，因此受进程创建约束的套件取 lane 预算、连同 hook 预算一起抬高，并让外层等待远大于任何被测超时。据此，恢复已被授予的预算、或按实测争抢标定一个有界重试，都不属于掩盖式修复。
			
 
				+
			
 
				+仅用于诊断的流程放在单独 reference 中，因此普通编写任务不会加载 Actions 分诊步骤。它会先比较成功与失败证据，再对宿主机冲突、未完成生命周期、全局状态污染、负载敏感同步、平台或入口路径失败、产品竞态、provider 瞬时故障或 runner 基础设施进行分类。
			
 
				+
			
 
				+[dsh-pre-push-checks](../../../skills/dsh-pre-push-checks/SKILL.md) 在选择命令前按条件引用可靠性 Skill，[dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 则在 review 高风险测试时应用它。命令选择与通用 PR review 仍由这些现有 Skill 负责。
			
 
				+
			
 
				+该决策与[确定性与压力测试提案](../../proposed/testing/2026-06-11-deterministic-and-stress-testing.zh.md)部分重合。该 Skill 交付测试编写与诊断指引，但没有实现提案中的 lint 规则、通用回放 fixture 或 nightly stress job，因此提案保持活跃。
			
 
				+
			
 
				+## 考虑过的替代方案
			
 
				+
			
 
				+**扩展 dsh-pre-push-checks。** Pre-push 指引在测试设计之后运行，负责选择证据。如果它还负责资源分配、同步、teardown 与 CI 诊断，就会混合两种不同决策，并让普通 push 也加载可靠性流程。
			
 
				+
			
 
				+**扩展 dsh-code-review。** Review 指引可以在 diff 已存在后发现不可靠测试，但无法在 fixture 设计过程中指导 agent，也无法在没有 PR 时指导故障诊断。
			
 
				+
			
 
				+**把完整流程放入常驻测试政策。** 测试政策需要保持为测试层级与放置规则的简洁权威来源。让每个测试任务都加载详细 Actions 诊断与资源专项流程，会重复情境性指引，也会降低政策的可扫描性。
			
 
				+
			
 
				+**立即增加通用 stress runner 或正则 gate。** 重复运行保持绿色不能证明竞态已受控，而字面端口、路径、sleep 与 URL 可能是合法的 parser 输入或期望值。未来若出现高信号缺陷类型，可以增加窄范围的可执行检查，而不必把宽泛文本匹配当成政策。
			
 
				+
			
 
				+## 后果
			
 
				+
			
 
				+Agent 在设计或诊断确实需要这些规则的测试时获得可靠性指引，pre-push 与 review 流程也能共用同一套标准而不复制步骤。纯确定性测试继续采用普通的聚焦证据路径。
			
 
				+
			
 
				+该 Skill 属于指导性规则，无法机械阻止所有资源冲突。如果某种缺陷反复出现且能被静态识别，仍可增加可执行的仓库检查。仓库也会多维护一个活跃 Skill 与 reference，其链接和陈述必须与真实 CI 拓扑保持一致。
			
 
				+
			
 
				+现有确定性与压力测试提案继续开放，本变更也不会审计或重写当前测试语料库。
			
--- a/.agents/notes/implemented/testing/2026-08-29-windows-lane-hook-and-lefthook-budget.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-08-29-windows-lane-hook-and-lefthook-budget.i18n.yaml
@@ -0,0 +1,6 @@
 
				+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				+# side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				+# after editing either side, bring the other along and re-record with:
			
 
				+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-08-29-windows-lane-hook-and-lefthook-budget.md
			
 
				+2026-08-29-windows-lane-hook-and-lefthook-budget.md: 6886e3ad4958d20a88a66df6a9e02f5a60a36a6a
			
 
				+2026-08-29-windows-lane-hook-and-lefthook-budget.zh.md: 56c1e625d92f01e24f2268deb5d03040278da6af
			
--- a/.agents/notes/implemented/testing/2026-08-29-windows-lane-hook-and-lefthook-budget.md
+++ b/.agents/notes/implemented/testing/2026-08-29-windows-lane-hook-and-lefthook-budget.md
@@ -0,0 +1,35 @@
 
				+# Agent Note: Hook budget and Lefthook suite budget on the Windows coverage lane
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+English | [中文](2026-08-29-windows-lane-hook-and-lefthook-budget.zh.md)
			
 
				+
			
 
				+## Problem
			
 
				+
			
 
				+Two facts kept the Windows coverage lane failing on branches that touched neither the suite nor the gate.
			
 
				+
			
 
				+[`scripts/install-lefthook.spec.ts`](../../../../scripts/install-lefthook.spec.ts) took a `describe`-level `{ timeout: 30_000 }`, restated as a `MULTI_PROCESS_TEST_TIMEOUT_MS` constant on five of its cases. Every case builds scratch worktrees and drives them through spawned Git and Node subprocesses, so the suite is bound by process creation rather than by its assertions. On an idle macOS host its slowest case costs 7.5 s, so the ceiling carried roughly fourfold headroom — where the [translation-pairing-merge suite](2026-08-27-translation-pairing-merge-budget.md) fired at 15 s with more than tenfold. Under the self-hosted Windows runners' multi-second process-creation spikes this suite has been observed reporting `Test timed out in 30000ms` on branches that did not touch it, and the two cases observed failing are its slowest and its seventh-slowest.
			
 
				+
			
 
				+Separately, `coverageTestTimeoutArgs` in [`scripts/coverage-partitions.ts`](../../../../scripts/coverage-partitions.ts) raised `--testTimeout` and `--expect.poll.timeout` from `DSH_COVERAGE_TEST_TIMEOUT_MS` but left `--hookTimeout` at Vitest's separate 10 s default. Setup and teardown pay the same contention the raised test budget accounts for: [`removeFixtureSafely`](../../../../scripts/test-fixture-cleanup.ts) retries Windows handle release across a documented 10-second window, so an `afterEach` that exercises that window meets the hook default exactly. Raising only the test budget moves a contended suite's failure from the case to its teardown rather than removing it.
			
 
				+
			
 
				+## Decision
			
 
				+
			
 
				+The Lefthook suite takes `{ timeout: 90_000 }`, matching `DSH_COVERAGE_TEST_TIMEOUT_MS` in [`.github/workflows/ci.yml`](../../../../.github/workflows/ci.yml). The per-case constant is deleted rather than raised: it restated the `describe` value, and the translation-pairing-merge note already rejected per-case allowances because a later case added without one silently inherits a different ceiling.
			
 
				+
			
 
				+`coverageTestTimeoutArgs` emits `--hookTimeout` beside the other two arguments. One environment variable governs one budget for the work a contended lane must finish, whether that work sits in a case or in its setup and teardown.
			
 
				+
			
 
				+## Consequences
			
 
				+
			
 
				+A `git` or `node` spawn spike on the shared-volume runners no longer decides either suite's outcome, and a slow fixture teardown no longer fails a suite whose cases all passed. Neither value measures how long the work needs: the Lefthook suite's slowest case completes in about 7.5 s on an idle host, and a raised ceiling does not slow a passing run.
			
 
				+
			
 
				+Both budgets widen what counts as an acceptable duration, so a real slowdown into tens of seconds now passes where the previous ceilings would have caught it. That detection is traded away deliberately: those ceilings were firing on host contention rather than on regressions.
			
 
				+
			
 
				+The hook change applies wherever `DSH_COVERAGE_TEST_TIMEOUT_MS` is set, which today is the Windows coverage lane alone. Lanes that leave it unset keep every Vitest default, including the 10 s hook budget.
			
 
				+
			
 
				+## Alternatives considered
			
 
				+
			
 
				+**Give `--hookTimeout` its own environment variable.** Two knobs would describe one property of the host, and a lane that raised one without the other would reproduce this failure in the other direction.
			
 
				+
			
 
				+**Shorten the `removeFixtureSafely` retry window instead.** That trades a cleanup failure for temp residue on the shared self-hosted `/tmp`, which has twice exhausted the host's inode capacity.
			
 
				+
			
 
				+**Raise only the Lefthook suite and leave the hook default.** The suite's `afterEach` is exactly where its Windows `EPERM` cleanup failures appear, so the raised case budget would have surfaced the same run as a hook timeout.
			
--- a/.agents/notes/implemented/testing/2026-08-29-windows-lane-hook-and-lefthook-budget.zh.md
+++ b/.agents/notes/implemented/testing/2026-08-29-windows-lane-hook-and-lefthook-budget.zh.md
@@ -0,0 +1,35 @@
 
				+# Agent Note: Windows 覆盖率 lane 的 hook 预算与 Lefthook 套件预算
			
 
				+
			
 
				+Status: implemented
			
 
				+
			
 
				+[English](2026-08-29-windows-lane-hook-and-lefthook-budget.md) | 中文
			
 
				+
			
 
				+## 问题
			
 
				+
			
 
				+两件事让 Windows 覆盖率 lane 在既没碰套件、也没碰 gate 的分支上持续失败。
			
 
				+
			
 
				+[`scripts/install-lefthook.spec.ts`](../../../../scripts/install-lefthook.spec.ts) 在 `describe` 层取 `{ timeout: 30_000 }`，并以 `MULTI_PROCESS_TEST_TIMEOUT_MS` 常量的形式在其中五个用例上重复了同一个值。每个用例都会建临时 worktree 并通过 spawn 的 Git 与 Node 子进程驱动它，因此这个套件受进程创建约束，而不是受它的断言约束。在空闲的 macOS 主机上，它最慢的用例耗时 7.5 秒，也就是说这个上限只有约四倍余量——而 [translation-pairing-merge 套件](2026-08-27-translation-pairing-merge-budget.zh.md)在十倍以上余量的 15 秒上限下仍然触发。在自托管 Windows runner 数秒级的进程创建尖峰下，这个套件曾在没有改动它的分支上报出 `Test timed out in 30000ms`，而被观察到失败的两个用例正是它最慢的那个和第七慢的那个。
			
 
				+
			
 
				+另一件事是 [`scripts/coverage-partitions.ts`](../../../../scripts/coverage-partitions.ts) 里的 `coverageTestTimeoutArgs`：它用 `DSH_COVERAGE_TEST_TIMEOUT_MS` 抬高了 `--testTimeout` 和 `--expect.poll.timeout`，却把 `--hookTimeout` 留在 Vitest 独立的 10 秒默认值上。setup 与 teardown 承受的是被抬高的测试预算所针对的同一种争抢：[`removeFixtureSafely`](../../../../scripts/test-fixture-cleanup.ts) 会在一个注释写明的 10 秒窗口内重试 Windows 句柄释放，因此一个真正用满该窗口的 `afterEach` 恰好撞上 hook 默认值。只抬高测试预算，只是把一个受争抢套件的失败从用例挪到它的 teardown，而不是消除它。
			
 
				+
			
 
				+## 决定
			
 
				+
			
 
				+Lefthook 套件取 `{ timeout: 90_000 }`，与 [`.github/workflows/ci.yml`](../../../../.github/workflows/ci.yml) 里的 `DSH_COVERAGE_TEST_TIMEOUT_MS` 一致。逐用例常量被删除而不是被抬高：它只是重述了 `describe` 的取值，而 translation-pairing-merge 的 note 已经否决过逐用例余量——后续新增的用例若不带余量，就会静默继承另一个上限。
			
 
				+
			
 
				+`coverageTestTimeoutArgs` 在原有两个参数旁边发出 `--hookTimeout`。一个环境变量管一份预算，覆盖受争抢的 lane 必须完成的工作，无论这份工作位于用例内还是位于它的 setup 与 teardown。
			
 
				+
			
 
				+## 后果
			
 
				+
			
 
				+共享卷 runner 上一次 `git` 或 `node` 的 spawn 尖峰不再决定这两个套件的结果，一次缓慢的 fixture teardown 也不再让一个用例全部通过的套件失败。两个取值都不是对「需要多久」的测量：Lefthook 套件最慢的用例在空闲主机上约 7.5 秒，而抬高上限不会让一次通过的运行变慢。
			
 
				+
			
 
				+两份预算都放宽了「多长算可接受」，因此一个退化到几十秒的真实变慢现在会通过，而此前的上限会拦住它。这项检测能力是有意换掉的：那些上限触发的是宿主机争抢，不是回归。
			
 
				+
			
 
				+hook 的改动在所有设置了 `DSH_COVERAGE_TEST_TIMEOUT_MS` 的地方生效，目前仅 Windows 覆盖率 lane 一处。不设置它的 lane 保持全部 Vitest 默认值，包括 10 秒的 hook 预算。
			
 
				+
			
 
				+## 备选方案
			
 
				+
			
 
				+**给 `--hookTimeout` 单独一个环境变量。**两个旋钮描述宿主机的同一个属性，而只抬高其中一个的 lane 会以相反的方向复现同一个失败。
			
 
				+
			
 
				+**改为缩短 `removeFixtureSafely` 的重试窗口。**这是用清理失败换共享自托管 `/tmp` 上的临时目录残留，而该残留已经两次耗尽宿主机的 inode 容量。
			
 
				+
			
 
				+**只抬高 Lefthook 套件，保留 hook 默认值。**该套件的 `afterEach` 正是它 Windows `EPERM` 清理失败出现的位置，所以被抬高的用例预算只会把同一次运行改成以 hook 超时的形式暴露。
			
--- a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.i18n.yaml
+++ b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md
			
 
				-2026-06-11-deterministic-and-stress-testing.md: d9977be835af05f9ee303b63ec6015bc9e153170
			
 
				-2026-06-11-deterministic-and-stress-testing.zh.md: 263e69f85a1cd8ee47da07210e513cab272d1a44
			
 
				+2026-06-11-deterministic-and-stress-testing.md: fd69611a393e36df5c5707640175bfd85c8e77ea
			
 
				+2026-06-11-deterministic-and-stress-testing.zh.md: 5ba8dbe4cf2a6c08bf1a3d68def9f801430b176a
			
--- a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md
+++ b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md
@@ -4,6 +4,8 @@ Status: proposed
 
				 
			
 
				 English | [中文](2026-06-11-deterministic-and-stress-testing.zh.md)
			
 
				 
			
 
				+The [CI test reliability skill](../../implemented/testing/2026-08-28-ci-test-reliability-skill.md) provides current authoring and diagnosis guidance without implementing the lint rule, universal replay fixture, or nightly stress job proposed here. Those mechanisms remain proposed.
			
 
				+
			
 
				 ## Problem
			
 
				 
			
 
				 Several loop tests synchronize with `setTimeout(30)` sleeps — flakiness debt that wastes agent cycles on retries and can mask ordering bugs. Separately, our core architectural promise (any session log replays to identical derived history) is asserted in two tests but is cheap to assert *everywhere*. And the inbox wakeup race was verified by hand exactly once; nothing re-verifies it continuously.
			
--- a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.zh.md
+++ b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.zh.md
@@ -4,6 +4,8 @@ Status: proposed
 
				 
			
 
				 [English](2026-06-11-deterministic-and-stress-testing.md) | 中文
			
 
				 
			
 
				+[CI 测试可靠性 Skill](../../implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md) 提供当前的测试编写与诊断指引，但没有实现本提案中的 lint 规则、通用回放 fixture 或 nightly stress job。这些机制仍处于提案状态。
			
 
				+
			
 
				 ## 问题
			
 
				 
			
 
				 若干 agent loop（智能体循环）测试通过 `setTimeout(30)` 睡眠来同步——这是一笔不稳定性债务，浪费 agent 的重试周期，还可能掩盖时序 bug。另外，我们的核心架构承诺（任何会话日志回放后都能得到相同的派生历史）目前只在两个测试中断言，但在*所有*测试中断言的成本极低。此外，inbox 唤醒竞态只被手动验证过一次，没有任何机制持续复验。
			
--- a/.agents/skills/dsh-ci-test-reliability/SKILL.md
+++ b/.agents/skills/dsh-ci-test-reliability/SKILL.md
@@ -0,0 +1,131 @@
 
				+---
			
 
				+name: dsh-ci-test-reliability
			
 
				+description: Design, review, and diagnose DeepSeek Harness tests and fixtures that can fail nondeterministically under CI concurrency, shared host resources, clocks, process-global state, subprocesses, network listeners, or asynchronous teardown. Use when adding or changing tests with those risks, investigating flaky CI, or reviewing test isolation; use dsh-pre-push-checks separately to select outgoing commands.
			
 
				+---
			
 
				+
			
 
				+# Reliable DSH CI tests
			
 
				+
			
 
				+Build tests that remain correct under the repository's real CI topology, not only when run alone on a quiet workstation. This skill owns isolation and reliability decisions; it does not replace the repository's test-tier policy or select every command for a push.
			
 
				+
			
 
				+## Read the owning rules
			
 
				+
			
 
				+- Use [the testing policy](../../../docs/testing.md) to select unit, coverage, expected-output, snapshot, browser, or real-API evidence.
			
 
				+- Use [the defensive patterns](../../../docs/defensive-patterns.md) for lifecycle, subprocess, cancellation, and teardown behavior.
			
 
				+- Read the active Vitest config and GitHub workflow when their worker or job topology affects the test.
			
 
				+- For recorded-session scenarios, also follow [the snapshot instructions](../../../snapshots/AGENTS.md).
			
 
				+- Use [dsh-pre-push-checks](../dsh-pre-push-checks/SKILL.md) after the test design is sound to select outgoing validation.
			
 
				+
			
 
				+## Model the execution topology
			
 
				+
			
 
				+Assume these layers can overlap unless the active configuration proves otherwise:
			
 
				+
			
 
				+1. Tests in one Vitest file.
			
 
				+2. Separate Vitest files or worker processes.
			
 
				+3. Independent Vitest or repository-gate processes in one job.
			
 
				+4. Different Actions jobs whose runners share one host.
			
 
				+
			
 
				+Process isolation does not isolate host ports, predictable filesystem paths, external services, databases, sockets, or inherited child processes. For every acquired resource, identify its owner, atomic allocation mechanism, observable readiness signal, registered cleanup, and quiescent completion signal.
			
 
				+
			
 
				+Do not serialize an entire suite merely because one fixture lacks isolation. Narrow the exclusive scope or change the resource allocation first. A sequential Vitest block cannot protect a host resource from another file, process, job, or runner.
			
 
				+
			
 
				+## Allocate resources atomically
			
 
				+
			
 
				+Use the resource owner's allocator instead of checking availability and claiming it later.
			
 
				+
			
 
				+- Network fixtures bind loopback with `listen(0)` and read the assigned address only after the server reports that it is listening. Never scan for a free port and bind it later.
			
 
				+- Create private per-test temporary roots with `mkdtemp`; do not acquire predictable shared paths.
			
 
				+- Give shared databases, sockets, sessions, and output locations unique per-test namespaces.
			
 
				+- Use exclusive creation where a path must not already exist.
			
 
				+- Keep stable recorded identifiers separate from ephemeral transport addresses. Translate inside the fixture instead of forcing the live resource to use the recorded value.
			
 
				+
			
 
				+Literal paths and URLs used only as parser inputs or expected values are not acquired resources. Do not rewrite them merely because they look fixed.
			
 
				+
			
 
				+## Contain process-global state
			
 
				+
			
 
				+Treat `process.env`, `cwd`, fake timers, locale and timezone, module mocks, registries, console hooks, `globalThis`, and global `fetch` interception as exclusive mutable resources.
			
 
				+
			
 
				+Prefer an injected dependency or instance-local adapter. When mutation is required:
			
 
				+
			
 
				+- capture whether the original value was absent or present;
			
 
				+- restore that exact state;
			
 
				+- register restoration immediately;
			
 
				+- use `try/finally` around the smallest mutation scope;
			
 
				+- keep an `afterEach` fallback when failure before the local `finally` is plausible;
			
 
				+- intercept the narrowest exact request or call that the fixture owns.
			
 
				+
			
 
				+## Respect platform-owned semantics
			
 
				+
			
 
				+CI runs the same suite on Windows and on POSIX hosts, and a value the operating system owns does not always come back the way a test wrote it.
			
 
				+
			
 
				+- Writing a value back is safe only when the assertion tolerates the write-back failing. Restoring a file's `mtime` to prove that a fingerprint invalidates anyway holds everywhere; restoring it to prove that a record stays valid assumes a lossless round trip, which NTFS's 100-nanosecond ticks do not give a fractional millisecond. When the assertion depends on the restoration, take the expected value from a fresh read rather than from the remembered one.
			
 
				+- Windows matches environment variable names case-insensitively, so a fixture seeding `http_proxy` and `HTTP_PROXY` as separate keys holds one entry there.
			
 
				+- Windows releases file handles asynchronously, so a rename or removal that completes at once on a POSIX host needs a bounded retry sized to the observed contention.
			
 
				+- Windows has no POSIX permission or signal semantics. A case that depends on them takes an explicit platform skip naming the reason, rather than an assertion weakened everywhere.
			
 
				+
			
 
				+Prefer an observation that holds on every platform. When a case genuinely cannot, exclude it on that platform explicitly.
			
 
				+
			
 
				+## Budget timeouts against the lane
			
 
				+
			
 
				+A `describe` or case timeout overrides the runner's `--testTimeout` instead of yielding to it, so a value below the lane's budget lowers what CI already granted — and the same literal reads as a widening on a host whose default is smaller. A suite bound by process creation takes the lane budget; a tighter value carries the reason it is tighter.
			
 
				+
			
 
				+Raise the hook budget with the test budget. Setup and teardown pay the same contention, so lifting only the case budget moves a contended failure into `afterEach`.
			
 
				+
			
 
				+Where a timeout is the subject, keep the outer wait far larger than the timeout under test. A case proving that a 20 ms deadline fires must not race the harness's own wait, or load decides which deadline reports first.
			
 
				+
			
 
				+## Synchronize on state
			
 
				+
			
 
				+A fixed sleep is not evidence that setup completed or cleanup settled.
			
 
				+
			
 
				+- Wait for an explicit readiness event, handshake, state transition, owned promise, or externally observable condition.
			
 
				+- Use deferred promises or barriers to place a race at a deterministic point and prove the relevant operations overlap.
			
 
				+- Use a timeout only to bound a wait, never as the condition that makes the assertion correct.
			
 
				+- Do not assert scheduler-dependent ordering unless that ordering is the product behavior under test.
			
 
				+- When time itself is the subject, inject or fake the clock and always restore real timers.
			
 
				+
			
 
				+## Dispose to quiescence
			
 
				+
			
 
				+Register cleanup immediately after acquisition so assertion failures also release the resource. Cleanup stops new callbacks or requests, detaches listeners, restores global hooks, terminates owned work, and awaits child exit, server close, worker termination, or the equivalent completion signal.
			
 
				+
			
 
				+Calling `abort()`, `close()`, or `kill()` without awaiting the owned completion signal is incomplete teardown. When late completion is possible, prove that disposal prevents it from mutating another test.
			
 
				+
			
 
				+## Prove the intended regression
			
 
				+
			
 
				+- Observe an ordinary regression fail before the fix when practical.
			
 
				+- For a new static or corpus guard, temporarily introduce the rejected case and observe the intended failure.
			
 
				+- For a race, use barriers to prove overlap; repeated execution alone is not a race test.
			
 
				+- For ports, sockets, shared paths, subprocesses, or other host resources, run independent test processes concurrently when cross-process isolation is part of the fix.
			
 
				+- Where a fixture spawns with its own deadline, assert that no signal or timeout ended the child before asserting its exit status, so a killed child reports as a timeout instead of as a status mismatch.
			
 
				+- Verify external state, events, files, logs, exits, or disposal instead of trusting the component's self-report.
			
 
				+
			
 
				+Stress runs supplement a deterministic regression; they do not replace one.
			
 
				+
			
 
				+## Reject flake-masking fixes
			
 
				+
			
 
				+Do not present these as root-cause fixes for deterministic local tests:
			
 
				+
			
 
				+- increasing a timeout without identifying the awaited state;
			
 
				+- adding retries;
			
 
				+- making all files serial;
			
 
				+- swallowing an error or unhandled rejection;
			
 
				+- weakening an assertion;
			
 
				+- normalizing away unstable behavior;
			
 
				+- adding a sleep before cleanup or assertion.
			
 
				+
			
 
				+Retries remain valid for documented transient external-provider tests under the real-API policy. Keep that exception at the external boundary.
			
 
				+
			
 
				+Restoring a budget is not masking. Raising a suite to the lane budget it already had, or sizing a bounded retry to the contention actually measured on the runner, names the awaited work and returns what the lane granted; neither invents headroom around an unexamined wait.
			
 
				+
			
 
				+## Diagnose existing flakes
			
 
				+
			
 
				+For an existing probabilistic CI failure, read [the CI flake diagnosis workflow](references/ci-flake-diagnosis.md). A diagnosis-only request remains read-only: report the cause and evidence unless the user also asks for a fix.
			
 
				+
			
 
				+## Validate and report
			
 
				+
			
 
				+Run the smallest focused regression for the affected behavior. Add topology-specific evidence only when the change owns that risk:
			
 
				+
			
 
				+- global mutation needs restoration evidence;
			
 
				+- lifecycle or subprocess work needs quiescent teardown evidence;
			
 
				+- ports, sockets, or shared paths need concurrent independent-process evidence;
			
 
				+- a new guard needs a negative control.
			
 
				+
			
 
				+Before a push, use [dsh-pre-push-checks](../dsh-pre-push-checks/SKILL.md). Report exact commands and observed results; do not describe retries, skipped tests, or pending CI as passing.
			
--- a/.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md
+++ b/.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md
@@ -0,0 +1,60 @@
 
				+# CI flake diagnosis
			
 
				+
			
 
				+Use this workflow only when the task is to investigate an existing probabilistic test or CI failure. Preserve the requested read/write scope: diagnosis does not authorize a fix, workflow rerun, or CI configuration change.
			
 
				+
			
 
				+## Freeze the evidence
			
 
				+
			
 
				+Record the repository, workflow, job, commit SHA, runner labels, timestamps, exact failing test or command, and the first stable failure signature. Keep infrastructure messages separate from test output.
			
 
				+
			
 
				+Compare multiple failing and passing runs. Prefer runs of the same SHA; when that is impossible, verify that the relevant test and CI configuration are identical across the compared commits. One passing rerun does not prove an infrastructure fault, and one timeout does not prove a product race.
			
 
				+
			
 
				+Use Actions logs and metadata to establish whether failures overlap on one host or resource namespace. Preserve links to the supporting runs rather than pasting large logs.
			
 
				+
			
 
				+## Classify the failure
			
 
				+
			
 
				+Classify from recorded evidence, not from the eventual fix:
			
 
				+
			
 
				+- **Host-resource collision:** the same port, socket, database, predictable path, cache, or external namespace is acquired by independent processes or jobs.
			
 
				+- **Incomplete lifecycle:** teardown returns before children, workers, streams, servers, or callbacks reach quiescence; later output or mutations appear in another test.
			
 
				+- **Process-global contamination:** outcome depends on test order or leaked `process.env`, `cwd`, fake timers, globals, mocks, locale, or module state.
			
 
				+- **Load-sensitive synchronization:** a sleep, polling interval, or assumed event-loop turn substitutes for observable readiness or completion.
			
 
				+- **Platform or entry-path mismatch:** the failure consistently follows an operating system, shell, filesystem rule, source/build mode, or executable entry. Timestamp precision, environment variable name case, handle-release timing, and permission semantics all differ between Windows and POSIX hosts, so a case passing on macOS says nothing about the Windows lane.
			
 
				+- **Product concurrency defect:** the test controls its resources, reproduces deterministically with explicit overlap, and exposes a race in shipped behavior.
			
 
				+- **External-provider transience:** the failure is owned by a live API or network boundary and matches its documented retry policy.
			
 
				+- **Runner infrastructure:** checkout, dependency download, disk, host process, or runner service fails independently of the test command. Require direct runner evidence before assigning this class. Where a self-hosted pool exposes no host metrics, say so and classify from what the logs do carry: one signature repeating across unrelated branches on one pool is evidence of shared-host contention even when the host cannot be inspected.
			
 
				+
			
 
				+If evidence supports more than one independent fact, report each one. Do not collapse a timeout, signal, exit code, and assertion into a single inferred outcome.
			
 
				+
			
 
				+## Reproduce the smallest relevant topology
			
 
				+
			
 
				+Start with the owning test file or focused test name. Increase concurrency only to the first topology that reproduces the signature:
			
 
				+
			
 
				+1. one test process;
			
 
				+2. concurrent tests or files;
			
 
				+3. multiple independent Vitest processes;
			
 
				+4. the owning repository gate with its configured worker count;
			
 
				+5. separate jobs or runner processes sharing the implicated host resource.
			
 
				+
			
 
				+Match the active Vitest config, environment knobs, source/build mode, and platform. Do not lower a production timeout or add random load merely to manufacture a different failure.
			
 
				+
			
 
				+Where the signature belongs to a platform the available host cannot run, the ladder stops at the last reachable rung. Record that limit rather than substituting a passing run on another platform, then use CI as the reproduction, changing one suspected owner per run so the result stays attributable.
			
 
				+
			
 
				+For a suspected race, replace probabilistic timing with a barrier at the contested transition. For a suspected host collision, prove simultaneous acquisition of the same identifier or prove that atomic unique allocation removes the conflict.
			
 
				+
			
 
				+## Fix at the owner
			
 
				+
			
 
				+When implementation is authorized, fix the component that allocates, publishes readiness, mutates global state, or owns teardown. Do not hide the failure in a snapshot normalizer, retry wrapper, broader timeout, global serialization setting, or weaker assertion.
			
 
				+
			
 
				+Keep stable fixture data separate from live resource allocation. A recorded URL can remain stable while the fixture maps its transport to an OS-assigned port; a stable expected path can remain an assertion without becoming a shared writable directory.
			
 
				+
			
 
				+## Close the investigation
			
 
				+
			
 
				+The evidence is complete when:
			
 
				+
			
 
				+- the original signature has a supported classification;
			
 
				+- the smallest relevant topology reproduces it, or the external evidence is sufficient and the reproduction limit is explicit;
			
 
				+- an authorized fix fails under a negative control or pre-fix state and passes under the same topology afterward;
			
 
				+- any concurrent-process, restoration, or quiescent-teardown proof required by the resource owner passes;
			
 
				+- remaining Actions checks are reported as passing, pending, skipped, or failing from their observed state.
			
 
				+
			
 
				+Do not run until a test happens to pass and call that result stable. Stop after the selected evidence establishes the conclusion, or report the missing fact that blocks classification.
			
--- a/.agents/skills/dsh-code-review/SKILL.md
+++ b/.agents/skills/dsh-code-review/SKILL.md
@@ -13,6 +13,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
 
				 - [docs/defensive-patterns.md](../../../docs/defensive-patterns.md): subprocess, callback, async-state, and disposal bug classes.
			
 
				 - [docs/AGENTS.md](../../../docs/AGENTS.md): documentation placement and prose discipline.
			
 
				 - [dsh-prose-standard](../dsh-prose-standard/SKILL.md): required coverage and editorial judgment for comments, docs, prompts, and visible strings.
			
 
				+- [dsh-ci-test-reliability](../dsh-ci-test-reliability/SKILL.md): isolation and regression-proof rules for resource-owning, asynchronous, or flaky tests and fixtures.
			
 
				 - [docs/testing.md](../../../docs/testing.md) and the [quality-gates Agent Note](../../notes/implemented/process/2026-06-11-quality-gates.md): required test tiers and gates.
			
 
				 - [Agent Notes](../../notes/README.md): design rationale. Treat disagreement with an Agent Note as a design discussion, not an automatic veto.
			
 
				 - For bilingual changes, read [translation-rules.md](../../../docs/i18n/translation-rules.md) and [terminology.md](../../../docs/i18n/terminology.md); the extended translation skill is outside automatic review and runs only on explicit user invocation.
			
@@ -40,6 +41,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
 
				 - **Bounds cover the final operation:** locate the owner of the complete emitted or retained result, including wrappers and metadata. Probe tiny and exact limits, oversized single chunks, and multibyte text for byte limits.
			
 
				 - **Real entry path:** tests exercise the shipped Loader, bin, worker, ACP bridge, or subprocess where relevant. A hand-mounted plugin does not catch invalid Loader exports; a function plugin must named-export its namespace and have no default export.
			
 
				 - **Test strength:** assertions fail on the intended regression and verify external state, logs, events, or disposal rather than restating the implementation or trusting an agent's report. Coverage is necessary but not evidence that the scenario is correct.
			
 
				+- **Test reliability:** for a resource-owning, asynchronous, platform-sensitive, or flaky test, apply [dsh-ci-test-reliability](../dsh-ci-test-reliability/SKILL.md) to the real worker/job topology, resource allocation, global-state restoration, synchronization, timeout budget, and quiescent teardown.
			
 
				 - **Invariant lifecycle and negative controls:** verify candidate observations are rejected before publication where possible, session-backed checks reconstruct durable history after late loading or HMR, and a deliberately invalid case fails through the real runner for the intended rule.
			
 
				 - **Implemented Agent Notes match shipped reality:** when a PR implements a proposed Agent Note, move and rewrite it as present-tense shipped state in the same diff, then verify paths, names, and mechanisms against the implementation.
			
 
				 - **Transcript changes:** editor-visible or model-visible changes update snapshots or explain why no snapshot applies. Review expected-output diffs as behavior changes, not formatting noise.
			
--- a/.agents/skills/dsh-pre-push-checks/SKILL.md
+++ b/.agents/skills/dsh-pre-push-checks/SKILL.md
@@ -28,6 +28,8 @@ The command never guesses or fetches a base. Supply the ref verified from curren
 
				 
			
 
				 There is no universal local baseline beyond the hooks. Every behavior change needs the narrowest available test or purpose-built check that would fail for its regression; add broader checks only for surfaces the diff actually reaches.
			
 
				 
			
 
				+When the outgoing change adds or changes a resource-owning or asynchronous test, fixture, helper, or CI execution path, use [dsh-ci-test-reliability](../dsh-ci-test-reliability/SKILL.md) first to decide whether restoration, negative-control, quiescent-teardown, or concurrent-process evidence applies. This skill still selects the commands and avoids repeating evidence that already passed.
			
 
				+
			
 
				 - **Package or script behavior:** run the owning Vitest file or focused test name. Add adjacent package tests when a shared contract changes; leave repository-wide coverage to CI unless the change is genuinely cross-cutting or the user requests it.
			
 
				 - **Documentation, Agent Notes, catalogs, or doc-linked comments:** run `pnpm run doc-sync`; run full lint when the documentation workflow requires it.
			
 
				 - **Model-, editor-, CLI-, or terminal-visible output:** run the focused keyless snapshot or real runnable-example scenario that owns the output.
			
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -252,6 +252,13 @@ jobs:
 
				             name: node 22.19
			
 
				             runner: ubuntu-latest
			
 
				             gate_concurrency: '1'
			
 
				+          # Pinned inside 24.0-24.11.1: those releases carry the v1 internal
			
 
				+          # loader while reporting major 24, and every other job tracks the
			
 
				+          # latest 24, which is v2. A bare `24` here would retest that same v2.
			
 
				+          - node: '24.9'
			
 
				+            name: node 24.9
			
 
				+            runner: ubuntu-latest
			
 
				+            gate_concurrency: '1'
			
 
				           - node: 26
			
 
				             name: node 26
			
 
				             runner: ubuntu-latest
			
@@ -276,6 +283,12 @@ jobs:
 
				           DSH_BUILD_CLIENT_PROFILE: official
			
 
				         run: pnpm run check:node-compat
			
 
				 
			
 
				+      # Kept out of the gate aggregate: the shape a Node release carries only
			
 
				+      # changes with the Node version, so this belongs to the version matrix
			
 
				+      # rather than to every commit's checks.
			
 
				+      - name: Check Loader internal shape detection
			
 
				+        run: pnpm exec vitest run packages/boot/app-boot/tests/loader-shape.compat.spec.ts
			
 
				+
			
 
				   python-sdk:
			
 
				     if: github.event_name == 'pull_request'
			
 
				     runs-on: ubuntu-latest
			
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -2,9 +2,9 @@
 
				 # entries, all on one version. The vendored framework and the native packages are
			
 
				 # separate sequences with their own workflows and version lines.
			
 
				 #
			
 
				-# Pack runs without credentials on every pull request and master push, so a
			
 
				-# pull request proves the whole publish set still packs. Publication is a manual
			
 
				-# workflow_dispatch of release-publish.yml from a dsh-v* tag.
			
 
				+# Pack and dependency-layout verification run without credentials on every pull
			
 
				+# request and master push. Publication is a manual workflow_dispatch of
			
 
				+# release-publish.yml from a dsh-v* tag.
			
 
				 name: Release (dsh)
			
 
				 
			
 
				 on:
			
@@ -26,6 +26,46 @@ env:
 
				   DSH_TELEMETRY_DISABLED: '1'
			
 
				 
			
 
				 jobs:
			
 
				+  dependencies:
			
 
				+    name: Dependency layout
			
 
				+    runs-on: ubuntu-24.04
			
 
				+    steps:
			
 
				+      - uses: actions/checkout@v6
			
 
				+        with:
			
 
				+          persist-credentials: false
			
 
				+
			
 
				+      - uses: pnpm/action-setup@v4
			
 
				+        with:
			
 
				+          dest: ${{ runner.temp }}/setup-pnpm
			
 
				+
			
 
				+      - uses: actions/setup-node@v6
			
 
				+        with:
			
 
				+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
			
 
				+
			
 
				+      - name: Configure pnpm store path
			
 
				+        id: pnpm-store
			
 
				+        run: |
			
 
				+          store_root="$HOME/.local/share/pnpm/store"
			
 
				+          echo "PNPM_CONFIG_STORE_DIR=$store_root" >> "$GITHUB_ENV"
			
 
				+          store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent)
			
 
				+          echo "path=$store_path" >> "$GITHUB_OUTPUT"
			
 
				+
			
 
				+      - uses: actions/cache/restore@v4
			
 
				+        with:
			
 
				+          path: ${{ steps.pnpm-store.outputs.path }}
			
 
				+          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
			
 
				+          restore-keys: |
			
 
				+            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
			
 
				+
			
 
				+      - name: Install (immutable)
			
 
				+        run: pnpm install --frozen-lockfile
			
 
				+
			
 
				+      - name: Verify dependency policy
			
 
				+        run: pnpm run verify-package-dependencies
			
 
				+
			
 
				+      - name: Verify npm install layout
			
 
				+        run: pnpm run verify-npm-install-layout
			
 
				+
			
 
				   pack:
			
 
				     name: Pack npm tarballs
			
 
				     runs-on: ubuntu-24.04
			
--- a/apps/web/tests/conversation-column-overflow.e2e.ts
+++ b/apps/web/tests/conversation-column-overflow.e2e.ts
@@ -1,344 +0,0 @@
 
				-// Web e2e scenario: the conversation column scrolls on one axis only, as the
			
 
				-// browser actually lays it out. The hazard: a horizontal scrollbar appears
			
 
				-// under the whole center column once the window (or the sidebar drag) narrows
			
 
				-// it — the hero's decorative backdrop ellipse bleeds past the column and
			
 
				-// becomes user-scrollable.
			
 
				-//
			
 
				-// The bleed is by construction and stays: `.heroGlow` is sized 1051/776 of the
			
 
				-// hero box (ConversationRoot.module.css) so the blur scales with the input
			
 
				-// card. The scroll container is where the bar comes from:
			
 
				-// `[data-conversation-scroll]` scrolls vertically, and a one-axis scroller
			
 
				-// computes the other axis's initial `visible` to `auto`, so the bleed becomes
			
 
				-// a bar; `overflow-x: hidden` on the scroller prevents it.
			
 
				-//
			
 
				-// Only a real engine reports that pair — the bleed and the resulting scroll
			
 
				-// range — so the scenario sweeps viewport widths that bracket the glow's
			
 
				-// width and asserts both at each stop. Asserting no horizontal scroll alone
			
 
				-// would go vacuous the moment the glow stopped bleeding for an unrelated
			
 
				-// reason, which is why each stop also records whether it bleeds; the wide stop
			
 
				-// is the control where it does not.
			
 
				-//
			
 
				-// Zero model calls: the hero is the boot state, so nothing is seeded and no
			
 
				-// replay row mounts. A stray stream would fail loud with NO_ADAPTER.
			
 
				-import { fileURLToPath } from 'node:url'
			
 
				-import { join } from 'node:path'
			
 
				-import type { Browser, Page } from 'playwright'
			
 
				-import { chromium } from 'playwright'
			
 
				-import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
			
 
				-import {
			
 
				-  assertFixtureInventory, compareOrRefreshGolden, launchWebScaffold, watchConsole, webSnapshotMode,
			
 
				-  type WebScaffold,
			
 
				-} from './scaffold.ts'
			
 
				-import { newEnglishPage, saveFailureShot } from './support.ts'
			
 
				-
			
 
				-const SNAPSHOT_DIR = fileURLToPath(new URL('./expected/conversation-column-overflow', import.meta.url))
			
 
				-/**
			
 
				- * Committed golden of the one-axis relation at every stop. It records
			
 
				- * relations and booleans, never absolute coordinates: the column width follows
			
 
				- * the viewport and the sidebar, and a golden carrying pixels would document the
			
 
				- * platform instead of the behavior.
			
 
				- */
			
 
				-const GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'geometry.expected.md')
			
 
				-const MODE = webSnapshotMode()
			
 
				-/** Narrow sweep stop where the mutation control retains overflow across scrollbar implementations. */
			
 
				-const CONTROL_VIEWPORT = 600
			
 
				-/**
			
 
				- * Viewport widths bracketing the glow: the narrow stops retain the reported
			
 
				- * bleed while the widest stop proves the relation can also be false.
			
 
				- */
			
 
				-const WIDTHS = [1680, 1200, 1000, 800, CONTROL_VIEWPORT]
			
 
				-/** Element id of the mutation control's injected sheet, so the test can take it back out. */
			
 
				-const CONTROL_STYLE_ID = 'dsh-column-overflow-control'
			
 
				-/** Horizontal wheel delta per gesture; must exceed the widest bleed the sweep can produce. */
			
 
				-const WHEEL_DELTA = 300
			
 
				-
			
 
				-/** One viewport stop: whether the glow bleeds past the column, and whether that bleed scrolls. */
			
 
				-interface ColumnMetrics {
			
 
				-  /** Viewport width the stop was measured at. */
			
 
				-  width: number
			
 
				-  /** The column's content width. Not committed to the golden — it is what settles after a resize, and what the sweep waits on. */
			
 
				-  columnWidth: number
			
 
				-  /** Resolved `overflow-x` on the conversation scroll container. */
			
 
				-  overflowX: string
			
 
				-  /**
			
 
				-   * True when the glow's box reaches past the column's content edge — the
			
 
				-   * condition the `overflow-x: hidden` declaration has to survive.
			
 
				-   */
			
 
				-  glowBleeds: boolean
			
 
				-  /**
			
 
				-   * `scrollWidth - clientWidth`. Deliberately NOT the assertion: `hidden` and
			
 
				-   * `auto` both report the same value, because `hidden` clips the bleed rather
			
 
				-   * than reflowing it away. Recorded because it is the vacuity guard in
			
 
				-   * numbers — it must stay positive at the narrow stops, or the scenario has
			
 
				-   * stopped reproducing the situation `overflow-x: hidden` exists for.
			
 
				-   */
			
 
				-  bleedRange: number
			
 
				-  /** True when the column still scrolls vertically — the axis `overflow-x: hidden` must not take away. */
			
 
				-  scrollsVertically: boolean
			
 
				-}
			
 
				-
			
 
				-/**
			
 
				- * Measure the conversation column at the page's current viewport.
			
 
				- * @param page - the page under test.
			
 
				- * @param width - the viewport width already applied, recorded with the reading.
			
 
				- * @returns the stop's overflow relations.
			
 
				- */
			
 
				-function measureColumn(page: Page, width: number): Promise<ColumnMetrics> {
			
 
				-  return page.evaluate((viewportWidth) => {
			
 
				-    const scroller = document.querySelector<HTMLElement>('[data-conversation-scroll]')
			
 
				-    if (scroller === null) throw new Error('conversation scroll container not in the DOM')
			
 
				-    const glow = scroller.querySelector<SVGElement>('[class*="heroGlow"]')
			
 
				-    if (glow === null) throw new Error('hero glow not in the DOM — the boot state is not the hero')
			
 
				-    const box = scroller.getBoundingClientRect()
			
 
				-    const glowBox = glow.getBoundingClientRect()
			
 
				-    return {
			
 
				-      width: viewportWidth,
			
 
				-      columnWidth: scroller.clientWidth,
			
 
				-      overflowX: getComputedStyle(scroller).overflowX,
			
 
				-      // `clientWidth` is the content edge, which is what the scrollable
			
 
				-      // overflow region is measured against; either side counts as a bleed,
			
 
				-      // though only the right one can produce a bar in this writing mode.
			
 
				-      glowBleeds: glowBox.right > box.left + scroller.clientWidth + 0.5 || glowBox.left < box.left - 0.5,
			
 
				-      bleedRange: scroller.scrollWidth - scroller.clientWidth,
			
 
				-      scrollsVertically: getComputedStyle(scroller).overflowY === 'auto',
			
 
				-    }
			
 
				-  }, width)
			
 
				-}
			
 
				-
			
 
				-/**
			
 
				- * Scroll the column sideways the way a user would and report where it landed.
			
 
				- *
			
 
				- * This is the one signal that separates the two states, and it is why the
			
 
				- * scenario needs a real engine: `overflow-x: hidden` leaves the box
			
 
				- * programmatically scrollable and leaves `scrollWidth` untouched, so every
			
 
				- * property reading agrees across the two overflow modes. Only refusing an
			
 
				- * actual input event differs — measured at the 1200px stop, the shipped
			
 
				- * column stays at 0 while the same page with `overflow-x: auto` forced on
			
 
				- * lands at its scroll boundary.
			
 
				- * @param page - the page under test.
			
 
				- * @returns `scrollLeft` after one horizontal wheel over the column.
			
 
				- */
			
 
				-async function wheelHorizontally(page: Page): Promise<number> {
			
 
				-  const origin = await page.evaluate(() => {
			
 
				-    const scroller = document.querySelector<HTMLElement>('[data-conversation-scroll]')
			
 
				-    if (scroller === null) throw new Error('conversation scroll container not in the DOM')
			
 
				-    // Start from the origin so the reading is this gesture's own effect.
			
 
				-    scroller.scrollLeft = 0
			
 
				-    const box = scroller.getBoundingClientRect()
			
 
				-    // Near the top of the column, clear of the centered hero card: the wheel
			
 
				-    // must reach the column, not a nested scroller the composer owns.
			
 
				-    return { x: box.left + box.width / 2, y: box.top + 60 }
			
 
				-  })
			
 
				-  await page.mouse.move(origin.x, origin.y)
			
 
				-  await page.mouse.wheel(WHEEL_DELTA, 0)
			
 
				-  // A fixed settle, then two frames. Polling for a settled value cannot be
			
 
				-  // used here — the value under test is 0, which a poll starting at 0 accepts
			
 
				-  // before the gesture has had any chance to move it — so the wait is
			
 
				-  // generous enough to cover a smooth-scroll animation on any engine the lane
			
 
				-  // runs on. The timing is identical on both sides of the mutation control
			
 
				-  // below, which is what makes a 0 reading evidence rather than a race won.
			
 
				-  await page.waitForTimeout(400)
			
 
				-  return page.evaluate(() => new Promise<number>((resolve) => {
			
 
				-    requestAnimationFrame(() => {
			
 
				-      requestAnimationFrame(() => {
			
 
				-        resolve(document.querySelector<HTMLElement>('[data-conversation-scroll]')?.scrollLeft ?? -1)
			
 
				-      })
			
 
				-    })
			
 
				-  }))
			
 
				-}
			
 
				-
			
 
				-/**
			
 
				- * Measure the positive horizontal scroll boundary without changing the
			
 
				- * shipped overflow mode. This is distinct from `scrollWidth - clientWidth`
			
 
				- * when a stable scrollbar gutter leaves part of the overflow on the negative
			
 
				- * side of the scroll origin.
			
 
				- * @param page - the page under test.
			
 
				- * @returns the greatest positive `scrollLeft` reachable by the control gesture.
			
 
				- */
			
 
				-async function horizontalScrollLimit(page: Page): Promise<number> {
			
 
				-  return page.evaluate((delta) => {
			
 
				-    const scroller = document.querySelector<HTMLElement>('[data-conversation-scroll]')
			
 
				-    if (scroller === null) throw new Error('conversation scroll container not in the DOM')
			
 
				-    const previousScrollBehavior = scroller.style.scrollBehavior
			
 
				-    scroller.style.scrollBehavior = 'auto'
			
 
				-    scroller.scrollLeft = delta
			
 
				-    const limit = scroller.scrollLeft
			
 
				-    scroller.scrollLeft = 0
			
 
				-    scroller.style.scrollBehavior = previousScrollBehavior
			
 
				-    return limit
			
 
				-  }, WHEEL_DELTA)
			
 
				-}
			
 
				-
			
 
				-/** A stop's readings plus where a horizontal wheel over it landed. */
			
 
				-type ColumnStop = ColumnMetrics & {
			
 
				-  /** `scrollLeft` after one horizontal wheel: the user-facing claim, 0 at every stop. */
			
 
				-  scrollLeftAfterWheel: number
			
 
				-}
			
 
				-
			
 
				-/**
			
 
				- * Render the golden body: one line per stop, relations only.
			
 
				- *
			
 
				- * Absolute pixels are deliberately absent apart from `scrollLeftAfterWheel`,
			
 
				- * which the shipped overflow mode pins to 0 by construction. The bleed is
			
 
				- * recorded as a boolean rather than its width, so the golden survives any
			
 
				- * platform whose column lands a pixel off — a fixture that has to be
			
 
				- * re-recorded per platform documents the platform, not the behavior.
			
 
				- * @param stops - the measured stops, in sweep order.
			
 
				- * @returns the golden body, without a trailing newline.
			
 
				- */
			
 
				-function renderGeometry(stops: ColumnStop[]): string {
			
 
				-  return [
			
 
				-    '# Conversation column horizontal overflow',
			
 
				-    '',
			
 
				-    '| viewport | overflow-x | glow bleeds past the column | scrollLeft after a horizontal wheel | scrolls vertically |',
			
 
				-    '| --- | --- | --- | --- | --- |',
			
 
				-    ...stops.map(stop => `| ${String(stop.width)}px | ${stop.overflowX} | ${String(stop.glowBleeds)} `
			
 
				-      + `| ${String(stop.scrollLeftAfterWheel)}px | ${String(stop.scrollsVertically)} |`),
			
 
				-  ].join('\n')
			
 
				-}
			
 
				-
			
 
				-describe('web e2e: the conversation column scrolls on one axis', () => {
			
 
				-  let scaffold: WebScaffold
			
 
				-  let browser: Browser
			
 
				-  let page: Page
			
 
				-  let tripwire: ReturnType<typeof watchConsole>
			
 
				-
			
 
				-  beforeAll(async () => {
			
 
				-    scaffold = await launchWebScaffold({})
			
 
				-    browser = await chromium.launch()
			
 
				-    page = await newEnglishPage(browser, 900)
			
 
				-    tripwire = watchConsole(page)
			
 
				-    await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
			
 
				-    await page.waitForSelector('[data-conversation-scroll] [class*="heroGlow"]', { timeout: 30_000 })
			
 
				-  }, 180_000)
			
 
				-
			
 
				-  afterAll(async () => {
			
 
				-    await browser?.close()
			
 
				-    await scaffold?.close()
			
 
				-  })
			
 
				-
			
 
				-  /**
			
 
				-   * Resize to a viewport and read the column once its width stops moving.
			
 
				-   *
			
 
				-   * The glow rides the hero box, which rides the column, and the frame eases
			
 
				-   * its column tracks over `--ds-transition-duration-slow`: reading straight
			
 
				-   * after a resize can report the previous viewport's relation, or a width
			
 
				-   * caught mid-transition.
			
 
				-   * @param width - viewport width to settle at.
			
 
				-   * @returns the column's readings at that width.
			
 
				-   */
			
 
				-  const settleAt = async (width: number): Promise<ColumnMetrics> => {
			
 
				-    await page.setViewportSize({ width, height: 900 })
			
 
				-    let previous = -1
			
 
				-    await expect.poll(async () => {
			
 
				-      const current = (await measureColumn(page, width)).columnWidth
			
 
				-      const settled = current === previous
			
 
				-      previous = current
			
 
				-      return settled
			
 
				-    }, { timeout: 10_000 }).toBe(true)
			
 
				-    return measureColumn(page, width)
			
 
				-  }
			
 
				-
			
 
				-  /**
			
 
				-   * Sweep the stops once per run and hand the SAME readings to every assertion
			
 
				-   * below, so the golden and the assertions describe one measurement instead of
			
 
				-   * two runs that could disagree. Memoized rather than re-run per test: the
			
 
				-   * gestures below move the viewport, and a second sweep would be a second
			
 
				-   * chance for a resize to settle differently.
			
 
				-   * @returns the stops in {@link WIDTHS} order.
			
 
				-   */
			
 
				-  let swept: Promise<ColumnStop[]> | undefined
			
 
				-  const sweep = (): Promise<ColumnStop[]> => {
			
 
				-    swept ??= (async () => {
			
 
				-      const stops: ColumnStop[] = []
			
 
				-      for (const width of WIDTHS) {
			
 
				-        stops.push({ ...await settleAt(width), scrollLeftAfterWheel: await wheelHorizontally(page) })
			
 
				-      }
			
 
				-      return stops
			
 
				-    })()
			
 
				-    return swept
			
 
				-  }
			
 
				-
			
 
				-  it('never scrolls horizontally, at any width the glow bleeds past', async () => {
			
 
				-    onTestFailed(() => saveFailureShot(page, 'web-e2e-conversation-column-overflow'))
			
 
				-    const stops = await sweep()
			
 
				-    // The vacuity guard, in two halves: the glow has to reach past the column
			
 
				-    // at the narrow stops, and that reach has to still register as scrollable
			
 
				-    // overflow. Without both, the claim below holds for free.
			
 
				-    expect(stops.filter(stop => stop.glowBleeds).map(stop => stop.width)).toEqual([
			
 
				-      1200, 1000, 800, CONTROL_VIEWPORT,
			
 
				-    ])
			
 
				-    for (const stop of stops.filter(stop => stop.glowBleeds)) {
			
 
				-      expect(stop.bleedRange, `viewport ${String(stop.width)}`).toBeGreaterThan(0)
			
 
				-    }
			
 
				-    for (const stop of stops) {
			
 
				-      expect(stop.overflowX, `viewport ${String(stop.width)}`).toBe('hidden')
			
 
				-      // The reported symptom, stated directly: a horizontal wheel over the
			
 
				-      // column moves nothing, at every stop.
			
 
				-      expect(stop.scrollLeftAfterWheel, `viewport ${String(stop.width)}`).toBe(0)
			
 
				-      // The axis the column is a scroller for must survive `overflow-x: hidden`.
			
 
				-      expect(stop.scrollsVertically, `viewport ${String(stop.width)}`).toBe(true)
			
 
				-    }
			
 
				-    expect(tripwire.pageErrors).toEqual([])
			
 
				-  }, 120_000)
			
 
				-
			
 
				-  it('scrolls horizontally again once the axis is opened back up (control)', async () => {
			
 
				-    onTestFailed(() => saveFailureShot(page, 'web-e2e-conversation-column-overflow-control'))
			
 
				-    // The mutation control, run in the page rather than against a second
			
 
				-    // build: it lifts exactly the `overflow-x: hidden` declaration, so the
			
 
				-    // initial `visible` that a one-axis scroller computes to `auto` takes
			
 
				-    // over, and shows the same gesture, at the same timing, carrying the
			
 
				-    // column to its positive scroll boundary.
			
 
				-    // Without it a `scrollLeft` of 0 could equally mean the wheel never arrived.
			
 
				-    // Injected with an id rather than through `addStyleTag`, so the teardown
			
 
				-    // below can take the sheet out again by selector: it must not outlive this
			
 
				-    // test, or the golden ends up reading the control.
			
 
				-    await page.evaluate((id: string) => {
			
 
				-      const sheet = document.createElement('style')
			
 
				-      sheet.id = id
			
 
				-      sheet.textContent = '[data-conversation-scroll] { overflow-x: auto !important; }'
			
 
				-      document.head.append(sheet)
			
 
				-    }, CONTROL_STYLE_ID)
			
 
				-    try {
			
 
				-      // Resolve the mutated layout at the narrowest sweep stop. At wider stops,
			
 
				-      // a classic scrollbar can change the available box enough to remove the
			
 
				-      // overflow that the control is meant to expose.
			
 
				-      const before = await settleAt(CONTROL_VIEWPORT)
			
 
				-      expect(before.overflowX).toBe('auto')
			
 
				-      expect(before.bleedRange).toBeGreaterThan(0)
			
 
				-      const scrollLimit = await horizontalScrollLimit(page)
			
 
				-      // The control has a reachable horizontal range, and the gesture exceeds
			
 
				-      // it so the equality below proves that the wheel reached the far edge.
			
 
				-      expect(scrollLimit).toBeGreaterThan(0)
			
 
				-      expect(scrollLimit).toBeLessThan(WHEEL_DELTA)
			
 
				-      // Rounded: `scrollLeft` is fractional under a fractional layout while
			
 
				-      // the claim is that the column reached the positive boundary, not that
			
 
				-      // two engines agree on a sub-pixel.
			
 
				-      expect(Math.round(await wheelHorizontally(page))).toBe(Math.round(scrollLimit))
			
 
				-    } finally {
			
 
				-      await page.evaluate((id: string) => {
			
 
				-        document.getElementById(id)?.remove()
			
 
				-      }, CONTROL_STYLE_ID)
			
 
				-    }
			
 
				-    // The override is gone and the shipped state is back: the later goldens
			
 
				-    // read the product, not the control.
			
 
				-    expect((await settleAt(CONTROL_VIEWPORT)).overflowX).toBe('hidden')
			
 
				-    expect(tripwire.pageErrors).toEqual([])
			
 
				-  }, 120_000)
			
 
				-
			
 
				-  it('matches the committed column-overflow golden', async () => {
			
 
				-    onTestFailed(() => saveFailureShot(page, 'web-e2e-conversation-column-overflow-golden'))
			
 
				-    await compareOrRefreshGolden(GEOMETRY_EXPECTED, renderGeometry(await sweep()), MODE)
			
 
				-    expect(tripwire.pageErrors).toEqual([])
			
 
				-  }, 120_000)
			
 
				-
			
 
				-  it('commits exactly the fixtures it reads', async () => {
			
 
				-    // No model calls, so no replay log: the golden is the whole inventory.
			
 
				-    await assertFixtureInventory(SNAPSHOT_DIR, ['geometry.expected.md'])
			
 
				-  })
			
 
				-
			
 
				-  it.skipIf(MODE === 'record')('issued zero model calls and stayed clean', () => {
			
 
				-    expect(tripwire.warnings).toEqual([])
			
 
				-    expect(tripwire.pageErrors).toEqual([])
			
 
				-  })
			
 
				-})
			
--- a/apps/web/tests/default-model.e2e.ts
+++ b/apps/web/tests/default-model.e2e.ts
@@ -148,7 +148,7 @@ describe('web e2e: the composer model switch is the default for later sessions',
 
				       sessionId: SessionId(await createSession('default-model-refusal')),
			
 
				       mode: 'queue',
			
 
				       content: [{ type: 'text', text: 'hi' }],
			
 
				-    }, new AbortController().signal)).rejects.toMatchObject({ failure: { code: 'model-unavailable' } })
			
 
				+    }, new AbortController().signal)).rejects.toMatchObject({ code: 'session/model-unavailable' })
			
 
				 
			
 
				     // The way out stays open. Locking the model seat with everything else
			
 
				     // would leave the composer asking for the one thing it prevents.
			
--- a/apps/web/tests/expected/composer-tab-geometry/geometry.expected.md
+++ b/apps/web/tests/expected/composer-tab-geometry/geometry.expected.md
@@ -2,7 +2,7 @@
 
				 
			
 
				 ## Wide viewport (1680px, card at its cap)
			
 
				 
			
 
				-- Chat: scrollbar-gutter stable, overflow hidden/auto
			
 
				+- Chat: scrollbar-gutter stable, overflow auto/auto
			
 
				 - Chat scroller scrolls: true
			
 
				 - Chat reserved band: 8px
			
 
				 - Trajectory: scrollbar-gutter auto, overflow hidden/auto
			
@@ -14,7 +14,7 @@
 
				 
			
 
				 ## Narrow viewport (800px, card shrinking with the column)
			
 
				 
			
 
				-- Chat: scrollbar-gutter stable, overflow hidden/auto
			
 
				+- Chat: scrollbar-gutter stable, overflow auto/auto
			
 
				 - Chat scroller scrolls: true
			
 
				 - Chat reserved band: 8px
			
 
				 - Trajectory: scrollbar-gutter auto, overflow hidden/auto
			
@@ -26,7 +26,7 @@
 
				 
			
 
				 ## Wide viewport, seat compensation removed in the page (control)
			
 
				 
			
 
				-- Chat: scrollbar-gutter stable, overflow hidden/auto
			
 
				+- Chat: scrollbar-gutter stable, overflow auto/auto
			
 
				 - Chat scroller scrolls: true
			
 
				 - Chat reserved band: 8px
			
 
				 - Trajectory: scrollbar-gutter auto, overflow hidden/auto
			
--- a/apps/web/tests/expected/conversation-column-overflow/geometry.expected.md
+++ b/apps/web/tests/expected/conversation-column-overflow/geometry.expected.md
@@ -1,9 +0,0 @@
 
				-# Conversation column horizontal overflow
			
 
				-
			
 
				-| viewport | overflow-x | glow bleeds past the column | scrollLeft after a horizontal wheel | scrolls vertically |
			
 
				-| --- | --- | --- | --- | --- |
			
 
				-| 1680px | hidden | false | 0px | true |
			
 
				-| 1200px | hidden | true | 0px | true |
			
 
				-| 1000px | hidden | true | 0px | true |
			
 
				-| 800px | hidden | true | 0px | true |
			
 
				-| 600px | hidden | true | 0px | true |
			
--- a/apps/web/tests/expected/github-ready-review/conversation-expanded.expected.md
+++ b/apps/web/tests/expected/github-ready-review/conversation-expanded.expected.md
@@ -44,7 +44,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: {{clock}} Ran for {{duration}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: {{clock}}
			
 
				 - textbox "Message or run a task... / commands, @ files or sessions"
			
 
				 - button "Commands":
			
 
				   - img
			
--- a/apps/web/tests/expected/github-ready-review/conversation.expected.md
+++ b/apps/web/tests/expected/github-ready-review/conversation.expected.md
@@ -36,7 +36,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: {{clock}} Ran for {{duration}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: {{clock}}
			
 
				 - textbox "Message or run a task... / commands, @ files or sessions"
			
 
				 - button "Commands":
			
 
				   - img
			
--- a/apps/web/tests/expected/markdown-cjk-strong/ui.expected.md
+++ b/apps/web/tests/expected/markdown-cjk-strong/ui.expected.md
@@ -44,7 +44,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: {{clock}} Ran for {{duration}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: {{clock}}
			
 
				 - textbox "Message or run a task... / commands, @ files or sessions"
			
 
				 - button "Commands":
			
 
				   - img
			
--- a/apps/web/tests/expected/markdown-images/ui.expected.md
+++ b/apps/web/tests/expected/markdown-images/ui.expected.md
@@ -23,7 +23,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: {{clock}} Ran for {{duration}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: {{clock}}
			
 
				 - textbox "Message or run a task... / commands, @ files or sessions"
			
 
				 - button "Commands":
			
 
				   - img
			
--- a/apps/web/tests/expected/markdown-inline-code-links/ui.expected.md
+++ b/apps/web/tests/expected/markdown-inline-code-links/ui.expected.md
@@ -35,7 +35,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: {{clock}} Ran for {{duration}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: {{clock}}
			
 
				 - textbox "Message or run a task... / commands, @ files or sessions"
			
 
				 - button "Commands":
			
 
				   - img
			
--- a/apps/web/tests/expected/math-rendering/ui.expected.md
+++ b/apps/web/tests/expected/math-rendering/ui.expected.md
@@ -39,7 +39,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: {{clock}} Ran for {{duration}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: {{clock}}
			
 
				 - textbox "Message or run a task... / commands, @ files or sessions"
			
 
				 - button "Commands":
			
 
				   - img
			
--- a/apps/web/tests/expected/skill-user-invoke/ui-expanded.expected.md
+++ b/apps/web/tests/expected/skill-user-invoke/ui-expanded.expected.md
@@ -36,7 +36,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: {{clock}}
			
 
				 - textbox "Message or run a task... / commands, @ files or sessions"
			
 
				 - button "Commands":
			
 
				   - img
			
--- a/apps/web/tests/expected/skill-user-invoke/ui.expected.md
+++ b/apps/web/tests/expected/skill-user-invoke/ui.expected.md
@@ -28,7 +28,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: {{clock}}
			
 
				 - textbox "Message or run a task... / commands, @ files or sessions"
			
 
				 - button "Commands":
			
 
				   - img
			
--- a/apps/web/tests/expected/stats-paged-history/ui.expected.md
+++ b/apps/web/tests/expected/stats-paged-history/ui.expected.md
@@ -48,7 +48,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m2 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m2 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r2
			
@@ -60,7 +63,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m3 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m3 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r3
			
@@ -72,7 +78,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m4 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m4 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r4
			
@@ -84,7 +93,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m5 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m5 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r5
			
@@ -96,7 +108,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m6 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m6 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r6
			
@@ -108,7 +123,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m7 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m7 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r7
			
@@ -120,7 +138,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m8 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m8 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r8
			
@@ -132,7 +153,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m9 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m9 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r9
			
@@ -144,7 +168,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m10 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m10 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r10
			
@@ -156,7 +183,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m11 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m11 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r11
			
@@ -168,7 +198,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m12 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m12 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r12
			
@@ -180,7 +213,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m13 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m13 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r13
			
@@ -192,7 +228,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m14 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m14 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r14
			
@@ -204,7 +243,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m15 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m15 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r15
			
@@ -216,7 +258,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m16 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m16 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r16
			
@@ -228,7 +273,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m17 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m17 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r17
			
@@ -240,7 +288,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m18 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m18 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r18
			
@@ -252,7 +303,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m19 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m19 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r19
			
@@ -264,7 +318,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m20 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m20 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r20
			
@@ -276,7 +333,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m21 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m21 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r21
			
@@ -288,7 +348,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m22 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m22 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r22
			
@@ -300,7 +363,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m23 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m23 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r23
			
@@ -312,7 +378,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m24 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m24 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r24
			
@@ -324,7 +393,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m25 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m25 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r25
			
@@ -336,7 +408,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m26 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m26 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r26
			
@@ -348,7 +423,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m27 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m27 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r27
			
@@ -360,7 +438,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}} m28 7/25 {{clock}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}} m28 7/25 {{clock}}
			
 
				 - button "Copy":
			
 
				   - img
			
 
				 - paragraph: r28
			
@@ -372,7 +453,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: 7/25 {{clock}} Ran for {{duration}}
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: 7/25 {{clock}}
			
 
				 - button "Back to bottom":
			
 
				   - img
			
 
				 - textbox "Message or run a task... / commands, @ files or sessions"
			
--- a/apps/web/tests/expected/steer-all/settled-expanded.expected.md
+++ b/apps/web/tests/expected/steer-all/settled-expanded.expected.md
@@ -46,7 +46,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: {{clock}}
			
 
				 - textbox "Message or run a task... / commands, @ files or sessions"
			
 
				 - button "Commands":
			
 
				   - img
			
--- a/apps/web/tests/expected/steer-all/settled.expected.md
+++ b/apps/web/tests/expected/steer-all/settled.expected.md
@@ -34,7 +34,10 @@
 
				   - img
			
 
				 - button "Branch into a new conversation":
			
 
				   - img
			
 
				-- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
			
 
				+- button "Ran for {{duration}}":
			
 
				+  - img
			
 
				+  - text: Ran for {{duration}}
			
 
				+- text: {{clock}}
			
 
				 - textbox "Message or run a task... / commands, @ files or sessions"
			
 
				 - button "Commands":
			
 
				   - img
			
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -3,7 +3,7 @@
 
				 // One tiny recorded turn (text-only) drives the whole spec: the empty-state
			
 
				 // hero materializes a real Workspace + Session on first send (the jsdom
			
 
				 // workspace-flow suite pins the object-layer state machine over the fixture
			
 
				-// client; THIS spec pins the same flow through HTTP RPC + SSE + the host
			
 
				+// client; THIS spec pins the same flow through HTTP RPC + WebSocket + the host
			
 
				 // gateway), reload replays everything from the log (zero further model
			
 
				 // calls), and the theme scenario proves the shipped dark palette actually
			
 
				 // cascades: attribute -> alias token flip -> painted surface change. No
			
@@ -13,7 +13,7 @@
 
				 import { readFile } from 'node:fs/promises'
			
 
				 import { fileURLToPath } from 'node:url'
			
 
				 import { join } from 'node:path'
			
 
				-import type { Browser, Page } from 'playwright'
			
 
				+import type { Browser, Page, WebSocketRoute } from 'playwright'
			
 
				 import { chromium } from 'playwright'
			
 
				 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
			
 
				 import type { SessionEvent } from '@deepseek-ai/dsh-session'
			
@@ -22,7 +22,9 @@ import {
 
				   captureStableAria, compareOrRefreshGolden, fixtureUserPrompts,
			
 
				   launchWebScaffold, recordFixture, watchConsole, webSnapshotMode, type WebScaffold,
			
 
				 } from './scaffold.ts'
			
 
				-import { connectFreshWorkspace, newEnglishPage, saveFailureShot, writeComposerDraft } from './support.ts'
			
 
				+import {
			
 
				+  connectFreshWorkspace, newEnglishPage, saveFailureShot, writeComposerDraft,
			
 
				+} from './support.ts'
			
 
				 
			
 
				 const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/lifecycle-chrome', import.meta.url))
			
 
				 const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl')
			
@@ -31,6 +33,7 @@ const HERO_EXPECTED = join(SNAPSHOT_DIR, 'hero.expected.md')
 
				 const COMMAND_MENU_EXPECTED = join(SNAPSHOT_DIR, 'command-menu.expected.md')
			
 
				 const FUZZY_COMMAND_MENU_EXPECTED = join(SNAPSHOT_DIR, 'command-menu-fuzzy.expected.md')
			
 
				 const PLAN_ACTIVE_EXPECTED = join(SNAPSHOT_DIR, 'plan-active.expected.md')
			
 
				+const CONNECTION_ERROR_EXPECTED = join(SNAPSHOT_DIR, 'connection-error.expected.md')
			
 
				 // Post-reload golden: the same settled conversation rebuilt purely from
			
 
				 // persistence + history — byte-equal rendering is exactly the recovery claim.
			
 
				 const RELOADED_EXPECTED = join(SNAPSHOT_DIR, 'reloaded.expected.md')
			
@@ -282,12 +285,138 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
 
				     expect(tripwire.pageErrors).toEqual([])
			
 
				   }, 60_000)
			
 
				 
			
 
				+  it.skipIf(MODE === 'record')('shows automatic and user-requested connection recovery beside Settings', async () => {
			
 
				+    const recoveryPage = await newEnglishPage(browser)
			
 
				+    const recoveryTripwire = watchConsole(recoveryPage)
			
 
				+    const sockets: WebSocketRoute[] = []
			
 
				+    let rejectConnections = false
			
 
				+    await recoveryPage.routeWebSocket('**/api/remote.mux', (route) => {
			
 
				+      sockets.push(route)
			
 
				+      if (rejectConnections) {
			
 
				+        void route.close({ code: 4001, reason: 'connection recovery test' })
			
 
				+        return
			
 
				+      }
			
 
				+      route.connectToServer()
			
 
				+    })
			
 
				+    onTestFailed(() => saveFailureShot(recoveryPage, 'web-e2e-connection-recovery'))
			
 
				+    try {
			
 
				+      await recoveryPage.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
			
 
				+      await recoveryPage.waitForSelector('[class*="frame"]', { timeout: 30_000 })
			
 
				+      await expect.poll(() => sockets.length).toBe(1)
			
 
				+      rejectConnections = true
			
 
				+      await recoveryPage.context().setOffline(true)
			
 
				+      await expect.poll(() => recoveryPage.evaluate(() => navigator.onLine)).toBe(false)
			
 
				+      const offline = recoveryPage.getByRole('button', {
			
 
				+        name: 'Disconnected, reconnect now', exact: true,
			
 
				+      })
			
 
				+      await offline.waitFor({ timeout: 2_000 })
			
 
				+      await recoveryPage.waitForTimeout(750)
			
 
				+      expect(sockets).toHaveLength(1)
			
 
				+
			
 
				+      await recoveryPage.context().setOffline(false)
			
 
				+      await expect.poll(() => recoveryPage.evaluate(() => navigator.onLine)).toBe(true)
			
 
				+      const connecting = recoveryPage.getByRole('button', {
			
 
				+        name: 'Connecting, restart now', exact: true,
			
 
				+      })
			
 
				+      await connecting.waitFor({ timeout: 10_000 })
			
 
				+      expect(await connecting.innerText()).toMatch(/^Connecting\.{1,3}$/)
			
 
				+      const connectingGeometry = await connectionIndicatorGeometry(connecting)
			
 
				+      expect(await connectionIndicatorTextAlignment(connecting)).toBe('left')
			
 
				+      await connecting.hover()
			
 
				+      expect(await connecting.innerText()).toBe('Reconnect now')
			
 
				+      expect(await connectionIndicatorGeometry(connecting)).toEqual(connectingGeometry)
			
 
				+      await recoveryPage.mouse.move(0, 0)
			
 
				+
			
 
				+      await expect.poll(() => sockets.length, { timeout: 40_000 }).toBe(7)
			
 
				+      const indicator = recoveryPage.getByRole('button', {
			
 
				+        name: 'Disconnected, reconnect now', exact: true,
			
 
				+      })
			
 
				+      await indicator.waitFor({ timeout: 10_000 })
			
 
				+      expect(await connectionIndicatorGeometry(indicator)).toEqual(connectingGeometry)
			
 
				+      expect(await connectionIndicatorTextAlignment(indicator)).toBe('left')
			
 
				+      const snapshot = await captureStableAria(recoveryPage, '[class*="footArea"]', scaffold.workspaceCwd)
			
 
				+      await compareOrRefreshGolden(CONNECTION_ERROR_EXPECTED, snapshot, MODE)
			
 
				+      const style = await indicator.evaluate((element) => {
			
 
				+        const probe = document.createElement('span')
			
 
				+        probe.style.color = 'var(--dsw-alias-state-warn-label)'
			
 
				+        probe.style.backgroundColor = 'var(--dsw-alias-state-warn-tertiary)'
			
 
				+        document.body.append(probe)
			
 
				+        const actual = getComputedStyle(element)
			
 
				+        const reference = getComputedStyle(probe)
			
 
				+        const result = {
			
 
				+          background: actual.backgroundColor,
			
 
				+          color: actual.color,
			
 
				+          referenceBackground: reference.backgroundColor,
			
 
				+          referenceColor: reference.color,
			
 
				+        }
			
 
				+        probe.remove()
			
 
				+        return result
			
 
				+      })
			
 
				+      expect(style.background).toBe(style.referenceBackground)
			
 
				+      expect(style.color).toBe(style.referenceColor)
			
 
				+      expect(await indicator.locator('svg').count()).toBe(1)
			
 
				+      expect(await indicator.getAttribute('title')).toBeNull()
			
 
				+      const idleBackground = await indicator.evaluate(element => getComputedStyle(element).backgroundColor)
			
 
				+      await indicator.hover()
			
 
				+      expect(await indicator.innerText()).toBe('Reconnect now')
			
 
				+      const hoverBackground = await indicator.evaluate(element => getComputedStyle(element).backgroundColor)
			
 
				+      expect(hoverBackground).toBe(idleBackground)
			
 
				+      await recoveryPage.mouse.down()
			
 
				+      await expect.poll(() => indicator.evaluate(element => getComputedStyle(element).backgroundColor))
			
 
				+        .not.toBe(hoverBackground)
			
 
				+      rejectConnections = false
			
 
				+      await recoveryPage.mouse.up()
			
 
				+
			
 
				+      await expect.poll(() => sockets.length).toBe(8)
			
 
				+      const recovered = recoveryPage.getByRole('status')
			
 
				+      await recovered.waitFor({ timeout: 10_000 })
			
 
				+      expect(await recovered.innerText()).toBe('Connected')
			
 
				+      expect(await connectionIndicatorGeometry(recovered)).toEqual(connectingGeometry)
			
 
				+      expect(await connectionIndicatorTextAlignment(recovered)).toBe('left')
			
 
				+      await recovered.waitFor({ state: 'detached', timeout: 5_000 })
			
 
				+      expect(recoveryTripwire.pageErrors).toEqual([])
			
 
				+      expect(recoveryTripwire.warnings.filter(warning => /connection lost, retry #[1-6]/i.test(warning)))
			
 
				+        .toHaveLength(7)
			
 
				+    } finally {
			
 
				+      await recoveryPage.close()
			
 
				+    }
			
 
				+  }, 60_000)
			
 
				+
			
 
				   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
			
 
				     expect(tripwire.warnings).toEqual([])
			
 
				     await assertFixtureInventory(SNAPSHOT_DIR, [
			
 
				       'session.jsonl', 'replay.override.json', 'command-menu.expected.md',
			
 
				-      'command-menu-fuzzy.expected.md', 'hero.expected.md', 'plan-active.expected.md',
			
 
				+      'command-menu-fuzzy.expected.md', 'connection-error.expected.md', 'hero.expected.md', 'plan-active.expected.md',
			
 
				       'reloaded.expected.md', 'reloaded-expanded.expected.md',
			
 
				     ])
			
 
				   })
			
 
				 })
			
 
				+
			
 
				+async function connectionIndicatorGeometry(locator: ReturnType<Page['getByRole']>): Promise<{
			
 
				+  readonly outer: readonly number[]
			
 
				+  readonly icon: readonly number[]
			
 
				+  readonly label: readonly number[]
			
 
				+}> {
			
 
				+  return await locator.evaluate((element) => {
			
 
				+    const outer = element.getBoundingClientRect()
			
 
				+    const icon = element.children.item(0)?.getBoundingClientRect()
			
 
				+    const label = element.children.item(1)?.getBoundingClientRect()
			
 
				+    if (icon === undefined || label === undefined) throw new Error('connection indicator children missing')
			
 
				+    const rounded = (values: readonly number[]): readonly number[] => values.map(value => Math.round(value * 100) / 100)
			
 
				+    return {
			
 
				+      outer: rounded([outer.x, outer.y, outer.width, outer.height]),
			
 
				+      icon: rounded([icon.x - outer.x, icon.y - outer.y, icon.width, icon.height]),
			
 
				+      label: rounded([label.x - outer.x, label.y - outer.y, label.width, label.height]),
			
 
				+    }
			
 
				+  })
			
 
				+}
			
 
				+
			
 
				+async function connectionIndicatorTextAlignment(
			
 
				+  locator: ReturnType<Page['getByRole']>,
			
 
				+): Promise<string> {
			
 
				+  return await locator.evaluate((element) => {
			
 
				+    const label = element.children.item(1)
			
 
				+    if (label === null) throw new Error('connection indicator label missing')
			
 
				+    return getComputedStyle(label).textAlign
			
 
				+  })
			
 
				+}
			
--- a/apps/web/tests/reference-composer.e2e.ts
+++ b/apps/web/tests/reference-composer.e2e.ts
@@ -166,6 +166,12 @@ describe.skipIf(MODE === 'record')('web e2e: file and session references through
 
				     expect(snapshot).not.toContain('text: Subagents')
			
 
				 
			
 
				     await input.fill('@reference')
			
 
				+    // The open menu keeps the previous query's rows while the new one loads
			
 
				+    // (stale-while-revalidate), and rows are keyed by index, so a click
			
 
				+    // resolved against a stale row lands on whatever settles into that slot.
			
 
				+    // `folderx/` matches only the bare '@' query: its disappearance marks the
			
 
				+    // settled result set.
			
 
				+    await expect.poll(() => menu.getByRole('option', { name: /folderx/ }).count(), { timeout: 15_000 }).toBe(0)
			
 
				     await menu.getByRole('option', { name: /reference\.txt/ }).click()
			
 
				     // The pick lands an atomic chip: a real DOM capsule carrying the domain
			
 
				     // icon and the label (the canonical reference text lives on the node and
			
--- a/apps/web/tests/turn-tail-actions.e2e.ts
+++ b/apps/web/tests/turn-tail-actions.e2e.ts
@@ -170,18 +170,37 @@ describe('web e2e: assistant IconActions wait for the turn to end', () => {
 
				     const { settled } = await sendPrompt(120_000)
			
 
				     await settled
			
 
				 
			
 
				-    const disclosure = page.getByRole('button', { name: /Turn usage/ })
			
 
				-    await expect.poll(() => disclosure.count(), { timeout: 10_000 }).toBe(1)
			
 
				-    expect(await disclosure.getAttribute('aria-expanded')).toBe('false')
			
 
				-    expect(await page.getByText('15.8K tok · Cache hit 49.7%', { exact: true }).count()).toBe(1)
			
 
				+    const trigger = page.getByRole('button', { name: /Usage 15\.8K tok/ })
			
 
				+    await expect.poll(() => trigger.count(), { timeout: 10_000 }).toBe(1)
			
 
				+    expect(await trigger.getAttribute('aria-expanded')).toBe('false')
			
 
				+    // The usage pill carries the icon and the turn total; the time pill beside
			
 
				+    // it carries the run time, and both keep their details dialog-only.
			
 
				+    expect(await trigger.textContent()).toBe('Usage 15.8K tok')
			
 
				+    const timeTrigger = page.getByRole('button', { name: /^Ran for \S+$/ })
			
 
				+    expect(await timeTrigger.count()).toBe(1)
			
 
				+    expect(await page.locator('[data-turn-tail]').getByText(/tok\/s|TTFT/).count()).toBe(0)
			
 
				+    expect(await page.getByRole('dialog').count()).toBe(0)
			
 
				 
			
 
				-    await disclosure.click()
			
 
				-    expect(await disclosure.getAttribute('aria-expanded')).toBe('true')
			
 
				-    expect(await page.getByText('deepseek-official/deepseek-v4-flash', { exact: true }).count()).toBe(1)
			
 
				-    expect(await page.getByText('7,891 tok', { exact: true }).count()).toBe(1)
			
 
				-    expect(await page.getByText('7,808 tok', { exact: true }).count()).toBe(1)
			
 
				-    expect(await page.getByText('112 tok (42 tok reasoning)', { exact: true }).count()).toBe(1)
			
 
				-    expect(await page.getByText('15,811 tok', { exact: true }).count()).toBe(1)
			
 
				+    await trigger.click()
			
 
				+    expect(await trigger.getAttribute('aria-expanded')).toBe('true')
			
 
				+    const dialog = page.getByRole('dialog', { name: 'Turn usage' })
			
 
				+    expect(await dialog.count()).toBe(1)
			
 
				+    expect(await dialog.getByText('deepseek-official/deepseek-v4-flash', { exact: true }).count()).toBe(1)
			
 
				+    expect(await dialog.getByText('49.7%', { exact: true }).count()).toBe(1)
			
 
				+    expect(await dialog.getByText('7,891 tok', { exact: true }).count()).toBe(1)
			
 
				+    expect(await dialog.getByText('7,808 tok', { exact: true }).count()).toBe(1)
			
 
				+    expect(await dialog.getByText('112 tok (42 tok reasoning)', { exact: true }).count()).toBe(1)
			
 
				+    expect(await dialog.getByText('15,811 tok', { exact: true }).count()).toBe(1)
			
 
				+    await page.keyboard.press('Escape')
			
 
				+    expect(await page.getByRole('dialog').count()).toBe(0)
			
 
				+
			
 
				+    await timeTrigger.click()
			
 
				+    const timeDialog = page.getByRole('dialog', { name: 'Turn time and speed' })
			
 
				+    expect(await timeDialog.count()).toBe(1)
			
 
				+    expect(await timeDialog.getByText(/tok\/s/).count()).toBe(1)
			
 
				+    expect(await timeDialog.getByText('Time to first token (TTFT)', { exact: true }).count()).toBe(1)
			
 
				+    await page.keyboard.press('Escape')
			
 
				+    await trigger.click()
			
 
				 
			
 
				     const expanded = await captureStableAria(page, '[class*="centerCol"]', scaffold!.workspaceCwd)
			
 
				     await compareOrRefreshGolden(USAGE_EXPANDED_EXPECTED, expanded, MODE)
			
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -54,7 +54,7 @@ When the gate goes red:
 
				 2. **Condense** content that belongs here but can be shorter.
			
 
				 3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
			
 
				 
			
 
				-Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 675 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,150, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
			
 
				+Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
			
 
				 
			
 
				 ## The slop checklist
			
 
				 
			
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write docs/api-gateway.md
			
 
				-api-gateway.md: 43b00bcff3da0adb1d53ac25534b65366bc42611
			
 
				-api-gateway.zh.md: bb2711220fd75ef0119e1188c22a0af5ad4169a8
			
 
				+api-gateway.md: 92d1bb5f0103fd4e2424992de9445f4768346f91
			
 
				+api-gateway.zh.md: 3c3d95a5c125c592baf21579fb724101708b5cf8
			
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -124,7 +124,7 @@ The Connection performs the unified trust check for `/api` before the HTTP bridg
 
				 
			
 
				 For every call, the Gateway resolves the descriptor and live service from the current registries instead of caching business objects. It requires the fields in `args` to match the descriptor exactly, validates wire values with codecs, resolves objects or receivers through registered lookup or Context providers, invokes the service method targeted by the binding, and validates the return value. A missing provider, unknown identity, binding mismatch, missing or extra argument, schema failure, or missing method fails before entering or after leaving business code.
			
 
				 
			
 
				-The lookup provider's `register()` supplies both the stable declaration and the default resolver; `configure()` supplies a resolver owned by Host composition that may execute asynchronously and is scoped to an effect lifetime. Configuration may precede provider mounting; without a provider, invocation still fails with `lookup-unavailable`, and unloading the configuration restores the provider's default policy. The Session Controller owns the standard `agentFor()` semantics for `agent` and `session`: it reuses a live Agent, automatically resumes ordinary cold sessions, deduplicates concurrent resumes, and rejects identities owned by subagent routing; the `session` lookup returns that Agent's Session. Resume failures and ownership fences pass through unchanged as existing RPC errors rather than being collapsed into the Gateway's `internal` error.
			
 
				+The lookup provider's `register()` supplies both the stable declaration and the default resolver; `configure()` supplies a resolver owned by Host composition that may execute asynchronously and is scoped to an effect lifetime. Configuration may precede provider mounting; without a provider, invocation still fails with `gateway/lookup-unavailable`, and unloading the configuration restores the provider's default policy. The Session Controller owns the standard resolver semantics for `agent` and `session`: it reuses a live Agent, automatically resumes ordinary cold sessions, deduplicates concurrent resumes, and rejects identities owned by subagent routing; the `session` lookup returns that Agent's Session. A resume failure and an ownership fence raise a `RemoteError` carrying their own code, `session/not-found` or `session/agent-busy`, which the Gateway encodes onto the wire unchanged; only an unclassified throw folds into `gateway/internal`.
			
 
				 
			
 
				 Unloading a Client contribution removes its descriptors and concrete methods together, aborts its in-flight calls, and makes stale method handles retained by external code reject further calls. A strict endpoint withdrawn on the Host also does not degrade to SRC inference, preventing a hot unload from silently weakening validation.
			
 
				 
			
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -124,7 +124,7 @@ Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共
 
				 
			
 
				 Gateway 每次调用都从当前注册表解析描述符和实时服务，不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致，先用 codec 校验 wire 值，再通过注册的 lookup 或 Context 提供方解析对象或接收者，最后调用 binding 指向的服务方法并校验返回值。缺少提供方、identity 未命中、binding 不一致、参数缺失或多余、schema 失败和方法不存在都会在进入业务代码前或离开业务代码后失败。
			
 
				 
			
 
				-lookup 提供方的 `register()` 同时提供稳定声明和默认 resolver；`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于提供方挂载；没有提供方时调用仍以 `lookup-unavailable` 失败，配置卸载后则恢复提供方默认策略。Session Controller 负责 `agent` 与 `session` 的标准 `agentFor()` 语义：复用 live Agent，自动恢复普通冷会话，对并发恢复去重，并拒绝由 subagent routing 拥有的 identity；`session` lookup 返回该 Agent 的 Session。恢复失败和 ownership fence 通过既有 RPC error 原样返回，不折叠为 Gateway 的 `internal` 错误。
			
 
				+lookup 提供方的 `register()` 同时提供稳定声明和默认 resolver；`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于提供方挂载；没有提供方时调用仍以 `gateway/lookup-unavailable` 失败，配置卸载后则恢复提供方默认策略。Session Controller 负责 `agent` 与 `session` 的标准 resolver 语义：复用 live Agent，自动恢复普通冷会话，对并发恢复去重，并拒绝由 subagent routing 拥有的 identity；`session` lookup 返回该 Agent 的 Session。恢复失败与 ownership fence 抛出携带自有码的 `RemoteError`（`session/not-found` 或 `session/agent-busy`），Gateway 原样编码上 wire；只有未归类的 throw 才折成 `gateway/internal`。
			
 
				 
			
 
				 Client 卸载一个贡献时会一起移除描述符和具体方法，中止其进行中的调用，并使外部仍持有的陈旧方法句柄拒绝继续调用。Host 上已经注册过的严格 endpoint 被撤回后也不会降级到 SRC 推断，以免热卸载悄然降低校验强度。
			
 
				 
			
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
			
 
				-config-catalog.md: 4909347c5f2648962b74a7965d1e7dd18521f3b7
			
 
				-config-catalog.zh.md: 98270d431a601058341eb1b5dfbb59ea4505a15e
			
 
				+config-catalog.md: d968108ae652a10007a9c00595a955cefeb37f3b
			
 
				+config-catalog.zh.md: 16f33ee3934c82a94c07fa7c406665465b1decbf
			
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -157,7 +157,7 @@ export interface PresetRoot {
 
				 export type PresetTrust = 'system' | 'user'
			
 
				 ```
			
 
				 
			
 
				-Source: [`packages/preset/agent-presets/src/preset.ts:54`](../packages/preset/agent-presets/src/preset.ts)
			
 
				+Source: [`packages/preset/agent-presets/src/preset.ts:52`](../packages/preset/agent-presets/src/preset.ts)
			
 
				 
			
 
				 <a id="deepseek-aidsh-agent-spine-demo"></a>
			
 
				 
			
@@ -285,12 +285,12 @@ Requires: `typert`
 
				 ```ts config-catalog
			
 
				 /** Gateway transport configuration. */
			
 
				 export interface Config {
			
 
				-  /** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 30000 */
			
 
				+  /** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 2000 */
			
 
				   readonly websocketHeartbeatIntervalMs?: number
			
 
				 }
			
 
				 ```
			
 
				 
			
 
				-Source: [`packages/api/gateway/src/index.ts:118`](../packages/api/gateway/src/index.ts)
			
 
				+Source: [`packages/api/gateway/src/index.ts:119`](../packages/api/gateway/src/index.ts)
			
 
				 
			
 
				 <a id="deepseek-aidsh-api-session-controller"></a>
			
 
				 
			
@@ -322,7 +322,7 @@ export interface Config {
 
				 }
			
 
				 ```
			
 
				 
			
 
				-Source: [`packages/api/settings-controller/src/index.ts:41`](../packages/api/settings-controller/src/index.ts)
			
 
				+Source: [`packages/api/settings-controller/src/index.ts:37`](../packages/api/settings-controller/src/index.ts)
			
 
				 
			
 
				 <a id="deepseek-aidsh-attachment-local"></a>
			
 
				 
			
@@ -3550,5 +3550,6 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 
				 - `@deepseek-ai/dsh-typert-protocol` ([`packages/typert/protocol/src/index.ts`](../packages/typert/protocol/src/index.ts))
			
 
				 - `@deepseek-ai/dsh-typert-registry` ([`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts))
			
 
				 - `@deepseek-ai/dsh-util-crypto` ([`packages/util/crypto/src/index.ts`](../packages/util/crypto/src/index.ts))
			
 
				+- `@deepseek-ai/dsh-util-time` ([`packages/util/time/src/index.ts`](../packages/util/time/src/index.ts))
			
 
				 - `@deepseek-ai/dsh-util-workspace-path` ([`packages/util/workspace-path/src/index.ts`](../packages/util/workspace-path/src/index.ts))
			
 
				 - `@deepseek-ai/dsh-win32-process` ([`packages/subprocess/win32-process/src/index.ts`](../packages/subprocess/win32-process/src/index.ts))
			
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -159,7 +159,7 @@ export interface PresetRoot {
 
				 export type PresetTrust = 'system' | 'user'
			
 
				 ```
			
 
				 
			
 
				-来源：[`packages/preset/agent-presets/src/preset.ts:54`](../packages/preset/agent-presets/src/preset.ts)
			
 
				+来源：[`packages/preset/agent-presets/src/preset.ts:52`](../packages/preset/agent-presets/src/preset.ts)
			
 
				 
			
 
				 <a id="deepseek-aidsh-agent-spine-demo"></a>
			
 
				 
			
@@ -287,12 +287,12 @@ export interface Config {
 
				 ```ts config-catalog
			
 
				 /** Gateway transport configuration. */
			
 
				 export interface Config {
			
 
				-  /** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 30000 */
			
 
				+  /** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 2000 */
			
 
				   readonly websocketHeartbeatIntervalMs?: number
			
 
				 }
			
 
				 ```
			
 
				 
			
 
				-来源：[`packages/api/gateway/src/index.ts:118`](../packages/api/gateway/src/index.ts)
			
 
				+来源：[`packages/api/gateway/src/index.ts:119`](../packages/api/gateway/src/index.ts)
			
 
				 
			
 
				 <a id="deepseek-aidsh-api-session-controller"></a>
			
 
				 
			
@@ -324,7 +324,7 @@ export interface Config {
 
				 }
			
 
				 ```
			
 
				 
			
 
				-来源：[`packages/api/settings-controller/src/index.ts:41`](../packages/api/settings-controller/src/index.ts)
			
 
				+来源：[`packages/api/settings-controller/src/index.ts:37`](../packages/api/settings-controller/src/index.ts)
			
 
				 
			
 
				 <a id="deepseek-aidsh-attachment-local"></a>
			
 
				 
			
@@ -3551,5 +3551,6 @@ export interface Config {
 
				 - `@deepseek-ai/dsh-typert-protocol`（[`packages/typert/protocol/src/index.ts`](../packages/typert/protocol/src/index.ts)）
			
 
				 - `@deepseek-ai/dsh-typert-registry`（[`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts)）
			
 
				 - `@deepseek-ai/dsh-util-crypto`（[`packages/util/crypto/src/index.ts`](../packages/util/crypto/src/index.ts)）
			
 
				+- `@deepseek-ai/dsh-util-time`（[`packages/util/time/src/index.ts`](../packages/util/time/src/index.ts)）
			
 
				 - `@deepseek-ai/dsh-util-workspace-path`（[`packages/util/workspace-path/src/index.ts`](../packages/util/workspace-path/src/index.ts)）
			
 
				 - `@deepseek-ai/dsh-win32-process`（[`packages/subprocess/win32-process/src/index.ts`](../packages/subprocess/win32-process/src/index.ts)）
			
--- a/docs/cookbook/adding-a-remote-api.i18n.yaml
+++ b/docs/cookbook/adding-a-remote-api.i18n.yaml
@@ -0,0 +1,6 @@
 
				+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
			
 
				+# side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				+# after editing either side, bring the other along and re-record with:
			
 
				+#   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-remote-api.md
			
 
				+adding-a-remote-api.md: 0f89101e9bc3ff961d465c109f033150e93e04f6
			
 
				+adding-a-remote-api.zh.md: 0c5a57b539ecd98cb88790260a3fb8e7b41afff6
			
--- a/docs/cookbook/adding-a-remote-api.md
+++ b/docs/cookbook/adding-a-remote-api.md
@@ -0,0 +1,197 @@
 
				+# Cookbook: adding a Remote API
			
 
				+
			
 
				+English | [中文](adding-a-remote-api.zh.md)
			
 
				+
			
 
				+Adding or changing a `ctx.remote` endpoint takes the five steps on this page: declare the method, declare its failures, register it on the package, consume it on the Client, and test it. Decorator semantics, lookup resolution, the generation pipeline, and the `/api` route are the mechanism and belong to the [API Gateway reference](../api-gateway.md); this page gives the action for each step and the conventions it must satisfy. Why the programming interface looks like this is in the [Typert Remote method calls Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md), and why a failure is one `RemoteError` plus a code table is in the [failure vocabulary Agent Note](../../.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.md).
			
 
				+
			
 
				+## 1. Declare the API
			
 
				+
			
 
				+The owner is a Host-side Cordis service: extend `TypertRemoteService` so the service key and the wire namespace are bound together, then mark the exposed methods with `@Remote`. Mark the business method itself when its signature already satisfies the wire conventions; write a `remoteExport*` adapter only when the shape has to change (adding `signal`, reordering parameters, exporting another name), and let that adapter call the unrenamed business method. Lookup objects (`Agent`, `Session`) may only occupy top-level parameter positions, and a method that supports cooperative cancellation takes `signal: AbortSignal` as its final parameter.
			
 
				+
			
 
				+```ts
			
 
				+import type { Context } from '@deepseek-ai/cordis'
			
 
				+import type { Agent } from '@deepseek-ai/dsh-agent'
			
 
				+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
			
 
				+
			
 
				+/** One stored note as a Client reads it. */
			
 
				+export interface NoteRow {
			
 
				+  readonly noteId: string
			
 
				+  readonly title: string
			
 
				+}
			
 
				+
			
 
				+declare module '@deepseek-ai/cordis' {
			
 
				+  interface Context {
			
 
				+    notesController: NotesController
			
 
				+  }
			
 
				+}
			
 
				+
			
 
				+export class NotesController extends TypertRemoteService {
			
 
				+  constructor(ctx: Context) {
			
 
				+    super(ctx, 'notesController', { namespace: 'notes' })
			
 
				+  }
			
 
				+
			
 
				+  /**
			
 
				+   * @param agent - lookup parameter the Gateway resolves from its wire identity.
			
 
				+   * @param signal - carrier cancellation, always the final parameter.
			
 
				+   * @returns the notes this Agent's session owns.
			
 
				+   */
			
 
				+  @Remote('list')
			
 
				+  async remoteExportList(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
			
 
				+    return await this.list(agent, signal)
			
 
				+  }
			
 
				+
			
 
				+  /** The in-process API the adapter above delegates to, unchanged by it. */
			
 
				+  async list(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
			
 
				+    signal.throwIfAborted()
			
 
				+    return await Promise.resolve([{ noteId: `${agent.id}-1`, title: 'draft' }])
			
 
				+  }
			
 
				+}
			
 
				+```
			
 
				+
			
 
				+## 2. Declare the failures
			
 
				+
			
 
				+A Remote failure is one class, `RemoteError`: merge the domain codes into `RemoteErrorDetailsMap` through declaration merging and `throw new RemoteError(code, message, details)` at the failure point. Do not build a family of domain error classes, and do not write an exit-mapping function; an exception unrelated to this endpoint is not pre-classified, because the Gateway folds it into `gateway/internal`. Write a `catch` only to classify an arbitrary provider exception as one domain code, and attach the original exception as `cause`.
			
 
				+
			
 
				+A code reads `<domain>/<reason>`, and its declaration has four placement rules:
			
 
				+
			
 
				+- One producer only: declare it in the producing package, next to the throw.
			
 
				+- Several packages produce it: declare it in the lowest domain package both depend on (`session/not-found` in `core/session`, `workspace/not-found` in `dsh-workspace`).
			
 
				+- The carrier codes `gateway/bad-request`, `gateway/cancelled`, and `gateway/internal` are declared in protocol, and the Gateway infrastructure codes in gateway — use them, never copy them.
			
 
				+- A local failure that never crosses the wire stays out of the code table; express it with the caller's own type.
			
 
				+
			
 
				+```ts
			
 
				+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
			
 
				+
			
 
				+declare module '@deepseek-ai/dsh-typert-protocol' {
			
 
				+  interface RemoteErrorDetailsMap {
			
 
				+    /** No stored note carries that id. */
			
 
				+    'note/not-found': { readonly noteId: string }
			
 
				+    /** The store refused an otherwise valid write. */
			
 
				+    'note/rejected': { readonly noteId: string }
			
 
				+  }
			
 
				+}
			
 
				+
			
 
				+declare const stored: ReadonlyMap<string, string>
			
 
				+declare function persist(noteId: string, title: string): Promise<void>
			
 
				+
			
 
				+export async function rename(noteId: string, title: string): Promise<void> {
			
 
				+  if (!stored.has(noteId)) {
			
 
				+    throw new RemoteError('note/not-found', `no note "${noteId}"`, { noteId })
			
 
				+  }
			
 
				+  try {
			
 
				+    await persist(noteId, title)
			
 
				+  } catch (error: unknown) {
			
 
				+    const message = error instanceof Error ? error.message : String(error)
			
 
				+    throw new RemoteError('note/rejected', message, { noteId }, { cause: error })
			
 
				+  }
			
 
				+}
			
 
				+```
			
 
				+
			
 
				+## 3. Register it on the package
			
 
				+
			
 
				+`@Remote` must live in a Loader entry plugin package; when the owner is an abstract seam, the controller goes in the matching package under `packages/api/`. The manifest gains the two generated entries and the protocol peer dependency, while on the Client side the `@deepseek-ai/dsh-api-remotes` assembly mounts the contribution and re-exports the type vocabulary that consumers need. Which generated artifact each entry points at, and how the generation pipeline is ordered, are in the [API Gateway reference](../api-gateway.md).
			
 
				+
			
 
				+```json
			
 
				+{
			
 
				+  "exports": {
			
 
				+    "./typert": { "types": "./lib/typert.host.d.ts", "default": "./lib/typert.host.js" },
			
 
				+    "./remote": { "types": "./lib/typert.remote-client.d.ts", "default": "./lib/typert.remote-client.js" }
			
 
				+  },
			
 
				+  "peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" },
			
 
				+  "devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" }
			
 
				+}
			
 
				+```
			
 
				+
			
 
				+Rerun `pnpm run build:lib` after changing a signature, the code table, the namespace, or an export name, because that is what hands the Client its new declarations and codecs; changing only an implementation body needs no regeneration.
			
 
				+
			
 
				+## 4. Consume it on the Client
			
 
				+
			
 
				+The calling plugin declares both `remote` and `remote.<namespace>` in its `inject`, and the call site writes `ctx.remote.<namespace>.<method>(...)` directly: no `Pick<ClientRemote, …>` narrowing, no hand-written method signature, no wire relay object. The result is a `RemoteResult<T>`, so branch on `if (!result.ok)` in place and discriminate by `code` rather than `instanceof` — a code branch narrows `details` on its own. An exception-flow site writes `throw result.error` (it is a real Error); whoever catches it uses `isRemoteFailure` to tell a Remote failure from a local defect and rethrows the defect. Do not write a defensive catch: a Remote call does not reject, and an assembly mistake should crash.
			
 
				+
			
 
				+Fixed Host facts come from `ctx.remote.$host`: `home` and `isLoopback` are plain reads with no subscription and no generation counter, and `home` is `undefined` until the first ready frame. Refresh after a reconnect through `ctx.on('connection/reset')` or a domain's own remote event. When the caller aborts a unary call, the outcome is `gateway/cancelled` on the error branch rather than a throw.
			
 
				+
			
 
				+```ts ignore-check
			
 
				+import type { Context } from '@deepseek-ai/cordis'
			
 
				+import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client'
			
 
				+import type {} from '@deepseek-ai/dsh-api-remotes/client'
			
 
				+
			
 
				+export const inject = ['remote', 'remote.notes']
			
 
				+
			
 
				+declare const ctx: Context
			
 
				+
			
 
				+/** Store-side read: the error branch is handled where the code is meaningful. */
			
 
				+export async function noteTitles(): Promise<readonly string[]> {
			
 
				+  const result = await ctx.remote.notes.list()
			
 
				+  if (!result.ok) {
			
 
				+    if (result.error.code === 'note/not-found') return []
			
 
				+    throw result.error
			
 
				+  }
			
 
				+  return result.value.map(row => row.title)
			
 
				+}
			
 
				+
			
 
				+/** Action-side: a Remote failure becomes copy; a local fault keeps crashing. */
			
 
				+export async function renderTitles(): Promise<string> {
			
 
				+  try {
			
 
				+    return (await noteTitles()).join(', ')
			
 
				+  } catch (error: unknown) {
			
 
				+    if (!isRemoteFailure(error)) throw error
			
 
				+    return `unavailable (${error.code})`
			
 
				+  }
			
 
				+}
			
 
				+
			
 
				+/** Fixed Host facts as plain reads. */
			
 
				+export function hostLabel(): string {
			
 
				+  const { home, isLoopback } = ctx.remote.$host
			
 
				+  return home ?? (isLoopback ? 'local host' : 'remote host')
			
 
				+}
			
 
				+```
			
 
				+
			
 
				+## 5. Test it
			
 
				+
			
 
				+On the owner side, assert the code that was thrown: recover the failure with `remoteErrorOf` after catching, then compare `code` and the details fields you care about with `toMatchObject` — never deep-compare the error object with `toEqual`, and never assert `instanceof`.
			
 
				+
			
 
				+```ts
			
 
				+import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
			
 
				+import { expect, it } from 'vitest'
			
 
				+
			
 
				+declare function rename(noteId: string, title: string): Promise<void>
			
 
				+
			
 
				+it('refuses an unknown note before writing', async () => {
			
 
				+  const failure = await rename('n-404', 'fresh title').catch((error: unknown) => error)
			
 
				+
			
 
				+  expect(remoteErrorOf(failure)).toMatchObject({
			
 
				+    code: 'note/not-found',
			
 
				+    details: { noteId: 'n-404' },
			
 
				+  })
			
 
				+})
			
 
				+```
			
 
				+
			
 
				+A Client-side double returns real instances: take the `RemoteError` and `TestRemote` value imports from `@deepseek-ai/dsh-client-test-runtime`, because a value import from the `api-remotes` facade would load the unbuilt assembly chain. `TestRemote.$host` is a plain field a spec assigns directly.
			
 
				+
			
 
				+```ts ignore-check
			
 
				+import { Context } from '@deepseek-ai/cordis'
			
 
				+import { RemoteError, TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
			
 
				+import { expect, it } from 'vitest'
			
 
				+
			
 
				+it('renders the failure code the Host reported', async () => {
			
 
				+  const ctx = new Context()
			
 
				+  const remote = new TestRemote(ctx, {
			
 
				+    notes: {
			
 
				+      list: () => Promise.resolve({
			
 
				+        ok: false as const,
			
 
				+        error: new RemoteError('note/not-found', 'no note "n-404"', { noteId: 'n-404' }),
			
 
				+      }),
			
 
				+    },
			
 
				+  })
			
 
				+  remote.$host = { home: '/home/fixture', isLoopback: true }
			
 
				+
			
 
				+  await expect(ctx.remote.notes.list()).resolves.toMatchObject({ error: { code: 'note/not-found' } })
			
 
				+})
			
 
				+```
			
 
				+
			
 
				+## Verify
			
 
				+
			
 
				+1. `pnpm run build:lib`: mandatory once a signature, the code table, the namespace, or an export name changed, because it produces the Client declarations and codecs.
			
 
				+2. `pnpm run typecheck`: both the Host and the Client program, where a code merged into an unreachable package turns red.
			
 
				+3. Run both sides' specs by name: `npx vitest run <owner spec> <client spec>`.
			
 
				+4. Add a recorded-session snapshot when the endpoint reaches a product-visible surface, per the [testing policy](../testing.md).
			
--- a/docs/cookbook/adding-a-remote-api.zh.md
+++ b/docs/cookbook/adding-a-remote-api.zh.md
@@ -0,0 +1,197 @@
 
				+# 实操手册：新增一个 Remote API
			
 
				+
			
 
				+[English](adding-a-remote-api.md) | 中文
			
 
				+
			
 
				+新增或改动一个 `ctx.remote` 端点按本页五步走：声明方法、声明失败、在包上注册、在 Client 消费、写测试。decorator 语义、lookup 解析、生成管线与 `/api` 路由属于机制，由 [API Gateway 参考](../api-gateway.zh.md)负责；本页给的是每一步的动作与必须遵守的约定。为什么是这套编程面，见 [Typert Remote 方法调用 Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md)；为什么失败面是单个 `RemoteError` 加一张码表，见[失败词汇 Agent Note](../../.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.zh.md)。
			
 
				+
			
 
				+## 1. 声明 API
			
 
				+
			
 
				+owner 是一个 Host 侧 Cordis 服务：继承 `TypertRemoteService` 把 service 键与 wire namespace 一起绑定，再用 `@Remote` 标注对外暴露的方法。业务方法的签名若已符合 wire 约定就直接标注它本身；只有形态需要调整（补 `signal`、换参数顺序、换导出名）才写一个 `remoteExport*` adapter，由它调用不改名的业务方法。lookup 对象（`Agent`、`Session`）只能占顶层参数位，支持协作式取消的方法把 `signal: AbortSignal` 放在最后一位。
			
 
				+
			
 
				+```ts
			
 
				+import type { Context } from '@deepseek-ai/cordis'
			
 
				+import type { Agent } from '@deepseek-ai/dsh-agent'
			
 
				+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
			
 
				+
			
 
				+/** One stored note as a Client reads it. */
			
 
				+export interface NoteRow {
			
 
				+  readonly noteId: string
			
 
				+  readonly title: string
			
 
				+}
			
 
				+
			
 
				+declare module '@deepseek-ai/cordis' {
			
 
				+  interface Context {
			
 
				+    notesController: NotesController
			
 
				+  }
			
 
				+}
			
 
				+
			
 
				+export class NotesController extends TypertRemoteService {
			
 
				+  constructor(ctx: Context) {
			
 
				+    super(ctx, 'notesController', { namespace: 'notes' })
			
 
				+  }
			
 
				+
			
 
				+  /**
			
 
				+   * @param agent - lookup parameter the Gateway resolves from its wire identity.
			
 
				+   * @param signal - carrier cancellation, always the final parameter.
			
 
				+   * @returns the notes this Agent's session owns.
			
 
				+   */
			
 
				+  @Remote('list')
			
 
				+  async remoteExportList(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
			
 
				+    return await this.list(agent, signal)
			
 
				+  }
			
 
				+
			
 
				+  /** The in-process API the adapter above delegates to, unchanged by it. */
			
 
				+  async list(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
			
 
				+    signal.throwIfAborted()
			
 
				+    return await Promise.resolve([{ noteId: `${agent.id}-1`, title: 'draft' }])
			
 
				+  }
			
 
				+}
			
 
				+```
			
 
				+
			
 
				+## 2. 声明失败
			
 
				+
			
 
				+Remote 失败只有一个类 `RemoteError`：域码经 declaration merging 进 `RemoteErrorDetailsMap`，失败点直接 `throw new RemoteError(code, message, details)`。不要建域异常类家族，也不要写出口映射函数；与本端点无关的异常不预先归类，Gateway 会兜底折成 `gateway/internal`。只有"把任意 provider 异常归为一个域码"这一种场景才写 `catch`，并把原始异常挂在 `cause` 上。
			
 
				+
			
 
				+码名是 `<域>/<理由>`，声明落点四条：
			
 
				+
			
 
				+- 只有一个生产者：声明落生产者包，紧挨抛出点。
			
 
				+- 多个包共同生产：落双方共同依赖的最低层域包（`session/not-found` 在 `core/session`，`workspace/not-found` 在 `dsh-workspace`）。
			
 
				+- 载体码 `gateway/bad-request`、`gateway/cancelled`、`gateway/internal` 已在 protocol 声明，Gateway 基础设施码已在 gateway 声明——直接用，不要复制。
			
 
				+- 不上 wire 的本地失败不进码表，用调用方自己的类型表达。
			
 
				+
			
 
				+```ts
			
 
				+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
			
 
				+
			
 
				+declare module '@deepseek-ai/dsh-typert-protocol' {
			
 
				+  interface RemoteErrorDetailsMap {
			
 
				+    /** No stored note carries that id. */
			
 
				+    'note/not-found': { readonly noteId: string }
			
 
				+    /** The store refused an otherwise valid write. */
			
 
				+    'note/rejected': { readonly noteId: string }
			
 
				+  }
			
 
				+}
			
 
				+
			
 
				+declare const stored: ReadonlyMap<string, string>
			
 
				+declare function persist(noteId: string, title: string): Promise<void>
			
 
				+
			
 
				+export async function rename(noteId: string, title: string): Promise<void> {
			
 
				+  if (!stored.has(noteId)) {
			
 
				+    throw new RemoteError('note/not-found', `no note "${noteId}"`, { noteId })
			
 
				+  }
			
 
				+  try {
			
 
				+    await persist(noteId, title)
			
 
				+  } catch (error: unknown) {
			
 
				+    const message = error instanceof Error ? error.message : String(error)
			
 
				+    throw new RemoteError('note/rejected', message, { noteId }, { cause: error })
			
 
				+  }
			
 
				+}
			
 
				+```
			
 
				+
			
 
				+## 3. 在包上注册
			
 
				+
			
 
				+`@Remote` 必须落在一个 Loader entry 插件包里；owner 是抽象 seam 时把控制器放进 `packages/api/` 下的对应包。包清单要补两个生成入口与 protocol 的 peer 依赖，Client 侧则由 `@deepseek-ai/dsh-api-remotes` 的 assembly 挂载该贡献并按需转口类型词汇。两个入口分别指向哪个生成产物、生成管线如何排序，见 [API Gateway 参考](../api-gateway.zh.md)。
			
 
				+
			
 
				+```json
			
 
				+{
			
 
				+  "exports": {
			
 
				+    "./typert": { "types": "./lib/typert.host.d.ts", "default": "./lib/typert.host.js" },
			
 
				+    "./remote": { "types": "./lib/typert.remote-client.d.ts", "default": "./lib/typert.remote-client.js" }
			
 
				+  },
			
 
				+  "peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" },
			
 
				+  "devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" }
			
 
				+}
			
 
				+```
			
 
				+
			
 
				+改动了签名、码表、namespace 或导出名之后重跑 `pnpm run build:lib`，Client 才拿得到新的声明与 codec；只改实现体不需要重新生成。
			
 
				+
			
 
				+## 4. 在 Client 消费
			
 
				+
			
 
				+调用插件在 `inject` 里同时声明 `remote` 与 `remote.<namespace>`，调用点直写 `ctx.remote.<namespace>.<method>(...)`：不要用 `Pick<ClientRemote, …>` 窄化、不要手写方法签名、不要造 wire 中转对象。结果是 `RemoteResult<T>`，就地 `if (!result.ok)` 分支，判 `code` 而不是 `instanceof`——code 分支会自动窄化 `details`。异常流的站点写 `throw result.error`（它是真 Error）；接住它的上层用 `isRemoteFailure` 区分 Remote 失败与本地缺陷，本地缺陷继续往上抛。不要写防御性 catch：Remote 调用不 reject，装配错误就该炸。
			
 
				+
			
 
				+Host 的固定事实读 `ctx.remote.$host`：`home` 与 `isLoopback` 是普通值读取，没有订阅也没有 generation 计数器，`home` 在第一帧 ready 之前是 `undefined`；重连后的刷新走 `ctx.on('connection/reset')` 或各域自己的 remote 事件。调用方 abort 掉一次一元调用时，结果落在错误分支上的 `gateway/cancelled`，而不是抛出。
			
 
				+
			
 
				+```ts ignore-check
			
 
				+import type { Context } from '@deepseek-ai/cordis'
			
 
				+import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client'
			
 
				+import type {} from '@deepseek-ai/dsh-api-remotes/client'
			
 
				+
			
 
				+export const inject = ['remote', 'remote.notes']
			
 
				+
			
 
				+declare const ctx: Context
			
 
				+
			
 
				+/** Store-side read: the error branch is handled where the code is meaningful. */
			
 
				+export async function noteTitles(): Promise<readonly string[]> {
			
 
				+  const result = await ctx.remote.notes.list()
			
 
				+  if (!result.ok) {
			
 
				+    if (result.error.code === 'note/not-found') return []
			
 
				+    throw result.error
			
 
				+  }
			
 
				+  return result.value.map(row => row.title)
			
 
				+}
			
 
				+
			
 
				+/** Action-side: a Remote failure becomes copy; a local fault keeps crashing. */
			
 
				+export async function renderTitles(): Promise<string> {
			
 
				+  try {
			
 
				+    return (await noteTitles()).join(', ')
			
 
				+  } catch (error: unknown) {
			
 
				+    if (!isRemoteFailure(error)) throw error
			
 
				+    return `unavailable (${error.code})`
			
 
				+  }
			
 
				+}
			
 
				+
			
 
				+/** Fixed Host facts as plain reads. */
			
 
				+export function hostLabel(): string {
			
 
				+  const { home, isLoopback } = ctx.remote.$host
			
 
				+  return home ?? (isLoopback ? 'local host' : 'remote host')
			
 
				+}
			
 
				+```
			
 
				+
			
 
				+## 5. 测试
			
 
				+
			
 
				+owner 侧断言抛出的码：捕获后用 `remoteErrorOf` 取出失败，再用 `toMatchObject` 比对 `code` 与需要的 `details` 字段——不要用 `toEqual` 深比对错误对象，也不要断言 `instanceof`。
			
 
				+
			
 
				+```ts
			
 
				+import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
			
 
				+import { expect, it } from 'vitest'
			
 
				+
			
 
				+declare function rename(noteId: string, title: string): Promise<void>
			
 
				+
			
 
				+it('refuses an unknown note before writing', async () => {
			
 
				+  const failure = await rename('n-404', 'fresh title').catch((error: unknown) => error)
			
 
				+
			
 
				+  expect(remoteErrorOf(failure)).toMatchObject({
			
 
				+    code: 'note/not-found',
			
 
				+    details: { noteId: 'n-404' },
			
 
				+  })
			
 
				+})
			
 
				+```
			
 
				+
			
 
				+Client 侧的替身返回真实例：`RemoteError` 与 `TestRemote` 的值 import 一律取自 `@deepseek-ai/dsh-client-test-runtime`，因为从 `api-remotes` facade 值 import 会拉起尚未构建的装配链。`TestRemote.$host` 是普通字段，spec 直接赋值即可。
			
 
				+
			
 
				+```ts ignore-check
			
 
				+import { Context } from '@deepseek-ai/cordis'
			
 
				+import { RemoteError, TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
			
 
				+import { expect, it } from 'vitest'
			
 
				+
			
 
				+it('renders the failure code the Host reported', async () => {
			
 
				+  const ctx = new Context()
			
 
				+  const remote = new TestRemote(ctx, {
			
 
				+    notes: {
			
 
				+      list: () => Promise.resolve({
			
 
				+        ok: false as const,
			
 
				+        error: new RemoteError('note/not-found', 'no note "n-404"', { noteId: 'n-404' }),
			
 
				+      }),
			
 
				+    },
			
 
				+  })
			
 
				+  remote.$host = { home: '/home/fixture', isLoopback: true }
			
 
				+
			
 
				+  await expect(ctx.remote.notes.list()).resolves.toMatchObject({ error: { code: 'note/not-found' } })
			
 
				+})
			
 
				+```
			
 
				+
			
 
				+## 验证
			
 
				+
			
 
				+1. `pnpm run build:lib`：签名、码表、namespace 或导出名变过就必须重跑，Client 声明与 codec 由它产出。
			
 
				+2. `pnpm run typecheck`：Host 与 Client 两个 program 都过一遍，码表的 merge 落点错了会在这里红。
			
 
				+3. 点名跑两侧 spec：`npx vitest run <owner spec> <client spec>`。
			
 
				+4. 端点属于产品可见面时补一条录制会话快照，规则见[测试策略](../testing.zh.md)。
			
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.i18n.yaml
@@ -2,5 +2,5 @@
 
				 # side as of the last confirmed-consistent state. Both languages carry equal authority;
			
 
				 # after editing either side, bring the other along and re-record with:
			
 
				 #   pnpm run verify-translation-pairing --write docs/event-producer-consumer.md
			
 
				-event-producer-consumer.md: 24ed4b92daae6d06a862618e398605fce7063f4f
			
 
				-event-producer-consumer.zh.md: af440aa4155b65a211b7fdc9bce232a264bbe3a7
			
 
				+event-producer-consumer.md: 53ed72ca93702ad06d63d3fb3b80ab6aba05baaa
			
 
				+event-producer-consumer.zh.md: 8f4b12a8e7dbea96b735320997a5a0a2a4a8a545