Add files using upload-large-folder tool

packages/client/connection/README.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 packages/client/connection/README.md
+README.md: c8c2b2f6edb0ce43a07a664bcc2b3c9ece047b7b
+README.zh.md: 2c25c0d3520fd7e5d3eeeec98c41cc1d3d4d25d8

packages/client/connection/README.md

@@ -0,0 +1,81 @@
+---
+description: "Browser-host wire layer for the web GUI: Remote RPC, event-stream delivery with reconnect, exact Fetch routes, the /api HTTP bridge, and the browser-trust fence."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-connection
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The package carries browser-to-Host Remote calls, exact Fetch responses, and connection generations. The Client plugin mounts `ctx.connection` with current-page loopback state, generic RPC, the active generation and its Host facts, observable recovery state, an immediate reconnect command, and the registration point for one generation source. A generation becomes visible when its source reports ready; source completion, failure, withdrawal, or an explicit stop clears it before `ConnectionController` applies its retry policy.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Browser authentication and request trust](#browser-authentication-and-request-trust)
+- [Connection generation](#connection-generation)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+The browser uses HTTP POST for Remote unary calls. API Gateway owns the `/api/remote.mux` WebSocket and its logical streams; shell-owned compositions provide equivalent Remote streams through `connection.rpc.open` without opening a WebSocket. The browser plugin reads the page transport, recovery settings, and location, then delegates to `installConnection(ctx, options)`. A composition that owns its carrier may call the same installer directly; the whole-client test tier does so. Each invocation creates one Context-owned service, so several Client trees can use different carriers in one realm. The Host half always provides the carrier-neutral RPC and exact `GET`/`HEAD`/`POST` route registries. When a Web carrier is present it also owns the sole `/api` route, Fetch bridge, browser authentication, and Host/Origin checks; a shell-owned carrier dispatches the shared Fetch handler directly. Each exact route declares buffered or streaming request-body handling before the bridge reads any bytes. Typert Gateway claims generated Remote endpoints, feature packages register non-JSON responses such as Session-log downloads and raw file uploads, and unclaimed requests return 404. Loopback hostname classification remains package-internal to the browser-facing Client state. Browser raw-body transfer is provided by [`dsh-client-file-upload`](../file-upload/README.md).
+
+-----
+
+<a id="browser-authentication-and-request-trust"></a>
+## Browser authentication and request trust
+
+Every Host RPC method and WebSocket stream requires one browser session; there is no method-specific loopback tier. Each process mints a random launch token. `dsh-web-app` prints and opens the ordinary root URL with `?token=...`; `frontend-static` delegates root and index requests to `ctx.connection.authorizeIndex`, which accepts that token only on `GET /`, writes an authority-bound signed cookie, and redirects to clean `/`. A missing, expired, malformed, or wrong-authority cookie returns 401 before RPC dispatch. Static assets remain public. The HTTP carrier accepts no query token outside the root exchange and no Authorization-header token.
+
+The cookie signing secret is the owner-scoped `client-connection/browser-session` grant record in `ctx.credentials`. The local provider persists it in `$DSH_HOME/.credentials.yaml`; `BrowserAuth` loads or creates the record during Connection activation and retains the secret in memory, so request authentication is synchronous. Deleting or replacing the record takes effect on the next Connection activation. Cookies carry an absolute issue/expiry interval, defaulting to 30 days through `cookieMaxAgeDays`, and bind the normalized hostname plus port in both their deterministic name and signed payload. They are host-only, `Path=/`, `HttpOnly`, and `SameSite=Strict`; they deliberately omit `Secure` because the shipped server uses loopback HTTP.
+
+Before authentication, every request still passes `src/api-request-trust.ts`. Its `Host` must be loopback or match a `trustedHosts` entry: exact on `host:port`, any port on port-less entries, both sides WHATWG-normalized. An attached `Origin` must equal that Host and `sec-fetch-site: cross-site` is refused. Malformed configured authorities fail plugin load. These checks defend DNS rebinding and cross-site browser requests; they never establish identity. A failed Host/Origin check returns 403, while a trusted but unauthenticated request returns 401. `dsh web --host 0.0.0.0` remains unsupported. Decision records: [browser request trust](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md) and [browser token authentication](../../../.agents/notes/implemented/architecture/2026-08-24-browser-token-authentication.md).
+
+<a id="connection-generation"></a>
+## Connection generation
+
+API Gateway Client registers the internal `$events` logical stream as the sole generation source, independently of whether any `$on` listener exists. The Host attaches all incremental listeners in the API Remotes source factory, then sends one `{ type: 'ready', clientId, host: { home } }` item before events. `ConnectionController` publishes that generation and calls `onConnected` only after the ready item arrives, so baseline acquisition cannot race ahead of incremental observation.
+
+An ended `$events` stream, a Remote stream error, a non-ready opening item, or a malformed event item invalidates the current generation. A pending handshake logs a slow-Host warning after 3 seconds and logs the readiness timeout and aborts after 15 seconds by default, including time spent waiting for the physical socket. The source must stop delivery, release resources, and settle after cancellation before a replacement starts; late readiness from a cancelled source cannot publish a generation. While the browser reports network availability, the controller publishes `connecting` and retries with 50%–100% jitter under caps of 500ms, 1s, 2s, 4s, 8s, and 10s, continuing at the final cap until recovery. Every retry asks Gateway to replace the physical WebSocket once and reopens `$events`. The [continuous recovery decision](../../../.agents/notes/implemented/bug-fix/2026-09-05-continuous-client-recovery.md) owns the deadlines and retry policy.
+
+`ctx.connection.reconnect()` interrupts active work, resets the sequence, and starts retry 1 immediately. Browser `offline` aborts active work, publishes `disconnected`, and suspends automatic attempts; the next `online` transition resets the sequence and starts at the 500ms tier. Only a ready item publishes `connected`. Gateway mux owns no independent retry schedule.
+
+Set the Host Connection row's `config.recovery` to override retry caps, the growth factor, or handshake warning and cancellation times; the [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-client-connection) lists accepted fields. The Host validates these values and injects them into each served page. The Client validates the bootstrap data before providing Connection and uses those defaults when Gateway starts its loop; explicit `start()` timing overrides take precedence. The growth factor must be finite and at least one. Readiness, failure, cancellation, or a hard deadline that occurs before the warning cancels that warning. Reload the page after changing Host recovery configuration.
+
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the wire consumer layer moves already-composed messages between browser and host; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Buffered `/api` routes retain each request body in memory** — `maxRequestBodyBytes` (default 300 MiB, sized for the default 200 MiB aggregate image limit after base64 expansion plus envelope headroom) bounds ordinary image and RPC envelopes. Opt-in streaming routes receive backpressured chunks and bypass the aggregate cap; route implementations own persistence, cancellation, and any storage quota.
+- **The browser cookie is not marked `Secure`** — loopback HTTP is the shipped transport, so exposing the same authority over plaintext networking can expose the bearer cookie in transit.
+- **There is no logout operation** — clearing the browser cookie ends one browser session; deleting the owner credential record and restarting `dsh` revokes every session.
+
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. Browser-session verification reads the credential record asynchronously at the request that authorizes work, while the credentials companion owns record commit-event lifetime. Stream/reconnect sequencing and rpcId round-trip discipline are exercised directly by behavior specs, and route register/dispose symmetry is audited by the webserver companion.

packages/client/connection/README.zh.md

@@ -0,0 +1,81 @@
+---
+description: "Web GUI 的浏览器与 Host 之间的协议层：Remote RPC、带重连的事件流投递、精确 Fetch 路由、/api HTTP 桥与浏览器信任栅栏。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-connection
+
+[English](README.md) | 中文
+
+## 概述
+
+本包承载浏览器到 Host 的 Remote 调用、精确 Fetch 响应与 connection generation。Client 插件挂载 `ctx.connection`，其中包含当前页面的 loopback 状态、通用 RPC、当前 generation 及其 Host 信息、可观察的恢复状态、立即重连命令，以及单一 generation source 的注册点。source 报告 ready 后 generation 才可见；source 结束、失败、被撤回或显式 stop 都会清空它，再由 `ConnectionController` 执行重试策略。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [浏览器认证与请求信任](#browser-authentication-and-request-trust)
+- [Connection generation](#connection-generation)
+- [模型体验](#model-experience)
+- [已知限制与暂缓事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+浏览器通过 HTTP POST 执行 Remote 一元调用；API Gateway 自己拥有 `/api/remote.mux` WebSocket 及其逻辑流。由 shell 持有的组合通过 `connection.rpc.open` 提供等价的 Remote 流，不打开 WebSocket。浏览器插件读取页面 transport、恢复设置与 location，再委托 `installConnection(ctx, options)`。持有自身载体的组合可以直接调用同一个安装函数；整机客户端测试档就是这一消费者。每次调用都会创建一个归所属 Context 的服务，因此同一 realm 中的多棵 Client 树可以使用不同载体。Host half 始终提供与载体无关的 RPC 注册表和精确 `GET`/`HEAD`/`POST` 路由注册表。存在 Web 载体时，它还持有唯一 `/api` route、Fetch bridge、浏览器认证与 Host/Origin 校验；由 shell 持有的载体则直接分派共享 Fetch handler。每条精确路由会在 bridge 读取任何字节前声明缓冲或流式请求体处理方式。Typert Gateway 认领生成的 Remote endpoint，功能包注册 Session 日志下载、原始文件上传等非 JSON 响应，未认领的请求返回 404。Loopback hostname 判定只供浏览器侧当前页面状态使用，留在包内。浏览器原始请求体传输由 [`dsh-client-file-upload`](../file-upload/README.zh.md) 提供。
+
+-----
+
+<a id="browser-authentication-and-request-trust"></a>
+## 浏览器认证与请求信任
+
+每个 Host RPC 方法和 WebSocket 流都要求一个浏览器会话，不存在按方法区分的 loopback 层。每个进程生成一个随机启动令牌。`dsh-web-app` 打印并打开带 `?token=...` 的普通根 URL；`frontend-static` 把根路径和 index 请求交给 `ctx.connection.authorizeIndex`，后者只在 `GET /` 接受该令牌，写入绑定 authority 的签名 cookie，再重定向到干净的 `/`。缺失、过期、畸形或 authority 不匹配的 cookie 会在 RPC 分发前得到 401。静态资源保持公开。HTTP 载体不在根路径交换之外接受 query token，也不接受 Authorization header token。
+
+cookie 签名密钥是 `ctx.credentials` 中由 `client-connection/browser-session` 拥有的 grant 记录。本地提供方把它持久化到 `$DSH_HOME/.credentials.yaml`；`BrowserAuth` 在 Connection 激活期间加载或创建该记录，并把密钥留在内存中，因此请求认证同步执行。删除或替换该记录会在下一次 Connection 激活时生效。cookie 携带绝对签发与过期区间，`cookieMaxAgeDays` 默认设为 30 天，并在确定性名称与签名 payload 中同时绑定规范化 hostname 和 port。它是 host-only、`Path=/`、`HttpOnly`、`SameSite=Strict`；随附服务器使用 loopback HTTP，因此刻意不设置 `Secure`。
+
+认证之前，每个请求仍经过 `src/api-request-trust.ts`。其 `Host` 必须是 loopback，或与 `trustedHosts` 条目匹配：带端口的 `host:port` 精确匹配，不带端口的条目匹配任意端口，两侧均经 WHATWG 归一化。若附带 `Origin`，它必须等于该 Host；`sec-fetch-site: cross-site` 一律拒绝。畸形配置 authority 会让插件加载失败。这些检查防御 DNS rebinding 与跨站浏览器请求，绝不建立身份。Host/Origin 校验失败返回 403；Host 可信但未认证的请求返回 401。`dsh web --host 0.0.0.0` 仍不受支持。决策记录：[浏览器请求信任](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md)与[浏览器令牌认证](../../../.agents/notes/implemented/architecture/2026-08-24-browser-token-authentication.zh.md)。
+
+<a id="connection-generation"></a>
+## Connection generation
+
+API Gateway Client 把内部 `$events` 逻辑流注册为唯一 generation source，与有无 `$on` 订阅无关。Host 在 API Remotes source factory 同步挂好所有增量 listener 后，先发送唯一 `{ type: 'ready', clientId, host: { home } }` 项，再发送事���。`ConnectionController` 仅在收到该 ready 项后发布 generation 并调用 `onConnected`，因此 baseline 不会跑在增量 listener 前面。
+
+`$events` 结束、Remote 流报错、收到非 ready 首项或畸形事件项，都会使当前 generation 失效。默认情况下，挂起的握手在 3 秒后记录 Host 响应缓慢告警，在 15 秒后记录就绪超时并中止，包含等待物理 socket 的时间。取消后，source 必须停止投递、释放资源并结束，替换 source 才能启动；已取消 source 迟到的 ready 不能发布 generation。浏览器报告网络可用时，Controller 发布 `connecting`，并在 500ms、1s、2s、4s、8s 与 10s 上限内采用 50%–100% 抖动重试，达到终档后继续尝试直到恢复。每次重试都要求 Gateway 替换一次物理 WebSocket，再重开 `$events`。[持续恢复决策](../../../.agents/notes/implemented/bug-fix/2026-09-05-continuous-client-recovery.zh.md)规定握手期限与重试策略。
+
+`ctx.connection.reconnect()` 会中断活动工作、重置序列，并立即开始 retry 1。浏览器 `offline` 会中断活动工作、发布 `disconnected` 并暂停自动尝试；下一次 `online` 转换会重置序列并从 500ms 档开始。只有 ready 项会发布 `connected`。Gateway mux 不拥有独立重试调度。
+
+可通过 Host Connection 行的 `config.recovery` 覆盖重试上限、增长因子或握手告警与取消时间；[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-client-connection)列出接受的字段。Host 校验这些值，并将其注入所提供的每个页面。Client 在提供 Connection 前校验启动数据，并在 Gateway 启动循环时采用这些默认值；显式传给 `start()` 的时序覆盖优先。增长因子必须是至少为一的有限数。若就绪、失败、取消或硬期限先于告警发生，该告警会被取消。修改 Host 恢复配置后需重新加载页面。
+
+
+<a id="model-experience"></a>
+## 模型体验
+
+无。协议消费层只在浏览器与主机之间搬运已经组合好的消息；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **缓冲型 `/api` 路由会把每个请求体保留在内存里**：`maxRequestBodyBytes`（默认 300 MiB，按默认 200 MiB 图片总量上限经 base64 膨胀加信封余量得出）限制普通图片与 RPC 信封。显式启用的流式路由接收带背压的分块并绕过总量上限；路由实现负责持久化、取消与存储配额。
+- **浏览器 cookie 不带 `Secure`**：当前随产品提供的传输方式是 loopback HTTP；若部署经明文网络暴露同一 authority，bearer cookie 可能在传输中泄露。
+- **没有 logout 操作**：清除浏览器 cookie 会结束单个浏览器会话；删除 owner 凭据记录并重启 `dsh` 会撤销全部会话。
+
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变式：** 不发布伴生入口。浏览器会话验证会在请求授权工作时异步读取凭据记录，而记录的 commit-event 生命周期由 credentials 伴生入口负责；流与重连的时序及 rpcId 往返约束由行为规范直接验证，路由注册与 dispose（资源释放）的对称性由 webserver 伴生入口审计。

packages/client/connection/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@deepseek-ai/dsh-client-connection",
+  "description": "Authenticated RPC transport and generation lifecycle",
+  "version": "0.1.6-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/connection"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh-credentials": "workspace:^",
+    "@deepseek-ai/schemastery": "workspace:^",
+    "zod": "^4.4.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-attachment": "workspace:^",
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^"
+  }
+}

packages/client/connection/src/api-path.ts

@@ -0,0 +1,7 @@
+/**
+ * The /api URL prefix — single source for both halves of the web transport.
+ * The node half registers this prefix on the web server.
+ */
+
+/** Route prefix owning every api request (`/api` and `/api/<anything>`). */
+export const API_PATH = '/api'

packages/client/connection/src/api-request-trust.ts

@@ -0,0 +1,118 @@
+/**
+ * Browser-trust fence for every /api request. Defends the two confused-deputy
+ * paths a browser opens against a local HTTP API — DNS rebinding (Host names
+ * the attacker's domain while the socket reaches this server) and cross-site
+ * requests fired from a malicious page. The Host fence binds every request,
+ * browser-looking or not: over plain HTTP a browser attaches neither Origin
+ * nor Fetch-Metadata to reads (images and navigations — those
+ * headers go only to trustworthy destinations), so an unmarked request may
+ * still be a rebound browser read and Host is the one header rebinding cannot
+ * forge. Non-browser and remote clients pass the same fence via loopback,
+ * deployment-derived LAN IP literals, or a declared `trustedHosts` authority.
+ * Network reachability and authentication stay out of scope: binding policy
+ * belongs to the webserver config, and this fence is not an auth layer.
+ */
+
+import { isLoopbackHostname } from './loopback-hostname.ts'
+import type { ConnectionTrustRequest } from './rpc.ts'
+
+function header(headers: ConnectionTrustRequest['headers'], name: string): string | undefined {
+  if (headers instanceof Headers) return headers.get(name) ?? undefined
+  const value = headers[name]
+  return typeof value === 'string' ? value : undefined
+}
+
+/** Normalized URL of a Host-header authority (hostname lowercased, default port stripped, IPv6 bracketed), or undefined when unparsable. */
+function parseAuthority(authority: string): URL | undefined {
+  try {
+    // http: is a WHATWG "special scheme": parsing yields a non-empty hostname or throws.
+    return new URL(`http://${authority}`)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Assert one configured `trustedHosts` entry is a bare authority (`host` or
+ * `host:port`) in canonical form: it must survive WHATWG parsing unchanged
+ * (case aside). Anything parsing would silently rewrite is refused as a typo
+ * that must fail the load loudly instead of being ignored until requests 403
+ * or quietly changing the grant: URL parts beyond the authority
+ * (`harness.internal/path`, `user@harness.internal` — which would authorize
+ * the embedded hostname), stripped whitespace, a dangling colon or
+ * zero-padded port (which would broaden an intended exact-port grant to every
+ * port), and non-canonical host spellings (`0x7f.0.0.1`, percent-encoding,
+ * unbracketed IPv6; IDN hosts are declared in punycode, the form the wire
+ * carries).
+ * @param entry - the configured value, verbatim.
+ */
+export function assertTrustedAuthority(entry: string): void {
+  const entryUrl = parseAuthority(entry)
+  if (entryUrl !== undefined && canonicalAuthority(entry, entryUrl) === entry.toLowerCase()) return
+  throw new Error(`client-connection: trustedHosts entry ${JSON.stringify(entry)} is not a bare host[:port] authority`)
+}
+
+/**
+ * Canonical form of a parsed authority: `hostname` when no port was written,
+ * else `hostname:port`. The port is judged from URL parses under both special
+ * schemes (their default ports differ, so `:80` and `:443` still count as
+ * explicit), never from the raw string, where WHATWG trimming would misread
+ * shapes like `host:port ` as port-less.
+ */
+function canonicalAuthority(entry: string, entryUrl: URL): string {
+  // An authority that parsed under http cannot fail under https.
+  const port = entryUrl.port !== '' ? entryUrl.port : new URL(`https://${entry}`).port
+  return port === '' ? entryUrl.hostname : `${entryUrl.hostname}:${port}`
+}
+
+/**
+ * Whether the request authority matches a `trustedHosts` entry. An entry with
+ * an explicit port matches that exact authority; a port-less entry matches the
+ * hostname on any port (the shape the CLI derives for IP-literal LAN serving,
+ * where the bound port may be OS-assigned). Both sides compare through WHATWG
+ * normalization, so case and a redundant `:80` never decide trust.
+ */
+function isTrustedAuthority(hostUrl: URL, trustedHosts: readonly string[]): boolean {
+  return trustedHosts.some((entry) => {
+    const entryUrl = parseAuthority(entry)
+    if (entryUrl === undefined) return false
+    return canonicalAuthority(entry, entryUrl) === entryUrl.hostname
+      ? entryUrl.hostname === hostUrl.hostname
+      : entryUrl.host === hostUrl.host
+  })
+}
+
+/**
+ * Decide whether one /api request may reach the RPC bridge.
+ * @param request - Node HTTP or Fetch request facts (headers).
+ * @param trustedHosts - non-loopback authorities this deployment serves: exact `host:port`, or port-less `host` matching any port.
+ * @returns true when the Host is ours (loopback or trusted) and any attached browser markers are same-origin.
+ */
+export function isTrustedApiRequest(request: ConnectionTrustRequest, trustedHosts: readonly string[]): boolean {
+  // Host fence (DNS-rebinding defense), applied to every request: the browser
+  // fills Host from the URL it believes it is talking to, so a rebound page
+  // carries the attacker's domain here even though the socket lands on this
+  // server. There is no marker shortcut — a browser read over plain HTTP
+  // (images and navigations) arrives with neither Origin nor
+  // Fetch-Metadata, indistinguishable from curl, and its response is readable
+  // by the rebound page.
+  const host = header(request.headers, 'host')
+  if (host === undefined) return false
+  const hostUrl = parseAuthority(host)
+  if (hostUrl === undefined) return false
+  if (!isLoopbackHostname(hostUrl.hostname) && !isTrustedAuthority(hostUrl, trustedHosts)) return false
+  // Cross-site fence: modern browsers label the initiator relationship on
+  // every fetch; an explicit cross-site marker is refused regardless of Origin.
+  if (header(request.headers, 'sec-fetch-site') === 'cross-site') return false
+  // Origin fence: when a browser attaches an Origin it must be exactly this
+  // authority (compared through the same normalization as the Host). Absent
+  // Origin is fine — the Host fence above already bound the request. The
+  // literal "null" (sandboxed iframes, file: pages) is an opaque origin, refused.
+  const origin = header(request.headers, 'origin')
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}

packages/client/connection/src/browser-auth.ts

@@ -0,0 +1,313 @@
+/** Browser-session authentication for the Host Connection carrier. */
+
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { credentialKey } from '@deepseek-ai/dsh-credentials'
+import type { CredentialProvider, CredentialRecord } from '@deepseek-ai/dsh-credentials'
+import type {
+  ConnectionIndexRequest,
+  ConnectionIndexResponse,
+  ConnectionTrustRequest,
+} from './rpc.ts'
+
+const AUTH_RECORD_KEY = credentialKey('client-connection', 'browser-session')
+const DAY_MILLISECONDS = 24 * 60 * 60 * 1000
+const SECRET_BYTES = 32
+const TOKEN_QUERY = 'token'
+const COOKIE_PREFIX = 'dsh-auth-'
+const COOKIE_PAYLOAD_VERSION = 1
+const STORED_SECRET_VERSION = 1
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*$/
+const PROCESS_LAUNCH_TOKENS = new WeakMap<object, string>()
+
+interface StoredSecretPayload {
+  readonly version: typeof STORED_SECRET_VERSION
+  readonly secret: string
+}
+
+interface BrowserCookiePayload {
+  readonly version: typeof COOKIE_PAYLOAD_VERSION
+  readonly authority: string
+  readonly issuedAt: number
+  readonly expiresAt: number
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function encodeBase64Url(value: Uint8Array): string {
+  return Buffer.from(value).toString('base64')
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/=+$/u, '')
+}
+
+function decodeBase64Url(value: string): Buffer | undefined {
+  if (!BASE64URL_PATTERN.test(value) || value.length % 4 === 1) return undefined
+  const padding = '='.repeat((4 - value.length % 4) % 4)
+  const decoded = Buffer.from(value.replaceAll('-', '+').replaceAll('_', '/') + padding, 'base64')
+  return encodeBase64Url(decoded) === value ? decoded : undefined
+}
+
+function processLaunchToken(owner: object): string {
+  const existing = PROCESS_LAUNCH_TOKENS.get(owner)
+  if (existing !== undefined) return existing
+  const created = encodeBase64Url(randomBytes(SECRET_BYTES))
+  PROCESS_LAUNCH_TOKENS.set(owner, created)
+  return created
+}
+
+function header(
+  headers: ConnectionTrustRequest['headers'],
+  name: string,
+): string | undefined {
+  if (headers instanceof Headers) return headers.get(name) ?? undefined
+  const value = headers[name]
+  return typeof value === 'string' ? value : undefined
+}
+
+/** Canonical request authority used as the cookie name and signed audience. */
+function requestAuthority(headers: ConnectionTrustRequest['headers']): string | undefined {
+  const host = header(headers, 'host')
+  if (host === undefined) return undefined
+  try {
+    return new URL(`http://${host}`).host
+  } catch {
+    return undefined
+  }
+}
+
+function canonicalSecret(value: unknown): Buffer | undefined {
+  if (typeof value !== 'string') return undefined
+  const decoded = decodeBase64Url(value)
+  if (decoded === undefined || decoded.byteLength !== SECRET_BYTES) return undefined
+  return decoded
+}
+
+function storedSecret(record: CredentialRecord | undefined): Buffer | undefined {
+  if (record === undefined) return undefined
+  if (record.kind !== 'grant' || !isRecord(record.payload)
+    || record.payload.version !== STORED_SECRET_VERSION) {
+    throw new Error('client-connection: browser-session credential record has an unsupported format')
+  }
+  const secret = canonicalSecret(record.payload.secret)
+  if (secret === undefined) {
+    throw new Error('client-connection: browser-session credential record has an invalid secret')
+  }
+  return secret
+}
+
+function tokenMatches(actual: string, expected: string): boolean {
+  const actualBytes = Buffer.from(actual, 'utf8')
+  const expectedBytes = Buffer.from(expected, 'utf8')
+  return actualBytes.byteLength === expectedBytes.byteLength && timingSafeEqual(actualBytes, expectedBytes)
+}
+
+function cookieName(authority: string): string {
+  return COOKIE_PREFIX + encodeBase64Url(createHash('sha256').update(authority).digest())
+}
+
+/** Read the exact generated cookie without implementing general Cookie decoding. */
+function cookieValue(headerValue: string, name: string): string | undefined {
+  for (const segment of headerValue.split(';')) {
+    const at = segment.indexOf('=')
+    if (at === -1 || segment.slice(0, at).trim() !== name) continue
+    return segment.slice(at + 1).trim()
+  }
+  return undefined
+}
+
+/** Serialize the fixed browser-session attributes; generated names and values are cookie-safe base64url. */
+function sessionCookie(name: string, value: string, expiresAt: number, maxAgeSeconds: number): string {
+  return `${name}=${value}; Max-Age=${String(maxAgeSeconds)}; Path=/; Expires=${new Date(expiresAt).toUTCString()}; HttpOnly; SameSite=Strict`
+}
+
+function signature(secret: Buffer, body: string): Buffer {
+  return createHmac('sha256', secret).update(body).digest()
+}
+
+function encodeCookie(payload: BrowserCookiePayload, secret: Buffer): string {
+  const body = encodeBase64Url(Buffer.from(JSON.stringify(payload), 'utf8'))
+  return `v1.${body}.${encodeBase64Url(signature(secret, body))}`
+}
+
+function decodeCookie(value: string, secret: Buffer): BrowserCookiePayload | undefined {
+  const parts = value.split('.')
+  const [version, body, encodedSignature] = parts
+  if (parts.length !== 3 || version !== 'v1' || body === undefined || encodedSignature === undefined) {
+    return undefined
+  }
+  const actualSignature = decodeBase64Url(encodedSignature)
+  if (actualSignature === undefined) return undefined
+  const expectedSignature = signature(secret, body)
+  if (actualSignature.byteLength !== expectedSignature.byteLength
+    || !timingSafeEqual(actualSignature, expectedSignature)) return undefined
+  let decoded: unknown
+  try {
+    const bodyBytes = decodeBase64Url(body)
+    if (bodyBytes === undefined) return undefined
+    decoded = JSON.parse(bodyBytes.toString('utf8'))
+  } catch {
+    return undefined
+  }
+  if (!isRecord(decoded)
+    || decoded.version !== COOKIE_PAYLOAD_VERSION
+    || typeof decoded.authority !== 'string'
+    || !Number.isSafeInteger(decoded.issuedAt)
+    || !Number.isSafeInteger(decoded.expiresAt)) return undefined
+  return decoded as unknown as BrowserCookiePayload
+}
+
+async function initializeSecret(credentials: CredentialProvider): Promise<Buffer> {
+  const generated: StoredSecretPayload = {
+    version: STORED_SECRET_VERSION,
+    secret: encodeBase64Url(randomBytes(SECRET_BYTES)),
+  }
+  const record = await credentials.modifyRecord(AUTH_RECORD_KEY, (current) => {
+    if (current !== undefined) {
+      storedSecret(current)
+      return Promise.resolve(undefined)
+    }
+    return Promise.resolve({ kind: 'grant', payload: generated })
+  })
+  const secret = storedSecret(record)
+  if (secret === undefined) {
+    throw new Error('client-connection: browser-session credential record was not created')
+  }
+  return secret
+}
+
+/**
+ * Process launch-token exchange and persistent signed-cookie verification.
+ * Connection loads the credential provider's signing secret during activation
+ * and retains it for synchronous request authentication.
+ */
+export class BrowserAuth {
+  private readonly launchToken: string
+  private readonly maxAgeMilliseconds: number
+
+  private constructor(
+    processOwner: object,
+    private readonly secret: Buffer,
+    maxAgeDays: number,
+  ) {
+    this.launchToken = processLaunchToken(processOwner)
+    this.maxAgeMilliseconds = maxAgeDays * DAY_MILLISECONDS
+    if (!Number.isSafeInteger(this.maxAgeMilliseconds)
+      || !Number.isSafeInteger(Date.now() + this.maxAgeMilliseconds)) {
+      throw new Error('client-connection: cookieMaxAgeDays exceeds the safe timestamp range')
+    }
+  }
+
+  /**
+   * Initialize browser authentication and create its durable signing secret
+   * when this Harness home has none.
+   * @param processOwner - root application context retaining one token across Connection reloads.
+   * @param credentials - persistent credential provider for the Web profile.
+   * @param maxAgeDays - positive absolute browser-cookie lifetime in days.
+   * @returns initialized authentication owner with the process owner's launch token.
+   */
+  static async create(
+    processOwner: object,
+    credentials: CredentialProvider,
+    maxAgeDays: number,
+  ): Promise<BrowserAuth> {
+    return new BrowserAuth(processOwner, await initializeSecret(credentials), maxAgeDays)
+  }
+
+  /**
+   * Add this process's launch token to the ordinary application root URL.
+   * @param baseUrl - canonical browser origin without credentials.
+   * @returns root URL carrying the process token as its sole authentication input.
+   */
+  authenticatedUrl(baseUrl: string): string {
+    const url = new URL(baseUrl)
+    url.pathname = '/'
+    url.search = ''
+    url.hash = ''
+    url.searchParams.set(TOKEN_QUERY, this.launchToken)
+    return url.href
+  }
+
+  /**
+   * Authenticate an index request. A valid root query token mints the cookie
+   * and redirects to clean `/`; a valid cookie lets the caller serve the
+   * index; every other request receives the same minimal 401 response.
+   * @param req - incoming root or configured-index request.
+   * @param res - response owned when this method returns false.
+   * @returns true only when the caller may serve index.html.
+   */
+  authorizeIndex(req: ConnectionIndexRequest, res: ConnectionIndexResponse): boolean {
+    /* v8 ignore next -- node:http always supplies url on server requests. */
+    const url = new URL(req.url ?? '/', 'http://dsh.invalid')
+    const tokens = url.searchParams.getAll(TOKEN_QUERY)
+    if (tokens.length > 0) {
+      const authority = requestAuthority(req.headers)
+      if (req.method === 'GET' && url.pathname === '/' && tokens.length === 1
+        && authority !== undefined && tokenMatches(tokens.join(''), this.launchToken)) {
+        const issuedAt = Date.now()
+        const expiresAt = issuedAt + this.maxAgeMilliseconds
+        const value = encodeCookie({
+          version: COOKIE_PAYLOAD_VERSION,
+          authority,
+          issuedAt,
+          expiresAt,
+        }, this.secret)
+        res.writeHead(303, {
+          'cache-control': 'no-store',
+          'location': '/',
+          'referrer-policy': 'no-referrer',
+          'set-cookie': sessionCookie(
+            cookieName(authority), value, expiresAt, Math.floor(this.maxAgeMilliseconds / 1000),
+          ),
+        })
+        res.end()
+        return false
+      }
+      if (req.method === 'GET' && url.pathname === '/' && this.isAuthenticated(req)) {
+        res.writeHead(303, {
+          'cache-control': 'no-store',
+          'location': '/',
+          'referrer-policy': 'no-referrer',
+        })
+        res.end()
+        return false
+      }
+      this.writeUnauthorized(req, res)
+      return false
+    }
+    if (this.isAuthenticated(req)) return true
+    this.writeUnauthorized(req, res)
+    return false
+  }
+
+  /**
+   * Verify the authority-bound browser cookie on a Host request.
+   * @param request - request headers carrying Host and Cookie.
+   * @returns true only for an unexpired cookie signed by this activation's loaded secret.
+   */
+  isAuthenticated(request: ConnectionTrustRequest): boolean {
+    const authority = requestAuthority(request.headers)
+    const rawCookie = header(request.headers, 'cookie')
+    if (authority === undefined || rawCookie === undefined) return false
+    const value = cookieValue(rawCookie, cookieName(authority))
+    if (value === undefined) return false
+    const payload = decodeCookie(value, this.secret)
+    if (payload === undefined || payload.authority !== authority) return false
+    const now = Date.now()
+    return payload.issuedAt <= now
+      && payload.expiresAt > now
+      && payload.expiresAt > payload.issuedAt
+      && payload.expiresAt - payload.issuedAt <= this.maxAgeMilliseconds
+  }
+
+  private writeUnauthorized(req: ConnectionIndexRequest, res: ConnectionIndexResponse): void {
+    res.writeHead(401, {
+      'cache-control': 'no-store',
+      'content-type': 'text/plain; charset=utf-8',
+    })
+    res.end(req.method === 'HEAD'
+      ? undefined
+      : 'dsh web authentication required; reopen the URL printed by dsh web.\n')
+  }
+}

packages/client/connection/src/client/api.ts

@@ -0,0 +1,25 @@
+/** Browser-safe Connection protocol and shared application value exports. */
+
+export type {
+  ClientRequest,
+  RpcMessage,
+  RpcRequest,
+  RpcResponse,
+  RpcResult,
+  ServerResponse,
+} from '../rpc.ts'
+export { RpcId, transportError } from '../rpc.ts'
+export type { SessionId, SessionEvent } from '@deepseek-ai/dsh-session/types'
+export type { MessageId } from '@deepseek-ai/dsh-llm/brand'
+export type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm/types'
+
+import type { RpcResponse, RpcResult } from '../rpc.ts'
+
+/**
+ * Return the business result carried by an RPC response.
+ * @param response - RPC response to unwrap.
+ * @returns the response's business result.
+ */
+export function resultOf<T>(response: RpcResponse<T>): RpcResult<T> {
+  return response.result
+}

packages/client/connection/src/client/connection.ts

@@ -0,0 +1,323 @@
+/** Connection generation readiness, cancellation, and continuous recovery. */
+import { resolveConnectionConfig, type ConnectionRecoveryConfig } from '../recovery-config.ts'
+
+export type { ConnectionRecoveryConfig } from '../recovery-config.ts'
+
+/** Stable Host facts delivered by one established Remote event generation. */
+export interface ConnectionHostInfo {
+  /** Host account home used only to abbreviate displayed filesystem paths. */
+  readonly home: string
+}
+
+/** One successfully established Host generation. */
+export interface ConnectionGeneration {
+  /** Monotone generation number within this Client runtime. */
+  readonly id: number
+  /** Host facts carried by this generation's opening frame. */
+  readonly host: ConnectionHostInfo
+}
+
+const MANUAL_RECONNECT = new Error('connection: manual reconnect requested')
+const NETWORK_STATE_CHANGED = new Error('connection: browser network state changed')
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const t = setTimeout(done, ms)
+    signal.addEventListener('abort', done, { once: true })
+    function done(): void {
+      clearTimeout(t)
+      signal.removeEventListener('abort', done)
+      resolve()
+    }
+  })
+}
+
+function waitForAbort(signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.resolve()
+  return new Promise((resolve) => {
+    signal.addEventListener('abort', () => { resolve() }, { once: true })
+  })
+}
+
+/** Connection lifecycle state published after the first attempt has an outcome. */
+export type ConnectionState =
+  | 'connected'
+  | 'disconnected'
+  | 'connecting'
+
+/** Connection-generation callbacks owned by API Gateway. */
+export interface ConnectionSinks {
+  /** After the generation source reports ready, first connect included. */
+  onConnected?: (host: ConnectionHostInfo) => void
+  /** State transitions after the initial attempt has an outcome. Equivalent states are deduplicated. */
+  onStateChange?: (state: ConnectionState) => void
+  /** Start one fresh physical-carrier attempt before each logical retry. */
+  onReconnectRequested?: () => void
+}
+
+/**
+ * One long-lived source defining a Connection generation. The source must
+ * attach its incremental listeners before calling `ready`, then remain pending
+ * until the generation is lost or `signal` aborts. On abort it must stop
+ * delivery, release its resources, and settle before a replacement can start.
+ * @param signal - cancellation for the current generation.
+ * @param ready - one-shot report that incremental delivery is attached.
+ * @returns a promise settling only when this generation ends or fails.
+ */
+export type ConnectionGenerationSource = (
+  signal: AbortSignal,
+  ready: (host: ConnectionHostInfo) => void,
+) => Promise<void>
+
+/**
+ * Opens the registered generation source, reconnecting with exponential backoff on loss.
+ * State (generation/attempt) is instance-private, never in the store.
+ * Sink exceptions do not kill the generation loop.
+ */
+export class ConnectionController {
+  private generation = 0
+  private attempt = 0
+  private current: AbortController | null = null
+  private retryDelay: AbortController | null = null
+  private running = false
+  private immediateRetry = false
+  private networkAvailable = true
+  private lastState: ConnectionState | undefined
+  private readonly config: Required<ConnectionRecoveryConfig>
+
+  constructor(
+    private readonly source: ConnectionGenerationSource,
+    private readonly sinks: ConnectionSinks = {},
+    config: ConnectionRecoveryConfig = {},
+  ) {
+    this.config = resolveConnectionConfig(config)
+  }
+
+  /** Idempotent: begin the connect/pump/reconnect loop. */
+  start(): void {
+    if (this.running) return
+    this.running = true
+    void this.loop()
+  }
+
+  /** Stop the loop and abort the current generation source. */
+  stop(): void {
+    this.running = false
+    this.current?.abort()
+    this.current = null
+    this.retryDelay?.abort()
+    this.retryDelay = null
+  }
+
+  /** Reset the retry sequence and replace the current generation or retry delay immediately. */
+  reconnect(): void {
+    if (!this.running) return
+    this.attempt = 0
+    this.immediateRetry = true
+    this.emitState('connecting')
+    if (!this.isRunning()) return
+    this.current?.abort(MANUAL_RECONNECT)
+    this.retryDelay?.abort(MANUAL_RECONNECT)
+  }
+
+  /**
+   * Suspend automatic retries while offline and restart backoff when the network returns.
+   * @param available - whether the browser reports network access.
+   */
+  setNetworkAvailable(available: boolean): void {
+    if (this.networkAvailable === available) return
+    this.networkAvailable = available
+    this.attempt = 0
+    this.immediateRetry = false
+    if (!this.running) return
+    this.emitState(available ? 'connecting' : 'disconnected')
+    if (!this.isRunning()) return
+    this.current?.abort(NETWORK_STATE_CHANGED)
+    this.retryDelay?.abort(NETWORK_STATE_CHANGED)
+  }
+
+  private backoffCap(attempt: number): number {
+    const { backoffBaseMs, backoffFactor, backoffMaxMs } = this.config
+    return Math.min(backoffMaxMs, backoffBaseMs * backoffFactor ** Math.max(0, attempt - 1))
+  }
+
+  private backoffDelay(attempt: number): number {
+    const cap = this.backoffCap(attempt)
+    return cap / 2 + Math.random() * (cap / 2)
+  }
+
+  /** Re-read retry inputs after a potentially reentrant state sink. */
+  private isRetryInterrupted(immediate: boolean): boolean {
+    return this.immediateRetry || (!this.networkAvailable && !immediate)
+  }
+
+  /** Read through a method: stop() flips the flag across awaits, so narrowing from the loop condition must not stick. */
+  private isRunning(): boolean {
+    return this.running
+  }
+
+  /** Re-read both mutable liveness guards after a potentially reentrant sink. */
+  private isGenerationActive(controller: AbortController): boolean {
+    return this.isRunning() && !controller.signal.aborted
+  }
+
+  private async loop(): Promise<void> {
+    let retry = false
+    while (this.running) {
+      if (!this.networkAvailable && !this.immediateRetry) {
+        const retryDelay = new AbortController()
+        this.retryDelay = retryDelay
+        this.emitState('disconnected')
+        await waitForAbort(retryDelay.signal)
+        if (this.retryDelay === retryDelay) this.retryDelay = null
+        if (!this.isRunning()) return
+        retry = true
+        continue
+      }
+
+      let manualAttempt = false
+      if (retry) {
+        const immediate = this.immediateRetry
+        this.immediateRetry = false
+        if (immediate) this.attempt = 0
+        manualAttempt = immediate
+        const attempt = ++this.attempt
+        this.emitState('connecting')
+        if (!this.isRunning()) return
+        if (this.isRetryInterrupted(immediate)) continue
+        if (!immediate) {
+          const retryDelay = new AbortController()
+          this.retryDelay = retryDelay
+          await sleep(this.backoffDelay(attempt), retryDelay.signal)
+          if (this.retryDelay === retryDelay) this.retryDelay = null
+          if (!this.isRunning()) return
+          if (retryDelay.signal.aborted) continue
+        }
+        console.warn(`[connection] connection lost, retry #${String(attempt)}`)
+        this.callSink(() => { this.sinks.onReconnectRequested?.() })
+        if (!this.isRunning()) return
+      }
+
+      const gen = ++this.generation
+      const ac = new AbortController()
+      this.current = ac
+
+      let sourceReady = false
+      let resolveReady!: (host: ConnectionHostInfo) => void
+      let rejectReady!: (error: Error) => void
+      let rejectSourceLost!: (error: Error) => void
+      const ready = new Promise<ConnectionHostInfo>((resolve, reject) => {
+        resolveReady = resolve
+        rejectReady = reject
+      })
+      const sourceLost = new Promise<never>((_resolve, reject) => {
+        rejectSourceLost = reject
+      })
+      const reportReady = (host: ConnectionHostInfo): void => {
+        if (sourceReady || gen !== this.generation || !this.isGenerationActive(ac)) return
+        sourceReady = true
+        resolveReady(host)
+      }
+
+      const failed = new Promise<void>((resolve) => {
+        const settle = (): void => {
+          if (gen === this.generation && !ac.signal.aborted) ac.abort()
+          resolve()
+        }
+        void Promise.resolve()
+          .then(() => this.source(ac.signal, reportReady))
+          .then(
+            () => {
+              const error = new Error('connection generation ended')
+              if (!sourceReady) rejectReady(error)
+              rejectSourceLost(error)
+              settle()
+            },
+            (error: unknown) => {
+              const failure = error instanceof Error
+                ? error
+                : new Error('connection generation failed', { cause: error })
+              if (!sourceReady) rejectReady(failure)
+              rejectSourceLost(failure)
+              settle()
+            },
+          )
+      })
+
+      try {
+        const host = await Promise.race([
+          waitForReady(ready, this.config, ac.signal),
+          sourceLost,
+        ])
+        if (ac.signal.aborted) throw new Error('generation aborted during readiness handshake')
+        this.attempt = 0
+        this.emitState('connected')
+        // A state sink may synchronously stop this controller.
+        if (this.isGenerationActive(ac)) {
+          this.callSink(() => { this.sinks.onConnected?.(host) })
+        }
+      } catch (error) {
+        if (!ac.signal.aborted) ac.abort(error)
+      }
+
+      await failed
+      if (!this.isRunning()) return
+      if (manualAttempt) this.attempt = 0
+      retry = true
+    }
+  }
+
+  /** Deduplicated state emission (sink isolation applies). */
+  private emitState(state: ConnectionState): void {
+    if (this.lastState === state) return
+    this.lastState = state
+    this.callSink(() => this.sinks.onStateChange?.(state))
+  }
+
+  /** Sink exception isolation: a business-layer throw is logged only, never affecting pump or reconnect semantics. */
+  private callSink(fn: () => void): void {
+    try {
+      fn()
+    } catch (error) {
+      console.error('[connection] connection sink threw:', error)
+    }
+  }
+}
+
+/** Report a slow handshake before the hard deadline ends its generation. */
+function waitForReady<T>(
+  ready: Promise<T>,
+  config: Required<ConnectionRecoveryConfig>,
+  signal: AbortSignal,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    let settled = false
+    const warning = setTimeout(() => {
+      console.warn(`[connection] generation is still not ready after ${String(config.generationReadyWarnMs)}ms`)
+    }, config.generationReadyWarnMs)
+    const timeout = setTimeout(() => {
+      const error = new Error(`connection generation was not ready within ${String(config.generationReadyTimeoutMs)}ms`)
+      console.warn(`[connection] ${error.message}; cancelling generation`)
+      finish({ error })
+    }, config.generationReadyTimeoutMs)
+    const aborted = (): void => {
+      finish({ error: new Error('connection generation aborted', { cause: signal.reason }) })
+    }
+    const finish = (outcome: { readonly value: T } | { readonly error: Error }): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(warning)
+      clearTimeout(timeout)
+      signal.removeEventListener('abort', aborted)
+      if ('error' in outcome) reject(outcome.error)
+      else resolve(outcome.value)
+    }
+    signal.addEventListener('abort', aborted, { once: true })
+    void ready.then(
+      (value) => { finish({ value }) },
+      (error: unknown) => {
+        finish({ error: error as Error })
+      },
+    )
+  })
+}

packages/client/connection/src/client/index.ts

@@ -0,0 +1,324 @@
+/** Browser wire client: Remote transport and connection generations. */
+import type { Context } from '@deepseek-ai/cordis'
+import {
+  ConnectionController,
+  type ConnectionRecoveryConfig,
+  type ConnectionGeneration,
+  type ConnectionGenerationSource,
+  type ConnectionSinks,
+  type ConnectionState,
+} from './connection.ts'
+import { createWebConnectionRpc, type RpcFetch, type RpcStreamOpen } from './rpc.ts'
+import { isLoopbackHostname } from '../loopback-hostname.ts'
+import type { ClientConnectionRpc } from '../rpc.ts'
+import { resolveConnectionConfig } from '../recovery-config.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    /**
+     * A connection generation was established. Wire-derived caches must
+     * repull; long-lived streams own their own resume and baseline lifecycle.
+     * @mode emit
+     */
+    'connection/reset'(): void
+  }
+}
+
+// ---- Browser-safe protocol and shared value re-exports ----
+export type {
+  MessageId,
+  RpcRequest, RpcResponse, RpcResult,
+  ClientRequest, ServerResponse, RpcMessage,
+  SessionId, SessionEvent, ContentBlock, StreamChunk,
+} from './api.ts'
+export {
+  RpcId,
+  transportError,
+} from './api.ts'
+
+// Connection loop types are public through ConnectionHandle.start; the
+// controller remains package-internal.
+export type {
+  ConnectionRecoveryConfig,
+  ConnectionGeneration,
+  ConnectionGenerationSource,
+  ConnectionHostInfo,
+  ConnectionSinks,
+  ConnectionState,
+} from './connection.ts'
+export type {
+  ClientConnectionRpc, ConnectionRpcFailure, ConnectionRpcResult,
+} from '../rpc.ts'
+export type { RpcFetch } from './rpc.ts'
+
+/** Observable identity and Host facts for the active connection generation. */
+export interface ConnectionGenerationState {
+  /** Active generation, or undefined before readiness and while reconnecting. */
+  getSnapshot(): ConnectionGeneration | undefined
+  /** Subscribe to generation establishment, replacement, and loss. */
+  subscribe(listener: () => void): () => void
+}
+
+/** Observable recovery lifecycle of the owned Connection loop. */
+export interface ConnectionStateSource {
+  /** Current state, or undefined before the first connection outcome. */
+  getSnapshot(): ConnectionState | undefined
+  /** Subscribe to state changes. */
+  subscribe(listener: () => void): () => void
+}
+
+/** Required services (none — this is the wire root). */
+export const inject: string[] = []
+
+/**
+ * Physical carrier selected when the Connection service is installed. The
+ * served web app omits it and gets HTTP + WebSocket; a shell that owns a
+ * different transport (the worker preview's postMessage tunnel) provides both
+ * halves instead of forking this plugin.
+ */
+export interface ClientTransportHooks {
+  /**
+   * Already decoded logical RPC carrier. When present it replaces the HTTP
+   * caller outright: no envelopes, no `fetch`, no `openStream` (an in-process
+   * Host such as a test mock plugs in here).
+   */
+  rpc?: ClientConnectionRpc
+  /** Transport for generic unary RPC channels (the Typert gateway); unused when `rpc` is present. */
+  fetch?: RpcFetch
+  /** Worker-local Gateway stream carrier; absent when the page uses the Gateway WebSocket or `rpc` is present. */
+  openStream?: RpcStreamOpen
+  /**
+   * Bundle transport for the module system, present when the carrier also owns
+   * bundle bytes (the worker tunnel). Absent in the served web app, whose
+   * bundles load over HTTP.
+   */
+  loadBundle?(url: string): Promise<void>
+  /**
+   * The transport owner declares the page owns the Host outright: the Host
+   * runs inside a worker this page spawned, so no other party can reach it and
+   * the loopback stand-in for "the operator's own machine" is vacuous.
+   * `ctx.connection.isLoopback` then reports the privileged surface reachable
+   * regardless of the page authority. Only a shell that assembles its own
+   * transport can set this; served pages never carry the global at all.
+   */
+  ownsHost?: boolean
+}
+
+/** Page global carrying {@link ClientTransportHooks}; absent in the served web app. */
+interface ClientTransportGlobal {
+  __DSH_TRANSPORT__?: ClientTransportHooks
+  __DSH_CONNECTION_RECOVERY__?: unknown
+}
+
+/** Browser location fields used to classify loopback authority. */
+export interface ConnectionLocation {
+  readonly hostname: string
+}
+
+/** Instance-local inputs for installing a Connection service. */
+export interface ConnectionInstallOptions {
+  /** Explicit physical carrier; omit for the browser HTTP + WebSocket carrier. */
+  readonly transport?: ClientTransportHooks
+  /** Reconnect timing overrides; omitted fields use controller defaults. */
+  readonly recovery?: ConnectionRecoveryConfig
+  /** Page location; omit for a non-browser composition. */
+  readonly location?: ConnectionLocation
+}
+
+/**
+ * The ctx.connection service API. API Gateway supplies generation readiness
+ * and reset callbacks; Connection stays independent of downstream domain state.
+ */
+export interface ConnectionHandle {
+  /**
+   * Whether the privileged surface is reachable: the page authority is
+   * loopback, the transport declares the page owns the Host
+   * ({@link ClientTransportHooks.ownsHost}), or the context is not a browser.
+   */
+  readonly isLoopback: boolean
+  /** Current Remote event generation and the Host facts carried by its opening frame. */
+  readonly generation: ConnectionGenerationState
+  /** Current recovery lifecycle for connection-specific consumers. */
+  readonly state: ConnectionStateSource
+  /** Generic logical RPC channels over the same Connection transport. */
+  readonly rpc: ClientConnectionRpc
+  /** Reset retry progression and replace the current attempt immediately. */
+  reconnect(): void
+  /**
+   * Register the sole source defining Host generations. The source reports
+   * ready only after its incremental listeners are attached.
+   * @param source - long-lived generation source owned by the push carrier.
+   * @returns disposer withdrawing the source and stopping an active loop.
+   */
+  registerGenerationSource(source: ConnectionGenerationSource): () => void
+  /**
+   * Start the connect/reconnect loop with the consumer's state callbacks.
+   * API Gateway owns the loop; a second call throws.
+   * @param sinks - connection-state callbacks.
+   * @param config - explicit timing overrides; omitted fields use Host bootstrap timing.
+   * @returns lifecycle controls for the loop.
+   */
+  start(sinks: ConnectionSinks, config?: ConnectionRecoveryConfig): ConnectionLoop
+}
+
+/** Controls retained by the sole owner of a running connection loop. */
+export interface ConnectionLoop {
+  /** Stop the loop and withdraw its active generation. */
+  stop(): void
+}
+
+interface ConnectionOwner {
+  readonly token: object
+  readonly source: ConnectionGenerationSource
+  readonly controller: ConnectionController
+  readonly stopNetworkWatch: () => void
+}
+
+interface BrowserNetworkTarget {
+  readonly navigator?: { readonly onLine?: boolean }
+  addEventListener(type: 'online' | 'offline', listener: () => void): void
+  removeEventListener(type: 'online' | 'offline', listener: () => void): void
+}
+
+function watchBrowserNetwork(controller: ConnectionController): () => void {
+  const browser = (globalThis as { readonly window?: BrowserNetworkTarget }).window
+  const initiallyAvailable = browser?.navigator?.onLine
+  if (browser === undefined || initiallyAvailable === undefined) return () => {}
+  const online = (): void => { controller.setNetworkAvailable(true) }
+  const offline = (): void => { controller.setNetworkAvailable(false) }
+  controller.setNetworkAvailable(initiallyAvailable)
+  browser.addEventListener('online', online)
+  browser.addEventListener('offline', offline)
+  return () => {
+    browser.removeEventListener('online', online)
+    browser.removeEventListener('offline', offline)
+  }
+}
+
+/**
+ * Install one Context-owned Connection service from explicit composition inputs.
+ * @param ctx - client Cordis context.
+ * @param options - physical carrier, reconnect timing, and page location.
+ */
+export function installConnection(ctx: Context, options: ConnectionInstallOptions = {}): void {
+  const pageLocation = options.location
+  const transport = options.transport
+  const recovery = options.recovery ?? {}
+  const rpc = transport?.rpc ?? createWebConnectionRpc(transport?.fetch, transport?.openStream)
+  let generationSource: ConnectionGenerationSource | undefined
+  let owner: ConnectionOwner | undefined
+  let generationId = 0
+  let generation: ConnectionGeneration | undefined
+  let state: ConnectionState | undefined
+  const generationListeners = new Set<() => void>()
+  const stateListeners = new Set<() => void>()
+  const publishGeneration = (next: ConnectionGeneration | undefined): void => {
+    if (Object.is(generation, next)) return
+    generation = next
+    for (const listener of [...generationListeners]) {
+      try {
+        listener()
+      } catch (error) {
+        console.error('[connection] generation listener threw:', error)
+      }
+    }
+  }
+  const publishState = (next: ConnectionState | undefined): void => {
+    if (state === next) return
+    state = next
+    for (const listener of [...stateListeners]) {
+      try {
+        listener()
+      } catch (error) {
+        console.error('[connection] state listener threw:', error)
+      }
+    }
+  }
+  const releaseOwner = (current: ConnectionOwner): void => {
+    if (owner !== current) return
+    owner = undefined
+    current.stopNetworkWatch()
+    current.controller.stop()
+    publishGeneration(undefined)
+    publishState(undefined)
+  }
+  const handle: ConnectionHandle = {
+    isLoopback: transport?.ownsHost === true || pageLocation === undefined || isLoopbackHostname(pageLocation.hostname),
+    generation: {
+      getSnapshot: () => generation,
+      subscribe: (listener) => {
+        generationListeners.add(listener)
+        return () => { generationListeners.delete(listener) }
+      },
+    },
+    state: {
+      getSnapshot: () => state,
+      subscribe: (listener) => {
+        stateListeners.add(listener)
+        return () => { stateListeners.delete(listener) }
+      },
+    },
+    rpc,
+    reconnect() {
+      owner?.controller.reconnect()
+    },
+    registerGenerationSource(source) {
+      if (generationSource !== undefined) {
+        throw new Error('connection: a generation source is already registered')
+      }
+      generationSource = source
+      return () => {
+        if (generationSource !== source) return
+        generationSource = undefined
+        const current = owner
+        if (current?.source === source) releaseOwner(current)
+      }
+    },
+    start(sinks, config) {
+      if (owner !== undefined) throw new Error('connection: the stream loop is already owned by another consumer')
+      const source = generationSource
+      if (source === undefined) throw new Error('connection: no generation source is registered')
+      const token = {}
+      const ownsGeneration = (): boolean => owner?.token === token
+      const controller = new ConnectionController(source, {
+        ...sinks,
+        onConnected: (host) => {
+          const nextGeneration = { id: ++generationId, host }
+          publishGeneration(nextGeneration)
+          if (!ownsGeneration() || !Object.is(generation, nextGeneration)) return
+          sinks.onConnected?.(host)
+        },
+        onStateChange: (state) => {
+          if (state !== 'connected') {
+            publishGeneration(undefined)
+          }
+          if (!ownsGeneration()) return
+          publishState(state)
+          sinks.onStateChange?.(state)
+        },
+      }, { ...recovery, ...config })
+      const current = { token, source, controller, stopNetworkWatch: watchBrowserNetwork(controller) }
+      owner = current
+      controller.start()
+      return {
+        stop: () => { releaseOwner(current) },
+      }
+    },
+  }
+  ctx.provide('connection', handle)
+}
+
+/**
+ * Client plugin body: read the page composition and install its Connection service.
+ * @param ctx - client Cordis context.
+ */
+export function apply(ctx: Context): void {
+  const globals = globalThis as ClientTransportGlobal
+  const pageLocation = typeof location === 'undefined' ? undefined : location
+  const transport = globals.__DSH_TRANSPORT__
+  installConnection(ctx, {
+    ...(transport === undefined ? {} : { transport }),
+    recovery: resolveConnectionConfig(globals.__DSH_CONNECTION_RECOVERY__),
+    ...(pageLocation === undefined ? {} : { location: pageLocation }),
+  })
+}

packages/client/connection/src/client/random-uuid.ts

@@ -0,0 +1,14 @@
+/** Browser-safe UUID generation for client-side wire correlation. */
+
+/**
+ * Generate an RFC 4122 version 4 UUID without requiring a secure context.
+ * @returns a UUID backed by `crypto.getRandomValues()`, which browsers expose on insecure origins.
+ */
+export function randomUuid(): string {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16))
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  view.setUint8(6, (view.getUint8(6) & 0x0f) | 0x40)
+  view.setUint8(8, (view.getUint8(8) & 0x3f) | 0x80)
+  const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}

packages/client/connection/src/client/rpc.ts

@@ -0,0 +1,120 @@
+/** Browser caller for generic Connection unary RPC channels. */
+
+import {
+  RpcId,
+  type ClientRequest,
+  type RpcId as RpcIdType,
+} from '../rpc.ts'
+import type { ClientConnectionRpc, ConnectionRpcResult } from '../rpc.ts'
+import { randomUuid } from './random-uuid.ts'
+
+const INTERNAL_BASE = 'http://dsh.internal'
+const CHANNEL_PATTERN = /^\/[A-Za-z0-9._~-]+$/
+const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
+
+/** Transport this caller posts through; same signature as the global `fetch`. */
+export type RpcFetch = (input: URL, init: RequestInit) => Promise<Response>
+
+/** Worker-local opener for decoded Gateway Remote streams. */
+export type RpcStreamOpen = (
+  endpoint: string,
+  payload: unknown,
+  signal: AbortSignal,
+) => AsyncIterable<unknown>
+
+/**
+ * Create the browser-backed generic RPC caller.
+ * @param doFetch - transport override; defaults to the page's global fetch.
+ * @param openStream - optional worker-local Gateway stream carrier.
+ * @returns caller that owns request correlation and response-envelope validation.
+ */
+export function createWebConnectionRpc(doFetch?: RpcFetch, openStream?: RpcStreamOpen): ClientConnectionRpc {
+  const send: RpcFetch = doFetch ?? ((input, init) => globalThis.fetch(input, init))
+  return {
+    async call(channel, endpoint, payload, signal) {
+      assertTarget(channel, endpoint)
+      const rpcId = RpcId(randomUuid())
+      const message: ClientRequest = {
+        type: 'client-request',
+        rpcId,
+        method: endpoint,
+        payload,
+      }
+      const response = await send(
+        new URL(`${channel}/${endpoint}`, resolveBase()),
+        {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(message),
+          ...signal === undefined ? {} : { signal },
+        },
+      )
+      if (!response.ok) {
+        throw new Error(`transport failure for ${channel}/${endpoint}: HTTP ${response.status}`)
+      }
+      const full = parseConnectionResponse(await response.json())
+      if (full.rpcId !== rpcId) {
+        throw new Error(`rpcId mismatch for ${endpoint}: sent ${rpcId}, got ${full.rpcId}`)
+      }
+      return full.result
+    },
+    ...openStream === undefined ? {} : {
+      open(channel, endpoint, payload, signal) {
+        assertTarget(channel, endpoint)
+        if (channel !== '/api') {
+          throw new Error(`connection: worker-local streams require the /api channel, got ${JSON.stringify(channel)}`)
+        }
+        return openStream(endpoint, payload, signal)
+      },
+    },
+  }
+}
+
+function parseConnectionResponse(value: unknown): {
+  readonly rpcId: RpcIdType
+  readonly result: ConnectionRpcResult<unknown>
+} {
+  if (!isRecord(value) || value.type !== 'server-response' || typeof value.rpcId !== 'string') {
+    throw new TypeError('connection: invalid server-response envelope')
+  }
+  const result = value.result
+  if (!isRecord(result)) throw new TypeError('connection: invalid server-response result')
+  if (result.ok === true) {
+    return {
+      rpcId: RpcId(value.rpcId),
+      result: { ok: true, value: result.value },
+    }
+  }
+  if (result.ok !== false || !isRecord(result.error)) {
+    throw new TypeError('connection: invalid server-response result')
+  }
+  const error = result.error
+  if (typeof error.code !== 'string' || typeof error.message !== 'string' || !isRecord(error.details)) {
+    throw new TypeError('connection: invalid server-response failure')
+  }
+  return {
+    rpcId: RpcId(value.rpcId),
+    result: {
+      ok: false,
+      error: { code: error.code, message: error.message, details: error.details },
+    },
+  }
+}
+
+function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function resolveBase(): string {
+  const location = (globalThis as { location?: { origin?: string } }).location
+  return location?.origin !== undefined && location.origin !== 'null' ? location.origin : INTERNAL_BASE
+}
+
+function assertTarget(channel: string, endpoint: string): void {
+  const segments = endpoint.split('/')
+  if (!CHANNEL_PATTERN.test(channel)
+    || segments.some(segment =>
+      segment === '' || segment === '.' || segment === '..' || !ENDPOINT_SEGMENT_PATTERN.test(segment))) {
+    throw new Error(`connection: invalid RPC target ${JSON.stringify(`${channel}/${endpoint}`)}`)
+  }
+}

packages/client/connection/src/http-bridge.ts

@@ -0,0 +1,111 @@
+/**
+ * node:http ↔ WHATWG fetch bridge for the /api transport (host side of the
+ * web carrier; the fetch-shaped handler itself is transport-agnostic).
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { Readable } from 'node:stream'
+import type { ConnectionFetchHandler } from './rpc.ts'
+
+/** Default carrier cap for all HTTP RPC bodies: sized for the default
+ * aggregate image limit (200 MiB) after base64 expansion plus envelope
+ * headroom (~267.7 MiB required), rounded up for slack. The bridge buffers
+ * each body in memory, so this cap is also the per-request resident bound. */
+export const DEFAULT_MAX_REQUEST_BODY_BYTES = 300 * 1024 * 1024
+
+/**
+ * Bridge one node:http request to the fetch-shaped handler (client close
+ * aborts; response bodies stream out chunk by chunk).
+ * @param req - incoming node:http request.
+ * @param res - node:http response the bridge writes and owns to completion.
+ * @param apiHandler - fetch-shaped API carrier the request is dispatched to.
+ * @param maxRequestBodyBytes - maximum bytes buffered for a buffered route.
+ */
+export async function bridge(
+  req: IncomingMessage,
+  res: ServerResponse,
+  apiHandler: ConnectionFetchHandler,
+  maxRequestBodyBytes = DEFAULT_MAX_REQUEST_BODY_BYTES,
+): Promise<void> {
+  const abort = new AbortController()
+  // Client-disconnect detection MUST hang off the response, not the request:
+  // since Node 16, IncomingMessage 'close' fires as soon as the request body is
+  // fully consumed (immediately for a bodyless GET), which would abort a
+  // streaming response right after open. ServerResponse 'close' fires on connection teardown;
+  // writableEnded distinguishes a normal end() from the client going away.
+  res.on('close', () => {
+    if (!res.writableEnded) abort.abort()
+  })
+  /* v8 ignore next 2 -- node:http always sets url/method on server requests. */
+  const url = new URL(req.url ?? '/', 'http://dsh.internal')
+  const method = req.method ?? 'GET'
+  const headers = Object.fromEntries(
+    Object.entries(req.headers).filter(([, value]) => typeof value === 'string') as [string, string][],
+  )
+  const bodyMode = apiHandler.requestBodyMode({ method, url })
+  let request: Request
+  if (bodyMode === 'buffered') {
+    const declaredLength = req.headers['content-length']
+    if (declaredLength !== undefined && Number(declaredLength) > maxRequestBodyBytes) {
+      res.writeHead(413, { connection: 'close' })
+      res.end()
+      req.destroy()
+      return
+    }
+    const chunks: Buffer[] = []
+    let received = 0
+    for await (const chunk of req) {
+      const buffer = chunk as Buffer
+      received += buffer.byteLength
+      if (received > maxRequestBodyBytes) {
+        res.writeHead(413, { connection: 'close' })
+        res.end()
+        req.destroy()
+        return
+      }
+      chunks.push(buffer)
+    }
+    request = new Request(url, {
+      method,
+      headers,
+      ...chunks.length > 0 ? { body: Buffer.concat(chunks) } : {},
+      signal: abort.signal,
+    })
+  } else {
+    request = new Request(url, {
+      method,
+      headers,
+      body: Readable.toWeb(req) as ReadableStream<Uint8Array>,
+      signal: abort.signal,
+      duplex: 'half',
+    } as RequestInit & { duplex: 'half' })
+  }
+  const response = await apiHandler.fetch(request)
+  const requestUnread = bodyMode === 'streaming' && !req.readableEnded
+  const responseHeaders = Object.fromEntries(response.headers.entries())
+  res.writeHead(response.status, requestUnread ? { ...responseHeaders, connection: 'close' } : responseHeaders)
+  if (response.body === null) {
+    res.end()
+    if (requestUnread) req.destroy()
+    return
+  }
+  for await (const chunk of response.body) {
+    // Backpressure: a false return means the socket buffer is full — wait for drain
+    // instead of buffering unboundedly (slow or suspended consumers). 'close' also
+    // resolves so a mid-wait disconnect can't park this loop forever; the close
+    // handler above aborts the handler stream, which then ends the iteration.
+    if (!res.write(chunk)) {
+      await new Promise<void>((resolve) => {
+        const done = (): void => {
+          res.off('drain', done)
+          res.off('close', done)
+          resolve()
+        }
+        res.once('drain', done)
+        res.once('close', done)
+      })
+    }
+  }
+  res.end()
+  if (requestUnread) req.destroy()
+}

packages/client/connection/src/index.ts

@@ -0,0 +1,143 @@
+/** Host HTTP bridge for browser-client RPC. */
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type {} from '@deepseek-ai/dsh-attachment'
+import type {} from '@deepseek-ai/dsh-credentials'
+// Activates the webServer Context merge used below.
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import { API_PATH } from './api-path.ts'
+import { bridge, DEFAULT_MAX_REQUEST_BODY_BYTES } from './http-bridge.ts'
+import { assertTrustedAuthority } from './api-request-trust.ts'
+import { BrowserAuth } from './browser-auth.ts'
+import { HostConnectionService } from './rpc-host.ts'
+import { ConnectionRecoveryConfigSchema, resolveConnectionConfig, type ConnectionRecoveryConfig } from './recovery-config.ts'
+
+export type {
+  ConnectionFetchMethod,
+  ConnectionFetchHandler,
+  ConnectionFetchRoute,
+  ConnectionIndexRequest,
+  ConnectionIndexResponse,
+  ConnectionRpcEndpointMatcher,
+  ConnectionRpcFailure,
+  ConnectionRpcHandler,
+  ConnectionRequestRejection,
+  ConnectionRpcResult,
+  ConnectionRequestBodyMode,
+  ConnectionTrustRequest,
+  ClientRequest,
+  HostConnectionHandle,
+  HostConnectionFetch,
+  HostConnectionRpc,
+  RpcMessage,
+  ServerResponse,
+} from './rpc.ts'
+export { RpcId, transportError } from './rpc.ts'
+export {
+  clientRequestSchema,
+  rpcErrorSchema,
+  rpcIdSchema,
+  rpcMessageSchema,
+  rpcResultSchema,
+  serverResponseSchema,
+} from './rpc-schema.ts'
+export { HostConnectionService } from './rpc-host.ts'
+
+export { API_PATH } from './api-path.ts'
+
+/** Stable Cordis plugin name. */
+export const name = 'client-connection'
+
+/** Headroom for RPC JSON fields around aggregate base64 image payloads. */
+const REQUEST_ENVELOPE_HEADROOM_BYTES = 1024 * 1024
+
+function assertImageBodyCapacity(ctx: Context, maxRequestBodyBytes: number): void {
+  const attachments = ctx.get('attachments')
+  if (attachments === undefined) return
+  const requiredImageBodyBytes = Math.ceil(
+    attachments.imageLimits.maxMessageImageBytes * 4 / 3,
+  ) + REQUEST_ENVELOPE_HEADROOM_BYTES
+  if (maxRequestBodyBytes < requiredImageBodyBytes) {
+    throw new Error(
+      `client-connection maxRequestBodyBytes (${String(maxRequestBodyBytes)}) must be at least `
+      + `${String(requiredImageBodyBytes)} for the configured aggregate image limit`,
+    )
+  }
+}
+
+/** Services required before providing Connection. */
+export const inject = ['credentials']
+
+/** Browser authentication, request limits, and connection recovery configuration. */
+export interface ConnectionConfig {
+  /** Browser recovery timing, injected into each served page. */
+  recovery?: ConnectionRecoveryConfig
+  /**
+   * Authorities this deployment serves beyond loopback: exact `host:port`, or
+   * port-less `host` matching any port. The /api trust fence refuses any
+   * request whose Host is neither loopback nor listed here, so a
+   * non-loopback (`0.0.0.0`) deployment must declare the names it is reached
+   * by; the Web runtime derives LAN IP literals from an active all-interface
+   * bind. An entry that is not a bare, canonical authority fails plugin load.
+   */
+  trustedHosts?: string[]
+  /** Absolute browser-session lifetime in days. Default: 30. */
+  cookieMaxAgeDays?: number
+  /** Maximum buffered JSON body for every `/api` request. Default: 300 MiB. */
+  maxRequestBodyBytes?: number
+}
+
+export const Config: z<ConnectionConfig> = z.object({
+  recovery: ConnectionRecoveryConfigSchema.default({}),
+  trustedHosts: z.array(String).default([]),
+  cookieMaxAgeDays: z.natural().min(1).default(30),
+  maxRequestBodyBytes: z.natural().min(1).default(DEFAULT_MAX_REQUEST_BODY_BYTES),
+})
+
+/**
+ * Provides carrier-neutral RPC and Fetch registries. When `webServer` is
+ * present, the plugin also mounts the `/api` browser transport with Host/Origin
+ * checks and persistent browser authentication.
+ * @param ctx - Host plugin context.
+ * @param config - resolved plugin config (schema defaults applied).
+ */
+export async function apply(ctx: Context, config?: ConnectionConfig): Promise<void> {
+  const recovery = resolveConnectionConfig(config?.recovery)
+  // The Loader resolves schema defaults; hand-built test contexts may pass none.
+  const trustedHosts = config?.trustedHosts ?? []
+  const cookieMaxAgeDays = config?.cookieMaxAgeDays ?? 30
+  const maxRequestBodyBytes = config?.maxRequestBodyBytes ?? DEFAULT_MAX_REQUEST_BODY_BYTES
+  // Config boundary: a malformed entry fails the load loudly here rather than
+  // silently authorizing its hostname prefix at request time.
+  for (const entry of trustedHosts) assertTrustedAuthority(entry)
+  assertImageBodyCapacity(ctx, maxRequestBodyBytes)
+  const connection = new HostConnectionService(
+    ctx,
+    trustedHosts,
+    await BrowserAuth.create(ctx.root, ctx.credentials, cookieMaxAgeDays),
+  )
+  ctx.inject(['webServer'], (webCtx) => {
+    assertImageBodyCapacity(webCtx, maxRequestBodyBytes)
+    webCtx.on('webserver/index-inject', (table) => {
+      table.push({ kind: 'global', name: '__DSH_CONNECTION_RECOVERY__', value: recovery })
+    })
+    const fetchHandler = connection.createSharedFetchHandler(API_PATH)
+    const route: WebRoute = {
+      kind: 'prefix',
+      path: API_PATH,
+      handler: async (req, res) => {
+        const rejection = connection.requestRejection(req)
+        if (rejection !== undefined) {
+          res.writeHead(rejection)
+          res.end(rejection === 401 ? 'unauthorized' : 'forbidden')
+          return
+        }
+        await bridge(req, res, fetchHandler, maxRequestBodyBytes)
+      },
+    }
+    webCtx.effect(() => webCtx.webServer.register(route), 'client-connection: /api route')
+  })
+  ctx.inject(['attachments'], (attachmentCtx) => {
+    assertImageBodyCapacity(attachmentCtx, maxRequestBodyBytes)
+  })
+}

packages/client/connection/src/loopback-hostname.ts

@@ -0,0 +1,18 @@
+/**
+ * Browser-safe, zero-dependency loopback classification shared by the `/api`
+ * Host fence and the package's `ctx.connection` state. The predicate stays
+ * package-internal; client plugins consume the derived state through Cordis.
+ */
+
+/**
+ * Whether a normalized URL hostname names the local loopback authority.
+ * @param hostname - WHATWG URL hostname (IPv6 literals retain brackets).
+ * @returns true for localhost, IPv6 loopback, or any IPv4 address in 127/8.
+ */
+export function isLoopbackHostname(hostname: string): boolean {
+  if (hostname === 'localhost' || hostname === '[::1]') return true
+  const parts = hostname.split('.')
+  return parts.length === 4
+    && parts[0] === '127'
+    && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}

packages/client/connection/src/recovery-config.ts

@@ -0,0 +1,44 @@
+/** Shared validation for Host-configured and browser-local connection recovery. */
+import z from '@deepseek-ai/schemastery'
+
+/** Timing for generation readiness and automatic reconnection. */
+export interface ConnectionRecoveryConfig {
+  /** First-retry delay cap in ms; actual delay is 50–100% of the cap. Default: 500. */
+  backoffBaseMs?: number
+  /** Finite growth factor of at least 1 per failed attempt; 1 keeps a fixed cap. Default: 2. */
+  backoffFactor?: number
+  /** Maximum retry delay cap in ms; retries continue at this cap. Default: 10000. */
+  backoffMaxMs?: number
+  /**
+   * Delay before reporting a slow handshake, without cancelling it. Default: 3000.
+   * Omitted when readiness, failure, cancellation, or the hard deadline occurs first.
+   */
+  generationReadyWarnMs?: number
+  /** Deadline in ms for readiness, including physical connection setup. Default: 15000. */
+  generationReadyTimeoutMs?: number
+}
+
+// Browsers and Node share this maximum signed 32-bit timer delay.
+const MAX_TIMER_MS = 2_147_483_647
+
+/** Schema shared by the Host plugin and the Client's recovery input parser. */
+export const ConnectionRecoveryConfigSchema: z<ConnectionRecoveryConfig> = z.object({
+  backoffBaseMs: z.natural().min(1).max(MAX_TIMER_MS).default(500),
+  backoffFactor: z.number().min(1).max(Number.MAX_VALUE).default(2),
+  backoffMaxMs: z.natural().min(1).max(MAX_TIMER_MS).default(10_000),
+  generationReadyWarnMs: z.natural().min(1).max(MAX_TIMER_MS).default(3_000),
+  generationReadyTimeoutMs: z.natural().min(1).max(MAX_TIMER_MS).default(15_000),
+})
+
+/**
+ * Validate recovery input and supply every timing default before starting work.
+ * @param config - Host configuration, page bootstrap data, or direct loop options.
+ * @returns validated, complete recovery timing.
+ */
+export function resolveConnectionConfig(config: unknown = {}): Required<ConnectionRecoveryConfig> {
+  const resolved = ConnectionRecoveryConfigSchema(config as ConnectionRecoveryConfig) as Required<ConnectionRecoveryConfig>
+  if (!Number.isFinite(resolved.backoffFactor)) {
+    throw new RangeError('connection recovery backoffFactor must be finite')
+  }
+  return resolved
+}

packages/client/connection/src/rpc-host.ts

@@ -0,0 +1,303 @@
+/** Host registry and HTTP adapter for generic Connection RPC channels. */
+
+import { Context, Service } from '@deepseek-ai/cordis'
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import {
+  RpcId,
+  type ClientRequest,
+  type RpcId as RpcIdType,
+} from './rpc.ts'
+import { clientRequestSchema } from './rpc-schema.ts'
+import { bridge } from './http-bridge.ts'
+import { isTrustedApiRequest } from './api-request-trust.ts'
+import { API_PATH } from './api-path.ts'
+import type { BrowserAuth } from './browser-auth.ts'
+import type {
+  ConnectionIndexRequest,
+  ConnectionIndexResponse,
+  ConnectionFetchRoute,
+  ConnectionFetchHandler,
+  HostConnectionFetch,
+  ConnectionRpcEndpointMatcher,
+  ConnectionRpcFailure,
+  ConnectionRpcHandler,
+  ConnectionRpcResult,
+  ConnectionRequestRejection,
+  ConnectionTrustRequest,
+  HostConnectionHandle,
+  HostConnectionRpc,
+} from './rpc.ts'
+
+const INVALID_REQUEST_RPC_ID = RpcId('invalid-request')
+const CHANNEL_PATTERN = /^\/[A-Za-z0-9._~-]+$/
+const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
+
+interface ConnectionRpcInterceptor {
+  readonly matches: ConnectionRpcEndpointMatcher
+  readonly fetchHandler: ConnectionFetchHandler
+}
+
+interface RegisteredFetchRoute {
+  readonly methods: ReadonlySet<string>
+  readonly requestBody: ConnectionFetchRoute['requestBody']
+  readonly fetch: ConnectionFetchRoute['fetch']
+}
+
+interface ConnectionServerResponse {
+  readonly type: 'server-response'
+  readonly rpcId: RpcIdType
+  readonly result: ConnectionRpcResult<unknown>
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Host Connection transport and RPC registrations. */
+    connection: HostConnectionHandle
+  }
+}
+
+/** Host Connection service whose channel registrations belong to the caller fiber. */
+export class HostConnectionService extends Service implements HostConnectionHandle {
+  private readonly interceptors = new Map<string, ConnectionRpcInterceptor>()
+  private readonly fetchRoutes = new Map<string, RegisteredFetchRoute>()
+
+  /**
+   * Provide the Host half over the active HTTP server.
+   * @param ctx - owning Connection plugin context.
+   * @param trustedHosts - deployment authorities accepted by the Host/Origin fence.
+   * @param browserAuth - process token and persistent browser-session owner.
+   */
+  constructor(
+    ctx: Context,
+    private readonly trustedHosts: readonly string[],
+    private readonly browserAuth: BrowserAuth,
+  ) {
+    super(ctx, 'connection')
+  }
+
+  /** Generic channel registry scoped to the Context reading this service. */
+  get rpc(): HostConnectionRpc {
+    const owner = this.ctx
+    return {
+      handle: (channel, handler) => this.register(owner, channel, handler),
+      intercept: (channel, matches, handler) =>
+        this.registerInterceptor(owner, channel, matches, handler),
+    }
+  }
+
+  /** Exact Fetch-route registry scoped to the Context reading this service. */
+  get fetch(): HostConnectionFetch {
+    const owner = this.ctx
+    return {
+      register: route => this.registerFetchRoute(owner, route),
+    }
+  }
+
+  /** Apply the configured Host/Origin fence, then browser authentication. */
+  requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection {
+    if (!isTrustedApiRequest(request, this.trustedHosts)) return 403
+    return this.browserAuth.isAuthenticated(request) ? undefined : 401
+  }
+
+  /** Authenticate an index request through the process-token exchange or cookie. */
+  authorizeIndex(request: ConnectionIndexRequest, response: ConnectionIndexResponse): boolean {
+    return this.browserAuth.authorizeIndex(request, response)
+  }
+
+  /** Add this process's launch token to the clean application URL. */
+  authenticatedUrl(baseUrl: string): string {
+    return this.browserAuth.authenticatedUrl(baseUrl)
+  }
+
+  /**
+   * Compose one shared-channel Fetch handler from exact routes and its interceptor.
+   * @param channel - shared channel mounted by Connection.
+   * @returns Fetch handler that selects one owner or returns 404.
+   */
+  createSharedFetchHandler(
+    channel: '/api',
+  ): ConnectionFetchHandler {
+    return {
+      requestBodyMode: ({ method, url }) => {
+        const route = this.fetchRoutes.get(url.pathname)
+        return route?.methods.has(method) === true ? route.requestBody : 'buffered'
+      },
+      fetch: (request) => {
+        const pathname = new URL(request.url).pathname
+        const route = this.fetchRoutes.get(pathname)
+        if (route?.methods.has(request.method) === true) return route.fetch(request)
+        const endpoint = endpointFromPath(channel, pathname)
+        const interceptor = this.interceptors.get(channel)
+        if (endpoint === undefined || interceptor === undefined || !interceptor.matches(endpoint)) {
+          return Promise.resolve(new Response('not found', { status: 404 }))
+        }
+        return interceptor.fetchHandler.fetch(request)
+      },
+    }
+  }
+
+  private registerFetchRoute(
+    owner: Context,
+    route: ConnectionFetchRoute,
+  ): () => Promise<void> {
+    assertFetchRoute(route)
+    const registered: RegisteredFetchRoute = {
+      methods: new Set(route.methods),
+      requestBody: route.requestBody,
+      fetch: route.fetch,
+    }
+    return owner.effect(() => {
+      if (this.fetchRoutes.has(route.path)) {
+        throw new Error(`connection: exact Fetch route ${JSON.stringify(route.path)} is already registered`)
+      }
+      this.fetchRoutes.set(route.path, registered)
+      return () => { this.fetchRoutes.delete(route.path) }
+    }, `client-connection: ${route.path} Fetch route`)
+  }
+
+  private register(
+    owner: Context,
+    channel: string,
+    handler: ConnectionRpcHandler,
+  ): () => Promise<void> {
+    assertChannel(channel)
+    const fetchHandler = rpcFetchHandler(channel, handler)
+    const route: WebRoute = {
+      kind: 'prefix',
+      path: channel,
+      handler: async (req, res) => {
+        const rejection = this.requestRejection(req)
+        if (rejection !== undefined) {
+          res.writeHead(rejection)
+          res.end(rejection === 401 ? 'unauthorized' : 'forbidden')
+          return
+        }
+        await bridge(req, res, fetchHandler)
+      },
+    }
+    return owner.effect(
+      () => owner.webServer.register(route),
+      `client-connection: ${channel} rpc channel`,
+    )
+  }
+
+  private registerInterceptor(
+    owner: Context,
+    channel: string,
+    matches: ConnectionRpcEndpointMatcher,
+    handler: ConnectionRpcHandler,
+  ): () => Promise<void> {
+    if (channel !== API_PATH) {
+      throw new Error(`connection: invalid shared RPC channel ${JSON.stringify(channel)}`)
+    }
+    const interceptor: ConnectionRpcInterceptor = {
+      matches,
+      fetchHandler: rpcFetchHandler(channel, handler),
+    }
+    return owner.effect(() => {
+      if (this.interceptors.has(channel)) {
+        throw new Error(`connection: shared RPC channel ${JSON.stringify(channel)} already has an interceptor`)
+      }
+      this.interceptors.set(channel, interceptor)
+      return () => {
+        this.interceptors.delete(channel)
+      }
+    }, `client-connection: ${channel} rpc interceptor`)
+  }
+}
+
+function rpcFetchHandler(
+  channel: string,
+  handler: ConnectionRpcHandler,
+): ConnectionFetchHandler {
+  return {
+    requestBodyMode: () => 'buffered',
+    async fetch(request: Request): Promise<Response> {
+      const endpoint = endpointFromPath(channel, new URL(request.url).pathname)
+      if (request.method !== 'POST' || endpoint === undefined) {
+        return new Response('not found', { status: 404 })
+      }
+
+      const mediaType = request.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase()
+      if (mediaType !== 'application/json') {
+        return new Response('content type must be application/json', { status: 415 })
+      }
+
+      let body: unknown
+      try {
+        body = await request.json()
+      } catch {
+        return new Response('body is not JSON', { status: 400 })
+      }
+
+      const envelope = clientRequestSchema.safeParse(body)
+      if (!envelope.success) {
+        return invalidEnvelopeResponse(body, envelope.error.issues)
+      }
+      const message: ClientRequest = envelope.data
+      if (message.method !== endpoint) {
+        return errorResponse(message.rpcId, {
+          code: 'gateway/bad-request',
+          message: `method ${JSON.stringify(message.method)} does not match endpoint ${JSON.stringify(endpoint)}`,
+          details: { issues: [] },
+        })
+      }
+
+      try {
+        const result = await handler(endpoint, message.payload, request.signal)
+        return fullResponse(message.rpcId, result)
+      } catch (error) {
+        return new Response(`handler failure: ${String(error)}`, { status: 500 })
+      }
+    },
+  }
+}
+
+function invalidEnvelopeResponse(body: unknown, issues: readonly object[]): Response {
+  const rawId = (body as { rpcId?: unknown } | null)?.rpcId
+  const rpcId = typeof rawId === 'string' ? RpcId(rawId) : INVALID_REQUEST_RPC_ID
+  return errorResponse(rpcId, {
+    code: 'gateway/bad-request',
+    message: 'invalid client-request message',
+    details: { issues },
+  })
+}
+
+function endpointFromPath(channel: string, pathname: string): string | undefined {
+  if (!pathname.startsWith(`${channel}/`)) return undefined
+  const endpoint = pathname.slice(channel.length + 1)
+  const segments = endpoint.split('/')
+  if (segments.some(segment =>
+    segment === '' || segment === '.' || segment === '..' || !ENDPOINT_SEGMENT_PATTERN.test(segment))) {
+    return undefined
+  }
+  return endpoint
+}
+
+function errorResponse(rpcId: RpcIdType, error: ConnectionRpcFailure): Response {
+  return fullResponse(rpcId, { ok: false, error })
+}
+
+function fullResponse(rpcId: RpcIdType, result: ConnectionRpcResult<unknown>): Response {
+  const body: ConnectionServerResponse = { type: 'server-response', rpcId, result }
+  return Response.json(body)
+}
+
+function assertChannel(channel: string): void {
+  if (!CHANNEL_PATTERN.test(channel) || channel === '/api') {
+    throw new Error(`connection: invalid or reserved RPC channel ${JSON.stringify(channel)}`)
+  }
+}
+
+function assertFetchRoute(route: ConnectionFetchRoute): void {
+  if (endpointFromPath(API_PATH, route.path) === undefined) {
+    throw new Error(`connection: invalid exact Fetch route ${JSON.stringify(route.path)}`)
+  }
+  if (route.methods.length === 0) {
+    throw new Error(`connection: exact Fetch route ${JSON.stringify(route.path)} declares no methods`)
+  }
+  const methods = new Set(route.methods)
+  if (methods.size !== route.methods.length) {
+    throw new Error(`connection: exact Fetch route ${JSON.stringify(route.path)} repeats a method`)
+  }
+}

packages/client/connection/src/rpc-schema.ts

@@ -0,0 +1,53 @@
+/** Runtime validation for Connection RPC envelopes. */
+
+import { z } from 'zod'
+import type { ClientRequest, RpcId, RpcMessage, ServerResponse } from './rpc.ts'
+
+/** Correlation id after wire validation. */
+export const rpcIdSchema = z.string() as unknown as z.ZodType<RpcId>
+
+/** Generic endpoint failure carried in a response envelope. */
+export const rpcErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  details: z.record(z.string(), z.unknown()),
+})
+
+/**
+ * Build the result parser for one endpoint value parser.
+ * @param value - endpoint-owned success-value parser.
+ * @returns parser for either a success value or generic failure.
+ */
+export function rpcResultSchema<T>(value: z.ZodType<T>): z.ZodType<{
+  readonly ok: true
+  readonly value: T
+} | {
+  readonly ok: false
+  readonly error: z.infer<typeof rpcErrorSchema>
+}> {
+  return z.union([
+    z.object({ ok: z.literal(true), value }),
+    z.object({ ok: z.literal(false), error: rpcErrorSchema }),
+  ])
+}
+
+/** Client request envelope; endpoint payload validation belongs to its owner. */
+export const clientRequestSchema = z.object({
+  type: z.literal('client-request'),
+  rpcId: rpcIdSchema,
+  method: z.string(),
+  payload: z.unknown(),
+}) as z.ZodType<ClientRequest>
+
+/** Server response envelope; endpoint value validation belongs to its caller. */
+export const serverResponseSchema = z.object({
+  type: z.literal('server-response'),
+  rpcId: rpcIdSchema,
+  result: rpcResultSchema(z.unknown().optional()),
+}) as z.ZodType<ServerResponse>
+
+/** Either Connection RPC envelope direction. */
+export const rpcMessageSchema = z.discriminatedUnion('type', [
+  clientRequestSchema as unknown as z.ZodObject<z.ZodRawShape>,
+  serverResponseSchema as unknown as z.ZodObject<z.ZodRawShape>,
+]) as unknown as z.ZodType<RpcMessage>

packages/client/connection/src/rpc.ts

@@ -0,0 +1,251 @@
+/** Generic unary RPC contracts shared by the Host and Client Connection halves. */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Correlation id minted by a caller and echoed by the Connection response. */
+export type RpcId = Branded<'rpc-id'>
+
+/**
+ * Brand one validated string as a Connection correlation id.
+ * @param id - validated wire identity.
+ * @returns the same string with the correlation-id brand.
+ */
+export function RpcId(id: string): RpcId {
+  return id as RpcId
+}
+
+/** Carrier-neutral failure returned by one logical RPC endpoint. */
+export interface ConnectionRpcFailure {
+  readonly code: string
+  readonly message: string
+  readonly details: object
+}
+
+/** Carrier-neutral result returned by one logical RPC endpoint. */
+export type ConnectionRpcResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: ConnectionRpcFailure }
+
+/** Historical short name for a generic Connection result. */
+export type RpcResult<T> = ConnectionRpcResult<T>
+
+/**
+ * Convert a rejected transport operation into a generic failure result.
+ * @param error - rejected transport value.
+ * @returns an `internal` failure preserving the available message.
+ */
+export function transportError<T>(error: unknown): RpcResult<T> {
+  return {
+    ok: false,
+    error: {
+      code: 'gateway/internal',
+      message: error instanceof Error ? error.message : String(error),
+      details: {},
+    },
+  }
+}
+
+/** Narrow request form used by direct fixture adapters. */
+export interface RpcRequest<P> {
+  readonly rpcId: RpcId
+  readonly payload: P
+}
+
+/** Narrow response form used by direct fixture adapters. */
+export interface RpcResponse<T> {
+  readonly rpcId: RpcId
+  readonly result: RpcResult<T>
+}
+
+/** Full request envelope carried by Connection RPC transports. */
+export interface ClientRequest {
+  readonly type: 'client-request'
+  readonly rpcId: RpcId
+  readonly method: string
+  readonly payload: unknown
+}
+
+/** Full response envelope carried by Connection RPC transports. */
+export interface ServerResponse {
+  readonly type: 'server-response'
+  readonly rpcId: RpcId
+  readonly result: ConnectionRpcResult<unknown>
+}
+
+/** Complete Connection RPC envelope union. */
+export type RpcMessage = ClientRequest | ServerResponse
+
+/** HTTP request facts consumed by browser trust and authentication. */
+export interface ConnectionTrustRequest {
+  /** Request headers supplied by either the Fetch or node:http representation. */
+  readonly headers: Headers | Readonly<Record<string, string | readonly string[] | undefined>>
+}
+
+/** HTTP status returned before dispatch, or undefined when the request may proceed. */
+export type ConnectionRequestRejection = 401 | 403 | undefined
+
+/** Root/index request facts used by the browser-token exchange. */
+export interface ConnectionIndexRequest extends ConnectionTrustRequest {
+  readonly method?: string | undefined
+  readonly url?: string | undefined
+}
+
+/** Root/index response operations owned by the browser-token exchange. */
+export interface ConnectionIndexResponse {
+  writeHead(status: number, headers?: Readonly<Record<string, string>>): unknown
+  end(body?: string): unknown
+}
+
+/** Handler invoked after Connection has decoded the transport envelope. */
+export type ConnectionRpcHandler = (
+  endpoint: string,
+  payload: unknown,
+  signal: AbortSignal,
+) => Promise<ConnectionRpcResult<unknown>>
+
+/** Synchronous ownership test for one endpoint on a shared RPC channel. */
+export type ConnectionRpcEndpointMatcher = (endpoint: string) => boolean
+
+/** HTTP methods supported by exact Fetch routes on the shared API channel. */
+export type ConnectionFetchMethod = 'GET' | 'HEAD' | 'POST'
+
+/** How the node:http bridge presents one request body to its Fetch route. */
+export type ConnectionRequestBodyMode = 'buffered' | 'streaming'
+
+/** One exact, transport-independent Fetch route owned by a Host feature. */
+export interface ConnectionFetchRoute {
+  /** Absolute path below `/api`; query parameters remain available on the request URL. */
+  readonly path: string
+  /** Methods this route owns. Other methods continue through normal shared-channel dispatch. */
+  readonly methods: readonly ConnectionFetchMethod[]
+  /** Buffered requests obey the configured JSON cap; streaming requests arrive with backpressure and no aggregate cap. */
+  readonly requestBody: ConnectionRequestBodyMode
+  /** Handle one request after the physical carrier has applied its trust and authentication policy. */
+  readonly fetch: (request: Request) => Promise<Response>
+}
+
+/** Host registry for exact Fetch routes that cannot use JSON Remote invocation. */
+export interface HostConnectionFetch {
+  /**
+   * Register one exact route on the shared API channel.
+   * @param route - path, methods, and Fetch-shaped implementation.
+   * @returns asynchronous disposer removing this exact contribution.
+   */
+  register(route: ConnectionFetchRoute): () => Promise<void>
+}
+
+/** Host registry for logical RPC channels carried by the current transport. */
+export interface HostConnectionRpc {
+  /**
+   * Register one authenticated absolute channel prefix.
+   * @param channel - absolute logical channel such as `/rpc`.
+   * @param handler - decoded endpoint handler returning the existing RPC result shape.
+   * @returns asynchronous disposer removing the channel and its physical route.
+   */
+  handle(
+    channel: string,
+    handler: ConnectionRpcHandler,
+  ): () => Promise<void>
+
+  /**
+   * Intercept owned endpoints on the shared `/api` channel before its fallback.
+   * @param channel - reserved shared channel; currently `/api`.
+   * @param matches - synchronous endpoint ownership test.
+   * @param handler - decoded endpoint handler returning the existing RPC result shape.
+   * @returns asynchronous disposer removing the interceptor.
+   */
+  intercept(
+    channel: '/api',
+    matches: ConnectionRpcEndpointMatcher,
+    handler: ConnectionRpcHandler,
+  ): () => Promise<void>
+}
+
+/** Host `ctx.connection` shape consumed by transport-independent adapters. */
+export interface HostConnectionHandle {
+  /** Generic RPC channel registry. */
+  readonly rpc: HostConnectionRpc
+  /** Exact Fetch routes for streaming or browser-native responses. */
+  readonly fetch: HostConnectionFetch
+
+  /**
+   * Compose exact Fetch routes and the shared-channel RPC interceptor.
+   * @param channel - shared channel mounted by Connection.
+   * @returns Fetch handler for trusted, authenticated requests.
+   */
+  createSharedFetchHandler(channel: '/api'): ConnectionFetchHandler
+
+  /**
+   * Apply Connection's Host/Origin checks and browser authentication to
+   * another Web route.
+   * @param request - request headers from the HTTP or upgrade request.
+   * @returns rejection status, or undefined when the route may accept the request.
+   */
+  requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection
+
+  /**
+   * Authenticate one frontend index request, owning a token redirect or 401.
+   * @param request - root or configured-index HTTP request.
+   * @param response - response owned when the result is false.
+   * @returns true only when the frontend may serve index.html.
+   */
+  authorizeIndex(request: ConnectionIndexRequest, response: ConnectionIndexResponse): boolean
+
+  /**
+   * Add the fresh process token to an ordinary Web application URL.
+   * @param baseUrl - clean canonical browser origin.
+   * @returns root URL accepted by {@link authorizeIndex} for initial login.
+   */
+  authenticatedUrl(baseUrl: string): string
+}
+
+/** Transport-independent Fetch handler used by HTTP and worker carriers. */
+export interface ConnectionFetchHandler {
+  /**
+   * Resolve body handling before the bridge reads any request bytes.
+   * @param request - request method and URL available from node:http headers.
+   * @returns the registered route's body handling mode.
+   */
+  requestBodyMode(request: { readonly method: string; readonly url: URL }): ConnectionRequestBodyMode
+
+  /**
+   * Dispatch one already-authenticated request.
+   * @param request - Fetch request below the shared channel.
+   * @returns the registered response or a 404 response.
+   */
+  fetch(request: Request): Promise<Response>
+}
+
+/** Client caller for logical RPC channels carried by the current transport. */
+export interface ClientConnectionRpc {
+  /**
+   * Call one endpoint through an already registered logical channel.
+   * @param channel - absolute logical channel such as `/api`.
+   * @param endpoint - channel-relative endpoint such as `goals/create`.
+   * @param payload - channel-owned request payload.
+   * @param signal - optional caller cancellation.
+   * @returns the endpoint-owned success/error result; correlation stays inside Connection.
+   */
+  call(
+    channel: string,
+    endpoint: string,
+    payload: unknown,
+    signal?: AbortSignal,
+  ): Promise<ConnectionRpcResult<unknown>>
+
+  /**
+   * Open an in-process logical stream when the selected carrier supplies one.
+   * Browser transports omit this method; API Gateway owns their WebSocket mux.
+   * @param channel - absolute logical channel such as `/api`.
+   * @param endpoint - channel-relative endpoint such as `session/follow`.
+   * @param payload - channel-owned request payload.
+   * @param signal - caller cancellation for this logical stream.
+   * @returns decoded stream values from the in-process carrier.
+   */
+  readonly open?: (
+    channel: string,
+    endpoint: string,
+    payload: unknown,
+    signal: AbortSignal,
+  ) => AsyncIterable<unknown>
+}

packages/client/connection/tests/api-helpers.client.spec.ts

@@ -0,0 +1,21 @@
+/**
+ * Contract-layer helpers: transport-error folding and response unwrapping.
+ * (The assistant block classifier half of the legacy spec lives in
+ * runtime/tests — the classifier moved there.)
+ */
+
+import { describe, expect, it } from 'vitest'
+import { RpcId, resultOf, transportError } from '../src/client/api.ts'
+
+describe('transportError', () => {
+  it('folds an Error to internal keeping the message, and stringifies non-Errors', () => {
+    expect(transportError(new Error('线断了'))).toEqual({ ok: false, error: { code: 'gateway/internal', message: '线断了', details: {} } })
+    expect(transportError('raw string')).toMatchObject({ ok: false, error: { message: 'raw string' } })
+  })
+})
+
+describe('resultOf', () => {
+  it('unwraps the result slot', () => {
+    expect(resultOf({ rpcId: RpcId('r'), result: { ok: true, value: 7 } })).toEqual({ ok: true, value: 7 })
+  })
+})

packages/client/connection/tests/api-request-trust.host.spec.ts

@@ -0,0 +1,115 @@
+/** Behavior of the /api browser-trust fence (rebinding + cross-site defense). */
+
+import { describe, expect, it } from 'vitest'
+import { assertTrustedAuthority, isTrustedApiRequest } from '../src/api-request-trust.ts'
+
+function request(headers: Record<string, string | undefined>): { headers: Record<string, string | undefined> } {
+  return { headers }
+}
+
+describe('isTrustedApiRequest', () => {
+  it('holds markerless requests to the same Host fence — a plain-HTTP browser read carries no markers', () => {
+    // Over plain HTTP a browser attaches neither Origin nor Fetch-Metadata to
+    // reads (EventSource, images, navigations), so a rebound-origin GET is
+    // markerless and its response readable: no marker shortcut may exist.
+    expect(isTrustedApiRequest(request({ host: '127.0.0.1:3080' }), [])).toBe(true)
+    expect(isTrustedApiRequest(request({ host: '192.168.1.5:3080' }), ['192.168.1.5'])).toBe(true)
+    expect(isTrustedApiRequest(request({ host: '192.168.1.5:3080' }), [])).toBe(false)
+    expect(isTrustedApiRequest(request({ host: 'harness.example' }), [])).toBe(false)
+    expect(isTrustedApiRequest(request({}), [])).toBe(false)
+  })
+
+  it('accepts loopback Hosts in every spelling, with and without ports, for browser requests', () => {
+    for (const host of ['localhost', 'localhost:3080', '127.0.0.1', '127.0.0.1:3080', '127.8.9.10:80', '[::1]', '[::1]:3080', 'LOCALHOST:3080']) {
+      expect(isTrustedApiRequest(request({ host, origin: `http://${host}` }), [])).toBe(true)
+    }
+  })
+
+  it('refuses a rebound Host: the attacker domain names the socket it did not expect', () => {
+    expect(isTrustedApiRequest(request({
+      host: 'evil.example:3080',
+      origin: 'http://evil.example:3080',
+      'sec-fetch-site': 'same-origin',
+    }), [])).toBe(false)
+  })
+
+  it('accepts a declared public authority: exact on host:port entries, any port on port-less entries', () => {
+    const headers = { host: 'harness.internal:3080', origin: 'http://harness.internal:3080' }
+    expect(isTrustedApiRequest(request(headers), ['harness.internal:3080'])).toBe(true)
+    expect(isTrustedApiRequest(request(headers), ['harness.internal'])).toBe(true)
+    expect(isTrustedApiRequest(request(headers), ['harness.internal:9999'])).toBe(false)
+    expect(isTrustedApiRequest(request(headers), [])).toBe(false)
+  })
+
+  it('matches Host, Origin, and trusted entries through WHATWG normalization (case, default port)', () => {
+    expect(isTrustedApiRequest(request({ host: 'Harness.INTERNAL:3080', origin: 'http://harness.internal:3080' }), ['harness.internal:3080'])).toBe(true)
+    expect(isTrustedApiRequest(request({ host: 'harness.internal', origin: 'http://harness.internal' }), ['HARNESS.internal:80'])).toBe(true)
+    // An unparsable entry never matches; it must not poison the rest of the list.
+    expect(isTrustedApiRequest(request({ host: 'harness.internal', origin: 'http://harness.internal' }), ['bad entry', 'harness.internal'])).toBe(true)
+    expect(isTrustedApiRequest(request({ host: 'harness.internal', origin: 'http://harness.internal' }), ['bad entry'])).toBe(false)
+  })
+
+  it('refuses cross-origin browser markers even on a loopback Host', () => {
+    // Origin present and different → cross-site request that survived preflight rules.
+    expect(isTrustedApiRequest(request({ host: '127.0.0.1:3080', origin: 'http://evil.example' }), [])).toBe(false)
+    // Explicit cross-site label → refused regardless of Origin.
+    expect(isTrustedApiRequest(request({ host: '127.0.0.1:3080', 'sec-fetch-site': 'cross-site' }), [])).toBe(false)
+    // Opaque origin (sandboxed iframe, file: page) parses to no authority.
+    expect(isTrustedApiRequest(request({ host: '127.0.0.1:3080', origin: 'null' }), [])).toBe(false)
+  })
+
+  it('accepts a same-origin browser request, with or without an Origin header', () => {
+    expect(isTrustedApiRequest(request({
+      host: 'localhost:3080',
+      origin: 'http://localhost:3080',
+      'sec-fetch-site': 'same-origin',
+    }), [])).toBe(true)
+    // Origin-less browser shapes (same-origin GETs) still carry sec-fetch-site.
+    expect(isTrustedApiRequest(request({ host: 'localhost:3080', 'sec-fetch-site': 'same-origin' }), [])).toBe(true)
+  })
+
+  it('reads Fetch Headers while preserving absent browser markers', () => {
+    expect(isTrustedApiRequest({ headers: new Headers({ host: '127.0.0.1:3080' }) }, [])).toBe(true)
+    expect(isTrustedApiRequest({
+      headers: new Headers({ host: '127.0.0.1:3080', origin: 'http://evil.example' }),
+    }, [])).toBe(false)
+  })
+
+  it('assertTrustedAuthority accepts bare authorities and throws on anything more', () => {
+    for (const entry of ['harness.internal', 'harness.internal:3080', 'HARNESS.internal:80', '10.0.0.9', '[::1]:3080']) {
+      expect(() => { assertTrustedAuthority(entry) }).not.toThrow()
+    }
+    // WHATWG parsing would quietly read a hostname out of each of these; the
+    // config boundary must refuse them instead of authorizing the prefix.
+    for (const entry of ['harness.internal/path', 'harness.internal/', 'user@harness.internal', 'harness.internal?x', 'harness.internal#f', 'harness.internal\\path', 'bad entry', '']) {
+      expect(() => { assertTrustedAuthority(entry) }).toThrow(/not a bare host\[:port\] authority/)
+    }
+    // WHATWG trimming would silently strip these; the entry must fail instead.
+    for (const entry of ['harness.internal:3080 ', ' harness.internal', 'harness.internal:30\t80']) {
+      expect(() => { assertTrustedAuthority(entry) }).toThrow(/not a bare host\[:port\] authority/)
+    }
+    // WHATWG parsing would silently rewrite these — a dangling colon or
+    // zero-padded port would broaden an intended exact-port grant to every
+    // port, and non-canonical host spellings would not read back as written.
+    for (const entry of ['harness.internal:', '[::1]:', 'harness.internal:0080', '0x7f.0.0.1', '[0:0:0:0:0:0:0:1]']) {
+      expect(() => { assertTrustedAuthority(entry) }).toThrow(/not a bare host\[:port\] authority/)
+    }
+  })
+
+  it('never lets stray whitespace broaden an exact-port entry to every port', () => {
+    // Defense in depth below the load-time assert: the explicit-port judgment
+    // reads the parsed URL, so a trimmed `host:port ` entry stays exact.
+    const trusted = ['harness.internal:3080 ']
+    expect(isTrustedApiRequest(request({ host: 'harness.internal:9999', origin: 'http://harness.internal:9999' }), trusted)).toBe(false)
+    expect(isTrustedApiRequest(request({ host: 'harness.internal:3080', origin: 'http://harness.internal:3080' }), trusted)).toBe(true)
+  })
+
+  it('refuses malformed or untrusted authorities on browser requests', () => {
+    const markers = { 'sec-fetch-site': 'same-origin' }
+    expect(isTrustedApiRequest(request({ ...markers }), [])).toBe(false)
+    expect(isTrustedApiRequest(request({ ...markers, host: '' }), [])).toBe(false)
+    expect(isTrustedApiRequest(request({ ...markers, host: 'bad host' }), [])).toBe(false)
+    expect(isTrustedApiRequest(request({ ...markers, host: '127.0.0.999' }), [])).toBe(false)
+    expect(isTrustedApiRequest(request({ ...markers, host: '128.0.0.1' }), [])).toBe(false)
+  })
+})

packages/client/connection/tests/browser-auth.host.spec.ts

@@ -0,0 +1,250 @@
+/** Browser launch-token and persistent-cookie behavior. */
+
+import { createHmac } from 'node:crypto'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { CredentialProvider } from '@deepseek-ai/dsh-credentials'
+import { BrowserAuth } from '../src/browser-auth.ts'
+import type { ConnectionIndexRequest, ConnectionIndexResponse } from '../src/rpc.ts'
+import { RecordCredentials } from './browser-credentials.ts'
+
+function signedCookie(store: RecordCredentials, name: string, payload: unknown): string {
+  const body = typeof payload === 'string'
+    ? Buffer.from(payload, 'utf8').toString('base64url')
+    : Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url')
+  return signedBodyCookie(store, name, body)
+}
+
+function signedBodyCookie(store: RecordCredentials, name: string, body: string): string {
+  const record = store.record
+  if (record?.kind !== 'grant' || typeof record.payload !== 'object' || record.payload === null) {
+    throw new Error('test credential store has no signing secret')
+  }
+  const secret: unknown = Reflect.get(record.payload, 'secret')
+  if (typeof secret !== 'string') throw new Error('test credential record has no string secret')
+  const signature = createHmac('sha256', Buffer.from(secret, 'base64url')).update(body).digest('base64url')
+  return `${name}=v1.${body}.${signature}`
+}
+
+interface ResponseState {
+  status?: number
+  headers?: Readonly<Record<string, string>>
+  body?: string
+}
+
+function response(): { value: ConnectionIndexResponse; state: ResponseState } {
+  const state: ResponseState = {}
+  return {
+    value: {
+      writeHead(status, headers) {
+        state.status = status
+        if (headers !== undefined) state.headers = headers
+      },
+      end(body) {
+        if (body !== undefined) state.body = body
+      },
+    },
+    state,
+  }
+}
+
+function credentials(store: RecordCredentials): CredentialProvider {
+  return store as unknown as CredentialProvider
+}
+
+function createAuth(
+  store: RecordCredentials,
+  maxAgeDays = 30,
+  processOwner: object = {},
+): Promise<BrowserAuth> {
+  return BrowserAuth.create(processOwner, credentials(store), maxAgeDays)
+}
+
+function request(url: string, authority = '127.0.0.1:3080', init?: {
+  cookie?: string
+  method?: string
+}): ConnectionIndexRequest {
+  return {
+    method: init?.method ?? 'GET',
+    url,
+    headers: {
+      host: authority,
+      ...init?.cookie === undefined ? {} : { cookie: init.cookie },
+    },
+  }
+}
+
+function exchange(
+  auth: BrowserAuth,
+  authority = '127.0.0.1:3080',
+): { cookie: string; launchUrl: string; state: ResponseState } {
+  const launchUrl = auth.authenticatedUrl(`http://${authority}`)
+  const target = new URL(launchUrl)
+  const res = response()
+  expect(auth.authorizeIndex(request(`${target.pathname}${target.search}`, authority), res.value)).toBe(false)
+  const setCookie = res.state.headers?.['set-cookie']
+  if (setCookie === undefined) throw new Error('token exchange did not set a cookie')
+  return { cookie: setCookie.split(';', 1)[0]!, launchUrl, state: res.state }
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('BrowserAuth', () => {
+  it('mints one process token and a persistent authority-bound cookie', async () => {
+    const store = new RecordCredentials()
+    const processOwner = {}
+    const first = await createAuth(store, 30, processOwner)
+    const login = exchange(first)
+
+    expect(login.state).toMatchObject({
+      status: 303,
+      headers: {
+        'cache-control': 'no-store',
+        'location': '/',
+        'referrer-policy': 'no-referrer',
+      },
+    })
+    expect(login.state.headers?.['set-cookie']).toMatch(/; Max-Age=2592000; Path=\/; Expires=.*; HttpOnly; SameSite=Strict$/u)
+    expect(login.state.headers?.['set-cookie']).not.toContain('Secure')
+    expect(first.isAuthenticated(request('/', '127.0.0.1:3080', { cookie: login.cookie }))).toBe(true)
+    expect(first.isAuthenticated({
+      headers: new Headers({ host: '127.0.0.1:3080', cookie: login.cookie }),
+    })).toBe(true)
+    expect(first.isAuthenticated({ headers: new Headers() })).toBe(false)
+    expect(first.isAuthenticated(request('/', 'localhost:3080', { cookie: login.cookie }))).toBe(false)
+    expect(first.isAuthenticated(request('/', '127.0.0.1:3081', { cookie: login.cookie }))).toBe(false)
+
+    const reloaded = await createAuth(store, 30, processOwner)
+    expect(reloaded.authenticatedUrl('http://127.0.0.1:3080')).toBe(login.launchUrl)
+    expect(reloaded.isAuthenticated(request('/', '127.0.0.1:3080', { cookie: login.cookie }))).toBe(true)
+
+    const restarted = await createAuth(store)
+    expect(new URL(restarted.authenticatedUrl('http://127.0.0.1:3080')).searchParams.get('token'))
+      .not.toBe(new URL(login.launchUrl).searchParams.get('token'))
+    expect(restarted.isAuthenticated(request('/', '127.0.0.1:3080', { cookie: login.cookie }))).toBe(true)
+    const staleUrl = new URL(login.launchUrl)
+    const redirected = response()
+    expect(restarted.authorizeIndex(request(
+      `${staleUrl.pathname}${staleUrl.search}`,
+      '127.0.0.1:3080',
+      { cookie: login.cookie },
+    ), redirected.value)).toBe(false)
+    expect(redirected.state).toEqual({
+      status: 303,
+      headers: {
+        'cache-control': 'no-store',
+        'location': '/',
+        'referrer-policy': 'no-referrer',
+      },
+    })
+  })
+
+  it('accepts the cookie for index serving and gives every unauthenticated request one response', async () => {
+    const auth = await createAuth(new RecordCredentials())
+    const { cookie } = exchange(auth)
+    const allowed = response()
+    expect(auth.authorizeIndex(request('/index.html', '127.0.0.1:3080', { cookie }), allowed.value)).toBe(true)
+    expect(allowed.state).toEqual({})
+
+    for (const candidate of [
+      request('/'),
+      request('/?token=wrong'),
+      request('/?token=wrong&token=again'),
+      request('/index.html?token=wrong'),
+      request(auth.authenticatedUrl('http://127.0.0.1:3080'), '127.0.0.1:3080', { method: 'HEAD' }),
+    ]) {
+      const denied = response()
+      expect(auth.authorizeIndex(candidate, denied.value)).toBe(false)
+      expect(denied.state.status).toBe(401)
+      expect(denied.state.headers).toEqual({
+        'cache-control': 'no-store',
+        'content-type': 'text/plain; charset=utf-8',
+      })
+      expect(denied.state.body).toBe(candidate.method === 'HEAD'
+        ? undefined
+        : 'dsh web authentication required; reopen the URL printed by dsh web.\n')
+    }
+  })
+
+  it('rejects tampering, expiry, future issuance, and a longer lifetime than configured', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-08-24T00:00:00.000Z'))
+    const store = new RecordCredentials()
+    const auth = await createAuth(store)
+    const { cookie } = exchange(auth)
+    const [name, value] = cookie.split('=') as [string, string]
+
+    expect(auth.isAuthenticated(request('/', '127.0.0.1:3080', { cookie: `${name}=broken` }))).toBe(false)
+    expect(auth.isAuthenticated(request('/', '127.0.0.1:3080', { cookie: `${name}=${value.slice(0, -1)}x` }))).toBe(false)
+    expect(auth.isAuthenticated(request('/', '127.0.0.1:3080', { cookie: `${name}=%` }))).toBe(false)
+    expect(auth.isAuthenticated(request('/', '127.0.0.1:3080', {
+      cookie: signedBodyCookie(store, name, 'a'),
+    }))).toBe(false)
+    expect(auth.isAuthenticated({ headers: {} })).toBe(false)
+    expect(auth.isAuthenticated({ headers: { host: 'bad host', cookie } })).toBe(false)
+    expect(auth.isAuthenticated({ headers: { host: '127.0.0.1:3080' } })).toBe(false)
+
+    const invalidPayloads: unknown[] = [
+      'not json',
+      null,
+      { version: 2, authority: '127.0.0.1:3080', issuedAt: Date.now(), expiresAt: Date.now() + 1000 },
+      { version: 1, authority: 42, issuedAt: Date.now(), expiresAt: Date.now() + 1000 },
+      { version: 1, authority: '127.0.0.1:3080', issuedAt: 'now', expiresAt: Date.now() + 1000 },
+      { version: 1, authority: '127.0.0.1:3080', issuedAt: Date.now(), expiresAt: 'later' },
+    ]
+    for (const payload of invalidPayloads) {
+      expect(auth.isAuthenticated(request('/', '127.0.0.1:3080', {
+        cookie: signedCookie(store, name, payload),
+      }))).toBe(false)
+    }
+
+    const shorter = await createAuth(store, 1)
+    expect(shorter.isAuthenticated(request('/', '127.0.0.1:3080', { cookie }))).toBe(false)
+    vi.setSystemTime(new Date('2026-09-24T00:00:00.000Z'))
+    expect(auth.isAuthenticated(request('/', '127.0.0.1:3080', { cookie }))).toBe(false)
+    vi.setSystemTime(new Date('2026-08-23T00:00:00.000Z'))
+    expect(auth.isAuthenticated(request('/', '127.0.0.1:3080', { cookie }))).toBe(false)
+  })
+
+  it('loads one secret per activation and replaces it after deletion on the next activation', async () => {
+    const store = new RecordCredentials()
+    const auth = await createAuth(store)
+    const first = exchange(auth)
+    expect(store).toMatchObject({ reads: 0, modifies: 1 })
+
+    await store.deleteRecord()
+    expect(auth.isAuthenticated(request('/', '127.0.0.1:3080', { cookie: first.cookie }))).toBe(true)
+    const sameActivation = exchange(auth)
+    expect(auth.isAuthenticated(request('/', '127.0.0.1:3080', { cookie: sameActivation.cookie }))).toBe(true)
+    expect(store).toMatchObject({ reads: 0, modifies: 1 })
+
+    const reactivated = await createAuth(store)
+    const second = exchange(reactivated)
+    expect(second.cookie).not.toBe(first.cookie)
+    expect(reactivated.isAuthenticated(request('/', '127.0.0.1:3080', { cookie: first.cookie }))).toBe(false)
+    expect(reactivated.isAuthenticated(request('/', '127.0.0.1:3080', { cookie: second.cookie }))).toBe(true)
+    expect(store).toMatchObject({ reads: 0, modifies: 2 })
+  })
+
+  it('fails loud on an invalid owner record instead of replacing it', async () => {
+    const unsupported = new RecordCredentials()
+    unsupported.record = { kind: 'api-key', key: 'not-a-cookie-secret' }
+    await expect(createAuth(unsupported)).rejects.toThrow(/unsupported format/u)
+
+    const malformed = new RecordCredentials()
+    malformed.record = { kind: 'grant', payload: { version: 1, secret: 'short' } }
+    await expect(createAuth(malformed)).rejects.toThrow(/invalid secret/u)
+
+    const nonString = new RecordCredentials()
+    nonString.record = { kind: 'grant', payload: { version: 1, secret: 42 } }
+    await expect(createAuth(nonString)).rejects.toThrow(/invalid secret/u)
+
+    const discarded = new RecordCredentials()
+    discarded.discardWrites = true
+    await expect(createAuth(discarded)).rejects.toThrow(/was not created/u)
+
+    await expect(createAuth(new RecordCredentials(), Number.MAX_SAFE_INTEGER))
+      .rejects.toThrow(/safe timestamp range/u)
+  })
+})

packages/client/connection/tests/browser-credentials.ts

@@ -0,0 +1,36 @@
+import type { Context } from '@deepseek-ai/cordis'
+import type { CredentialProvider, CredentialRecord } from '@deepseek-ai/dsh-credentials'
+
+/** Mutable credential-record double for Connection authentication tests. */
+export class RecordCredentials {
+  record: CredentialRecord | undefined
+  discardWrites = false
+  reads = 0
+  modifies = 0
+
+  readRecord(): Promise<CredentialRecord | undefined> {
+    this.reads += 1
+    return Promise.resolve(this.record)
+  }
+
+  async modifyRecord(
+    _key: unknown,
+    mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>,
+  ): Promise<CredentialRecord | undefined> {
+    this.modifies += 1
+    const next = await mutate(this.record)
+    if (this.discardWrites) return undefined
+    if (next !== undefined) this.record = next
+    return this.record
+  }
+
+  deleteRecord(): Promise<void> {
+    this.record = undefined
+    return Promise.resolve()
+  }
+}
+
+/** Provide the record operations Connection needs during authentication setup. */
+export function provideBrowserCredentials(ctx: Context): void {
+  ctx.provide('credentials', new RecordCredentials() as unknown as CredentialProvider)
+}

packages/client/connection/tests/client-apply.client.spec.ts

@@ -0,0 +1,620 @@
+/**
+ * Connection plugin browser-half apply: ctx.connection handle mounting,
+ * explicit carrier selection, and single-consumer connection-loop ownership.
+ */
+import { Context } from '@deepseek-ai/cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  apply,
+  type ClientConnectionRpc,
+  type ClientTransportHooks,
+  type ConnectionGenerationSource,
+  type RpcFetch,
+  type ConnectionHandle,
+  type ConnectionState,
+} from '../src/client/index.ts'
+
+type Win = {
+  location?: { hostname: string; origin?: string }
+  __DSH_TRANSPORT__?: ClientTransportHooks
+}
+
+afterEach(() => {
+  delete (globalThis as Win).location
+  delete (globalThis as Win).__DSH_TRANSPORT__
+  vi.unstubAllGlobals()
+  vi.useRealTimers()
+})
+
+class BrowserNetworkProbe extends EventTarget {
+  readonly navigator = { onLine: true }
+
+  setOnline(online: boolean): void {
+    this.navigator.onLine = online
+    this.dispatchEvent(new Event(online ? 'online' : 'offline'))
+  }
+}
+
+class GenerationProbe {
+  private readonly active = new Set<() => void>()
+
+  readonly source: ConnectionGenerationSource = (signal, ready) => new Promise<void>((resolve) => {
+    let settled = false
+    const finish = (): void => {
+      if (settled) return
+      settled = true
+      signal.removeEventListener('abort', finish)
+      this.active.delete(finish)
+      resolve()
+    }
+    this.active.add(finish)
+    signal.addEventListener('abort', finish, { once: true })
+    ready({ home: '/h' })
+    if (signal.aborted) finish()
+  })
+
+  end(): void {
+    for (const finish of [...this.active]) finish()
+  }
+}
+
+function installGeneration(handle: ConnectionHandle): GenerationProbe {
+  const probe = new GenerationProbe()
+  handle.registerGenerationSource(probe.source)
+  return probe
+}
+
+async function mount(): Promise<ConnectionHandle> {
+  const ctx = new Context()
+  await ctx.plugin({ apply, inject: [] })
+  const handle = ctx.get('connection') as ConnectionHandle | undefined
+  if (handle === undefined) throw new Error('ctx.connection not provided')
+  return handle
+}
+
+describe('connection client apply', () => {
+  it('uses Host bootstrap timing when Gateway starts without overrides', async () => {
+    vi.useFakeTimers()
+    vi.stubGlobal('__DSH_CONNECTION_RECOVERY__', {
+      backoffBaseMs: 10, backoffMaxMs: 10, generationReadyTimeoutMs: 20,
+    })
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const handle = await mount()
+    const signals: AbortSignal[] = []
+    handle.registerGenerationSource(signal => new Promise<void>((resolve) => {
+      signals.push(signal)
+      signal.addEventListener('abort', () => { resolve() }, { once: true })
+    }))
+    const loop = handle.start({})
+    try {
+      await vi.advanceTimersByTimeAsync(20)
+      expect(signals[0]?.aborted).toBe(true)
+      expect(handle.state.getSnapshot()).toBe('connecting')
+      await vi.advanceTimersByTimeAsync(10)
+      expect(signals).toHaveLength(2)
+    } finally {
+      loop.stop()
+      await vi.advanceTimersByTimeAsync(0)
+      warnSpy.mockRestore()
+    }
+  })
+
+  it.each([{ generationReadyTimeoutMs: 0 }, { backoffFactor: NaN }])('rejects malformed bootstrap recovery before publishing the service: %j', (recovery) => {
+    vi.stubGlobal('__DSH_CONNECTION_RECOVERY__', recovery)
+    const ctx = new Context()
+    expect(() => { apply(ctx) }).toThrow()
+    expect(ctx.get('connection')).toBeUndefined()
+  })
+
+  it('rejects a NaN start override without acquiring the generation source', async () => {
+    const handle = await mount()
+    const source = vi.fn<ConnectionGenerationSource>()
+    const unregister = handle.registerGenerationSource(source)
+    try {
+      expect(() => handle.start({}, { backoffFactor: NaN })).toThrow(/backoffFactor.*finite/)
+      expect(source).not.toHaveBeenCalled()
+    } finally {
+      unregister()
+    }
+  })
+
+  it('treats a runtime without browser location as local', async () => {
+    delete (globalThis as Win).location
+    expect((await mount()).isLoopback).toBe(true)
+  })
+
+  it('mounts ctx.connection and identifies a loopback page', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    expect(handle.isLoopback).toBe(true)
+  })
+
+  it('reports non-loopback page authority through the connection handle', async () => {
+    ;(globalThis as Win).location = { hostname: '192.0.2.20' }
+    expect((await mount()).isLoopback).toBe(false)
+  })
+
+  it('requires one generation source and ignores a stale source disposer', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    const first = new GenerationProbe()
+    const second = new GenerationProbe()
+
+    expect(() => handle.start({})).toThrow('no generation source is registered')
+    const unregisterFirst = handle.registerGenerationSource(first.source)
+    expect(() => { handle.registerGenerationSource(second.source) })
+      .toThrow('a generation source is already registered')
+    unregisterFirst()
+    const unregisterSecond = handle.registerGenerationSource(second.source)
+    unregisterFirst()
+
+    const loop = handle.start({})
+    await vi.waitFor(() => {
+      expect(handle.generation.getSnapshot()?.host.home).toBe('/h')
+    })
+    unregisterSecond()
+    expect(handle.generation.getSnapshot()).toBeUndefined()
+    loop.stop()
+  })
+
+  it('start() hands out one loop, rejects a second consumer, and stop() aborts the generation', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    installGeneration(handle)
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    const generations: Array<string | undefined> = []
+    const stopThrowing = handle.generation.subscribe(() => { throw new Error('subscriber bug') })
+    const stopGeneration = handle.generation.subscribe(() => {
+      generations.push(handle.generation.getSnapshot()?.host.home)
+    })
+    expect(handle.generation.getSnapshot()).toBeUndefined()
+    let connected = 0
+    const loop = handle.start({ onConnected: () => { connected++ } })
+    expect(() => handle.start({})).toThrow(/already owned by another consumer/)
+    await vi.waitFor(() => {
+      expect(handle.generation.getSnapshot()?.host.home).toBe('/h')
+    })
+    loop.stop() // teardown must not throw; the fixture streams abort quietly
+    expect(handle.generation.getSnapshot()).toBeUndefined()
+    expect(generations).toEqual(['/h', undefined])
+    expect(connected).toBe(1)
+    expect(errorSpy).toHaveBeenCalledTimes(2)
+    stopThrowing()
+    stopGeneration()
+    errorSpy.mockRestore()
+  })
+
+  it('does not notify state subscribers when a pre-ready loop stops', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    handle.registerGenerationSource(signal => new Promise<void>((resolve) => {
+      signal.addEventListener('abort', () => { resolve() }, { once: true })
+    }))
+    const listener = vi.fn()
+    const unsubscribe = handle.state.subscribe(listener)
+    const loop = handle.start({})
+
+    loop.stop()
+
+    expect(handle.state.getSnapshot()).toBeUndefined()
+    expect(listener).not.toHaveBeenCalled()
+    unsubscribe()
+  })
+
+  it('allows a replacement owner and ignores the previous owner handle', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    const generation = installGeneration(handle)
+
+    const first = handle.start({})
+    await vi.waitFor(() => {
+      expect(handle.generation.getSnapshot()?.host.home).toBe('/h')
+    })
+    first.stop()
+    expect(handle.generation.getSnapshot()).toBeUndefined()
+
+    const second = handle.start({})
+    await vi.waitFor(() => {
+      expect(handle.generation.getSnapshot()?.host.home).toBe('/h')
+    })
+    first.stop()
+    expect(handle.generation.getSnapshot()?.host.home).toBe('/h')
+
+    second.stop()
+    generation.end()
+  })
+
+  it('lets the connection service force only its current owner to reconnect', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    installGeneration(handle)
+    const requested = vi.fn()
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const loop = handle.start({ onReconnectRequested: requested }, {
+      backoffBaseMs: 60_000,
+      backoffFactor: 2,
+      backoffMaxMs: 120_000,
+      generationReadyTimeoutMs: 500,
+    })
+    try {
+      await vi.waitFor(() => { expect(handle.generation.getSnapshot()?.id).toBe(1) })
+      handle.reconnect()
+      await vi.waitFor(() => { expect(handle.generation.getSnapshot()?.id).toBe(2) })
+      expect(requested).toHaveBeenCalledOnce()
+      loop.stop()
+      handle.reconnect()
+      expect(requested).toHaveBeenCalledOnce()
+    } finally {
+      loop.stop()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('ignores a non-browser window shim without navigator state', async () => {
+    vi.stubGlobal('window', new EventTarget())
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    installGeneration(handle)
+    const loop = handle.start({})
+    try {
+      await vi.waitFor(() => { expect(handle.state.getSnapshot()).toBe('connected') })
+    } finally {
+      loop.stop()
+    }
+  })
+
+  it('feeds browser offline and online events into the owned retry loop', async () => {
+    vi.useFakeTimers()
+    const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0)
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const browser = new BrowserNetworkProbe()
+    vi.stubGlobal('window', browser)
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    let calls = 0
+    const source: ConnectionGenerationSource = (signal, ready) => new Promise<void>((resolve) => {
+      calls++
+      ready({ home: '/h' })
+      signal.addEventListener('abort', () => { resolve() }, { once: true })
+    })
+    handle.registerGenerationSource(source)
+    const states: Array<ConnectionState | undefined> = []
+    const unsubscribe = handle.state.subscribe(() => { states.push(handle.state.getSnapshot()) })
+    const loop = handle.start({}, {
+      backoffBaseMs: 100,
+      backoffFactor: 2,
+      backoffMaxMs: 1_000,
+      generationReadyTimeoutMs: 500,
+    })
+    try {
+      await vi.advanceTimersByTimeAsync(0)
+      expect(handle.state.getSnapshot()).toBe('connected')
+      expect(calls).toBe(1)
+
+      browser.setOnline(false)
+      expect(handle.state.getSnapshot()).toBe('disconnected')
+      await vi.advanceTimersByTimeAsync(10_000)
+      expect(calls).toBe(1)
+
+      browser.setOnline(true)
+      expect(handle.state.getSnapshot()).toBe('connecting')
+      await vi.advanceTimersByTimeAsync(49)
+      expect(calls).toBe(1)
+      await vi.advanceTimersByTimeAsync(1)
+      expect(calls).toBe(2)
+      expect(handle.state.getSnapshot()).toBe('connected')
+      expect(states).toEqual(['connected', 'disconnected', 'connecting', 'connected'])
+    } finally {
+      unsubscribe()
+      loop.stop()
+      randomSpy.mockRestore()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('does not announce a generation synchronously stopped by a generation subscriber', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    installGeneration(handle)
+    const owner: { loop?: ReturnType<ConnectionHandle['start']> } = {}
+    let sawGeneration = false
+    const stopGeneration = handle.generation.subscribe(() => {
+      if (handle.generation.getSnapshot() === undefined) return
+      sawGeneration = true
+      owner.loop?.stop()
+    })
+    const connected = vi.fn()
+    const loop = handle.start({ onConnected: connected })
+    owner.loop = loop
+    try {
+      await vi.waitFor(() => { expect(sawGeneration).toBe(true) })
+      expect(handle.generation.getSnapshot()).toBeUndefined()
+      expect(connected).not.toHaveBeenCalled()
+    } finally {
+      stopGeneration()
+      loop.stop()
+    }
+  })
+
+  it('retracts the generation while connecting and publishes the next generation', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    const generation = installGeneration(handle)
+    const generations: Array<string | undefined> = []
+    const reconnectSnapshots: Array<string | undefined> = []
+    const stopGeneration = handle.generation.subscribe(() => {
+      generations.push(handle.generation.getSnapshot()?.host.home)
+    })
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const loop = handle.start({
+      onStateChange: (state) => {
+        if (state === 'connecting') {
+          reconnectSnapshots.push(handle.generation.getSnapshot()?.host.home)
+        }
+      },
+    }, { backoffBaseMs: 10, backoffFactor: 2, backoffMaxMs: 80, generationReadyTimeoutMs: 500 })
+    try {
+      await vi.waitFor(() => {
+        expect(handle.generation.getSnapshot()?.host.home).toBe('/h')
+      })
+      generation.end()
+
+      await vi.waitFor(() => { expect(reconnectSnapshots).toEqual([undefined]) })
+      await vi.waitFor(() => { expect(generations).toEqual(['/h', undefined, '/h']) })
+      expect(handle.generation.getSnapshot()?.host.home).toBe('/h')
+    } finally {
+      stopGeneration()
+      loop.stop()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('publishes connection state directly on the service and isolates subscribers', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    const generation = installGeneration(handle)
+    const snapshots: Array<ConnectionState | undefined> = []
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    const unsubscribe = handle.state.subscribe(() => { snapshots.push(handle.state.getSnapshot()) })
+    const stopThrowing = handle.state.subscribe(() => { throw new Error('state subscriber failed') })
+    expect(handle.state.getSnapshot()).toBeUndefined()
+
+    const loop = handle.start({}, {
+      backoffBaseMs: 10,
+      backoffFactor: 2,
+      backoffMaxMs: 80,
+      generationReadyTimeoutMs: 500,
+    })
+    try {
+      await vi.waitFor(() => { expect(handle.state.getSnapshot()).toBe('connected') })
+      const connected = handle.state.getSnapshot()
+      expect(handle.state.getSnapshot()).toBe(connected)
+      generation.end()
+      await vi.waitFor(() => {
+        expect(snapshots).toEqual([
+          'connected',
+          'connecting',
+          'connected',
+        ])
+      })
+      expect(errorSpy).toHaveBeenCalledWith('[connection] state listener threw:', expect.any(Error))
+    } finally {
+      unsubscribe()
+      stopThrowing()
+      loop.stop()
+      errorSpy.mockRestore()
+    }
+    expect(handle.state.getSnapshot()).toBeUndefined()
+  })
+
+  it('does not announce disconnection after a generation subscriber stops the loop', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    const handle = await mount()
+    const generation = installGeneration(handle)
+    const owner: { loop?: ReturnType<ConnectionHandle['start']> } = {}
+    let stoppedOnRetraction = false
+    const stopGeneration = handle.generation.subscribe(() => {
+      if (handle.generation.getSnapshot() !== undefined || owner.loop === undefined) return
+      stoppedOnRetraction = true
+      owner.loop.stop()
+    })
+    const states: ConnectionState[] = []
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const loop = handle.start({
+      onStateChange: (state) => { states.push(state) },
+    }, { backoffBaseMs: 10, backoffFactor: 2, backoffMaxMs: 80, generationReadyTimeoutMs: 500 })
+    owner.loop = loop
+    try {
+      await vi.waitFor(() => {
+        expect(handle.generation.getSnapshot()?.host.home).toBe('/h')
+      })
+      generation.end()
+
+      await vi.waitFor(() => { expect(stoppedOnRetraction).toBe(true) })
+      expect(handle.generation.getSnapshot()).toBeUndefined()
+      expect(states).toEqual(['connected'])
+    } finally {
+      stopGeneration()
+      loop.stop()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('carries RPC calls without requiring secure-context randomUUID', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost' }
+    vi.stubGlobal('crypto', {
+      getRandomValues(bytes: Uint8Array) {
+        return bytes.fill(0)
+      },
+    })
+    const handle = await mount()
+    const original = globalThis.fetch
+    const seen: { url: string; body: unknown }[] = []
+    globalThis.fetch = async (input: URL | RequestInfo, init?: RequestInit) => {
+      const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+      if (typeof init?.body !== 'string') throw new TypeError('expected a JSON string request body')
+      const body = JSON.parse(init.body) as { rpcId: string }
+      seen.push({ url, body })
+      return Response.json({
+        type: 'server-response',
+        rpcId: body.rpcId,
+        result: { ok: true, value: { ref: 'goal-1' } },
+      })
+    }
+    try {
+      await expect(handle.rpc.call('/api', 'goals/create', { args: { agentId: 'agent-1' } }))
+        .resolves.toEqual({ ok: true, value: { ref: 'goal-1' } })
+    } finally {
+      globalThis.fetch = original
+      vi.unstubAllGlobals()
+    }
+    expect(seen).toHaveLength(1)
+    expect(seen[0]?.url).toBe('http://dsh.internal/api/goals/create')
+    expect(seen[0]?.body).toMatchObject({
+      type: 'client-request',
+      rpcId: '00000000-0000-4000-8000-000000000000',
+      method: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    })
+  })
+
+  it('uses an already decoded rpc carrier from the transport hooks instead of the HTTP caller', async () => {
+    ;(globalThis as Win).location = { hostname: 'preview.example' }
+    const rpc: ClientConnectionRpc = {
+      call: vi.fn(async (_channel: string, endpoint: string, payload: unknown) => ({ ok: true as const, value: { endpoint, payload } })),
+      open: vi.fn((_channel: string, endpoint: string) => (async function *(): AsyncGenerator { yield endpoint })()),
+    }
+    ;(globalThis as Win).__DSH_TRANSPORT__ = { rpc }
+    const handle = await mount()
+    expect(handle.rpc).toBe(rpc)
+    await expect(handle.rpc.call('/api', 'session/list', { args: [] })).resolves.toEqual({
+      ok: true, value: { endpoint: 'session/list', payload: { args: [] } },
+    })
+  })
+
+  it('exposes a worker-local Gateway stream through connection.rpc.open', async () => {
+    ;(globalThis as Win).location = { hostname: 'preview.example' }
+    const openStream = vi.fn<NonNullable<ClientTransportHooks['openStream']>>(
+      (endpoint, payload, signal) => (async function *(): AsyncGenerator {
+        signal.throwIfAborted()
+        yield { endpoint, payload }
+      })(),
+    )
+    ;(globalThis as Win).__DSH_TRANSPORT__ = {
+      fetch: vi.fn<RpcFetch>(),
+      openStream,
+      ownsHost: true,
+    }
+    const handle = await mount()
+    const abort = new AbortController()
+    const open = handle.rpc.open
+    if (open === undefined) throw new Error('worker-local stream carrier was not installed')
+
+    const values = []
+    for await (const value of open('/api', 'session/follow', { args: { sessionId: 'session-1' } }, abort.signal)) {
+      values.push(value)
+    }
+    expect(values).toEqual([{
+      endpoint: 'session/follow', payload: { args: { sessionId: 'session-1' } },
+    }])
+    expect(openStream).toHaveBeenCalledWith(
+      'session/follow',
+      { args: { sessionId: 'session-1' } },
+      abort.signal,
+    )
+    expect(handle.isLoopback).toBe(true)
+    expect(() => open('/rpc', 'session/follow', {}, abort.signal))
+      .toThrow('worker-local streams require the /api channel')
+    expect(() => open('/api/path', 'session/follow', {}, abort.signal))
+      .toThrow('invalid RPC target')
+  })
+
+  it('validates generic RPC transport failures, correlation, and targets', async () => {
+    ;(globalThis as Win).location = {
+      hostname: 'harness.example', origin: 'https://harness.example',
+    }
+    const handle = await mount()
+    const original = globalThis.fetch
+    const abort = new AbortController()
+    globalThis.fetch = vi.fn().mockResolvedValue(new Response('unavailable', { status: 503 }))
+    try {
+      await expect(handle.rpc.call('/api', 'goals/create', {}, abort.signal))
+        .rejects.toThrow('HTTP 503')
+      expect(globalThis.fetch).toHaveBeenCalledWith(
+        new URL('https://harness.example/api/goals/create'),
+        expect.objectContaining({ signal: abort.signal }),
+      )
+
+      ;(globalThis as Win).location = { hostname: 'localhost', origin: 'null' }
+      globalThis.fetch = vi.fn().mockResolvedValue(Response.json({
+        type: 'server-response',
+        rpcId: 'different-rpc',
+        result: { ok: true, value: null },
+      }))
+      await expect(handle.rpc.call('/api', 'goals/create', {})).rejects.toThrow('rpcId mismatch')
+      const fetch = vi.mocked(globalThis.fetch)
+      expect(fetch.mock.calls[0]?.[0]).toEqual(new URL('http://dsh.internal/api/goals/create'))
+      expect(fetch.mock.calls[0]?.[1]).not.toHaveProperty('signal')
+
+      const respond = (result: unknown): void => {
+        globalThis.fetch = async (_input: URL | RequestInfo, init?: RequestInit) => {
+          if (typeof init?.body !== 'string') throw new TypeError('expected a JSON request body')
+          const request = JSON.parse(init.body) as { rpcId: string }
+          return Response.json({ type: 'server-response', rpcId: request.rpcId, result })
+        }
+      }
+      for (const envelope of [
+        null,
+        { type: 'other', rpcId: 'rpc', result: { ok: true } },
+        { type: 'server-response', rpcId: 1, result: { ok: true } },
+      ]) {
+        globalThis.fetch = vi.fn().mockResolvedValue(Response.json(envelope))
+        await expect(handle.rpc.call('/api', 'goals/create', {}))
+          .rejects.toThrow('invalid server-response envelope')
+      }
+
+      respond(null)
+      await expect(handle.rpc.call('/api', 'goals/create', {}))
+        .rejects.toThrow('invalid server-response result')
+      respond({ ok: 'yes' })
+      await expect(handle.rpc.call('/api', 'goals/create', {}))
+        .rejects.toThrow('invalid server-response result')
+      respond({ ok: false, error: null })
+      await expect(handle.rpc.call('/api', 'goals/create', {}))
+        .rejects.toThrow('invalid server-response result')
+
+      for (const error of [
+        { code: 1, message: 'failed', details: {} },
+        { code: 'failed', message: 1, details: {} },
+        { code: 'failed', message: 'failed', details: [] },
+      ]) {
+        respond({ ok: false, error })
+        await expect(handle.rpc.call('/api', 'goals/create', {}))
+          .rejects.toThrow('invalid server-response failure')
+      }
+      respond({
+        ok: false,
+        error: { code: 'fixture-failed', message: 'fixture rejected the call', details: { retry: false } },
+      })
+      await expect(handle.rpc.call('/api', 'goals/create', {})).resolves.toEqual({
+        ok: false,
+        error: { code: 'fixture-failed', message: 'fixture rejected the call', details: { retry: false } },
+      })
+    } finally {
+      globalThis.fetch = original
+    }
+
+    for (const [channel, endpoint] of [
+      ['api2', 'goals/create'],
+      ['/api/path', 'goals/create'],
+      ['/api', ''],
+      ['/api', '.'],
+      ['/api', '..'],
+      ['/api', 'goals//create'],
+      ['/api', 'goals/create?unsafe'],
+    ] as const) {
+      await expect(handle.rpc.call(channel, endpoint, {})).rejects.toThrow('invalid RPC target')
+    }
+  })
+
+})

packages/client/connection/tests/connection.client.spec.ts

@@ -0,0 +1,800 @@
+/** Connection generation readiness, loss, retry, and sink isolation. */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { ConnectionGenerationSource, ConnectionState } from '../src/client/connection.ts'
+import { ConnectionController } from '../src/client/connection.ts'
+import { FakeGenerationSource } from './fake-generation.client.ts'
+
+const FAST = { backoffBaseMs: 10, backoffFactor: 2, backoffMaxMs: 80, generationReadyTimeoutMs: 500 }
+
+describe('connection lifecycle', () => {
+  it('announces connected with the Host facts from generation readiness', async () => {
+    const source = new FakeGenerationSource()
+    const homes: string[] = []
+    const controller = new ConnectionController(source.source, {
+      onConnected: (host) => { homes.push(host.home) },
+    }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(homes).toEqual(['/h']) })
+    } finally {
+      controller.stop()
+    }
+  })
+
+  it('reconnects with a fresh generation when its source fails, and stop() ends the loop', async () => {
+    const source = new FakeGenerationSource()
+    let connected = 0
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const controller = new ConnectionController(source.source, { onConnected: () => { connected++ } }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      source.fail(new Error('stream torn'))
+      await vi.waitFor(() => { expect(connected).toBe(2) })
+      expect(source.activeCount).toBe(1)
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+    }
+    await vi.waitFor(() => { expect(source.activeCount).toBe(0) })
+    await new Promise(resolve => setTimeout(resolve, 40))
+    expect(source.activeCount).toBe(0)
+  })
+
+  it('keeps retrying at the jittered cap and recovers after a prolonged outage', async () => {
+    vi.useFakeTimers()
+    const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0)
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const reconnectRequested = vi.fn()
+    let calls = 0
+    let available = false
+    const states: ConnectionState[] = []
+    const source: ConnectionGenerationSource = (signal, ready) => {
+      calls++
+      if (!available) return Promise.reject(new Error('offline'))
+      ready({ home: '/h' })
+      return new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+    }
+    const controller = new ConnectionController(source, {
+      onReconnectRequested: reconnectRequested,
+      onStateChange: state => states.push(state),
+    })
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(0)
+      expect(calls).toBe(1)
+      expect(states).toEqual(['connecting'])
+
+      for (const [attempt, delay] of [250, 500, 1_000, 2_000, 4_000, 5_000].entries()) {
+        await vi.advanceTimersByTimeAsync(delay)
+        expect(calls).toBe(attempt + 2)
+      }
+
+      expect(reconnectRequested).toHaveBeenCalledTimes(6)
+      expect(warnSpy).toHaveBeenCalledTimes(6)
+      expect(warnSpy).toHaveBeenLastCalledWith('[connection] connection lost, retry #6')
+      expect(states).toEqual(['connecting'])
+      await vi.advanceTimersByTimeAsync(60_000)
+      expect(calls).toBe(19)
+      available = true
+      await vi.advanceTimersByTimeAsync(5_000)
+      expect(calls).toBe(20)
+      expect(states).toEqual(['connecting', 'connected'])
+      expect(reconnectRequested).toHaveBeenCalledTimes(19)
+    } finally {
+      controller.stop()
+      randomSpy.mockRestore()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('continues retrying at a fixed cap when the growth factor is one', async () => {
+    vi.useFakeTimers()
+    const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0)
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const states: ConnectionState[] = []
+    let calls = 0
+    const controller = new ConnectionController(() => {
+      calls++
+      return Promise.reject(new Error('offline'))
+    }, {
+      onStateChange: state => states.push(state),
+    }, {
+      backoffBaseMs: 10,
+      backoffFactor: 1,
+      backoffMaxMs: 80,
+      generationReadyTimeoutMs: 500,
+    })
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(5)
+      expect(calls).toBe(2)
+      expect(states).toEqual(['connecting'])
+      await vi.advanceTimersByTimeAsync(1_000)
+      expect(calls).toBe(202)
+    } finally {
+      controller.stop()
+      randomSpy.mockRestore()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('interrupts the retry delay when a reconnect is requested', async () => {
+    vi.useFakeTimers()
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const reconnectRequested = vi.fn()
+    let calls = 0
+    const source: ConnectionGenerationSource = (signal, ready) => {
+      calls++
+      if (calls === 1) return Promise.reject(new Error('offline'))
+      ready({ home: '/h' })
+      return new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+    }
+    const controller = new ConnectionController(source, { onReconnectRequested: reconnectRequested })
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(0)
+      expect(calls).toBe(1)
+      controller.reconnect()
+      await vi.advanceTimersByTimeAsync(0)
+      expect(calls).toBe(2)
+      expect(reconnectRequested).toHaveBeenCalledOnce()
+    } finally {
+      controller.stop()
+      controller.reconnect()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('pauses retries while offline and restarts the base delay after each recovery', async () => {
+    vi.useFakeTimers()
+    const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0)
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const states: ConnectionState[] = []
+    let calls = 0
+    let active = 0
+    let maxActive = 0
+    const source: ConnectionGenerationSource = (signal, ready) => new Promise<void>((resolve) => {
+      calls++
+      active++
+      maxActive = Math.max(maxActive, active)
+      ready({ home: '/h' })
+      signal.addEventListener('abort', () => {
+        active--
+        resolve()
+      }, { once: true })
+    })
+    const controller = new ConnectionController(source, {
+      onStateChange: state => states.push(state),
+    })
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(0)
+      expect(calls).toBe(1)
+      expect(states).toEqual(['connected'])
+
+      controller.setNetworkAvailable(false)
+      controller.setNetworkAvailable(false)
+      expect(states.at(-1)).toBe('disconnected')
+      await vi.advanceTimersByTimeAsync(60_000)
+      expect(calls).toBe(1)
+      expect(active).toBe(0)
+
+      controller.setNetworkAvailable(true)
+      controller.setNetworkAvailable(true)
+      expect(states.at(-1)).toBe('connecting')
+      await vi.advanceTimersByTimeAsync(125)
+      controller.setNetworkAvailable(false)
+      await vi.advanceTimersByTimeAsync(60_000)
+      expect(calls).toBe(1)
+
+      controller.setNetworkAvailable(true)
+      await vi.advanceTimersByTimeAsync(249)
+      expect(calls).toBe(1)
+      await vi.advanceTimersByTimeAsync(1)
+      expect(calls).toBe(2)
+      expect(active).toBe(1)
+      expect(maxActive).toBe(1)
+      expect(states).toEqual([
+        'connected',
+        'disconnected',
+        'connecting',
+        'disconnected',
+        'connecting',
+        'connected',
+      ])
+      expect(warnSpy).toHaveBeenCalledOnce()
+      expect(warnSpy).toHaveBeenCalledWith('[connection] connection lost, retry #1')
+    } finally {
+      controller.stop()
+      randomSpy.mockRestore()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('stops an offline wait when its state sink stops the controller synchronously', async () => {
+    const source = vi.fn<ConnectionGenerationSource>(() => Promise.resolve())
+    const controller = new ConnectionController(source, {
+      onStateChange: () => { controller.stop() },
+    })
+    controller.setNetworkAvailable(false)
+    controller.start()
+    await Promise.resolve()
+    expect(source).not.toHaveBeenCalled()
+  })
+
+  it('allows one manual attempt while offline without starting automatic retries', async () => {
+    vi.useFakeTimers()
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const states: ConnectionState[] = []
+    let calls = 0
+    const controller = new ConnectionController(() => {
+      calls++
+      return Promise.reject(new Error('offline'))
+    }, {
+      onStateChange: state => states.push(state),
+    })
+    controller.setNetworkAvailable(false)
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(0)
+      expect(states).toEqual(['disconnected'])
+      expect(calls).toBe(0)
+
+      controller.reconnect()
+      expect(states.at(-1)).toBe('connecting')
+      await vi.advanceTimersByTimeAsync(0)
+      expect(calls).toBe(1)
+      expect(states.at(-1)).toBe('disconnected')
+      await vi.advanceTimersByTimeAsync(60_000)
+      expect(calls).toBe(1)
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('does not delay a reconnect requested synchronously from the connecting state sink', async () => {
+    vi.useFakeTimers()
+    const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0)
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    let calls = 0
+    let restart = true
+    const controller = new ConnectionController(() => {
+      calls++
+      return Promise.reject(new Error('offline'))
+    }, {
+      onStateChange: (state) => {
+        if (state !== 'connecting' || !restart) return
+        restart = false
+        controller.reconnect()
+      },
+    }, {
+      backoffBaseMs: 10,
+      backoffFactor: 2,
+      backoffMaxMs: 10,
+      generationReadyTimeoutMs: 500,
+    })
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(0)
+      expect(calls).toBe(2)
+      expect(warnSpy.mock.calls.map(([message]) => String(message))).toEqual([
+        '[connection] connection lost, retry #1',
+      ])
+    } finally {
+      controller.stop()
+      randomSpy.mockRestore()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it.each([
+    {
+      label: 'manual reconnect',
+      stopState: 'connecting' as const,
+      interrupt: (controller: ConnectionController) => { controller.reconnect() },
+    },
+    {
+      label: 'browser going offline',
+      stopState: 'disconnected' as const,
+      interrupt: (controller: ConnectionController) => { controller.setNetworkAvailable(false) },
+    },
+  ])('honors a synchronous stop from the $label state sink', async ({ stopState, interrupt }) => {
+    const source = new FakeGenerationSource()
+    const controller = new ConnectionController(source.source, {
+      onStateChange: (state) => {
+        if (state === stopState) controller.stop()
+      },
+    }, FAST)
+    controller.start()
+    await vi.waitFor(() => { expect(source.activeCount).toBe(1) })
+    interrupt(controller)
+    await vi.waitFor(() => { expect(source.activeCount).toBe(0) })
+  })
+
+  it('stops when the physical-reconnect sink disposes the controller', async () => {
+    vi.useFakeTimers()
+    const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0)
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    let calls = 0
+    const reconnectRequested = vi.fn()
+    const controller = new ConnectionController(() => {
+      calls++
+      return Promise.reject(new Error('offline'))
+    }, {
+      onReconnectRequested: () => {
+        reconnectRequested()
+        controller.stop()
+      },
+    }, FAST)
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(5)
+      expect(calls).toBe(1)
+      expect(reconnectRequested).toHaveBeenCalledOnce()
+    } finally {
+      controller.stop()
+      randomSpy.mockRestore()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('stops before opening a retry when the connecting state sink disposes the controller', async () => {
+    vi.useFakeTimers()
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    let calls = 0
+    const controller = new ConnectionController(() => {
+      calls++
+      return Promise.reject(new Error('offline'))
+    }, {
+      onStateChange: (state) => {
+        if (state === 'connecting') controller.stop()
+      },
+    })
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(60_000)
+      expect(calls).toBe(1)
+      expect(warnSpy).not.toHaveBeenCalled()
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('restarts an active retry immediately and resets its attempt number', async () => {
+    vi.useFakeTimers()
+    const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0)
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const reconnectRequested = vi.fn()
+    const states: ConnectionState[] = []
+    let calls = 0
+    const source: ConnectionGenerationSource = (signal) => {
+      calls++
+      if (calls <= 2) return Promise.reject(new Error('offline'))
+      return new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+    }
+    const controller = new ConnectionController(source, {
+      onReconnectRequested: reconnectRequested,
+      onStateChange: state => states.push(state),
+    }, FAST)
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(20)
+      expect(calls).toBe(3)
+      expect(states.at(-1)).toBe('connecting')
+
+      controller.reconnect()
+      await vi.advanceTimersByTimeAsync(0)
+      expect(calls).toBe(4)
+      expect(states.at(-1)).toBe('connecting')
+      expect(reconnectRequested).toHaveBeenCalledTimes(3)
+      expect(warnSpy.mock.calls.map(([message]) => String(message))).toEqual([
+        '[connection] connection lost, retry #1',
+        '[connection] connection lost, retry #2',
+        '[connection] connection lost, retry #1',
+      ])
+    } finally {
+      controller.stop()
+      randomSpy.mockRestore()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('stops while an automatic retry delay is pending', async () => {
+    vi.useFakeTimers()
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    let calls = 0
+    const controller = new ConnectionController(() => {
+      calls++
+      return Promise.reject(new Error('offline'))
+    })
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(0)
+      expect(calls).toBe(1)
+      controller.stop()
+      await vi.advanceTimersByTimeAsync(2_000)
+      expect(calls).toBe(1)
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('replaces an active generation immediately when reconnect is requested', async () => {
+    const source = new FakeGenerationSource()
+    const reconnectRequested = vi.fn()
+    let connected = 0
+    const controller = new ConnectionController(source.source, {
+      onConnected: () => { connected++ },
+      onReconnectRequested: reconnectRequested,
+    }, { backoffBaseMs: 60_000, backoffFactor: 2, backoffMaxMs: 120_000, generationReadyTimeoutMs: 500 })
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      controller.reconnect()
+      await vi.waitFor(() => { expect(connected).toBe(2) })
+      expect(reconnectRequested).toHaveBeenCalledOnce()
+      expect(source.activeCount).toBe(1)
+    } finally {
+      controller.stop()
+    }
+  })
+
+  it('isolates a connected sink exception from the generation', async () => {
+    const source = new FakeGenerationSource()
+    let connected = 0
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    const controller = new ConnectionController(source.source, {
+      onConnected: () => {
+        connected++
+        throw new Error('business layer bug')
+      },
+    }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      expect(source.activeCount).toBe(1)
+      expect(errorSpy).toHaveBeenCalledWith('[connection] connection sink threw:', expect.any(Error))
+    } finally {
+      controller.stop()
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('holds onConnected until the incremental source reports ready', async () => {
+    const source = new FakeGenerationSource()
+    source.holdReady = true
+    let connected = 0
+    const controller = new ConnectionController(source.source, { onConnected: () => { connected++ } }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(source.activeCount).toBe(1) })
+      await new Promise(resolve => setTimeout(resolve, 30))
+      expect(connected).toBe(0)
+      source.releaseReady()
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+    } finally {
+      controller.stop()
+    }
+  })
+
+  it('accepts only the first readiness report from one generation', async () => {
+    const homes: string[] = []
+    const source: ConnectionGenerationSource = (signal, ready) => {
+      ready({ home: '/first' })
+      ready({ home: '/duplicate' })
+      return new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+    }
+    const controller = new ConnectionController(source, {
+      onConnected: (host) => { homes.push(host.home) },
+    }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(homes).toEqual(['/first']) })
+    } finally {
+      controller.stop()
+    }
+  })
+
+  it('does not announce readiness after a stop queued from the ready callback', async () => {
+    const owner: { controller?: ConnectionController } = {}
+    let sourceCalls = 0
+    const connected = vi.fn()
+    const source: ConnectionGenerationSource = (signal, ready) => new Promise<void>((resolve) => {
+      sourceCalls++
+      ready({ home: '/h' })
+      queueMicrotask(() => { owner.controller?.stop() })
+      signal.addEventListener('abort', () => { resolve() }, { once: true })
+    })
+    const controller = new ConnectionController(source, { onConnected: connected }, FAST)
+    owner.controller = controller
+    controller.start()
+    await vi.waitFor(() => { expect(sourceCalls).toBe(1) })
+    expect(connected).not.toHaveBeenCalled()
+  })
+
+  it('rejects a generation whose source ends during readiness and retries', async () => {
+    const source = new FakeGenerationSource()
+    source.holdReady = true
+    const states: ConnectionState[] = []
+    let connected = 0
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const controller = new ConnectionController(source.source, {
+      onConnected: () => { connected++ },
+      onStateChange: state => states.push(state),
+    }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(source.activeCount).toBe(1) })
+      source.holdReady = false
+      source.end()
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      expect(states).toEqual(['connecting', 'connected'])
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it.each([
+    { label: 'ends normally', fail: () => Promise.resolve() },
+    {
+      label: 'rejects with a non-Error reason',
+      // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- the non-Error rejection is the scenario under test
+      fail: () => Promise.reject('fixture offline'),
+    },
+  ])('retries when the generation source $label before reporting ready', async ({ fail }) => {
+    let sourceCalls = 0
+    let connected = 0
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const source: ConnectionGenerationSource = (signal, ready) => {
+      sourceCalls++
+      if (sourceCalls === 1) return fail()
+      ready({ home: '/h' })
+      return new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+    }
+    const controller = new ConnectionController(source, { onConnected: () => { connected++ } }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(sourceCalls).toBe(2) })
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('accepts a slow Host after the warning and clears both readiness timers', async () => {
+    vi.useFakeTimers()
+    const source = new FakeGenerationSource()
+    source.holdReady = true
+    let connected = 0
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const controller = new ConnectionController(
+      source.source,
+      { onConnected: () => { connected++ } },
+      { ...FAST, generationReadyWarnMs: 20, generationReadyTimeoutMs: 100 },
+    )
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(0)
+      expect(source.activeCount).toBe(1)
+      await vi.advanceTimersByTimeAsync(20)
+      expect(connected).toBe(0)
+      expect(source.activeCount).toBe(1)
+      expect(warnSpy).toHaveBeenCalledWith('[connection] generation is still not ready after 20ms')
+      source.releaseReady()
+      await vi.advanceTimersByTimeAsync(100)
+      expect(connected).toBe(1)
+      expect(source.activeCount).toBe(1)
+      expect(vi.getTimerCount()).toBe(0)
+      expect(warnSpy).toHaveBeenCalledTimes(1)
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it.each([20, 100, 200])('cancels an unready generation with warn=%i ms, waits for cleanup, and ignores late ready', async (generationReadyWarnMs) => {
+    vi.useFakeTimers()
+    const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0)
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const cleanup = Promise.withResolvers<undefined>()
+    const signals: AbortSignal[] = []
+    const report: Array<(host: { home: string }) => void> = []
+    const connected = vi.fn()
+    const states: ConnectionState[] = []
+    const source: ConnectionGenerationSource = async (signal, ready) => {
+      signals.push(signal)
+      report.push(ready)
+      await new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+      await cleanup.promise
+    }
+    const controller = new ConnectionController(source, {
+      onConnected: connected,
+      onStateChange: state => states.push(state),
+    }, { ...FAST, generationReadyWarnMs, generationReadyTimeoutMs: 100 })
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(100)
+      expect(signals[0]?.aborted).toBe(true)
+      expect(signals[0]?.reason).toMatchObject({ message: 'connection generation was not ready within 100ms' })
+      const warnings = generationReadyWarnMs <= 100
+        ? [[`[connection] generation is still not ready after ${String(generationReadyWarnMs)}ms`]]
+        : []
+      warnings.push(['[connection] connection generation was not ready within 100ms; cancelling generation'])
+      expect(warnSpy.mock.calls).toEqual(warnings)
+      report[0]!({ home: '/stale' })
+      await vi.advanceTimersByTimeAsync(1_000)
+      expect(signals).toHaveLength(1)
+      expect(connected).not.toHaveBeenCalled()
+      expect(warnSpy.mock.calls).toEqual(warnings)
+      cleanup.resolve(undefined)
+      await vi.advanceTimersByTimeAsync(5)
+      expect(signals).toHaveLength(2)
+      report[1]!({ home: '/fresh' })
+      await vi.advanceTimersByTimeAsync(0)
+      expect(connected).toHaveBeenCalledExactlyOnceWith({ home: '/fresh' })
+      expect(states).toEqual(['connecting', 'connected'])
+      expect(vi.getTimerCount()).toBe(0)
+    } finally {
+      controller.stop()
+      cleanup.resolve(undefined)
+      await vi.advanceTimersByTimeAsync(0)
+      randomSpy.mockRestore()
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it.each(['stop', 'reconnect', 'failure'] as const)('clears a pending handshake deadline on %s', async (action) => {
+    vi.useFakeTimers()
+    const source = new FakeGenerationSource()
+    source.holdReady = true
+    const connected = vi.fn()
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const controller = new ConnectionController(source.source, { onConnected: connected }, {
+      ...FAST, generationReadyWarnMs: 20, generationReadyTimeoutMs: 100,
+    })
+    controller.start()
+    try {
+      await vi.advanceTimersByTimeAsync(10)
+      source.holdReady = false
+      if (action === 'failure') source.fail(new Error('carrier failed'))
+      else controller[action]()
+      await vi.advanceTimersByTimeAsync(0)
+      source.releaseReady()
+      await vi.advanceTimersByTimeAsync(200)
+      expect(source.activeCount).toBe(action === 'stop' ? 0 : 1)
+      expect(connected).toHaveBeenCalledTimes(action === 'stop' ? 0 : 1)
+      expect(vi.getTimerCount()).toBe(0)
+      expect(warnSpy.mock.calls.some(([message]) => String(message).includes('still not ready'))).toBe(false)
+      expect(warnSpy.mock.calls.some(([message]) => String(message).includes('cancelling generation'))).toBe(false)
+    } finally {
+      controller.stop()
+      await vi.advanceTimersByTimeAsync(0)
+      warnSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('emits the disconnected, retry-attempt, and connected transitions', async () => {
+    const source = new FakeGenerationSource()
+    const states: ConnectionState[] = []
+    let connected = 0
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const controller = new ConnectionController(source.source, {
+      onConnected: () => { connected++ },
+      onStateChange: state => states.push(state),
+    }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      expect(states).toEqual(['connected'])
+      source.fail(new Error('torn'))
+      await vi.waitFor(() => { expect(connected).toBe(2) })
+      expect(states).toEqual(['connected', 'connecting', 'connected'])
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('does not announce a generation stopped synchronously by its connected state sink', async () => {
+    const source = new FakeGenerationSource()
+    const states: ConnectionState[] = []
+    let connected = 0
+    const controller = new ConnectionController(source.source, {
+      onConnected: () => { connected++ },
+      onStateChange: (state) => {
+        states.push(state)
+        if (state === 'connected') controller.stop()
+      },
+    }, FAST)
+
+    controller.start()
+    await vi.waitFor(() => { expect(states).toEqual(['connected']) })
+    await vi.waitFor(() => { expect(source.activeCount).toBe(0) })
+    expect(connected).toBe(0)
+  })
+
+  it('keeps one connecting state across consecutive retry attempts', async () => {
+    let sourceCalls = 0
+    const states: ConnectionState[] = []
+    let connected = 0
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const source: ConnectionGenerationSource = (signal, ready) => {
+      sourceCalls++
+      if (sourceCalls <= 2) return Promise.reject(new Error('down'))
+      ready({ home: '/h' })
+      return new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+    }
+    const controller = new ConnectionController(source, {
+      onConnected: () => { connected++ },
+      onStateChange: state => states.push(state),
+    }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(sourceCalls).toBe(3) })
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      expect(states).toEqual(['connecting', 'connected'])
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('runs with no sinks at all', async () => {
+    const source = new FakeGenerationSource()
+    const controller = new ConnectionController(source.source, {}, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(source.activeCount).toBe(1) })
+    } finally {
+      controller.stop()
+    }
+  })
+
+  it('start() is idempotent', async () => {
+    const source = new FakeGenerationSource()
+    let connected = 0
+    const controller = new ConnectionController(source.source, { onConnected: () => { connected++ } }, FAST)
+    controller.start()
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      expect(source.activeCount).toBe(1)
+    } finally {
+      controller.stop()
+    }
+  })
+})

packages/client/connection/tests/fake-generation.client.ts

@@ -0,0 +1,80 @@
+/** Test-local programmable Connection generation source. */
+import type { ConnectionGenerationSource } from '../src/client/connection.ts'
+
+type StreamItem = { kind: 'end' } | { kind: 'fail'; error: unknown }
+
+interface StreamConnection {
+  feed(item: StreamItem): void
+}
+
+/** Hand-pumped generation source for Connection lifecycle tests. */
+export class FakeGenerationSource {
+  private readonly connections: StreamConnection[] = []
+
+  /** When true, the source never reports ready. */
+  suppressReady = false
+
+  /** When true, ready callbacks remain parked until the test releases them. */
+  holdReady = false
+
+  private heldReady: Array<() => void> = []
+
+  /** Open one generation. */
+  readonly source: ConnectionGenerationSource = (signal, ready) => this.open(signal, ready)
+
+  /** Release every generation currently parked before readiness. */
+  releaseReady(): void {
+    const held = this.heldReady
+    this.heldReady = []
+    for (const fire of held) fire()
+  }
+
+  /** End every active generation normally. */
+  end(): void {
+    for (const connection of [...this.connections]) connection.feed({ kind: 'end' })
+  }
+
+  /** Fail every active generation. */
+  fail(error: unknown): void {
+    for (const connection of [...this.connections]) connection.feed({ kind: 'fail', error })
+  }
+
+  /** Number of currently active generations. */
+  get activeCount(): number {
+    return this.connections.length
+  }
+
+  private async open(
+    signal: AbortSignal,
+    onReady: (host: { readonly home: string }) => void,
+  ): Promise<void> {
+    const inbox: StreamItem[] = []
+    let wake: (() => void) | null = null
+    const connection: StreamConnection = {
+      feed: (item) => {
+        inbox.push(item)
+        wake?.()
+      },
+    }
+    this.connections.push(connection)
+    const ready = (): void => { onReady({ home: '/h' }) }
+    if (this.holdReady) this.heldReady.push(ready)
+    else if (!this.suppressReady) ready()
+    try {
+      while (!signal.aborted) {
+        while (inbox.length > 0) {
+          const item = inbox.shift() as StreamItem
+          if (item.kind === 'end') return
+          if (item.kind === 'fail') throw item.error
+        }
+        await new Promise<void>((resolve) => {
+          wake = resolve
+          signal.addEventListener('abort', () => { resolve() }, { once: true })
+        })
+        wake = null
+      }
+    } finally {
+      this.connections.splice(this.connections.indexOf(connection), 1)
+    }
+  }
+}

packages/client/connection/tests/fetch-routes.host.spec.ts

@@ -0,0 +1,83 @@
+import { Context } from '@deepseek-ai/cordis'
+import { describe, expect, it, vi } from 'vitest'
+import type { BrowserAuth } from '../src/browser-auth.ts'
+import { HostConnectionService } from '../src/rpc-host.ts'
+
+async function mounted(): Promise<{
+  readonly connection: HostConnectionService
+  readonly dispose: () => Promise<void>
+}> {
+  const ctx = new Context()
+  const fiber = ctx.plugin((pluginCtx) => {
+    new HostConnectionService(pluginCtx, [], {} as BrowserAuth)
+  })
+  await fiber.await()
+  return {
+    connection: ctx.get('connection') as HostConnectionService,
+    dispose: () => fiber.dispose(),
+  }
+}
+
+describe('Connection exact Fetch routes', () => {
+  it('dispatches owned methods and returns 404 for unclaimed requests', async () => {
+    const { connection, dispose: disposeFiber } = await mounted()
+    const route = vi.fn(async (request: Request) =>
+      Response.json({ query: new URL(request.url).searchParams.get('sessionId') }))
+    const dispose = connection.fetch.register({
+      path: '/api/session.export',
+      methods: ['GET', 'HEAD', 'POST'],
+      requestBody: 'streaming',
+      fetch: route,
+    })
+    const shared = connection.createSharedFetchHandler('/api')
+
+    const response = await shared.fetch(new Request(
+      'http://host/api/session.export?sessionId=session-1',
+    ))
+    expect(shared.requestBodyMode({
+      method: 'POST', url: new URL('http://host/api/session.export'),
+    })).toBe('streaming')
+    expect(shared.requestBodyMode({
+      method: 'DELETE', url: new URL('http://host/api/session.export'),
+    })).toBe('buffered')
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ query: 'session-1' })
+    expect(route).toHaveBeenCalledOnce()
+    const post = await shared.fetch(new Request('http://host/api/session.export', { method: 'POST' }))
+    expect(post.status).toBe(200)
+    expect(route).toHaveBeenCalledTimes(2)
+
+    await dispose()
+    const withdrawn = await shared.fetch(new Request('http://host/api/session.export'))
+    expect(withdrawn.status).toBe(404)
+    await disposeFiber()
+  })
+
+  it('rejects invalid and duplicate registrations', async () => {
+    const { connection, dispose: disposeFiber } = await mounted()
+    const fetch = async (): Promise<Response> => new Response()
+
+    expect(() => connection.fetch.register({ path: '/outside', methods: ['GET'], requestBody: 'buffered', fetch }))
+      .toThrow('invalid exact Fetch route')
+    expect(() => connection.fetch.register({ path: '/api/session.export', methods: [], requestBody: 'buffered', fetch }))
+      .toThrow('declares no methods')
+    expect(() => connection.fetch.register({
+      path: '/api/session.export', methods: ['GET', 'GET'], fetch,
+      requestBody: 'buffered',
+    })).toThrow('repeats a method')
+    const dispose = connection.fetch.register({
+      path: '/api/session.export', methods: ['GET'], fetch,
+      requestBody: 'buffered',
+    })
+    expect(() => connection.fetch.register({
+      path: '/api/session.export', methods: ['HEAD'], fetch,
+      requestBody: 'buffered',
+    })).toThrow('already registered')
+    await dispose()
+    expect(() => connection.fetch.register({
+      path: '/api/session.export', methods: ['HEAD'], fetch,
+      requestBody: 'buffered',
+    })).not.toThrow()
+    await disposeFiber()
+  })
+})

packages/client/connection/tests/generation.client.spec.ts

@@ -0,0 +1,65 @@
+import { Context } from '@deepseek-ai/cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  apply,
+  type ConnectionGenerationSource,
+  type ConnectionHandle,
+} from '../src/client/index.ts'
+
+type BrowserGlobal = {
+  location?: { hostname: string }
+}
+
+const contexts = new Set<Context>()
+
+afterEach(async () => {
+  vi.restoreAllMocks()
+  delete (globalThis as BrowserGlobal).location
+  await Promise.all([...contexts].map(async ctx => ctx.fiber.dispose()))
+  contexts.clear()
+})
+
+async function mount(): Promise<ConnectionHandle> {
+  ;(globalThis as BrowserGlobal).location = { hostname: 'localhost' }
+  const ctx = new Context()
+  contexts.add(ctx)
+  await ctx.plugin({ apply, inject: [] })
+  const connection = ctx.get('connection') as ConnectionHandle | undefined
+  if (connection === undefined) throw new Error('plugin did not provide Connection')
+  return connection
+}
+
+describe('Connection generation facts', () => {
+  it('publishes ready-frame Host facts and retracts them when the loop stops', async () => {
+    const connection = await mount()
+    const source: ConnectionGenerationSource = (signal, ready) => {
+      ready({ home: '/home/from-ready' })
+      return new Promise<void>((resolve) => {
+        if (signal.aborted) resolve()
+        else signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+    }
+    connection.registerGenerationSource(source)
+    const seen: Array<string | undefined> = []
+    const stopListening = connection.generation.subscribe(() => {
+      seen.push(connection.generation.getSnapshot()?.host.home)
+    })
+    const loop = connection.start({}, {
+      backoffBaseMs: 1,
+      backoffFactor: 2,
+      backoffMaxMs: 8,
+      generationReadyTimeoutMs: 100,
+    })
+
+    await vi.waitFor(() => {
+      expect(connection.generation.getSnapshot()).toEqual({
+        id: 1,
+        host: { home: '/home/from-ready' },
+      })
+    })
+    loop.stop()
+    expect(connection.generation.getSnapshot()).toBeUndefined()
+    expect(seen).toEqual(['/home/from-ready', undefined])
+    stopListening()
+  })
+})

packages/client/connection/tests/http-bridge.host.spec.ts

@@ -0,0 +1,147 @@
+import { EventEmitter } from 'node:events'
+import { Readable } from 'node:stream'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { describe, expect, it } from 'vitest'
+import { bridge } from '../src/http-bridge.ts'
+
+describe('HTTP bridge abort', () => {
+  it('destroys a declared-oversize request instead of draining it', async () => {
+    const destroyed: true[] = []
+    const request = Readable.from([]) as unknown as IncomingMessage
+    Object.assign(request, {
+      url: '/api/session.prompt',
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'content-length': '999999' },
+      destroy: () => { destroyed.push(true) },
+    })
+    let status: number | undefined
+    let headers: unknown
+    const response = Object.assign(new EventEmitter(), {
+      writableEnded: false,
+      writeHead(code: number, values?: unknown) { status = code; headers = values; return this },
+      write() { return true },
+      end(this: { writableEnded: boolean }) { this.writableEnded = true; return this },
+    }) as unknown as ServerResponse
+
+    await bridge(request, response, {
+      requestBodyMode: () => 'buffered',
+      fetch: () => { throw new Error('a rejected request must never reach the handler') },
+    }, 1000)
+    // The socket must not stay parked draining a body the client can trickle
+    // at will after the rejection — same discipline as the chunked overrun.
+    expect(status).toBe(413)
+    expect(headers).toMatchObject({ connection: 'close' })
+    expect(destroyed).toHaveLength(1)
+  })
+
+  it('aborts a pending native picker request when the browser disconnects', async () => {
+    const body = JSON.stringify({
+      type: 'client-request', rpcId: 'picker-1', method: 'directoryPicker/pick', payload: { args: {} },
+    })
+    const request = Readable.from([Buffer.from(body)]) as unknown as IncomingMessage
+    Object.assign(request, {
+      url: '/api/directoryPicker/pick',
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+    })
+
+    const response = Object.assign(new EventEmitter(), {
+      writableEnded: false,
+      writeHead() { return this },
+      write() { return true },
+      end() { this.writableEnded = true; return this },
+    }) as unknown as ServerResponse
+
+    let resolveStarted!: () => void
+    const started = new Promise<void>((resolve) => { resolveStarted = resolve })
+    let carrierSignal: AbortSignal | undefined
+    const pending = bridge(request, response, {
+      requestBodyMode: () => 'buffered',
+      fetch: async (input) => {
+        const fetchRequest = input
+        carrierSignal = fetchRequest.signal
+        resolveStarted()
+        if (!fetchRequest.signal.aborted) {
+          await new Promise<void>((resolve) => {
+            fetchRequest.signal.addEventListener('abort', () => { resolve() }, { once: true })
+          })
+        }
+        return Response.json({ aborted: fetchRequest.signal.aborted })
+      },
+    }, Number.MAX_SAFE_INTEGER)
+    await started
+    response.emit('close')
+    await pending
+    expect(carrierSignal?.aborted).toBe(true)
+  })
+
+  it('streams a declared 2.19 GiB request before the body ends and bypasses the JSON buffer cap', async () => {
+    const request = new Readable({ read() {} }) as unknown as IncomingMessage
+    Object.assign(request, {
+      url: '/api/session/uploadFileBinary?sessionId=s1',
+      method: 'POST',
+      headers: {
+        'content-type': 'application/octet-stream',
+        'content-length': String(Math.ceil(2.19 * 1024 ** 3)),
+      },
+    })
+    let status: number | undefined
+    const responseBytes: Uint8Array[] = []
+    const response = Object.assign(new EventEmitter(), {
+      writableEnded: false,
+      writeHead(code: number) { status = code; return this },
+      write(chunk: Uint8Array) { responseBytes.push(chunk); return true },
+      end(this: { writableEnded: boolean }) { this.writableEnded = true; return this },
+    }) as unknown as ServerResponse
+
+    let resolveStarted!: () => void
+    const started = new Promise<void>((resolve) => { resolveStarted = resolve })
+    const received: Uint8Array[] = []
+    const pending = bridge(request, response, {
+      requestBodyMode: () => 'streaming',
+      fetch: async (input) => {
+        resolveStarted()
+        if (input.body === null) throw new Error('streaming request lost its body')
+        for await (const chunk of input.body) received.push(chunk)
+        return new Response('stored')
+      },
+    }, 1)
+
+    await started
+    expect(received).toEqual([])
+    request.push(Buffer.from([1, 2]))
+    request.push(Buffer.from([3, 4]))
+    request.push(null)
+    await pending
+    expect(status).toBe(200)
+    expect(received).toEqual([Uint8Array.of(1, 2), Uint8Array.of(3, 4)])
+    expect(Buffer.concat(responseBytes).toString()).toBe('stored')
+  })
+
+  it('closes an unread streaming request after returning an early validation response', async () => {
+    const destroyed: true[] = []
+    const request = new Readable({ read() {} }) as unknown as IncomingMessage
+    Object.assign(request, {
+      url: '/api/session/uploadFileBinary',
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      destroy: () => { destroyed.push(true) },
+    })
+    let status: number | undefined
+    let headers: unknown
+    const response = Object.assign(new EventEmitter(), {
+      writableEnded: false,
+      writeHead(code: number, values?: unknown) { status = code; headers = values; return this },
+      write() { return true },
+      end(this: { writableEnded: boolean }) { this.writableEnded = true; return this },
+    }) as unknown as ServerResponse
+
+    await bridge(request, response, {
+      requestBodyMode: () => 'streaming',
+      fetch: () => Promise.resolve(new Response(null, { status: 415 })),
+    }, 1)
+    expect(status).toBe(415)
+    expect(headers).toMatchObject({ connection: 'close' })
+    expect(destroyed).toEqual([true])
+  })
+})

packages/client/connection/tests/loopback-hostname.client.spec.ts

@@ -0,0 +1,18 @@
+/** Shared loopback-hostname semantics for the Host fence and browser UI. */
+
+import { describe, expect, it } from 'vitest'
+import { isLoopbackHostname } from '../src/loopback-hostname.ts'
+
+describe('isLoopbackHostname', () => {
+  it('accepts localhost, IPv6 loopback, and the whole IPv4 127/8 block', () => {
+    for (const hostname of ['localhost', '[::1]', '127.0.0.1', '127.8.9.10', '127.255.255.255']) {
+      expect(isLoopbackHostname(hostname)).toBe(true)
+    }
+  })
+
+  it('refuses malformed and non-loopback hostnames', () => {
+    for (const hostname of ['remote.localhost', '::1', '128.0.0.1', '127.0.0', '127.0.0.256', '127.0.0.-1']) {
+      expect(isLoopbackHostname(hostname)).toBe(false)
+    }
+  })
+})

packages/client/connection/tests/node-half.host.spec.ts

@@ -0,0 +1,565 @@
+/** Node half: registers the /api prefix route bridging to the api gateway. */
+import { EventEmitter } from 'node:events'
+import { createServer, request as httpRequest } from 'node:http'
+import { Readable } from 'node:stream'
+import { Context } from '@deepseek-ai/cordis'
+import { describe, expect, it } from 'vitest'
+import type { AddressInfo } from 'node:net'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment'
+import type { IndexInjection, WebServer, WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver'
+import { API_PATH, RpcId, apply, inject, type ClientRequest, type ConnectionConfig, type HostConnectionHandle } from '../src/index.ts'
+import { DEFAULT_MAX_REQUEST_BODY_BYTES } from '../src/http-bridge.ts'
+import { provideBrowserCredentials } from './browser-credentials.ts'
+
+/** Structural webServer fake recording both route registries. */
+function fakeHttpServer(
+  routes: WebRoute[],
+  upgrades: WebUpgradeRoute[],
+): Pick<WebServer, 'register' | 'registerUpgrade' | 'tapIndex' | 'port'> {
+  return {
+    register(route) {
+      if (routes.some(candidate => candidate.kind === route.kind && candidate.path === route.path)) {
+        throw new Error(`duplicate route ${route.path}`)
+      }
+      routes.push(route)
+      return () => { routes.splice(routes.indexOf(route), 1) }
+    },
+    registerUpgrade(route) {
+      upgrades.push(route)
+      return () => { upgrades.splice(upgrades.indexOf(route), 1) }
+    },
+    tapIndex: () => () => {},
+    port: 0,
+  }
+}
+
+/** Bodyless GET carrying the given headers (enough for the trust fence + bridge). */
+function fakeRequest(headers: Record<string, string>, url = `${API_PATH}/session.list`): IncomingMessage {
+  const request = Readable.from([]) as unknown as IncomingMessage
+  Object.assign(request, { url, method: 'GET', headers })
+  return request
+}
+
+/** JSON POST carrying a complete client-request envelope. */
+function fakePost(headers: Record<string, string>, url: string, body: unknown): IncomingMessage {
+  const request = Readable.from([Buffer.from(JSON.stringify(body))]) as unknown as IncomingMessage
+  Object.assign(request, { url, method: 'POST', headers: { 'content-type': 'application/json', ...headers } })
+  return request
+}
+
+/** Raw POST for malformed-body and media-type boundary cases. */
+function fakeRawPost(headers: Record<string, string>, url: string, body: string): IncomingMessage {
+  const request = Readable.from([Buffer.from(body)]) as unknown as IncomingMessage
+  Object.assign(request, { url, method: 'POST', headers })
+  return request
+}
+
+/** Response recorder compatible with both the fence's short-circuit and the bridge. */
+function fakeResponse(): {
+  response: ServerResponse
+  state: { status?: number; headers?: Record<string, string>; body?: unknown }
+} {
+  const state: { status?: number; headers?: Record<string, string>; body?: unknown } = {}
+  const chunks: Buffer[] = []
+  const response = Object.assign(new EventEmitter(), {
+    writableEnded: false,
+    writeHead(value: number, headers?: Record<string, string>) {
+      state.status = value
+      if (headers !== undefined) state.headers = headers
+      return this
+    },
+    write(value: string | Uint8Array) { chunks.push(Buffer.from(value)); return true },
+    end(this: { writableEnded: boolean }, value?: unknown) {
+      if (typeof value === 'string' || value instanceof Uint8Array) chunks.push(Buffer.from(value))
+      else if (value !== undefined) throw new TypeError('fake response only accepts string or Uint8Array bodies')
+      if (chunks.length > 0) state.body = Buffer.concat(chunks).toString()
+      this.writableEnded = true
+      return this
+    },
+  }) as unknown as ServerResponse
+  return { response, state }
+}
+
+async function mounted(config?: ConnectionConfig): Promise<{
+  ctx: Context
+  routes: WebRoute[]
+  upgrades: WebUpgradeRoute[]
+  connection: HostConnectionHandle
+  dispose: () => Promise<void>
+}> {
+  const ctx = new Context()
+  const routes: WebRoute[] = []
+  const upgrades: WebUpgradeRoute[] = []
+  provideBrowserCredentials(ctx)
+  ctx.provide('webServer', fakeHttpServer(routes, upgrades) as WebServer)
+  const fiber = ctx.plugin({ inject: [...inject], apply }, config)
+  await fiber.await()
+  return {
+    ctx,
+    routes,
+    upgrades,
+    connection: ctx.get('connection') as HostConnectionHandle,
+    dispose: () => fiber.dispose(),
+  }
+}
+
+/** Exchange a service's process token for one authority-bound Cookie header. */
+function browserCookie(connection: HostConnectionHandle, authority: string): string {
+  const url = new URL(connection.authenticatedUrl(`http://${authority}`))
+  const exchanged = fakeResponse()
+  connection.authorizeIndex(
+    fakeRequest({ host: authority }, `${url.pathname}${url.search}`),
+    exchanged.response,
+  )
+  const setCookie = exchanged.state.headers?.['set-cookie']
+  if (setCookie === undefined) throw new Error('browser token exchange did not set a cookie')
+  return setCookie.split(';', 1)[0]!
+}
+
+describe('connection node half', () => {
+  it('provides the carrier-neutral service without a Web server', async () => {
+    const ctx = new Context()
+    provideBrowserCredentials(ctx)
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(ctx.get('connection')).toBeInstanceOf(Object)
+    await fiber.dispose()
+  })
+
+  it('injects validated browser recovery timing and withdraws it on disposal', async () => {
+    const { ctx, dispose } = await mounted({ recovery: { generationReadyTimeoutMs: 25_000 } })
+    try {
+      const rows: IndexInjection[] = []
+      ctx.emit('webserver/index-inject', rows)
+      expect(rows).toEqual([{
+        kind: 'global', name: '__DSH_CONNECTION_RECOVERY__', value: {
+          backoffBaseMs: 500, backoffFactor: 2, backoffMaxMs: 10_000,
+          generationReadyWarnMs: 3_000, generationReadyTimeoutMs: 25_000,
+        },
+      }])
+      await dispose()
+      const after: IndexInjection[] = []
+      ctx.emit('webserver/index-inject', after)
+      expect(after).toEqual([])
+    } finally {
+      await dispose()
+    }
+  })
+
+  it.each([
+    { recovery: { backoffBaseMs: 0 }, error: /backoffBaseMs/ },
+    { recovery: { backoffFactor: NaN }, error: /backoffFactor.*finite/ },
+  ])('rejects invalid recovery timing before acquiring Host resources: $recovery', async ({ recovery, error }) => {
+    const ctx = new Context()
+    await expect(apply(ctx, { recovery })).rejects.toThrow(error)
+    expect(ctx.get('connection')).toBeUndefined()
+  })
+
+  it('reserves enough default carrier capacity for the 200 MiB image batch', () => {
+    expect(DEFAULT_MAX_REQUEST_BODY_BYTES).toBe(300 * 1024 * 1024)
+    expect(DEFAULT_MAX_REQUEST_BODY_BYTES).toBeGreaterThan(Math.ceil(200 * 1024 * 1024 * 4 / 3) + 1024 * 1024)
+  })
+
+  it('fails loud when the carrier cap cannot hold the configured image batch', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    ctx.provide('webServer', fakeHttpServer(routes, []) as WebServer)
+    ctx.provide('attachments', {
+      imageLimits: { maxMessageImageBytes: 20 * 1024 * 1024 },
+    } as AttachmentStore)
+    await expect(apply(ctx, { maxRequestBodyBytes: 1024 }))
+      .rejects.toThrow(/must be at least .* aggregate image limit/)
+    expect(routes).toHaveLength(0)
+  })
+
+  it('fails the load on a trustedHosts entry that is not a bare authority', async () => {
+    const routes: WebRoute[] = []
+    const upgrades: WebUpgradeRoute[] = []
+    const ctx = new Context()
+    provideBrowserCredentials(ctx)
+    ctx.provide('webServer', fakeHttpServer(routes, upgrades) as WebServer)
+    const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.internal/path'] })
+    await expect(fiber).rejects.toThrow(/not a bare host\[:port\] authority/)
+    expect(routes).toHaveLength(0)
+    expect(upgrades).toHaveLength(0)
+  })
+
+  it('registers only the HTTP route and removes it with the fiber', async () => {
+    const { routes, upgrades, dispose } = await mounted()
+    expect(routes).toHaveLength(1)
+    expect(routes[0]).toMatchObject({ kind: 'prefix', path: API_PATH })
+    expect(upgrades).toHaveLength(0)
+    await dispose()
+    expect(routes).toHaveLength(0)
+    expect(upgrades).toHaveLength(0)
+  })
+
+  it('refuses an untrusted Host on any /api path before the bridge runs', async () => {
+    const { routes, dispose } = await mounted()
+    const { response, state } = fakeResponse()
+    await routes[0]!.handler(fakeRequest({
+      host: 'harness.example', origin: 'http://harness.example', 'sec-fetch-site': 'same-origin',
+    }), response)
+    expect(state.status).toBe(403)
+    expect(state.body).toBe('forbidden')
+    await dispose()
+  })
+
+  it('requires the same browser session for every method on every trusted authority', async () => {
+    const { routes, connection, dispose } = await mounted({ trustedHosts: ['harness.example'] })
+    const methods = [
+      'session/openWorkspacePath',
+      'llm/discoverModels', 'skills/list', 'settings/openAgentPresetDirectory',
+    ]
+    for (const method of methods) {
+      const denied = fakeResponse()
+      await routes[0]!.handler(fakeRequest({ host: 'harness.example' }, `${API_PATH}/${method}`), denied.response)
+      expect([method, denied.state.status, denied.state.body]).toEqual([method, 401, 'unauthorized'])
+    }
+
+    const cookie = browserCookie(connection, 'harness.example')
+    for (const method of methods) {
+      const allowed = fakeResponse()
+      await routes[0]!.handler(
+        fakeRequest({ host: 'harness.example', cookie }, `${API_PATH}/${method}`),
+        allowed.response,
+      )
+      expect([method, allowed.state.status]).toEqual([method, 404])
+    }
+
+    const forged = fakeResponse()
+    await routes[0]!.handler(fakeRequest({ host: 'localhost:3080' }), forged.response)
+    expect(forged.state).toMatchObject({ status: 401, body: 'unauthorized' })
+    await dispose()
+  })
+
+  it('passes loopback and declared-authority requests through to the bridge', async () => {
+    const { routes, connection, dispose } = await mounted({ trustedHosts: ['harness.example:3080', '192.168.1.5'] })
+    // Loopback, no browser markers (curl shape): the fence passes; the carrier
+    // answers 404 for a GET unary path — proof the bridge ran.
+    const loopback = fakeResponse()
+    await routes[0]!.handler(fakeRequest({
+      host: '127.0.0.1:3080',
+      cookie: browserCookie(connection, '127.0.0.1:3080'),
+    }), loopback.response)
+    expect(loopback.state.status).toBe(404)
+    // An all-interfaces composition derives port-less LAN IP literals, which
+    // pass markerless curl on any port.
+    const lan = fakeResponse()
+    await routes[0]!.handler(fakeRequest({
+      host: '192.168.1.5:3080',
+      cookie: browserCookie(connection, '192.168.1.5:3080'),
+    }), lan.response)
+    expect(lan.state.status).toBe(404)
+    // Declared public authority, same-origin browser shape.
+    const declared = fakeResponse()
+    await routes[0]!.handler(fakeRequest({
+      host: 'harness.example:3080',
+      origin: 'http://harness.example:3080',
+      'sec-fetch-site': 'same-origin',
+      cookie: browserCookie(connection, 'harness.example:3080'),
+    }), declared.response)
+    expect(declared.state.status).toBe(404)
+    await dispose()
+  })
+
+  it('shares its configured trust and authentication policy with sibling routes', async () => {
+    const { connection, dispose } = await mounted({ trustedHosts: ['harness.example'] })
+    const loopback = fakeRequest({ host: '127.0.0.1:3080' })
+    const declared = fakeRequest({ host: 'harness.example' })
+
+    expect(connection.requestRejection(loopback)).toBe(401)
+    expect(connection.requestRejection(declared)).toBe(401)
+    expect(connection.requestRejection(fakeRequest({
+      host: 'harness.example',
+      cookie: browserCookie(connection, 'harness.example'),
+    }))).toBeUndefined()
+    await dispose()
+  })
+
+  it('provides a disposable dedicated RPC channel', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    provideBrowserCredentials(ctx)
+    ctx.provide('webServer', fakeHttpServer(routes, []) as WebServer)
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(routes).toHaveLength(1)
+    expect(routes[0]).toMatchObject({ kind: 'prefix', path: API_PATH })
+
+    const connection = ctx.get('connection') as HostConnectionHandle
+    const calls: unknown[] = []
+    const remove = connection.rpc.handle('/rpc', async (endpoint, payload) => {
+      calls.push({ endpoint, payload })
+      return { ok: true, value: { accepted: true } }
+    })
+    const route = routes.find(candidate => candidate.path === '/rpc')
+    expect(route).toBeDefined()
+
+    const request: ClientRequest = {
+      type: 'client-request',
+      rpcId: RpcId('rpc-dedicated'),
+      method: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }
+    const result = fakeResponse()
+    await route!.handler(fakePost({
+      host: '127.0.0.1:3080',
+      cookie: browserCookie(connection, '127.0.0.1:3080'),
+    }, '/rpc/goals/create', request), result.response)
+    expect(result.state.status).toBe(200)
+    expect(JSON.parse(String(result.state.body))).toEqual({
+      type: 'server-response',
+      rpcId: 'rpc-dedicated',
+      result: { ok: true, value: { accepted: true } },
+    })
+    expect(calls).toEqual([{
+      endpoint: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }])
+
+    expect(() => connection.rpc.handle('/rpc', async () => ({ ok: true, value: null })))
+      .toThrow(/duplicate route/)
+    await remove()
+    expect(routes.map(candidate => candidate.path)).toEqual([API_PATH])
+    await fiber.dispose()
+    expect(routes).toHaveLength(0)
+  })
+
+  it('dispatches claimed /api endpoints and withdraws the claim', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    provideBrowserCredentials(ctx)
+    ctx.provide('webServer', fakeHttpServer(routes, []) as WebServer)
+    const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.example'] })
+    await fiber.await()
+    const connection = ctx.get('connection') as HostConnectionHandle
+    const calls: unknown[] = []
+    const remove = connection.rpc.intercept(
+      '/api',
+      endpoint => endpoint === 'goals/create',
+      async (endpoint, payload) => {
+        calls.push({ endpoint, payload })
+        return { ok: true, value: { accepted: true } }
+      },
+    )
+    expect(() => connection.rpc.intercept(
+      '/api',
+      () => true,
+      async () => ({ ok: true, value: null }),
+    )).toThrow('already has an interceptor')
+    expect(() => connection.rpc.intercept(
+      '/rpc' as '/api',
+      () => true,
+      async () => ({ ok: true, value: null }),
+    )).toThrow('invalid shared RPC channel')
+    const route = routes.find(candidate => candidate.path === API_PATH)!
+    const request: ClientRequest = {
+      type: 'client-request',
+      rpcId: RpcId('rpc-shared'),
+      method: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }
+
+    const claimed = fakeResponse()
+    const loopbackCookie = browserCookie(connection, '127.0.0.1:3080')
+    await route.handler(fakePost({
+      host: '127.0.0.1:3080', cookie: loopbackCookie,
+    }, '/api/goals/create', request), claimed.response)
+    expect(JSON.parse(String(claimed.state.body))).toEqual({
+      type: 'server-response',
+      rpcId: 'rpc-shared',
+      result: { ok: true, value: { accepted: true } },
+    })
+    expect(calls).toEqual([{
+      endpoint: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }])
+
+    const denied = fakeResponse()
+    await route.handler(fakePost({ host: 'other.example' }, '/api/goals/create', request), denied.response)
+    expect(denied.state).toMatchObject({ status: 403, body: 'forbidden' })
+    expect(calls).toHaveLength(1)
+
+    const unclaimed = fakeResponse()
+    await route.handler(fakeRequest({
+      host: '127.0.0.1:3080', cookie: loopbackCookie,
+    }, '/api/session.list'), unclaimed.response)
+    expect(unclaimed.state.status).toBe(404)
+
+    await remove()
+    const withdrawn = fakeResponse()
+    await route.handler(fakePost({
+      host: '127.0.0.1:3080', cookie: loopbackCookie,
+    }, '/api/goals/create', request), withdrawn.response)
+    expect(withdrawn.state.status).toBe(404)
+    expect(calls).toHaveLength(1)
+
+    const removeAuthenticated = connection.rpc.intercept(
+      '/api',
+      endpoint => endpoint === 'goals/create',
+      async () => ({ ok: true, value: null }),
+    )
+    const declared = fakeResponse()
+    await route.handler(fakePost({
+      host: 'harness.example',
+      cookie: browserCookie(connection, 'harness.example'),
+    }, '/api/goals/create', request), declared.response)
+    expect(declared.state.status).toBe(200)
+    await removeAuthenticated()
+    await fiber.dispose()
+  })
+
+  it('applies the configured trust fence and JSON envelope checks to generic channels', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    provideBrowserCredentials(ctx)
+    ctx.provide('webServer', fakeHttpServer(routes, []) as WebServer)
+    const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.example'] })
+    await fiber.await()
+    const connection = ctx.get('connection') as HostConnectionHandle
+    const remove = connection.rpc.handle('/rpc', async (endpoint) => {
+      if (endpoint === 'fail') throw new Error('handler broke')
+      return { ok: true, value: null }
+    })
+    const route = routes.find(candidate => candidate.path === '/rpc')!
+    const harnessHeaders = {
+      host: 'harness.example',
+      cookie: browserCookie(connection, 'harness.example'),
+    }
+
+    const denied = fakeResponse()
+    await route.handler(fakePost({ host: 'other.example' }, '/rpc/goals/create', {}), denied.response)
+    expect(denied.state).toMatchObject({ status: 403, body: 'forbidden' })
+
+    const unauthenticated = fakeResponse()
+    await route.handler(fakePost({ host: 'harness.example' }, '/rpc/goals/create', {}), unauthenticated.response)
+    expect(unauthenticated.state).toMatchObject({ status: 401, body: 'unauthorized' })
+
+    const methodMismatch = fakeResponse()
+    await route.handler(fakePost(harnessHeaders, '/rpc/goals/create', {
+      type: 'client-request', rpcId: 'rpc-bad', method: 'other', payload: {},
+    }), methodMismatch.response)
+    expect(JSON.parse(String(methodMismatch.state.body))).toMatchObject({
+      rpcId: 'rpc-bad',
+      result: { ok: false, error: { code: 'gateway/bad-request' } },
+    })
+
+    for (const [request, status] of [
+      [fakeRequest(harnessHeaders, '/rpc/goals/create'), 404],
+      [fakePost(harnessHeaders, '/outside/goals/create', {}), 404],
+      [fakePost(harnessHeaders, '/rpc/goals//create', {}), 404],
+      [fakeRawPost(harnessHeaders, '/rpc/goals/create', '{}'), 415],
+      [fakeRawPost({ ...harnessHeaders, 'content-type': 'text/plain' }, '/rpc/goals/create', '{}'), 415],
+      [fakeRawPost({ ...harnessHeaders, 'content-type': 'application/json; charset=utf-8' }, '/rpc/goals/create', '{'), 400],
+    ] as const) {
+      const response = fakeResponse()
+      await route.handler(request, response.response)
+      expect(response.state.status).toBe(status)
+    }
+
+    for (const [body, rpcId] of [
+      [{ rpcId: 'retained-id' }, 'retained-id'],
+      [{ rpcId: 42 }, 'invalid-request'],
+      [null, 'invalid-request'],
+    ] as const) {
+      const response = fakeResponse()
+      await route.handler(fakePost(harnessHeaders, '/rpc/goals/create', body), response.response)
+      expect(JSON.parse(String(response.state.body))).toMatchObject({
+        rpcId,
+        result: { ok: false, error: { code: 'gateway/bad-request' } },
+      })
+    }
+
+    const failed = fakeResponse()
+    await route.handler(fakePost(harnessHeaders, '/rpc/fail', {
+      type: 'client-request', rpcId: 'rpc-fail', method: 'fail', payload: {},
+    }), failed.response)
+    expect(failed.state).toMatchObject({ status: 500, body: 'handler failure: Error: handler broke' })
+
+    expect(() => connection.rpc.handle('/api', async () => ({ ok: true, value: null })))
+      .toThrow('invalid or reserved RPC channel')
+    expect(() => connection.rpc.handle('api3', async () => ({ ok: true, value: null })))
+      .toThrow('invalid or reserved RPC channel')
+    await remove()
+    await fiber.dispose()
+  })
+})
+
+describe('connection node half over a real HTTP server', () => {
+  /** Serve the registered prefix route from a real server and return its port. */
+  async function serve(routes: WebRoute[]): Promise<{ port: number; close: () => Promise<void> }> {
+    const server = createServer((request, response) => {
+      void routes[0]!.handler(request, response)
+    })
+    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+    const address = server.address() as AddressInfo
+    return {
+      port: address.port,
+      close: () => new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error === undefined || error === null) resolve()
+          else reject(error)
+        })
+      }),
+    }
+  }
+
+  /** One real request; `host` spoofs the authority the way a LAN client's browser would send it. */
+  function call(port: number, method: string, host: string, cookie?: string): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const request = httpRequest(
+        {
+          host: '127.0.0.1',
+          port,
+          path: `${API_PATH}/${method}`,
+          method: 'GET',
+          headers: { host, ...cookie === undefined ? {} : { cookie } },
+        },
+        (response) => {
+          response.resume()
+          response.on('end', () => { resolve(response.statusCode ?? 0) })
+        },
+      )
+      request.on('error', reject)
+      request.end()
+    })
+  }
+
+  it('requires authentication uniformly over a real HTTP request', async () => {
+    // A real IncomingMessage pins the exploit boundary: a client-controlled
+    // Host naming loopback passes the rebinding fence but never authenticates.
+    const { routes, connection, dispose } = await mounted({ trustedHosts: ['harness.example'] })
+    const { port, close } = await serve(routes)
+    try {
+      const methods = [
+        'settings/openSettingsDocument',
+        'session/openWorkspacePath',
+        'llm/discoverModels', 'skills/list',
+        'settings/openAgentPresetDirectory',
+        'llm/listProviders', 'session/modelCatalog',
+      ]
+      for (const method of methods) {
+        expect([method, await call(port, method, 'localhost')]).toEqual([method, 401])
+        expect([method, await call(port, method, 'harness.example')]).toEqual([method, 401])
+      }
+      expect(await call(port, 'settings/openSettingsDocument', 'other.example')).toBe(403)
+
+      const declaredCookie = browserCookie(connection, 'harness.example')
+      for (const method of methods) {
+        expect([method, await call(port, method, 'harness.example', declaredCookie)]).toEqual([method, 404])
+      }
+      const loopbackAuthority = `127.0.0.1:${String(port)}`
+      expect(await call(
+        port,
+        'settings/openSettingsDocument',
+        loopbackAuthority,
+        browserCookie(connection, loopbackAuthority),
+      )).toBe(404)
+    } finally {
+      await close()
+      await dispose()
+    }
+  })
+})

packages/client/connection/tests/recovery-config.client.spec.ts

@@ -0,0 +1,32 @@
+/** Recovery timing validation before a loop or Host bootstrap is published. */
+import { describe, expect, it } from 'vitest'
+import { resolveConnectionConfig } from '../src/recovery-config.ts'
+
+describe('connection recovery configuration', () => {
+  it('separates the slow-Host warning from the hard handshake deadline', () => {
+    expect(resolveConnectionConfig()).toEqual({
+      backoffBaseMs: 500,
+      backoffFactor: 2,
+      backoffMaxMs: 10_000,
+      generationReadyWarnMs: 3_000,
+      generationReadyTimeoutMs: 15_000,
+    })
+  })
+
+  it.each([
+    { backoffBaseMs: 0 },
+    { backoffFactor: 0.5 },
+    { backoffFactor: Infinity },
+    { backoffFactor: NaN },
+    { backoffMaxMs: -1 },
+    { generationReadyWarnMs: NaN },
+    { generationReadyTimeoutMs: 2_147_483_648 },
+    { generationReadyTimeoutMs: '15000' },
+  ])('rejects timing that could disable recovery or overflow a timer: %j', (config) => {
+    expect(() => resolveConnectionConfig(config)).toThrow()
+  })
+
+  it('preserves a finite fractional growth factor', () => {
+    expect(resolveConnectionConfig({ backoffFactor: 1.5 }).backoffFactor).toBe(1.5)
+  })
+})

packages/client/connection/tests/rpc-schema.host.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { RpcId, transportError } from '../src/rpc.ts'
+import {
+  clientRequestSchema,
+  rpcErrorSchema,
+  rpcIdSchema,
+  rpcMessageSchema,
+  rpcResultSchema,
+  serverResponseSchema,
+} from '../src/rpc-schema.ts'
+import { z } from 'zod'
+
+describe('Connection RPC schema', () => {
+  it('brands any validated string correlation id', () => {
+    expect(RpcId('abc')).toBe('abc')
+    expect(rpcIdSchema.parse('')).toBe('')
+    expect(() => rpcIdSchema.parse(42)).toThrow()
+  })
+
+  it('folds transport exceptions into an internal failure', () => {
+    expect(transportError(new Error('wire down'))).toEqual({
+      ok: false,
+      error: { code: 'gateway/internal', message: 'wire down', details: {} },
+    })
+    expect(transportError('raw')).toMatchObject({
+      ok: false,
+      error: { code: 'gateway/internal', message: 'raw' },
+    })
+  })
+
+  it('validates generic failures and both result branches', () => {
+    expect(rpcErrorSchema.parse({ code: 'domain-failure', message: 'failed', details: { id: 'x' } }))
+      .toEqual({ code: 'domain-failure', message: 'failed', details: { id: 'x' } })
+    expect(() => rpcErrorSchema.parse({ code: 1, message: 'failed', details: {} })).toThrow()
+    expect(() => rpcErrorSchema.parse({ code: 'failed', message: 'failed', details: [] })).toThrow()
+
+    const schema = rpcResultSchema(z.object({ n: z.number() }))
+    expect(schema.parse({ ok: true, value: { n: 1 } })).toEqual({ ok: true, value: { n: 1 } })
+    expect(schema.parse({ ok: false, error: { code: 'failed', message: 'x', details: {} } }))
+      .toMatchObject({ ok: false })
+    expect(() => schema.parse({ ok: true, error: {} })).toThrow()
+  })
+
+  it('validates both envelope directions and valueless success', () => {
+    const request = { type: 'client-request', rpcId: 'r1', method: 'settings/describe', payload: { args: {} } }
+    const response = { type: 'server-response', rpcId: 'r1', result: { ok: true, value: 1 } }
+    expect(clientRequestSchema.parse(request).method).toBe('settings/describe')
+    expect(serverResponseSchema.parse(response).rpcId).toBe('r1')
+    for (const message of [request, response]) expect(rpcMessageSchema.parse(message)).toBeTruthy()
+    expect(() => rpcMessageSchema.parse({ type: 'other', rpcId: 'x' })).toThrow()
+    expect(() => clientRequestSchema.parse({ type: 'client-request', rpcId: 'r1' })).toThrow()
+    expect(() => serverResponseSchema.parse({ type: 'server-response', rpcId: 'r1' })).toThrow()
+    expect(() => serverResponseSchema.parse({ type: 'server-response', rpcId: 'r1', result: {} })).toThrow()
+    expect(serverResponseSchema.parse({
+      type: 'server-response', rpcId: 'r1', result: { ok: true },
+    }).rpcId).toBe('r1')
+  })
+})

packages/client/connection/tsconfig.client.json

@@ -0,0 +1,42 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.client.tsbuildinfo"
+  },
+  "files": [
+    "src/api-path.ts",
+    "src/client/api.ts",
+    "src/client/connection.ts",
+    "src/client/index.ts",
+    "src/client/random-uuid.ts",
+    "src/client/rpc.ts",
+    "src/loopback-hostname.ts",
+    "src/recovery-config.ts",
+    "src/rpc.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../attachment/attachment"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../credentials/credentials"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../util/brand"
+    }
+  ]
+}

packages/client/connection/tsconfig.host.json

@@ -0,0 +1,43 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.host.tsbuildinfo"
+  },
+  "files": [
+    "src/api-path.ts",
+    "src/api-request-trust.ts",
+    "src/browser-auth.ts",
+    "src/http-bridge.ts",
+    "src/index.ts",
+    "src/loopback-hostname.ts",
+    "src/recovery-config.ts",
+    "src/rpc-host.ts",
+    "src/rpc-schema.ts",
+    "src/rpc.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../attachment/attachment"
+    },
+    {
+      "path": "../../credentials/credentials"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../host/webserver"
+    },
+    {
+      "path": "../../util/brand"
+    }
+  ]
+}

packages/client/connection/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.host.json"
+    },
+    {
+      "path": "./tsconfig.client.json"
+    }
+  ]
+}

packages/client/connection/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-connection', ['lib/types/index.js'])

packages/client/file-upload/src/client/contract.ts

@@ -0,0 +1,33 @@
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import type { FileUploadValue } from '../types.ts'
+
+/** Browser request body accepted by the background file-upload service. */
+export type FileUploadBody = Blob | ReadableStream<Uint8Array>
+
+/** Monotone byte progress reported while a browser body is consumed. */
+export interface FileUploadProgress {
+  readonly loaded: number
+  readonly total?: number
+}
+
+/** Browser upload service addressed by one Session identity. */
+export interface FileUploadService {
+  /**
+   * Store one file for a Session. Blob and stream bodies use
+   * the background carrier; exact bytes use Remote.
+   * @param sessionId - Session that owns the staged receipt.
+   * @param data - browser Blob, exact bytes, or a one-shot byte stream.
+   * @param name - optional display name.
+   * @param signal - optional cancellation for the active upload.
+   * @param onProgress - optional byte-progress observer for background bodies.
+   * @returns the staged receipt and durable file reference, or a business error.
+   */
+  upload(
+    sessionId: SessionId,
+    data: Blob | Uint8Array | ReadableStream<Uint8Array>,
+    name?: string,
+    signal?: AbortSignal,
+    onProgress?: (progress: FileUploadProgress) => void,
+  ): Promise<RemoteResult<FileUploadValue>>
+}

packages/client/file-upload/src/client/index.ts

@@ -0,0 +1,26 @@
+/** Browser background-upload Cordis service. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { FileUploadRuntime } from './runtime.ts'
+import type { FileUploadService } from './contract.ts'
+
+export type { FileUploadProgress, FileUploadService } from './contract.ts'
+export type { FileUploadReceiptId, FileUploadValue } from '../types.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Session-addressed browser service for staged file uploads. */
+    fileUpload: FileUploadService
+  }
+}
+
+/** The upload service uses the generated Remote fallback. */
+export const inject = ['remote']
+
+/**
+ * Provide the browser background-upload service.
+ * @param ctx - Client plugin context.
+ */
+export function apply(ctx: Context): void {
+  ctx.plugin(FileUploadRuntime)
+}

packages/client/file-upload/src/client/runtime.ts

@@ -0,0 +1,345 @@
+/** Background browser upload implementation for Blob and byte-stream bodies. */
+
+import { Service, type Context } from '@deepseek-ai/cordis'
+import { bytesToBase64 } from '@deepseek-ai/dsh-util-crypto'
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { FILE_UPLOAD_PATH } from '../protocol.ts'
+import type {
+  ClientFileUploadHooks, EncodedFileUploadRequest, FileUploadFetch, FileUploadValue,
+} from '../types.ts'
+import type { FileUploadBody, FileUploadService } from './contract.ts'
+
+interface FileUploadRequest {
+  readonly path: string
+  readonly body: FileUploadBody
+  readonly headers?: Readonly<Record<string, string>>
+  readonly signal?: AbortSignal
+  readonly onProgress?: (progress: { readonly loaded: number; readonly total?: number }) => void
+}
+
+interface FileUploadResponse {
+  readonly status: number
+  readonly body: string
+}
+
+interface FileUploadRemoteContext extends Context {
+  readonly remote: {
+    readonly fileUploads: {
+      upload(
+        sessionId: SessionId,
+        request: EncodedFileUploadRequest,
+        signal?: AbortSignal,
+      ): Promise<RemoteResult<FileUploadValue>>
+    }
+  }
+}
+
+interface UploadWorkerStart {
+  readonly url: string
+  readonly body: FileUploadBody
+  readonly headers: Readonly<Record<string, string>>
+}
+
+type UploadWorkerOutput =
+  | { readonly kind: 'progress'; readonly loaded: number; readonly total?: number }
+  | { readonly kind: 'complete'; readonly status: number; readonly body: string }
+  | { readonly kind: 'error'; readonly message: string }
+
+interface UploadWorkerScope {
+  onmessage: ((event: MessageEvent<UploadWorkerStart>) => void) | null
+  postMessage(message: UploadWorkerOutput): void
+}
+
+interface UploadXhr {
+  readonly upload: { onprogress: ((event: ProgressEvent) => void) | null }
+  status: number
+  responseText: string
+  withCredentials: boolean
+  onload: ((event: ProgressEvent) => void) | null
+  onerror: ((event: ProgressEvent) => void) | null
+  open(method: string, url: string): void
+  setRequestHeader(name: string, value: string): void
+  send(body: Blob): void
+}
+
+type UploadWorkerFetch = (
+  input: string,
+  init: RequestInit & { readonly duplex: 'half' },
+) => Promise<Response>
+
+/**
+ * Self-contained Worker body; its string form becomes the Blob Worker source.
+ * @param scope - Worker global used for requests and progress messages.
+ * @param createXhr - XMLHttpRequest factory used for Blob progress.
+ * @param doFetch - Fetch carrier used for one-shot ReadableStream bodies.
+ */
+export function fileUploadWorker(
+  scope: UploadWorkerScope = self,
+  createXhr: () => UploadXhr = () => new XMLHttpRequest(),
+  doFetch: UploadWorkerFetch = (input, init) => fetch(input, init),
+): void {
+  scope.onmessage = (event: MessageEvent<UploadWorkerStart>) => {
+    const request = event.data
+    if (request.body instanceof Blob) {
+      const xhr = createXhr()
+      xhr.open('POST', request.url)
+      xhr.withCredentials = true
+      for (const [name, value] of Object.entries(request.headers)) xhr.setRequestHeader(name, value)
+      xhr.upload.onprogress = (progress) => {
+        scope.postMessage({
+          kind: 'progress',
+          loaded: progress.loaded,
+          ...(progress.lengthComputable ? { total: progress.total } : {}),
+        } satisfies UploadWorkerOutput)
+      }
+      xhr.onload = () => {
+        scope.postMessage({ kind: 'complete', status: xhr.status, body: xhr.responseText } satisfies UploadWorkerOutput)
+      }
+      xhr.onerror = () => {
+        scope.postMessage({ kind: 'error', message: 'background upload transport failed' } satisfies UploadWorkerOutput)
+      }
+      xhr.send(request.body)
+      return
+    }
+    if (!(request.body instanceof ReadableStream)) {
+      scope.postMessage({ kind: 'error', message: 'background upload worker received an invalid body' })
+      return
+    }
+    const source = request.body
+    void (async () => {
+      const reader = source.getReader()
+      let loaded = 0
+      const body = new ReadableStream<Uint8Array>({
+        async pull(controller) {
+          const item = await reader.read()
+          if (item.done) {
+            controller.close()
+            return
+          }
+          if (!(item.value instanceof Uint8Array)) {
+            throw new TypeError('background upload stream produced a non-Uint8Array chunk')
+          }
+          loaded += item.value.byteLength
+          scope.postMessage({ kind: 'progress', loaded })
+          controller.enqueue(item.value)
+        },
+        async cancel(reason) {
+          await reader.cancel(reason)
+        },
+      })
+      const response = await doFetch(request.url, {
+        method: 'POST',
+        headers: request.headers,
+        credentials: 'include',
+        body,
+        duplex: 'half',
+      })
+      scope.postMessage({
+        kind: 'complete',
+        status: response.status,
+        body: await response.text(),
+      })
+    })().catch((error: unknown) => {
+      scope.postMessage({
+        kind: 'error',
+        message: error instanceof Error ? error.message : String(error),
+      })
+    })
+  }
+}
+
+interface ClientFileUploadGlobal {
+  __DSH_FILE_UPLOAD__?: ClientFileUploadHooks
+}
+
+interface FileUploadTransport {
+  post(request: FileUploadRequest): Promise<FileUploadResponse>
+}
+
+/** Cordis service that owns one background carrier per upload operation. */
+export class FileUploadRuntime extends Service implements FileUploadService {
+  private readonly transport: FileUploadTransport
+
+  /** @param ctx - providing Client context. */
+  constructor(ctx: Context) {
+    super(ctx, 'fileUpload')
+    const hook = (globalThis as ClientFileUploadGlobal).__DSH_FILE_UPLOAD__
+    this.transport = hook === undefined ? workerTransport() : customTransport(hook.fetch)
+  }
+
+  /**
+   * Post one body with the carrier selected before Cordis boot.
+   * @param request - target, body, cancellation, and progress observer.
+   * @returns the response status and text body.
+   */
+  post(request: FileUploadRequest): Promise<FileUploadResponse> {
+    return this.transport.post(request)
+  }
+
+  /**
+   * Store one file for a Session.
+   * @param sessionId - Session that owns the staged receipt.
+   * @param data - browser Blob, exact bytes, or a one-shot byte stream.
+   * @param name - optional display name.
+   * @param signal - optional cancellation for the active upload.
+   * @param onProgress - optional byte-progress observer for background bodies.
+   * @returns the staged receipt and durable file reference, or a business error.
+   */
+  async upload(
+    sessionId: SessionId,
+    data: Blob | Uint8Array | ReadableStream<Uint8Array>,
+    name?: string,
+    signal?: AbortSignal,
+    onProgress?: (progress: { readonly loaded: number; readonly total?: number }) => void,
+  ): Promise<RemoteResult<FileUploadValue>> {
+    if (!(data instanceof Uint8Array)) {
+      const query = new URLSearchParams({ sessionId })
+      if (name !== undefined) query.set('name', name)
+      const response = await this.post({
+        path: `${FILE_UPLOAD_PATH}?${query.toString()}`,
+        body: data,
+        headers: { 'content-type': 'application/octet-stream' },
+        ...(signal === undefined ? {} : { signal }),
+        ...(onProgress === undefined ? {} : { onProgress }),
+      })
+      if (response.status !== 200) {
+        throw new Error(`file upload transport failed with HTTP ${String(response.status)}`)
+      }
+      return parseFileUploadResult(response.body)
+    }
+    return (this.ctx as FileUploadRemoteContext).remote.fileUploads.upload(
+      sessionId,
+      {
+        data: bytesToBase64(data),
+        ...(name === undefined ? {} : { name }),
+      },
+      signal,
+    )
+  }
+}
+
+function customTransport(customFetch: FileUploadFetch): FileUploadTransport {
+  return {
+    async post(request) {
+      const init: RequestInit & { duplex?: 'half' } = {
+        method: 'POST',
+        ...(request.headers === undefined ? {} : { headers: request.headers }),
+        body: request.body,
+        ...(request.body instanceof ReadableStream ? { duplex: 'half' as const } : {}),
+        ...(request.signal === undefined ? {} : { signal: request.signal }),
+      }
+      const response = await customFetch(resolveUrl(request.path), init)
+      return { status: response.status, body: await response.text() }
+    },
+  }
+}
+
+function workerTransport(): FileUploadTransport {
+  return {
+    post(request) {
+      if (typeof Worker !== 'function') {
+        return Promise.reject(new Error('background upload requires Web Worker support'))
+      }
+      const workerUrl = URL.createObjectURL(new Blob([
+        `(${fileUploadWorker.toString()})()`,
+      ], { type: 'text/javascript' }))
+      const worker = new Worker(workerUrl, { name: 'dsh-file-upload' })
+      URL.revokeObjectURL(workerUrl)
+      return new Promise((resolve, reject) => {
+        let settled = false
+        const abort = (): void => {
+          settled = true
+          worker.terminate()
+          request.signal?.removeEventListener('abort', abort)
+          reject(new DOMException('The operation was aborted.', 'AbortError'))
+        }
+        const finish = (settle: () => void): void => {
+          if (settled) return
+          settled = true
+          request.signal?.removeEventListener('abort', abort)
+          worker.terminate()
+          settle()
+        }
+        worker.onmessage = (event: MessageEvent<UploadWorkerOutput>) => {
+          const output = event.data
+          if (output.kind === 'progress') {
+            request.onProgress?.({
+              loaded: output.loaded,
+              ...(output.total === undefined ? {} : { total: output.total }),
+            })
+          } else if (output.kind === 'complete') {
+            finish(() => { resolve({ status: output.status, body: output.body }) })
+          } else {
+            finish(() => { reject(new Error(output.message)) })
+          }
+        }
+        worker.onerror = (event) => {
+          finish(() => { reject(new Error(event.message || 'background upload worker failed')) })
+        }
+        if (request.signal?.aborted === true) {
+          abort()
+          return
+        }
+        request.signal?.addEventListener('abort', abort, { once: true })
+        const message: UploadWorkerStart = {
+          url: resolveUrl(request.path).href,
+          body: request.body,
+          headers: request.headers ?? {},
+        }
+        if (request.body instanceof ReadableStream) worker.postMessage(message, [request.body])
+        else worker.postMessage(message)
+      })
+    },
+  }
+}
+
+function resolveUrl(path: string): URL {
+  const pageLocation = Reflect.get(globalThis, 'location') as unknown
+  const origin = typeof pageLocation === 'object' && pageLocation !== null
+    && 'origin' in pageLocation && typeof pageLocation.origin === 'string'
+    ? pageLocation.origin
+    : undefined
+  return new URL(path, origin === undefined || origin === 'null' ? 'http://dsh.internal' : origin)
+}
+
+function parseFileUploadResult(body: string): RemoteResult<FileUploadValue> {
+  const value = JSON.parse(body) as unknown
+  if (!isRecord(value) || typeof value.ok !== 'boolean') {
+    throw new TypeError('file upload transport returned an invalid result')
+  }
+  if (!value.ok) {
+    const error = value.error
+    if (!isRecord(error) || typeof error.code !== 'string'
+      || typeof error.message !== 'string' || !isRecord(error.details)) {
+      throw new TypeError('file upload transport returned an invalid failure')
+    }
+    return {
+      ok: false,
+      error: new RemoteError(error.code as never, error.message, error.details as never),
+    }
+  }
+  const result = value.value
+  const file = isRecord(result) ? result.file : undefined
+  if (!isRecord(result) || typeof result.receiptId !== 'string' || !isRecord(file)
+    || typeof file.attachmentId !== 'string' || typeof file.name !== 'string'
+    || typeof file.bytes !== 'number' || !Number.isSafeInteger(file.bytes) || file.bytes < 0) {
+    throw new TypeError('file upload transport returned an invalid receipt')
+  }
+  return {
+    ok: true,
+    value: {
+      receiptId: result.receiptId as FileUploadValue['receiptId'],
+      file: {
+        attachmentId: file.attachmentId as FileUploadValue['file']['attachmentId'],
+        name: file.name,
+        bytes: file.bytes,
+      },
+    },
+  }
+}
+
+function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

packages/client/file-upload/src/http-route.ts

@@ -0,0 +1,81 @@
+/** Authenticated raw-byte upload route registered on the Connection fetch registry. */
+
+import { brandString } from '@deepseek-ai/dsh-brand'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
+import type { FileUploads } from './index.ts'
+import type { FileUploadValue } from './types.ts'
+
+type FileUploadHttpResult =
+  | { readonly ok: true; readonly value: FileUploadValue }
+  | {
+    readonly ok: false
+    readonly error: { readonly code: string; readonly message: string; readonly details: object }
+  }
+
+/**
+ * Handle one authenticated raw-byte upload.
+ * @param service - Host upload service receiving streamed bytes.
+ * @param request - authenticated HTTP request from Connection.
+ * @returns JSON result using HTTP status 200 after request validation.
+ */
+export async function handleFileUploadHttp(service: FileUploads, request: Request): Promise<Response> {
+  if (request.method !== 'POST') {
+    return new Response(null, { status: 405, headers: { allow: 'POST' } })
+  }
+  const mediaType = request.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase()
+  if (mediaType !== 'application/octet-stream') {
+    return new Response('content type must be application/octet-stream', { status: 415 })
+  }
+  const url = new URL(request.url)
+  const sessionId = url.searchParams.get('sessionId')
+  if (sessionId === null || sessionId === '') {
+    return new Response('sessionId is required', { status: 400 })
+  }
+  const name = url.searchParams.get('name') ?? undefined
+  let result: FileUploadHttpResult
+  try {
+    result = {
+      ok: true,
+      value: await service.uploadStream({
+        sessionId: brandString<SessionId>(sessionId),
+        data: requestBodyChunks(request.body),
+        signal: request.signal,
+        ...(name === undefined ? {} : { name }),
+      }),
+    }
+  } catch (error) {
+    const failure = remoteErrorOf(error)
+    result = {
+      ok: false,
+      error: failure !== undefined
+        ? { code: failure.code, message: failure.message, details: failure.details }
+        : {
+          code: 'gateway/internal',
+          message: error instanceof Error ? error.message : String(error),
+          details: {},
+        },
+    }
+  }
+  return new Response(JSON.stringify(result), {
+    status: 200,
+    headers: {
+      'content-type': 'application/json; charset=utf-8',
+      'cache-control': 'no-store',
+    },
+  })
+}
+
+async function* requestBodyChunks(body: ReadableStream<Uint8Array> | null): AsyncIterable<Uint8Array> {
+  if (body === null) return
+  const reader = body.getReader()
+  try {
+    while (true) {
+      const chunk = await reader.read()
+      if (chunk.done) return
+      yield chunk.value
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}

packages/client/file-upload/src/index.ts

@@ -0,0 +1,265 @@
+/** Host file-upload service: streamed intake and Agent-scoped staged receipts. */
+
+import { randomUUID } from 'node:crypto'
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { FileAttachmentRef } from '@deepseek-ai/dsh-attachment'
+import type {} from '@deepseek-ai/dsh-client-connection'
+import type { CommandFileReceiptResolver } from '@deepseek-ai/dsh-commands'
+import { scopeOf } from '@deepseek-ai/dsh-scope'
+import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import { Remote, RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
+import { handleFileUploadHttp } from './http-route.ts'
+import { FILE_UPLOAD_PATH } from './protocol.ts'
+import type { EncodedFileUploadRequest, FileUploadReceiptId, FileUploadValue } from './types.ts'
+
+export type * from './types.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Host storage and staged-receipt service for browser file uploads. */
+    fileUploads: FileUploads
+  }
+}
+
+interface StagedFileUpload {
+  readonly file: FileAttachmentRef
+  /** Prompt that accepted this receipt; absent until successful admission. */
+  requestId?: string
+}
+
+/** Resolve or resume the ordinary Agent that owns one Session identity. */
+export type AgentResolver = (sessionId: SessionId) => Promise<Agent>
+
+/** Prompt receipt binding that restores its previous owners unless delivery commits it. */
+export interface PromptFileBinding extends Disposable {
+  /** Keep the receipt bindings until queue or history observation retires them. */
+  commit(): void
+}
+
+class PromptFileBindingGuard implements PromptFileBinding {
+  private settled = false
+
+  constructor(private readonly rollback: () => void) {}
+
+  commit(): void {
+    this.settled = true
+  }
+
+  [Symbol.dispose](): void {
+    if (this.settled) return
+    this.settled = true
+    this.rollback()
+  }
+}
+
+/** Host service owning upload storage and Agent-scoped staged receipts. */
+export class FileUploads extends TypertRemoteService {
+  static inject = ['agents', 'attachments', 'commands', 'connection']
+
+  private readonly stagedFiles = new WeakMap<Session, Map<FileUploadReceiptId, StagedFileUpload>>()
+  private agentResolver: AgentResolver | undefined
+
+  /** @param ctx - Host context carrying Agent, attachment, command, and Connection services. */
+  constructor(ctx: Context) {
+    super(ctx, 'fileUploads')
+    const resolve: CommandFileReceiptResolver = (agent, receiptId) =>
+      this.resolve(agent, receiptId as FileUploadReceiptId)
+    ctx.effect(
+      () => ctx.commands.registerFileReceiptResolver(resolve),
+      'file-upload: command file receipt resolver',
+    )
+    ctx.effect(
+      () => ctx.connection.fetch.register({
+        path: FILE_UPLOAD_PATH,
+        methods: ['POST'],
+        requestBody: 'streaming',
+        fetch: request => handleFileUploadHttp(this, request),
+      }),
+      'file-upload: streaming route',
+    )
+    ctx.on('session/event', (session, event) => { this.observeSessionEvent(session, event) })
+    ctx.on('session/disposed', (session) => { this.stagedFiles.delete(session) })
+  }
+
+  /**
+   * Register the ordinary-Session resolver used when a raw upload addresses a cold Session.
+   * @param resolve - resolver that returns the exact live Agent or throws a Remote error.
+   * @returns disposer removing this resolver.
+   */
+  registerAgentResolver(resolve: AgentResolver): () => void {
+    if (this.agentResolver !== undefined) throw new Error('file-upload: Agent resolver is already registered')
+    this.agentResolver = resolve
+    return () => {
+      if (this.agentResolver === resolve) this.agentResolver = undefined
+    }
+  }
+
+  /**
+   * Persist one encoded upload and stage it under the Agent receiver selected by Typert.
+   * @param agent - receiving Agent resolved from the Remote Agent scope.
+   * @param request - canonical base64 bytes and optional display name.
+   * @param signal - caller cancellation before storage begins.
+   * @returns the staged receipt and durable file reference.
+   */
+  @Remote('upload')
+  upload(agent: Agent, request: EncodedFileUploadRequest, signal: AbortSignal): Promise<FileUploadValue> {
+    signal.throwIfAborted()
+    return this.commit(agent, async () => this.ctx.attachments.admitEncodedFile({
+      data: request.data,
+      ...(request.name === undefined ? {} : { name: request.name }),
+    }))
+  }
+
+  /**
+   * Persist raw chunks for one Session without aggregating the upload.
+   * @param request - Session identity, ordered bytes, cancellation, and optional display name.
+   * @returns the staged receipt and durable file reference.
+   */
+  async uploadStream(request: {
+    readonly sessionId: SessionId
+    readonly data: AsyncIterable<Uint8Array>
+    readonly signal?: AbortSignal
+    readonly name?: string
+  }): Promise<FileUploadValue> {
+    const agent = await this.resolveAgent(request.sessionId)
+    return this.commit(agent, async () => this.ctx.attachments.saveFileStream({
+      data: request.data,
+      ...(request.signal === undefined ? {} : { signal: request.signal }),
+      ...(request.name === undefined ? {} : { name: request.name }),
+    }))
+  }
+
+  /**
+   * Resolve one staged receipt inside its receiving Agent scope.
+   * @param agent - receiving Agent.
+   * @param receiptId - opaque receipt minted for one completed upload.
+   * @returns durable file reference, or `undefined` for an unknown or foreign receipt.
+   */
+  resolve(agent: Agent, receiptId: FileUploadReceiptId): FileAttachmentRef | undefined {
+    this.assertAgentScope(agent)
+    return this.stagedFiles.get(agent.session)?.get(receiptId)?.file
+  }
+
+  /**
+   * Bind receipts while one prompt enters an Agent inbox.
+   * Disposal restores every prior binding unless the caller commits successful delivery.
+   * @param agent - receiving Agent.
+   * @param receiptIds - distinct staged receipts referenced by the prompt.
+   * @param requestId - prompt identity later observed in queue or history.
+   * @returns binding kept after commit until queue or history observation retires its receipts.
+   */
+  bindPrompt(
+    agent: Agent,
+    receiptIds: readonly FileUploadReceiptId[],
+    requestId: string,
+  ): PromptFileBinding {
+    this.assertAgentScope(agent)
+    const staged = this.stagedFiles.get(agent.session)
+    const bound = receiptIds.map((receiptId) => {
+      const upload = staged?.get(receiptId)
+      if (upload === undefined) throw fileNotStaged()
+      return { upload, previous: upload.requestId }
+    })
+    for (const { upload } of bound) upload.requestId = requestId
+    return new PromptFileBindingGuard(() => {
+      for (const { upload, previous } of bound) {
+        if (previous === undefined) delete upload.requestId
+        else upload.requestId = previous
+      }
+    })
+  }
+
+  /**
+   * Retire every receipt accepted by one removed queue occurrence.
+   * @param agent - receiving Agent.
+   * @param requestId - prompt identity carried by the queue occurrence.
+   */
+  retirePrompt(agent: Agent, requestId: string): void {
+    this.assertAgentScope(agent)
+    this.retire(agent.session, requestId)
+  }
+
+  private async commit(agent: Agent, save: () => Promise<FileAttachmentRef>): Promise<FileUploadValue> {
+    this.assertOrdinaryAgent(agent)
+    let file: FileAttachmentRef
+    try {
+      file = await save()
+    } catch (error) {
+      if (this.ctx.attachments.isAttachmentError(error)) {
+        throw new RemoteError('session/attachment-invalid' as never, error.message, { reason: error.code } as never)
+      }
+      throw new RemoteError(
+        'gateway/internal',
+        `failed to store file upload: ${String(error)}`,
+        {},
+        { cause: error },
+      )
+    }
+    if (this.ctx.agents.get(agent.id) !== agent) {
+      throw new RemoteError(
+        'session/not-found',
+        `session "${agent.id}" was disposed before its file upload completed`,
+        { sessionId: agent.id },
+      )
+    }
+    let staged = this.stagedFiles.get(agent.session)
+    if (staged === undefined) {
+      staged = new Map()
+      this.stagedFiles.set(agent.session, staged)
+    }
+    const receiptId = randomUUID() as FileUploadReceiptId
+    staged.set(receiptId, { file })
+    return { receiptId, file }
+  }
+
+  private async resolveAgent(sessionId: SessionId): Promise<Agent> {
+    const live = this.ctx.agents.get(sessionId)
+    if (live !== undefined) return live
+    const resolver = this.agentResolver
+    if (resolver === undefined) {
+      throw new RemoteError('session/not-found', `session "${sessionId}" is not attached`, { sessionId })
+    }
+    return resolver(sessionId)
+  }
+
+  private assertAgentScope(agent: Agent): void {
+    if (scopeOf(agent.ctx) !== agent) throw new Error('file-upload: operation requires the Agent\'s own scope')
+  }
+
+  private assertOrdinaryAgent(agent: Agent): void {
+    this.assertAgentScope(agent)
+    if (agent.session.header.origin === 'subagent') {
+      throw new RemoteError(
+        'subagent/attachment-invalid' as never,
+        'subagent conversations do not accept file uploads',
+        { reason: 'SUBAGENT_FILE_UNSUPPORTED' } as never,
+      )
+    }
+  }
+
+  private observeSessionEvent(session: Session, event: SessionEvent): void {
+    if (event.type !== 'user/message' || event.data.source.kind !== 'user'
+      || !('rpcId' in event.data.source)) return
+    if (typeof event.data.source.rpcId === 'string') this.retire(session, event.data.source.rpcId)
+  }
+
+  private retire(session: Session, requestId: string): void {
+    const staged = this.stagedFiles.get(session)
+    if (staged === undefined) return
+    for (const [receiptId, upload] of staged) {
+      if (upload.requestId === requestId) staged.delete(receiptId)
+    }
+    if (staged.size === 0) this.stagedFiles.delete(session)
+  }
+}
+
+function fileNotStaged(): RemoteError {
+  return new RemoteError(
+    'session/attachment-invalid' as never,
+    'File was not uploaded for this session.',
+    { reason: 'FILE_NOT_STAGED' } as never,
+  )
+}
+
+export default FileUploads

packages/client/file-upload/src/protocol.ts

@@ -0,0 +1,2 @@
+/** Authenticated raw-byte route owned by the file-upload service. */
+export const FILE_UPLOAD_PATH = '/api/session/uploadFileBinary'

packages/client/file-upload/src/types.ts

@@ -0,0 +1,35 @@
+/** Browser-safe request and receipt types for staged file uploads. */
+
+import type { FileAttachmentRef } from '@deepseek-ai/dsh-attachment/types'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Canonical encoded upload accepted by the Remote fallback. */
+export interface EncodedFileUploadRequest {
+  /** Canonical base64 encoding of the exact file bytes. */
+  readonly data: string
+  /** Optional display name; the Host sanitizes it into the stored leaf name. */
+  readonly name?: string
+}
+
+/** Durable receipt for one staged file upload. */
+export interface FileUploadValue {
+  /** Per-upload authority accepted only inside the receiving Agent scope. */
+  readonly receiptId: FileUploadReceiptId
+  readonly file: FileAttachmentRef
+}
+
+/** Host-minted authority for one staged file upload in one Agent scope. */
+export type FileUploadReceiptId = Branded<'file-upload-receipt-id'>
+
+/**
+ * Fetch-shaped carrier installed by a page that owns its Host transport.
+ * @param input - absolute same-origin upload URL.
+ * @param init - raw request body, headers, and cancellation signal.
+ * @returns the Host response.
+ */
+export type FileUploadFetch = (input: URL, init: RequestInit) => Promise<Response>
+
+/** Pre-Cordis hook supplied by a page whose Host runs in another execution context. */
+export interface ClientFileUploadHooks {
+  readonly fetch: FileUploadFetch
+}

packages/client/file-upload/tests/file-upload-http.host.spec.ts

@@ -0,0 +1,126 @@
+import { runInNewContext } from 'node:vm'
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
+import { describe, expect, it, vi } from 'vitest'
+import type { Mock } from 'vitest'
+import { handleFileUploadHttp } from '../src/http-route.ts'
+import type { FileUploads } from '../src/index.ts'
+
+function request(input: {
+  method?: string
+  sessionId?: string
+  name?: string
+  contentType?: string
+  body?: Uint8Array
+} = {}): Request {
+  const query = new URLSearchParams()
+  if (input.sessionId !== undefined) query.set('sessionId', input.sessionId)
+  if (input.name !== undefined) query.set('name', input.name)
+  const suffix = query.size === 0 ? '' : `?${query.toString()}`
+  return new Request(`http://host/api/session/uploadFileBinary${suffix}`, {
+    method: input.method ?? 'POST',
+    headers: input.contentType === undefined ? {} : { 'content-type': input.contentType },
+    ...(input.body === undefined ? {} : { body: new Blob([Uint8Array.from(input.body).buffer]) }),
+  })
+}
+
+function uploads(result: unknown): FileUploads & {
+  uploadStream: Mock<FileUploads['uploadStream']>
+  uploadedChunks: Uint8Array[]
+} {
+  const uploadedChunks: Uint8Array[] = []
+  const uploadStream = vi.fn<FileUploads['uploadStream']>(async (input) => {
+    for await (const chunk of input.data) uploadedChunks.push(chunk)
+    return await result as Awaited<ReturnType<FileUploads['uploadStream']>>
+  })
+  return {
+    uploadedChunks,
+    uploadStream,
+  } as unknown as FileUploads & {
+    uploadStream: Mock<FileUploads['uploadStream']>
+    uploadedChunks: Uint8Array[]
+  }
+}
+
+describe('background file upload Fetch route', () => {
+  it('accepts one authenticated streaming POST request', async () => {
+    const service = uploads(Promise.resolve({}))
+    expect((await handleFileUploadHttp(service, request({
+      sessionId: 's1', contentType: 'application/octet-stream',
+    }))).status).toBe(200)
+  })
+
+  it('rejects the wrong method, media type, and missing Session id without storing', async () => {
+    const service = uploads(Promise.resolve({}))
+    const wrongMethod = await handleFileUploadHttp(service, request({ method: 'GET' }))
+    expect(wrongMethod.status).toBe(405)
+    expect(wrongMethod.headers.get('allow')).toBe('POST')
+
+    const wrongType = await handleFileUploadHttp(service, request({ contentType: 'application/json' }))
+    expect(wrongType.status).toBe(415)
+    expect(await wrongType.text()).toBe('content type must be application/octet-stream')
+
+    const missingSession = await handleFileUploadHttp(
+      service,
+      request({ contentType: 'application/octet-stream' }),
+    )
+    expect(missingSession.status).toBe(400)
+    expect(await missingSession.text()).toBe('sessionId is required')
+    expect(service.uploadStream).not.toHaveBeenCalled()
+  })
+
+  it('stores the request bytes and returns the staged receipt', async () => {
+    const value = {
+      receiptId: 'receipt-1',
+      file: { attachmentId: 'file-1', name: 'large & final.bin', bytes: 4 },
+    }
+    const service = uploads(Promise.resolve(value))
+    const response = await handleFileUploadHttp(service, request({
+      sessionId: 's1',
+      name: 'large & final.bin',
+      contentType: 'application/octet-stream; charset=binary',
+      body: Uint8Array.of(1, 2, 3, 4),
+    }))
+    expect(service.uploadStream).toHaveBeenCalledOnce()
+    const upload = service.uploadStream.mock.calls[0]?.[0]
+    expect(upload).toMatchObject({ sessionId: 's1', name: 'large & final.bin' })
+    expect(upload?.signal).toBeInstanceOf(AbortSignal)
+    expect(service.uploadedChunks).toEqual([Uint8Array.of(1, 2, 3, 4)])
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toBe('application/json; charset=utf-8')
+    expect(response.headers.get('cache-control')).toBe('no-store')
+    expect(await response.json()).toEqual({ ok: true, value })
+  })
+
+  it('returns business and internal storage failures and keeps an absent name absent', async () => {
+    const business = uploads(Promise.reject(new RemoteError(
+      'session/attachment-invalid', 'denied', { reason: 'NOPE' },
+    )))
+    const businessResponse = await handleFileUploadHttp(business, request({
+      sessionId: 's1', contentType: 'application/octet-stream',
+    }))
+    expect(business.uploadStream).toHaveBeenCalledOnce()
+    const upload = business.uploadStream.mock.calls[0]?.[0]
+    expect(upload).toMatchObject({ sessionId: 's1' })
+    expect(upload?.signal).toBeInstanceOf(AbortSignal)
+    expect(business.uploadedChunks).toEqual([])
+    expect(await businessResponse.json()).toEqual({
+      ok: false,
+      error: { code: 'session/attachment-invalid', message: 'denied', details: { reason: 'NOPE' } },
+    })
+
+    const internal = uploads(Promise.reject(new Error('disk offline')))
+    expect(await (await handleFileUploadHttp(internal, request({
+      sessionId: 's1', contentType: 'application/octet-stream',
+    }))).json()).toEqual({
+      ok: false, error: { code: 'gateway/internal', message: 'disk offline', details: {} },
+    })
+
+    const foreignError = runInNewContext('new Error("disk exception")') as unknown as Error
+    const exception = uploads(Promise.reject(foreignError))
+    expect(await (await handleFileUploadHttp(exception, request({
+      sessionId: 's1', contentType: 'application/octet-stream',
+    }))).json()).toEqual({
+      ok: false, error: { code: 'gateway/internal', message: 'Error: disk exception', details: {} },
+    })
+  })
+})

packages/client/file-upload/tests/file-upload.client.spec.ts

@@ -0,0 +1,497 @@
+import { Context } from '@deepseek-ai/cordis'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { apply } from '../src/client/index.ts'
+import { fileUploadWorker, FileUploadRuntime } from '../src/client/runtime.ts'
+import type { FileUploadBody } from '../src/client/contract.ts'
+import type { ClientFileUploadHooks } from '../src/types.ts'
+
+interface UploadGlobal {
+  __DSH_FILE_UPLOAD__?: ClientFileUploadHooks
+}
+
+afterEach(() => {
+  delete (globalThis as UploadGlobal).__DSH_FILE_UPLOAD__
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+})
+
+describe('file upload worker body', () => {
+  it('sends a Blob with credentials and reports progress, completion, and failure', () => {
+    const posted: unknown[] = []
+    const scope: {
+      onmessage: ((event: MessageEvent<{
+        url: string
+        body: FileUploadBody
+        headers: Readonly<Record<string, string>>
+      }>) => void) | null
+      postMessage(message: unknown): void
+    } = { onmessage: null, postMessage: (message: unknown) => { posted.push(message) } }
+    const xhr = {
+      upload: { onprogress: null as ((event: ProgressEvent) => void) | null },
+      status: 201,
+      responseText: '{"ok":true}',
+      withCredentials: false,
+      onload: null as ((event: ProgressEvent) => void) | null,
+      onerror: null as ((event: ProgressEvent) => void) | null,
+      open: vi.fn(),
+      setRequestHeader: vi.fn(),
+      send: vi.fn(),
+    }
+    fileUploadWorker(scope, () => xhr)
+    const body = new Blob(['large'])
+    scope.onmessage?.({
+      data: { url: 'https://harness.test/upload', body, headers: { 'content-type': 'application/octet-stream' } },
+    } as never)
+    expect(xhr.open).toHaveBeenCalledWith('POST', 'https://harness.test/upload')
+    expect(xhr.withCredentials).toBe(true)
+    expect(xhr.setRequestHeader).toHaveBeenCalledWith('content-type', 'application/octet-stream')
+    expect(xhr.send).toHaveBeenCalledWith(body)
+
+    xhr.upload.onprogress?.({ loaded: 2, total: 4, lengthComputable: true } as ProgressEvent)
+    xhr.upload.onprogress?.({ loaded: 3, total: 0, lengthComputable: false } as ProgressEvent)
+    xhr.onload?.({} as ProgressEvent)
+    xhr.onerror?.({} as ProgressEvent)
+    expect(posted).toEqual([
+      { kind: 'progress', loaded: 2, total: 4 },
+      { kind: 'progress', loaded: 3 },
+      { kind: 'complete', status: 201, body: '{"ok":true}' },
+      { kind: 'error', message: 'background upload transport failed' },
+    ])
+  })
+
+  it('streams Uint8Array chunks through fetch and reports consumed bytes', async () => {
+    const posted: unknown[] = []
+    const scope = {
+      onmessage: null as ((event: MessageEvent) => void) | null,
+      postMessage: (message: unknown) => { posted.push(message) },
+    }
+    const fetch = vi.fn(async (_url: string, init: RequestInit & { readonly duplex: 'half' }) => {
+      const chunks: number[][] = []
+      for await (const chunk of init.body as ReadableStream<Uint8Array>) chunks.push([...chunk])
+      expect(chunks).toEqual([[1, 2], [3]])
+      expect(init).toMatchObject({
+        method: 'POST',
+        headers: { 'x-test': 'yes' },
+        credentials: 'include',
+        duplex: 'half',
+      })
+      return new Response('stored', { status: 202 })
+    })
+    const body = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(Uint8Array.of(1, 2))
+        controller.enqueue(Uint8Array.of(3))
+        controller.close()
+      },
+    })
+    fileUploadWorker(scope, () => { throw new Error('XHR must not handle streams') }, fetch)
+    scope.onmessage?.({ data: { url: 'https://harness.test/upload', body, headers: { 'x-test': 'yes' } } } as never)
+    await vi.waitFor(() => {
+      expect(posted).toEqual([
+        { kind: 'progress', loaded: 2 },
+        { kind: 'progress', loaded: 3 },
+        { kind: 'complete', status: 202, body: 'stored' },
+      ])
+    })
+  })
+
+  it('propagates cancellation from the fetch body to the source stream', async () => {
+    const posted: unknown[] = []
+    const scope = {
+      onmessage: null as ((event: MessageEvent) => void) | null,
+      postMessage: (message: unknown) => { posted.push(message) },
+    }
+    const cancel = vi.fn()
+    const source = new ReadableStream<Uint8Array>({ cancel })
+    fileUploadWorker(
+      scope,
+      () => { throw new Error('unused') },
+      async (_url, init) => {
+        await (init.body as ReadableStream<Uint8Array>).cancel('fetch stopped')
+        return new Response('cancelled')
+      },
+    )
+    scope.onmessage?.({ data: { url: '/upload', body: source, headers: {} } } as never)
+    await vi.waitFor(() => {
+      expect(cancel).toHaveBeenCalledWith('fetch stopped')
+      expect(posted.at(-1)).toEqual({ kind: 'complete', status: 200, body: 'cancelled' })
+    })
+  })
+
+  it('reports invalid bodies, stream chunks, and fetch failures', async () => {
+    const posted: unknown[] = []
+    const scope = {
+      onmessage: null as ((event: MessageEvent) => void) | null,
+      postMessage: (message: unknown) => { posted.push(message) },
+    }
+    fileUploadWorker(scope, () => { throw new Error('unused') })
+    scope.onmessage?.({ data: { url: '/upload', body: 'bad', headers: {} } } as never)
+    expect(posted).toEqual([{ kind: 'error', message: 'background upload worker received an invalid body' }])
+
+    const badChunk = new ReadableStream({ start(controller) { controller.enqueue('bad'); controller.close() } })
+    fileUploadWorker(
+      scope,
+      () => { throw new Error('unused') },
+      async (_url, init) => {
+        await new Response(init.body).arrayBuffer()
+        return new Response()
+      },
+    )
+    scope.onmessage?.({ data: { url: '/upload', body: badChunk, headers: {} } } as never)
+    await vi.waitFor(() => {
+      expect(posted.at(-1)).toEqual({
+        kind: 'error', message: 'background upload stream produced a non-Uint8Array chunk',
+      })
+    })
+
+    const body = new ReadableStream<Uint8Array>({ start(controller) { controller.close() } })
+    fileUploadWorker(
+      scope,
+      () => { throw new Error('unused') },
+      () => Promise.reject(new Error('offline')),
+    )
+    scope.onmessage?.({ data: { url: '/upload', body, headers: {} } } as never)
+    await vi.waitFor(() => {
+      expect(posted.at(-1)).toEqual({ kind: 'error', message: 'offline' })
+    })
+
+    const failedSource = new ReadableStream<Uint8Array>({
+      start(controller) { controller.error('source failed') },
+    })
+    fileUploadWorker(
+      scope,
+      () => { throw new Error('unused') },
+      async (_url, init) => {
+        await (init.body as ReadableStream<Uint8Array>).getReader().read()
+        return new Response()
+      },
+    )
+    scope.onmessage?.({ data: { url: '/upload', body: failedSource, headers: {} } } as never)
+    await vi.waitFor(() => {
+      expect(posted.at(-1)).toEqual({ kind: 'error', message: 'source failed' })
+    })
+  })
+
+  it('uses Worker globals when the emitted body supplies no test seams', async () => {
+    const posted: unknown[] = []
+    const scope = {
+      onmessage: null as ((event: MessageEvent) => void) | null,
+      postMessage: (message: unknown) => { posted.push(message) },
+    }
+    const xhr = {
+      upload: { onprogress: null },
+      status: 204,
+      responseText: '',
+      withCredentials: false,
+      onload: null,
+      onerror: null,
+      open: vi.fn(),
+      setRequestHeader: vi.fn(),
+      send: vi.fn(),
+    }
+    vi.stubGlobal('self', scope)
+    vi.stubGlobal('XMLHttpRequest', vi.fn(function () { return xhr }))
+    fileUploadWorker()
+    scope.onmessage?.({ data: { url: '/upload', body: new Blob(), headers: {} } } as MessageEvent)
+    expect(xhr.send).toHaveBeenCalledOnce()
+
+    const fetch = vi.fn(async (_url: string, init: RequestInit) => {
+      await new Response(init.body).arrayBuffer()
+      return new Response(null, { status: 204 })
+    })
+    vi.stubGlobal('fetch', fetch)
+    fileUploadWorker()
+    const stream = new ReadableStream<Uint8Array>({ start(controller) { controller.close() } })
+    scope.onmessage?.({ data: { url: '/stream', body: stream, headers: {} } } as MessageEvent)
+    await vi.waitFor(() => {
+      expect(fetch).toHaveBeenCalledOnce()
+      expect(posted.at(-1)).toEqual({ kind: 'complete', status: 204, body: '' })
+    })
+  })
+})
+
+describe('file upload service', () => {
+  it('uses a page-owned Host fetch for Blob and ReadableStream bodies', async () => {
+    vi.stubGlobal('location', { origin: 'https://preview.test' })
+    const fetch = vi.fn((_url: URL, _init?: RequestInit) =>
+      Promise.resolve(new Response('accepted', { status: 202 })))
+    ;(globalThis as UploadGlobal).__DSH_FILE_UPLOAD__ = { fetch }
+    const ctx = new Context()
+    const fiber = ctx.plugin(FileUploadRuntime)
+    await fiber
+    const blob = new Blob(['opaque'])
+    const signal = new AbortController().signal
+    await expect((ctx.fileUpload as FileUploadRuntime).post({
+      path: '/api/upload', body: blob, headers: { 'x-test': 'yes' }, signal,
+    })).resolves.toEqual({ status: 202, body: 'accepted' })
+    expect(fetch).toHaveBeenLastCalledWith(new URL('https://preview.test/api/upload'), {
+      method: 'POST', headers: { 'x-test': 'yes' }, body: blob, signal,
+    })
+
+    const stream = new ReadableStream<Uint8Array>({ start(controller) { controller.close() } })
+    await (ctx.fileUpload as FileUploadRuntime).post({ path: '/stream', body: stream })
+    expect(fetch).toHaveBeenLastCalledWith(new URL('https://preview.test/stream'), {
+      method: 'POST', body: stream, duplex: 'half',
+    })
+    await fiber.dispose()
+  })
+
+  it('mounts through the plugin entry and resolves non-browser URLs', async () => {
+    vi.stubGlobal('location', { origin: 'null' })
+    const fetch = vi.fn(() => Promise.resolve(new Response(null, { status: 204 })))
+    ;(globalThis as UploadGlobal).__DSH_FILE_UPLOAD__ = { fetch }
+    const ctx = new Context()
+    const fiber = ctx.plugin({ apply })
+    await fiber
+    const body = new Blob()
+    await (ctx.fileUpload as FileUploadRuntime).post({ path: '/fallback', body })
+    expect(fetch).toHaveBeenCalledWith(new URL('http://dsh.internal/fallback'), {
+      method: 'POST', body,
+    })
+    await fiber.dispose()
+  })
+
+  it('fails loud when a served browser has no Worker implementation', async () => {
+    vi.stubGlobal('Worker', undefined)
+    const ctx = new Context()
+    const fiber = ctx.plugin(FileUploadRuntime)
+    await fiber
+    await expect((ctx.fileUpload as FileUploadRuntime).post({ path: '/upload', body: new Blob() }))
+      .rejects.toThrow('background upload requires Web Worker support')
+    await fiber.dispose()
+  })
+
+  it('forwards progress and completion from a dedicated Worker and then terminates it', async () => {
+    const created = vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:worker')
+    const revoked = vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {})
+    class FakeWorker {
+      static last: FakeWorker | undefined
+      onmessage: ((event: MessageEvent) => void) | null = null
+      onerror: ((event: ErrorEvent) => void) | null = null
+      readonly postMessage = vi.fn()
+      readonly terminate = vi.fn()
+      constructor(readonly url: string, readonly options: WorkerOptions) { FakeWorker.last = this }
+    }
+    vi.stubGlobal('Worker', FakeWorker)
+    vi.stubGlobal('location', { origin: 'https://harness.test' })
+    const ctx = new Context()
+    const fiber = ctx.plugin(FileUploadRuntime)
+    await fiber
+    const progress = vi.fn()
+    const blob = new Blob(['bytes'])
+    const pending = (ctx.fileUpload as FileUploadRuntime).post({ path: '/api/upload', body: blob, onProgress: progress })
+    const worker = FakeWorker.last
+    if (worker === undefined) throw new Error('worker missing')
+    expect(created).toHaveBeenCalledOnce()
+    expect(revoked).toHaveBeenCalledWith('blob:worker')
+    expect(worker.postMessage).toHaveBeenCalledWith({
+      url: 'https://harness.test/api/upload', body: blob, headers: {},
+    })
+    worker.onmessage?.({ data: { kind: 'progress', loaded: 4, total: 5 } } as MessageEvent)
+    worker.onmessage?.({ data: { kind: 'progress', loaded: 6 } } as MessageEvent)
+    worker.onmessage?.({ data: { kind: 'complete', status: 200, body: 'done' } } as MessageEvent)
+    worker.onmessage?.({ data: { kind: 'complete', status: 500, body: 'late' } } as MessageEvent)
+    await expect(pending).resolves.toEqual({ status: 200, body: 'done' })
+    expect(progress.mock.calls).toEqual([
+      [{ loaded: 4, total: 5 }],
+      [{ loaded: 6 }],
+    ])
+    expect(worker.terminate).toHaveBeenCalledOnce()
+    await fiber.dispose()
+  })
+
+  it('transfers stream ownership to the dedicated Worker', async () => {
+    vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:worker')
+    vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {})
+    class FakeWorker {
+      static last: FakeWorker | undefined
+      onmessage: ((event: MessageEvent) => void) | null = null
+      onerror: ((event: ErrorEvent) => void) | null = null
+      readonly postMessage = vi.fn()
+      readonly terminate = vi.fn()
+      constructor() { FakeWorker.last = this }
+    }
+    vi.stubGlobal('Worker', FakeWorker)
+    const ctx = new Context()
+    const fiber = ctx.plugin(FileUploadRuntime)
+    await fiber
+    const stream = new ReadableStream<Uint8Array>({ start(controller) { controller.close() } })
+    const pending = (ctx.fileUpload as FileUploadRuntime).post({ path: '/stream', body: stream })
+    const worker = FakeWorker.last
+    if (worker === undefined) throw new Error('worker missing')
+    expect(worker.postMessage).toHaveBeenCalledWith(expect.objectContaining({ body: stream }), [stream])
+    worker.onmessage?.({ data: { kind: 'complete', status: 200, body: 'done' } } as MessageEvent)
+    await expect(pending).resolves.toEqual({ status: 200, body: 'done' })
+    await fiber.dispose()
+  })
+
+  it('rejects worker messages, worker errors, and caller cancellation', async () => {
+    vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:worker')
+    vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {})
+    class FakeWorker {
+      static all: FakeWorker[] = []
+      onmessage: ((event: MessageEvent) => void) | null = null
+      onerror: ((event: ErrorEvent) => void) | null = null
+      readonly postMessage = vi.fn()
+      readonly terminate = vi.fn()
+      constructor() { FakeWorker.all.push(this) }
+    }
+    vi.stubGlobal('Worker', FakeWorker)
+    const ctx = new Context()
+    const fiber = ctx.plugin(FileUploadRuntime)
+    await fiber
+
+    const reported = (ctx.fileUpload as FileUploadRuntime).post({ path: '/upload', body: new Blob() })
+    FakeWorker.all[0]?.onmessage?.({ data: { kind: 'error', message: 'network failed' } } as MessageEvent)
+    await expect(reported).rejects.toThrow('network failed')
+
+    const errored = (ctx.fileUpload as FileUploadRuntime).post({ path: '/upload', body: new Blob() })
+    FakeWorker.all[1]?.onerror?.({ message: 'worker crashed' } as ErrorEvent)
+    await expect(errored).rejects.toThrow('worker crashed')
+
+    const unnamed = (ctx.fileUpload as FileUploadRuntime).post({ path: '/upload', body: new Blob() })
+    FakeWorker.all[2]?.onerror?.({ message: '' } as ErrorEvent)
+    await expect(unnamed).rejects.toThrow('background upload worker failed')
+
+    const controller = new AbortController()
+    const aborted = (ctx.fileUpload as FileUploadRuntime).post({ path: '/upload', body: new Blob(), signal: controller.signal })
+    controller.abort()
+    await expect(aborted).rejects.toMatchObject({ name: 'AbortError' })
+    expect(FakeWorker.all[3]?.terminate).toHaveBeenCalledOnce()
+
+    const already = new AbortController()
+    already.abort()
+    await expect((ctx.fileUpload as FileUploadRuntime).post({ path: '/upload', body: new Blob(), signal: already.signal }))
+      .rejects.toMatchObject({ name: 'AbortError' })
+    expect(FakeWorker.all[4]?.postMessage).not.toHaveBeenCalled()
+    await fiber.dispose()
+  })
+})
+
+describe('Session-addressed file upload', () => {
+  const SESSION_ID = 's1' as SessionId
+
+  async function scopedService(options: {
+    readonly remote?: ReturnType<typeof vi.fn>
+  } = {}) {
+    const ctx = new Context()
+    const remote = options.remote ?? vi.fn(() => Promise.resolve({
+      ok: true,
+      value: {
+        receiptId: 'remote-receipt',
+        file: { attachmentId: 'remote-file', name: 'file', bytes: 3 },
+      },
+    }))
+    ctx.provide('remote', { fileUploads: { upload: remote } } as never)
+    const fiber = ctx.plugin(FileUploadRuntime)
+    await fiber
+    return { ctx, fiber, remote, service: ctx.fileUpload }
+  }
+
+  it('assembles the scoped streaming request and parses progress and receipt fields', async () => {
+    vi.stubGlobal('location', { origin: 'https://preview.test' })
+    const progress = vi.fn()
+    const fetch = vi.fn((_url: URL, init: RequestInit) => {
+      expect(init.body).toBeInstanceOf(Blob)
+      progress({ loaded: 2, total: 4 })
+      return Promise.resolve(new Response(JSON.stringify({
+        ok: true,
+        value: {
+          receiptId: 'receipt-1',
+          file: { attachmentId: 'file-1', name: 'notes & refs.pdf', bytes: 4 },
+        },
+      }), { status: 200 }))
+    })
+    ;(globalThis as UploadGlobal).__DSH_FILE_UPLOAD__ = { fetch }
+    const { fiber, service } = await scopedService()
+    const signal = new AbortController().signal
+    const file = new Blob(['data'])
+
+    await expect(service.upload(SESSION_ID, file, 'notes & refs.pdf', signal, progress)).resolves.toEqual({
+      ok: true,
+      value: {
+        receiptId: 'receipt-1',
+        file: { attachmentId: 'file-1', name: 'notes & refs.pdf', bytes: 4 },
+      },
+    })
+    expect(fetch).toHaveBeenCalledWith(
+      new URL('https://preview.test/api/session/uploadFileBinary?sessionId=s1&name=notes+%26+refs.pdf'),
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'content-type': 'application/octet-stream' },
+        body: file,
+        signal,
+      }),
+    )
+    await fiber.dispose()
+  })
+
+  it('uses the direct Remote fallback for exact bytes', async () => {
+    const remote = vi.fn(() => Promise.resolve({
+      ok: true,
+      value: {
+        receiptId: 'remote-receipt',
+        file: { attachmentId: 'remote-file', name: 'bytes.bin', bytes: 3 },
+      },
+    }))
+    const { fiber, service } = await scopedService({ remote })
+    await expect(service.upload(SESSION_ID, Uint8Array.of(0, 0, 0), 'bytes.bin'))
+      .resolves.toMatchObject({ ok: true })
+    await expect(service.upload(SESSION_ID, Uint8Array.of(1)))
+      .resolves.toMatchObject({ ok: true })
+    expect(remote.mock.calls).toEqual([
+      [SESSION_ID, { data: 'AAAA', name: 'bytes.bin' }, undefined],
+      [SESSION_ID, { data: 'AQ==' }, undefined],
+    ])
+    await fiber.dispose()
+  })
+
+  it('rejects malformed background results', async () => {
+    vi.stubGlobal('location', { origin: 'https://preview.test' })
+    ;(globalThis as UploadGlobal).__DSH_FILE_UPLOAD__ = {
+      fetch: () => Promise.resolve(new Response(null, { status: 413 })),
+    }
+    const rejected = await scopedService()
+    await expect(rejected.service.upload(SESSION_ID, new Blob()))
+      .rejects.toThrow('file upload transport failed with HTTP 413')
+    await rejected.fiber.dispose()
+
+    const bodies: unknown[] = [
+      null,
+      { ok: 'yes' },
+      { ok: false, error: null },
+      { ok: false, error: { code: 1, message: 'denied', details: {} } },
+      { ok: false, error: { code: 'denied', message: 1, details: {} } },
+      { ok: false, error: { code: 'denied', message: 'denied', details: null } },
+      { ok: true, value: null },
+      { ok: true, value: { receiptId: 'r', file: { attachmentId: 'a', name: 'x', bytes: -1 } } },
+    ]
+    for (const body of bodies) {
+      ;(globalThis as UploadGlobal).__DSH_FILE_UPLOAD__ = {
+        fetch: () => Promise.resolve(new Response(JSON.stringify(body), { status: 200 })),
+      }
+      const malformed = await scopedService()
+      await expect(malformed.service.upload(SESSION_ID, new Blob()))
+        .rejects.toThrow(/file upload transport returned an invalid/)
+      await malformed.fiber.dispose()
+    }
+
+    ;(globalThis as UploadGlobal).__DSH_FILE_UPLOAD__ = {
+      fetch: () => Promise.resolve(new Response(JSON.stringify({
+        ok: false,
+        error: { code: 'session/attachment-invalid', message: 'denied', details: { reason: 'NOPE' } },
+      }), { status: 200 })),
+    }
+    const failed = await scopedService()
+    await expect(failed.service.upload(SESSION_ID, new Blob())).resolves.toMatchObject({
+      ok: false,
+      error: {
+        code: 'session/attachment-invalid',
+        message: 'denied',
+        details: { reason: 'NOPE' },
+      },
+    })
+    await failed.fiber.dispose()
+  })
+})

packages/client/locale/README.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 packages/client/locale/README.md
+README.md: 56a9cff9c3ec18dcc395378fcd1691207c022284
+README.zh.md: 1b7a7b7de48843961f3cbac3f4ee99cff641d212

packages/client/locale/README.md

@@ -0,0 +1,142 @@
+---
+description: "Localization for the web GUI: the zh/en preference, browser-derived fallback, typed namespace dictionaries, and the framework translation seat, for users and plugin authors."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-locale
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `dsh-client-locale` to switch the web GUI between the shipped English and Chinese locales or languages added by client plugins. User selections take effect immediately; loopback pages persist them in `$DSH_HOME/settings.yaml`, while non-loopback pages keep them only for the current process. New browsers use the first supported language requested by the browser until an allowed stored preference arrives. Plugin authors add typed namespace dictionaries and translate through the public locale API; slot-rendered copy updates without a reload.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Use it wherever the web GUI needs a language switch or translated copy: the shipped settings row covers users, and plugin authors register their own dictionaries. Nothing needs configuration to mount — the package activates with the client tree.
+
+### Choosing a language
+
+Open Settings → General and select a registered language. The active locale is applied immediately: the UI copy switches, `<html lang>` points at the external id or built-in document tag, and the choice is written to the durable settings section. A browser without an explicit Host preference selects the first registered language that matches `navigator` by full tag and then primary subtag, falling back to English. A stored external locale waits for its definition to register instead of becoming active while unavailable.
+
+### Registering a dictionary
+
+Call `ctx.locale.register(ns, { zh, en })` with a namespace merged into `LocaleNamespaceMap`; the compiler checks every key against the namespace's typed key union and requires both shipped locales. Consumers translate through `ctx.locale.bind(ns)` or the framework-injected `t` seat. A dictionary registered after the UI is already mounted is picked up without a remount.
+
+### Registering a language pack
+
+An external client plugin registers the language definition and each translated namespace as owned effects; definitions and dictionaries may register in either order:
+
+```js
+export const inject = ['locale']
+
+export function apply(ctx) {
+  ctx.effect(
+    () => ctx.locale.addLanguage({ id: 'ja', label: '日本語', fallback: 'en' }),
+    'my-locale: language',
+  )
+  ctx.effect(
+    () => ctx.locale.register('common', 'ja', {
+      cancel: 'キャンセル',
+      close: '閉じる',
+    }),
+    'my-locale: common dictionary',
+  )
+}
+```
+
+An external id is a non-empty ASCII BCP 47-style tag. Its fallback must already be registered, and the chain must terminate at `en`; unknown targets, duplicate ids, and cycles fail at registration. Lookup walks the fallback chain in the requested namespace, repeats it in `common`, then displays the key. Unloading a definition removes it from the selector and returns an active selection to the available browser/default locale.
+
+### What the Host half does
+
+The Host persists the preference through the settings service on loopback pages. The Client deliberately withholds that settings scope on non-loopback pages, so their locale selection remains process-local even though Connection authenticates every API method.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains how the locale service is built; observable behavior is covered in [Use this package](#use-this-package).
+
+### Design concept
+
+One `LocaleRuntime` owns the preference and the dictionary registry, and is itself the slot system's `LocaleFace`: `getSnapshot`/`subscribe` back the framework-injected `t` seat through `ctx.slots.installLocale`. The immutable snapshot carries the active locale, the selectable locales, and a monotonic revision; dictionary registration and locale switches both advance the revision, but only a switch emits the `locale/change` event. Product-authored Client UI text must enter through these typed dictionaries or an already-localized primitive prop; `verify-client-ui-i18n` enforces that source ownership ([decision](../../../.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md)).
+
+### Preference resolution
+
+The provisional locale comes from the browser (`navigator.languages` matched by full tag and then primary subtag, English as the fallback), standing in until the allowed Host-backed settings scope delivers its stored preference. The Host read runs after plugin activation so an unavailable or withheld settings scope cannot block the page, and the result replaces the provisional value live. A stored external locale waits for its definition to register. `setLocale` is the only write entry; it persists even when the id already matches the active locale, because the active value may be provisional and must survive a different browser sharing the same home.
+
+### Dictionary lookup
+
+The typed object form requires complete dictionaries for both built-in locales. The per-locale form lets language packs register each namespace independently. For each key, lookup walks the active language's declared fallback chain in the requested namespace, repeats that chain in `common`, then displays the key itself. Bound translate functions retain stable identity per namespace so they can ride inject surfaces without breaking memoization.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/client/index.ts`](src/client/index.ts) | `LocaleRuntime`, dictionary registry, Language row registration, `locale/change` event |
+| [`src/index.ts`](src/index.ts) | Node half: registers the `locale` settings namespace |
+| [`src/locale-settings.ts`](src/locale-settings.ts) | The durable schema for `locale.preference` |
+| [`src/locales/`](src/locales/) | The shipped `zh`/`en` dictionaries |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these when the locale contract is not enough: the slot face it implements, the settings surface it rides, and the persistence decision behind the preference.
+
+- [Client slot system](../ui-slots/README.md) — the slot model and the `LocaleFace` seat this package implements.
+- [Host-backed preferences decision](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md) — why the preference persists in Host settings instead of the browser.
+- [Settings group map](../../settings/README.md) — the settings service that stores the preference.
+- [Client group map](../README.md) — the browser half this package belongs to.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the locale service is a browser-side UI plugin layer that registers nothing model-facing.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define where localization is incomplete or frozen at registration time. They are current package constraints, not a task backlog.
+
+- **Registry-held text reads its translation once** — copy captured at registration time outside the slot render path (e.g. the `/model` command description in the command registry) keeps the language it was registered under until re-registration; slot-rendered copy follows switches live.
+- **Language packs own language-specific behavior** — the registry supplies selection, persistence, browser matching, key fallback, and `<html lang>`; it does not add plural rules or bidirectional layout.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. The locale catalog and dictionaries have no independent runtime source to compare against; registration disposal, preference resolution, and fallback lookup are asserted by behavior specs.

packages/client/locale/README.zh.md

@@ -0,0 +1,142 @@
+---
+description: "面向用户与插件作者的 web GUI 本地化说明：zh/en 偏好、浏览器派生回退、类型化命名空间字典与框架翻译席位。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-locale
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `dsh-client-locale` 可在 web GUI 中切换内置的英文和中文 locale，或 client 插件添加的语言。用户选择会立即生效；loopback 页面把选择持久化到 `$DSH_HOME/settings.yaml`，非 loopback 页面则只为当前进程保留选择。全新浏览器会使用浏览器请求的第一个受支持语言，直到允许读取的已存储偏好到达。插件作者可添加类型化命名空间字典，并通过公开 locale API 翻译；经 slot 渲染的文案无需重新加载即可随语言切换更新。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与暂缓事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+只要 web GUI 需要语言切换或翻译文案就使用它：已发布的设置行覆盖用户侧，插件作者则注册自己的字典。挂载无需任何配置——本包随客户端树一起激活。
+
+### 选择语言
+
+打开“设置 → 常规”并选择一种已注册语言。生效中的 locale 会立即应用：UI 文案切换、`<html lang>` 指向外部 id 或内置语言的文档标签，选择写入持久设置分区。没有显式 Host 偏好的浏览器会按完整标签、再按主语言子标签选择 `navigator` 请求的第一个已注册语言，无法匹配时回退到英文。已存储的外部 locale 会等待其定义注册，不会在不可用时生效。
+
+### 注册字典
+
+用已合并进 `LocaleNamespaceMap` 的命名空间调用 `ctx.locale.register(ns, { zh, en })`；编译器会对照该命名空间的类型化键并集检查每个键，并要求两个内置 locale 齐全。消费方通过 `ctx.locale.bind(ns)` 或框架注入的 `t` 席位翻译。UI 已挂载后再注册的字典无需重新挂载即可生效。
+
+### 注册语言包
+
+外部 client 插件把语言定义和每个已翻译命名空间注册为自身拥有的 effect；定义与字典可以按任意顺序注册：
+
+```js
+export const inject = ['locale']
+
+export function apply(ctx) {
+  ctx.effect(
+    () => ctx.locale.addLanguage({ id: 'ja', label: '日本語', fallback: 'en' }),
+    'my-locale: language',
+  )
+  ctx.effect(
+    () => ctx.locale.register('common', 'ja', {
+      cancel: 'キャンセル',
+      close: '閉じる',
+    }),
+    'my-locale: common dictionary',
+  )
+}
+```
+
+外部 id 必须是非空的 ASCII BCP 47 风格标签。它的 fallback 必须已经注册，且整条链必须终止于 `en`；未知目标、重复 id 与循环会在注册时失败。查找时先在请求命名空间内遍历生效语言的 fallback 链，再在 `common` 中遍历该链，最后显示键本身。卸载语言定义会将其从选择器移除，并让生效中的选择回落到可用的浏览器语言或默认语言。
+
+### Host 半侧做什么
+
+Host 通过 settings 服务为 loopback 页面持久化偏好。Client 会刻意拒绝非 loopback 页面使用该 settings scope，因此即使 Connection 认证所有 API 方法，它们的 locale 选择仍只存在于进程内。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释 locale 服务的构建方式；可观察行为已在[使用本包](#use-this-package)中说明。
+
+### 设计理念
+
+一个 `LocaleRuntime` 同时拥有偏好与字典注册表，并且自身就是 slot 系统的 `LocaleFace`：`getSnapshot`／`subscribe` 通过 `ctx.slots.installLocale` 支撑框架注入的 `t` 席位。不可变快照携带生效中的 locale、可选择的 locale 列表与单调 revision；字典注册与 locale 切换都会推进 revision，但只有切换会发出 `locale/change` 事件。产品编写的 Client UI 文本必须来自这些带类型的字典，或来自已经本地化的 primitive prop；`verify-client-ui-i18n` 强制执行该源码归属（见[决策](../../../.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.zh.md)）。
+
+### 偏好解析
+
+临时 locale 来自浏览器（`navigator.languages` 先按完整标签、再按主语言子标签匹配，以英文作为回退），在允许使用的 Host-backed settings scope 送达其存储偏好之前生效。Host 读取在插件激活后运行，因此 settings scope 不可用或被拒绝都不会阻塞页面，结果会实时替换临时值。已存储的外部 locale 会等待其定义注册。`setLocale` 是唯一写入入口；即使 id 已与生效中的 locale 匹配也会持久化，因为生效中的值可能是临时的，必须能供共享同一 home 的其他浏览器继续使��。
+
+### 字典查找
+
+带类型的对象形式要求两个内置 locale 都有完整字典；逐 locale 形式允许语言包独立注册每个命名空间。逐键查找会先在请求命名空间中沿生效语言声明的 fallback 链查找，再在 `common` 中重复该链，最后显示键本身。绑定的翻译函数按命名空间保持稳定身份，因此可通过 inject 机制传递，且不会破坏 memoization。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/client/index.ts`](src/client/index.ts) | `LocaleRuntime`、字典注册表、Language 行注册、`locale/change` 事件 |
+| [`src/index.ts`](src/index.ts) | node 半侧：注册 `locale` 设置命名空间 |
+| [`src/locale-settings.ts`](src/locale-settings.ts) | `locale.preference` 的持久 schema |
+| [`src/locales/`](src/locales/) | 内置的 `zh`／`en` 字典 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当仅阅读 locale 约定不足以解答问题时，请继续阅读以下页面，了解它实现的 slot 接口、依托的设置机制，以及偏好背后的持久化决策。
+
+- [客户端 slot 系统](../ui-slots/README.zh.md)——本包实现的 slot 模型与 `LocaleFace` 席位。
+- [Host 支撑偏好决策](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.zh.md)——偏好为何持久化在 Host 设置中而非浏览器里。
+- [设置组地图](../../settings/README.zh.md)——存储该偏好的设置服务。
+- [客户端组地图](../README.zh.md)——本包所属的浏览器半侧。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无。locale 服务属于浏览器侧 UI 插件层，不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明本地化在哪些地方不完整，或在注册时被冻结。它们是当前包约束，不是待办事项清单。
+
+- **注册表持有的文本只读取一次翻译**——在 slot 渲染路径之外于注册时捕获的文案（例如 command 注册表中的 `/model` 命令描述）在重新注册前保持注册时的语言；slot 渲染的文案随切换实时更新。
+- **语言包负责语言特有行为**——注册表提供选择、持久化、浏览器匹配、逐键回退和 `<html lang>`；它不增加复数规则或双向布局。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变式：** 不发布伴生入口。locale catalog 与字典没有可供交叉核对的独立运行时来源；注册释放、偏好解析和 fallback 查找由行为测试覆盖。

packages/client/locale/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@deepseek-ai/dsh-client-locale",
+  "description": "Locale plugin: Host-backed preference, extensible language catalog, browser fallback, and typed built-in dictionaries",
+  "version": "0.1.6-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/locale"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-api-remotes": "workspace:^",
+    "@deepseek-ai/dsh-client-store": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-settings": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-settings": "workspace:^"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "workspace:^"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}