Merge fix/web-agent-runtime-context into fix/web-gui-feedback-loop

packages/host/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/host/README.md
+README.md: 391adb7009a01d1ec95c8dcb809e8a2065aa0b31
+README.zh.md: 7fc730ed9ec3a067589b277733eb5bb2c42f8b4e

packages/host/README.md

@@ -0,0 +1,16 @@
+# host/ — web-GUI host half
+
+English | [中文](README.zh.md)
+
+The host side of the dsh web GUI: the API gateway every client shape shares, and the plain HTTP server it rides on. The browser side lives in [`client/`](../client/README.md); the composed application is [`apps/cli`](../../apps/cli/config/base.cordis.yml) serving [`apps/web`](../../apps/web/). All **product** packages.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `apiproxy/` | The shared API gateway: the zero-Node TS wire contract (`src/api/`), the fetch carrier pair (`toFetchHandler` host-side, `AbstractApiClient` client-side), and the host implementation over `ctx.agents`/`ctx.workspace` | `ctx.apiProxy` |
+| `webserver/` | Plain HTTP route-registration carrier: `node:http` server listening on activation; routes register as named `exact`/`prefix` handlers | `ctx.httpServer` |
+| `directory-picker/` | Workspace-directory picking seam: discriminated `native`/`browse` capability the gateway's picker RPCs delegate to | `ctx.directoryPicker` |
+| `directory-picker-native/` | Dual-face native interaction: OS-chooser backend (osascript / PowerShell / Zenity+KDialog, host-display only) + the browser half filling ui-workspace's directory-flow slots | (registers `ctx.directoryPicker`) |
+| `directory-picker-browse/` | Dual-face browse interaction: listing/creation primitives over Node stdlib (remote-capable) + the browser half rendering the in-app Select Workspace Directory dialog | (registers `ctx.directoryPicker`) |
+| `directory-picker-auto/` | Adaptive chooser: resolves the host's situation once at boot (bind host, SSH, display) and mounts the matching dual-face backend as an in-memory Loader entry | (mounts a backend row) |
+
+`apiproxy` is transport-agnostic by design — it registers no routes; carriers wrap `ctx.apiProxy` themselves. The HTTP carrier route (with its `/api` browser-trust fence) is mounted by [`client/connection`](../client/connection/README.md)'s node half, which is why that package lives in the client group: it owns both ends of the wire.

packages/host/README.zh.md

@@ -0,0 +1,16 @@
+# host/ — web GUI 宿主半侧
+
+[English](README.md) | 中文
+
+dsh web GUI 的宿主侧：所有客户端形态共用的 API 网关，以及承载它的纯 HTTP 服务器。浏览器侧位于 [`client/`](../client/README.md)；组合后的应用是 [`apps/cli`](../../apps/cli/config/base.cordis.yml)，它负责服务 [`apps/web`](../../apps/web/)。全部为**产品**包。
+
+| 包 | 角色 | ctx 键 |
+|---|---|---|
+| `apiproxy/` | 共享 API 网关：零 Node 依赖的 TS 协议契约（`src/api/`）、fetch 载体对（宿主侧 `toFetchHandler`、客户端侧 `AbstractApiClient`），以及基于 `ctx.agents`／`ctx.workspace` 的宿主实现 | `ctx.apiProxy` |
+| `webserver/` | 纯 HTTP 路由注册载体：激活即监听的 `node:http` 服务器；路由以命名的 `exact`／`prefix` 处理器注册 | `ctx.httpServer` |
+| `directory-picker/` | 工作区目录选择 seam：网关的 picker RPC 委托的可辨识 `native`／`browse` 能力 | `ctx.directoryPicker` |
+| `directory-picker-native/` | 双面原生交互：OS 选择器后端（osascript／PowerShell／Zenity+KDialog，仅宿主屏幕可用）+ 填入 ui-workspace 目录流 slot 的 browser half | （注册 `ctx.directoryPicker`） |
+| `directory-picker-browse/` | 双面浏览交互：基于 Node 标准库的列举／创建原语（可远程）+ 渲染应用内选择工作区目录对话框的 browser half | （注册 `ctx.directoryPicker`） |
+| `directory-picker-auto/` | 自适应选择器：启动时一次性判定宿主处境（绑定宿主、SSH、显示），并把匹配的双面后端挂载为内存中的 Loader 条目 | （挂载一个后端行） |
+
+`apiproxy` 在设计上与传输方式无关——它不注册任何路由；载体自行包装 `ctx.apiProxy`。HTTP 载体路由（连同其 `/api` 浏览器信任栅栏）由 [`client/connection`](../client/connection/README.md) 的 node 半侧挂载，这正是该包住在 client 组的原因：它拥有这条线的两端。

packages/host/apiproxy/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
-README.md: d6db9a9541b0727b61dbe501f7234564ffef139e
-README.zh.md: 4175c8fdb98aad2882718a2c95cd9e45825d787d
+README.md: 3c5a83a468b0cf9e596b8b13fafe40c409576fc5
+README.zh.md: f8533564575bf6b716f3fa7241ce47b8d4dd435f

packages/host/apiproxy/README.md

@@ -2,25 +2,39 @@
 
 English | [中文](README.zh.md)
 
-The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers (HTTP today, IPC later) wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`apps/cli/cordis.yml`](../../../apps/cli/cordis.yml).
+The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers (HTTP today, IPC later) wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`apps/cli/config/base.cordis.yml`](../../../apps/cli/config/base.cordis.yml).
 
 ## Contract layer (`/api`)
 
-Wire messages form a four-quadrant discriminated union — who initiates × request/response — decoupled from the physical channel: `ClientRequest` (POST `/api/<method>` body), `ServerResponse` (that POST's response body), `ServerRequest` (SSE frame), `ClientResponse` (POST `/api/respond` body). Responses always echo the matching request's `rpcId` and never mint a new one. Method parameter/return structures live only in the domain interface signatures (`SessionsApi`, `HostApi`, `EventsApi`); `RpcMethodMap` registers the methods and every other position derives via `RequestPayload<K>`/`ResponseValue<K>`. Zod schemas anchor `satisfies z.ZodType<Wire<T>>` and parse at two levels: envelope first, business payload second, dispatched per method. Business errors ride `RpcResult`'s error branch (`RpcErrorDetailsMap` closes the code set); HTTP status expresses only the carrier.
+Wire messages form a four-quadrant discriminated union — who initiates × request/response — decoupled from the physical channel: `ClientRequest` (POST `/api/<method>` body), `ServerResponse` (that POST's response body), `ServerRequest` (SSE frame), `ClientResponse` (POST `/api/respond` body). Responses always echo the matching request's `rpcId` and never mint a new one. Method parameter/return structures live only in the domain interface signatures (`SessionsApi`, `HostApi`, `EventsApi`); `RpcMethodMap` registers the methods and every other position derives via `RequestPayload<K>`/`ResponseValue<K>`. Zod schemas anchor `satisfies z.ZodType<Wire<T>>` and parse at two levels: envelope first, business payload second, dispatched per method. Business errors ride `RpcResult`'s error branch (`RpcErrorDetailsMap` closes the code set); HTTP status expresses only the carrier. Every `/api` POST must declare the `application/json` media type — anything else is refused with 415 before dispatch, so cross-site "simple" requests (which browsers send without a CORS preflight) can never execute a side-effectful method blind.
 
 The layering/protocol decisions are recorded in the [GUI layering and RPC protocol RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md); the browser-side consumption architecture in the [web client architecture RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md).
 
-The mux stream projects the latest log-backed title as a validated `session/title` control frame after each attached-session subscription baseline and immediately after the corresponding live raw title event. This projection does not add titles to `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs.
+`session.history` pages on append-origin message boundaries: `maxMessages` counts `user/message`, `assistant/message`, and `steering/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it.
+
+`session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
+
+Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. `session.rename` accepts an explicit user title (resuming a cold session first), delegating to `ctx.sessionTitle.rename` — the accepted `session/title` event pins the title against automatic regeneration — and returns the normalized title plus its event seq so a client settles its `title` projection cell ahead of the push frame; a title that normalizes to empty returns `title-invalid`.
+
+`session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged provider/model/reasoning target, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) owns the boundary rationale.
 
 Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target with provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`.
 
-Workspace and Session lists are separate reconnect baselines. `workspace.create` creates a unique name or adopts an existing directory, `workspace.delete` removes only the Workspace registration, `session.create` accepts an optional preallocated Session id, and `host/workspace-changed`, `host/workspace-removed`, plus `host/session-added` carry committed increments in either arrival order. Registration deletion preserves the directory and session logs; its Sessions remain in `session.list` and become Ungrouped. `SessionSummary.blank` and the `host/session-added` frame carry the derived zero-events bit: clients hide blank sessions and reuse them per workspace, flip blank on the first `host/session-status(running:true)`, and treat `session.list` as the reconnect authority; cold summaries are never blank because lazy persistence keeps never-appended sessions out of `list()`.
+Pending queued input is a live control-plane contract, not session history. The gateway mirrors queued `InboxItem` occurrences from `agent/inbox/*` and broadcasts authoritative `session/queue` snapshots on every queued change and reconnect; pending steering stays outside this Web projection. `session.updateQueue` addresses one `InboxItemId`: edit replaces pending content and remove discards it. `session.cancel` aborts only the active turn and preserves pending inbox work; after cancellation reaches quiescence and the closing turn flushes, AgentLoop claims the next waking occurrence in FIFO order. The browser never resends or promotes that occurrence. A driver claim wins races by retiring the address before admission; a later operation returns `queue-item-not-found`. Queue operations query only an attached Agent and never resume a cold session because process-local inbox identities do not survive restart or disposal. The client never infers retirement from turn or status events.
 
-`host.pickDirectory` opens one native directory picker and returns its selected path, or `null` when the user cancels. Its host implementation invokes platform tools without a shell: `osascript` on macOS, an STA PowerShell `FolderBrowserDialog` on Windows, and Zenity with a KDialog fallback on Linux. The picker function is injectable for tests. This user-paced method is the sole unary call exempt from the default 30-second timeout; caller and connection aborts still propagate to the native process. The browser carrier separately restricts this privileged method to loopback, same-origin requests.
+Workspace and Session lists are separate reconnect baselines. `workspace.create({ name })` creates a uniquely titled directory under the configured root, while `workspace.create({ path })` adopts an existing canonical directory and permits basename-derived titles to repeat. `workspace.delete` removes only the Workspace registration, `session.create` accepts an optional preallocated Session id, and `host/workspace-changed`, `host/workspace-removed`, plus `host/session-added` carry committed increments in either arrival order. `workspace.archiveSession` adds one session to the registry-global archive set and answers the full updated set; `workspace.list` carries that set as the reconnect baseline and `host/archived-sessions-changed` pushes the full snapshot after every durable change. Archiving hides the session from grouping surfaces without touching its log or its workspace account; a session neither live nor persisted fails with `session-not-found`. Registration deletion preserves the directory and session logs; its Sessions remain in `session.list` and become Ungrouped. `SessionSummary.blank` and the `host/session-added` frame carry the derived zero-events bit: clients hide blank sessions and reuse them per workspace, flip blank on the first `host/session-status(running:true)`, and treat `session.list` as the reconnect authority; cold summaries are never blank because lazy persistence keeps never-appended sessions out of `list()`.
 
-`session.history` pages on message boundaries, and its tail page (no `beforeSeq`) carries two session-level extras the page window cannot supply: the in-flight partial's chunk events, and `todos` — the latest `todo/write` whole-list projection over the full log. Older pages omit `todos` because the projection is session-level, not per-page; a tail response that omits it means the whole log holds no `todo/write`, so clients read the absent field as the empty plan rather than as unchanged state.
+`session.search` is a bounded content-search projection over the sessions visible through `session.list`. The gateway asks the optional `ctx.sessionQuery` service for globally ranked current-surface user, assistant, and steering matches, consumes that stream until it has at most 20 visible session/snippet pairs plus one lookahead, and revalidates every hit against the list-derived authorization set before returning it. Provider pages start at 20 hits; when a first-page request rejects that limit, the gateway probes 10, 5, 2, then 1 and retains the learned size for continuation and stale-generation restarts. Returned snippets contain at most 240 Unicode code points, and the response schema independently enforces that bound at each client boundary. Keeping the authorization set in Host memory avoids SQLite's variable ceiling for large valid corpora without weakening visibility or ranking.
 
-The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `command.execute` runs a slash-command line host-side and returns a detached result; the carrier's request signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
+A stale continuation discards every partial result, deduplication entry, and cursor from that provider attempt, then restarts at the first page against the original list-derived visibility snapshot without discarding the learned provider page size. Limit probes and stale retries share the same limit of at most 100 provider calls (and therefore at most 2,000 inspected hits); a page larger than its requested limit, a repeated continuation cursor, or a still-unexhausted stream at that call budget fails closed as an `internal` business error. The carrier request signal cancels persistence listing, cold-summary collection, and every search call, including a limit or stale rejection observed concurrently with cancellation. A deployment without the service, or any unrecovered index/query failure, also returns an `internal` business error so clients can retain metadata-only matches.
+
+Directory picking delegates to the composed `ctx.directoryPicker` backend ([the directory-picker seam](../directory-picker/README.md)); a method called outside the composed capability's kind fails with `directory-picker-unavailable` (the client needs no advertisement — the composed picker package's own client half renders the matching interaction). Under `native`, `host.pickDirectory` opens one native chooser and returns its selected path (`null` on cancel); this user-paced method does not use the default 30-second unary timeout, while caller/connection aborts still propagate to the native process. Under `browse`, `host.listDirectory` returns one name-sorted directory level with breadcrumb ancestry, a `home` anchor, and host-owned `hidden` flags (absent path = home directory), and `host.createDirectory` creates one validated child segment; the backend's typed failures map 1:1 onto the `directory-unreadable`/`directory-exists`/`directory-create-failed` codes. The browser carrier's prefix-wide trust fence (dsh-client-connection) covers all of these like every other `/api` request.
+
+`host.openPath` opens a filesystem path with the operating system's default application (`open` on macOS, `Invoke-Item` on Windows, `xdg-open` on Linux). The opener is injectable for tests. The browser carrier applies the same loopback, same-origin restriction as `host.pickDirectory`.
+
+The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the browser's user-selected model-reference path, so it returns only skills that are both model-invocable and user-invocable; this domain has no direct skill-loading RPC. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream. Command handlers may legitimately outlast the 30-second transport health deadline, so `command.execute` carries only caller/connection cancellation; that signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
+
+The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves the namespaces addressed by registered configurable providers (`ctx.llm.listConfigurableProviders()`) plus a small explicit allowlist — the Web preference `permission` and the product-owned `ui-onboarding`; adding a Settings registration alone never makes it remotely readable or writable. Any other namespace answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, and the section's `revision`. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired by `llm/adapters-updated` and by a change to a configurable-provider namespace, whose settings carry that provider's catalog and endpoint; a `permission` or `ui-onboarding` change emits only its settings invalidation. The browser carrier restricts the whole configuration plane, reads included (`settings.describe`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.
 
 ## Carrier layer (`/client` + root)
 
@@ -37,6 +51,8 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **`respond` routing is shipped, but pending-interaction state is host-side work** — the wire shape (POST `/api/respond`, `RpcReceipt`) is final; the pending table that makes late/duplicate answers meaningful lives in `src/api-proxy.ts` and is still minimal (questions only, no approvals).
-- **Reserved seams stay out of `RpcMethodMap`** — `session.fork`, `prompt.mode: 'inject'`, `task.list`, `host.listModels`, and a describe `hostInstanceId` are documented reservations; an unknown method fails loud at envelope parse rather than getting a not-implemented code.
+- **Reserved seams stay out of `RpcMethodMap`** — `prompt.mode: 'inject'`, `task.list`, and a describe `hostInstanceId` are documented reservations (the former `host.listModels` reservation shipped as `llm.models`); an unknown method fails loud at envelope parse rather than getting a not-implemented code.
 - **No protocol version field** — client and host ship together; `host.describe` gains a version negotiation field only when an independently released client exists.
-- **Linux native picker requires desktop tooling** — `host.pickDirectory` reports an actionable error when neither Zenity nor KDialog is installed; it does not fall back to a custom or typed-path browser.
+- **Search failures include provider diagnostics** — the gateway is a single-user local service. A carrier that exposes it to multiple users must replace internal search details with a public-safe diagnostic.
+- **Linux native picker requires desktop tooling** — under the `native` capability, `host.pickDirectory` reports an actionable error when neither Zenity nor KDialog is installed; the browse backend is the composition-level fallback (see the [native backend README](../directory-picker-native/README.md)).
+- **A cold session's `updatedAt` counts a mere pickup as a write (per-file backends only)** — the attached projection excludes the `session/end-seed` boundary, because picking a session up is not activity, but a cold session's `updatedAt` is its log file's mtime and every durable write refreshes that, the boundary included. `agentFor()` resumes a cold session on first touch, so merely opening one in a client writes it. This applies only where `locate()` resolves a per-session artifact, i.e. JSONL; SQLite returns `undefined`, so its cold sessions fall back to `createdAt` and are skewed the other way — too old rather than too new — independently of this boundary. A session touched without being worked in therefore sorts newer than its last real activity until it attaches. Separating the two needs a log read, which is exactly what the mtime path exists to avoid; a stored last-activity field in the index would fix it at the source, scoped in the [last-activity-index Agent Note](../../../.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md).

packages/host/apiproxy/README.zh.md

@@ -2,25 +2,39 @@
 
 [English](README.md) | 中文
 
-所有客户端形态共用的 API 网关：TS 契约（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包（package）在设计上与传输方式无关，不注册任何路由；载体（目前为 HTTP，未来可以是 IPC）自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`apps/cli/cordis.yml`](../../../apps/cli/cordis.yml)。
+所有客户端形态共用的 API 网关：TS 契约（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包（package）在设计上与传输方式无关，不注册任何路由；载体（目前为 HTTP，未来可以是 IPC）自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`apps/cli/config/base.cordis.yml`](../../../apps/cli/config/base.cordis.yml)。
 
 ## 契约层（`/api`）
 
-协议消息组成一个四象限可辨识联合：发起方 × 请求／响应，与物理通道解耦。四种消息分别是 `ClientRequest`（POST `/api/<method>` 的请求体）、`ServerResponse`（该 POST 的响应体）、`ServerRequest`（SSE 帧）和 `ClientResponse`（POST `/api/respond` 的请求体）。响应始终回显对应请求的 `rpcId`，绝不签发新值。方法的参数与返回值结构只存在于领域接口签名（`SessionsApi`、`HostApi`、`EventsApi`）中；`RpcMethodMap` 注册方法，其他所有位置均通过 `RequestPayload<K>`／`ResponseValue<K>` 派生。Zod schema 以 `satisfies z.ZodType<Wire<T>>` 锚定类型，并分两层解析：先解析信封，再解析业务载荷，随后按方法分发。业务错误由 `RpcResult` 的错误分支承载（`RpcErrorDetailsMap` 封闭错误码集合）；HTTP 状态只表达载体层结果。
+协议消息组成一个四象限可辨识联合：发起方 × 请求／响应，与物理通道解耦。四种消息分别是 `ClientRequest`（POST `/api/<method>` 的请求体）、`ServerResponse`（该 POST 的响应体）、`ServerRequest`（SSE 帧）和 `ClientResponse`（POST `/api/respond` 的请求体）。响应始终回显对应请求的 `rpcId`，绝不签发新值。方法的参数与返回值结构只存在于领域接口签名（`SessionsApi`、`HostApi`、`EventsApi`）中；`RpcMethodMap` 注册方法，其他所有位置均通过 `RequestPayload<K>`／`ResponseValue<K>` 派生。Zod schema 以 `satisfies z.ZodType<Wire<T>>` 锚定类型，并分两层解析：先解析信封，再解析业务载荷，随后按方法分发。业务错误由 `RpcResult` 的错误分支承载（`RpcErrorDetailsMap` 封闭错误码集合）；HTTP 状态只表达载体层结果。每个 `/api` POST 都必须声明 `application/json` 媒体类型——否则在分发前即以 415 拒绝，因此跨站"简单请求"（浏览器不经 CORS 预检就会发出）永远无法盲目执行有副作用的方法。
 
 分层与协议决策记录在 [GUI 分层与 RPC 协议 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)中；浏览器侧消费架构记录在 [Web 客户端架构 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)中。
 
-mux 流会在每个已附加会话的订阅基线之后，以及对应的实时原始标题事件之后，立即把基于日志的最新标题投影为经过校验的 `session/title` 控制帧。该投影不会把标题加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。
+`session.history` 按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message`、`assistant/message` 和 `steering/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
 
-会话模型路由属于会话领域契约。`session.models` 返回选中的提供方／模型／推理（reasoning）目标，以及按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。
+`session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元铸造一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
-Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.create` 会创建唯一名称或接纳现有目录，`workspace.delete` 只移除 Workspace 注册记录，`session.create` 接受可选的预分配 Session id，`host/workspace-changed`、`host/workspace-removed` 与 `host/session-added` 则以任意到达顺序携带已提交的增量。删除注册记录会保留目录和会话日志；相关 Session 仍留在 `session.list` 中，并进入 Ungrouped。`SessionSummary.blank` 与 `host/session-added` 帧携带派生的零事件位：客户端隐藏空白会话并按 workspace 复用它们，在首个 `host/session-status(running:true)` 时翻转 blank，并以 `session.list` 作为重连权威；冷会话摘要永远不是空白：惰性持久化让从未追加过事件的会话根本不出现在 `list()` 中。
+会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。`session.rename` 接受用户显式标题（冷会话先恢复），委托给 `ctx.sessionTitle.rename`——被接受的 `session/title` 事件将标题钉住、不再被自动生成覆盖——并返回规范化后的标题及其事件 seq，让 client 在推送帧到达前就结算自己的 `title` 投影格；规范化后为空的标题返回 `title-invalid`。
 
-`host.pickDirectory` 会打开一个原生目录选择器并返回选中的路径；用户取消时返回 `null`。宿主实现不经 shell 调用平台工具：macOS 使用 `osascript`，Windows 使用以 STA 模式运行的 PowerShell `FolderBrowserDialog`，Linux 使用 Zenity，并以 KDialog 作为回退。选择器函数可在测试中注入。该方法需等待用户完成操作，是唯一不受默认 30 秒超时限制的一元调用；调用方发出的中止信号和连接中止仍会传播至原生进程。浏览器载体另行将这一特权方法限制为仅接受来自回环地址的同源请求。
+`session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的提供方／模型／推理（reasoning）目标及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。
 
-`session.history` 按消息边界分页，其尾页（不带 `beforeSeq`）额外携带两项页窗口本身无法提供的会话级数据：进行中局部消息的 chunk 事件，以及 `todos`——整份日志上最后一次 `todo/write` 的整表投影。较早的页面不带 `todos`，因为该投影是会话级而非分页级的；尾页响应缺少该字段意味着整份日志中没有任何 `todo/write`，因此客户端要把缺失字段读作空计划，而不是读作「状态未变」。
+会话模型路由属于会话领域契约。`session.models` 返回选中的提供方／模型／推理目标，以及按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。
 
-`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`command.execute` 在宿主侧运行一条斜杠命令行并返回脱耦结果；载体的请求信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
+待处理的 queued 输入属于实时控制平面契约，而非会话历史。网关镜像来自 `agent/inbox/*` 的 queued `InboxItem` 入队项，并在每次 queued 变更和重连时广播权威的 `session/queue` 快照；待处理 steering（中途引导）不进入此 Web 投影。`session.updateQueue` 通过 `InboxItemId` 寻址单个项：编辑会替换待处理内容，移除会将其丢弃。`session.cancel` 仅中止活动轮次，并保留待处理 inbox 工作；取消达到完全停稳且结束中的轮次完成 flush 后，AgentLoop 按 FIFO 顺序认领下一个可唤醒入队项。浏览器绝不重发或提升该入队项。驱动器在接纳前退役寻址标识，因此认领会赢得竞态；之后的操作返回 `queue-item-not-found`。队列操作只查询当前已挂载的 Agent，绝不恢复冷会话，因为进程本地 inbox 标识无法在重启或资源释放后存活。客户端绝不根据轮次或状态事件推断项已退役。
+
+Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.create({ name })` 会在配置根目录下创建显示标题唯一的目录，而 `workspace.create({ path })` 会接纳已有的规范目录，并允许由 basename 派生的标题重复。`workspace.delete` 只移除 Workspace 注册记录，`session.create` 接受可选的预分配 Session id，`host/workspace-changed`、`host/workspace-removed` 与 `host/session-added` 则以任意到达顺序携带已提交的增量。`workspace.archiveSession` 向注册表级全局归档集合添加一个会话，并应答完整的更新后集合；`workspace.list` 携带该集合作为重连基线，`host/archived-sessions-changed` 在每次持久变更后推送完整快照。归档只把会话从各分组视图中隐藏，不触碰其日志和 workspace 记账；既非实时也未持久化的会话以 `session-not-found` 失败。删除注册记录会保留目录和会话日志；相关 Session 仍留在 `session.list` 中，并进入 Ungrouped。`SessionSummary.blank` 与 `host/session-added` 帧携带派生的零事件位：客户端隐藏空白会话并按 workspace 复用它们，在首个 `host/session-status(running:true)` 时翻转 blank，并以 `session.list` 作为重连权威；冷会话摘要永远不是空白：惰性持久化让从未追加过事件的会话根本不出现在 `list()` 中。
+
+`session.search` 是以 `session.list` 所列会话为范围的有界内容搜索投影。网关向可选的 `ctx.sessionQuery` 服务请求全局排序后的当前 surface user、assistant 和 steering（中途引导）匹配项，并持续消费该结果流，直到获得至多 20 个可见会话／snippet 对及一个前瞻项；返回前仍会依据从列表推导的授权集合重新校验每个命中。提供方分页初始请求 20 个命中；如果第一页请求因这一上限被拒绝，网关会依次探测 10、5、2、1，并在续传和陈旧世代重启中沿用探测所得的页面大小。返回的 snippet 最多包含 240 个 Unicode 码点，响应 schema 则会在每个客户端边界独立强制执行该上限。将授权集合保留在宿主内存中，可在不削弱可见性或排序的前提下避开有效大型语料库的 SQLite 变量上限。
+
+陈旧的续传会丢弃该提供方尝试中的所有部分结果、去重条目和游标，然后依据最初从列表推导的可见性快照从第一页重新开始，但不会丢弃探测所得的提供方页面大小。上限探测与陈旧重试共用最多 100 次提供方调用的限制（因此最多检查 2,000 个命中）；如果某页命中数超过其请求的上限、续传游标重复，或用尽该调用预算后结果流仍未耗尽，都会直接返回 `internal` 业务错误，不返回部分结果。载体请求信号可取消持久化列表枚举、冷会话摘要收集和每一次搜索调用；即使同时收到上限拒绝或陈旧拒绝，也以取消为准。部署若未挂载该服务，或索引／查询故障无法恢复，也会返回 `internal` 业务错误，以便客户端保留仅基于元数据的匹配项。
+
+目录选择委托给组合的 `ctx.directoryPicker` 后端（[目录选择 seam](../directory-picker/README.md)）；调用组合能力 kind 之外的方法会以 `directory-picker-unavailable` 失败（客户端不需要广播——组合的选择器包自己的 client half 渲染匹配的交互）。在 `native` 下，`host.pickDirectory` 打开一个原生选择器并返回选中路径（取消为 `null`）；该方法需等待用户完成操作，不使用默认的 30 秒一元调用超时，而调用方与连接的中止仍会传播至原生进程。在 `browse` 下，`host.listDirectory` 返回一个按名称排序的目录层级，携带面包屑祖先链、`home` 锚点与宿主判定的 `hidden` 标志（不带路径即家目录），`host.createDirectory` 创建一个经校验的子段；后端的类型化失败 1:1 映射为 `directory-unreadable`／`directory-exists`／`directory-create-failed` 错误码。浏览器载体的前缀级信任栅栏（dsh-client-connection）像覆盖其他所有 `/api` 请求一样覆盖上述全部方法。
+
+`host.openPath` 会用操作系统的默认应用打开一个文件系统路径（macOS 为 `open`，Windows 为 `Invoke-Item`，Linux 为 `xdg-open`）。打开器可在测试中注入。浏览器载体对其施加与 `host.pickDirectory` 相同的回环、同源限制。
+
+`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于浏览器中由用户选择的模型引用路径，因此仅返回模型和用户均可调用的 skill；该领域没有直接加载 skill 的 RPC。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
+
+`settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表，以及该分节的 `revision`。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；过期的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取：`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
 
 ## 载体层（`/client` + 根路径）
 
@@ -37,6 +51,8 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 ## 已知限制与延期工作
 
 - **`respond` 路由已经发布，但待处理交互状态仍属宿主侧工作**：协议形状（POST `/api/respond`、`RpcReceipt`）已经定型；使延迟或重复回答具有明确语义的待处理表位于 `src/api-proxy.ts`，目前仍很精简（只支持问题，不支持审批）。
-- **预留 seam 不进入 `RpcMethodMap`**：`session.fork`、`prompt.mode: 'inject'`、`task.list`、`host.listModels` 和描述字段 `hostInstanceId` 都是已记录的预留项；未知方法会在信封解析时直接失败，而不会返回「尚未实现」错误码。
+- **预留 seam 不进入 `RpcMethodMap`**：`prompt.mode: 'inject'`、`task.list` 和描述字段 `hostInstanceId` 都是已记录的预留项（先前预留的 `host.listModels` 已作为 `llm.models` 交付）；未知方法会在信封解析时直接失败，而不会返回「尚未实现」错误码。
 - **没有协议版本字段**：客户端与宿主一同发布；只有出现独立发布的客户端后，`host.describe` 才会增加版本协商字段。
-- **Linux 原生选择器依赖桌面工具**：Zenity 和 KDialog 均未安装时，`host.pickDirectory` 会给出包含解决建议的错误提示；它不会回退到自定义目录浏览器，也不会要求用户手动输入路径。
+- **搜索失败会包含提供方诊断信息**：网关是单用户本地服务。将其暴露给多名用户的载体必须用可安全公开的诊断信息替代内部搜索细节。
+- **Linux 原生选择器依赖桌面工具**：在 `native` 能力下，Zenity 和 KDialog 均未安装时，`host.pickDirectory` 会给出包含解决建议的错误提示；组合层面的回退是 browse 后端（见 [native 后端 README](../directory-picker-native/README.md)）。
+- **冷会话的 `updatedAt` 会把一次单纯的拾起算作写入（仅逐文件后端）**：已附加投影排除了 `session/end-seed` 边界，因为接手一个会话不算活动；但冷会话的 `updatedAt` 取自其日志文件的 mtime，而每一次持久写入都会刷新它，包括这条边界。`agentFor()` 会在首次触碰时恢复一个冷会话，因此在客户端里仅仅打开一个会话就会写入它。这只适用于 `locate()` 能解析出逐会话产物的场景，即 JSONL；SQLite 返回 `undefined`，因此它的冷会话回退到 `createdAt`，偏差方向相反——偏旧而不是偏新——且与这条边界无关。于是一个被触碰过却没有在里面工作过的会话，在重新附加之前会按晚于其最后一次真实活动的时间排序。要把两者区分开需要读取日志，而这恰恰是 mtime 路径存在的目的；在索引中存储一个最后活动字段可以从源头修好它，范围见[最后活动索引 Agent Note（agent 决策记录）](../../../.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md)。

packages/host/apiproxy/package.json

@@ -43,10 +43,18 @@
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
+    "@deepseek-ai/dsh-credentials": "workspace:^",
+    "@deepseek-ai/dsh-goal": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-native-command": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-session-projection-cache": "workspace:^",
+    "@deepseek-ai/dsh-session-query": "workspace:^",
     "@deepseek-ai/dsh-session-title": "workspace:^",
+    "@deepseek-ai/dsh-settings": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",

packages/host/apiproxy/src/api/commands.schema.ts

@@ -4,10 +4,11 @@
  */
 
 import { z } from 'zod'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 import { sessionIdSchema } from './sessions.schema.ts'
-import type { CommandDescriptor, CommandExecuteResult } from './commands.ts'
+import type { CommandDescriptor } from './commands.ts'
 
 /** CommandDescriptor row of command.list. */
 export const commandDescriptorSchema = z.object({
@@ -32,14 +33,12 @@ export const commandExecuteRequestSchema = z.object({
   line: z.string(),
 }) satisfies z.ZodType<Wire<RequestPayload<'command.execute'>>>
 
-/** Detached command outcome (result slot of command.execute's value). */
-export const commandExecuteResultSchema = z.object({
-  kind: z.union([z.literal('success'), z.literal('error')]),
-  text: z.string().optional(),
-}) satisfies z.ZodType<Wire<CommandExecuteResult>>
+/** CommandId: one brand cast after shape validation (the only cast point in this domain). */
+export const commandIdSchema = z.string().min(1) as unknown as z.ZodType<CommandId>
 
-/** command.execute response value (matched=false carries no result). */
+/** command.execute response value: pure admission — outcomes ride the logged
+ * lifecycle events; commandId (present exactly when matched) correlates with them. */
 export const commandExecuteValueSchema = z.object({
   matched: z.boolean(),
-  result: commandExecuteResultSchema.optional(),
+  commandId: commandIdSchema.optional(),
 }) satisfies z.ZodType<Wire<ResponseValue<'command.execute'>>>

packages/host/apiproxy/src/api/commands.ts

@@ -5,6 +5,7 @@
  * together), so there is no agent-less surface on this wire.
  */
 
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { RpcRequest, RpcResponse } from './rpc.ts'
 
@@ -22,12 +23,6 @@ export interface CommandDescriptor {
   readonly input?: { readonly hint: string }
 }
 
-/** Detached command outcome rendered directly by the requesting client. */
-export interface CommandExecuteResult {
-  readonly kind: 'success' | 'error'
-  readonly text?: string
-}
-
 /** Command-domain unary methods (the map keys command.* of RpcMethodMap). */
 export interface CommandsApi {
   /**
@@ -38,11 +33,16 @@ export interface CommandsApi {
 
   /**
    * Parses and executes one slash-command line against the addressed agent
-   * without sending it to the model. matched=false when syntax or name does
-   * not resolve (the client falls back to its default sink). The signal rides
-   * beside the request, never on the wire: the fetch carrier's request signal
-   * cancels the running handler.
+   * without sending it to the model — pure admission semantics. matched=false
+   * when syntax or name does not resolve (the client falls back to its
+   * default sink). The handler's outcome does NOT ride the response: the host
+   * executor durably logs the lifecycle (`command/run`/`command/done`), which
+   * broadcasts on the mux stream and renders as a persistent flow node.
+   * `commandId` is present exactly when matched — the minted lifecycle
+   * pairing id, letting the issuing client correlate this acknowledgment
+   * with that flow node. The signal rides beside the request, never on the
+   * wire: the fetch carrier's request signal cancels the running handler.
    */
   execute(request: RpcRequest<{ sessionId: SessionId; line: string }>, signal: AbortSignal):
-  Promise<RpcResponse<{ matched: boolean; result?: CommandExecuteResult }>>
+  Promise<RpcResponse<{ matched: boolean; commandId?: CommandId }>>
 }

packages/host/apiproxy/src/api/credentials.schema.ts

@@ -0,0 +1,48 @@
+/**
+ * credentials domain zod schemas (names derived from map keys:
+ * credentialsDescribeRequestSchema / credentialsDescribeValueSchema / …).
+ * The reference-name pattern mirrors the seam's `credentialRef` guard so an
+ * invalid name fails as `bad-request` before reaching the service.
+ */
+
+import { z } from 'zod'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import type { CredentialView } from './credentials.ts'
+
+/** POSIX-portable environment-variable name (the seam's `credentialRef` pattern). */
+export const credentialRefNameSchema = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/)
+
+/** CredentialView entry of credentials.describe. */
+export const credentialViewSchema = z.object({
+  configured: z.boolean(),
+  source: z.string().optional(),
+  writable: z.boolean(),
+}) satisfies z.ZodType<Wire<CredentialView>>
+
+/** credentials.describe request payload. */
+export const credentialsDescribeRequestSchema = z.object({
+  refs: z.array(credentialRefNameSchema).max(64),
+}) satisfies z.ZodType<Wire<RequestPayload<'credentials.describe'>>>
+
+/** credentials.describe response value. */
+export const credentialsDescribeValueSchema = z.object({
+  credentials: z.record(z.string(), credentialViewSchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'credentials.describe'>>>
+
+/** credentials.set request payload: the one direction a value crosses this wire. */
+export const credentialsSetRequestSchema = z.object({
+  ref: credentialRefNameSchema,
+  value: z.string().min(1),
+}) satisfies z.ZodType<Wire<RequestPayload<'credentials.set'>>>
+
+/** credentials.set response value. */
+export const credentialsSetValueSchema = z.object({}) satisfies z.ZodType<Wire<ResponseValue<'credentials.set'>>>
+
+/** credentials.unset request payload. */
+export const credentialsUnsetRequestSchema = z.object({
+  ref: credentialRefNameSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'credentials.unset'>>>
+
+/** credentials.unset response value. */
+export const credentialsUnsetValueSchema = z.object({}) satisfies z.ZodType<Wire<ResponseValue<'credentials.unset'>>>

packages/host/apiproxy/src/api/credentials.ts

@@ -0,0 +1,44 @@
+/**
+ * credentials domain contract: the web face of the credential-reference seam
+ * (`ctx.credentials`). Reads are structurally value-free — a credential view
+ * carries configured/source/writable and has no slot for the value — and the
+ * value crosses the wire in exactly one direction, inside `credentials.set`.
+ * There is no enumeration method by design: clients learn which references
+ * exist from settings schemas and values (`apiKeyEnv` fields).
+ */
+
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+
+/** Wire view of one credential reference's state. */
+export interface CredentialView {
+  /** Whether any layer currently supplies a non-empty value. */
+  configured: boolean
+  /** Winning layer when configured (`env`, `file`, …); provider vocabulary. */
+  source?: string
+  /** Whether `credentials.set`/`credentials.unset` can affect this reference. */
+  writable: boolean
+}
+
+/** Credentials-domain unary methods (the map keys credentials.* of RpcMethodMap). */
+export interface CredentialsApi {
+  /**
+   * Describe the named references (batch): configured state, winning source,
+   * and writability — never values. An invalid reference name is a
+   * `bad-request`; an unknown-but-valid one describes as unconfigured.
+   */
+  describe(request: RpcRequest<{ refs: string[] }>): Promise<RpcResponse<{ credentials: Record<string, CredentialView> }>>
+
+  /**
+   * Store one credential value in the writable layer. Rejected with
+   * `credential-rejected` while a read-only layer (the live environment)
+   * shadows the reference — the write would otherwise appear to succeed while
+   * resolution keeps returning the shadowing value.
+   */
+  set(request: RpcRequest<{ ref: string; value: string }>): Promise<RpcResponse<{}>>
+
+  /**
+   * Remove one credential from the writable layer; same shadowing rejection
+   * as `set`. Unsetting an absent reference succeeds (idempotent).
+   */
+  unset(request: RpcRequest<{ ref: string }>): Promise<RpcResponse<{}>>
+}

packages/host/apiproxy/src/api/events.schema.ts

@@ -10,7 +10,9 @@ import type { HostFrame, MuxFrame } from './events.ts'
 import type { Wire } from './rpc.schema.ts'
 import { rpcErrorSchema, rpcIdSchema } from './rpc.schema.ts'
 import { approvalRequestIdSchema } from './approvals.schema.ts'
-import { contentBlockSchema, sessionEventSchema, sessionIdSchema, toolEventViewSchema } from './sessions.schema.ts'
+import {
+  contentBlockSchema, inboxItemIdSchema, sessionEventSchema, sessionIdSchema, toolEventViewSchema,
+} from './sessions.schema.ts'
 import { workspaceIdSchema, workspaceViewSchema } from './workspace.schema.ts'
 
 /** Question shape validated strictly against core dsh-user-interaction. */
@@ -21,13 +23,25 @@ export const askUserQuestionItemSchema = z.object({
   detail: z.string().optional(),
   options: z.array(z.object({ label: z.string(), description: z.string().optional() })).optional(),
   multiSelect: z.boolean().optional(),
+  // Presentation intent: a tagged union on the wire, so an unknown tag is a
+  // rejected frame rather than a silently generic render.
+  intent: z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('plan-review'), approve: z.string() }),
+  ]).optional(),
 }) satisfies z.ZodType<Wire<AskUserQuestionItem>>
 
+/** Unified message envelope carried by transient queue frames. */
+const messageSchema = z.object({
+  id: z.string().min(1),
+  role: z.union([z.literal('system'), z.literal('user'), z.literal('assistant')]),
+  content: z.array(contentBlockSchema),
+  source: z.looseObject({ kind: z.string() }),
+})
+
 /** MuxFrame union (payload slot of a mux-stream ServerRequest). */
 export const muxFrameSchema = z.discriminatedUnion('type', [
   z.object({ type: z.literal('session/event'), sessionId: sessionIdSchema, event: sessionEventSchema, view: toolEventViewSchema.optional() }),
   z.object({ type: z.literal('session/subscribed'), sessionId: sessionIdSchema, lastSeq: z.number().int() }),
-  z.object({ type: z.literal('session/title'), sessionId: sessionIdSchema, title: z.string().min(1), eventSeq: z.number().int().nonnegative(), updatedAt: z.number() }),
   z.object({ type: z.literal('approval/requested'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, toolName: z.string(), callId: z.string().optional(), reason: z.string().optional() }),
   z.object({ type: z.literal('approval/resolved'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, outcome: z.union([z.literal('allowed-once'), z.literal('rejected'), z.literal('cancelled'), z.literal('unavailable')]) }),
   // Non-empty by wire contract: the user-interaction service rejects empty
@@ -35,8 +49,17 @@ export const muxFrameSchema = z.discriminatedUnion('type', [
   // and must fail loud here, not reach the composer.
   z.object({ type: z.literal('question/requested'), sessionId: sessionIdSchema, questions: z.array(askUserQuestionItemSchema).min(1) }),
   z.object({ type: z.literal('question/resolved'), sessionId: sessionIdSchema, questionRpcId: rpcIdSchema, outcome: z.union([z.literal('answered'), z.literal('cancelled')]) }),
-  // content/source reuse the wide passthroughs (both are merge-extensible in core).
-  z.object({ type: z.literal('session/queued'), sessionId: sessionIdSchema, content: z.array(contentBlockSchema), source: z.looseObject({ kind: z.string() }), steering: z.boolean() }),
+  z.object({
+    type: z.literal('session/queue'),
+    sessionId: sessionIdSchema,
+    items: z.array(z.object({
+      id: inboxItemIdSchema,
+      message: messageSchema,
+    })),
+  }),
+  // value stays wide: it already passed its unit's own schema on the host,
+  // and deep-validating here would import every domain's schema into the carrier.
+  z.object({ type: z.literal('session/projection'), sessionId: sessionIdSchema, key: z.string().min(1), value: z.unknown(), seq: z.number().int().nonnegative() }),
   z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
 ]) as unknown as z.ZodType<MuxFrame>
 
@@ -48,6 +71,10 @@ export const hostFrameSchema = z.discriminatedUnion('type', [
   z.object({ type: z.literal('host/agent-error'), sessionId: sessionIdSchema, message: z.string() }),
   z.object({ type: z.literal('host/workspace-changed'), workspace: workspaceViewSchema }),
   z.object({ type: z.literal('host/workspace-removed'), workspaceId: workspaceIdSchema }),
+  z.object({ type: z.literal('host/archived-sessions-changed'), archivedSessionIds: z.array(sessionIdSchema) }),
   z.object({ type: z.literal('host/commands-changed') }),
+  z.object({ type: z.literal('host/settings-changed'), ns: z.string() }),
+  z.object({ type: z.literal('host/credentials-changed'), ref: z.string() }),
+  z.object({ type: z.literal('host/models-changed') }),
   z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
 ]) as unknown as z.ZodType<HostFrame>

packages/host/apiproxy/src/api/events.ts

@@ -8,7 +8,8 @@
 
 import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-interaction/types'
 import type { ApprovalOutcome, ApprovalRequestId } from '@deepseek-ai/dsh-user-approval/types'
-import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm/types'
+import type { Message } from '@deepseek-ai/dsh-llm/types'
+import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand'
 import type { CallId } from '@deepseek-ai/dsh-llm/brand'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
@@ -31,13 +32,21 @@ export type ToolEventView =
   | { for: 'call'; view: ToolCallView }
   | { for: 'result'; view: ToolResultView }
 
+/** One pending queued occurrence in an authoritative queue snapshot. */
+export interface QueuedInboxItem {
+  /** Agent-owned occurrence identity used by queue mutations. */
+  id: InboxItemId
+  /** Complete pending message; it is not durable until the Agent claims it. */
+  message: Message
+}
+
 /** Streaming face of the contract: the two SSE stream openers (mux + host). */
 export interface EventsApi {
   /**
    * All-session aggregated mux stream. On open, emits a subscribed control frame for every
-   * attached session followed by its optional latest title snapshot, then replays each
-   * session's still-pending approval/question requested frames (rpcId reused verbatim — the
-   * refresh-recovery baseline).
+   * attached session, then replays each session's still-pending approval/question requested
+   * frames (rpcId reused verbatim — the refresh-recovery baseline). Session titles ride the
+   * generic projection pair (history-tail projections block + session/projection frames).
    * since: resume seam, unimplemented in v1 (ignored if passed); reconnection = reopen the
    * stream + refetch history.
    */
@@ -57,24 +66,27 @@ export interface EventsApi {
 export type MuxFrame =
   | { type: 'session/event'; sessionId: SessionId; event: SessionEvent; view?: ToolEventView }
   | { type: 'session/subscribed'; sessionId: SessionId; lastSeq: number }
-  | { type: 'session/title'; sessionId: SessionId; title: string; eventSeq: number; updatedAt: number }
   | { type: 'approval/requested'; sessionId: SessionId; approvalId: ApprovalRequestId; toolName: string; callId?: CallId; reason?: string }
   | { type: 'approval/resolved'; sessionId: SessionId; approvalId: ApprovalRequestId; outcome: ApprovalOutcome }
   | { type: 'question/requested'; sessionId: SessionId; questions: AskUserQuestionItem[] }
   | { type: 'question/resolved'; sessionId: SessionId; questionRpcId: RpcId; outcome: 'answered' | 'cancelled' }
   /**
-   * A message entered the addressed agent's inbox. A queued message is not
-   * model-visible, so there is no session event to carry it; this transient
-   * frame is the only wire signal. On stream open the
-   * host replays the current queue snapshot for every attached session (same
-   * refresh-recovery baseline as pending questions); queue clearing on cancel
-   * has no dedicated frame — clients fold it from the status flip.
-   * `steering` is the host's acceptance-time queue classification and remains
-   * authoritative in reconnect snapshots. `source` carries the prompt's rpcId
-   * when the message came over this wire (the client's provisional-echo
-   * reconciliation key).
+   * Complete transient queue state after every enqueue, mutation, claim, or
+   * discard. Pending work is not model-visible and therefore has no durable
+   * session event; the whole snapshot makes edit, deletion, cancel, and
+   * reconnect converge through one authoritative signal. Pending steering is
+   * outside this Web queue projection.
    */
-  | { type: 'session/queued'; sessionId: SessionId; content: ContentBlock[]; source: MessageSource; steering: boolean }
+  | { type: 'session/queue'; sessionId: SessionId; items: QueuedInboxItem[] }
+  /**
+   * One projection unit's finished value changed (session-projection RFC).
+   * Live push state, never logged — replay recomputes on the host (the
+   * tool-view posture). `value` is the unit's schema-validated view output;
+   * `seq` is the unit's watermark at emission. Clients keep one generic
+   * per-session value store under higher-seq-wins, seeded by the history
+   * tail page's projections block.
+   */
+  | { type: 'session/projection'; sessionId: SessionId; key: string; value: unknown; seq: number }
   | { type: 'stream/error'; error: RpcError }
 
 /**
@@ -89,7 +101,9 @@ export type MuxFrame =
  * workspace mutation (create/attach/order change — the client upserts, while
  * `workspace.list` provides the reconnect baseline); workspace-removed is the
  * committed registration-deletion increment and never implies directory or
- * session-log deletion.
+ * session-log deletion; archived-sessions-changed pushes the full registry
+ * archive set after every durable change (same full-snapshot posture as
+ * workspace-changed — `workspace.list` re-baselines it on reconnect).
  */
 export type HostFrame =
   | { type: 'host/session-added'; sessionId: SessionId; blank: boolean; parentSessionId?: SessionId; cwd?: string }
@@ -98,10 +112,30 @@ export type HostFrame =
   | { type: 'host/agent-error'; sessionId: SessionId; message: string }
   | { type: 'host/workspace-changed'; workspace: WorkspaceView }
   | { type: 'host/workspace-removed'; workspaceId: WorkspaceView['workspaceId'] }
+  | { type: 'host/archived-sessions-changed'; archivedSessionIds: SessionId[] }
   /**
    * The command registry changed (`commands/change` passthrough). Pure
    * invalidation signal, no payload: clients refetch `command.list` in the
    * background rather than diffing.
    */
   | { type: 'host/commands-changed' }
+  /**
+   * One settings namespace's resolved value changed (`settings/updated`
+   * passthrough) — an RPC write, an external `settings.yaml` edit, or a
+   * provider reload all converge here. Clients refetch `settings.describe`;
+   * values never ride the frame (they would need redaction and can go stale).
+   */
+  | { type: 'host/settings-changed'; ns: string }
+  /**
+   * One credential reference's state changed (`credentials/updated`
+   * passthrough): a set/unset over this wire or an external `.env` edit.
+   * The ref is an environment-variable NAME — never a value.
+   */
+  | { type: 'host/credentials-changed'; ref: string }
+  /**
+   * The provider topology changed (`llm/adapters-updated` passthrough):
+   * routes registered or dropped, or the configurable directory moved. Pure
+   * invalidation: clients refetch `llm.providers`/`llm.models`/`session.models`.
+   */
+  | { type: 'host/models-changed' }
   | { type: 'stream/error'; error: RpcError }

packages/host/apiproxy/src/api/goals.schema.ts

@@ -0,0 +1,79 @@
+/**
+ * goals domain zod schemas. Mutation-only shapes: every value schema is a
+ * `{ ref }` acknowledgement (clear: `{ cleared }`) — the current goal state
+ * travels exclusively on the 'goal' session projection.
+ */
+
+import { z } from 'zod'
+import type { Wire } from './rpc.schema.ts'
+import type { GoalRef, RequestPayload, ResponseValue } from './index.ts'
+
+/** GoalRef schema. */
+export const goalRefSchema = z.object({
+  id: z.string(),
+  revision: z.number().int().positive(),
+}) as unknown as z.ZodType<Wire<GoalRef>>
+
+/** Shared `{ ref }` acknowledgement value of every non-clear mutation. */
+const goalRefValueSchema = z.object({ ref: goalRefSchema })
+
+/** goal.create request payload. */
+export const goalCreateRequestSchema = z.object({
+  sessionId: z.string(),
+  objective: z.string().min(1),
+  maxGoalRounds: z.number().int().positive().optional(),
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.create'>>>
+
+/** goal.create response value. */
+export const goalCreateValueSchema = goalRefValueSchema as unknown as z.ZodType<Wire<ResponseValue<'goal.create'>>>
+
+/** goal.edit request payload. */
+export const goalEditRequestSchema = z.object({
+  sessionId: z.string(),
+  ref: goalRefSchema,
+  objective: z.string().min(1).optional(),
+  maxGoalRounds: z.number().int().positive().optional(),
+}).refine(value => value.objective !== undefined || value.maxGoalRounds !== undefined, {
+  message: 'goal.edit requires objective or maxGoalRounds',
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.edit'>>>
+
+/** goal.edit response value. */
+export const goalEditValueSchema = goalRefValueSchema as unknown as z.ZodType<Wire<ResponseValue<'goal.edit'>>>
+
+/** goal.pause request payload. */
+export const goalPauseRequestSchema = z.object({
+  sessionId: z.string(),
+  ref: goalRefSchema,
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.pause'>>>
+
+/** goal.pause response value. */
+export const goalPauseValueSchema = goalRefValueSchema as unknown as z.ZodType<Wire<ResponseValue<'goal.pause'>>>
+
+/** goal.resume request payload. */
+export const goalResumeRequestSchema = z.object({
+  sessionId: z.string(),
+  ref: goalRefSchema,
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.resume'>>>
+
+/** goal.resume response value. */
+export const goalResumeValueSchema = goalRefValueSchema as unknown as z.ZodType<Wire<ResponseValue<'goal.resume'>>>
+
+/** goal.complete request payload. */
+export const goalCompleteRequestSchema = z.object({
+  sessionId: z.string(),
+  ref: goalRefSchema,
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.complete'>>>
+
+/** goal.complete response value. */
+export const goalCompleteValueSchema = goalRefValueSchema as unknown as z.ZodType<Wire<ResponseValue<'goal.complete'>>>
+
+/** goal.clear request payload. */
+export const goalClearRequestSchema = z.object({
+  sessionId: z.string(),
+  ref: goalRefSchema,
+}) as unknown as z.ZodType<Wire<RequestPayload<'goal.clear'>>>
+
+/** goal.clear response value. */
+export const goalClearValueSchema = z.object({
+  cleared: z.literal(true),
+}) as unknown as z.ZodType<Wire<ResponseValue<'goal.clear'>>>

packages/host/apiproxy/src/api/goals.ts

@@ -0,0 +1,50 @@
+/**
+ * goals domain contract. Method signatures are the source of truth:
+ * unary methods take the RpcRequest<P> narrow form and the impl echoes rpcId.
+ *
+ * Mutations only: the read side is the 'goal' session projection (history
+ * tail-page projections block + session/projection frames), so there is no
+ * goal.get and no wire goal view — responses acknowledge with the new CAS
+ * ref and never feed client state (the committed goal/change event reaches
+ * every client through the mux stream carrying the same whole value).
+ */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+
+/** Identifies one goal across its durable revisions. */
+export type GoalId = Branded<'GoalId'>
+
+/** Compare-and-set identity for one exact goal revision. */
+export interface GoalRef {
+  readonly id: GoalId
+  readonly revision: number
+}
+
+/** Goal-domain unary methods (every mutation resolves the session's agent and applies one CAS-guarded verb). */
+export interface GoalsApi {
+  /** Create and arm a goal. */
+  create(request: RpcRequest<{ sessionId: SessionId; objective: string; maxGoalRounds?: number }>):
+  Promise<RpcResponse<{ ref: GoalRef }>>
+
+  /** Edit objective and/or round cap without changing phase. */
+  edit(request: RpcRequest<{ sessionId: SessionId; ref: GoalRef; objective?: string; maxGoalRounds?: number }>):
+  Promise<RpcResponse<{ ref: GoalRef }>>
+
+  /** Pause an active goal and disarm automatic continuation. */
+  pause(request: RpcRequest<{ sessionId: SessionId; ref: GoalRef }>):
+  Promise<RpcResponse<{ ref: GoalRef }>>
+
+  /** Resume and arm a stopped goal. */
+  resume(request: RpcRequest<{ sessionId: SessionId; ref: GoalRef }>):
+  Promise<RpcResponse<{ ref: GoalRef }>>
+
+  /** Mark a current non-complete goal complete and disarm it. */
+  complete(request: RpcRequest<{ sessionId: SessionId; ref: GoalRef }>):
+  Promise<RpcResponse<{ ref: GoalRef }>>
+
+  /** Clear the current goal while retaining a durable tombstone and history. */
+  clear(request: RpcRequest<{ sessionId: SessionId; ref: GoalRef }>):
+  Promise<RpcResponse<{ cleared: true }>>
+}

packages/host/apiproxy/src/api/host.schema.ts

@@ -3,6 +3,7 @@
  */
 
 import { z } from 'zod'
+import type { DirectoryEntry } from './host.ts'
 import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 
@@ -16,6 +17,8 @@ export const hostDescribeValueSchema = z.object({
   provider: z.string().optional(),
   model: z.string().optional(),
   attachedSessions: z.number().int().nonnegative(),
+  // Open string, not a literal union: unknown kinds must survive the wire so
+  // a merge-added capability can advertise (the client hides the affordance).
 }) satisfies z.ZodType<Wire<ResponseValue<'host.describe'>>>
 
 /** host.pickDirectory request payload (empty object literal). */
@@ -25,3 +28,48 @@ export const hostPickDirectoryRequestSchema = z.object({}) satisfies z.ZodType<W
 export const hostPickDirectoryValueSchema = z.object({
   path: z.string().nullable(),
 }) satisfies z.ZodType<Wire<ResponseValue<'host.pickDirectory'>>>
+
+/** Directory row shared by listing entries and breadcrumb crumbs. */
+export const directoryEntrySchema = z.object({
+  name: z.string(),
+  path: z.string(),
+  hidden: z.boolean(),
+}) satisfies z.ZodType<Wire<DirectoryEntry>>
+
+/** host.listDirectory request payload; an absent path lists the home directory. */
+export const hostListDirectoryRequestSchema = z.object({
+  path: z.string().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'host.listDirectory'>>>
+
+/** host.listDirectory response value. */
+export const hostListDirectoryValueSchema = z.object({
+  path: z.string(),
+  home: z.string(),
+  crumbs: z.array(directoryEntrySchema),
+  entries: z.array(directoryEntrySchema),
+  truncated: z.boolean(),
+}) satisfies z.ZodType<Wire<ResponseValue<'host.listDirectory'>>>
+
+/** host.createDirectory request payload: name must be one plain path segment. */
+export const hostCreateDirectoryRequestSchema = z.object({
+  path: z.string(),
+  name: z.string(),
+}).refine(
+  payload => payload.name.trim() !== '' && payload.name !== '.' && payload.name !== '..'
+    && !/[/\\]/.test(payload.name),
+  { message: 'host.createDirectory requires a single non-blank path segment name' },
+) satisfies z.ZodType<Wire<RequestPayload<'host.createDirectory'>>>
+
+/** host.createDirectory response value: the created directory's absolute path. */
+export const hostCreateDirectoryValueSchema = z.object({
+  path: z.string(),
+}) satisfies z.ZodType<Wire<ResponseValue<'host.createDirectory'>>>
+/** host.openPath request payload. */
+export const hostOpenPathRequestSchema = z.object({
+  path: z.string().min(1),
+}) satisfies z.ZodType<Wire<RequestPayload<'host.openPath'>>>
+
+/** host.openPath response value. */
+export const hostOpenPathValueSchema = z.object({
+  opened: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'host.openPath'>>>

packages/host/apiproxy/src/api/host.ts

@@ -5,6 +5,33 @@
 
 import type { RpcRequest, RpcResponse } from './rpc.ts'
 
+/** One directory row of a listing: a child entry or a breadcrumb ancestor. */
+export interface DirectoryEntry {
+  /** Base name shown in a browser row (a root crumb carries its full path). */
+  name: string
+  /** Absolute host path — the client never joins path segments itself. */
+  path: string
+  /** Hidden by the host platform's convention (dot-prefixed on POSIX); the client owns whether to show it. */
+  hidden: boolean
+}
+
+/** host.listDirectory response value: one directory level plus its ancestry. */
+export interface DirectoryListing {
+  /** Absolute path of the listed directory. */
+  path: string
+  /** The host account's home directory (breadcrumb "Home" rooting). */
+  home: string
+  /**
+   * Ancestor chain from the filesystem root to the listed directory
+   * inclusive; every crumb is a jump target (crumb `hidden` is always false).
+   */
+  crumbs: DirectoryEntry[]
+  /** Direct child directories, name-sorted; symlinks to directories included. */
+  entries: DirectoryEntry[]
+  /** True when the backend cut `entries` at its complete-result bound (the name-sorted tail is absent). */
+  truncated: boolean
+}
+
 /** Host-level unary methods. */
 export interface HostApi {
   /**
@@ -13,7 +40,7 @@ export interface HostApi {
    * directory (root for session persistence and tool execution); provider/model = the defaults
    * applied when a new agent doesn't specify them explicitly, absent when the host configures
    * no explicit default (the adapter falls back internally);
-   * attachedSessions = count of currently attached sessions (those with a live agent).
+   * attachedSessions = count of currently attached sessions (those with a live agent);
    */
   describe(request: RpcRequest<{}>): Promise<RpcResponse<{
     version: string
@@ -23,9 +50,45 @@ export interface HostApi {
     attachedSessions: number
   }>>
 
-  /** Open the operating system's single-directory picker; cancellation returns null. */
+  /**
+   * Open the operating system's single-directory picker; cancellation returns
+   * null. Only served under the `native` capability.
+   */
   pickDirectory(
     request: RpcRequest<{}>,
     signal: AbortSignal,
   ): Promise<RpcResponse<{ path: string | null }>>
+
+  /**
+   * List one directory level for the in-app browser; an absent path lists the
+   * host account's home directory. Only served under the `browse` capability;
+   * unreadable or missing targets fail with `directory-unreadable`. The
+   * carrier's request signal follows the caller, stopping the backend's scan
+   * on disconnect or timeout.
+   */
+  listDirectory(
+    request: RpcRequest<{ path?: string }>,
+    signal: AbortSignal,
+  ): Promise<RpcResponse<DirectoryListing>>
+
+  /**
+   * Create one child directory under an existing parent (the browser's
+   * "New folder"). Only served under the `browse` capability; an existing
+   * child fails with `directory-exists`, every other filesystem failure with
+   * `directory-create-failed`.
+   */
+  createDirectory(
+    request: RpcRequest<{ path: string; name: string }>,
+  ): Promise<RpcResponse<{ path: string }>>
+
+  /**
+   * Open a filesystem path with the operating system's default application
+   * (Finder / Explorer / xdg-open hand-off). The browser carrier's
+   * prefix-wide trust fence covers this privileged method like every other
+   * `/api` request.
+   */
+  openPath(
+    request: RpcRequest<{ path: string }>,
+    signal: AbortSignal,
+  ): Promise<RpcResponse<{ opened: true }>>
 }

packages/host/apiproxy/src/api/index.ts

@@ -10,6 +10,10 @@ import type { WorkspaceApi } from './workspace.ts'
 import type { CommandsApi } from './commands.ts'
 import type { SkillsApi } from './skills.ts'
 import type { EventsApi } from './events.ts'
+import type { GoalsApi } from './goals.ts'
+import type { SettingsApi } from './settings.ts'
+import type { CredentialsApi } from './credentials.ts'
+import type { LlmApi } from './llm.ts'
 import type { ClientResponse, RpcReceipt } from './rpc.ts'
 
 /** Root interface of the unified API surface. New client-request domain = one new file pair + one field here + one map row. */
@@ -20,6 +24,10 @@ export interface ApiProxy {
   commands: CommandsApi
   skills: SkillsApi
   events: EventsApi
+  goals: GoalsApi
+  settings: SettingsApi
+  credentials: CredentialsApi
+  llm: LlmApi
   /** Response entry for server-requests (client-response, echoing their rpcId); not a domain method (four-quadrant model). */
   respond(message: ClientResponse): Promise<RpcReceipt>
 }
@@ -27,13 +35,18 @@ export interface ApiProxy {
 // ---- Domain interfaces and payload entities ----
 export type {
   HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, SessionModels, SessionsApi, SessionSummary,
+  ModelReasoningEffort, ModelTarget, QueueAction, SessionModels, SessionProjectionsBlock, SessionSearchItem,
+  SessionsApi, SessionSummary,
 } from './sessions.ts'
-export type { HostApi } from './host.ts'
+export type { DirectoryEntry, DirectoryListing, HostApi } from './host.ts'
 export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
-export type { CommandsApi, CommandDescriptor, CommandExecuteResult } from './commands.ts'
+export type { CommandsApi, CommandDescriptor } from './commands.ts'
 export type { SkillsApi, SkillEntry } from './skills.ts'
-export type { EventsApi, MuxFrame, HostFrame, ToolCallView, ToolEventView, ToolResultView } from './events.ts'
+export type { EventsApi, MuxFrame, HostFrame, QueuedInboxItem, ToolCallView, ToolEventView, ToolResultView } from './events.ts'
+export type { GoalsApi, GoalId, GoalRef } from './goals.ts'
+export type { SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView } from './settings.ts'
+export type { CredentialsApi, CredentialView } from './credentials.ts'
+export type { ConfigurableProviderView, LlmApi } from './llm.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'
 export type { QuestionResponsePayload } from './questions.ts'
 
@@ -53,6 +66,13 @@ export type {
 // ---- Errors and ids ----
 export { RpcId, transportError } from './rpc.ts'
 export type { RpcError, RpcErrorCode, RpcErrorDetailsMap, RpcResult } from './rpc.ts'
+export type { InboxItemId } from '@deepseek-ai/dsh-agent/brand'
+
+// ---- Fixed session-search product bounds ----
+export {
+  SESSION_SEARCH_RESULT_LIMIT,
+  SESSION_SEARCH_SNIPPET_MAX_CODE_POINTS,
+} from './session-search.ts'
 
 // ---- Method registry and derived generics ----
 export type { RequestPayload, ResponseValue, RpcMethodMap } from './rpc-map.ts'

packages/host/apiproxy/src/api/llm.schema.ts

@@ -0,0 +1,36 @@
+/**
+ * llm domain zod schemas (names derived from map keys: llmProvidersRequestSchema /
+ * llmProvidersValueSchema / llmModelsRequestSchema / llmModelsValueSchema).
+ */
+
+import { z } from 'zod'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import type { ConfigurableProviderView } from './llm.ts'
+import { modelCatalogFailureSchema, modelProviderGroupSchema } from './sessions.schema.ts'
+
+/** ConfigurableProviderView row of llm.providers. */
+export const configurableProviderViewSchema = z.object({
+  provider: z.string().min(1),
+  displayName: z.string().min(1),
+  settingsNs: z.string(),
+  settingsPath: z.array(z.string()),
+  active: z.boolean(),
+}) satisfies z.ZodType<Wire<ConfigurableProviderView>>
+
+/** llm.providers request payload. */
+export const llmProvidersRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'llm.providers'>>>
+
+/** llm.providers response value. */
+export const llmProvidersValueSchema = z.object({
+  providers: z.array(configurableProviderViewSchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'llm.providers'>>>
+
+/** llm.models request payload. */
+export const llmModelsRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'llm.models'>>>
+
+/** llm.models response value. */
+export const llmModelsValueSchema = z.object({
+  groups: z.array(modelProviderGroupSchema),
+  failures: z.array(modelCatalogFailureSchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'llm.models'>>>

packages/host/apiproxy/src/api/llm.ts

@@ -0,0 +1,43 @@
+/**
+ * llm domain contract: host-scoped provider topology for configuration
+ * surfaces. `llm.providers` merges the configurable-provider directory
+ * (which providers CAN be configured, and where their settings live) with the
+ * live route registry; `llm.models` is the session-independent model catalog
+ * (`session.models` minus the per-session current/unlisted logic). Both
+ * invalidate on the `host/models-changed` frame.
+ */
+
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+import type { ModelCatalogFailure, ModelProviderGroup } from './sessions.ts'
+
+/** Wire view of one configurable provider. */
+export interface ConfigurableProviderView {
+  /** Provider route key (`deepseek-official`, `openai`, …). */
+  provider: string
+  /** Human-readable name for configuration surfaces. */
+  displayName: string
+  /** Settings namespace whose section configures this provider. */
+  settingsNs: string
+  /** Path from that section's root to the provider's profile object (empty = whole section). */
+  settingsPath: string[]
+  /** Whether the route is currently registered (its models are requestable). */
+  active: boolean
+}
+
+/** Llm-domain unary methods (the map keys llm.* of RpcMethodMap). */
+export interface LlmApi {
+  /**
+   * List every configurable provider with its live/dormant state, in
+   * directory declaration order. Routes registered outside the directory
+   * (an adapter that never declared configurability) are appended with their
+   * registration identity and no settings address.
+   */
+  providers(request: RpcRequest<{}>): Promise<RpcResponse<{ providers: ConfigurableProviderView[] }>>
+
+  /**
+   * Host-scoped model catalog over every registered provider route: the
+   * settings surface's models view, needing no session. Per-provider listing
+   * failures ride `failures` without failing the sound groups.
+   */
+  models(request: RpcRequest<{}>): Promise<RpcResponse<{ groups: ModelProviderGroup[]; failures: ModelCatalogFailure[] }>>
+}

packages/host/apiproxy/src/api/rpc-map.ts

@@ -9,6 +9,10 @@ import type { HostApi } from './host.ts'
 import type { WorkspaceApi } from './workspace.ts'
 import type { CommandsApi } from './commands.ts'
 import type { SkillsApi } from './skills.ts'
+import type { GoalsApi } from './goals.ts'
+import type { SettingsApi } from './settings.ts'
+import type { CredentialsApi } from './credentials.ts'
+import type { LlmApi } from './llm.ts'
 import type { RpcResponse } from './rpc.ts'
 
 /**
@@ -18,22 +22,45 @@ import type { RpcResponse } from './rpc.ts'
  */
 export interface RpcMethodMap {
   'session.list': SessionsApi['list']
+  'session.search': SessionsApi['search']
   'session.create': SessionsApi['create']
   'session.history': SessionsApi['history']
   'session.models': SessionsApi['models']
   'session.selectModel': SessionsApi['selectModel']
+  'session.rename': SessionsApi['rename']
+  'session.fork': SessionsApi['fork']
   'session.prompt': SessionsApi['prompt']
+  'session.updateQueue': SessionsApi['updateQueue']
   'session.cancel': SessionsApi['cancel']
   'host.describe': HostApi['describe']
   'host.pickDirectory': HostApi['pickDirectory']
+  'host.listDirectory': HostApi['listDirectory']
+  'host.createDirectory': HostApi['createDirectory']
+  'host.openPath': HostApi['openPath']
   'workspace.list': WorkspaceApi['list']
   'workspace.create': WorkspaceApi['create']
   'workspace.rename': WorkspaceApi['rename']
   'workspace.delete': WorkspaceApi['delete']
   'workspace.insertSessionBefore': WorkspaceApi['insertSessionBefore']
+  'workspace.archiveSession': WorkspaceApi['archiveSession']
   'command.list': CommandsApi['list']
   'command.execute': CommandsApi['execute']
   'skill.list': SkillsApi['list']
+  'goal.create': GoalsApi['create']
+  'goal.edit': GoalsApi['edit']
+  'goal.pause': GoalsApi['pause']
+  'goal.resume': GoalsApi['resume']
+  'goal.complete': GoalsApi['complete']
+  'goal.clear': GoalsApi['clear']
+  'settings.describe': SettingsApi['describe']
+  'settings.update': SettingsApi['update']
+  'settings.replace': SettingsApi['replace']
+  'settings.mutate': SettingsApi['mutate']
+  'credentials.describe': CredentialsApi['describe']
+  'credentials.set': CredentialsApi['set']
+  'credentials.unset': CredentialsApi['unset']
+  'llm.providers': LlmApi['providers']
+  'llm.models': LlmApi['models']
 }
 
 /** Business request payload of method K (reaches through the RpcRequest narrow form to payload). */

packages/host/apiproxy/src/api/rpc.schema.ts

@@ -42,7 +42,20 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('workspace-invalid-path'), message: z.string(), details: z.object({ path: z.string() }) }),
   z.object({ code: z.literal('workspace-name-conflict'), message: z.string(), details: z.object({ name: z.string() }) }),
   z.object({ code: z.literal('workspace-move-invalid'), message: z.string(), details: z.object({ workspaceId: z.string(), sessionId: z.string(), beforeSessionId: z.string().optional() }) }),
+  z.object({ code: z.literal('directory-unreadable'), message: z.string(), details: z.object({ path: z.string() }) }),
+  z.object({ code: z.literal('directory-exists'), message: z.string(), details: z.object({ path: z.string() }) }),
+  z.object({ code: z.literal('directory-create-failed'), message: z.string(), details: z.object({ path: z.string() }) }),
+  z.object({ code: z.literal('directory-picker-unavailable'), message: z.string(), details: z.object({ capability: z.string() }) }),
   z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
+  z.object({ code: z.literal('queue-item-not-found'), message: z.string(), details: z.object({ itemId: z.string() }) }),
+  z.object({ code: z.literal('command-error'), message: z.string(), details: z.object({}) }),
+  z.object({ code: z.literal('unknown-command'), message: z.string(), details: z.object({}) }),
+  z.object({ code: z.literal('settings-rejected'), message: z.string(), details: z.object({ ns: z.string() }) }),
+  z.object({ code: z.literal('settings-not-exposed'), message: z.string(), details: z.object({ ns: z.string() }) }),
+  z.object({ code: z.literal('settings-conflict'), message: z.string(), details: z.object({ ns: z.string(), expected: z.number(), actual: z.number() }) }),
+  z.object({ code: z.literal('credential-rejected'), message: z.string(), details: z.object({ ref: z.string() }) }),
+  z.object({ code: z.literal('title-invalid'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
+  z.object({ code: z.literal('fork-unavailable'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
   z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }),
 ]) as unknown as z.ZodType<RpcError>
 

packages/host/apiproxy/src/api/rpc.ts

@@ -9,6 +9,7 @@ import type { z as zCore } from 'zod'
 type ZodIssue = zCore.core.$ZodIssue
 import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand'
 
 /**
  * Message correlation id: the initiator mints it on a request; a response
@@ -39,7 +40,37 @@ export interface RpcErrorDetailsMap {
   'workspace-invalid-path': { path: string }
   'workspace-name-conflict': { name: string }
   'workspace-move-invalid': { workspaceId: string; sessionId: SessionId; beforeSessionId?: SessionId }
+  'directory-unreadable': { path: string }
+  'directory-exists': { path: string }
+  'directory-create-failed': { path: string }
+  'directory-picker-unavailable': { capability: string }
   'agent-busy': { reason: string }
+  'queue-item-not-found': { itemId: InboxItemId }
+  /** A known slash command reported a usage/state error; the message is the command's own text. */
+  'command-error': {}
+  /** A leading-/ prompt named no registered command; the message names the token. */
+  'unknown-command': {}
+  /**
+   * A settings write was refused (schema validation, unknown namespace,
+   * read-only provider, or storage failure); the message is the seam's text.
+   */
+  'settings-rejected': { ns: string }
+  /**
+   * A settings namespace exists in the seam but is outside the configuration
+   * plane's model-provider boundary, so this proxy neither reads nor writes
+   * it; the message names the namespace.
+   */
+  'settings-not-exposed': { ns: string }
+  /**
+   * A settings write carried an `expectedRevision` the namespace has already
+   * moved past: another writer (tab, editor, or an external file edit) landed
+   * first. The details carry both revisions so a client can re-read and retry.
+   */
+  'settings-conflict': { ns: string; expected: number; actual: number }
+  /** A credential write was refused (read-only shadowing layer or storage failure); the message is the seam's own text. */
+  'credential-rejected': { ref: string }
+  'title-invalid': { sessionId: SessionId }
+  'fork-unavailable': { sessionId: SessionId }
   'internal': {}
 }
 

packages/host/apiproxy/src/api/session-search.ts

@@ -0,0 +1,22 @@
+/** Maximum number of sessions returned by one sidebar search. */
+export const SESSION_SEARCH_RESULT_LIMIT = 20
+
+/** Maximum snippet length in Unicode code points. */
+export const SESSION_SEARCH_SNIPPET_MAX_CODE_POINTS = 240
+
+/**
+ * Return the longest prefix containing at most `maximum` Unicode code points.
+ * @param value - text to bound.
+ * @param maximum - non-negative code-point limit.
+ * @returns `value` unchanged when it fits, otherwise a code-point-safe prefix.
+ */
+export function truncateUnicodeCodePoints(value: string, maximum: number): string {
+  let count = 0
+  let end = 0
+  for (const codePoint of value) {
+    if (count === maximum) return value.slice(0, end)
+    count++
+    end += codePoint.length
+  }
+  return value
+}

packages/host/apiproxy/src/api/sessions.schema.ts

@@ -7,18 +7,27 @@
 
 import { z } from 'zod'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand'
 import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 import type {
   HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, SessionSummary,
+  ModelReasoningEffort, ModelTarget, SessionProjectionsBlock, SessionSearchItem, SessionSummary,
 } from './sessions.ts'
 import type { ToolEventView } from './events.ts'
 import type { WorkspaceId } from './workspace.ts'
+import {
+  SESSION_SEARCH_RESULT_LIMIT,
+  SESSION_SEARCH_SNIPPET_MAX_CODE_POINTS,
+  truncateUnicodeCodePoints,
+} from './session-search.ts'
 
 /** SessionId: one brand cast after shape validation (the only cast point in this domain). */
 export const sessionIdSchema = z.string().min(1) as unknown as z.ZodType<SessionId>
 
+/** InboxItemId: one brand cast after non-empty string validation. */
+export const inboxItemIdSchema = z.string().min(1) as unknown as z.ZodType<InboxItemId>
+
 /**
  * WorkspaceId: the workspace domain's one brand cast. Hosted here rather
  * than in workspace.schema because session.create references it while
@@ -37,7 +46,7 @@ export const sessionEventSchema = z.object({
   surfaceOp: z.unknown().optional(),
 }) as unknown as z.ZodType<SessionEvent>
 
-/** SessionSummary row of session.list. */
+/** SessionSummary row of session.list (`projections` reuses the history block's shape and schema). */
 export const sessionSummarySchema = z.object({
   sessionId: sessionIdSchema,
   updatedAt: z.number(),
@@ -45,7 +54,8 @@ export const sessionSummarySchema = z.object({
   blank: z.boolean(),
   parentSessionId: sessionIdSchema.optional(),
   cwd: z.string().optional(),
-}) satisfies z.ZodType<Wire<SessionSummary>>
+  projections: z.lazy(() => sessionProjectionsBlockSchema).optional(),
+}) as unknown as z.ZodType<Wire<SessionSummary>>
 
 /** session.list request payload (cursor is a reserved seat, unimplemented in v1). */
 export const sessionListRequestSchema = z.object({
@@ -53,9 +63,36 @@ export const sessionListRequestSchema = z.object({
 }) satisfies z.ZodType<Wire<RequestPayload<'session.list'>>>
 
 /** session.list response value. */
-export const sessionListValueSchema = z.object({
+export const sessionListValueSchema: z.ZodType<Wire<ResponseValue<'session.list'>>> = z.object({
   items: z.array(sessionSummarySchema),
-}) satisfies z.ZodType<Wire<ResponseValue<'session.list'>>>
+})
+
+/** Fixed wire bound for one interactive sidebar query. */
+const SESSION_SEARCH_QUERY_MAX_CHARS = 500
+
+/** session.search request payload. */
+export const sessionSearchRequestSchema = z.object({
+  query: z.string().trim().min(1).max(SESSION_SEARCH_QUERY_MAX_CHARS)
+    .refine(query => !query.includes('\0'), { message: 'search query must not contain NUL' }),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.search'>>>
+
+/** One session.search result. */
+export const sessionSearchItemSchema = z.object({
+  sessionId: sessionIdSchema,
+  snippet: z.string().refine(
+    snippet => truncateUnicodeCodePoints(
+      snippet,
+      SESSION_SEARCH_SNIPPET_MAX_CODE_POINTS,
+    ) === snippet,
+    { message: `search snippet must contain at most ${SESSION_SEARCH_SNIPPET_MAX_CODE_POINTS} Unicode code points` },
+  ),
+}) satisfies z.ZodType<Wire<SessionSearchItem>>
+
+/** session.search response value. */
+export const sessionSearchValueSchema = z.object({
+  items: z.array(sessionSearchItemSchema).max(SESSION_SEARCH_RESULT_LIMIT),
+  hasMore: z.boolean(),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.search'>>>
 
 /** session.create request payload (at most one of workspaceId / cwd). */
 export const sessionCreateRequestSchema = z.object({
@@ -72,6 +109,29 @@ export const sessionCreateValueSchema = z.object({
   sessionId: sessionIdSchema,
 }) satisfies z.ZodType<Wire<ResponseValue<'session.create'>>>
 
+/** session.rename request payload (raw title; host-side normalization decides acceptance). */
+export const sessionRenameRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  title: z.string(),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.rename'>>>
+
+/** session.rename response value (the normalized accepted title and its event seq). */
+export const sessionRenameValueSchema = z.object({
+  title: z.string().min(1),
+  seq: z.number().int().nonnegative(),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.rename'>>>
+
+/** session.fork request payload (atSeq anchors the completed-turn cut). */
+export const sessionForkRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  atSeq: z.number().int().nonnegative().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.fork'>>>
+
+/** session.fork response value (the child session id). */
+export const sessionForkValueSchema = z.object({
+  sessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<ResponseValue<'session.fork'>>>
+
 /** session.history request payload (beforeSeq/maxMessages page backwards from the window tail). */
 export const sessionHistoryRequestSchema = z.object({
   sessionId: sessionIdSchema,
@@ -139,17 +199,22 @@ export const historyEntrySchema = z.object({
   view: toolEventViewSchema.optional(),
 }) satisfies z.ZodType<Wire<HistoryEntry>>
 
-/** One todo item of the tail page's session-level projection (the todo/write payload shape). */
-export const todoItemSchema = z.object({
-  content: z.string(),
-  status: z.union([z.literal('pending'), z.literal('in_progress'), z.literal('completed')]),
-})
+/**
+ * Projection baseline passthrough: `values` stays a wide record — each value
+ * was already parsed by its provider's own schema on the host side, and
+ * deep-validating here would import every domain's schema into the carrier.
+ */
+export const sessionProjectionsBlockSchema = z.object({
+  // -1 = empty log (the lastSeq convention of session/subscribed).
+  asOfSeq: z.number().int().min(-1),
+  values: z.record(z.string(), z.unknown()),
+}) as unknown as z.ZodType<SessionProjectionsBlock>
 
-/** session.history response value. */
+/** session.history response value (projections rides the tail page only). */
 export const sessionHistoryValueSchema = z.object({
   events: z.array(historyEntrySchema),
   hasMore: z.boolean(),
-  todos: z.array(todoItemSchema).optional(),
+  projections: sessionProjectionsBlockSchema.optional(),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.history'>>>
 
 /** session.models request payload. */
@@ -187,11 +252,30 @@ export const sessionPromptRequestSchema = z.object({
   content: z.array(contentBlockSchema),
 }) as unknown as z.ZodType<RequestPayload<'session.prompt'>>
 
-/** session.prompt response value. */
+/** session.prompt response value (the command slot appears only when the prompt dispatched a slash command). */
 export const sessionPromptValueSchema = z.object({
   accepted: z.literal(true),
+  command: z.object({
+    kind: z.literal('success'),
+    text: z.string().optional(),
+  }).optional(),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.prompt'>>>
 
+/** session.updateQueue request payload. */
+export const sessionUpdateQueueRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  itemId: inboxItemIdSchema,
+  action: z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('edit'), content: z.array(contentBlockSchema) }),
+    z.object({ kind: z.literal('remove') }),
+  ]),
+}) as unknown as z.ZodType<RequestPayload<'session.updateQueue'>>
+
+/** session.updateQueue response value. */
+export const sessionUpdateQueueValueSchema = z.object({
+  accepted: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.updateQueue'>>>
+
 /** session.cancel request payload. */
 export const sessionCancelRequestSchema = z.object({
   sessionId: sessionIdSchema,

packages/host/apiproxy/src/api/sessions.ts

@@ -5,7 +5,11 @@
  */
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
-import type { SessionEvent, SessionId, TodoItem } from '@deepseek-ai/dsh-session/types'
+import type { InboxItemId } from '@deepseek-ai/dsh-agent/brand'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+// The pure-type outlet: api/ is browser-importable, and the package root's
+// cordis Context merge (via dsh-agent) must not enter client aggregates.
+import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types'
 import type { RpcId, RpcRequest, RpcResponse } from './rpc.ts'
 import type { ToolEventView } from './events.ts'
 import type { WorkspaceId } from './workspace.ts'
@@ -32,6 +36,23 @@ export interface HistoryEntry {
   view?: ToolEventView
 }
 
+/**
+ * The projection baseline riding the history tail page: one synchronous cut
+ * over every registered projection unit, read from the registry's watermark
+ * cache. `asOfSeq` is the seq of the last committed event every value
+ * reflects — the window tail event seq (`-1` for an empty log, mirroring
+ * `session/subscribed.lastSeq`), directly comparable with
+ * `session/projection` frame seqs under the client's higher-seq-wins rule. A
+ * key absent from `values` means the capability is absent (its domain plugin
+ * is unmounted).
+ */
+export interface SessionProjectionsBlock {
+  /** Seq of the last event the values reflect; -1 for an empty log. */
+  asOfSeq: number
+  /** Whole current value per registered projection key. */
+  values: Partial<SessionProjectionMap>
+}
+
 /** Complete model target selected for one session. */
 export interface ModelTarget {
   /** Registered provider route. */
@@ -104,25 +125,55 @@ export interface SessionModels {
   failures: ModelCatalogFailure[]
 }
 
+/** A client-requested mutation of one still-pending queue item. */
+export type QueueAction =
+  | { kind: 'edit'; content: ContentBlock[] }
+  | { kind: 'remove' }
+
 /** Session list entry (v1 builds no index: list does readdir+stat). */
 export interface SessionSummary {
   sessionId: SessionId
-  /** Persisted file mtime. */
+  /**
+   * Last activity. Attached: the last non-`session/end-seed` event, since a
+   * pickup is not activity. Cold: the log's mtime, or `createdAt` for a backend
+   * with no per-session file (README Known Limitations covers the skew).
+   */
   updatedAt: number
   /** Status of the attached agent; always false for cold (unattached) sessions. */
   running: boolean
   /**
-   * Derived emptiness bit: true while the session log holds zero events (no
-   * user message yet). Clients hide blank sessions from lists and reuse them
-   * for New Session on the same workspace. Always false for cold sessions —
-   * lazy persistence keeps a never-appended session out of the store, so a
-   * listed cold session necessarily has events.
+   * Derived conversation-not-started bit: true while no turn has run (no
+   * prompt was accepted yet). Standalone plugin events — command lifecycle
+   * records, plan/mode, titles, goals — do not open a turn and therefore do
+   * not clear it. Clients hide blank sessions from lists and reuse them for
+   * New Session on the same workspace. Always false for cold sessions —
+   * lazy persistence keeps a never-appended session out of the store, and a
+   * listed cold session's log holds its turns.
    */
   blank: boolean
   /** fork/spawn lineage (session.header.parentSession passthrough); absent for root sessions. */
   parentSessionId?: SessionId
   /** Session working directory (header.cwd passthrough); absent when unrecorded. */
   cwd?: string
+  /**
+   * Projection baseline for this row, with zero log loads: attached sessions
+   * read the registry's live watermark cut; cold sessions read the persisted
+   * projection cache's stored rows — as stale as that session's last durable
+   * checkpoint (`asOfSeq` says exactly how stale), never wrong, and directly
+   * seedable into the client's per-session value store under its
+   * higher-seq-wins rule (a list baseline can never overwrite a newer push
+   * frame). Absent when no value is available (no registry, no cache row for
+   * a cold session, or a fail-soft cache read miss); a listing client treats
+   * absence as "no title yet", exactly like a blank session.
+   */
+  projections?: SessionProjectionsBlock
+}
+
+/** One session-content search result; display metadata stays owned by `session.list`. */
+export interface SessionSearchItem {
+  sessionId: SessionId
+  /** Plain-text excerpt around the strongest matching visible message. */
+  snippet: string
 }
 
 /** Session-domain unary methods (the map keys session.* of RpcMethodMap). */
@@ -130,6 +181,16 @@ export interface SessionsApi {
   /** Lists persisted sessions (updatedAt descending). v1 returns everything; cursor is a reserved seat, unimplemented. */
   list(request: RpcRequest<{ cursor?: string }>): Promise<RpcResponse<{ items: SessionSummary[] }>>
 
+  /**
+   * Searches the current user/assistant/steering message surface across
+   * sessions visible to `list`. Results contain at most 20 sessions and carry
+   * no continuation cursor; `hasMore` asks the client to refine the query.
+   */
+  search(
+    request: RpcRequest<{ query: string }>,
+    signal: AbortSignal,
+  ): Promise<RpcResponse<{ items: SessionSearchItem[]; hasMore: boolean }>>
+
   /**
    * Creates a real session and its idle agent. At most one of `workspaceId` /
    * `cwd` is accepted; an omitted project uses the Host cwd. A caller may
@@ -142,20 +203,23 @@ export interface SessionsApi {
   Promise<RpcResponse<{ sessionId: SessionId }>>
 
   /**
-   * Reads a window of history events; page boundaries align to message boundaries: one page =
-   * all raw events owned by a whole number of messages (including their chunk / tool events),
-   * never cut mid-message. The tail page (beforeSeq absent) additionally carries the in-flight
+   * Reads a window of history events; page boundaries align to append-origin message
+   * boundaries: one page = all raw events owned by a whole number of such messages (including
+   * their chunk / tool events), never cut mid-message. Model-only replacement copies consume no
+   * `maxMessages`, so a compaction's provenance stays on the page of its replacement. The tail
+   * page (beforeSeq absent) additionally carries the in-flight
    * partial — chunk events already emitted for the last unfinalized message.
    * Each entry pairs the raw SessionEvent with the host-computed view (tool events whose
    * presenter produced one, evaluated against the registry at pagination time); the client
    * rebuilds the surface from the events with the shared fold.
-   * The tail page (beforeSeq absent) also carries `todos` — the session's current todo
-   * projection (latest `todo/write` over the FULL log, independent of the page window) —
-   * so a paged client restores the plan without walking history; absent when the session
-   * never wrote one. Older pages omit it (the projection is session-level, not per-page).
+   * The tail page — and only the tail page — additionally carries `projections`
+   * when the deployment mounts the session-projection registry: every moment
+   * the client needs a fresh baseline already pulls the tail page, and
+   * loadOlder (the only beforeSeq path) is the only path that never needs one.
+   * A deployment without the registry serves histories without the block.
    */
   history(request: RpcRequest<{ sessionId: SessionId; beforeSeq?: number; maxMessages?: number }>):
-  Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean; todos?: TodoItem[] }>>
+  Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean; projections?: SessionProjectionsBlock }>>
 
   /** Reads a fresh advisory model directory for this session. Provider lookups run independently. */
   models(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<SessionModels>>
@@ -173,10 +237,49 @@ export interface SessionsApi {
   }>):
   Promise<RpcResponse<{ selected: ModelTarget }>>
 
+  /**
+   * Renames a session: appends a `session/title` event with the `user`
+   * source, which pins the title against automatic regeneration. The
+   * normalized accepted title and the title event's seq return so the caller
+   * can settle its projection cell without waiting for the push frame. A
+   * title that normalizes to empty fails with `title-invalid`.
+   */
+  rename(request: RpcRequest<{ sessionId: SessionId; title: string }>):
+  Promise<RpcResponse<{ title: string; seq: number }>>
+
+  /**
+   * Sends a message. content is core's ContentBlock[] verbatim; mode maps 1:1 — queue→send, steer→steer.
+   * A prompt whose content is exactly one text block starting with '/' is a slash command: the host
+   * executes it through the command registry (mode-agnostic) and it is never sent to the model. A
+   * successful command returns ok with the command slot (its success text, when the command produced
+   * one — carried for future rendering; the state change is the feedback). A usage/state error is an
+   * RPC error with code command-error; an unrecognized name is an RPC error with code unknown-command.
+   */
+  /**
+   * Forks a new session from a completed-turn prefix of the source. `atSeq`
+   * anchors the cut: the boundary is the first `turn/end` at or after it
+   * (a message's fork button passes the message seq, so the fork includes
+   * that whole turn); a boundary past the log end, or an omitted `atSeq`,
+   * falls back to the source's last completed turn. An in-log anchor whose
+   * turn is still open fails with `fork-unavailable` instead of clipping to
+   * an earlier turn. The child inherits the source cwd, latest logged model
+   * target, workspace attachment, and `parentSessionId` lineage; the seed
+   * prefix carries the source title.
+   */
+  fork(request: RpcRequest<{ sessionId: SessionId; atSeq?: number }>):
+  Promise<RpcResponse<{ sessionId: SessionId }>>
+
   /** Sends a message. content is core's ContentBlock[] verbatim; mode maps 1:1 — queue→send, steer→steer. */
   prompt(request: RpcRequest<{ sessionId: SessionId; mode: 'queue' | 'steer'; content: ContentBlock[] }>):
+  Promise<RpcResponse<{ accepted: true; command?: { kind: 'success'; text?: string } }>>
+
+  /**
+   * Edits or removes one pending queued occurrence.
+   */
+  updateQueue(request: RpcRequest<{ sessionId: SessionId; itemId: InboxItemId; action: QueueAction }>):
   Promise<RpcResponse<{ accepted: true }>>
 
-  /** Stops: clears both FIFOs + aborts the current step (1:1 with agent.cancel). */
+  /** Stops the active turn, preserving pending inbox work that resumes in FIFO order after cancellation settles. */
   cancel(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ accepted: true }>>
+
 }

packages/host/apiproxy/src/api/settings.schema.ts

@@ -0,0 +1,72 @@
+/**
+ * settings domain zod schemas (names derived from map keys: settingsDescribeRequestSchema /
+ * settingsDescribeValueSchema / settingsUpdate* / settingsReplace*).
+ */
+
+import { z } from 'zod'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import type { SettingsNamespaceView, SettingsPathOpView, SettingsSecretView } from './settings.ts'
+
+/** One redacted secret slot. */
+export const settingsSecretViewSchema = z.object({
+  path: z.array(z.string()),
+  set: z.boolean(),
+}) satisfies z.ZodType<Wire<SettingsSecretView>>
+
+/** SettingsNamespaceView row of settings.describe and the write responses. */
+export const settingsNamespaceViewSchema = z.object({
+  ns: z.string().min(1),
+  schema: z.unknown(),
+  value: z.unknown(),
+  base: z.unknown().optional(),
+  user: z.unknown().optional(),
+  applies: z.union([z.literal('live'), z.literal('restart')]),
+  secrets: z.array(settingsSecretViewSchema),
+  revision: z.number(),
+}) satisfies z.ZodType<Wire<SettingsNamespaceView>>
+
+/** settings.describe request payload. */
+export const settingsDescribeRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'settings.describe'>>>
+
+/** settings.describe response value. */
+export const settingsDescribeValueSchema = z.object({
+  writable: z.boolean(),
+  namespaces: z.array(settingsNamespaceViewSchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'settings.describe'>>>
+
+/** settings.update request payload. */
+export const settingsUpdateRequestSchema = z.object({
+  ns: z.string().min(1),
+  patch: z.record(z.string(), z.unknown()),
+  expectedRevision: z.number().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'settings.update'>>>
+
+/** settings.update response value: the namespace's new redacted view. */
+export const settingsUpdateValueSchema = settingsNamespaceViewSchema satisfies z.ZodType<Wire<ResponseValue<'settings.update'>>>
+
+/** settings.replace request payload. */
+export const settingsReplaceRequestSchema = z.object({
+  ns: z.string().min(1),
+  section: z.record(z.string(), z.unknown()),
+  expectedRevision: z.number().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'settings.replace'>>>
+
+/** One path-addressed edit of settings.mutate. */
+export const settingsPathOpSchema = z.discriminatedUnion('op', [
+  z.object({ op: z.literal('set'), path: z.array(z.string()), value: z.unknown() }),
+  z.object({ op: z.literal('unset'), path: z.array(z.string()) }),
+]) as unknown as z.ZodType<Wire<SettingsPathOpView>>
+
+/** settings.mutate request payload. */
+export const settingsMutateRequestSchema = z.object({
+  ns: z.string().min(1),
+  ops: z.array(settingsPathOpSchema),
+  expectedRevision: z.number().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'settings.mutate'>>>
+
+/** settings.mutate response value: the namespace's new redacted view. */
+export const settingsMutateValueSchema = settingsNamespaceViewSchema satisfies z.ZodType<Wire<ResponseValue<'settings.mutate'>>>
+
+/** settings.replace response value. */
+export const settingsReplaceValueSchema = settingsNamespaceViewSchema satisfies z.ZodType<Wire<ResponseValue<'settings.replace'>>>

packages/host/apiproxy/src/api/settings.ts

@@ -0,0 +1,90 @@
+/**
+ * settings domain contract: the web face of the user-settings seam
+ * (`ctx.settings`). Every payload that leaves this domain is redacted by the
+ * seam (`describe({ redactSecrets: true })` semantics): `role('secret')`
+ * fields never ride a response in any layer, and the `secrets` slot list is
+ * how a form learns a write-only field exists and whether it is configured.
+ */
+
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+
+/** One schema-declared secret slot inside a redacted namespace value. */
+export interface SettingsSecretView {
+  /** Path from the section root to the removed field. */
+  path: string[]
+  /** Whether the slot currently holds a value (the value itself never rides). */
+  set: boolean
+}
+
+/** Wire view of one registered settings namespace. */
+export interface SettingsNamespaceView {
+  /** Namespace key (`llm-deepseek`, `llm-pi-ai`, …). */
+  ns: string
+  /** Serialized schemastery schema envelope (`schema.toJSON()`); rehydrate with `new Schema(json)`. */
+  schema: unknown
+  /** Redacted resolved value (schema defaults → composition base → user layer). */
+  value: unknown
+  /** Redacted composition base layer, when the registrant declared one. */
+  base?: unknown
+  /** Redacted raw user section, when one exists; a field's presence here marks it user-overridden. */
+  user?: unknown
+  /** When the owner applies changes. */
+  applies: 'live' | 'restart'
+  /** Every schema-declared secret slot with its configured state. */
+  secrets: SettingsSecretView[]
+  /**
+   * Monotonic revision of the raw user section this view was read at. Send it
+   * back as `expectedRevision` on a write so a stale editor is refused rather
+   * than silently overwriting a concurrent change.
+   */
+  revision: number
+}
+
+/**
+ * One path-addressed edit carried by `settings.mutate`. `set` writes the
+ * value at the path (creating intermediate objects); `unset` removes it. The
+ * empty path addresses the section root.
+ */
+export type SettingsPathOpView =
+  | { op: 'set'; path: string[]; value: unknown }
+  | { op: 'unset'; path: string[] }
+
+/** Settings-domain unary methods (the map keys settings.* of RpcMethodMap). */
+export interface SettingsApi {
+  /**
+   * Describe every registered namespace: redacted layered values plus the
+   * serialized schema a client renders its form from. `writable: false`
+   * (read-only provider) tells the client to disable every write control.
+   */
+  describe(request: RpcRequest<{}>): Promise<RpcResponse<{ writable: boolean; namespaces: SettingsNamespaceView[] }>>
+
+  /**
+   * Merge a patch into one namespace's user layer (validate → persist →
+   * commit). Secret-role fields may be INCLUDED in the patch (write-only
+   * direction); a form that leaves a secret untouched simply omits it and the
+   * merge preserves the stored value. Responds with the namespace's new
+   * redacted view; a schema or storage rejection is `settings-rejected`.
+   */
+  update(request: RpcRequest<{ ns: string; patch: object; expectedRevision?: number }>): Promise<RpcResponse<SettingsNamespaceView>>
+
+  /**
+   * Replace one namespace's user section wholesale — the removal/reset path a
+   * merge cannot express (`section: {}` resets to composition defaults). Keys
+   * absent from `section` are dropped, secrets included: a client must first
+   * fold the descriptor's `user` layer (and re-supply any secret it wants to
+   * keep) or accept the reset.
+   */
+  replace(request: RpcRequest<{ ns: string; section: object; expectedRevision?: number }>): Promise<RpcResponse<SettingsNamespaceView>>
+
+  /**
+   * Apply path-addressed edits to one namespace's user section, resolved
+   * against the section as stored — NOT against whatever the caller last
+   * read. This is the removal path for any client holding the redacted
+   * descriptor: it names the field it means, so a secret the wire never
+   * returned cannot be deleted as a side effect. `replace` remains the
+   * deliberate wholesale reset.
+   */
+  mutate(
+    request: RpcRequest<{ ns: string; ops: SettingsPathOpView[]; expectedRevision?: number }>,
+  ): Promise<RpcResponse<SettingsNamespaceView>>
+}

packages/host/apiproxy/src/api/skills.ts

@@ -20,6 +20,6 @@ export interface SkillEntry {
 
 /** Skill-domain unary methods (the map key skill.* of RpcMethodMap). */
 export interface SkillsApi {
-  /** Lists model-invocable skills for the addressed session's project root. */
+  /** Lists skills usable by the browser's user-selected model-reference path. */
   list(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ skills: readonly SkillEntry[] }>>
 }

packages/host/apiproxy/src/api/workspace.schema.ts

@@ -28,6 +28,7 @@ export const workspaceListRequestSchema = z.object({}) satisfies z.ZodType<Wire<
 /** workspace.list response value. */
 export const workspaceListValueSchema = z.object({
   items: z.array(workspaceViewSchema),
+  archivedSessionIds: z.array(sessionIdSchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'workspace.list'>>>
 
 /** workspace.create request payload: exactly one of path/name (the contract's create spellings). */
@@ -80,3 +81,13 @@ export const workspaceInsertSessionBeforeRequestSchema = z.object({
 export const workspaceInsertSessionBeforeValueSchema = z.object({
   workspace: workspaceViewSchema,
 }) satisfies z.ZodType<Wire<ResponseValue<'workspace.insertSessionBefore'>>>
+
+/** workspace.archiveSession request payload. */
+export const workspaceArchiveSessionRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'workspace.archiveSession'>>>
+
+/** workspace.archiveSession response value: the full updated archive set. */
+export const workspaceArchiveSessionValueSchema = z.object({
+  archivedSessionIds: z.array(sessionIdSchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'workspace.archiveSession'>>>

packages/host/apiproxy/src/api/workspace.ts

@@ -22,7 +22,7 @@ export interface WorkspaceView {
   workspaceId: WorkspaceId
   /** Canonical directory path (host-side realpath canon). */
   path: string
-  /** Unique display title (defaults to the path basename at create). */
+  /** Display title (defaults to the path basename at create). */
   title: string
   /**
    * Sessions accounted under this workspace, in manually owned order
@@ -37,8 +37,13 @@ export interface WorkspaceView {
 
 /** Workspace-domain unary methods (the map keys workspace.* of RpcMethodMap). */
 export interface WorkspaceApi {
-  /** Lists all workspaces in the registry's durable display order. */
-  list(request: RpcRequest<{}>): Promise<RpcResponse<{ items: WorkspaceView[] }>>
+  /**
+   * Lists all workspaces in the registry's durable display order, plus the
+   * registry-global archive set (the reconnect baseline of
+   * `host/archived-sessions-changed`). Archived sessions stay in their
+   * workspace's `sessionIds` account; grouping surfaces hide them.
+   */
+  list(request: RpcRequest<{}>): Promise<RpcResponse<{ items: WorkspaceView[]; archivedSessionIds: SessionId[] }>>
 
   /**
    * Creates (or idempotently resolves) a workspace. Exactly one of `path` /
@@ -48,8 +53,8 @@ export interface WorkspaceApi {
    * root before registering. Either spelling resolving to a directory already
    * owned by a workspace returns that workspace (`created: false`) for the
    * existing-folder spelling. Create-by-name rejects an existing title with
-   * `workspace-name-conflict`; a new path whose basename duplicates another
-   * Workspace title is rejected by the registry with the same code.
+   * `workspace-name-conflict`; path adoption allows distinct canonical paths
+   * whose basenames produce the same display title.
    * A new name-created workspace uses `name` as both directory name and title;
    * a path-created workspace uses the registry's basename title default.
    */
@@ -86,4 +91,15 @@ export interface WorkspaceApi {
     sessionId: SessionId
     beforeSessionId?: SessionId
   }>): Promise<RpcResponse<{ workspace: WorkspaceView }>>
+
+  /**
+   * Adds one session to the registry-global archive set: the session
+   * disappears from every grouping surface but keeps its session log and its
+   * workspace accounting slot (a future unarchive restores its position).
+   * Idempotent for an already archived id. A session neither live nor in
+   * session persistence fails with `session-not-found`. Returns the full
+   * updated set (same snapshot the changed frame carries).
+   */
+  archiveSession(request: RpcRequest<{ sessionId: SessionId }>):
+  Promise<RpcResponse<{ archivedSessionIds: SessionId[] }>>
 }

packages/host/apiproxy/src/fetch/client.ts

@@ -13,17 +13,25 @@ import { RpcId } from '../api/rpc.ts'
 import type { Wire } from '../api/rpc.schema.ts'
 import { rpcReceiptSchema, serverRequestSchema, serverResponseSchema } from '../api/rpc.schema.ts'
 import { hostFrameSchema, muxFrameSchema } from '../api/events.schema.ts'
-import { hostDescribeValueSchema, hostPickDirectoryValueSchema } from '../api/host.schema.ts'
+import {
+  hostCreateDirectoryValueSchema, hostDescribeValueSchema,
+  hostListDirectoryValueSchema, hostOpenPathValueSchema, hostPickDirectoryValueSchema,
+} from '../api/host.schema.ts'
 import {
   sessionCancelValueSchema,
   sessionCreateValueSchema,
+  sessionForkValueSchema,
   sessionHistoryValueSchema,
   sessionListValueSchema,
   sessionModelsValueSchema,
   sessionPromptValueSchema,
+  sessionRenameValueSchema,
+  sessionSearchValueSchema,
   sessionSelectModelValueSchema,
+  sessionUpdateQueueValueSchema,
 } from '../api/sessions.schema.ts'
 import {
+  workspaceArchiveSessionValueSchema,
   workspaceCreateValueSchema,
   workspaceDeleteValueSchema,
   workspaceInsertSessionBeforeValueSchema,
@@ -32,14 +40,30 @@ import {
 } from '../api/workspace.schema.ts'
 import { commandExecuteValueSchema, commandListValueSchema } from '../api/commands.schema.ts'
 import { skillListValueSchema } from '../api/skills.schema.ts'
+import {
+  goalCreateValueSchema,
+  goalEditValueSchema,
+  goalPauseValueSchema,
+  goalResumeValueSchema,
+  goalCompleteValueSchema,
+  goalClearValueSchema,
+} from '../api/goals.schema.ts'
+import {
+  settingsDescribeValueSchema, settingsMutateValueSchema, settingsReplaceValueSchema, settingsUpdateValueSchema,
+} from '../api/settings.schema.ts'
+import {
+  credentialsDescribeValueSchema, credentialsSetValueSchema, credentialsUnsetValueSchema,
+} from '../api/credentials.schema.ts'
+import { llmModelsValueSchema, llmProvidersValueSchema } from '../api/llm.schema.ts'
 
 /**
  * Client consumption face of the contract (shape a): same domain tree as ApiProxy, but unary
  * methods take the business payload directly — the carrier mints the rpcId and wraps the
  * envelope. Business code needing the call's rpcId reads it from the RpcResponse echo.
- * Unary methods and respond accept an optional external AbortSignal as the last parameter
- * (merged with the instance timeout via AbortSignal.any; same "signal rides beside the
- * request, never on the wire" discipline as the stream signatures).
+ * Unary methods and respond accept an optional external AbortSignal as the last parameter.
+ * Bounded calls merge it with the instance timeout via AbortSignal.any; user-paced calls
+ * carry only that external signal. In both cases the signal rides beside the request, never
+ * on the wire, like the stream signatures.
  * Stream methods accept an optional onOpen callback: it fires once the SSE transport is
  * readable (response headers received, before any frame) — the "stream established" signal
  * connection controllers need for the readiness handshake. Generators are lazy, so the
@@ -51,16 +75,23 @@ import { skillListValueSchema } from '../api/skills.schema.ts'
 export interface IApiClient {
   sessions: {
     list(payload: RequestPayload<'session.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.list'>>>
+    search(payload: RequestPayload<'session.search'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.search'>>>
     create(payload: RequestPayload<'session.create'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.create'>>>
     history(payload: RequestPayload<'session.history'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.history'>>>
     models(payload: RequestPayload<'session.models'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.models'>>>
     selectModel(payload: RequestPayload<'session.selectModel'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.selectModel'>>>
+    rename(payload: RequestPayload<'session.rename'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.rename'>>>
+    fork(payload: RequestPayload<'session.fork'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.fork'>>>
     prompt(payload: RequestPayload<'session.prompt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.prompt'>>>
+    updateQueue(payload: RequestPayload<'session.updateQueue'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.updateQueue'>>>
     cancel(payload: RequestPayload<'session.cancel'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.cancel'>>>
   }
   host: {
     describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
     pickDirectory(payload: RequestPayload<'host.pickDirectory'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.pickDirectory'>>>
+    listDirectory(payload: RequestPayload<'host.listDirectory'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.listDirectory'>>>
+    createDirectory(payload: RequestPayload<'host.createDirectory'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.createDirectory'>>>
+    openPath(payload: RequestPayload<'host.openPath'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.openPath'>>>
   }
   workspace: {
     list(payload: RequestPayload<'workspace.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.list'>>>
@@ -68,6 +99,7 @@ export interface IApiClient {
     rename(payload: RequestPayload<'workspace.rename'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.rename'>>>
     delete(payload: RequestPayload<'workspace.delete'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.delete'>>>
     insertSessionBefore(payload: RequestPayload<'workspace.insertSessionBefore'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.insertSessionBefore'>>>
+    archiveSession(payload: RequestPayload<'workspace.archiveSession'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.archiveSession'>>>
   }
   commands: {
     list(payload: RequestPayload<'command.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'command.list'>>>
@@ -80,6 +112,29 @@ export interface IApiClient {
     mux(payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>>
     host(payload: Parameters<ApiProxy['events']['host']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<HostFrame>>
   }
+  goals: {
+    create(payload: RequestPayload<'goal.create'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.create'>>>
+    edit(payload: RequestPayload<'goal.edit'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.edit'>>>
+    pause(payload: RequestPayload<'goal.pause'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.pause'>>>
+    resume(payload: RequestPayload<'goal.resume'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.resume'>>>
+    complete(payload: RequestPayload<'goal.complete'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.complete'>>>
+    clear(payload: RequestPayload<'goal.clear'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'goal.clear'>>>
+  }
+  settings: {
+    describe(payload: RequestPayload<'settings.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'settings.describe'>>>
+    update(payload: RequestPayload<'settings.update'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'settings.update'>>>
+    replace(payload: RequestPayload<'settings.replace'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'settings.replace'>>>
+    mutate(payload: RequestPayload<'settings.mutate'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'settings.mutate'>>>
+  }
+  credentials: {
+    describe(payload: RequestPayload<'credentials.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'credentials.describe'>>>
+    set(payload: RequestPayload<'credentials.set'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'credentials.set'>>>
+    unset(payload: RequestPayload<'credentials.unset'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'credentials.unset'>>>
+  }
+  llm: {
+    providers(payload: RequestPayload<'llm.providers'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'llm.providers'>>>
+    models(payload: RequestPayload<'llm.models'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'llm.models'>>>
+  }
   /** client-response passthrough (rpcId is a backfill of the server-request's id — never minted here). */
   respond(message: ClientResponse, signal?: AbortSignal): Promise<RpcReceipt>
 }
@@ -90,27 +145,53 @@ export interface IApiClient {
  */
 const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseValue<K>>> } = {
   'session.list': sessionListValueSchema,
+  'session.search': sessionSearchValueSchema,
   'session.create': sessionCreateValueSchema,
   'session.history': sessionHistoryValueSchema,
   'session.models': sessionModelsValueSchema,
   'session.selectModel': sessionSelectModelValueSchema,
+  'session.rename': sessionRenameValueSchema,
+  'session.fork': sessionForkValueSchema,
   'session.prompt': sessionPromptValueSchema,
+  'session.updateQueue': sessionUpdateQueueValueSchema,
   'session.cancel': sessionCancelValueSchema,
   'host.describe': hostDescribeValueSchema,
   'host.pickDirectory': hostPickDirectoryValueSchema,
+  'host.listDirectory': hostListDirectoryValueSchema,
+  'host.createDirectory': hostCreateDirectoryValueSchema,
+  'host.openPath': hostOpenPathValueSchema,
   'workspace.list': workspaceListValueSchema,
   'workspace.create': workspaceCreateValueSchema,
   'workspace.rename': workspaceRenameValueSchema,
   'workspace.delete': workspaceDeleteValueSchema,
   'workspace.insertSessionBefore': workspaceInsertSessionBeforeValueSchema,
+  'workspace.archiveSession': workspaceArchiveSessionValueSchema,
   'command.list': commandListValueSchema,
   'command.execute': commandExecuteValueSchema,
   'skill.list': skillListValueSchema,
+  'goal.create': goalCreateValueSchema,
+  'goal.edit': goalEditValueSchema,
+  'goal.pause': goalPauseValueSchema,
+  'goal.resume': goalResumeValueSchema,
+  'goal.complete': goalCompleteValueSchema,
+  'goal.clear': goalClearValueSchema,
+  'settings.describe': settingsDescribeValueSchema,
+  'settings.update': settingsUpdateValueSchema,
+  'settings.replace': settingsReplaceValueSchema,
+  'settings.mutate': settingsMutateValueSchema,
+  'credentials.describe': credentialsDescribeValueSchema,
+  'credentials.set': credentialsSetValueSchema,
+  'credentials.unset': credentialsUnsetValueSchema,
+  'llm.providers': llmProvidersValueSchema,
+  'llm.models': llmModelsValueSchema,
 }
 
-/** Default unary timeout (rpc-compare 2026-07-19: a hung host must not leave callers pending forever). */
+/** Default timeout for bounded unary calls (rpc-compare 2026-07-19: a hung host must not leave callers pending forever). */
 const DEFAULT_TIMEOUT_MS = 30_000
 
+/** Whether a unary call uses the transport health deadline or only caller/connection cancellation. */
+type UnaryTimeoutPolicy = 'default' | 'caller-signal-only'
+
 /** URL base for in-process handler injection (fake authority, opencode precedent). */
 const INTERNAL_BASE = 'http://dsh.internal'
 
@@ -128,7 +209,7 @@ export abstract class AbstractApiClient implements IApiClient {
   private flushScheduled = false
   private readonly envelopeListeners = new Set<(batch: readonly RpcMessage[]) => void>()
 
-  /** @param timeoutMs - unary timeout; streams never time out (long-lived by nature). */
+  /** @param timeoutMs - timeout for bounded unary calls; user-paced calls and streams do not use it. */
   constructor(protected readonly timeoutMs: number = DEFAULT_TIMEOUT_MS) {}
 
   /** Transport aspect: browser fetch, injected handler.fetch, IPC bridge, ... */
@@ -183,15 +264,15 @@ export abstract class AbstractApiClient implements IApiClient {
 
   /**
    * Shared POST leg of both C→S carriers (callUnary/respond): JSON body,
-   * timeout merged with the caller's optional external signal, non-2xx → transport throw.
+   * optional default timeout merged with the caller's external signal, non-2xx → transport throw.
    */
   private async postJson(
     path: string,
     body: ClientRequest | ClientResponse,
     signal: AbortSignal | undefined,
-    useDefaultTimeout = true,
+    timeoutPolicy: UnaryTimeoutPolicy = 'default',
   ): Promise<Response> {
-    const requestSignal = useDefaultTimeout
+    const requestSignal = timeoutPolicy === 'default'
       ? signal === undefined
         ? AbortSignal.timeout(this.timeoutMs)
         : AbortSignal.any([AbortSignal.timeout(this.timeoutMs), signal])
@@ -215,11 +296,11 @@ export abstract class AbstractApiClient implements IApiClient {
     method: K,
     payload: RequestPayload<K>,
     signal?: AbortSignal,
-    useDefaultTimeout = true,
+    timeoutPolicy: UnaryTimeoutPolicy = 'default',
   ): Promise<RpcResponse<ResponseValue<K>>> {
     const message: ClientRequest = { type: 'client-request', rpcId: this.mintRpcId(), method, payload }
     this.onEnvelope(message)
-    const response = await this.postJson(`/api/${method}`, message, signal, useDefaultTimeout)
+    const response = await this.postJson(`/api/${method}`, message, signal, timeoutPolicy)
     const full = serverResponseSchema.parse(await response.json())
     this.onEnvelope(full)
     if (full.rpcId !== message.rpcId) throw new Error(`rpcId mismatch for ${method}: sent ${message.rpcId}, got ${full.rpcId}`)
@@ -292,11 +373,15 @@ export abstract class AbstractApiClient implements IApiClient {
 
   readonly sessions: IApiClient['sessions'] = {
     list: (payload, signal) => this.callUnary('session.list', payload, signal),
+    search: (payload, signal) => this.callUnary('session.search', payload, signal),
     create: (payload, signal) => this.callUnary('session.create', payload, signal),
     history: (payload, signal) => this.callUnary('session.history', payload, signal),
     models: (payload, signal) => this.callUnary('session.models', payload, signal),
     selectModel: (payload, signal) => this.callUnary('session.selectModel', payload, signal),
+    rename: (payload, signal) => this.callUnary('session.rename', payload, signal),
+    fork: (payload, signal) => this.callUnary('session.fork', payload, signal),
     prompt: (payload, signal) => this.callUnary('session.prompt', payload, signal),
+    updateQueue: (payload, signal) => this.callUnary('session.updateQueue', payload, signal),
     cancel: (payload, signal) => this.callUnary('session.cancel', payload, signal),
   }
 
@@ -304,7 +389,12 @@ export abstract class AbstractApiClient implements IApiClient {
     describe: (payload, signal) => this.callUnary('host.describe', payload, signal),
     // A native system dialog is user-paced and may legitimately stay open
     // longer than the normal unary deadline. Caller/connection aborts remain.
-    pickDirectory: (payload, signal) => this.callUnary('host.pickDirectory', payload, signal, false),
+    pickDirectory: (payload, signal) => this.callUnary(
+      'host.pickDirectory', payload, signal, 'caller-signal-only',
+    ),
+    listDirectory: (payload, signal) => this.callUnary('host.listDirectory', payload, signal),
+    createDirectory: (payload, signal) => this.callUnary('host.createDirectory', payload, signal),
+    openPath: (payload, signal) => this.callUnary('host.openPath', payload, signal),
   }
 
   readonly workspace: IApiClient['workspace'] = {
@@ -313,17 +403,49 @@ export abstract class AbstractApiClient implements IApiClient {
     rename: (payload, signal) => this.callUnary('workspace.rename', payload, signal),
     delete: (payload, signal) => this.callUnary('workspace.delete', payload, signal),
     insertSessionBefore: (payload, signal) => this.callUnary('workspace.insertSessionBefore', payload, signal),
+    archiveSession: (payload, signal) => this.callUnary('workspace.archiveSession', payload, signal),
   }
 
   readonly commands: IApiClient['commands'] = {
     list: (payload, signal) => this.callUnary('command.list', payload, signal),
-    execute: (payload, signal) => this.callUnary('command.execute', payload, signal),
+    // Command handlers are user-driven operations and may legitimately exceed
+    // the transport health deadline. Caller/connection aborts remain.
+    execute: (payload, signal) => this.callUnary(
+      'command.execute', payload, signal, 'caller-signal-only',
+    ),
   }
 
   readonly skills: IApiClient['skills'] = {
     list: (payload, signal) => this.callUnary('skill.list', payload, signal),
   }
 
+  readonly goals: IApiClient['goals'] = {
+    create: (payload, signal) => this.callUnary('goal.create', payload, signal),
+    edit: (payload, signal) => this.callUnary('goal.edit', payload, signal),
+    pause: (payload, signal) => this.callUnary('goal.pause', payload, signal),
+    resume: (payload, signal) => this.callUnary('goal.resume', payload, signal),
+    complete: (payload, signal) => this.callUnary('goal.complete', payload, signal),
+    clear: (payload, signal) => this.callUnary('goal.clear', payload, signal),
+  }
+
+  readonly settings: IApiClient['settings'] = {
+    describe: (payload, signal) => this.callUnary('settings.describe', payload, signal),
+    update: (payload, signal) => this.callUnary('settings.update', payload, signal),
+    replace: (payload, signal) => this.callUnary('settings.replace', payload, signal),
+    mutate: (payload, signal) => this.callUnary('settings.mutate', payload, signal),
+  }
+
+  readonly credentials: IApiClient['credentials'] = {
+    describe: (payload, signal) => this.callUnary('credentials.describe', payload, signal),
+    set: (payload, signal) => this.callUnary('credentials.set', payload, signal),
+    unset: (payload, signal) => this.callUnary('credentials.unset', payload, signal),
+  }
+
+  readonly llm: IApiClient['llm'] = {
+    providers: (payload, signal) => this.callUnary('llm.providers', payload, signal),
+    models: (payload, signal) => this.callUnary('llm.models', payload, signal),
+  }
+
   readonly events: IApiClient['events'] = {
     mux: (payload, signal, onOpen) => this.openMux(payload, signal, onOpen),
     host: (payload, signal, onOpen) => this.openHost(payload, signal, onOpen),

packages/host/apiproxy/src/fetch/handler.ts

@@ -2,8 +2,8 @@
  * Server side of the fetch carrier: maps an ApiProxy onto a pure
  * WHATWG Request->Response function. Two-level parse: full form (type/rpcId/method +
  * path==method) -> payload dispatched per method. HTTP status expresses only the carrier
- * (404 unknown path / 400 non-JSON body / 500 handler crash); business errors are always
- * 200 + ServerResponse.
+ * (404 unknown path / 415 non-JSON media type / 400 non-JSON body / 500 handler crash);
+ * business errors are always 200 + ServerResponse.
  */
 
 import { randomUUID } from 'node:crypto'
@@ -17,14 +17,23 @@ import { clientRequestSchema, clientResponseSchema } from '../api/rpc.schema.ts'
 import {
   sessionCancelRequestSchema,
   sessionCreateRequestSchema,
+  sessionForkRequestSchema,
   sessionHistoryRequestSchema,
   sessionListRequestSchema,
   sessionModelsRequestSchema,
   sessionPromptRequestSchema,
+  sessionRenameRequestSchema,
+  sessionSearchRequestSchema,
   sessionSelectModelRequestSchema,
+  sessionUpdateQueueRequestSchema,
 } from '../api/sessions.schema.ts'
-import { hostDescribeRequestSchema, hostPickDirectoryRequestSchema } from '../api/host.schema.ts'
 import {
+  hostCreateDirectoryRequestSchema, hostDescribeRequestSchema,
+  hostListDirectoryRequestSchema, hostOpenPathRequestSchema,
+  hostPickDirectoryRequestSchema,
+} from '../api/host.schema.ts'
+import {
+  workspaceArchiveSessionRequestSchema,
   workspaceCreateRequestSchema,
   workspaceDeleteRequestSchema,
   workspaceInsertSessionBeforeRequestSchema,
@@ -33,6 +42,21 @@ import {
 } from '../api/workspace.schema.ts'
 import { commandExecuteRequestSchema, commandListRequestSchema } from '../api/commands.schema.ts'
 import { skillListRequestSchema } from '../api/skills.schema.ts'
+import {
+  goalCreateRequestSchema,
+  goalEditRequestSchema,
+  goalPauseRequestSchema,
+  goalResumeRequestSchema,
+  goalCompleteRequestSchema,
+  goalClearRequestSchema,
+} from '../api/goals.schema.ts'
+import {
+  settingsDescribeRequestSchema, settingsMutateRequestSchema, settingsReplaceRequestSchema, settingsUpdateRequestSchema,
+} from '../api/settings.schema.ts'
+import {
+  credentialsDescribeRequestSchema, credentialsSetRequestSchema, credentialsUnsetRequestSchema,
+} from '../api/credentials.schema.ts'
+import { llmModelsRequestSchema, llmProvidersRequestSchema } from '../api/llm.schema.ts'
 
 /**
  * Unary dispatch table, keyed by (and compiler-locked to) RpcMethodMap: a map row without a
@@ -41,7 +65,8 @@ import { skillListRequestSchema } from '../api/skills.schema.ts'
  * Schemas anchor to the Wire<> widening (the repo-wide exactOptionalPropertyTypes accommodation
  * documented on Wire); the dispatch point carries the one Wire→exact cast.
  * Every invoke receives the carrier Request's signal; methods whose contract
- * declares a signal parameter (command.execute) forward it, the rest ignore it.
+ * declares a signal parameter (session.search and command.execute) forward it,
+ * the rest ignore it.
  */
 type UnaryRoutes = {
   [K in keyof RpcMethodMap]: {
@@ -52,22 +77,45 @@ type UnaryRoutes = {
 
 const UNARY_ROUTES: UnaryRoutes = {
   'session.list': { schema: sessionListRequestSchema, invoke: (api, r) => api.sessions.list(r) },
+  'session.search': { schema: sessionSearchRequestSchema, invoke: (api, r, signal) => api.sessions.search(r, signal) },
   'session.create': { schema: sessionCreateRequestSchema, invoke: (api, r) => api.sessions.create(r) },
   'session.history': { schema: sessionHistoryRequestSchema, invoke: (api, r) => api.sessions.history(r) },
   'session.models': { schema: sessionModelsRequestSchema, invoke: (api, r) => api.sessions.models(r) },
   'session.selectModel': { schema: sessionSelectModelRequestSchema, invoke: (api, r) => api.sessions.selectModel(r) },
+  'session.rename': { schema: sessionRenameRequestSchema, invoke: (api, r) => api.sessions.rename(r) },
+  'session.fork': { schema: sessionForkRequestSchema, invoke: (api, r) => api.sessions.fork(r) },
   'session.prompt': { schema: sessionPromptRequestSchema, invoke: (api, r) => api.sessions.prompt(r) },
+  'session.updateQueue': { schema: sessionUpdateQueueRequestSchema, invoke: (api, r) => api.sessions.updateQueue(r) },
   'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
   'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
   'host.pickDirectory': { schema: hostPickDirectoryRequestSchema, invoke: (api, r, signal) => api.host.pickDirectory(r, signal) },
+  'host.listDirectory': { schema: hostListDirectoryRequestSchema, invoke: (api, r, signal) => api.host.listDirectory(r, signal) },
+  'host.createDirectory': { schema: hostCreateDirectoryRequestSchema, invoke: (api, r) => api.host.createDirectory(r) },
+  'host.openPath': { schema: hostOpenPathRequestSchema, invoke: (api, r, signal) => api.host.openPath(r, signal) },
   'workspace.list': { schema: workspaceListRequestSchema, invoke: (api, r) => api.workspace.list(r) },
   'workspace.create': { schema: workspaceCreateRequestSchema, invoke: (api, r) => api.workspace.create(r) },
   'workspace.rename': { schema: workspaceRenameRequestSchema, invoke: (api, r) => api.workspace.rename(r) },
   'workspace.delete': { schema: workspaceDeleteRequestSchema, invoke: (api, r) => api.workspace.delete(r) },
   'workspace.insertSessionBefore': { schema: workspaceInsertSessionBeforeRequestSchema, invoke: (api, r) => api.workspace.insertSessionBefore(r) },
+  'workspace.archiveSession': { schema: workspaceArchiveSessionRequestSchema, invoke: (api, r) => api.workspace.archiveSession(r) },
   'command.list': { schema: commandListRequestSchema, invoke: (api, r) => api.commands.list(r) },
   'command.execute': { schema: commandExecuteRequestSchema, invoke: (api, r, signal) => api.commands.execute(r, signal) },
   'skill.list': { schema: skillListRequestSchema, invoke: (api, r) => api.skills.list(r) },
+  'goal.create': { schema: goalCreateRequestSchema, invoke: (api, r) => api.goals.create(r) },
+  'goal.edit': { schema: goalEditRequestSchema, invoke: (api, r) => api.goals.edit(r) },
+  'goal.pause': { schema: goalPauseRequestSchema, invoke: (api, r) => api.goals.pause(r) },
+  'goal.resume': { schema: goalResumeRequestSchema, invoke: (api, r) => api.goals.resume(r) },
+  'goal.complete': { schema: goalCompleteRequestSchema, invoke: (api, r) => api.goals.complete(r) },
+  'goal.clear': { schema: goalClearRequestSchema, invoke: (api, r) => api.goals.clear(r) },
+  'settings.describe': { schema: settingsDescribeRequestSchema, invoke: (api, r) => api.settings.describe(r) },
+  'settings.update': { schema: settingsUpdateRequestSchema, invoke: (api, r) => api.settings.update(r) },
+  'settings.replace': { schema: settingsReplaceRequestSchema, invoke: (api, r) => api.settings.replace(r) },
+  'settings.mutate': { schema: settingsMutateRequestSchema, invoke: (api, r) => api.settings.mutate(r) },
+  'credentials.describe': { schema: credentialsDescribeRequestSchema, invoke: (api, r) => api.credentials.describe(r) },
+  'credentials.set': { schema: credentialsSetRequestSchema, invoke: (api, r) => api.credentials.set(r) },
+  'credentials.unset': { schema: credentialsUnsetRequestSchema, invoke: (api, r) => api.credentials.unset(r) },
+  'llm.providers': { schema: llmProvidersRequestSchema, invoke: (api, r) => api.llm.providers(r) },
+  'llm.models': { schema: llmModelsRequestSchema, invoke: (api, r) => api.llm.models(r) },
 }
 
 /** Route lookup that narrows an arbitrary path segment to a map key (single cast point for the string→key refinement). */
@@ -102,7 +150,7 @@ function fullResponse(narrow: RpcResponse<unknown>): Response {
  */
 // K appears once in the signature but ties the UNARY_ROUTES[K] row lookup to its own
 // schema/invoke pairing; a union parameter degrades the row to an uninvokable intersection.
-// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+// oxlint-disable-next-line typescript/no-unnecessary-type-parameters
 async function handleUnary<K extends keyof RpcMethodMap>(
   api: ApiProxy, method: K, message: ClientRequest, signal: AbortSignal,
 ): Promise<Response> {
@@ -188,6 +236,17 @@ export function toFetchHandler(api: ApiProxy): { fetch: typeof fetch } {
         return new Response('not found', { status: 404 })
       }
 
+      // Cross-site write fence: browsers send "simple" POSTs (text/plain,
+      // form encodings) without a CORS preflight, so a malicious page could
+      // otherwise execute side-effectful RPCs blind — the response stays
+      // unreadable cross-origin, but session.prompt would still run. Only the
+      // JSON media type is accepted; anything else is forced into a preflight
+      // this server never answers. 415 = carrier layer, like the 400 below.
+      const mediaType = req.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 req.json()

packages/host/apiproxy/src/index.ts

@@ -45,7 +45,7 @@ export interface Config {
  * project directory and the fallback parent for name-created Workspaces.
  */
 export class ApiProxyService extends Service implements ApiProxy {
-  static inject = ['agents', 'llm', 'sessions', 'tools', 'userInteraction', 'workspace']
+  static inject = ['agents', 'directoryPicker', 'llm', 'sessions', 'tools', 'userInteraction', 'workspace']
 
   static Config: z<Config> = z.object({
     provider: z.string().required(),
@@ -57,7 +57,11 @@ export class ApiProxyService extends Service implements ApiProxy {
   readonly workspace: ApiProxy['workspace']
   readonly host: ApiProxy['host']
   readonly commands: ApiProxy['commands']
+  readonly goals: ApiProxy['goals']
   readonly skills: ApiProxy['skills']
+  readonly settings: ApiProxy['settings']
+  readonly credentials: ApiProxy['credentials']
+  readonly llm: ApiProxy['llm']
   readonly events: ApiProxy['events']
   readonly respond: ApiProxy['respond']
 
@@ -74,7 +78,11 @@ export class ApiProxyService extends Service implements ApiProxy {
     this.workspace = api.workspace
     this.host = api.host
     this.commands = api.commands
+    this.goals = api.goals
     this.skills = api.skills
+    this.settings = api.settings
+    this.credentials = api.credentials
+    this.llm = api.llm
     this.events = api.events
     // createApiProxy returns closures (no `this` capture); bind only satisfies
     // the unbound-method lint without changing behavior.

packages/host/apiproxy/src/native-path-opener.ts

@@ -0,0 +1,53 @@
+/** Cross-platform open-with-default-application used by the local GUI carrier. */
+
+import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
+
+/** Testable command boundary; native implementations never invoke a shell. */
+export type PathOpenerRunner = NativeCommandRunner
+
+/** Injectable platform facts for deterministic adapter tests. */
+export interface PathOpenerInternals {
+  platform?: NodeJS.Platform
+  run?: PathOpenerRunner
+}
+
+/** PowerShell single-quoted literal (doubles embedded quotes). */
+function powershellLiteral(path: string): string {
+  return `'${path.replace(/'/g, "''")}'`
+}
+
+/**
+ * Open a filesystem path with the operating system's default application.
+ * @param path - absolute or host-resolvable path (caller owns resolution).
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - platform and runner seam for deterministic tests.
+ */
+export async function openNativePath(
+  path: string,
+  signal: AbortSignal,
+  internals: PathOpenerInternals = {},
+): Promise<void> {
+  const platform = internals.platform ?? process.platform
+  const run = internals.run ?? runNativeCommand
+
+  if (platform === 'darwin') {
+    await run('open', [path], signal)
+    return
+  }
+
+  if (platform === 'win32') {
+    await run('powershell.exe', [
+      '-NoProfile',
+      '-Command',
+      `Invoke-Item -LiteralPath ${powershellLiteral(path)}`,
+    ], signal)
+    return
+  }
+
+  if (platform === 'linux') {
+    await run('xdg-open', [path], signal)
+    return
+  }
+
+  throw new Error(`native path opener is unsupported on ${platform}`)
+}

packages/host/apiproxy/tests/api-proxy-approval.spec.ts

@@ -0,0 +1,330 @@
+/**
+ * Approval pending registry over the proxy: an ask through `ctx.approval`
+ * becomes an answerable `approval/requested` mux frame (stable rpcId, replayed
+ * verbatim on a later mux open), `respond` routes by the echoed rpcId and
+ * validates the audit correlation, and the ask's abort signal withdraws the
+ * question with a broadcast `cancelled`.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import ApprovalService from '@deepseek-ai/dsh-user-approval'
+import type { ApprovalRequestId } from '@deepseek-ai/dsh-user-approval'
+import type { ApiProxy, MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId as mintRpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '../src/api-proxy.ts'
+
+async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(ApprovalService)
+  const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+  return { ctx, api }
+}
+
+/** A minimal agent stand-in inside an open turn (the service only reaches `.session`). */
+function agentOf(ctx: Context): Agent {
+  const session = ctx.sessions.create()
+  session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+  return { session } as unknown as Agent
+}
+
+/** Open a mux stream and capture frames into an array (returns an on-demand waiter). */
+function openMux(api: ApiProxy, abort: AbortController): { frames: MuxFrame[]; envelopes: RpcRequest<MuxFrame>[]; waitFor(type: MuxFrame['type']): Promise<MuxFrame> } {
+  const frames: MuxFrame[] = []
+  const envelopes: RpcRequest<MuxFrame>[] = []
+  const waiters: { type: MuxFrame['type']; resolve: (frame: MuxFrame) => void }[] = []
+  void (async () => {
+    for await (const envelope of api.events.mux({ rpcId: mintRpcId('t-mux'), payload: {} }, abort.signal)) {
+      frames.push(envelope.payload)
+      envelopes.push(envelope)
+      for (let i = waiters.length - 1; i >= 0; i -= 1) {
+        const waiter = waiters[i] as (typeof waiters)[number]
+        if (waiter.type === envelope.payload.type) {
+          waiters.splice(i, 1)
+          waiter.resolve(envelope.payload)
+        }
+      }
+    }
+  })()
+  return {
+    frames,
+    envelopes,
+    waitFor: (type) => {
+      const found = frames.find(frame => frame.type === type)
+      if (found !== undefined) return Promise.resolve(found)
+      return new Promise((resolve) => { waiters.push({ type, resolve }) })
+    },
+  }
+}
+
+function requestedOf(frame: MuxFrame): Extract<MuxFrame, { type: 'approval/requested' }> {
+  if (frame.type !== 'approval/requested') throw new Error(`expected approval/requested, got ${frame.type}`)
+  return frame
+}
+
+/** Wait until the stream delivered `count` frames of `type` (bounded poll; waitFor only covers the first). */
+async function waitForCount(mux: { frames: MuxFrame[] }, type: MuxFrame['type'], count: number): Promise<void> {
+  for (let i = 0; i < 200 && mux.frames.filter(frame => frame.type === type).length < count; i += 1) {
+    await new Promise(resolve => setTimeout(resolve, 5))
+  }
+  expect(mux.frames.filter(frame => frame.type === type).length).toBeGreaterThanOrEqual(count)
+}
+
+function answer(rpcId: RpcId, sessionId: unknown, approvalId: ApprovalRequestId, outcome: 'allowed-once' | 'rejected'): Parameters<ApiProxy['respond']>[0] {
+  return { type: 'client-response', rpcId, result: { ok: true, value: { sessionId, approvalId, outcome } } }
+}
+
+describe('approval pending registry', () => {
+  it('round-trips ask → requested frame → respond → outcome + resolved broadcast', async () => {
+    const { ctx, api } = await harness()
+    const abort = new AbortController()
+    const mux = openMux(api, abort)
+    const agent = agentOf(ctx)
+
+    const asked = ctx.approval.request({ agent, toolName: 'bash', reason: 'sandbox escalation' })
+    const requested = requestedOf(await mux.waitFor('approval/requested'))
+    expect(requested).toMatchObject({ toolName: 'bash', reason: 'sandbox escalation', sessionId: agent.session.id })
+
+    const envelope = mux.envelopes.find(e => e.payload.type === 'approval/requested') as RpcRequest<MuxFrame>
+    const receipt = await api.respond(answer(envelope.rpcId, requested.sessionId, requested.approvalId, 'allowed-once'))
+    expect(receipt).toEqual({ accepted: true })
+    await expect(asked).resolves.toBe('allowed-once')
+
+    const resolved = await mux.waitFor('approval/resolved')
+    expect(resolved).toMatchObject({ approvalId: requested.approvalId, outcome: 'allowed-once' })
+
+    // The question settled: a duplicate answer is late, not re-decidable.
+    const dup = await api.respond(answer(envelope.rpcId, requested.sessionId, requested.approvalId, 'rejected'))
+    expect(dup).toEqual({ accepted: false, reason: 'not-pending' })
+    abort.abort()
+  })
+
+  it('replays a still-pending requested frame (same rpcId) on a later mux open', async () => {
+    const { ctx, api } = await harness()
+    const first = new AbortController()
+    const firstMux = openMux(api, first)
+    const agent = agentOf(ctx)
+    const asked = ctx.approval.request({ agent, toolName: 'write' })
+    const requested = requestedOf(await firstMux.waitFor('approval/requested'))
+    const firstEnvelope = firstMux.envelopes.find(e => e.payload.type === 'approval/requested') as RpcRequest<MuxFrame>
+    first.abort()
+
+    // A fresh subscriber (refresh recovery) sees the same stable rpcId.
+    const second = new AbortController()
+    const secondMux = openMux(api, second)
+    const replayed = requestedOf(await secondMux.waitFor('approval/requested'))
+    const secondEnvelope = secondMux.envelopes.find(e => e.payload.type === 'approval/requested') as RpcRequest<MuxFrame>
+    expect(secondEnvelope.rpcId).toBe(firstEnvelope.rpcId)
+    expect(replayed.approvalId).toBe(requested.approvalId)
+
+    const receipt = await api.respond(answer(secondEnvelope.rpcId, replayed.sessionId, replayed.approvalId, 'rejected'))
+    expect(receipt).toEqual({ accepted: true })
+    await expect(asked).resolves.toBe('rejected')
+    second.abort()
+  })
+
+  it('rejects malformed and mismatched answers as bad-response, unknown ids as not-pending', async () => {
+    const { ctx, api } = await harness()
+    const abort = new AbortController()
+    const mux = openMux(api, abort)
+    const agent = agentOf(ctx)
+    void ctx.approval.request({ agent, toolName: 'bash' })
+    const requested = requestedOf(await mux.waitFor('approval/requested'))
+    const envelope = mux.envelopes.find(e => e.payload.type === 'approval/requested') as RpcRequest<MuxFrame>
+
+    // Unknown rpcId: not routed to any pending entry.
+    expect(await api.respond(answer(mintRpcId('ghost'), requested.sessionId, requested.approvalId, 'rejected')))
+      .toEqual({ accepted: false, reason: 'not-pending' })
+    // Error-branch result: the client can only answer with a value.
+    expect(await api.respond({ type: 'client-response', rpcId: envelope.rpcId, result: { ok: false, error: { code: 'internal', message: 'x', details: {} } } }))
+      .toEqual({ accepted: false, reason: 'bad-response' })
+    // Wrong audit correlation: the rpcId routed, but the payload disagrees.
+    expect(await api.respond(answer(envelope.rpcId, requested.sessionId, 'other-approval' as ApprovalRequestId, 'rejected')))
+      .toEqual({ accepted: false, reason: 'bad-response' })
+    // Malformed payload shape.
+    expect(await api.respond({ type: 'client-response', rpcId: envelope.rpcId, result: { ok: true, value: { nonsense: 1 } } }))
+      .toEqual({ accepted: false, reason: 'bad-response' })
+    abort.abort()
+  })
+
+  it('withdraws the question on the ask signal: cancelled outcome, resolved broadcast, late answer not-pending', async () => {
+    const { ctx, api } = await harness()
+    const abort = new AbortController()
+    const mux = openMux(api, abort)
+    const agent = agentOf(ctx)
+    const cancel = new AbortController()
+    const asked = ctx.approval.request({ agent, toolName: 'bash', signal: cancel.signal })
+    const requested = requestedOf(await mux.waitFor('approval/requested'))
+    const envelope = mux.envelopes.find(e => e.payload.type === 'approval/requested') as RpcRequest<MuxFrame>
+
+    cancel.abort()
+    await expect(asked).resolves.toBe('cancelled')
+    const resolved = await mux.waitFor('approval/resolved')
+    expect(resolved).toMatchObject({ approvalId: requested.approvalId, outcome: 'cancelled' })
+    expect(await api.respond(answer(envelope.rpcId, requested.sessionId, requested.approvalId, 'allowed-once')))
+      .toEqual({ accepted: false, reason: 'not-pending' })
+    abort.abort()
+  })
+
+  it('an ask whose signal aborted before dispatch settles cancelled without publishing', async () => {
+    // The service checks the signal, then dispatch rides a microtask: an
+    // abort in that window must not register a dead listener and strand the
+    // entry (zombie frame on every replay). Drive the waterfall directly
+    // with a pre-aborted signal to hit the answerer's register-path guard.
+    const { ctx, api } = await harness()
+    const abort = new AbortController()
+    const mux = openMux(api, abort)
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('approval/asked', { id: 'pre-aborted' as ApprovalRequestId, toolName: 'bash' })
+    const agent = { session } as unknown as Agent
+    const cancelled = new AbortController()
+    cancelled.abort()
+    const outcome = await ctx.waterfall(
+      'approval/request',
+      { agent, toolName: 'bash', signal: cancelled.signal },
+      () => Promise.resolve('unavailable' as const),
+    )
+    expect(outcome).toBe('cancelled')
+    // Nothing was published: a fresh mux open replays no approval frame.
+    const abort2 = new AbortController()
+    const mux2 = openMux(api, abort2)
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(mux2.envelopes.some(e => e.payload.type === 'approval/requested')).toBe(false)
+    abort2.abort()
+    abort.abort()
+    void mux
+  })
+
+  it('gateway teardown settles pending approvals as cancelled (question-provider parity)', async () => {
+    // Mount the proxy on its own fiber so disposal exercises the teardown
+    // effect while an ask is still pending.
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt, { persona: '' })
+    await ctx.plugin(UserInteractionService)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(ApprovalService)
+    let api!: ApiProxy
+    const fiber = ctx.plugin(Object.assign((fiberCtx: Context) => {
+      api = createApiProxy(fiberCtx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    }, { inject: ['sessions', 'agents', 'userInteraction', 'approval'] }))
+    await fiber.await()
+    const abort = new AbortController()
+    const mux = openMux(api, abort)
+    const asked = ctx.approval.request({ agent: agentOf(ctx), toolName: 'bash' })
+    const requested = requestedOf(await mux.waitFor('approval/requested'))
+    await fiber.dispose()
+    await expect(asked).resolves.toBe('cancelled')
+    const resolved = await mux.waitFor('approval/resolved')
+    expect(resolved).toMatchObject({ approvalId: requested.approvalId, outcome: 'cancelled' })
+    abort.abort()
+  })
+
+  it('carries callId on the frame and ignores a late abort after the answer settled', async () => {
+    const { ctx, api } = await harness()
+    const abort = new AbortController()
+    const mux = openMux(api, abort)
+    const agent = agentOf(ctx)
+    const cancel = new AbortController()
+    const asked = ctx.approval.request({ agent, toolName: 'bash', callId: 'call-9' as never, signal: cancel.signal })
+    const requested = requestedOf(await mux.waitFor('approval/requested'))
+    expect(requested.callId).toBe('call-9')
+    const envelope = mux.envelopes.find(e => e.payload.type === 'approval/requested') as RpcRequest<MuxFrame>
+    expect(await api.respond(answer(envelope.rpcId, requested.sessionId, requested.approvalId, 'allowed-once')))
+      .toEqual({ accepted: true })
+    await expect(asked).resolves.toBe('allowed-once')
+    // Late abort: the pending entry is gone; settle's delete-guard returns.
+    cancel.abort()
+    expect(mux.frames.filter(f => f.type === 'approval/resolved')).toHaveLength(1)
+    abort.abort()
+  })
+
+  it('pairs parallel asks by callId: each requested frame carries its own audit id', async () => {
+    const { ctx, api } = await harness()
+    const abort = new AbortController()
+    const mux = openMux(api, abort)
+    const agent = agentOf(ctx)
+    // Both asks append their approval/asked audit events before either
+    // answerer's microtask dispatch runs — the parallel tool-call window.
+    const askA = ctx.approval.request({ agent, toolName: 'bash', callId: 'call-a' as never })
+    const askB = ctx.approval.request({ agent, toolName: 'bash', callId: 'call-b' as never })
+    await waitForCount(mux, 'approval/requested', 2)
+    const frames = mux.envelopes.filter(e => e.payload.type === 'approval/requested')
+    const frameA = frames.find(e => requestedOf(e.payload).callId === 'call-a') as RpcRequest<MuxFrame>
+    const frameB = frames.find(e => requestedOf(e.payload).callId === 'call-b') as RpcRequest<MuxFrame>
+    // Each frame claimed the asked event with its own callId, not merely the newest.
+    const askedIdByCall = new Map(agent.session.events
+      .filter(event => event.type === 'approval/asked')
+      .map(event => [String(event.data.callId), event.data.id]))
+    expect(requestedOf(frameA.payload).approvalId).toBe(askedIdByCall.get('call-a'))
+    expect(requestedOf(frameB.payload).approvalId).toBe(askedIdByCall.get('call-b'))
+    // Answers route back to the right ask through the pairing.
+    expect(await api.respond(answer(frameB.rpcId, agent.session.id, requestedOf(frameB.payload).approvalId, 'rejected')))
+      .toEqual({ accepted: true })
+    expect(await api.respond(answer(frameA.rpcId, agent.session.id, requestedOf(frameA.payload).approvalId, 'allowed-once')))
+      .toEqual({ accepted: true })
+    await expect(askA).resolves.toBe('allowed-once')
+    await expect(askB).resolves.toBe('rejected')
+    abort.abort()
+  })
+
+  it('gives parallel callId-less asks distinct audit ids (claimed-entry skip); both stay answerable', async () => {
+    const { ctx, api } = await harness()
+    const abort = new AbortController()
+    const mux = openMux(api, abort)
+    const agent = agentOf(ctx)
+    const askA = ctx.approval.request({ agent, toolName: 'alpha' })
+    const askB = ctx.approval.request({ agent, toolName: 'beta' })
+    await waitForCount(mux, 'approval/requested', 2)
+    const frames = mux.envelopes.filter(e => e.payload.type === 'approval/requested')
+    const frameA = frames.find(e => requestedOf(e.payload).toolName === 'alpha') as RpcRequest<MuxFrame>
+    const frameB = frames.find(e => requestedOf(e.payload).toolName === 'beta') as RpcRequest<MuxFrame>
+    // Without a callId the pairing is heuristic, but never shared: the second
+    // dispatch skips the id the first pending entry already claimed.
+    expect(requestedOf(frameA.payload).approvalId).not.toBe(requestedOf(frameB.payload).approvalId)
+    expect(await api.respond(answer(frameA.rpcId, agent.session.id, requestedOf(frameA.payload).approvalId, 'allowed-once')))
+      .toEqual({ accepted: true })
+    expect(await api.respond(answer(frameB.rpcId, agent.session.id, requestedOf(frameB.payload).approvalId, 'rejected')))
+      .toEqual({ accepted: true })
+    await expect(askA).resolves.toBe('allowed-once')
+    await expect(askB).resolves.toBe('rejected')
+    abort.abort()
+  })
+
+  it('delegates a dispatch whose only asked candidate is already decided (stale re-dispatch)', async () => {
+    const { ctx, api } = await harness()
+    void api // the answerer is registered; the fake below bypasses the service
+    // Bypass ApprovalService: a log whose sole asked event already has its
+    // decided partner must not be re-claimed — the answerer delegates.
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('approval/asked', { id: 'stale-ask' as ApprovalRequestId, toolName: 'bash' })
+    session.append('approval/decided', { id: 'stale-ask' as ApprovalRequestId, outcome: 'rejected' })
+    const agent = { session } as unknown as Agent
+    const outcome = await ctx.waterfall('approval/request', { agent, toolName: 'bash' }, () => Promise.resolve('unavailable' as const))
+    expect(outcome).toBe('unavailable')
+  })
+
+  it('delegates an ask whose session log carries no asked audit event (foreign channel)', async () => {
+    const { ctx, api } = await harness()
+    void api // the answerer is registered; the fake below bypasses the audit path
+    // Bypass ApprovalService: dispatch the waterfall directly with a session
+    // that has no approval/asked event — the proxy answerer must call next().
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const agent = { session } as unknown as Agent
+    const outcome = await ctx.waterfall('approval/request', { agent, toolName: 'x' }, () => Promise.resolve('unavailable' as const))
+    expect(outcome).toBe('unavailable')
+  })
+})

packages/host/apiproxy/tests/api-proxy-blank.spec.ts

@@ -0,0 +1,85 @@
+/**
+ * The summary blank bit means "conversation not started" (no turn has run),
+ * not "log empty": standalone plugin events — command lifecycle records,
+ * plan/mode, permission knob events, session titles — never flip it, so running /plan or /goal on a
+ * fresh session keeps it list-hidden and reusable, while the first accepted
+ * prompt's turn/start clears it. The host/session-added frame shares the
+ * same predicate function (covered by the workspace spec's frame assertion).
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { Session } from '@deepseek-ai/dsh-session'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import { CommandId } from '@deepseek-ai/dsh-commands/brand'
+// Side-effect type imports: the knob-event SessionEventMap merges.
+import type {} from '@deepseek-ai/dsh-permission'
+import type {} from '@deepseek-ai/dsh-sandbox-policy'
+import type {} from '@deepseek-ai/dsh-user-approval'
+import type { ApiProxy, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`blank-${String(nextRpc++)}`), payload }
+}
+
+async function harness(): Promise<{ ctx: Context; api: ApiProxy; attach: (session: Session) => void }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(AgentRegistry)
+  return {
+    ctx,
+    api: createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }),
+    attach: (session) => {
+      ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
+    },
+  }
+}
+
+/** Append the standalone (non-conversation) event family a fresh session can accumulate. */
+function appendStandalone(session: Session): void {
+  session.append('command/run', {
+    commandId: CommandId('blank-cmd-1'), name: 'plan', args: '', source: { kind: 'user' },
+  })
+  session.append('plan/mode', { active: true })
+  session.append('command/done', { commandId: CommandId('blank-cmd-1'), kind: 'success', text: 'Plan mode on.' })
+  session.append('session/title', {
+    title: 'standalone title', messageSeqs: [], source: { kind: 'fallback' },
+  })
+  // The three permission knob events (a /permission switch on a fresh session).
+  session.append('permission/preset', { preset: 'danger-full-access' })
+  session.append('sandbox/mode', { mode: 'danger-full-access' })
+  session.append('approval/policy', { policy: 'never' })
+}
+
+async function listBlank(api: ApiProxy, id: string): Promise<boolean | undefined> {
+  const response = await api.sessions.list(request({}))
+  if (!response.result.ok) throw new Error('list failed')
+  return response.result.value.items.find(item => item.sessionId === id)?.blank
+}
+
+describe('summary blank = conversation not started', () => {
+  it('standalone events (command lifecycle, plan/mode, title) keep the session blank', async () => {
+    const { ctx, api, attach } = await harness()
+    const session = ctx.sessions.create()
+    attach(session)
+    expect(await listBlank(api, session.id)).toBe(true)
+    appendStandalone(session)
+    expect(await listBlank(api, session.id)).toBe(true)
+  })
+
+  it('the first turn clears blank', async () => {
+    const { ctx, api, attach } = await harness()
+    const session = ctx.sessions.create()
+    attach(session)
+    appendStandalone(session)
+    session.append('turn/start', { turn: 0, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(await listBlank(api, session.id)).toBe(false)
+  })
+})

packages/host/apiproxy/tests/api-proxy-cold.spec.ts

@@ -78,6 +78,42 @@ describe('sessions.list cold merge', () => {
   })
 })
 
+describe('attached updatedAt excludes end-seed', () => {
+  it('reports the last real work, not the pickup, so a resumed-untouched session does not float', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(UserInteractionService)
+    await ctx.plugin(AgentRegistry)
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+
+    // Old work, resumed just now: the log tail would report the pickup.
+    const worked = 1_000_000
+    const resumed = ctx.sessions.create(sid('resumed-untouched'), {
+      seed: [
+        { type: 'turn/start', seq: 0, time: worked, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+        { type: 'turn/end', seq: 1, time: worked, data: { turn: 1, reason: { kind: 'completed' } } },
+      ],
+      meta: { cwd: '/proj', createdAt: 500 },
+    })
+    ctx.agents.register({ id: resumed.id, session: resumed, status: 'idle', ctx } as Agent)
+    const boundary = resumed.events.at(-1)
+    expect(boundary?.type).toBe('session/end-seed')
+    expect(boundary?.time).toBeGreaterThan(worked)
+
+    const listed = await api.sessions.list(request({}))
+    if (!listed.result.ok) throw new Error('list failed')
+    const summary = listed.result.value.items.find(item => item.sessionId === 'resumed-untouched')
+    expect(summary?.updatedAt).toBe(worked)
+
+    // Real work appended after end-seed does move it.
+    resumed.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const after = await api.sessions.list(request({}))
+    if (!after.result.ok) throw new Error('list failed')
+    const moved = after.result.value.items.find(item => item.sessionId === 'resumed-untouched')
+    expect(moved?.updatedAt).toBeGreaterThan(worked)
+  })
+})
+
 describe('degenerate composition (no persistence, no factory)', () => {
   it('list skips the cold merge and resume maps a non-not-found failure to internal', async () => {
     const ctx = new Context()

packages/host/apiproxy/tests/api-proxy-commands.spec.ts

@@ -1,3 +1,4 @@
+import { MessageId, freezeMessage } from '@deepseek-ai/dsh-llm'
 /**
  * Command/skill RPC handlers and the two new frames over createApiProxy:
  * command.list serves the addressed agent's effective catalog (missing
@@ -8,12 +9,12 @@
  * open-time queue snapshot.
  */
 
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import AgentRegistry, { AgentMessageId } from '@deepseek-ai/dsh-agent'
-import type { Agent, AgentMessage } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { InboxItemId } from '@deepseek-ai/dsh-agent'
+import type { Agent, InboxItem, InboxPlacement } from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
-import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionId, UserMessage } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
@@ -115,8 +116,16 @@ describe('command.execute', () => {
     const api = createApiProxy(ctx, DEFAULTS)
     const agent = stubAgent(ctx)
     const value = expectOk(await api.commands.execute(request({ sessionId: agent.id, line: '/goal ship it' }), new AbortController().signal))
-    expect(value).toEqual({ matched: true, result: { kind: 'success', text: `goal:${agent.id}` } })
+    expect(value).toMatchObject({ matched: true })
+    expect(value.commandId).toBeTruthy()
     expect(received).toBe(' ship it')
+    // Pure admission on the wire: the outcome rides the durably logged
+    // lifecycle pair instead of the response.
+    const lifecycle = agent.session.events.filter(e => e.type === 'command/run' || e.type === 'command/done')
+    expect(lifecycle).toMatchObject([
+      { type: 'command/run', data: { commandId: value.commandId, name: 'goal', args: ' ship it' } },
+      { type: 'command/done', data: { commandId: value.commandId, kind: 'success', text: `goal:${agent.id}` } },
+    ])
   })
 
   it('returns matched:false when syntax or name does not resolve', async () => {
@@ -171,17 +180,35 @@ describe('skill.list', () => {
   it('lists skills for the session cwd taken from the header', async () => {
     const ctx = await harness()
     const seenCwds: (string | undefined)[] = []
-    ctx.skills.registerProvider({
+    ctx.skills.registerProvider(() => ({
       name: 'probe',
       list: (options) => {
         seenCwds.push(options.cwd)
-        return Promise.resolve([{
-          name: 'commit-helper', description: 'Git commits', whenToUse: 'when committing',
-          source: 'custom', provider: 'probe', rank: 0, locator: null,
-        }])
+        return Promise.resolve([
+          {
+            name: 'commit-helper', description: 'Git commits', whenToUse: 'when committing',
+            invocation: { modelInvocable: true, userInvocable: true },
+            source: 'custom', provider: 'probe', rank: 0, locator: null,
+          },
+          {
+            name: 'user-only', description: 'User-only',
+            invocation: { modelInvocable: false, userInvocable: true },
+            source: 'custom', provider: 'probe', rank: 0, locator: null,
+          },
+          {
+            name: 'model-only', description: 'Model-only',
+            invocation: { modelInvocable: true, userInvocable: false },
+            source: 'custom', provider: 'probe', rank: 0, locator: null,
+          },
+          {
+            name: 'trusted-only', description: 'Trusted-only',
+            invocation: { modelInvocable: false, userInvocable: false },
+            source: 'custom', provider: 'probe', rank: 0, locator: null,
+          },
+        ])
       },
       get: () => Promise.resolve(undefined),
-    })
+    }))
     const api = createApiProxy(ctx, DEFAULTS)
     // No agent is registered for this session: header resolution must not
     // touch (or resume through) the Agent registry.
@@ -210,11 +237,11 @@ describe('skill.list', () => {
 
   it('folds a provider failure into internal', async () => {
     const ctx = await harness()
-    ctx.skills.registerProvider({
+    ctx.skills.registerProvider(() => ({
       name: 'broken',
       list: () => Promise.reject(new Error('directory exploded')),
       get: () => Promise.resolve(undefined),
-    })
+    }))
     const api = createApiProxy(ctx, DEFAULTS)
     const session = ctx.sessions.create(undefined, { meta: { cwd: '/proj' } })
     const response = await api.skills.list(request({ sessionId: session.id }))
@@ -238,74 +265,168 @@ describe('host/commands-changed frame', () => {
 })
 
 /** Build one frozen inbox message for the live `agent/inbox/*` events. */
-function inboxMessage(id: string, text: string, rpcId?: string): AgentMessage {
-  return Object.freeze({
-    id: AgentMessageId(id),
+function inboxMessage(id: string, text: string, rpcId?: string): UserMessage {
+  return freezeMessage({
+    id: MessageId(id),
+    role: 'user',
     content: [{ type: 'text' as const, text }],
     source: rpcId === undefined ? { kind: 'user' as const } : { kind: 'user' as const, rpcId: RpcId(rpcId) },
   })
 }
 
-describe('session/queued frames', () => {
-  it('forwards live enqueue events and replays the snapshot on a later mux open', async () => {
+/** Build one addressable inbox occurrence around a frozen message. */
+function inboxItem(id: string, message: UserMessage, placement: InboxPlacement): InboxItem {
+  return { id: InboxItemId(id), message, placement }
+}
+
+describe('session.updateQueue', () => {
+  it('routes an addressable action and reports a lost claim race', async () => {
+    const ctx = await harness()
+    const agent = stubAgent(ctx)
+    const seen: unknown[] = []
+    agent.updateInbox = (id, action) => {
+      seen.push({ id, action })
+      return id === InboxItemId('present') ? 'applied' : 'not-found'
+    }
+    const api = createApiProxy(ctx, DEFAULTS)
+
+    const applied = await api.sessions.updateQueue({
+      rpcId: RpcId('q-apply'),
+      payload: {
+        sessionId: agent.id,
+        itemId: InboxItemId('present'),
+        action: { kind: 'edit', content: [{ type: 'text', text: 'edited' }] },
+      },
+    })
+    expect(expectOk(applied)).toEqual({ accepted: true })
+    const missing = await api.sessions.updateQueue({
+      rpcId: RpcId('q-missing'),
+      payload: {
+        sessionId: agent.id,
+        itemId: InboxItemId('claimed'),
+        action: { kind: 'remove' },
+      },
+    })
+    expect(expectErr(missing)).toMatchObject({ code: 'queue-item-not-found' })
+    expect(seen).toEqual([
+      { id: 'present', action: { kind: 'edit', content: [{ type: 'text', text: 'edited' }] } },
+      { id: 'claimed', action: { kind: 'remove' } },
+    ])
+  })
+
+  it('rejects a stale occurrence without resuming a cold agent', async () => {
+    const ctx = await harness()
+    const resume = vi.spyOn(ctx.agents, 'resume')
+    const api = createApiProxy(ctx, DEFAULTS)
+    const response = await api.sessions.updateQueue({
+      rpcId: RpcId('q-cold'),
+      payload: {
+        sessionId: 'cold-session' as SessionId,
+        itemId: InboxItemId('stale-item'),
+        action: { kind: 'remove' },
+      },
+    })
+
+    expect(expectErr(response)).toMatchObject({ code: 'queue-item-not-found' })
+    expect(resume).not.toHaveBeenCalled()
+  })
+})
+
+describe('session/queue frames', () => {
+  it('folds nested mutations observed before their outer enqueue', async () => {
+    const ctx = await harness()
+    const agent = stubAgent(ctx)
+    const original = inboxItem('i-edit', inboxMessage('m-edit', 'before'), 'queued')
+    const edited = inboxItem('i-edit', inboxMessage('m-edit', 'after'), 'queued')
+    const removed = inboxItem('i-remove', inboxMessage('m-remove', 'remove me'), 'queued')
+    ctx.on('agent/inbox/enqueue', (subject, item) => {
+      if (subject !== agent) return
+      if (item.id === original.id) ctx.emit('agent/inbox/update', agent, edited)
+      if (item.id === removed.id) ctx.emit('agent/inbox/discard', agent, [removed])
+    })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const live = new AbortController()
+    const collected = collect<MuxFrame>(
+      api.events.mux({ rpcId: RpcId('t-mux-reentrant'), payload: {} }, live.signal), 2, live)
+
+    ctx.emit('agent/inbox/enqueue', agent, original)
+    ctx.emit('agent/inbox/enqueue', agent, removed)
+
+    const liveFrames = (await collected).filter(frame => frame.type === 'session/queue')
+    expect(liveFrames.map(frame => frame.items)).toEqual([
+      [{ id: edited.id, message: edited.message }],
+    ])
+    const replay = new AbortController()
+    const replayFrames = await collect<MuxFrame>(
+      api.events.mux({ rpcId: RpcId('t-mux-reentrant-replay'), payload: {} }, replay.signal), 2, replay)
+    expect(replayFrames.filter(frame => frame.type === 'session/queue')).toEqual(liveFrames)
+  })
+
+  it('publishes complete live snapshots and replays the latest snapshot on reconnect', async () => {
     const ctx = await harness()
     const api = createApiProxy(ctx, DEFAULTS)
     const agent = stubAgent(ctx)
     const live = new AbortController()
     const liveStream = api.events.mux({ rpcId: RpcId('t-mux-live'), payload: {} }, live.signal)
-    // subscribed baseline + 2 queued frames
-    const liveCollected = collect<MuxFrame>(liveStream, 3, live)
+    // subscribed baseline + one queued snapshot; pending steering stays off this wire.
+    const liveCollected = collect<MuxFrame>(liveStream, 2, live)
 
-    const queued = inboxMessage('m-1', 'queued prompt')
-    const steering = inboxMessage('m-2', 'queued prompt')
-    ctx.emit('agent/inbox/enqueue', agent, queued, 'queued')
-    ctx.emit('agent/inbox/enqueue', agent, steering, 'steering')
+    const queued = inboxItem('i-1', inboxMessage('m-1', 'queued prompt'), 'queued')
+    const steering = inboxItem('i-2', inboxMessage('m-2', 'steering prompt'), 'steering')
+    ctx.emit('agent/inbox/enqueue', agent, queued)
+    ctx.emit('agent/inbox/enqueue', agent, steering)
 
-    const liveFrames = (await liveCollected).filter(f => f.type === 'session/queued')
+    const liveFrames = (await liveCollected).filter(f => f.type === 'session/queue')
     expect(liveFrames).toEqual([
-      { type: 'session/queued', sessionId: agent.id, content: queued.content, source: { kind: 'user' }, steering: false },
-      { type: 'session/queued', sessionId: agent.id, content: steering.content, source: { kind: 'user' }, steering: true },
+      {
+        type: 'session/queue',
+        sessionId: agent.id,
+        items: [{ id: queued.id, message: queued.message }],
+      },
     ])
 
-    // A fresh mux connection replays the still-pending entries as its baseline.
+    // A fresh mux connection replays only the current authoritative snapshot.
     const replay = new AbortController()
     const replayFrames = await collect<MuxFrame>(
-      api.events.mux({ rpcId: RpcId('t-mux-replay'), payload: {} }, replay.signal), 3, replay)
-    expect(replayFrames.filter(f => f.type === 'session/queued')).toEqual(liveFrames)
+      api.events.mux({ rpcId: RpcId('t-mux-replay'), payload: {} }, replay.signal), 2, replay)
+    expect(replayFrames.filter(f => f.type === 'session/queue')).toEqual([liveFrames[0]])
   })
 
-  it('retires mirror entries on their terminal dequeue', async () => {
+  it('publishes edits in place in the authoritative order', async () => {
     const ctx = await harness()
     const api = createApiProxy(ctx, DEFAULTS)
     const agent = stubAgent(ctx)
-    const queued = inboxMessage('m-3', 'x')
-    const steering = inboxMessage('m-4', 'x', 'r-1')
-    ctx.emit('agent/inbox/enqueue', agent, queued, 'queued')
-    ctx.emit('agent/inbox/enqueue', agent, steering, 'steering')
-    ctx.emit('agent/inbox/dequeue', agent, queued)
-    ctx.emit('agent/inbox/dequeue', agent, steering)
-
     const abort = new AbortController()
-    const frames = await collect<MuxFrame>(
-      api.events.mux({ rpcId: RpcId('t-mux-after'), payload: {} }, abort.signal), 1, abort)
-    expect(frames.filter(f => f.type === 'session/queued')).toHaveLength(0)
+    const collected = collect<MuxFrame>(
+      api.events.mux({ rpcId: RpcId('t-mux-updates'), payload: {} }, abort.signal), 5, abort)
+    const first = inboxItem('i-a', inboxMessage('m-a', 'a'), 'queued')
+    const second = inboxItem('i-b', inboxMessage('m-b', 'b'), 'queued')
+    const edited = inboxItem('i-b', inboxMessage('m-b', 'b edited'), 'queued')
+    ctx.emit('agent/inbox/enqueue', agent, first)
+    ctx.emit('agent/inbox/enqueue', agent, second)
+    ctx.emit('agent/inbox/update', agent, edited)
+    ctx.emit('agent/inbox/dequeue', agent, edited)
+
+    const frames = (await collected).filter(frame => frame.type === 'session/queue')
+    expect(frames.map(frame => frame.items)).toEqual([
+      [{ id: first.id, message: first.message }],
+      [{ id: first.id, message: first.message }, { id: second.id, message: second.message }],
+      [{ id: first.id, message: first.message }, { id: edited.id, message: edited.message }],
+      [{ id: first.id, message: first.message }],
+    ])
   })
 
-  it('retires mirror entries on a batch discard (cancel path)', async () => {
+  it('publishes an empty snapshot after terminal discard', async () => {
     const ctx = await harness()
     const api = createApiProxy(ctx, DEFAULTS)
     const agent = stubAgent(ctx)
-    const doomed = inboxMessage('m-5', 'doomed')
-    const survivor = inboxMessage('m-6', 'survivor')
-    ctx.emit('agent/inbox/enqueue', agent, doomed, 'queued')
-    ctx.emit('agent/inbox/enqueue', agent, survivor, 'queued')
+    const doomed = inboxItem('i-doomed', inboxMessage('m-5', 'doomed'), 'queued')
+    ctx.emit('agent/inbox/enqueue', agent, doomed)
     ctx.emit('agent/inbox/discard', agent, [doomed])
 
     const abort = new AbortController()
     const frames = await collect<MuxFrame>(
-      api.events.mux({ rpcId: RpcId('t-mux-swept'), payload: {} }, abort.signal), 2, abort)
-    const remaining = frames.filter(f => f.type === 'session/queued')
-    expect(remaining).toHaveLength(1)
-    expect(remaining[0]).toMatchObject({ content: survivor.content })
+      api.events.mux({ rpcId: RpcId('t-mux-swept'), payload: {} }, abort.signal), 1, abort)
+    expect(frames.filter(frame => frame.type === 'session/queue')).toHaveLength(0)
   })
 })

packages/host/apiproxy/tests/api-proxy-config.spec.ts

@@ -0,0 +1,480 @@
+/**
+ * Settings/credentials/llm RPC domains and their host-stream frames over
+ * createApiProxy: layered redacted describe, write-path rejection mapping,
+ * value-free credential views, the directory/live-route merge, and the three
+ * invalidation frames (settings/credentials/models changed).
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import z from 'schemastery'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import LlmService, { LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { Settings, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import { Credentials } from '@deepseek-ai/dsh-credentials'
+import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepseek-ai/dsh-credentials'
+import type { HostFrame } from '../src/api/index.ts'
+import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
+import { RpcId } from '../src/api/rpc.ts'
+import { createApiProxy } from '../src/api-proxy.ts'
+
+const DEFAULTS = { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`req-${String(nextRpc++)}`), payload }
+}
+
+function expectOk<T>(response: RpcResponse<T>): T {
+  expect(response.result.ok).toBe(true)
+  if (!response.result.ok) throw new Error('unreachable')
+  return response.result.value
+}
+
+function expectErr<T>(response: RpcResponse<T>): { code: string; message: string; details: unknown } {
+  expect(response.result.ok).toBe(false)
+  if (response.result.ok) throw new Error('unreachable')
+  return response.result.error
+}
+
+/** In-memory settings provider: the seam base class owns all tested behavior. */
+class MemorySettings extends Settings {
+  doc: Record<string, unknown>
+
+  constructor(ctx: ConstructorParameters<typeof Settings>[0], options?: { doc?: Record<string, unknown>; readOnly?: boolean }) {
+    super(ctx)
+    this.doc = structuredClone(options?.doc ?? {})
+    this.readOnly = options?.readOnly ?? false
+  }
+
+  private readonly readOnly: boolean
+
+  get writable(): boolean {
+    return !this.readOnly
+  }
+
+  protected load(): Promise<Record<string, unknown>> {
+    return Promise.resolve(structuredClone(this.doc))
+  }
+
+  protected persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
+    this.doc[ns] = structuredClone(section)
+    return Promise.resolve()
+  }
+}
+
+/** In-memory credential provider with an env-shadow double for the rejection path. */
+class MemoryCredentials extends Credentials {
+  private readonly values = new Map<string, string>()
+
+  constructor(ctx: ConstructorParameters<typeof Credentials>[0], options?: { shadowed?: string[] }) {
+    super(ctx)
+    this.shadowed = new Set(options?.shadowed ?? [])
+  }
+
+  private readonly shadowed: Set<string>
+
+  resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined> {
+    if (this.shadowed.has(ref)) return Promise.resolve({ value: 'from-env', source: 'env' })
+    const value = this.values.get(ref)
+    return Promise.resolve(value === undefined ? undefined : { value, source: 'file' })
+  }
+
+  describe(ref: CredentialRef): Promise<CredentialInfo> {
+    if (this.shadowed.has(ref)) return Promise.resolve({ configured: true, source: 'env', writable: false })
+    const configured = this.values.has(ref)
+    return Promise.resolve({ configured, ...configured ? { source: 'file' } : {}, writable: true })
+  }
+
+  set(ref: CredentialRef, value: string): Promise<void> {
+    if (this.shadowed.has(ref)) {
+      return Promise.reject(new Error(`credentials: ${ref} is shadowed by the read-only environment`))
+    }
+    this.values.set(ref, value)
+    this.ctx.emit('credentials/updated', ref)
+    return Promise.resolve()
+  }
+
+  unset(ref: CredentialRef): Promise<void> {
+    if (this.shadowed.has(ref)) {
+      return Promise.reject(new Error(`credentials: ${ref} is shadowed by the read-only environment`))
+    }
+    this.values.delete(ref)
+    this.ctx.emit('credentials/updated', ref)
+    return Promise.resolve()
+  }
+}
+
+/** Catalog-serving adapter stub for the llm.models path. */
+class CatalogAdapter extends LlmAdapter {
+  constructor(private readonly name: string, private readonly models: readonly string[]) {
+    super()
+  }
+
+  override providerInfo(provider: string): LlmProviderInfo {
+    return { id: provider, name: this.name }
+  }
+
+  override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
+    return Promise.resolve(this.models.map(id => ({ provider, id, name: id })))
+  }
+
+
+  async * stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    throw new Error('not exercised')
+  }
+}
+
+class BrokenCatalogAdapter extends CatalogAdapter {
+  override listModels(): Promise<readonly LlmModelInfo[]> {
+    return Promise.reject(new Error('catalog backend down'))
+  }
+}
+
+const NS = settingsNamespace('llm-deepseek')
+
+const AdapterConfig = z.object({
+  apiKey: z.string().role('secret'),
+  apiKeyEnv: z.string().default('DEEPSEEK_API_KEY'),
+  baseURL: z.string(),
+})
+
+async function harness(options?: {
+  settings?: false | { doc?: Record<string, unknown>; readOnly?: boolean }
+  credentials?: false | { shadowed?: string[] }
+  /** Skip the directory registration to exercise a namespace the proxy does not expose. */
+  configurableProviders?: false
+}): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(LlmService)
+  if (options?.settings !== false) await ctx.plugin(MemorySettings, options?.settings)
+  if (options?.credentials !== false) await ctx.plugin(MemoryCredentials, options?.credentials)
+  // Model-provider namespaces plus the explicit Web preference and product
+  // onboarding allowlists are the proxy's complete settings surface.
+  if (options?.configurableProviders !== false) {
+    ctx.llm.registerConfigurableProviders([
+      { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [] },
+    ])
+  }
+  // Host-stream opener reads the committed-workspace baseline; the stub
+  // suffices — the real workspace composition is api-proxy-workspace.spec's.
+  ctx.provide('workspace', { list: () => [] } as never)
+  return ctx
+}
+
+/** Drain `count` host frames matching `types`, then abort the stream. */
+async function collectHost(
+  api: ReturnType<typeof createApiProxy>,
+  types: string[],
+  count: number,
+  run: () => Promise<void>,
+): Promise<HostFrame[]> {
+  const abort = new AbortController()
+  const frames: HostFrame[] = []
+  const stream = api.events.host(request({}), abort.signal)
+  const consume = (async () => {
+    for await (const frame of stream) {
+      if (!types.includes(frame.payload.type)) continue
+      frames.push(frame.payload)
+      if (frames.length >= count) abort.abort()
+    }
+  })()
+  await run()
+  await consume
+  return frames
+}
+
+describe('settings domain', () => {
+  it('reports an actionable error when no settings provider is mounted', async () => {
+    const ctx = await harness({ settings: false })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const error = expectErr(await api.settings.describe(request({})))
+    expect(error.code).toBe('internal')
+    expect(error.message).toContain('dsh-settings-local')
+  })
+
+  it('describes layered redacted namespaces with their secret slots', async () => {
+    const ctx = await harness({ settings: { doc: { 'llm-deepseek': { apiKey: 'user-secret', baseURL: 'https://user' } } } })
+    ctx.settings.register(NS, AdapterConfig, { base: { baseURL: 'https://base' } })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const value = expectOk(await api.settings.describe(request({})))
+    expect(value.writable).toBe(true)
+    expect(value.namespaces).toHaveLength(1)
+    const view = value.namespaces[0]!
+    expect(view.ns).toBe('llm-deepseek')
+    expect(view.applies).toBe('live')
+    expect((view.schema as { refs?: unknown }).refs).toBeDefined()
+    expect(view.value).toEqual({ apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://user' })
+    expect(view.base).toEqual({ baseURL: 'https://base' })
+    expect(view.user).toEqual({ baseURL: 'https://user' })
+    expect(view.secrets).toEqual([{ path: ['apiKey'], set: true }])
+    expect(JSON.stringify(value)).not.toContain('user-secret')
+  })
+
+  it('serves model-provider and explicitly allowlisted Web namespaces only', async () => {
+    // The settings seam is general: any plugin may register a namespace for
+    // its own configuration. The Web configuration plane remains opt-in, so a
+    // future internal plugin cannot become remotely configurable just by
+    // registering; permission and the product onboarding namespace are the
+    // non-model namespaces intentionally admitted by this surface.
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig)
+    ctx.settings.register(settingsNamespace('some-other-plugin'), z.object({ secretPath: z.string() }))
+    ctx.settings.register(settingsNamespace('permission'), z.object({
+      defaultPreset: z.union(['read-only', 'workspace-write']).required(),
+    }), {
+      base: { defaultPreset: 'read-only' },
+    })
+    const api = createApiProxy(ctx, DEFAULTS)
+
+    const value = expectOk(await api.settings.describe(request({})))
+    expect(value.namespaces.map(view => view.ns)).toEqual(['llm-deepseek', 'permission'])
+    const permission = expectOk(await api.settings.mutate(request({
+      ns: 'permission',
+      ops: [{ op: 'set', path: ['defaultPreset'], value: 'workspace-write' }],
+    })))
+    expect(permission.value).toEqual({ defaultPreset: 'workspace-write' })
+
+    for (const response of [
+      await api.settings.update(request({ ns: 'some-other-plugin', patch: { secretPath: '/etc/shadow' } })),
+      await api.settings.replace(request({ ns: 'some-other-plugin', section: {} })),
+    ]) {
+      const error = expectErr(response)
+      expect(error.code).toBe('settings-not-exposed')
+      expect(error.details).toEqual({ ns: 'some-other-plugin' })
+    }
+    // The write never reached the seam.
+    expect(ctx.settings.describe().find(d => String(d.ns) === 'some-other-plugin')?.value).toEqual({})
+  })
+
+  it('serves the product onboarding namespace without invalidating the model catalog', async () => {
+    const ctx = await harness()
+    ctx.settings.register(settingsNamespace('ui-onboarding'), z.object({ welcomeNoticeVersion: z.string() }))
+    const api = createApiProxy(ctx, DEFAULTS)
+    expect(expectOk(await api.settings.describe(request({}))).namespaces.map(view => view.ns))
+      .toEqual(['ui-onboarding'])
+    const frames = await collectHost(api, ['host/settings-changed'], 1, async () => {
+      expectOk(await api.settings.mutate(request({
+        ns: 'ui-onboarding',
+        ops: [{ op: 'set', path: ['welcomeNoticeVersion'], value: 'v1' }],
+      })))
+    })
+    expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'ui-onboarding' }])
+  })
+
+  it('refuses even a model-provider namespace once its directory entry is gone', async () => {
+    const ctx = await harness({ configurableProviders: false })
+    ctx.settings.register(NS, AdapterConfig)
+    const api = createApiProxy(ctx, DEFAULTS)
+    expect(expectOk(await api.settings.describe(request({}))).namespaces).toEqual([])
+    expect(expectErr(await api.settings.update(request({ ns: 'llm-deepseek', patch: { baseURL: 'https://x' } }))).code)
+      .toBe('settings-not-exposed')
+  })
+
+  it('invalidates the model catalog when a provider namespace changes, and broadcasts a raw-only change', async () => {
+    // Editing `models` changes no route, so llm/adapters-updated never fires
+    // and an open model picker kept serving the old catalog. And storing an
+    // override equal to the resolved value emits nothing on settings/updated,
+    // so another tab never learned the field became overridden.
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig, { base: { baseURL: 'https://base' } })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const frames = await collectHost(api, ['host/settings-changed', 'host/models-changed'], 2, async () => {
+      await api.settings.update(request({ ns: 'llm-deepseek', patch: { baseURL: 'https://base' } }))
+    })
+    expect(frames).toEqual([
+      { type: 'host/settings-changed', ns: 'llm-deepseek' },
+      { type: 'host/models-changed' },
+    ])
+    // The resolved value never moved: base already said https://base.
+    expect(expectOk(await api.settings.describe(request({}))).namespaces[0]!.value)
+      .toEqual({ apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://base' })
+  })
+
+  it('broadcasts a permission change without invalidating the model catalog', async () => {
+    const ctx = await harness()
+    const permission = ctx.settings.register(settingsNamespace('permission'), z.object({
+      defaultPreset: z.union(['read-only', 'workspace-write']).required(),
+    }), {
+      base: { defaultPreset: 'read-only' },
+    })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const frames = await collectHost(api, ['host/settings-changed', 'host/models-changed'], 1, async () => {
+      await permission.update({ defaultPreset: 'workspace-write' })
+    })
+    expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'permission' }])
+  })
+
+  it('maps a stale expectedRevision to settings-conflict carrying both revisions', async () => {
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const opened = expectOk(await api.settings.describe(request({}))).namespaces[0]!.revision
+    expect(expectOk(await api.settings.update(request({ ns: 'llm-deepseek', patch: { baseURL: 'https://first' }, expectedRevision: opened })))
+      .revision).toBe(opened + 1)
+    const error = expectErr(await api.settings.update(request({ ns: 'llm-deepseek', patch: { baseURL: 'https://second' }, expectedRevision: opened })))
+    expect(error.code).toBe('settings-conflict')
+    expect(error.details).toEqual({ ns: 'llm-deepseek', expected: opened, actual: opened + 1 })
+    // The refused write changed nothing.
+    expect(expectOk(await api.settings.describe(request({}))).namespaces[0]!.user).toEqual({ baseURL: 'https://first' })
+  })
+
+  it('updates the user layer, answers with the new redacted view, and broadcasts the frame', async () => {
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig, { base: { baseURL: 'https://base' } })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const frames = await collectHost(api, ['host/settings-changed'], 1, async () => {
+      const view = expectOk(await api.settings.update(request({ ns: 'llm-deepseek', patch: { apiKey: 'sk-new', baseURL: 'https://next' } })))
+      expect(view.value).toEqual({ apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://next' })
+      expect(view.user).toEqual({ baseURL: 'https://next' })
+      expect(view.secrets).toEqual([{ path: ['apiKey'], set: true }])
+      expect(JSON.stringify(view)).not.toContain('sk-new')
+    })
+    expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'llm-deepseek' }])
+  })
+
+  it('replace resets the user layer wholesale', async () => {
+    const ctx = await harness({ settings: { doc: { 'llm-deepseek': { baseURL: 'https://user' } } } })
+    ctx.settings.register(NS, AdapterConfig)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const view = expectOk(await api.settings.replace(request({ ns: 'llm-deepseek', section: {} })))
+    expect(view.value).toEqual({ apiKeyEnv: 'DEEPSEEK_API_KEY' })
+    expect(view.user).toEqual({})
+  })
+
+  it.each([
+    ['an invalid namespace name', 'Not A Namespace', {}],
+    ['a schema-invalid patch', 'llm-deepseek', { baseURL: 42 }],
+  ])('rejects %s as settings-rejected', async (_case, ns, patch) => {
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const error = expectErr(await api.settings.update(request({ ns, patch })))
+    expect(error.code).toBe('settings-rejected')
+    expect(error.details).toEqual({ ns })
+  })
+
+  it('answers an unregistered namespace exactly like an unexposed one', async () => {
+    // Deliberately indistinguishable: separating "does not exist" from
+    // "exists but is not yours to configure" would let a caller enumerate the
+    // registered namespaces one probe at a time.
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig)
+    ctx.settings.register(settingsNamespace('some-other-plugin'), z.object({ secretPath: z.string() }))
+    const api = createApiProxy(ctx, DEFAULTS)
+    const unknown = expectErr(await api.settings.update(request({ ns: 'unknown-ns', patch: {} })))
+    const unexposed = expectErr(await api.settings.update(request({ ns: 'some-other-plugin', patch: {} })))
+    expect(unknown.code).toBe('settings-not-exposed')
+    expect(unexposed.code).toBe(unknown.code)
+    expect(unexposed.message.replace('some-other-plugin', 'unknown-ns')).toBe(unknown.message)
+  })
+
+  it('maps a read-only provider refusal onto the same rejection', async () => {
+    const ctx = await harness({ settings: { readOnly: true } })
+    ctx.settings.register(NS, AdapterConfig)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const value = expectOk(await api.settings.describe(request({})))
+    expect(value.writable).toBe(false)
+    const error = expectErr(await api.settings.update(request({ ns: 'llm-deepseek', patch: {} })))
+    expect(error.code).toBe('settings-rejected')
+    expect(error.message).toContain('read-only')
+  })
+})
+
+describe('credentials domain', () => {
+  it('reports an actionable error when no credential provider is mounted', async () => {
+    const ctx = await harness({ credentials: false })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const error = expectErr(await api.credentials.describe(request({ refs: ['A'] })))
+    expect(error.code).toBe('internal')
+    expect(error.message).toContain('dsh-credentials-local')
+  })
+
+  it('describes value-free views and flips state through set/unset with frames', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const before = expectOk(await api.credentials.describe(request({ refs: ['OPENAI_API_KEY'] })))
+    expect(before.credentials).toEqual({ OPENAI_API_KEY: { configured: false, writable: true } })
+    const frames = await collectHost(api, ['host/credentials-changed'], 2, async () => {
+      expectOk(await api.credentials.set(request({ ref: 'OPENAI_API_KEY', value: 'sk-secret' })))
+      const after = expectOk(await api.credentials.describe(request({ refs: ['OPENAI_API_KEY'] })))
+      expect(after.credentials).toEqual({ OPENAI_API_KEY: { configured: true, source: 'file', writable: true } })
+      expect(JSON.stringify(after)).not.toContain('sk-secret')
+      expectOk(await api.credentials.unset(request({ ref: 'OPENAI_API_KEY' })))
+    })
+    expect(frames).toEqual([
+      { type: 'host/credentials-changed', ref: 'OPENAI_API_KEY' },
+      { type: 'host/credentials-changed', ref: 'OPENAI_API_KEY' },
+    ])
+  })
+
+  it('maps a shadowed write onto credential-rejected for set and unset alike', async () => {
+    const ctx = await harness({ credentials: { shadowed: ['DEEPSEEK_API_KEY'] } })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const described = expectOk(await api.credentials.describe(request({ refs: ['DEEPSEEK_API_KEY'] })))
+    expect(described.credentials['DEEPSEEK_API_KEY']).toEqual({ configured: true, source: 'env', writable: false })
+    const setError = expectErr(await api.credentials.set(request({ ref: 'DEEPSEEK_API_KEY', value: 'x' })))
+    expect(setError.code).toBe('credential-rejected')
+    expect(setError.details).toEqual({ ref: 'DEEPSEEK_API_KEY' })
+    const unsetError = expectErr(await api.credentials.unset(request({ ref: 'DEEPSEEK_API_KEY' })))
+    expect(unsetError.code).toBe('credential-rejected')
+  })
+})
+
+describe('llm domain', () => {
+  it('merges the configurable directory with live routes and appends undeclared ones', async () => {
+    const ctx = await harness({ configurableProviders: false })
+    ctx.llm.registerConfigurableProviders([
+      { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [] },
+      { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] },
+    ])
+    ctx.llm.registerAdapter(['deepseek-official'], new CatalogAdapter('DeepSeek', ['deepseek-v4-flash']))
+    ctx.llm.registerAdapter(['undeclared'], new CatalogAdapter('Undeclared', ['u-1']))
+    const api = createApiProxy(ctx, DEFAULTS)
+    const value = expectOk(await api.llm.providers(request({})))
+    expect(value.providers).toEqual([
+      { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [], active: true },
+      { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'], active: false },
+      { provider: 'undeclared', displayName: 'Undeclared', settingsNs: '', settingsPath: [], active: true },
+    ])
+  })
+
+  it('serves the host-scoped catalog with per-provider failures contained', async () => {
+    const ctx = await harness()
+    ctx.llm.registerAdapter(['deepseek-official'], new CatalogAdapter('DeepSeek', ['deepseek-v4-flash', 'deepseek-v4-pro']))
+    ctx.llm.registerAdapter(['broken'], new BrokenCatalogAdapter('Broken', []))
+    const api = createApiProxy(ctx, DEFAULTS)
+    const value = expectOk(await api.llm.models(request({})))
+    expect(value.groups).toEqual([{
+      id: 'deepseek-official',
+      name: 'DeepSeek',
+      models: [
+        { id: 'deepseek-v4-flash', name: 'deepseek-v4-flash' },
+        { id: 'deepseek-v4-pro', name: 'deepseek-v4-pro' },
+      ],
+    }])
+    expect(value.failures).toEqual([{ id: 'broken', name: 'Broken', message: 'catalog backend down' }])
+  })
+
+  it('broadcasts host/models-changed at every topology commit point', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const frames = await collectHost(api, ['host/models-changed'], 2, async () => {
+      const dispose = ctx.llm.registerAdapter(['deepseek-official'], new CatalogAdapter('DeepSeek', []))
+      dispose()
+      return Promise.resolve()
+    })
+    expect(frames).toEqual([{ type: 'host/models-changed' }, { type: 'host/models-changed' }])
+  })
+})

packages/host/apiproxy/tests/api-proxy-fork.spec.ts

@@ -0,0 +1,184 @@
+/** Session-fork boundaries, lineage, and inherited model routing. */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentHandle, CreateAgentOptions } from '@deepseek-ai/dsh-agent'
+import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
+
+const sid = (id: string): SessionId => id as SessionId
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`fork-${String(nextRpc++)}`), payload }
+}
+
+async function composed(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(UserInteractionService)
+  ctx.provide('workspace', { list: () => [] } as never)
+  ctx.agents.setFactory({
+    createAgent: async (ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle> => {
+      const session = ctx.sessions.create(options.sessionId, {
+        ...options.seed === undefined ? {} : { seed: [...options.seed] },
+        ...options.meta === undefined ? {} : { meta: options.meta },
+      })
+      const agent = {} as Agent
+      const agentCtx = ownerCtx.extend({ agent })
+      Object.assign(agent, { id: session.id, session, status: 'idle', ctx: agentCtx })
+      await options.setup?.(agentCtx)
+      ctx.agents.register(agent)
+      return { agent, dispose: () => Promise.resolve() }
+    },
+    resume: () => Promise.reject(new Error('fork test sources are live')),
+  })
+  return ctx
+}
+
+/** Tail turn appended after the completed ones: left open, or closed as aborted (a stopped turn). */
+type Tail = 'none' | 'open' | 'aborted'
+
+function liveAgent(ctx: Context, id: string, turns: number, tail: Tail = 'none'): Session {
+  const session = ctx.sessions.create(sid(id), { meta: { cwd: '/proj' } })
+  for (let turn = 1; turn <= turns; turn++) {
+    session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: `prompt ${String(turn)}` }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    session.append('turn/end', { turn, reason: { kind: 'completed' } })
+  }
+  if (tail !== 'none') {
+    session.append('turn/start', { turn: turns + 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'open prompt' }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    if (tail === 'aborted') session.append('turn/end', { turn: turns + 1, reason: { kind: 'aborted' } })
+  }
+  ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
+  return session
+}
+
+const api = (ctx: Context) => createApiProxy(ctx, {
+  provider: 'default-provider',
+  model: 'default-model',
+  cwd: '/tmp',
+  workspaceRoot: '/tmp',
+})
+
+describe('sessions.fork', () => {
+  it('cuts at the anchored completed turn and records lineage and cwd', async () => {
+    const ctx = await composed()
+    const source = liveAgent(ctx, 'session-source', 2)
+    const response = await api(ctx).sessions.fork(request({ sessionId: source.id, atSeq: 1 }))
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) return
+    const child = ctx.sessions.get(response.result.value.sessionId)
+    expect(child?.events.map(event => event.type)).toEqual([
+      'turn/start', 'user/message', 'turn/end', 'session/end-seed',
+    ])
+    expect(child?.header.parentSession).toBe(source.id)
+    expect(child?.header.cwd).toBe('/proj')
+    await ctx.fiber.dispose()
+  })
+
+  it('uses the last completed turn only for omitted and past-end anchors', async () => {
+    const ctx = await composed()
+    const source = liveAgent(ctx, 'session-tail', 2, 'open')
+    const proxy = api(ctx)
+    const expectedTypes = [
+      'turn/start', 'user/message', 'turn/end',
+      'turn/start', 'user/message', 'turn/end',
+      'session/end-seed',
+    ]
+    const omitted = await proxy.sessions.fork(request({ sessionId: source.id }))
+    expect(omitted.result.ok).toBe(true)
+    if (omitted.result.ok) {
+      expect(ctx.sessions.get(omitted.result.value.sessionId)?.events.map(event => event.type))
+        .toEqual(expectedTypes)
+    }
+    const pastEnd = await proxy.sessions.fork(request({ sessionId: source.id, atSeq: 999 }))
+    expect(pastEnd.result.ok).toBe(true)
+    if (pastEnd.result.ok) {
+      expect(ctx.sessions.get(pastEnd.result.value.sessionId)?.events.map(event => event.type))
+        .toEqual(expectedTypes)
+    }
+    await ctx.fiber.dispose()
+  })
+
+  it('cuts through an aborted turn: stopped is closed, not open', async () => {
+    const ctx = await composed()
+    const source = liveAgent(ctx, 'session-aborted', 1, 'aborted')
+    // What a stopped message's fork button anchors on: the frozen node sits
+    // one event before its turn/end, floored client-side to that event's seq.
+    const anchor = (source.events.at(-1)?.seq ?? 0) - 1
+    const response = await api(ctx).sessions.fork(request({ sessionId: source.id, atSeq: anchor }))
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) return
+    expect(ctx.sessions.get(response.result.value.sessionId)?.events.map(event => event.type)).toEqual([
+      'turn/start', 'user/message', 'turn/end',
+      'turn/start', 'user/message', 'turn/end',
+      'session/end-seed',
+    ])
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects an in-log anchor whose turn is still open', async () => {
+    const ctx = await composed()
+    const source = liveAgent(ctx, 'session-open', 1, 'open')
+    const anchor = source.events.at(-1)?.seq ?? 0
+    const response = await api(ctx).sessions.fork(request({ sessionId: source.id, atSeq: anchor }))
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'fork-unavailable', details: { sessionId: source.id } },
+    })
+    if (!response.result.ok) expect(response.result.error.message).toMatch(/has not completed/)
+    await ctx.fiber.dispose()
+  })
+
+  it('installs the latest logged model target before the child can run', async () => {
+    const ctx = await composed()
+    const source = liveAgent(ctx, 'session-routed', 1)
+    source.append('request/header', {
+      header: {
+        config: {
+          provider: 'inherited-provider',
+          model: 'inherited-model',
+          reasoningEffort: ReasoningEffortId('high'),
+        },
+      },
+      reason: 'initial',
+    })
+    const response = await api(ctx).sessions.fork(request({ sessionId: source.id }))
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) return
+    const child = ctx.agents.get(response.result.value.sessionId)
+    if (child === undefined) throw new Error('fork did not publish the child agent')
+    const assembly = await child.ctx.systemPrompt.assemble()
+    expect(assembly.variables).toMatchObject({
+      provider: 'inherited-provider',
+      model: 'inherited-model',
+    })
+    const fallback: LlmCallConfig = { provider: 'default-provider', model: 'default-model' }
+    await expect(agentEvents(child.ctx, child).waterfall(
+      'agent/request', 1, 0, new AbortController().signal, () => Promise.resolve(fallback),
+    )).resolves.toMatchObject({
+      provider: 'inherited-provider',
+      model: 'inherited-model',
+      reasoningEffort: 'high',
+    })
+    await ctx.fiber.dispose()
+  })
+})

packages/host/apiproxy/tests/api-proxy-models.spec.ts

@@ -85,9 +85,9 @@ async function harness(logged?: {
   await ctx.plugin(LlmService)
   await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
-  ctx.llm.registerAdapter(['deepseek'], new CatalogAdapter('DeepSeek', [
-    { provider: 'deepseek', id: 'deepseek-chat', name: 'DeepSeek Chat' },
-    { provider: 'deepseek', id: 'deepseek-reasoner', name: 'DeepSeek Reasoner', description: 'Reasoning model' },
+  ctx.llm.registerAdapter(['deepseek-official'], new CatalogAdapter('DeepSeek', [
+    { provider: 'deepseek-official', id: 'deepseek-chat', name: 'DeepSeek Chat' },
+    { provider: 'deepseek-official', id: 'deepseek-reasoner', name: 'DeepSeek Reasoner', description: 'Reasoning model' },
   ], REASONING))
   ctx.llm.registerAdapter(['broken'], new CatalogAdapter('Broken Provider', new Error('catalog offline')))
   ctx.llm.registerAdapter(['metadata-broken'], new CatalogAdapter('Metadata Broken', [
@@ -120,20 +120,20 @@ function expectValue<T>(response: { result: { ok: true; value: T } | { ok: false
 describe('Web session model selection', () => {
   it('groups successful providers, isolates failures, and preserves an unlisted current model', async () => {
     const { ctx, sessionId } = await harness({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
       model: 'private-preview',
       reasoningEffort: ReasoningEffortId('max'),
     })
-    const api = createApiProxy(ctx, { provider: 'deepseek', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { provider: 'deepseek-official', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const catalog = expectValue(await api.sessions.models(request({ sessionId })))
     expect(catalog.current).toEqual({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
       model: 'private-preview',
       reasoningEffort: 'max',
     })
     expect(catalog.groups).toEqual([{
-      id: 'deepseek',
+      id: 'deepseek-official',
       name: 'DeepSeek',
       models: [
         { id: 'deepseek-chat', name: 'DeepSeek Chat', reasoning: REASONING },
@@ -165,43 +165,43 @@ describe('Web session model selection', () => {
 
   it('accepts an advisory-unlisted model, rejects an unavailable provider, and switches only after the next assembly', async () => {
     const { ctx, agent, sessionId } = await harness()
-    const api = createApiProxy(ctx, { provider: 'deepseek', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { provider: 'deepseek-official', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
     const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
     const signal = new AbortController().signal
 
     expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
-      .toEqual({ provider: 'deepseek', model: 'deepseek-chat' })
+      .toEqual({ provider: 'deepseek-official', model: 'deepseek-chat' })
     expect((await ctx.systemPrompt.assemble()).variables)
-      .toMatchObject({ provider: 'deepseek', model: 'deepseek-chat' })
+      .toMatchObject({ provider: 'deepseek-official', model: 'deepseek-chat' })
 
     const selected = expectValue(await api.sessions.selectModel(request({
       sessionId,
-      provider: 'deepseek',
+      provider: 'deepseek-official',
       model: 'private-preview',
       reasoningEffort: 'max',
     })))
     expect(selected.selected).toEqual({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
       model: 'private-preview',
       reasoningEffort: 'max',
     })
     await expect(agentEvents(ctx, agent).waterfall(
       'agent/request', 1, 0, signal, () => Promise.resolve(seed),
-    )).resolves.toMatchObject({ provider: 'deepseek', model: 'deepseek-chat' })
+    )).resolves.toMatchObject({ provider: 'deepseek-official', model: 'deepseek-chat' })
 
     expect((await ctx.systemPrompt.assemble()).variables)
-      .toMatchObject({ provider: 'deepseek', model: 'private-preview' })
+      .toMatchObject({ provider: 'deepseek-official', model: 'private-preview' })
     await expect(agentEvents(ctx, agent).waterfall(
       'agent/request', 1, 1, signal, () => Promise.resolve(seed),
     )).resolves.toMatchObject({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
       model: 'private-preview',
       reasoningEffort: 'max',
     })
 
     const unsupported = await api.sessions.selectModel(request({
       sessionId,
-      provider: 'deepseek',
+      provider: 'deepseek-official',
       model: 'private-preview',
       reasoningEffort: 'medium',
     }))
@@ -209,7 +209,7 @@ describe('Web session model selection', () => {
       ok: false,
       error: {
         code: 'model-unavailable',
-        message: 'provider "deepseek" model "private-preview" does not support reasoning effort "medium"',
+        message: 'provider "deepseek-official" model "private-preview" does not support reasoning effort "medium"',
       },
     })
 
@@ -227,7 +227,7 @@ describe('Web session model selection', () => {
       },
     })
     expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
-      .toEqual({ provider: 'deepseek', model: 'private-preview', reasoningEffort: 'max' })
+      .toEqual({ provider: 'deepseek-official', model: 'private-preview', reasoningEffort: 'max' })
     await ctx.fiber.dispose()
   })
 })

packages/host/apiproxy/tests/api-proxy-projections.spec.ts

@@ -0,0 +1,261 @@
+/**
+ * Projection carrier paths of the host ApiProxy: the history tail page's
+ * projections block reads the registry's watermark snapshot (asOfSeq = last
+ * event seq, one consistent cut); loadOlder pages never carry the block; a
+ * composition without the registry serves histories without it; a disposed
+ * registration's key leaves subsequent responses; and every unit change is
+ * pushed to mux consumers as a session/projection frame minted here.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { z } from 'zod'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import type { Session } from '@deepseek-ai/dsh-session'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import type { MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    'test/last-user': { text: string } | null
+  }
+}
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`proj-${String(nextRpc++)}`), payload }
+}
+
+/** Whole-value unit folding the latest user/message text; null before the first. */
+type LastUserState = { text: string } | null
+const lastUserUnit = (): ProjectionDefinition<'test/last-user', LastUserState> => ({
+  key: 'test/last-user',
+  schema: z.union([z.object({ text: z.string() }), z.null()]),
+  init: () => null,
+  apply: (state, event) => (event.type === 'user/message'
+    ? { text: (event.data.content[0] as { text?: string }).text ?? '' }
+    : state),
+  view: state => state,
+  stateVersion: 1,
+})
+
+async function harness(withRegistry: boolean): Promise<{ ctx: Context; session: Session }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(AgentRegistry)
+  if (withRegistry) await ctx.plugin(SessionProjectionRegistry)
+  const session = ctx.sessions.create()
+  // history resolves the agent first; a live structural stub is enough (only
+  // .session is read on this path).
+  ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
+  return { ctx, session }
+}
+
+/** Append `count` user messages so the log has paginable message boundaries. */
+function seedMessages(session: Session, count: number): void {
+  for (let i = 0; i < count; i++) {
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: `m${i}` }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+  }
+}
+
+const api = (ctx: Context) => createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+
+describe('session.history projections block', () => {
+  it('serves the unit value on the tail page with asOfSeq = last event seq', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register(lastUserUnit())
+    seedMessages(session, 3)
+    const response = await api(ctx).sessions.history(request({ sessionId: session.id }))
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    const { events, projections } = response.result.value
+    expect(projections).toBeDefined()
+    expect(projections?.asOfSeq).toBe(session.seq - 1)
+    expect(projections?.values['test/last-user']).toEqual({ text: 'm2' })
+    // asOfSeq IS the window tail: the last served event carries it.
+    expect(events.at(-1)?.event.seq).toBe(projections?.asOfSeq)
+  })
+
+  it('never carries the block on loadOlder pages (beforeSeq present)', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register(lastUserUnit())
+    seedMessages(session, 5)
+    const older = await api(ctx).sessions.history(request({ sessionId: session.id, beforeSeq: 3, maxMessages: 2 }))
+    expect(older.result.ok).toBe(true)
+    if (!older.result.ok) throw new Error('unreachable')
+    expect('projections' in older.result.value).toBe(false)
+  })
+
+  it('serves no block when the composition has no projection registry', async () => {
+    const { ctx, session } = await harness(false)
+    seedMessages(session, 2)
+    const response = await api(ctx).sessions.history(request({ sessionId: session.id }))
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    expect('projections' in response.result.value).toBe(false)
+  })
+
+  it('drops a disposed registration from subsequent tail pages (empty block, key absent)', async () => {
+    const { ctx, session } = await harness(true)
+    const dispose = ctx.sessionProjections.register(lastUserUnit())
+    seedMessages(session, 1)
+    const proxy = api(ctx)
+    const before = await proxy.sessions.history(request({ sessionId: session.id }))
+    if (!before.result.ok) throw new Error('unreachable')
+    expect(before.result.value.projections?.values['test/last-user']).toEqual({ text: 'm0' })
+
+    dispose()
+    const after = await proxy.sessions.history(request({ sessionId: session.id }))
+    if (!after.result.ok) throw new Error('unreachable')
+    // The registry is still mounted, so the block itself stays (asOfSeq cut
+    // with zero keys); the disposed key reads as capability absence.
+    expect(after.result.value.projections?.asOfSeq).toBe(session.seq - 1)
+    expect(after.result.value.projections?.values).toEqual({})
+  })
+})
+
+describe('session.list projections column', () => {
+  it('serves attached rows from the live registry cut, watermarked for client seeding', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register(lastUserUnit())
+    seedMessages(session, 1)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === session.id)
+    expect(row?.projections?.values['test/last-user']).toEqual({ text: 'm0' })
+    expect(row?.projections?.asOfSeq).toBe(session.seq - 1)
+  })
+
+  it('omits the column entirely when no registry is mounted', async () => {
+    const { ctx, session } = await harness(false)
+    seedMessages(session, 1)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === session.id)
+    expect(row).toBeDefined()
+    expect(row !== undefined && 'projections' in row).toBe(false)
+  })
+
+  it('serves cold rows from the persisted projection cache with zero log loads', async () => {
+    const { ctx } = await harness(true)
+    const coldId = SessionId('session-cold-listing')
+    const load = () => { throw new Error('list must not load event logs') }
+    ctx.provide('sessionPersistence', {
+      list: async () => [{ version: 0, id: coldId, createdAt: 5, cwd: '/tmp' }],
+      locate: () => undefined,
+      load,
+      inspect: load,
+      readFrom: load,
+    } as never)
+    ctx.provide('sessionProjectionCache', {
+      // The carrier hands the listed header through as the identity witness.
+      cachedSnapshot: (meta: { id: unknown; createdAt: number }) =>
+        (meta.id === coldId && meta.createdAt === 5
+          ? { asOfSeq: 7, values: { 'test/last-user': { text: 'cached' } } }
+          : undefined),
+    } as never)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === coldId)
+    expect(row?.running).toBe(false)
+    expect(row?.projections).toEqual({ asOfSeq: 7, values: { 'test/last-user': { text: 'cached' } } })
+  })
+
+  it('cold rows without a cache plugin (or without a stored row) just lack the column', async () => {
+    const { ctx } = await harness(true)
+    const coldId = SessionId('session-cold-uncached')
+    ctx.provide('sessionPersistence', {
+      list: async () => [{ version: 0, id: coldId, createdAt: 5, cwd: '/tmp' }],
+      locate: () => undefined,
+    } as never)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === coldId)
+    expect(row).toBeDefined()
+    expect(row !== undefined && 'projections' in row).toBe(false)
+  })
+
+  it('a throwing column read degrades that row, never the listing', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register({
+      ...lastUserUnit(),
+      view: () => { throw new Error('unit exploded') },
+    })
+    seedMessages(session, 1)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === session.id)
+    expect(row).toBeDefined()
+    expect(row !== undefined && 'projections' in row).toBe(false)
+  })
+})
+
+describe('session/projection push frame', () => {
+  /** Drain frames until `count` session/projection frames arrived. */
+  async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: number, abort: AbortController): Promise<MuxFrame[]> {
+    const frames: MuxFrame[] = []
+    for await (const envelope of iterable) {
+      frames.push(envelope.payload)
+      if (frames.filter(f => f.type === 'session/projection').length >= count) abort.abort()
+    }
+    return frames
+  }
+
+  it('broadcasts a frame per changed unit with the causing seq, and none for same-reference applies', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register(lastUserUnit())
+    const proxy = api(ctx)
+    // The gateway's onChanged subscription lives in an inject child whose
+    // fiber activates asynchronously; yield until it lands before appending.
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const abort = new AbortController()
+    const stream = proxy.events.mux({ rpcId: RpcId('t-proj-mux'), payload: {} }, abort.signal)
+    const collected = collect(stream, 2, abort)
+
+    seedMessages(session, 1)
+    // Same-reference apply: turn/start does not concern the unit — no frame.
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    seedMessages(session, 1)
+
+    const frames = await collected
+    const pushes = frames.filter(
+      (f): f is Extract<MuxFrame, { type: 'session/projection' }> => f.type === 'session/projection',
+    )
+    expect(pushes).toEqual([
+      { type: 'session/projection', sessionId: session.id, key: 'test/last-user', value: { text: 'm0' }, seq: 0 },
+      { type: 'session/projection', sessionId: session.id, key: 'test/last-user', value: { text: 'm0' }, seq: 2 },
+    ])
+    // Frame seq aligns with the tail block's asOfSeq vocabulary (higher-seq-wins compatible).
+    const tail = await proxy.sessions.history(request({ sessionId: session.id }))
+    if (!tail.result.ok) throw new Error('unreachable')
+    expect(tail.result.value.projections?.asOfSeq).toBe(pushes.at(-1)?.seq)
+  })
+
+  it('emits no projection frames when the composition has no registry', async () => {
+    const { ctx, session } = await harness(false)
+    const proxy = api(ctx)
+    const abort = new AbortController()
+    const stream = proxy.events.mux({ rpcId: RpcId('t-noproj-mux'), payload: {} }, abort.signal)
+    const frames: MuxFrame[] = []
+    const drained = (async () => {
+      for await (const envelope of stream) {
+        frames.push(envelope.payload)
+        if (frames.filter(f => f.type === 'session/event').length >= 2) abort.abort()
+      }
+    })()
+    seedMessages(session, 2)
+    await drained
+    expect(frames.some(f => f.type === 'session/projection')).toBe(false)
+  })
+})

packages/host/apiproxy/tests/api-proxy-rename.spec.ts

@@ -0,0 +1,129 @@
+/**
+ * sessions.rename delegation through the composed SessionTitleService. The
+ * agent factory is a structural stub whose createAgent forwards seed/meta into
+ * the real SessionStore, and whose resume never runs (every source here is
+ * already attached). Cold-session resolution is the shared `agentFor` path —
+ * api-proxy-cold.spec.ts owns the resume evidence for every unary that rides
+ * it, rename included.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore from '@deepseek-ai/dsh-session'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentHandle, CreateAgentOptions } from '@deepseek-ai/dsh-agent'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import SessionTitleService from '@deepseek-ai/dsh-session-title'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import type { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
+
+const sid = (id: string): SessionId => id as SessionId
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`fr-${String(nextRpc++)}`), payload }
+}
+
+async function composed(withTitles = true): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(UserInteractionService)
+  if (withTitles) {
+    await ctx.plugin(SessionTitleService, { fallbackMaxWords: 5, fallbackMaxBytes: 40, maxTitleBytes: 40 })
+  }
+  // Store-backed structural factory: create builds the session with the
+  // forwarded seed/meta (the store validates the balanced prefix) and
+  // registers an idle agent stub over it.
+  ctx.agents.setFactory({
+    createAgent: (ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle> => {
+      const session = ctx.sessions.create(options.sessionId, {
+        ...options.seed === undefined ? {} : { seed: [...options.seed] },
+        ...options.meta === undefined ? {} : { meta: options.meta },
+      })
+      const agent = { id: session.id, session, status: 'idle', ctx: ownerCtx } as Agent
+      ctx.agents.register(agent)
+      return Promise.resolve({ agent, dispose: () => Promise.resolve() })
+    },
+    resume: () => Promise.reject(new Error('resume must not run: every source is attached')),
+  })
+  return ctx
+}
+
+/** Register one live agent whose log holds `turns` completed turns. */
+function liveAgent(ctx: Context, id: string, turns: number): Session {
+  const session = ctx.sessions.create(sid(id), { meta: { cwd: '/proj' } })
+  for (let turn = 1; turn <= turns; turn++) {
+    session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: `prompt ${String(turn)}` }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    session.append('turn/end', { turn, reason: { kind: 'completed' } })
+  }
+  ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
+  return session
+}
+
+const api = (ctx: Context) => createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+
+describe('sessions.rename', () => {
+  it('accepts through the composed title service: normalized user-source event, echoed seq', async () => {
+    const ctx = await composed()
+    const source = liveAgent(ctx, 'session-rename', 1)
+
+    const renamed = await api(ctx).sessions.rename(request({ sessionId: source.id, title: '  new   name  ' }))
+    expect(renamed.result.ok).toBe(true)
+    if (!renamed.result.ok) return
+    expect(renamed.result.value.title).toBe('new name')
+    const event = source.events.findLast(item => item.type === 'session/title')
+    expect(event?.seq).toBe(renamed.result.value.seq)
+    expect(event?.data).toMatchObject({ title: 'new name', source: { kind: 'user' } })
+  })
+
+  it('maps only an empty-normalizing title to title-invalid, with a presentable message', async () => {
+    const ctx = await composed()
+    const source = liveAgent(ctx, 'session-rename-bad', 1)
+
+    // U+200B passes a client-side trim gate but normalizes to empty host-side.
+    const response = await api(ctx).sessions.rename(request({ sessionId: source.id, title: ' ​ ' }))
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) {
+      expect(response.result.error).toMatchObject({
+        code: 'title-invalid',
+        details: { sessionId: source.id },
+      })
+      // The message renders verbatim in the rename dialog's alert.
+      expect(response.result.error.message).toBe('session title must contain visible characters')
+    }
+  })
+
+  it('maps a non-validation rename failure (stale session object) to internal, not title-invalid', async () => {
+    const ctx = await composed()
+    // The registered agent holds a session object from another store: the
+    // title service's liveness check throws a plain Error, which must not
+    // read as the user's fault.
+    const foreign = await composed(false)
+    const stale = liveAgent(foreign, 'session-rename-stale', 1)
+    ctx.agents.register({ id: stale.id, session: stale, status: 'idle', ctx } as Agent)
+
+    const response = await api(ctx).sessions.rename(request({ sessionId: stale.id, title: 'name' }))
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) expect(response.result.error.code).toBe('internal')
+  })
+
+  it('answers internal when the composition mounts no session-title service', async () => {
+    const ctx = await composed(false)
+    const source = liveAgent(ctx, 'session-no-titles', 1)
+
+    const response = await api(ctx).sessions.rename(request({ sessionId: source.id, title: 'name' }))
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) {
+      expect(response.result.error.code).toBe('internal')
+      expect(response.result.error.message).toMatch(/mounts no session-title service/)
+    }
+  })
+})

packages/host/apiproxy/tests/api-proxy-search.spec.ts

@@ -0,0 +1,880 @@
+/**
+ * Host session.search projection: list-equivalent visibility, fixed message
+ * filters and result bound, cancellation mapping, and unavailable/failure
+ * behavior.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import { stat } from 'node:fs/promises'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import {
+  SessionQueryError,
+  type SessionSearchHit,
+  type SessionSearchRequest,
+} from '@deepseek-ai/dsh-session-query'
+import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
+
+vi.mock('node:fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs/promises')>()
+  return { ...actual, stat: vi.fn(actual.stat) }
+})
+
+const sid = (value: string): SessionId => value as SessionId
+const defaults = { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }
+
+function request(query: string): RpcRequest<{ query: string }> {
+  return { rpcId: RpcId(`search-${query}`), payload: { query } }
+}
+
+function header(id: string, cwd: string | null = '/project'): SessionHeader {
+  return {
+    version: 0,
+    id: sid(id),
+    createdAt: 100,
+    ...(cwd === null ? {} : { cwd }),
+  }
+}
+
+function hit(id: string, index = 0): SessionSearchHit {
+  const session = header(id)
+  return {
+    header: session,
+    live: true,
+    persisted: false,
+    bestMatch: {
+      sessionId: session.id,
+      seq: index,
+      type: 'user/message',
+      time: 200 + index,
+      surface: 'current',
+      snippet: `match ${index}`,
+    },
+  }
+}
+
+async function baseContext(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(UserInteractionService)
+  return ctx
+}
+
+describe('session.search', () => {
+  it('searches only list-visible ids and current conversation-message events', async () => {
+    const ctx = await baseContext()
+    const live = ctx.sessions.create(sid('live'), { meta: header('live', '/live') })
+    live.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'live text' }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    const cold = header('cold', '/cold')
+    const legacy = header('legacy', null)
+    ctx.provide('sessionPersistence', {
+      list: () => Promise.resolve([cold, legacy]),
+      locate: () => undefined,
+    } as never)
+
+    const searchSessions = vi.fn((
+      _request: SessionSearchRequest,
+      _exec?: { signal?: AbortSignal },
+    ) => Promise.resolve({
+      items: [
+        {
+          header: legacy,
+          live: false,
+          persisted: true,
+          bestMatch: {
+            sessionId: legacy.id,
+            seq: 3,
+            type: 'user/message' as const,
+            time: 190,
+            surface: 'current' as const,
+            snippet: 'must remain hidden',
+          },
+        },
+        {
+          header: cold,
+          live: false,
+          persisted: true,
+          bestMatch: {
+            sessionId: cold.id,
+            seq: 4,
+            type: 'assistant/message' as const,
+            time: 200,
+            surface: 'current' as const,
+            snippet: 'the matching answer',
+          },
+        },
+      ],
+    }))
+    ctx.provide('sessionQuery', { searchSessions } as never)
+    const api = createApiProxy(ctx, defaults)
+    const signal = new AbortController().signal
+
+    const response = await api.sessions.search(request('matching answer'), signal)
+
+    expect(response.result).toEqual({
+      ok: true,
+      value: {
+        items: [{ sessionId: 'cold', snippet: 'the matching answer' }],
+        hasMore: false,
+      },
+    })
+    expect(searchSessions).toHaveBeenCalledOnce()
+    const [query, exec] = searchSessions.mock.calls[0] as unknown as [
+      SessionSearchRequest,
+      { signal: AbortSignal },
+    ]
+    expect(query).toEqual({
+      query: 'matching answer',
+      eventFilters: [
+        {
+          kind: 'type',
+          values: ['user/message', 'assistant/message', 'steering/message'],
+        },
+        { kind: 'surface', values: ['current'] },
+      ],
+      limit: 20,
+    })
+    expect(exec.signal).toBe(signal)
+  })
+
+  it('returns an empty page without invoking the index when no session is visible', async () => {
+    const ctx = await baseContext()
+    const searchSessions = vi.fn()
+    ctx.provide('sessionQuery', { searchSessions } as never)
+    const api = createApiProxy(ctx, defaults)
+
+    const response = await api.sessions.search(
+      request('anything'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toEqual({
+      ok: true,
+      value: { items: [], hasMore: false },
+    })
+    expect(searchSessions).not.toHaveBeenCalled()
+  })
+
+  it('rejects snippets whose provider provenance violates the Host filters', async () => {
+    const ctx = await baseContext()
+    const visible = hit('visible')
+    ctx.sessions.create(visible.header.id, { meta: visible.header })
+    const withBestMatch = (
+      index: number,
+      bestMatch: Partial<SessionSearchHit['bestMatch']>,
+    ): SessionSearchHit => {
+      const base = hit('visible', index)
+      return { ...base, bestMatch: { ...base.bestMatch, ...bestMatch } }
+    }
+    ctx.provide('sessionQuery', {
+      searchSessions: () => Promise.resolve({
+        items: [
+          withBestMatch(0, { sessionId: sid('hidden') }),
+          withBestMatch(1, { surface: 'shadowed' }),
+          withBestMatch(2, { type: 'tool/result' }),
+          withBestMatch(3, { type: 'steering/message', snippet: 'allowed snippet' }),
+        ],
+      }),
+    } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('match'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toEqual({
+      ok: true,
+      value: {
+        items: [{ sessionId: 'visible', snippet: 'allowed snippet' }],
+        hasMore: false,
+      },
+    })
+  })
+
+  it('pages the globally ranked stream until the 20-item Host boundary is known', async () => {
+    const ctx = await baseContext()
+    const items = Array.from({ length: 21 }, (_, index) => hit(`visible-${index}`, index))
+    for (const item of items) {
+      ctx.sessions.create(item.header.id, { meta: item.header })
+    }
+    const searchSessions = vi.fn()
+      .mockResolvedValueOnce({
+        items: [hit('hidden-ranked-first'), ...items.slice(0, 19)],
+        nextCursor: 'page-2',
+      })
+      .mockResolvedValueOnce({ items: items.slice(19) })
+    ctx.provide('sessionQuery', {
+      searchSessions,
+    } as never)
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('match'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: true,
+      value: { hasMore: true },
+    })
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value.items).toHaveLength(20)
+    expect(response.result.value.items.at(-1)?.sessionId).toBe('visible-19')
+    expect(searchSessions).toHaveBeenCalledTimes(2)
+    expect(searchSessions.mock.calls[1]?.[0]).toMatchObject({ cursor: 'page-2' })
+  })
+
+  it('learns a provider maxLimit of 10 and collects the 20-item result plus lookahead', async () => {
+    const ctx = await baseContext()
+    const items = Array.from({ length: 21 }, (_, index) => hit(`visible-${index}`, index))
+    for (const item of items) {
+      ctx.sessions.create(item.header.id, { meta: item.header })
+    }
+    const invalidLimit = new SessionQueryError(
+      'provider accepts at most 10 items',
+      'SESSION_QUERY_INVALID_LIMIT',
+    )
+    const searchSessions = vi.fn((providerRequest: SessionSearchRequest) => {
+      const limit = providerRequest.limit
+      if (limit === undefined) throw new Error('Host search must request an explicit provider limit')
+      if (limit > 10) return Promise.reject(invalidLimit)
+      const offset = providerRequest.cursor === undefined
+        ? 0
+        : Number.parseInt(providerRequest.cursor.slice('offset-'.length), 10)
+      const end = Math.min(items.length, offset + limit)
+      return Promise.resolve({
+        items: items.slice(offset, end),
+        ...end < items.length ? { nextCursor: `offset-${end}` } : {},
+      })
+    })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('adaptive-page-limit'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: true,
+      value: { hasMore: true },
+    })
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value.items.map(item => item.sessionId))
+      .toEqual(items.slice(0, 20).map(item => item.header.id))
+    expect(searchSessions.mock.calls.map(([providerRequest]) => ({
+      limit: providerRequest.limit,
+      cursor: providerRequest.cursor,
+    }))).toEqual([
+      { limit: 20, cursor: undefined },
+      { limit: 10, cursor: undefined },
+      { limit: 10, cursor: 'offset-10' },
+      { limit: 10, cursor: 'offset-20' },
+    ])
+  })
+
+  it('counts a page-limit probe inside the 100-call budget', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const invalidLimit = new SessionQueryError(
+      'provider accepts at most 10 items',
+      'SESSION_QUERY_INVALID_LIMIT',
+    )
+    const searchSessions = vi.fn((providerRequest: SessionSearchRequest) => {
+      if (searchSessions.mock.calls.length === 1) {
+        expect(providerRequest).toMatchObject({ limit: 20 })
+        return Promise.reject(invalidLimit)
+      }
+      expect(providerRequest.limit).toBe(10)
+      return Promise.resolve({
+        items: [],
+        nextCursor: `page-${searchSessions.mock.calls.length}`,
+      })
+    })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('endless-pages'),
+      new AbortController().signal,
+    )
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error).toMatchObject({ code: 'internal' })
+    expect(response.result.error.message).toContain('100-call work budget')
+    expect(searchSessions).toHaveBeenCalledTimes(100)
+  })
+
+  it('restarts a stale continuation with its learned limit and original visibility snapshot', async () => {
+    const ctx = await baseContext()
+    const oldOnly = hit('old-only', 0)
+    const shared = hit('shared', 1)
+    const freshFirst = hit('fresh-first', 2)
+    const freshLast = hit('fresh-last', 3)
+    for (const item of [oldOnly, shared, freshFirst, freshLast]) {
+      ctx.sessions.create(item.header.id, { meta: item.header })
+    }
+    const late = hit('late-visible', 4)
+    const stale = new SessionQueryError(
+      'provider generation changed',
+      'SESSION_QUERY_STALE_CURSOR',
+    )
+    const invalidLimit = new SessionQueryError(
+      'provider accepts at most 10 items',
+      'SESSION_QUERY_INVALID_LIMIT',
+    )
+    const searchSessions = vi.fn((providerRequest: SessionSearchRequest) => {
+      switch (searchSessions.mock.calls.length) {
+        case 1:
+          expect(providerRequest).toMatchObject({ limit: 20 })
+          expect(providerRequest).not.toHaveProperty('cursor')
+          return Promise.reject(invalidLimit)
+        case 2:
+          expect(providerRequest).toMatchObject({ limit: 10 })
+          expect(providerRequest).not.toHaveProperty('cursor')
+          return Promise.resolve({
+            items: [oldOnly, shared],
+            nextCursor: 'old-cursor',
+          })
+        case 3:
+          expect(providerRequest).toMatchObject({ limit: 10 })
+          expect(providerRequest.cursor).toBe('old-cursor')
+          ctx.sessions.create(late.header.id, { meta: late.header })
+          return Promise.reject(stale)
+        case 4:
+          expect(providerRequest).toMatchObject({ limit: 10 })
+          expect(providerRequest).not.toHaveProperty('cursor')
+          return Promise.resolve({
+            items: [freshFirst, shared],
+            nextCursor: 'old-cursor',
+          })
+        case 5:
+          expect(providerRequest).toMatchObject({ limit: 10 })
+          expect(providerRequest.cursor).toBe('old-cursor')
+          return Promise.resolve({ items: [freshLast, late] })
+        default:
+          return Promise.reject(new Error('unexpected provider call'))
+      }
+    })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('stale-restart'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toEqual({
+      ok: true,
+      value: {
+        items: [
+          { sessionId: 'fresh-first', snippet: 'match 2' },
+          { sessionId: 'shared', snippet: 'match 1' },
+          { sessionId: 'fresh-last', snippet: 'match 3' },
+        ],
+        hasMore: false,
+      },
+    })
+    expect(searchSessions).toHaveBeenCalledTimes(5)
+  })
+
+  it('counts continuous stale restarts against the 100-call budget', async () => {
+    const ctx = await baseContext()
+    const partial = hit('partial')
+    ctx.sessions.create(partial.header.id, { meta: partial.header })
+    const stale = new SessionQueryError(
+      'provider generation changed',
+      'SESSION_QUERY_STALE_CURSOR',
+    )
+    const searchSessions = vi.fn((providerRequest: SessionSearchRequest) => {
+      if (searchSessions.mock.calls.length > 100) {
+        return Promise.reject(new Error('provider was called after the shared budget'))
+      }
+      if (providerRequest.cursor !== undefined) return Promise.reject(stale)
+      return Promise.resolve({
+        items: [partial],
+        nextCursor: `cursor-${searchSessions.mock.calls.length}`,
+      })
+    })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('stale-churn'),
+      new AbortController().signal,
+    )
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('internal')
+    expect(response.result.error.message).toContain('100-call work budget')
+    expect(response.result).not.toHaveProperty('value')
+    expect(searchSessions).toHaveBeenCalledTimes(100)
+  })
+
+  it('gives abort priority over a coincident stale continuation failure', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const controller = new AbortController()
+    const stale = new SessionQueryError(
+      'provider generation changed',
+      'SESSION_QUERY_STALE_CURSOR',
+    )
+    const searchSessions = vi.fn()
+      .mockResolvedValueOnce({ items: [], nextCursor: 'stale-cursor' })
+      .mockImplementationOnce(() => {
+        controller.abort()
+        return Promise.reject(stale)
+      })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('abort-stale'),
+      controller.signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'cancelled' },
+    })
+    expect(searchSessions).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not retry a stale first-page failure', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const searchSessions = vi.fn(() => Promise.reject(new SessionQueryError(
+      'provider generation changed before paging',
+      'SESSION_QUERY_STALE_CURSOR',
+    )))
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('first-page-stale'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'internal' },
+    })
+    expect(response.result).not.toHaveProperty('value')
+    expect(searchSessions).toHaveBeenCalledOnce()
+  })
+
+  it('does not adapt an invalid-limit continuation failure', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const searchSessions = vi.fn()
+      .mockResolvedValueOnce({ items: [], nextCursor: 'page-2' })
+      .mockRejectedValueOnce(new SessionQueryError(
+        'continuation limit is invalid',
+        'SESSION_QUERY_INVALID_LIMIT',
+      ))
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('continuation-invalid-limit'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'internal' },
+    })
+    expect(searchSessions).toHaveBeenCalledTimes(2)
+    expect(searchSessions.mock.calls.map(([providerRequest]) => (
+      providerRequest as SessionSearchRequest
+    ).limit))
+      .toEqual([20, 20])
+  })
+
+  it('stops page-limit adaptation at one item', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const searchSessions = vi.fn((providerRequest: SessionSearchRequest) => Promise.reject(
+      new SessionQueryError(
+        `provider rejects ${providerRequest.limit}`,
+        'SESSION_QUERY_INVALID_LIMIT',
+      ),
+    ))
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('minimum-page-limit'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'internal' },
+    })
+    expect(searchSessions.mock.calls.map(([providerRequest]) => providerRequest.limit))
+      .toEqual([20, 10, 5, 2, 1])
+  })
+
+  it('gives abort priority over a coincident invalid first-page limit', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const controller = new AbortController()
+    const searchSessions = vi.fn(() => {
+      controller.abort()
+      return Promise.reject(new SessionQueryError(
+        'provider rejects 20',
+        'SESSION_QUERY_INVALID_LIMIT',
+      ))
+    })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('abort-invalid-limit'),
+      controller.signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'cancelled' },
+    })
+    expect(searchSessions).toHaveBeenCalledOnce()
+  })
+
+  it('rejects an oversized provider page', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const oversized = Array.from({ length: 21 }, (_, index) => hit(`oversized-${index}`))
+    const searchSessions = vi.fn(() => Promise.resolve({ items: oversized }))
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('oversized-page'),
+      new AbortController().signal,
+    )
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error).toMatchObject({ code: 'internal' })
+    expect(response.result.error.message).toContain('returned 21 items; maximum is 20')
+  })
+
+  it('uses the learned provider limit for the overproduction guard', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const oversized = Array.from({ length: 11 }, (_, index) => hit(`oversized-${index}`))
+    const searchSessions = vi.fn((providerRequest: SessionSearchRequest) => {
+      if (providerRequest.limit === 20) {
+        return Promise.reject(new SessionQueryError(
+          'provider accepts at most 10 items',
+          'SESSION_QUERY_INVALID_LIMIT',
+        ))
+      }
+      return Promise.resolve({ items: oversized })
+    })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('adapted-oversized-page'),
+      new AbortController().signal,
+    )
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error).toMatchObject({ code: 'internal' })
+    expect(response.result.error.message).toContain('returned 11 items; maximum is 10')
+    expect(searchSessions).toHaveBeenCalledTimes(2)
+  })
+
+  it('bounds provider snippets to 240 Unicode code points without splitting astral text', async () => {
+    const ctx = await baseContext()
+    const visible = hit('visible')
+    ctx.sessions.create(visible.header.id, { meta: visible.header })
+    const expected = `${'x'.repeat(239)}😀`
+    const overlong = {
+      ...visible,
+      bestMatch: {
+        ...visible.bestMatch,
+        snippet: `${expected}${'y'.repeat(10_000)}`,
+      },
+    }
+    ctx.provide('sessionQuery', {
+      searchSessions: () => Promise.resolve({ items: [overlong] }),
+    } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('bounded-snippet'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toEqual({
+      ok: true,
+      value: {
+        items: [{ sessionId: 'visible', snippet: expected }],
+        hasMore: false,
+      },
+    })
+  })
+
+  it('fails closed when the provider repeats a continuation cursor', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const searchSessions = vi.fn()
+      .mockResolvedValueOnce({ items: [], nextCursor: 'repeated' })
+      .mockResolvedValueOnce({ items: [], nextCursor: 'repeated' })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('repeated-cursor'),
+      new AbortController().signal,
+    )
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error).toMatchObject({ code: 'internal' })
+    expect(response.result.error.message).toContain('repeated a continuation cursor')
+    expect(searchSessions).toHaveBeenCalledTimes(2)
+  })
+
+  it('validates a repeated cursor before accepting the authorized lookahead', async () => {
+    const ctx = await baseContext()
+    const items = Array.from({ length: 21 }, (_, index) => hit(`visible-${index}`, index))
+    for (const item of items) {
+      ctx.sessions.create(item.header.id, { meta: item.header })
+    }
+    const searchSessions = vi.fn()
+      .mockResolvedValueOnce({ items: items.slice(0, 20), nextCursor: 'repeated' })
+      .mockResolvedValueOnce({ items: items.slice(20), nextCursor: 'repeated' })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('repeated-lookahead-cursor'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'internal' },
+    })
+    expect(response.result).not.toHaveProperty('value')
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.message).toContain('repeated a continuation cursor')
+    expect(searchSessions).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not count duplicate session ids toward the result or lookahead boundary', async () => {
+    const ctx = await baseContext()
+    const items = Array.from({ length: 21 }, (_, index) => hit(`visible-${index}`, index))
+    for (const item of items) {
+      ctx.sessions.create(item.header.id, { meta: item.header })
+    }
+    const searchSessions = vi.fn()
+      .mockResolvedValueOnce({ items: items.slice(0, 20), nextCursor: 'page-2' })
+      .mockResolvedValueOnce({ items: items.slice(0, 20), nextCursor: 'page-3' })
+      .mockResolvedValueOnce({ items: items.slice(20) })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('duplicate-pages'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: true,
+      value: { hasMore: true },
+    })
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value.items.map(item => item.sessionId)).toEqual(
+      items.slice(0, 20).map(item => item.header.id),
+    )
+    expect(searchSessions).toHaveBeenCalledTimes(3)
+  })
+
+  it('cancels on a continuation page and passes the carrier signal to both calls', async () => {
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const controller = new AbortController()
+    const searchSessions = vi.fn()
+      .mockResolvedValueOnce({ items: [], nextCursor: 'page-2' })
+      .mockImplementationOnce(() => {
+        controller.abort()
+        return Promise.resolve({ items: [] })
+      })
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('cancel-continuation'),
+      controller.signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'cancelled' },
+    })
+    expect(searchSessions).toHaveBeenCalledTimes(2)
+    for (const call of searchSessions.mock.calls) {
+      expect(call[1]).toEqual({ signal: controller.signal })
+    }
+  })
+
+  it('keeps visibility sets above SQLite variable limits out of provider bindings', async () => {
+    const ctx = await baseContext()
+    const cold = Array.from(
+      { length: 32_751 },
+      (_, index) => header(`cold-${index}`, `/cold-${index}`),
+    )
+    ctx.provide('sessionPersistence', {
+      list: () => Promise.resolve(cold),
+      locate: () => undefined,
+    } as never)
+    const searchSessions = vi.fn((_request: SessionSearchRequest) => Promise.resolve({
+      items: [hit('cold-32750')],
+    }))
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('large corpus'),
+      new AbortController().signal,
+    )
+
+    expect(response.result).toEqual({
+      ok: true,
+      value: {
+        items: [{ sessionId: 'cold-32750', snippet: 'match 0' }],
+        hasMore: false,
+      },
+    })
+    expect(searchSessions).toHaveBeenCalledOnce()
+    expect(searchSessions.mock.calls[0]?.[0]).not.toHaveProperty('sessionFilters')
+  })
+
+  it('propagates cancellation through visible-session collection and stops cold-summary work', async () => {
+    const ctx = await baseContext()
+    const controller = new AbortController()
+    const cold = Array.from({ length: 32 }, (_, index) => header(`cold-${index}`, `/cold-${index}`))
+    const list = vi.fn((signal?: AbortSignal) => {
+      expect(signal).toBe(controller.signal)
+      return Promise.resolve(cold)
+    })
+    let locateCalls = 0
+    ctx.provide('sessionPersistence', {
+      list,
+      locate: () => {
+        locateCalls++
+        controller.abort()
+        return undefined
+      },
+    } as never)
+    const searchSessions = vi.fn()
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    const response = await createApiProxy(ctx, defaults).sessions.search(
+      request('cancel-during-visibility'),
+      controller.signal,
+    )
+
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'cancelled' },
+    })
+    expect(list).toHaveBeenCalledOnce()
+    expect(locateCalls).toBe(1)
+    expect(searchSessions).not.toHaveBeenCalled()
+  })
+
+  it('awaits every started cold-summary stat before returning cancellation', async () => {
+    const ctx = await baseContext()
+    const controller = new AbortController()
+    const cold = Array.from({ length: 16 }, (_, index) => header(`cold-${index}`, `/cold-${index}`))
+    const statGates = cold.map(() => Promise.withResolvers<{ mtimeMs: number }>())
+    const statMock = vi.mocked(stat)
+    statMock.mockClear()
+    for (const gate of statGates) {
+      statMock.mockImplementationOnce((() => gate.promise) as never)
+    }
+    ctx.provide('sessionPersistence', {
+      list: () => Promise.resolve(cold),
+      locate: (meta: SessionHeader) => ({ kind: 'jsonl', path: `/logs/${meta.id}.jsonl` }),
+    } as never)
+    const searchSessions = vi.fn()
+    ctx.provide('sessionQuery', { searchSessions } as never)
+
+    let settled = false
+    const responsePromise = createApiProxy(ctx, defaults).sessions.search(
+      request('cancel-during-cold-stats'),
+      controller.signal,
+    ).finally(() => {
+      settled = true
+    })
+    await vi.waitFor(() => {
+      expect(statMock).toHaveBeenCalledTimes(16)
+    })
+
+    controller.abort()
+    statGates[0]!.resolve({ mtimeMs: 101 })
+    await new Promise<void>(resolve => setImmediate(resolve))
+    expect(settled).toBe(false)
+
+    for (const gate of statGates.slice(1)) gate.resolve({ mtimeMs: 102 })
+    const response = await responsePromise
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'cancelled' },
+    })
+    expect(searchSessions).not.toHaveBeenCalled()
+  })
+
+  it('maps missing composition, query cancellation, and provider failure', async () => {
+    const missingCtx = await baseContext()
+    missingCtx.sessions.create(sid('visible'), { meta: header('visible') })
+    const missingApi = createApiProxy(missingCtx, defaults)
+    const preAborted = new AbortController()
+    preAborted.abort()
+    const cancelledBeforeLookup = await missingApi.sessions.search(
+      request('cancel-before-lookup'),
+      preAborted.signal,
+    )
+    expect(cancelledBeforeLookup.result).toMatchObject({
+      ok: false,
+      error: { code: 'cancelled' },
+    })
+
+    const missing = await missingApi.sessions.search(
+      request('needle'),
+      new AbortController().signal,
+    )
+    expect(missing.result.ok).toBe(false)
+    if (missing.result.ok) throw new Error('unreachable')
+    expect(missing.result.error.code).toBe('internal')
+    expect(missing.result.error.message).toContain('does not mount')
+
+    const ctx = await baseContext()
+    ctx.sessions.create(sid('visible'), { meta: header('visible') })
+    const aborted = new SessionQueryError('provider stopped', 'SESSION_QUERY_ABORTED')
+    const searchSessions = vi.fn()
+      .mockRejectedValueOnce(aborted)
+      .mockRejectedValueOnce(new Error('database unavailable'))
+    ctx.provide('sessionQuery', { searchSessions } as never)
+    const api = createApiProxy(ctx, defaults)
+
+    const cancelled = await api.sessions.search(
+      request('first'),
+      new AbortController().signal,
+    )
+    expect(cancelled.result).toMatchObject({
+      ok: false,
+      error: { code: 'cancelled' },
+    })
+
+    const failed = await api.sessions.search(
+      request('second'),
+      new AbortController().signal,
+    )
+    expect(failed.result.ok).toBe(false)
+    if (failed.result.ok) throw new Error('unreachable')
+    expect(failed.result.error.code).toBe('internal')
+    expect(failed.result.error.message).toContain('database unavailable')
+  })
+})

packages/host/apiproxy/tests/api-proxy-view.spec.ts

@@ -14,9 +14,9 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import { CallId, createMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import { CallId } from '@deepseek-ai/dsh-llm'
-import type { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type { MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
@@ -35,6 +35,35 @@ function tool(name: string, presenters: Pick<ToolDefinition, 'presentCall' | 'pr
   })
 }
 
+/** Append a production-shaped human prompt to the session surface. */
+function appendUserText(session: Session, text: string): SessionEvent {
+  return session.append('user/message', createUserMessage({
+    content: [{ type: 'text', text }], source: { kind: 'user' },
+  }), { surfaceOp: 'append' })
+}
+
+/** Append a production-shaped assistant message to the session surface. */
+function appendAssistantText(session: Session, text: string, step: number): SessionEvent {
+  return session.append('assistant/message', {
+    turn: 1,
+    step,
+    message: createMessage({
+      role: 'assistant',
+      content: [{ type: 'text', text }],
+      source: { kind: 'model', provider: 'p', model: 'm' },
+    }),
+  }, { surfaceOp: 'append' })
+}
+
+/**
+ * Append a plugin-owned log-only event. The host proxy is projection-only, so it
+ * declares no compaction vocabulary; the cast writes the real event shape without
+ * depending on the owning package.
+ */
+function appendExtension(session: Session, type: string, data: unknown): SessionEvent {
+  return (session.append as unknown as (type: string, data: unknown) => SessionEvent)(type, data)
+}
+
 async function harness(): Promise<{ ctx: Context }> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
@@ -88,16 +117,35 @@ describe('mux live view computation', () => {
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-term'), name: 'term', arguments: '{"cmd":"echo hi"}' })
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-diff'), name: 'diffy', arguments: '{}' })
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-call-only'), name: 'call-only', arguments: '{}' })
-    session.append('tool/result', { turn: 1, step: 1, callId: CallId('c-call-only'), content: [{ type: 'text', text: rawResult }], isError: false }, { surfaceOp: 'append' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        callId: CallId('c-call-only'),
+        content: [{ type: 'text', text: rawResult }],
+        isError: false,
+      }),
+    }, { surfaceOp: 'append' })
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-plain'), name: 'plain', arguments: '{}' })
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-boom'), name: 'boom', arguments: '{}' })
-    session.append('tool/result', { turn: 1, step: 1, callId: CallId('c-gen'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        callId: CallId('c-gen'),
+        content: [{ type: 'text', text: 'ok' }],
+        isError: false,
+      }),
+    }, { surfaceOp: 'append' })
 
     const frames = await collected
     const events = frames.filter(f => f.type === 'session/event')
     const byCall = new Map(events
       .filter(f => f.event.type === 'tool/call' || f.event.type === 'tool/result')
-      .map(f => [`${f.event.type}:${(f.event.data as { callId: string }).callId}`, f]))
+      .map(f => [
+        `${f.event.type}:${f.event.type === 'tool/call'
+          ? f.event.data.callId
+          : (f.event.data as SessionEvent<'tool/result'>['data']).message.source.callId}`,
+        f,
+      ]))
 
     expect(byCall.get('tool/call:c-gen')?.view).toEqual({ for: 'call', view: { card: 'generic', title: 'gen call' } })
     expect(byCall.get('tool/call:c-term')?.view).toEqual({ for: 'call', view: { card: 'terminal', title: 'echo hi' } })
@@ -130,15 +178,44 @@ describe('mux live view computation', () => {
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('h-term'), name: 'term', arguments: '{"cmd":"ls"}' })
     // meta rides through to presentResult's ToolResult (the spread arm).
-    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-term'), content: [{ type: 'text', text: 'ok' }], isError: false, meta: { n: 1 } }, { surfaceOp: 'append' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        callId: CallId('h-term'),
+        content: [{ type: 'text', text: 'ok' }],
+        isError: false,
+      }),
+      meta: { n: 1 },
+    }, { surfaceOp: 'append' })
     // Unpaired result: no tool/call with this id anywhere in the page.
-    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-orphan'), content: [{ type: 'text', text: 'x' }], isError: false }, { surfaceOp: 'append' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        callId: CallId('h-orphan'),
+        content: [{ type: 'text', text: 'x' }],
+        isError: false,
+      }),
+    }, { surfaceOp: 'append' })
     // Paired, but the call's stored arguments do not parse: backscan soft-falls.
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('h-bad'), name: 'term', arguments: '{broken' })
-    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-bad'), content: [{ type: 'text', text: 'y' }], isError: false }, { surfaceOp: 'append' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        callId: CallId('h-bad'),
+        content: [{ type: 'text', text: 'y' }],
+        isError: false,
+      }),
+    }, { surfaceOp: 'append' })
     // Presenterless tool: pairing succeeds but presentResult is absent.
     session.append('tool/call', { turn: 1, step: 1, callId: CallId('h-plain'), name: 'plain', arguments: '{}' })
-    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-plain'), content: [{ type: 'text', text: 'z' }], isError: false }, { surfaceOp: 'append' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        callId: CallId('h-plain'),
+        content: [{ type: 'text', text: 'z' }],
+        isError: false,
+      }),
+    }, { surfaceOp: 'append' })
 
     const response = await api.sessions.history({ rpcId: RpcId('t-hist'), payload: { sessionId: session.id } })
     expect(response.result.ok).toBe(true)
@@ -146,7 +223,12 @@ describe('mux live view computation', () => {
     const entries = response.result.value.events
     const byKey = new Map(entries
       .filter(entry => entry.event.type === 'tool/call' || entry.event.type === 'tool/result')
-      .map(entry => [`${entry.event.type}:${(entry.event.data as { callId: string }).callId}`, entry]))
+      .map(entry => [
+        `${entry.event.type}:${entry.event.type === 'tool/call'
+          ? entry.event.data.callId
+          : (entry.event.data as SessionEvent<'tool/result'>['data']).message.source.callId}`,
+        entry,
+      ]))
     expect(byKey.get('tool/call:h-term')?.view).toEqual({ for: 'call', view: { card: 'terminal', title: 'ls' } })
     expect(byKey.get('tool/result:h-term')?.view).toEqual({ for: 'result', view: { card: 'terminal', output: 'done' } })
     expect('view' in (byKey.get('tool/result:h-orphan') ?? {})).toBe(false)
@@ -154,37 +236,53 @@ describe('mux live view computation', () => {
     expect('view' in (byKey.get('tool/result:h-plain') ?? {})).toBe(false)
   })
 
-  it('tail page carries the full-log todo projection; older pages and todo-less sessions omit it', async () => {
+  it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => {
     const { ctx } = await harness()
     const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
     const session = ctx.sessions.create()
     ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
-    // Superseded write early in the log, latest write later; enough messages to page.
-    session.append('todo/write', { todos: [{ content: 'old', status: 'pending' }] })
-    for (let turn = 0; turn < 6; turn++) {
-      session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
-      session.append('user/message', { content: [{ type: 'text', text: `q${turn}` }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-      session.append('assistant/message', { turn, step: 0, content: [{ type: 'text', text: `a${turn}` }], provenance: { provider: 'p', model: 'm' } }, { surfaceOp: 'append' })
-      session.append('turn/end', { turn, reason: { kind: 'completed' } })
-    }
-    session.append('todo/write', { todos: [{ content: 'current', status: 'in_progress' }] })
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const first = appendUserText(session, 'first prompt')
+    appendAssistantText(session, 'first reply', 1)
+    const third = appendUserText(session, 'second prompt')
+    appendAssistantText(session, 'second reply', 2)
+    const shadowed = [...session.surface.nodes]
+    // A compaction transaction: log-only provenance immediately followed by the
+    // replacement that shadows the range.
+    const summary = appendExtension(session, 'compact/summary', {
+      summary: [{ type: 'text', text: 'summary' }],
+      shadowedRange: { start: shadowed[0], end: shadowed.at(-1) },
+      shadowedSeqs: shadowed,
+      shadowedTokenCount: 0,
+      provider: 'p',
+      model: 'm',
+    })
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: '<context_checkpoint>summary</context_checkpoint>' }],
+      source: { kind: 'plugin', plugin: 'compact' },
+    }), {
+      surfaceOp: { op: 'replace', start: shadowed[0] as number, end: shadowed.at(-1) as number },
+      sourceEventSeqs: [...shadowed, summary.seq],
+    })
 
-    // Tail page limited to 2 messages: the latest todo/write may or may not sit
-    // in the window — the projection must come from the FULL log either way.
-    const tail = await api.sessions.history({ rpcId: RpcId('t-todos'), payload: { sessionId: session.id, maxMessages: 2 } })
-    if (!tail.result.ok) throw new Error('history failed')
-    expect(tail.result.value.todos).toEqual([{ content: 'current', status: 'in_progress' }])
-    // An older page omits the projection (session-level, tail-page-only).
-    const boundary = tail.result.value.events[0]?.event.seq ?? 0
-    const older = await api.sessions.history({ rpcId: RpcId('t-todos-2'), payload: { sessionId: session.id, beforeSeq: boundary, maxMessages: 2 } })
-    if (!older.result.ok) throw new Error('older failed')
-    expect('todos' in older.result.value).toBe(false)
-    // A session with no todo/write anywhere omits the field.
-    const bare = ctx.sessions.create()
-    ctx.agents.register({ id: bare.id, session: bare, status: 'idle', ctx } as Agent)
-    const bareTail = await api.sessions.history({ rpcId: RpcId('t-todos-3'), payload: { sessionId: bare.id } })
-    if (!bareTail.result.ok) throw new Error('bare failed')
-    expect('todos' in bareTail.result.value).toBe(false)
+    const response = await api.sessions.history({
+      rpcId: RpcId('t-hist-compact'),
+      payload: { sessionId: session.id, maxMessages: 2 },
+    })
+    if (!response.result.ok) throw new Error('unreachable')
+    const page = response.result.value.events.map(entry => entry.event)
+    // Two append-origin messages fill the page even though a replacement copy of
+    // the same event type sits in the window: the copy is model-only.
+    const messages = page.filter(event => event.type === 'user/message' || event.type === 'assistant/message')
+    expect(messages.map(event => event.seq)).toEqual([third.seq, third.seq + 1, third.seq + 3])
+    expect(page.some(event => event.seq === first.seq)).toBe(false)
+    expect(response.result.value.hasMore).toBe(true)
+    // The range stays contiguous, so the checkpoint's provenance is readable on
+    // the same page as the checkpoint itself.
+    const summaryIndex = page.findIndex(event => event.seq === summary.seq)
+    expect(summaryIndex).toBeGreaterThan(-1)
+    expect(page[summaryIndex + 1]?.seq).toBe(summary.seq + 1)
+    expect(page.map(event => event.seq)).toEqual(page.map((_event, index) => third.seq + index))
   })
 
   it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => {
@@ -221,7 +319,14 @@ describe('mux live view computation', () => {
     session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
     // The turn/end above cleared the live table; pairing must fall back to
     // scanning the session's in-memory events.
-    session.append('tool/result', { turn: 1, step: 1, callId: CallId('c-late'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        callId: CallId('c-late'),
+        content: [{ type: 'text', text: 'ok' }],
+        isError: false,
+      }),
+    }, { surfaceOp: 'append' })
 
     const frames = await collected
     const result = frames.find(f => f.type === 'session/event' && f.event.type === 'tool/result')

packages/host/apiproxy/tests/api-proxy-workspace.spec.ts

@@ -3,13 +3,15 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import AgentRegistry, { AgentMessageId } from '@deepseek-ai/dsh-agent'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentFactory } from '@deepseek-ai/dsh-agent'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import type { Session } from '@deepseek-ai/dsh-session'
 import Storage from '@deepseek-ai/dsh-storage'
 import { DomainFacility } from '@deepseek-ai/dsh-storage-domain'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import { DirectoryPickerError } from '@deepseek-ai/dsh-host-directory-picker'
+import type { DirectoryPickerCapability } from '@deepseek-ai/dsh-host-directory-picker'
 import WorkspaceRegistry from '@deepseek-ai/dsh-workspace'
 import type { HostFrame, WorkspaceId } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
@@ -45,10 +47,12 @@ function stubAgent(session: Session): Agent {
     status: 'idle',
     acceptsNextStep: false,
     ctx: new Context(),
-    followup: () => AgentMessageId('stub'),
-    steer: () => AgentMessageId('stub'),
-    inject: () => AgentMessageId('stub'),
-    send: () => AgentMessageId('stub'),
+    followup: () => {},
+    steer: () => {},
+    inject: () => {},
+    send: () => {},
+    updateInbox: () => 'not-found',
+    reserveTurnAdmission: () => undefined,
     cancel() {},
     whenIdle: () => Promise.resolve(),
   }
@@ -57,7 +61,8 @@ function stubAgent(session: Session): Agent {
 /** Compose the API over real Session, Agent, Storage, Domain, and Workspace services. */
 async function harness(
   workspaceRoot = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-apiproxy-workspace-'))),
-  pickDirectory?: (signal: AbortSignal) => Promise<string | null>,
+  picker: DirectoryPickerCapability = { kind: 'native', pick: async () => null },
+  extras: { openPath?: (path: string, signal: AbortSignal) => Promise<void> } = {},
 ) {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
@@ -92,36 +97,151 @@ async function harness(
     },
   }
   ctx.agents.setFactory(factory)
+  // Structural picker fake: the gateway only reads capability(); a stable
+  // object per harness mirrors the seam's stability contract.
+  ctx.provide('directoryPicker', { capability: () => picker } as never)
   const api = createApiProxy(ctx, {
     provider: 'test',
     model: 'test-model',
     cwd: workspaceRoot,
     workspaceRoot,
-    ...pickDirectory === undefined ? {} : { pickDirectory },
+    ...extras.openPath === undefined ? {} : { openPath: extras.openPath },
   })
   return { api, ctx, storageDomain, workspaceRoot }
 }
 
 describe('host.pickDirectory', () => {
-  it('returns a selected path or explicit cancellation from the injected native boundary', async () => {
-    const selected = await harness(undefined, async () => '/tmp/project')
+  it('returns a selected path or explicit cancellation from the native capability', async () => {
+    const selected = await harness(undefined, { kind: 'native', pick: async () => '/tmp/project' })
     expect((await selected.api.host.pickDirectory(request({}), new AbortController().signal)).result)
       .toEqual({ ok: true, value: { path: '/tmp/project' } })
 
-    const cancelled = await harness(undefined, async () => null)
+    const cancelled = await harness(undefined, { kind: 'native', pick: async () => null })
     expect((await cancelled.api.host.pickDirectory(request({}), new AbortController().signal)).result)
       .toEqual({ ok: true, value: { path: null } })
   })
 
-  it('propagates abort into the native boundary as a cancelled RPC error', async () => {
-    const { api } = await harness(undefined, signal => new Promise((_resolve, reject) => {
-      signal.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
-    }))
+  it('propagates abort into the native capability as a cancelled RPC error', async () => {
+    const { api } = await harness(undefined, {
+      kind: 'native',
+      pick: signal => new Promise((_resolve, reject) => {
+        signal.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
+      }),
+    })
     const abort = new AbortController()
     const pending = api.host.pickDirectory(request({}), abort.signal)
     abort.abort()
     expect((await pending).result).toMatchObject({ ok: false, error: { code: 'cancelled' } })
   })
+
+  it('folds a non-abort native-chooser failure into an internal error', async () => {
+    const { api } = await harness(undefined, { kind: 'native', pick: async () => { throw new Error('no chooser installed') } })
+    const response = await api.host.pickDirectory(request({}), new AbortController().signal)
+    expect(response.result).toMatchObject({ ok: false, error: { code: 'internal' } })
+  })
+
+  it('refuses the native RPC under a browse composition', async () => {
+    const { api } = await harness(undefined, BROWSE_STUB)
+    const response = await api.host.pickDirectory(request({}), new AbortController().signal)
+    expect(response.result).toMatchObject({
+      ok: false,
+      error: { code: 'directory-picker-unavailable', details: { capability: 'browse' } },
+    })
+  })
+})
+
+/** Canned browse capability: one listing, one created path, typed failures on demand. */
+const BROWSE_STUB: DirectoryPickerCapability = {
+  kind: 'browse',
+  list: async (path) => {
+    if (path === '/denied') throw new DirectoryPickerError('directory-unreadable', '/denied', 'cannot list /denied')
+    const target = path ?? '/home/user'
+    return {
+      path: target,
+      home: '/home/user',
+      crumbs: [{ name: '/', path: '/', hidden: false }],
+      entries: [{ name: 'projects', path: `${target}/projects`, hidden: false }],
+      truncated: false,
+    }
+  },
+  createDirectory: async (path, name) => {
+    if (name === 'taken') throw new DirectoryPickerError('directory-exists', `${path}/${name}`, 'already exists')
+    if (name === 'unwritable') throw new Error('disk detached')
+    return `${path}/${name}`
+  },
+}
+
+describe('host.listDirectory / host.createDirectory', () => {
+  it('serves listings and creation through the browse capability, defaulting to home', async () => {
+    const { api } = await harness(undefined, BROWSE_STUB)
+    const home = await api.host.listDirectory(request({}), new AbortController().signal)
+    expect(home.result).toMatchObject({ ok: true, value: { path: '/home/user', home: '/home/user' } })
+    const listed = await api.host.listDirectory(request({ path: '/home/user/projects' }), new AbortController().signal)
+    expect(listed.result).toMatchObject({ ok: true, value: { path: '/home/user/projects' } })
+    const created = await api.host.createDirectory(request({ path: '/home/user', name: 'fresh' }))
+    expect(created.result).toEqual({ ok: true, value: { path: '/home/user/fresh' } })
+  })
+
+  it('maps typed picker failures onto the wire error codes and folds unknown throws to internal', async () => {
+    const { api } = await harness(undefined, BROWSE_STUB)
+    expect((await api.host.listDirectory(request({ path: '/denied' }), new AbortController().signal)).result).toMatchObject({
+      ok: false, error: { code: 'directory-unreadable', details: { path: '/denied' } },
+    })
+    expect((await api.host.createDirectory(request({ path: '/home/user', name: 'taken' }))).result).toMatchObject({
+      ok: false, error: { code: 'directory-exists' },
+    })
+    expect((await api.host.createDirectory(request({ path: '/home/user', name: 'unwritable' }))).result).toMatchObject({
+      ok: false, error: { code: 'internal' },
+    })
+  })
+
+  it('reports an aborted listing as cancelled, like the other signal-following RPCs', async () => {
+    const { api } = await harness(undefined, {
+      kind: 'browse',
+      list: (_path, signal) => new Promise((_resolve, reject) => {
+        signal?.addEventListener('abort', () => { reject(new Error('scan aborted')) }, { once: true })
+      }),
+      createDirectory: async () => '/never',
+    })
+    const abort = new AbortController()
+    const pending = api.host.listDirectory(request({}), abort.signal)
+    abort.abort()
+    expect((await pending).result).toMatchObject({ ok: false, error: { code: 'cancelled' } })
+  })
+
+  it('refuses the browse RPCs under a native composition', async () => {
+    const { api } = await harness()
+    expect((await api.host.listDirectory(request({}), new AbortController().signal)).result).toMatchObject({
+      ok: false, error: { code: 'directory-picker-unavailable', details: { capability: 'native' } },
+    })
+    expect((await api.host.createDirectory(request({ path: '/x', name: 'y' }))).result).toMatchObject({
+      ok: false, error: { code: 'directory-picker-unavailable', details: { capability: 'native' } },
+    })
+  })
+})
+
+describe('host.openPath', () => {
+  it('opens through the injected native boundary', async () => {
+    const opened: string[] = []
+    const { api } = await harness(undefined, undefined, {
+      openPath: async (path) => { opened.push(path) },
+    })
+    expect((await api.host.openPath(request({ path: '/tmp/a.txt' }), new AbortController().signal)).result)
+      .toEqual({ ok: true, value: { opened: true } })
+    expect(opened).toEqual(['/tmp/a.txt'])
+  })
+
+  it('propagates abort into the native boundary as a cancelled RPC error', async () => {
+    const { api } = await harness(undefined, undefined, {
+      openPath: (_path, signal) => new Promise((_resolve, reject) => {
+        signal.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
+      }),
+    })
+    const abort = new AbortController()
+    const pending = api.host.openPath(request({ path: '/tmp/a.txt' }), abort.signal)
+    abort.abort()
+    expect((await pending).result).toMatchObject({ ok: false, error: { code: 'cancelled' } })
+  })
 })
 
 describe('workspace.create', () => {
@@ -173,18 +293,25 @@ describe('workspace.create', () => {
     }
   })
 
-  it('rejects different paths that derive the same Workspace title', async () => {
+  it('adopts different paths that derive the same Workspace title', async () => {
     const { api, workspaceRoot } = await harness()
     const first = join(workspaceRoot, 'one', 'project')
     const second = join(workspaceRoot, 'two', 'project')
     mkdirSync(first, { recursive: true })
     mkdirSync(second, { recursive: true })
-    expectOk(await api.workspace.create(request({ path: first })))
-    const conflict = await api.workspace.create(request({ path: second }))
-    expect(conflict.result).toMatchObject({
-      ok: false,
-      error: { code: 'workspace-name-conflict', details: { name: 'project' } },
+    const firstResult = expectOk(await api.workspace.create(request({ path: first })))
+    const secondResult = expectOk(await api.workspace.create(request({ path: second })))
+    expect(firstResult).toMatchObject({
+      created: true,
+      workspace: { path: first, title: 'project' },
     })
+    expect(secondResult).toMatchObject({
+      created: true,
+      workspace: { path: second, title: 'project' },
+    })
+    expect(secondResult.workspace.workspaceId).not.toBe(firstResult.workspace.workspaceId)
+    expect(expectOk(await api.workspace.list(request({}))).items.map(workspace => workspace.path))
+      .toEqual([second, first])
   })
 })
 
@@ -322,4 +449,44 @@ describe('Host Workspace increments', () => {
     expect(expectOk(await api.sessions.list(request({}))).items.map(item => item.sessionId)).toContain(sessionId)
     abort.abort()
   })
+
+  it('archives a session into the global set, keeps its accounting, and streams the set once', async () => {
+    const { api } = await harness()
+    const workspace = expectOk(await api.workspace.create(request({ name: 'archive-home' }))).workspace
+    const sessionId = SessionId('session-to-archive')
+    expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId })))
+    expect(expectOk(await api.workspace.list(request({}))).archivedSessionIds).toEqual([])
+
+    const abort = new AbortController()
+    const stream: AsyncIterator<RpcRequest<HostFrame>> =
+      api.events.host(request({}), abort.signal)[Symbol.asyncIterator]()
+    const changed = nextHostFrame(stream)
+    expect(expectOk(await api.workspace.archiveSession(request({ sessionId }))).archivedSessionIds)
+      .toEqual([sessionId])
+    expect(await changed).toMatchObject({
+      payload: { type: 'host/archived-sessions-changed', archivedSessionIds: [sessionId] },
+    })
+
+    // Accounting and the session itself are untouched; list re-baselines the set.
+    const listed = expectOk(await api.workspace.list(request({})))
+    expect(listed.archivedSessionIds).toEqual([sessionId])
+    expect(listed.items[0]?.sessionIds).toEqual([sessionId])
+    expect(expectOk(await api.sessions.list(request({}))).items.map(item => item.sessionId)).toContain(sessionId)
+
+    // The idempotent repeat emits no second frame: the next observed frame is
+    // the workspace-changed of a later attach, not another archive snapshot.
+    const after = nextHostFrame(stream)
+    expect(expectOk(await api.workspace.archiveSession(request({ sessionId }))).archivedSessionIds)
+      .toEqual([sessionId])
+    const otherSession = SessionId('session-after-archive')
+    expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId: otherSession })))
+    expect((await after).payload.type).not.toBe('host/archived-sessions-changed')
+
+    const missing = await api.workspace.archiveSession(request({ sessionId: SessionId('session-ghost') }))
+    expect(missing.result).toMatchObject({
+      ok: false,
+      error: { code: 'session-not-found', details: { sessionId: 'session-ghost' } },
+    })
+    abort.abort()
+  })
 })

packages/host/apiproxy/tests/client-handler.spec.ts

@@ -7,7 +7,7 @@
 
 import { describe, expect, it, vi } from 'vitest'
 import type { SessionId } from '@deepseek-ai/dsh-session'
-import type { ApiProxy, HostFrame, MuxFrame, RpcMessage, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy'
+import type { ApiProxy, GoalRef, HostFrame, MuxFrame, RpcMessage, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy'
 import { InProcessApiClient, RpcId, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
 
 const sid = (id: string): SessionId => id as SessionId
@@ -23,41 +23,55 @@ function scriptedApi(overrides: {
   commands?: Partial<ApiProxy['commands']>
   skills?: Partial<ApiProxy['skills']>
   events?: Partial<ApiProxy['events']>
+  goals?: Partial<ApiProxy['goals']>
+  settings?: Partial<ApiProxy['settings']>
+  credentials?: Partial<ApiProxy['credentials']>
+  llm?: Partial<ApiProxy['llm']>
   respond?: ApiProxy['respond']
 } = {}): ApiProxy {
   async function *empty<F>(): AsyncGenerator<RpcRequest<F>> { /* no frames */ }
+  const err = <T>(r: RpcRequest<unknown>): Promise<RpcResponse<T>> =>
+    Promise.resolve({ rpcId: r.rpcId, result: { ok: false, error: { code: 'internal' as const, message: 'stub', details: {} } } })
   return {
     sessions: {
       list: r => ok(r, { items: [] }),
+      search: r => ok(r, { items: [], hasMore: false }),
       create: r => ok(r, { sessionId: sid('s-new') }),
       history: r => ok(r, {
         events: [],
         hasMore: false,
-        modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+        modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
       }),
       models: r => ok(r, {
-        current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+        current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
         groups: [],
         failures: [],
       }),
       selectModel: r => ok(r, {
         selected: { provider: r.payload.provider, model: r.payload.model },
       }),
+      rename: r => ok(r, { title: 'renamed', seq: 0 }),
+      fork: r => ok(r, { sessionId: sid('s-fork') }),
       prompt: r => ok(r, { accepted: true as const }),
+      updateQueue: r => ok(r, { accepted: true as const }),
       cancel: r => ok(r, { accepted: true as const }),
       ...overrides.sessions,
     },
     host: {
       describe: r => ok(r, { version: '0-test', cwd: '/t', attachedSessions: 0 }),
       pickDirectory: r => ok(r, { path: null }),
+      listDirectory: r => ok(r, { path: '/t', home: '/t', crumbs: [], entries: [], truncated: false }),
+      createDirectory: r => ok(r, { path: '/t/new' }),
+      openPath: r => ok(r, { opened: true as const }),
       ...overrides.host,
     },
     workspace: {
-      list: r => ok(r, { items: [] }),
+      list: r => ok(r, { items: [], archivedSessionIds: [] }),
       create: r => ok(r, { workspace: { workspaceId: 'w1' as never, path: '/t', title: 't', sessionIds: [], createdAt: '0', updatedAt: '0' }, created: true }),
       rename: r => ok(r, { workspace: { workspaceId: 'w1' as never, path: '/t', title: 't', sessionIds: [], createdAt: '0', updatedAt: '0' } }),
       delete: r => ok(r, { deleted: true as const }),
       insertSessionBefore: r => ok(r, { workspace: { workspaceId: 'w1' as never, path: '/t', title: 't', sessionIds: [], createdAt: '0', updatedAt: '0' } }),
+      archiveSession: r => ok(r, { archivedSessionIds: [r.payload.sessionId] }),
     },
     commands: {
       list: r => ok(r, { commands: [] }),
@@ -65,6 +79,33 @@ function scriptedApi(overrides: {
       ...overrides.commands,
     },
     skills: { list: r => ok(r, { skills: [] }), ...overrides.skills },
+    goals: {
+      create: err,
+      edit: err,
+      pause: err,
+      resume: err,
+      complete: err,
+      clear: err,
+      ...overrides.goals,
+    },
+    settings: {
+      describe: r => ok(r, { writable: true, namespaces: [] }),
+      update: err,
+      replace: err,
+      mutate: err,
+      ...overrides.settings,
+    },
+    credentials: {
+      describe: r => ok(r, { credentials: {} }),
+      set: err,
+      unset: err,
+      ...overrides.credentials,
+    },
+    llm: {
+      providers: r => ok(r, { providers: [] }),
+      models: r => ok(r, { groups: [], failures: [] }),
+      ...overrides.llm,
+    },
     events: { mux: () => empty<MuxFrame>(), host: () => empty<HostFrame>(), ...overrides.events },
     respond: overrides.respond ?? (() => Promise.resolve({ accepted: false as const, reason: 'not-pending' as const })),
   }
@@ -74,6 +115,15 @@ function client(api: ApiProxy, timeoutMs?: number): InProcessApiClient {
   return new InProcessApiClient(toFetchHandler(api), timeoutMs)
 }
 
+/** Wrap one scripted method to record its invocation into `seen` before responding. */
+function recorderInto(seen: { method: string; payload: unknown }[]) {
+  return <P, V>(method: string, respond: (r: RpcRequest<P>) => Promise<RpcResponse<V>>) =>
+    (r: RpcRequest<P>): Promise<RpcResponse<V>> => {
+      seen.push({ method, payload: r.payload })
+      return respond(r)
+    }
+}
+
 describe('unary round trip', () => {
   it('carries payload out and value back through the full wire form', async () => {
     let seen: RpcRequest<{ cursor?: string }> | undefined
@@ -93,6 +143,59 @@ describe('unary round trip', () => {
     expect(response.result).toEqual({ ok: true, value: { items: [{ sessionId: 's1', updatedAt: 7, running: false, blank: false }] } })
   })
 
+  it('round-trips a trimmed session search query and its bounded result metadata', async () => {
+    let seen: RpcRequest<{ query: string }> | undefined
+    const api = scriptedApi({
+      sessions: {
+        search: (request) => {
+          seen = request
+          return ok(request, {
+            items: [{ sessionId: sid('s1'), snippet: 'matching message text' }],
+            hasMore: true,
+          })
+        },
+      },
+    })
+    const response = await client(api).sessions.search({ query: '  message text  ' })
+    expect(seen?.payload).toEqual({ query: 'message text' })
+    expect(response.result).toEqual({
+      ok: true,
+      value: {
+        items: [{ sessionId: 's1', snippet: 'matching message text' }],
+        hasMore: true,
+      },
+    })
+  })
+
+  it('rejects an overlong session-search snippet at the client value boundary', async () => {
+    const api = scriptedApi({
+      sessions: {
+        search: request => ok(request, {
+          items: [{ sessionId: sid('s1'), snippet: '😀'.repeat(241) }],
+          hasMore: false,
+        }),
+      },
+    })
+
+    await expect(client(api).sessions.search({ query: 'message' }))
+      .rejects.toThrow(/240 Unicode code points/)
+  })
+
+  it('routes session fork with its optional cut anchor through the wire', async () => {
+    let seen: RpcRequest<{ sessionId: SessionId; atSeq?: number }> | undefined
+    const api = scriptedApi({
+      sessions: {
+        fork: (request) => {
+          seen = request
+          return ok(request, { sessionId: sid('s-child') })
+        },
+      },
+    })
+    const response = await client(api).sessions.fork({ sessionId: sid('s-parent'), atSeq: 7 })
+    expect(seen?.payload).toEqual({ sessionId: 's-parent', atSeq: 7 })
+    expect(response.result).toEqual({ ok: true, value: { sessionId: 's-child' } })
+  })
+
   it('routes workspace rename, delete, and insertSessionBefore through the wire', async () => {
     const api = scriptedApi()
     const c = client(api)
@@ -138,7 +241,7 @@ describe('unary round trip', () => {
   it('rejects a method/path mismatch as bad-request', async () => {
     const handler = toFetchHandler(scriptedApi())
     const body = { type: 'client-request', rpcId: 'r1', method: 'session.create', payload: {} }
-    const response = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: JSON.stringify(body) })
+    const response = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
     expect(response.status).toBe(200)
     const parsed = await response.json() as { result: { ok: boolean; error?: { code: string; message: string } } }
     expect(parsed.result.ok).toBe(false)
@@ -149,13 +252,13 @@ describe('unary round trip', () => {
   it('rejects a malformed envelope as bad-request, salvaging the rpcId or falling back to the sentinel', async () => {
     const handler = toFetchHandler(scriptedApi())
     // No salvageable rpcId → the fixed invalid-request sentinel keeps the response a valid ServerResponse.
-    const noId = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: JSON.stringify({ nonsense: true }) })
+    const noId = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ nonsense: true }) })
     expect(noId.status).toBe(200)
     const noIdParsed = await noId.json() as { rpcId: string; result: { ok: boolean } }
     expect(noIdParsed.result.ok).toBe(false)
     expect(noIdParsed.rpcId).toBe('invalid-request')
     // A string rpcId in the otherwise-bad body is salvaged for correlation.
-    const withId = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: JSON.stringify({ rpcId: 'salvage-me', nonsense: true }) })
+    const withId = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ rpcId: 'salvage-me', nonsense: true }) })
     const withIdParsed = await withId.json() as { rpcId: string; result: { ok: boolean } }
     expect(withIdParsed.result.ok).toBe(false)
     expect(withIdParsed.rpcId).toBe('salvage-me')
@@ -164,16 +267,34 @@ describe('unary round trip', () => {
   it('maps carrier failures to HTTP statuses and the client throws transport failure', async () => {
     const handler = toFetchHandler(scriptedApi())
     // Unknown method → 404.
-    const notFound = await handler.fetch('http://dsh.internal/api/no.such', { method: 'POST', body: '{}' })
+    const notFound = await handler.fetch('http://dsh.internal/api/no.such', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' })
     expect(notFound.status).toBe(404)
     // Non-JSON body → 400.
-    const badBody = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: '{oops' })
+    const badBody = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{oops' })
     expect(badBody.status).toBe(400)
     // Impl crash → 500, and through the client that is a throw, not an err result.
     const crashing = scriptedApi({ sessions: { list: () => { throw new Error('impl exploded') } } })
     await expect(client(crashing).sessions.list({})).rejects.toThrow(/transport failure .*500/)
   })
 
+  it('rejects non-JSON media types before executing anything (cross-site simple-request fence)', async () => {
+    const list = vi.fn((r: RpcRequest<{}>) => ok(r, { items: [] }))
+    const handler = toFetchHandler(scriptedApi({ sessions: { list } }))
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r1', method: 'session.list', payload: {} })
+    // A "simple" browser POST (text/plain — sent with no CORS preflight) is
+    // refused at the carrier before the impl runs.
+    const plain = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', headers: { 'content-type': 'text/plain' }, body })
+    expect(plain.status).toBe(415)
+    // A string body with no explicit header defaults to text/plain — same fence.
+    const unlabelled = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body })
+    expect(unlabelled.status).toBe(415)
+    expect(list).not.toHaveBeenCalled()
+    // Media-type parameters pass: the fence checks the type, not the exact string.
+    const charset = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', headers: { 'content-type': 'application/json; charset=utf-8' }, body })
+    expect(charset.status).toBe(200)
+    expect(list).toHaveBeenCalledTimes(1)
+  })
+
   it('rejects when the transport never resolves within timeoutMs', async () => {
     // AbortSignal.timeout is immune to fake timers; a short real timeout keeps this fast.
     const never = new InProcessApiClient({
@@ -240,10 +361,12 @@ describe('workspace domain round trip', () => {
   it('routes both workspace methods through their handler rows and value schemas', async () => {
     const c = client(scriptedApi())
     const list = await c.workspace.list({})
-    expect(list.result).toEqual({ ok: true, value: { items: [] } })
+    expect(list.result).toEqual({ ok: true, value: { items: [], archivedSessionIds: [] } })
     const created = await c.workspace.create({ path: '/t' })
     expect(created.result.ok).toBe(true)
     if (created.result.ok) expect(created.result.value.created).toBe(true)
+    const archivedResponse = await c.workspace.archiveSession({ sessionId: 's-arch' as never })
+    expect(archivedResponse.result).toEqual({ ok: true, value: { archivedSessionIds: ['s-arch'] } })
   })
 
   it('rejects a create payload violating the exactly-one refine at the handler', async () => {
@@ -404,6 +527,63 @@ describe('SSE stream path', () => {
   })
 })
 
+describe('goals unary surface', () => {
+  const ref: GoalRef = { id: 'goal-1' as GoalRef['id'], revision: 1 }
+  /** The `{ ref }` acknowledgement every non-clear mutation answers (state travels on the projection). */
+  const ack = { ref: { id: 'goal-1' as GoalRef['id'], revision: 2 } }
+
+  it('round-trips every goal method with its own payload and value shape', async () => {
+    const seen: { method: string; payload: unknown }[] = []
+    const record = recorderInto(seen)
+    const api = scriptedApi({
+      goals: {
+        create: record('goal.create', r => ok(r, ack)),
+        edit: record('goal.edit', r => ok(r, { ref: { ...ack.ref, revision: 3 } })),
+        pause: record('goal.pause', r => ok(r, ack)),
+        resume: record('goal.resume', r => ok(r, ack)),
+        complete: record('goal.complete', r => ok(r, ack)),
+        clear: record('goal.clear', r => ok(r, { cleared: true as const })),
+      },
+    })
+    const c = client(api)
+
+    const created = await c.goals.create({ sessionId: sid('s1'), objective: 'ship it', maxGoalRounds: 4 })
+    expect(created.result).toEqual({ ok: true, value: ack })
+    const edited = await c.goals.edit({ sessionId: sid('s1'), ref, objective: 'ship v2' })
+    expect(edited.result).toEqual({ ok: true, value: { ref: { ...ack.ref, revision: 3 } } })
+    expect((await c.goals.pause({ sessionId: sid('s1'), ref })).result).toEqual({ ok: true, value: ack })
+    expect((await c.goals.resume({ sessionId: sid('s1'), ref })).result).toEqual({ ok: true, value: ack })
+    expect((await c.goals.complete({ sessionId: sid('s1'), ref })).result).toEqual({ ok: true, value: ack })
+    const cleared = await c.goals.clear({ sessionId: sid('s1'), ref })
+    expect(cleared.result).toEqual({ ok: true, value: { cleared: true } })
+
+    // The handler dispatched each call through its own route row: payload parsed per method.
+    expect(seen.map(s => s.method)).toEqual(['goal.create', 'goal.edit', 'goal.pause', 'goal.resume', 'goal.complete', 'goal.clear'])
+    expect(seen[0]?.payload).toEqual({ sessionId: 's1', objective: 'ship it', maxGoalRounds: 4 })
+    expect(seen[1]?.payload).toEqual({ sessionId: 's1', ref, objective: 'ship v2' })
+  })
+
+  it('passes business errors through as results, not throws', async () => {
+    // Default scripted goals impl answers an err result: it must arrive as a result, not a throw.
+    const failed = await client(scriptedApi()).goals.pause({ sessionId: sid('s1'), ref })
+    expect(failed.result.ok).toBe(false)
+    if (!failed.result.ok) expect(failed.result.error.code).toBe('internal')
+  })
+
+  it('rejects an invalid goal payload at the handler as bad-request', async () => {
+    const response = await client(scriptedApi()).goals.create({ sessionId: sid('s1'), objective: '' })
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) expect(response.result.error.code).toBe('bad-request')
+
+    let editCalls = 0
+    const api = scriptedApi({ goals: { edit: (r) => { editCalls++; return ok(r, ack) } } })
+    const emptyEdit = await client(api).goals.edit({ sessionId: sid('s1'), ref })
+    expect(emptyEdit.result.ok).toBe(false)
+    if (!emptyEdit.result.ok) expect(emptyEdit.result.error.code).toBe('bad-request')
+    expect(editCalls).toBe(0)
+  })
+})
+
 describe('respond path', () => {
   it('round-trips a client-response to a receipt', async () => {
     const seen: unknown[] = []
@@ -421,7 +601,7 @@ describe('respond path', () => {
   it('returns bad-response for a malformed client-response without reaching the impl', async () => {
     const respond = vi.fn()
     const handler = toFetchHandler(scriptedApi({ respond }))
-    const response = await handler.fetch('http://dsh.internal/api/respond', { method: 'POST', body: JSON.stringify({ type: 'client-response' }) })
+    const response = await handler.fetch('http://dsh.internal/api/respond', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ type: 'client-response' }) })
     expect(await response.json()).toEqual({ accepted: false, reason: 'bad-response' })
     expect(respond).not.toHaveBeenCalled()
   })
@@ -468,3 +648,84 @@ describe('envelope tap', () => {
     expect(batches).toEqual([])
   })
 })
+
+describe('config unary surface', () => {
+  it('round-trips every settings/credentials/llm method with its own payload and value shape', async () => {
+    const seen: { method: string; payload: unknown }[] = []
+    const record = recorderInto(seen)
+    const view = {
+      ns: 'llm-deepseek',
+      schema: { uid: 1, refs: { 1: { type: 'object' } } },
+      value: { baseURL: 'https://next' },
+      user: { baseURL: 'https://next' },
+      applies: 'live' as const,
+      secrets: [{ path: ['apiKey'], set: true }],
+      revision: 0,
+    }
+    const providerRow = {
+      provider: 'openai',
+      displayName: 'openai',
+      settingsNs: 'llm-pi-ai',
+      settingsPath: ['providers', 'openai'],
+      active: false,
+    }
+    const group = { id: 'deepseek-official', name: 'DeepSeek', models: [{ id: 'deepseek-v4-flash', name: 'Flash' }] }
+    const api = scriptedApi({
+      settings: {
+        describe: record('settings.describe', r => ok(r, { writable: true, namespaces: [view] })),
+        update: record('settings.update', r => ok(r, view)),
+        replace: record('settings.replace', r => ok(r, view)),
+        mutate: record('settings.mutate', r => ok(r, view)),
+      },
+      credentials: {
+        describe: record('credentials.describe', r => ok(r, { credentials: { OPENAI_API_KEY: { configured: true, source: 'file', writable: true } } })),
+        set: record('credentials.set', r => ok(r, {})),
+        unset: record('credentials.unset', r => ok(r, {})),
+      },
+      llm: {
+        providers: record('llm.providers', r => ok(r, { providers: [providerRow] })),
+        models: record('llm.models', r => ok(r, { groups: [group], failures: [] })),
+      },
+    })
+    const c = client(api)
+
+    const described = await c.settings.describe({})
+    expect(described.result).toEqual({ ok: true, value: { writable: true, namespaces: [view] } })
+    const updated = await c.settings.update({ ns: 'llm-deepseek', patch: { baseURL: 'https://next' } })
+    expect(updated.result).toEqual({ ok: true, value: view })
+    const replaced = await c.settings.replace({ ns: 'llm-deepseek', section: {} })
+    expect(replaced.result).toEqual({ ok: true, value: view })
+    const mutated = await c.settings.mutate({
+      ns: 'llm-deepseek',
+      ops: [{ op: 'unset', path: ['baseURL'] }],
+      expectedRevision: 0,
+    })
+    expect(mutated.result).toEqual({ ok: true, value: view })
+    const creds = await c.credentials.describe({ refs: ['OPENAI_API_KEY'] })
+    expect(creds.result).toEqual({ ok: true, value: { credentials: { OPENAI_API_KEY: { configured: true, source: 'file', writable: true } } } })
+    expect((await c.credentials.set({ ref: 'OPENAI_API_KEY', value: 'sk-x' })).result).toEqual({ ok: true, value: {} })
+    expect((await c.credentials.unset({ ref: 'OPENAI_API_KEY' })).result).toEqual({ ok: true, value: {} })
+    const providers = await c.llm.providers({})
+    expect(providers.result).toEqual({ ok: true, value: { providers: [providerRow] } })
+    const models = await c.llm.models({})
+    expect(models.result).toEqual({ ok: true, value: { groups: [group], failures: [] } })
+
+    expect(seen.map(call => call.method)).toEqual([
+      'settings.describe', 'settings.update', 'settings.replace', 'settings.mutate',
+      'credentials.describe', 'credentials.set', 'credentials.unset',
+      'llm.providers', 'llm.models',
+    ])
+    expect(seen[1]?.payload).toEqual({ ns: 'llm-deepseek', patch: { baseURL: 'https://next' } })
+    expect(seen[3]?.payload)
+      .toEqual({ ns: 'llm-deepseek', ops: [{ op: 'unset', path: ['baseURL'] }], expectedRevision: 0 })
+    expect(seen[5]?.payload).toEqual({ ref: 'OPENAI_API_KEY', value: 'sk-x' })
+  })
+
+  it('rejects an invalid credential reference name at the carrier boundary', async () => {
+    const api = scriptedApi()
+    const response = await client(api).credentials.set({ ref: 'not a var', value: 'x' })
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('bad-request')
+  })
+})

packages/host/apiproxy/tests/fetch-carrier.spec.ts

@@ -1,3 +1,4 @@
+import { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import { describe, expect, it, vi } from 'vitest'
 import type { ApiProxy, HostFrame, MuxFrame } from '../src/api/index.ts'
 import type { ClientResponse, RpcMessage, RpcReceipt, RpcRequest } from '../src/api/rpc.ts'
@@ -21,14 +22,34 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
         if (overrides.crashOn === 'session.list') throw new Error('impl crashed')
         return { rpcId: request.rpcId, result: { ok: true, value: { items: [] } } }
       },
+      async search(request, signal) {
+        if (request.payload.query === 'hang') {
+          if (!signal.aborted) {
+            await new Promise<void>((resolve) => {
+              signal.addEventListener('abort', () => { resolve() }, { once: true })
+            })
+          }
+          return {
+            rpcId: request.rpcId,
+            result: { ok: false, error: { code: 'cancelled', message: 'aborted', details: {} } },
+          }
+        }
+        return {
+          rpcId: request.rpcId,
+          result: {
+            ok: true,
+            value: { items: [{ sessionId: 's1' as never, snippet: 'fixture match' }], hasMore: false },
+          },
+        }
+      },
       async create(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { sessionId: 's-new' as never } } }
       },
       async history(request) {
-        if (request.payload.sessionId === ('with-todos' as never)) {
+        if (request.payload.sessionId === ('with-projections' as never)) {
           return {
             rpcId: request.rpcId,
-            result: { ok: true, value: { events: [], hasMore: false, todos: [{ content: 'current', status: 'in_progress' as const }] } },
+            result: { ok: true, value: { events: [], hasMore: false, projections: { asOfSeq: 9, values: { todos: [{ content: 'current', status: 'in_progress' as const }] } } } },
           }
         }
         return {
@@ -42,7 +63,7 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
           result: {
             ok: true,
             value: {
-              current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+              current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
               groups: [],
               failures: [],
             },
@@ -66,9 +87,18 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
           },
         }
       },
+      async rename(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { title: request.payload.title, seq: 0 } } }
+      },
+      async fork(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { sessionId: 's-fork' as never } } }
+      },
       async prompt(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
       },
+      async updateQueue(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
+      },
       async cancel(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
       },
@@ -80,10 +110,19 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
       async pickDirectory(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { path: null } } }
       },
+      async listDirectory(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { path: '/w', home: '/w', crumbs: [{ name: '/', path: '/', hidden: false }], entries: [], truncated: false } } }
+      },
+      async createDirectory(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { path: '/w/new' } } }
+      },
+      async openPath(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { opened: true as const } } }
+      },
     },
     workspace: {
       async list(request) {
-        return { rpcId: request.rpcId, result: { ok: true, value: { items: [] } } }
+        return { rpcId: request.rpcId, result: { ok: true, value: { items: [], archivedSessionIds: [] } } }
       },
       async create(request) {
         return {
@@ -106,6 +145,9 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
           result: { ok: true, value: { workspace: { workspaceId: 'w1' as never, path: '/w', title: 'w', sessionIds: [], createdAt: 't', updatedAt: 't' } } },
         }
       },
+      async archiveSession(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { archivedSessionIds: [request.payload.sessionId] } } }
+      },
     },
     commands: {
       async list(request) {
@@ -121,7 +163,7 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
           return { rpcId: request.rpcId, result: { ok: false, error: { code: 'cancelled', message: 'aborted', details: {} } } }
         }
         if (request.payload.line.startsWith('/plan')) {
-          return { rpcId: request.rpcId, result: { ok: true, value: { matched: true, result: { kind: 'success' as const, text: 'plan set' } } } }
+          return { rpcId: request.rpcId, result: { ok: true, value: { matched: true, commandId: CommandId('cmd-x') } } }
         }
         return { rpcId: request.rpcId, result: { ok: true, value: { matched: false } } }
       },
@@ -131,6 +173,59 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
         return { rpcId: request.rpcId, result: { ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits' }] } } }
       },
     },
+    goals: {
+      async create(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'internal', message: 'stub', details: {} } } }
+      },
+      async edit(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'internal', message: 'stub', details: {} } } }
+      },
+      async pause(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'internal', message: 'stub', details: {} } } }
+      },
+      async resume(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'internal', message: 'stub', details: {} } } }
+      },
+      async complete(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'internal', message: 'stub', details: {} } } }
+      },
+      async clear(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'internal', message: 'stub', details: {} } } }
+      },
+    },
+    settings: {
+      async describe(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { writable: true, namespaces: [] } } }
+      },
+      async update(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'settings-rejected', message: 'stub', details: { ns: request.payload.ns } } } }
+      },
+      async replace(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'settings-rejected', message: 'stub', details: { ns: request.payload.ns } } } }
+      },
+      async mutate(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'settings-rejected', message: 'stub', details: { ns: request.payload.ns } } } }
+      },
+    },
+    credentials: {
+      async describe(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { credentials: {} } } }
+      },
+      async set(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: {} } }
+      },
+      async unset(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: {} } }
+      },
+    },
+    llm: {
+      async providers(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { providers: [] } } }
+      },
+      async models(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { groups: [], failures: [] } } }
+      },
+    },
     events: {
       mux: (_request, signal) => stream(muxFrames, signal),
       host: (_request, signal) => stream(hostFrames, signal),
@@ -158,10 +253,14 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     expect(response.rpcId).toMatch(/[0-9a-f-]{36}/)
   })
 
-  it('carries the tail-page todos projection through the wire schema (Zod must not strip it)', async () => {
-    const response = await client().sessions.history({ sessionId: 'with-todos' as never })
+  it('carries the tail-page projections block through the wire schema (Zod must not strip it)', async () => {
+    const response = await client().sessions.history({ sessionId: 'with-projections' as never })
     expect(response.result.ok).toBe(true)
-    if (response.result.ok) expect(response.result.value.todos).toEqual([{ content: 'current', status: 'in_progress' }])
+    if (response.result.ok) {
+      expect(response.result.value.projections).toEqual(
+        { asOfSeq: 9, values: { todos: [{ content: 'current', status: 'in_progress' }] } },
+      )
+    }
   })
 
   it('carries a business error as 200 + error result', async () => {
@@ -170,13 +269,17 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     if (!response.result.ok) expect(response.result.error.code).toBe('session-not-found')
   })
 
-  it('covers create/prompt/cancel/describe passthrough', async () => {
+  it('covers create/prompt/updateQueue/cancel/describe passthrough', async () => {
     const c = client()
+    expect((await c.sessions.search({ query: 'fixture' })).result).toEqual({
+      ok: true,
+      value: { items: [{ sessionId: 's1', snippet: 'fixture match' }], hasMore: false },
+    })
     expect((await c.sessions.create({})).result.ok).toBe(true)
     expect((await c.sessions.models({ sessionId: 's' as never })).result.ok).toBe(true)
     const selected = await c.sessions.selectModel({
       sessionId: 's' as never,
-      provider: 'deepseek',
+      provider: 'deepseek-official',
       model: 'deepseek-v4-flash',
       reasoningEffort: 'max',
     })
@@ -184,13 +287,20 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
       ok: true,
       value: {
         selected: {
-          provider: 'deepseek',
+          provider: 'deepseek-official',
           model: 'deepseek-v4-flash',
           reasoningEffort: 'max',
         },
       },
     })
+    const renamed = await c.sessions.rename({ sessionId: 's' as never, title: 'named' })
+    expect(renamed.result).toMatchObject({ ok: true, value: { title: 'named', seq: 0 } })
     expect((await c.sessions.prompt({ sessionId: 's' as never, mode: 'queue', content: [{ type: 'text', text: 'x' }] })).result.ok).toBe(true)
+    expect((await c.sessions.updateQueue({
+      sessionId: 's' as never,
+      itemId: 'item-1' as never,
+      action: { kind: 'remove' },
+    })).result.ok).toBe(true)
     expect((await c.sessions.cancel({ sessionId: 's' as never })).result.ok).toBe(true)
     expect((await c.host.describe({})).result.ok).toBe(true)
   })
@@ -205,25 +315,112 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     expect(response.result).toEqual({ ok: true, value: { path: '/tmp/project' } })
   })
 
+  it('round-trips the browse listing and creation calls through the wire form', async () => {
+    const c = client()
+    const listed = await c.host.listDirectory({ path: '/w' })
+    expect(listed.result).toEqual({
+      ok: true,
+      value: { path: '/w', home: '/w', crumbs: [{ name: '/', path: '/', hidden: false }], entries: [], truncated: false },
+    })
+    const home = await c.host.listDirectory({})
+    expect(home.result).toMatchObject({ ok: true, value: { home: '/w' } })
+    const created = await c.host.createDirectory({ path: '/w', name: 'fresh' })
+    expect(created.result).toEqual({ ok: true, value: { path: '/w/new' } })
+  })
+
+  it('round-trips host.openPath through the wire form', async () => {
+    const api = fakeApi()
+    let opened: string | undefined
+    api.host.openPath = async (request) => {
+      opened = request.payload.path
+      return { rpcId: request.rpcId, result: { ok: true, value: { opened: true as const } } }
+    }
+    const response = await client(api).host.openPath({ path: '/tmp/a.txt' })
+    expect(opened).toBe('/tmp/a.txt')
+    expect(response.result).toEqual({ ok: true, value: { opened: true } })
+  })
+
   it('round-trips command.list / command.execute / skill.list through the wire form', async () => {
     const c = client()
     const list = await c.commands.list({ sessionId: 's' as never })
     expect(list.result).toEqual({ ok: true, value: { commands: [{ name: 'plan', description: 'Toggle plan mode', input: { hint: 'on|off' } }] } })
     const hit = await c.commands.execute({ sessionId: 's' as never, line: '/plan off' })
-    expect(hit.result).toEqual({ ok: true, value: { matched: true, result: { kind: 'success', text: 'plan set' } } })
+    expect(hit.result).toEqual({ ok: true, value: { matched: true, commandId: 'cmd-x' } })
     const miss = await c.commands.execute({ sessionId: 's' as never, line: '/nope' })
     expect(miss.result).toEqual({ ok: true, value: { matched: false } })
     const skills = await c.skills.list({ sessionId: 's' as never })
     expect(skills.result).toEqual({ ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits' }] } })
   })
 
+  it('lets command.execute finish after the 30-second default unary deadline', async () => {
+    vi.useFakeTimers()
+    const timeoutSpy = vi.spyOn(AbortSignal, 'timeout').mockImplementation((milliseconds) => {
+      const controller = new AbortController()
+      setTimeout(() => {
+        controller.abort(new DOMException('The operation was aborted due to timeout', 'TimeoutError'))
+      }, milliseconds)
+      return controller.signal
+    })
+    try {
+      const api = fakeApi()
+      api.commands.execute = async (request) => {
+        await new Promise(resolve => setTimeout(resolve, 30_001))
+        return {
+          rpcId: request.rpcId,
+          result: { ok: true, value: { matched: true, commandId: CommandId('cmd-slow') } },
+        }
+      }
+      const execution = client(api).commands.execute({ sessionId: 's' as never, line: '/slow' })
+      const assertion = expect(execution).resolves.toMatchObject({
+        result: { ok: true, value: { matched: true, commandId: 'cmd-slow' } },
+      })
+
+      await Promise.all([
+        vi.advanceTimersByTimeAsync(30_001),
+        assertion,
+      ])
+      expect(timeoutSpy).not.toHaveBeenCalled()
+    } finally {
+      timeoutSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('keeps caller and connection aborts on command.execute', async () => {
+    const api = fakeApi()
+    const started = Promise.withResolvers<AbortSignal>()
+    api.commands.execute = async (request, signal) => {
+      started.resolve(signal)
+      if (!signal.aborted) {
+        await new Promise<void>((resolve) => {
+          signal.addEventListener('abort', () => { resolve() }, { once: true })
+        })
+      }
+      return {
+        rpcId: request.rpcId,
+        result: { ok: false, error: { code: 'cancelled', message: 'aborted', details: {} } },
+      }
+    }
+    const controller = new AbortController()
+    const execution = client(api).commands.execute(
+      { sessionId: 's' as never, line: '/hang' },
+      controller.signal,
+    )
+    const handlerSignal = await started.promise
+
+    controller.abort(new Error('connection closed'))
+
+    await expect(execution).rejects.toThrow('connection closed')
+    expect(handlerSignal.aborted).toBe(true)
+  })
+
   it('propagates the carrier Request signal into command.execute', async () => {
     const handler = toFetchHandler(fakeApi())
     const controller = new AbortController()
     const body = JSON.stringify({ type: 'client-request', rpcId: 'r-sig', method: 'command.execute', payload: { sessionId: 's', line: '/hang' } })
     // The fake's /hang settles only when the invoke-level signal aborts: a
     // completed response with the cancelled error proves req.signal reached it.
-    const pending = handler.fetch(new Request('http://x/api/command.execute', { method: 'POST', body, signal: controller.signal }))
+    const pending = handler.fetch(new Request('http://x/api/command.execute', { method: 'POST', headers: { 'content-type': 'application/json' }, body, signal: controller.signal }))
     controller.abort()
     const response = await pending
     const parsed = await response.json() as { rpcId: string; result: { ok: boolean; error?: { code: string } } }
@@ -231,6 +428,29 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     expect(parsed.result.error?.code).toBe('cancelled')
   })
 
+  it('propagates the carrier Request signal into session.search', async () => {
+    const handler = toFetchHandler(fakeApi())
+    const controller = new AbortController()
+    const body = JSON.stringify({
+      type: 'client-request',
+      rpcId: 'r-search-sig',
+      method: 'session.search',
+      payload: { query: 'hang' },
+    })
+    const pending = handler.fetch(new Request(
+      'http://x/api/session.search',
+      { method: 'POST', headers: { 'content-type': 'application/json' }, body, signal: controller.signal },
+    ))
+    controller.abort()
+    const response = await pending
+    const parsed = await response.json() as {
+      rpcId: string
+      result: { error?: { code: string } }
+    }
+    expect(parsed.rpcId).toBe('r-search-sig')
+    expect(parsed.result.error?.code).toBe('cancelled')
+  })
+
   it('propagates the carrier Request signal into host.pickDirectory', async () => {
     const api = fakeApi()
     api.host.pickDirectory = async (request, signal) => {
@@ -248,7 +468,7 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     const controller = new AbortController()
     const body = JSON.stringify({ type: 'client-request', rpcId: 'r-picker', method: 'host.pickDirectory', payload: {} })
     const pending = handler.fetch(new Request('http://x/api/host.pickDirectory', {
-      method: 'POST', body, signal: controller.signal,
+      method: 'POST', headers: { 'content-type': 'application/json' }, body, signal: controller.signal,
     }))
     controller.abort()
     const parsed = await (await pending).json() as { result: { error?: { code: string } } }
@@ -260,18 +480,18 @@ describe('handler carrier-layer statuses', () => {
   const handler = toFetchHandler(fakeApi())
 
   it('404s unknown paths and non-POST non-stream methods', async () => {
-    expect((await handler.fetch(new Request('http://x/other', { method: 'POST', body: '{}' }))).status).toBe(404)
+    expect((await handler.fetch(new Request('http://x/other', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' }))).status).toBe(404)
     expect((await handler.fetch(new Request('http://x/api/session.list', { method: 'GET' }))).status).toBe(404)
-    expect((await handler.fetch(new Request('http://x/api/no.such', { method: 'POST', body: JSON.stringify({ type: 'client-request', rpcId: 'r', method: 'no.such', payload: {} }) }))).status).toBe(404)
+    expect((await handler.fetch(new Request('http://x/api/no.such', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ type: 'client-request', rpcId: 'r', method: 'no.such', payload: {} }) }))).status).toBe(404)
   })
 
   it('400s a non-JSON body', async () => {
-    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', body: 'not json' }))
+    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', headers: { 'content-type': 'application/json' }, body: 'not json' }))
     expect(response.status).toBe(400)
   })
 
   it('rejects a malformed envelope with bad-request and the invalid-request sentinel rpcId', async () => {
-    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', body: JSON.stringify({ nope: true }) }))
+    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ nope: true }) }))
     expect(response.status).toBe(200)
     const body = await response.json() as { rpcId: string; result: { ok: boolean; error?: { code: string } } }
     expect(body.rpcId).toBe('invalid-request')
@@ -280,7 +500,7 @@ describe('handler carrier-layer statuses', () => {
 
   it('rejects a method/path mismatch echoing the envelope rpcId', async () => {
     const body = JSON.stringify({ type: 'client-request', rpcId: 'r-9', method: 'session.cancel', payload: {} })
-    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', body }))
+    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', headers: { 'content-type': 'application/json' }, body }))
     const parsed = await response.json() as { rpcId: string; result: { error?: { message: string } } }
     expect(parsed.rpcId).toBe('r-9')
     expect(parsed.result.error?.message).toContain('does not match path')
@@ -288,7 +508,7 @@ describe('handler carrier-layer statuses', () => {
 
   it('rejects an invalid payload with the zod issues attached', async () => {
     const body = JSON.stringify({ type: 'client-request', rpcId: 'r-10', method: 'session.cancel', payload: {} })
-    const response = await handler.fetch(new Request('http://x/api/session.cancel', { method: 'POST', body }))
+    const response = await handler.fetch(new Request('http://x/api/session.cancel', { method: 'POST', headers: { 'content-type': 'application/json' }, body }))
     const parsed = await response.json() as { result: { error?: { code: string; details: { issues: unknown[] } } } }
     expect(parsed.result.error?.code).toBe('bad-request')
     expect(parsed.result.error?.details.issues.length).toBeGreaterThan(0)
@@ -297,23 +517,23 @@ describe('handler carrier-layer statuses', () => {
   it('500s when the impl itself throws', async () => {
     const crashing = toFetchHandler(fakeApi({ crashOn: 'session.list' }))
     const body = JSON.stringify({ type: 'client-request', rpcId: 'r-11', method: 'session.list', payload: {} })
-    const response = await crashing.fetch(new Request('http://x/api/session.list', { method: 'POST', body }))
+    const response = await crashing.fetch(new Request('http://x/api/session.list', { method: 'POST', headers: { 'content-type': 'application/json' }, body }))
     expect(response.status).toBe(500)
     expect(await response.text()).toContain('impl crashed')
   })
 
   it('routes /api/respond, rejecting malformed client-responses as a receipt', async () => {
     const good = JSON.stringify({ type: 'client-response', rpcId: 'known', result: { ok: true, value: null } })
-    const goodReceipt: unknown = await (await handler.fetch(new Request('http://x/api/respond', { method: 'POST', body: good }))).json()
+    const goodReceipt: unknown = await (await handler.fetch(new Request('http://x/api/respond', { method: 'POST', headers: { 'content-type': 'application/json' }, body: good }))).json()
     expect(goodReceipt).toEqual({ accepted: true })
     const bad = JSON.stringify({ type: 'client-request', rpcId: 'r', method: 'x', payload: {} })
-    const badReceipt: unknown = await (await handler.fetch(new Request('http://x/api/respond', { method: 'POST', body: bad }))).json()
+    const badReceipt: unknown = await (await handler.fetch(new Request('http://x/api/respond', { method: 'POST', headers: { 'content-type': 'application/json' }, body: bad }))).json()
     expect(badReceipt).toEqual({ accepted: false, reason: 'bad-response' })
   })
 
   it('accepts (url, init) form fetch invocation', async () => {
     const body = JSON.stringify({ type: 'client-request', rpcId: 'r-12', method: 'session.list', payload: {} })
-    const response = await handler.fetch('http://x/api/session.list', { method: 'POST', body })
+    const response = await handler.fetch('http://x/api/session.list', { method: 'POST', headers: { 'content-type': 'application/json' }, body })
     expect(response.status).toBe(200)
   })
 })

packages/host/apiproxy/tests/native-path-opener.spec.ts

@@ -0,0 +1,82 @@
+type ExecFileCallback = (
+  error: (Error & { code?: string | number }) | null,
+  stdout: string,
+  stderr: string,
+) => void
+type ExecFileMock = (
+  command: string,
+  args: readonly string[],
+  options: { encoding: string; signal: AbortSignal; windowsHide: boolean },
+  callback: ExecFileCallback,
+) => void
+
+const { execFileMock } = vi.hoisted(() => ({ execFileMock: vi.fn<ExecFileMock>() }))
+
+vi.mock('node:child_process', () => ({ execFile: execFileMock }))
+
+import { describe, expect, it, vi } from 'vitest'
+import { openNativePath, type PathOpenerRunner } from '../src/native-path-opener.ts'
+
+const signal = () => new AbortController().signal
+
+describe('native path opener', () => {
+  it('opens with macOS open(1)', async () => {
+    const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
+    await openNativePath('/Users/test/file.txt', signal(), { platform: 'darwin', run })
+    expect(run).toHaveBeenCalledWith('open', ['/Users/test/file.txt'], expect.any(AbortSignal))
+  })
+
+  it('opens with Windows Invoke-Item and escapes single quotes', async () => {
+    const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
+    await openNativePath("C:\\work\\o'reilly.txt", signal(), { platform: 'win32', run })
+    expect(run).toHaveBeenCalledWith(
+      'powershell.exe',
+      ['-NoProfile', '-Command', "Invoke-Item -LiteralPath 'C:\\work\\o''reilly.txt'"],
+      expect.any(AbortSignal),
+    )
+  })
+
+  it('opens with Linux xdg-open', async () => {
+    const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
+    await openNativePath('/tmp/a.txt', signal(), { platform: 'linux', run })
+    expect(run).toHaveBeenCalledWith('xdg-open', ['/tmp/a.txt'], expect.any(AbortSignal))
+  })
+
+  it('rejects unsupported platforms', async () => {
+    await expect(openNativePath('/x', signal(), { platform: 'freebsd' as NodeJS.Platform }))
+      .rejects.toThrow('unsupported on freebsd')
+  })
+
+  it('uses the current process platform when no platform override is supplied', async () => {
+    const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
+    await openNativePath('/tmp/platform-default.txt', signal(), { run })
+    const expected = process.platform === 'win32'
+      ? 'powershell.exe'
+      : process.platform === 'linux'
+        ? 'xdg-open'
+        : 'open'
+    expect(run.mock.calls[0]?.[0]).toBe(expected)
+  })
+
+  it('runs the default command adapter without a shell and preserves command failures', async () => {
+    execFileMock.mockImplementationOnce((_command, _args, _options, callback) => {
+      callback(null, '', '')
+    })
+    await openNativePath('/tmp/default.txt', signal(), { platform: 'darwin' })
+    const [command, args, options] = execFileMock.mock.calls[0]!
+    expect(command).toBe('open')
+    expect(args).toEqual(['/tmp/default.txt'])
+    expect(options.encoding).toBe('utf8')
+    expect(options.windowsHide).toBe(true)
+    expect(options.signal).toBeInstanceOf(AbortSignal)
+
+    const commandError = Object.assign(new Error('open failed'), { code: 1 })
+    execFileMock.mockImplementationOnce((_command, _args, _options, callback) => {
+      callback(commandError, 'partial output', 'failure details')
+    })
+    await expect(openNativePath('/tmp/missing.txt', signal(), { platform: 'darwin' })).rejects.toMatchObject({
+      message: 'open failed', cause: commandError, code: 1,
+      stdout: 'partial output', stderr: 'failure details',
+    })
+  })
+})

packages/host/apiproxy/tests/rpc-schemas.spec.ts

@@ -10,10 +10,17 @@ import {
   sessionCreateValueSchema, sessionEventSchema, sessionHistoryRequestSchema, sessionHistoryValueSchema,
   sessionIdSchema, sessionListRequestSchema, sessionListValueSchema, sessionModelsRequestSchema,
   sessionModelsValueSchema, sessionPromptRequestSchema, sessionPromptValueSchema,
-  sessionSelectModelRequestSchema, sessionSelectModelValueSchema, sessionSummarySchema,
+  sessionSearchRequestSchema, sessionSearchValueSchema, sessionSelectModelRequestSchema,
+  sessionSelectModelValueSchema, sessionSummarySchema,
+  sessionUpdateQueueRequestSchema, sessionUpdateQueueValueSchema,
 } from '../src/api/sessions.schema.ts'
-import { hostDescribeRequestSchema, hostDescribeValueSchema } from '../src/api/host.schema.ts'
 import {
+  hostCreateDirectoryRequestSchema, hostCreateDirectoryValueSchema,
+  hostDescribeRequestSchema, hostDescribeValueSchema,
+  hostListDirectoryRequestSchema, hostListDirectoryValueSchema,
+} from '../src/api/host.schema.ts'
+import {
+  workspaceArchiveSessionRequestSchema, workspaceArchiveSessionValueSchema,
   workspaceCreateRequestSchema, workspaceCreateValueSchema, workspaceIdSchema,
   workspaceDeleteRequestSchema, workspaceDeleteValueSchema,
   workspaceInsertSessionBeforeRequestSchema, workspaceInsertSessionBeforeValueSchema,
@@ -28,6 +35,7 @@ import { skillEntrySchema, skillListRequestSchema, skillListValueSchema } from '
 import { hostFrameSchema, muxFrameSchema, askUserQuestionItemSchema } from '../src/api/events.schema.ts'
 import { approvalRequestIdSchema, approvalResponsePayloadSchema } from '../src/api/approvals.schema.ts'
 import { askUserQuestionAnswerSchema, questionResponsePayloadSchema } from '../src/api/questions.schema.ts'
+import { goalEditRequestSchema } from '../src/api/goals.schema.ts'
 
 describe('RpcId', () => {
   it('brands a raw string at zero runtime cost', () => {
@@ -63,11 +71,17 @@ describe('rpcErrorSchema', () => {
       details: { provider: 'p', model: 'm' },
     }).code).toBe('model-unavailable')
     expect(rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: { reason: 'r' } }).code).toBe('agent-busy')
+    expect(rpcErrorSchema.parse({ code: 'queue-item-not-found', message: 'm', details: { itemId: 'i' } }).code).toBe('queue-item-not-found')
+    expect(rpcErrorSchema.parse({ code: 'command-error', message: 'm', details: {} }).code).toBe('command-error')
+    expect(rpcErrorSchema.parse({ code: 'unknown-command', message: 'm', details: {} }).code).toBe('unknown-command')
+    expect(rpcErrorSchema.parse({ code: 'title-invalid', message: 'm', details: { sessionId: 's' } }).code).toBe('title-invalid')
     expect(rpcErrorSchema.parse({ code: 'internal', message: 'm', details: {} }).code).toBe('internal')
   })
 
   it('rejects a known code with missing details', () => {
     expect(() => rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: {} })).toThrow()
+    expect(() => rpcErrorSchema.parse({ code: 'title-invalid', message: 'm', details: {} })).toThrow()
+    expect(() => rpcErrorSchema.parse({ code: 'command-error', message: 'm' })).toThrow()
     expect(() => rpcErrorSchema.parse({ code: 'nope', message: 'm', details: {} })).toThrow()
   })
 })
@@ -119,15 +133,55 @@ describe('sessions domain schemas', () => {
     expect(sessionSummarySchema.parse({ sessionId: 's1', updatedAt: 1, running: true, blank: false, parentSessionId: 'p', cwd: '/x' }).cwd).toBe('/x')
     // blank is mandatory: a summary without it fails the parse.
     expect(() => sessionSummarySchema.parse({ sessionId: 's1', updatedAt: 1, running: false })).toThrow()
-    const event = sessionEventSchema.parse({ type: 'user/message', seq: 0, time: 1, data: { any: true } })
+    const event = sessionEventSchema.parse({
+      type: 'user/message',
+      seq: 0,
+      time: 1,
+      data: { any: true },
+    })
     expect(event).toMatchObject({ type: 'user/message' })
-    expect(() => sessionEventSchema.parse({ type: 'user/message', seq: -1, time: 1, data: {} })).toThrow()
+    expect(() => sessionEventSchema.parse({
+      type: 'user/message',
+      seq: -1,
+      time: 1,
+      data: {},
+    })).toThrow()
   })
 
   it('validates the per-method request/value pairs', () => {
     expect(sessionListRequestSchema.parse({})).toEqual({})
     expect(sessionListRequestSchema.parse({ cursor: 'c' }).cursor).toBe('c')
     expect(sessionListValueSchema.parse({ items: [] }).items).toEqual([])
+    expect(sessionSearchRequestSchema.parse({ query: '  exact phrase  ' })).toEqual({ query: 'exact phrase' })
+    expect(() => sessionSearchRequestSchema.parse({ query: '   ' })).toThrow()
+    expect(() => sessionSearchRequestSchema.parse({ query: 'bad\0query' })).toThrow(/NUL/)
+    expect(() => sessionSearchRequestSchema.parse({ query: 'x'.repeat(501) })).toThrow()
+    expect(sessionSearchValueSchema.parse({
+      items: [{ sessionId: 's1', snippet: 'matching text' }],
+      hasMore: true,
+    })).toEqual({
+      items: [{ sessionId: 's1', snippet: 'matching text' }],
+      hasMore: true,
+    })
+    expect(sessionSearchValueSchema.parse({
+      items: [{ sessionId: 's1', snippet: '😀'.repeat(240) }],
+      hasMore: false,
+    }).items[0]?.snippet).toBe('😀'.repeat(240))
+    expect(() => sessionSearchValueSchema.parse({
+      items: [{ sessionId: 's1', snippet: '😀'.repeat(241) }],
+      hasMore: false,
+    })).toThrow(/240 Unicode code points/)
+    expect(() => sessionSearchValueSchema.parse({
+      items: [{ sessionId: '', snippet: 'matching text' }],
+      hasMore: false,
+    })).toThrow()
+    expect(() => sessionSearchValueSchema.parse({
+      items: Array.from(
+        { length: 21 },
+        (_, index) => ({ sessionId: `s${index}`, snippet: 'matching text' }),
+      ),
+      hasMore: true,
+    })).toThrow()
     expect(sessionCreateRequestSchema.parse({ cwd: '/w' }).cwd).toBe('/w')
     // The refine's both-sides branch: workspaceId alone passes, workspaceId+cwd rejects.
     expect(sessionCreateRequestSchema.parse({ workspaceId: 'w1', sessionId: 's1' }).sessionId).toBe('s1')
@@ -138,13 +192,13 @@ describe('sessions domain schemas', () => {
     expect(sessionHistoryValueSchema.parse({
       events: [],
       hasMore: false,
-      modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }).hasMore).toBe(false)
     expect(sessionModelsRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
     expect(sessionModelsValueSchema.parse({
-      current: { provider: 'deepseek', model: 'deepseek-v4-flash', reasoningEffort: 'max' },
+      current: { provider: 'deepseek-official', model: 'deepseek-v4-flash', reasoningEffort: 'max' },
       groups: [{
-        id: 'deepseek',
+        id: 'deepseek-official',
         name: 'DeepSeek',
         models: [{
           id: 'deepseek-v4-flash',
@@ -164,12 +218,12 @@ describe('sessions domain schemas', () => {
     }).groups[0]?.models[0]?.id).toBe('deepseek-v4-flash')
     expect(sessionSelectModelRequestSchema.parse({
       sessionId: 's1',
-      provider: 'deepseek',
+      provider: 'deepseek-official',
       model: 'deepseek-v4-pro',
       reasoningEffort: 'max',
     }).reasoningEffort).toBe('max')
     expect(sessionSelectModelValueSchema.parse({
-      selected: { provider: 'deepseek', model: 'deepseek-v4-pro', reasoningEffort: 'max' },
+      selected: { provider: 'deepseek-official', model: 'deepseek-v4-pro', reasoningEffort: 'max' },
     }).selected.reasoningEffort).toBe('max')
     expect(() => sessionSelectModelRequestSchema.parse({
       sessionId: 's1',
@@ -178,14 +232,14 @@ describe('sessions domain schemas', () => {
     })).toThrow()
     expect(() => sessionSelectModelRequestSchema.parse({
       sessionId: 's1',
-      provider: 'deepseek',
+      provider: 'deepseek-official',
       model: 'm',
       reasoningEffort: '',
     })).toThrow()
     expect(() => sessionModelsValueSchema.parse({
-      current: { provider: 'deepseek', model: 'm' },
+      current: { provider: 'deepseek-official', model: 'm' },
       groups: [{
-        id: 'deepseek',
+        id: 'deepseek-official',
         name: 'DeepSeek',
         models: [{ id: 'm', name: 'M', reasoning: { efforts: [] } }],
       }],
@@ -195,8 +249,25 @@ describe('sessions domain schemas', () => {
     expect(prompt.mode).toBe('queue')
     expect(() => sessionPromptRequestSchema.parse({ sessionId: 's1', mode: 'inject', content: [] })).toThrow()
     expect(sessionPromptValueSchema.parse({ accepted: true }).accepted).toBe(true)
+    // The command slot appears only when the prompt dispatched a slash command.
+    const dispatched = sessionPromptValueSchema.parse({ accepted: true, command: { kind: 'success', text: 'Goal set' } })
+    expect(dispatched.command?.text).toBe('Goal set')
+    expect(sessionPromptValueSchema.parse({ accepted: true, command: { kind: 'success' } }).command).toEqual({ kind: 'success' })
+    expect(() => sessionPromptValueSchema.parse({ accepted: true, command: { kind: 'failure' } })).toThrow()
     expect(sessionCancelRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
+    expect(sessionUpdateQueueRequestSchema.parse({
+      sessionId: 's1',
+      itemId: 'i1',
+      action: { kind: 'edit', content: [{ type: 'text', text: 'next' }] },
+    }).action.kind).toBe('edit')
+    expect(sessionUpdateQueueRequestSchema.parse({
+      sessionId: 's1', itemId: 'i1', action: { kind: 'remove' },
+    }).action.kind).toBe('remove')
+    expect(() => sessionUpdateQueueRequestSchema.parse({
+      sessionId: 's1', itemId: 'i1', action: { kind: 'promote' },
+    })).toThrow()
     expect(sessionCancelValueSchema.parse({ accepted: true }).accepted).toBe(true)
+    expect(sessionUpdateQueueValueSchema.parse({ accepted: true }).accepted).toBe(true)
     expect(contentBlockSchema.parse({ type: 'text', text: 'x', extra: 1 })).toMatchObject({ extra: 1 })
   })
 })
@@ -208,6 +279,26 @@ describe('host domain schemas', () => {
     expect(value.attachedSessions).toBe(2)
     expect(hostDescribeValueSchema.parse({ version: '1', cwd: '/x', attachedSessions: 0 }).provider).toBeUndefined()
   })
+
+  it('validates the browse listing/creation payloads', () => {
+    expect(hostListDirectoryRequestSchema.parse({})).toEqual({})
+    expect(hostListDirectoryRequestSchema.parse({ path: '/x' })).toEqual({ path: '/x' })
+    const listing = hostListDirectoryValueSchema.parse({
+      path: '/home/u/p',
+      home: '/home/u',
+      crumbs: [{ name: '/', path: '/', hidden: false }, { name: 'p', path: '/home/u/p', hidden: false }],
+      entries: [{ name: '.dot', path: '/home/u/p/.dot', hidden: true }],
+      truncated: false,
+    })
+    expect(listing.entries[0]?.hidden).toBe(true)
+    // The flag is part of the wire value, not an optional decoration.
+    expect(() => hostListDirectoryValueSchema.parse({ path: '/x', home: '/x', crumbs: [], entries: [] })).toThrow()
+    expect(hostCreateDirectoryRequestSchema.parse({ path: '/x', name: 'new' })).toEqual({ path: '/x', name: 'new' })
+    for (const name of ['', ' ', '.', '..', 'a/b', 'a\\b']) {
+      expect(() => hostCreateDirectoryRequestSchema.parse({ path: '/x', name })).toThrow()
+    }
+    expect(hostCreateDirectoryValueSchema.parse({ path: '/x/new' })).toEqual({ path: '/x/new' })
+  })
 })
 
 describe('workspace domain schemas', () => {
@@ -222,7 +313,16 @@ describe('workspace domain schemas', () => {
     expect(workspaceViewSchema.parse(view).sessionIds).toEqual(['s1'])
     expect(() => workspaceViewSchema.parse({ ...view, sessionIds: 's1' })).toThrow()
     expect(workspaceListRequestSchema.parse({})).toEqual({})
-    expect(workspaceListValueSchema.parse({ items: [view] }).items).toHaveLength(1)
+    expect(workspaceListValueSchema.parse({ items: [view], archivedSessionIds: ['s1'] }).items).toHaveLength(1)
+    expect(() => workspaceListValueSchema.parse({ items: [view] })).toThrow()
+  })
+
+  it('archiveSession request/value carry the id and the full updated set', () => {
+    expect(workspaceArchiveSessionRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
+    expect(() => workspaceArchiveSessionRequestSchema.parse({})).toThrow()
+    expect(workspaceArchiveSessionValueSchema.parse({ archivedSessionIds: ['s1', 's2'] }).archivedSessionIds)
+      .toEqual(['s1', 's2'])
+    expect(() => workspaceArchiveSessionValueSchema.parse({ archivedSessionIds: 's1' })).toThrow()
   })
 
   it('create requires exactly one of path/name (both refine arms)', () => {
@@ -276,10 +376,13 @@ describe('commands domain schemas', () => {
     expect(() => commandExecuteRequestSchema.parse({ line: '/compact' })).toThrow()
     expect(() => commandExecuteRequestSchema.parse({ sessionId: 's1' })).toThrow()
     expect(commandExecuteValueSchema.parse({ matched: false })).toEqual({ matched: false })
-    const matched = commandExecuteValueSchema.parse({ matched: true, result: { kind: 'success', text: 'done' } })
-    expect(matched.result?.kind).toBe('success')
-    expect(commandExecuteValueSchema.parse({ matched: true, result: { kind: 'error', text: 'bad' } }).result?.kind).toBe('error')
-    expect(() => commandExecuteValueSchema.parse({ matched: true, result: { kind: 'other' } })).toThrow()
+    // Pure admission: matched plus the optional lifecycle pairing id
+    // (outcomes ride the logged lifecycle events, never this response).
+    expect(commandExecuteValueSchema.parse({ matched: true, commandId: 'cmd-1' }))
+      .toEqual({ matched: true, commandId: 'cmd-1' })
+    expect(commandExecuteValueSchema.parse({ matched: true })).toEqual({ matched: true })
+    expect(() => commandExecuteValueSchema.parse({ matched: true, commandId: '' })).toThrow()
+    expect(() => commandExecuteValueSchema.parse({})).toThrow()
   })
 })
 
@@ -299,28 +402,36 @@ describe('skills domain schemas', () => {
   })
 })
 
+describe('goals domain schemas', () => {
+  it('requires at least one replacement field for goal.edit', () => {
+    const ref = { id: 'g1', revision: 1 }
+    expect(goalEditRequestSchema.parse({ sessionId: 's1', ref, objective: 'updated' }).objective).toBe('updated')
+    expect(goalEditRequestSchema.parse({ sessionId: 's1', ref, maxGoalRounds: 3 }).maxGoalRounds).toBe(3)
+    expect(() => goalEditRequestSchema.parse({ sessionId: 's1', ref })).toThrow()
+  })
+})
+
 describe('events frame schemas', () => {
   it('accepts every mux frame branch', () => {
     const frames = [
       { type: 'session/event', sessionId: 's', event: { type: 't', seq: 0, time: 1, data: null } },
       { type: 'session/subscribed', sessionId: 's', lastSeq: -1 },
-      { type: 'session/title', sessionId: 's', title: 'Durable title', eventSeq: 2, updatedAt: 3 },
       { type: 'approval/requested', sessionId: 's', approvalId: 'a', toolName: 'bash', callId: 'c', reason: 'r' },
       { type: 'approval/resolved', sessionId: 's', approvalId: 'a', outcome: 'allowed-once' },
       { type: 'question/requested', sessionId: 's', questions: [{ id: 'q', question: 'Q?', options: [{ label: 'L' }], multiSelect: true }] },
       { type: 'question/resolved', sessionId: 's', questionRpcId: 'r', outcome: 'answered' },
-      { type: 'session/queued', sessionId: 's', content: [{ type: 'text', text: 'queued prompt' }], source: { kind: 'user', rpcId: 'r9' }, steering: false },
-      { type: 'session/queued', sessionId: 's', content: [{ type: 'text', text: 'steer' }], source: { kind: 'user' }, steering: true },
+      { type: 'session/queue', sessionId: 's', items: [
+        { id: 'i1', message: { id: 'm1', role: 'user', content: [{ type: 'text', text: 'queued prompt' }], source: { kind: 'user', rpcId: 'r9' } } },
+      ] },
+      { type: 'session/projection', sessionId: 's', key: 'todos', value: [{ content: 'x', status: 'pending' }], seq: 7 },
       { type: 'stream/error', error: { code: 'internal', message: 'm', details: {} } },
     ]
     for (const frame of frames) expect(muxFrameSchema.parse(frame)).toMatchObject({ type: frame.type })
     expect(() => muxFrameSchema.parse({ type: 'unknown/frame' })).toThrow()
     for (const invalid of [
-      { type: 'session/title', sessionId: 's', title: '', eventSeq: 0, updatedAt: 1 },
-      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: -1, updatedAt: 1 },
-      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: 0.5, updatedAt: 1 },
-      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: 0, updatedAt: 'now' },
-      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: 0, updatedAt: Number.NaN },
+      { type: 'session/projection', sessionId: 's', key: '', value: null, seq: 0 },
+      { type: 'session/projection', sessionId: 's', key: 'todos', value: null, seq: -1 },
+      { type: 'session/projection', sessionId: 's', key: 'todos', value: null, seq: 0.5 },
     ]) expect(() => muxFrameSchema.parse(invalid)).toThrow()
     expect(askUserQuestionItemSchema.parse({ id: 'q', question: 'Q?' }).id).toBe('q')
   })
@@ -329,10 +440,21 @@ describe('events frame schemas', () => {
     expect(() => muxFrameSchema.parse({ type: 'question/requested', sessionId: 's', questions: [] })).toThrow()
   })
 
-  it('rejects a queued frame missing its members', () => {
-    expect(() => muxFrameSchema.parse({ type: 'session/queued', sessionId: 's', content: 'x', source: { kind: 'user' } })).toThrow()
-    expect(() => muxFrameSchema.parse({ type: 'session/queued', sessionId: 's', content: [], source: { kind: 'user' } })).toThrow()
-    expect(() => muxFrameSchema.parse({ type: 'session/queued', sessionId: 's', content: [], source: {}, steering: false })).toThrow()
+  it('carries a question presentation intent through, and rejects an unknown one', () => {
+    const intent = { kind: 'plan-review', approve: 'Approve' }
+    expect(askUserQuestionItemSchema.parse({
+      id: 'plan-review', question: 'Approve?', detail: '# Plan', options: [{ label: 'Approve' }], intent,
+    }).intent).toEqual(intent)
+    // An unrecognised tag is a rejected frame, not a silently generic render.
+    for (const invalid of [{ kind: 'plan-review' }, { kind: 'poll', approve: 'Approve' }, { approve: 'Approve' }]) {
+      expect(() => askUserQuestionItemSchema.parse({ id: 'q', question: 'Q?', intent: invalid })).toThrow()
+    }
+  })
+
+  it('rejects a queue snapshot with malformed items', () => {
+    expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: 'x' })).toThrow()
+    expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: [{ id: '', message: {} }] })).toThrow()
+    expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: [{ id: 'i', message: { id: 'm', role: 'user', content: [], source: {} } }] })).toThrow()
   })
 
   it('accepts every host frame branch', () => {

packages/host/apiproxy/tsconfig.json

@@ -8,6 +8,15 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../goal/goal"
+    },
+    {
+      "path": "../../settings/settings"
+    },
+    {
+      "path": "../../credentials/credentials"
+    },
     {
       "path": "../../../vendor/cordis"
     },
@@ -32,6 +41,15 @@
     {
       "path": "../../session-persistence/session-persistence"
     },
+    {
+      "path": "../../session-projection/session-projection"
+    },
+    {
+      "path": "../../session-projection/session-projection-cache"
+    },
+    {
+      "path": "../../session-query/session-query"
+    },
     {
       "path": "../../session-title/session-title"
     },
@@ -50,8 +68,14 @@
     {
       "path": "../../workspace/workspace"
     },
+    {
+      "path": "../directory-picker"
+    },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../util/native-command"
     }
   ]
 }

packages/host/directory-picker-auto/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/host/directory-picker-auto/README.md
+README.md: 10d1784590b79fdfef3cf6683d389182cd8437b6
+README.zh.md: 86ec9f2c3a87557e86038ce7d3f89887c5bb3546

packages/host/directory-picker-auto/README.md

@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-host-directory-picker-auto
+
+English | [中文](README.zh.md)
+
+The **adaptive chooser** of the [directory-picker seam](../directory-picker/README.md): a node-half-only plugin that resolves the host's situation once at boot and mounts the matching dual-face backend — [`-native`](../directory-picker-native/README.md) or [`-browse`](../directory-picker-browse/README.md) — as a real Loader entry in the in-memory root tree (never persisted to a config file; the root tree's `write()` is a no-op). Because the backend arrives as an ordinary entry, its browser half is discovered by the client module table exactly as a config-row's would be, so the seam's one-row-swaps-both-faces invariant holds for the resolved choice. Unloading the chooser removes the entry again, unloading both faces with it.
+
+Resolution is one pure boot-time sample (`resolveDirectoryPickerBackend`), exported for reuse and tests. `native` requires every signal that the operator can see the host display and the native backend can serve it: a loopback-only bind (read from the injected `httpServer`; an all-interfaces bind admits remote browsers no OS chooser can reach), no SSH launch (`SSH_CONNECTION`/`SSH_TTY` unset or blank — under SSH port-forwarding the chooser would open on the unattended server), and a servable display session — assumed on darwin/win32; on linux `DISPLAY`/`WAYLAND_DISPLAY` plus a zenity or kdialog binary on `PATH` (the probe is one more boot-time fact); never on any other platform, since the native backend drives exactly darwin/win32/linux. Anything ambiguous resolves to `browse`, which works everywhere. The sample happens exactly once per boot so the mounted capability stays stable for the service lifetime, as the seam requires. Pinning an interaction is not a config field here — compose the `-native` or `-browse` row directly instead of this one, the seam's documented swap point; mounting the chooser **and** a backend row together fails loud (duplicate `directoryPicker` service, duplicate client flow in the `single` holes).
+
+## Model Experience
+
+None, as the chooser only composes the GUI host's directory selection; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Detection infers operator location from launch context, which no launch-side signal can prove** — a tmux session detached from its SSH launch loses the `SSH_*` markers; a darwin process outside an Aqua session still counts as displayed; and the `ssh -L` shape (a workstation-local launch later reached through a forwarded port, which arrives from `127.0.0.1`) resolves `native` and opens the chooser on the unattended workstation. A wrong `native` choice degrades to the backend's existing retryable failure dialog, and composing `-browse` directly pins the safe interaction for such deployments.
+- **The Linux chooser probe reads `PATH` only** — a zenity/kdialog reachable some other way (shell alias, non-PATH install) still resolves `browse`; installing either binary on `PATH` restores `native` eligibility at the next boot.
+- **Boot-time only** — one resolution serves every client of the boot; per-connection adaptivity (native for a local browser, browse for a remote one, same server) would need a per-client capability and the wire advertisement the seam deliberately deleted, and waits for a deployment that serves both at once.

packages/host/directory-picker-auto/README.zh.md

@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-host-directory-picker-auto
+
+[English](README.md) | 中文
+
+[目录选择 seam](../directory-picker/README.md) 的**自适应选择器**：一个只有 node 半侧的插件，在启动时一次性判定宿主处境，并把匹配的双面后端——[`-native`](../directory-picker-native/README.md) 或 [`-browse`](../directory-picker-browse/README.md)——作为真实的 Loader 条目挂进内存根树（绝不持久化到配置文件；根树的 `write()` 是 no-op）。由于后端以普通条目的形式到达，其 browser half 被 client 模块表发现的方式与配置行完全相同，因此对判定出的选择，seam 的“一行同时换两面”不变式依然成立。卸载该选择器会再次移除该条目，连同两面一起卸载。
+
+判定是一次纯函数的启动时采样（`resolveDirectoryPickerBackend`），已导出供复用与测试。`native` 要求“操作者看得到宿主屏幕、且 native 后端能服务它”的全部信号：仅回环的绑定（从注入的 `httpServer` 读取；全网卡绑定会接入任何 OS 选择器都触及不到的远程浏览器）；非 SSH 启动（`SSH_CONNECTION`／`SSH_TTY` 未设置或为空——SSH 端口转发下选择器会弹在无人值守的服务器上）；以及可服务的显示会话——darwin／win32 上视为存在；linux 上要求 `DISPLAY`／`WAYLAND_DISPLAY`，外加 `PATH` 上有 zenity 或 kdialog 二进制（该探查是又一项启动时事实）；其余任何平台上都不成立，因为 native 后端驱动的平台恰为 darwin／win32／linux。任何含糊情形都判定为处处可用的 `browse`。采样每次启动恰好发生一次，因此挂载的能力在服务生命周期内保持稳定，符合 seam 的要求。固定某种交互在这里不是配置字段——直接组合 `-native` 或 `-browse` 行来替代本行，那才是 seam 文档化的切换点；同时挂载选择器**和**某个后端行会大声失败（重复的 `directoryPicker` 服务、`single` 洞中的重复 client 流程）。
+
+## 模型体验
+
+无。该选择器仅组合 GUI 宿主的目录选择；这里没有任何内容进入模型请求。
+
+#### KV 缓存影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+- **探测是从启动上下文推断操作者位置，而任何启动侧信号都无法证明这一点**——从 SSH 启动中脱离的 tmux 会话会丢失 `SSH_*` 标记；Aqua 会话之外的 darwin 进程仍被算作有显示；而 `ssh -L` 形态（在工作站本地启动、之后经转发端口访问，从 `127.0.0.1` 到达）会判定 `native`，把选择器弹在无人值守的工作站上。错误的 `native` 选择会退化为后端既有的可重试失败对话框，而对这类部署，直接组合 `-browse` 即固定住安全的交互。
+- **Linux 选择器探查只读 `PATH`**——以其他途径可用的 zenity／kdialog（shell 别名、未装在 PATH 上）仍判定为 `browse`；把任一二进制装到 `PATH` 上，下次启动即恢复 `native` 资格。
+- **仅在启动时判定**——一次判定服务本次启动的所有客户端；按连接自适应（同一台服务器，本地浏览器用 native、远程浏览器用 browse）需要按客户端的能力对象以及 seam 有意删除的 wire 广播，等到出现同时服务两种形态的部署再做。

packages/host/directory-picker-auto/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@deepseek-ai/dsh-host-directory-picker-auto",
+  "description": "Adaptive chooser of the directory-picker seam: resolves the host situation at boot and mounts the native or browse backend for the DeepSeek Harness web GUI host",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/dsh-host-directory-picker-browse": "^0.0.1",
+    "@deepseek-ai/dsh-host-directory-picker-native": "^0.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-include": "workspace:^",
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker-browse": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker-native": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/host/directory-picker-auto/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Adaptive chooser of the directory-picker seam: resolves the host's
+ * situation once at boot (bind host, SSH launch, display session, Linux
+ * chooser binary) and mounts the matching dual-face backend — `-native` or
+ * `-browse` — as a real Loader entry in the in-memory root tree. Because the
+ * backend arrives as an ordinary entry, its browser half is discovered
+ * exactly as a config-row's would be, so the seam's one-row-swaps-both-faces
+ * invariant holds for the resolved choice; pinning an interaction remains
+ * composing that backend row directly instead of this one.
+ * @module @deepseek-ai/dsh-host-directory-picker-auto
+ */
+
+import type { Context } from 'cordis'
+// Empty type imports carry the `loader` and `httpServer` Context merges for the reads below.
+import type {} from '@cordisjs/plugin-loader'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import { canExecute, hasLinuxChooserBinary } from './probe.ts'
+import type { DirectoryPickerBackendKind } from './resolve.ts'
+import { resolveDirectoryPickerBackend } from './resolve.ts'
+
+export { canExecute, hasLinuxChooserBinary } from './probe.ts'
+export type { DirectoryPickerBackendKind, DirectoryPickerEnv, DirectoryPickerHostFacts } from './resolve.ts'
+export { resolveDirectoryPickerBackend } from './resolve.ts'
+
+/** Cordis plugin name. */
+export const name = 'directory-picker-auto'
+/** Required services: the effective bind host (`httpServer`) and the entry tree the backend mounts into (`loader`). */
+export const inject = ['httpServer', 'loader']
+
+/**
+ * Backend package per resolved kind — fixed composition vocabulary, not a
+ * tunable. Exported because the reference is a runtime string the static
+ * config gate cannot see in a yml row: `verify-cordis-config` requires every
+ * app composing this chooser to declare both values as dependencies.
+ */
+export const BACKEND_PACKAGES: Record<DirectoryPickerBackendKind, string> = {
+  native: '@deepseek-ai/dsh-host-directory-picker-native',
+  browse: '@deepseek-ai/dsh-host-directory-picker-browse',
+}
+
+/**
+ * Resolve the backend from one boot-time sample and mount it as a Loader
+ * entry; the effect's disposer removes the entry and joins the backend
+ * fiber's teardown, so unloading this plugin returns only after both faces
+ * of the mounted backend (and their dependents) quiesced.
+ * @param ctx - cordis context carrying the injected `httpServer` and `loader`.
+ */
+export async function apply(ctx: Context): Promise<void> {
+  const backend = resolveDirectoryPickerBackend({
+    bindHost: ctx.httpServer.host,
+    platform: process.platform,
+    env: process.env,
+    linuxChooser: hasLinuxChooserBinary(process.env.PATH, canExecute),
+  })
+  await ctx.effect(async () => {
+    // Root-tree create: the Loader root is in-memory (write() is a no-op), so
+    // the mounted row can never be persisted back into a config file.
+    const id = await ctx.loader.create({ name: BACKEND_PACKAGES[backend] })
+    return async () => {
+      // Tree teardown (group.stop) can have removed the entry already;
+      // nothing is left to unmount or await then.
+      const entry = ctx.loader.store[id]
+      if (entry === undefined) return
+      const fiber = entry.fiber
+      ctx.loader.remove(id)
+      // remove() only starts the fiber's dispose; join it so the chooser's
+      // unload signals completion only after the backend quiesced.
+      await fiber?.dispose()
+    }
+  }, 'directory-picker-auto: backend entry')
+}

packages/host/directory-picker-auto/src/invariant.ts

@@ -0,0 +1,25 @@
+/**
+ * Package-owned invariant companion for the adaptive directory-picker chooser.
+ * @module @deepseek-ai/dsh-host-directory-picker-auto/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-directory-picker-auto'
+
+/** Cordis companion plugin name. */
+export const name = 'host-directory-picker-auto-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: the sole effect is one boot-time Loader-entry mount owned by the plugin fiber; the store is authoritative. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register the adaptive directory-picker invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/host/directory-picker-auto/src/probe.ts

@@ -0,0 +1,44 @@
+/**
+ * PATH probe for the native backend's Linux chooser binaries: one boot-time
+ * sampled fact for the resolver, so an attended Linux host without
+ * zenity/kdialog keeps the working `browse` interaction instead of a backend
+ * whose every pick fails.
+ * @module @deepseek-ai/dsh-host-directory-picker-auto/probe
+ */
+
+import { accessSync, constants } from 'node:fs'
+import { delimiter, join } from 'node:path'
+
+/** The chooser binaries the native backend can drive on Linux (zenity, KDialog fallback). */
+const LINUX_CHOOSER_BINARIES = ['zenity', 'kdialog'] as const
+
+/**
+ * Whether the current process may execute the candidate path.
+ * @param candidate - absolute or PATH-joined file path.
+ * @returns true only for an existing executable file.
+ */
+export function canExecute(candidate: string): boolean {
+  try {
+    accessSync(candidate, constants.X_OK)
+  } catch {
+    // Absent or non-executable candidate — the only signals accessSync(X_OK) emits.
+    return false
+  }
+  return true
+}
+
+/**
+ * Scan a PATH value for one of the native backend's Linux chooser binaries.
+ * @param pathValue - the `PATH` environment value (absent or empty scans nothing).
+ * @param isExecutable - executability predicate ({@link canExecute} in production; injected for deterministic tests).
+ * @returns whether any PATH directory holds an executable chooser binary.
+ */
+export function hasLinuxChooserBinary(pathValue: string | undefined, isExecutable: (candidate: string) => boolean): boolean {
+  for (const dir of (pathValue ?? '').split(delimiter)) {
+    if (dir === '') continue
+    for (const name of LINUX_CHOOSER_BINARIES) {
+      if (isExecutable(join(dir, name))) return true
+    }
+  }
+  return false
+}

packages/host/directory-picker-auto/src/resolve.ts

@@ -0,0 +1,53 @@
+/**
+ * Boot-time backend resolution for the adaptive directory-picker composition:
+ * one pure decision from sampled host facts to a concrete backend kind. The
+ * caller samples exactly once per boot, so the mounted capability stays
+ * stable for the service lifetime as the seam requires.
+ * @module @deepseek-ai/dsh-host-directory-picker-auto/resolve
+ */
+
+import type { Config as HttpServerConfig } from '@deepseek-ai/dsh-host-webserver'
+
+/** Concrete interaction backend the resolver chooses between. */
+export type DirectoryPickerBackendKind = 'native' | 'browse'
+
+/** Environment keys the resolution reads (a `process.env` subset). */
+export type DirectoryPickerEnv = Readonly<
+  Partial<Record<'SSH_CONNECTION' | 'SSH_TTY' | 'DISPLAY' | 'WAYLAND_DISPLAY', string>>
+>
+
+/** Host facts the backend choice is a pure function of, sampled once at boot. */
+export interface DirectoryPickerHostFacts {
+  /** Effective webserver bind host (the schema's closed loopback/all-interfaces union). */
+  bindHost: HttpServerConfig['host']
+  /** Host process platform. */
+  platform: NodeJS.Platform
+  /** Environment sample; SSH marks a remote operator, DISPLAY/WAYLAND_DISPLAY a Linux display. */
+  env: DirectoryPickerEnv
+  /** Whether a Linux chooser binary the native backend can drive (zenity/kdialog) is on PATH; consulted only when `platform` is linux. */
+  linuxChooser: boolean
+}
+
+/** An env value counts only when set and non-blank (an empty export is "unset" by shell convention). */
+const present = (value: string | undefined): boolean => value !== undefined && value !== ''
+
+/**
+ * Resolve which backend serves this boot. `native` requires every signal that
+ * the operator can see the host display and the native backend can serve it:
+ * a loopback-only bind (an all-interfaces bind admits remote browsers no OS
+ * chooser can reach), no SSH launch (under SSH port-forwarding the chooser
+ * would open on the unattended server), and a servable display session —
+ * assumed on darwin/win32, requiring `DISPLAY`/`WAYLAND_DISPLAY` plus a
+ * chooser binary on linux, and never true elsewhere (the native backend
+ * drives exactly darwin/win32/linux). Anything ambiguous resolves to
+ * `browse`, which works everywhere.
+ * @param facts - the sampled host facts.
+ * @returns the backend kind to mount.
+ */
+export function resolveDirectoryPickerBackend(facts: DirectoryPickerHostFacts): DirectoryPickerBackendKind {
+  if (facts.bindHost !== '127.0.0.1') return 'browse'
+  if (present(facts.env.SSH_CONNECTION) || present(facts.env.SSH_TTY)) return 'browse'
+  if (facts.platform === 'darwin' || facts.platform === 'win32') return 'native'
+  if (facts.platform !== 'linux' || !facts.linuxChooser) return 'browse'
+  return present(facts.env.DISPLAY) || present(facts.env.WAYLAND_DISPLAY) ? 'native' : 'browse'
+}

packages/host/directory-picker-auto/tests/loader-composition.spec.ts

@@ -0,0 +1,177 @@
+/**
+ * REAL-composition coverage: a test-only cordis.yml booted through the
+ * vendored Loader mounts the webserver row plus the adaptive chooser, and the
+ * assertions observe the durable outcome — which backend entry the chooser
+ * mounted into the Loader store, the capability the seam then serves, and
+ * that disposing the chooser removes the mounted entry again (HMR safety),
+ * joining the backend's own teardown before the disposer settles.
+ */
+
+import { chmodSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import Include from '@cordisjs/plugin-include'
+import HttpServer from '@deepseek-ai/dsh-host-webserver'
+import type { DirectoryPicker } from '@deepseek-ai/dsh-host-directory-picker'
+import BrowseDirectoryPicker from '@deepseek-ai/dsh-host-directory-picker-browse'
+import NativeDirectoryPicker from '@deepseek-ai/dsh-host-directory-picker-native'
+import * as DirectoryPickerAuto from '../src/index.ts'
+
+const AUTO = '@deepseek-ai/dsh-host-directory-picker-auto'
+const NATIVE = '@deepseek-ai/dsh-host-directory-picker-native'
+const BROWSE = '@deepseek-ai/dsh-host-directory-picker-browse'
+
+let root: string | undefined
+let fakeBin: string | undefined
+let context: Context | undefined
+
+afterEach(async () => {
+  vi.unstubAllEnvs()
+  await context?.fiber.dispose()
+  context = undefined
+  for (const dir of [root, fakeBin]) {
+    // maxRetries absorbs teardown stragglers (e.g. an unawaited fiber's late
+    // file handle) that can otherwise race the recursive scan into ENOTEMPTY.
+    if (dir !== undefined) await rm(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 })
+  }
+  root = undefined
+  fakeBin = undefined
+})
+
+/** Write a dist fixture and a two-row cordis.yml (webserver + chooser), then boot it through the real Loader. */
+async function loadComposition(bindHost: '127.0.0.1' | '0.0.0.0'): Promise<{ ctx: Context; configPath: string }> {
+  root = await mkdtemp(join(tmpdir(), 'dsh-directory-picker-auto-'))
+  const dist = join(root, 'dist')
+  mkdirSync(dist)
+  const distIndex = join(dist, 'index.html')
+  await writeFile(distIndex, '<head></head><body>shell</body>')
+  const configPath = join(root, 'cordis.yml')
+  await writeFile(configPath, [
+    "- name: '@deepseek-ai/dsh-host-webserver'",
+    '  config:',
+    `    host: '${bindHost}'`,
+    '    port: 0',
+    '    portConflict: increment',
+    `    distIndex: '${distIndex}'`,
+    `- name: '${AUTO}'`,
+    '',
+  ].join('\n'))
+
+  context = new Context()
+  context.baseUrl = pathToFileURL(root).href + '/'
+  await context.plugin(Loader)
+  context.loader.builtins.include = Include
+  const modules = new Map<string, unknown>([
+    ['@deepseek-ai/dsh-host-webserver', HttpServer],
+    [AUTO, DirectoryPickerAuto],
+    [NATIVE, NativeDirectoryPicker],
+    [BROWSE, BrowseDirectoryPicker],
+  ])
+  context.loader.internal = {
+    version: 'v2',
+    async import(specifier: string) {
+      if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`)
+      return modules.get(specifier)
+    },
+  } as unknown as NonNullable<typeof context.loader.internal>
+  await context.loader.create({
+    name: 'cordis:include',
+    config: { path: pathToFileURL(configPath).href },
+  })
+  await context.loader.await()
+  return { ctx: context, configPath }
+}
+
+/** Entry names currently present in the loader store (root tree plus subtrees). */
+function entryNames(ctx: Context): string[] {
+  return [...ctx.loader.entries()].map(entry => entry.options.name)
+}
+
+/**
+ * Force every signal of an attended host on any platform: no SSH launch, a
+ * display, and a PATH holding one executable chooser binary so the real
+ * probe resolves identically on hosts with and without zenity/kdialog.
+ */
+function stubAttendedHost(): void {
+  fakeBin = mkdtempSync(join(tmpdir(), 'dsh-picker-bin-'))
+  const zenity = join(fakeBin, 'zenity')
+  writeFileSync(zenity, '#!/bin/sh\n')
+  chmodSync(zenity, 0o755)
+  vi.stubEnv('PATH', fakeBin)
+  vi.stubEnv('SSH_CONNECTION', '')
+  vi.stubEnv('SSH_TTY', '')
+  vi.stubEnv('DISPLAY', ':0')
+}
+
+describe('real Loader composition', () => {
+  // The 60s budget covers this file's static imports (webserver plus both
+  // backend node halves through tsx), which dominate on cold caches; the
+  // Loader itself resolves nothing here — `loader.internal` is a module map.
+  it('mounts the native backend for an attended loopback host and unmounts it on disposal', { timeout: 60_000 }, async () => {
+    stubAttendedHost()
+    const { ctx, configPath } = await loadComposition('127.0.0.1')
+
+    const unloaded = [...ctx.loader.entries()]
+      .filter(entry => entry.fiber === undefined && !entry.disabled)
+      .map(entry => entry.options.name)
+    expect(unloaded).toEqual([])
+    expect(entryNames(ctx)).toContain(NATIVE)
+    expect(entryNames(ctx)).not.toContain(BROWSE)
+    const picker = ctx.get('directoryPicker') as DirectoryPicker
+    expect(picker.capability().kind).toBe('native')
+    // The mounted row lives in the Loader's in-memory root tree only — the
+    // booted config file must never gain the resolved backend row.
+    expect(await readFile(configPath, 'utf8')).not.toContain(NATIVE)
+
+    // HMR safety: disposing the chooser's fiber removes the entry it created,
+    // and the disposer joins the backend's teardown — the service is gone the
+    // moment dispose() settles, with no further loader await.
+    const autoEntry = [...ctx.loader.entries()].find(entry => entry.options.name === AUTO)!
+    await autoEntry.fiber!.dispose()
+    expect(entryNames(ctx)).not.toContain(NATIVE)
+    expect(ctx.get('directoryPicker')).toBeUndefined()
+    // Self-disposing an include-tree entry persists `disabled: true` (loader
+    // behavior, not the chooser's); await that debounced write so it cannot
+    // race the temp-dir removal, and pin that the persisted row is the
+    // chooser itself — the resolved backend still never reaches the file.
+    await expect.poll(async () => await readFile(configPath, 'utf8')).toContain('disabled: true')
+    expect(await readFile(configPath, 'utf8')).not.toContain(NATIVE)
+  })
+
+  it('mounts the browse backend under an SSH launch', { timeout: 60_000 }, async () => {
+    stubAttendedHost()
+    vi.stubEnv('SSH_CONNECTION', '10.0.0.2 55 10.0.0.9 22')
+    const { ctx } = await loadComposition('127.0.0.1')
+
+    expect(entryNames(ctx)).toContain(BROWSE)
+    expect(entryNames(ctx)).not.toContain(NATIVE)
+    const picker = ctx.get('directoryPicker') as DirectoryPicker
+    expect(picker.capability().kind).toBe('browse')
+  })
+
+  it('mounts the browse backend for an all-interfaces bind even on an attended host', { timeout: 60_000 }, async () => {
+    stubAttendedHost()
+    const { ctx } = await loadComposition('0.0.0.0')
+
+    expect(entryNames(ctx)).toContain(BROWSE)
+    expect(entryNames(ctx)).not.toContain(NATIVE)
+  })
+
+  it('tolerates the mounted entry being removed by the tree before the chooser unloads', { timeout: 60_000 }, async () => {
+    stubAttendedHost()
+    const { ctx, configPath } = await loadComposition('127.0.0.1')
+
+    const backendEntry = [...ctx.loader.entries()].find(entry => entry.options.name === NATIVE)!
+    ctx.loader.remove(backendEntry.id)
+    const autoEntry = [...ctx.loader.entries()].find(entry => entry.options.name === AUTO)!
+    await expect(autoEntry.fiber!.dispose()).resolves.not.toThrow()
+    expect(entryNames(ctx)).not.toContain(NATIVE)
+    // Same self-dispose persistence as above: let the write land before teardown.
+    await expect.poll(async () => await readFile(configPath, 'utf8')).toContain('disabled: true')
+  })
+})

packages/host/directory-picker-auto/tests/resolve.spec.ts

@@ -0,0 +1,91 @@
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { delimiter, join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { canExecute, hasLinuxChooserBinary } from '../src/probe.ts'
+import { resolveDirectoryPickerBackend } from '../src/resolve.ts'
+import type { DirectoryPickerHostFacts } from '../src/resolve.ts'
+
+/** Baseline facts that resolve to `native`; each case overrides one signal (darwin never consults `linuxChooser`). */
+const attended: DirectoryPickerHostFacts = {
+  bindHost: '127.0.0.1',
+  platform: 'darwin',
+  env: {},
+  linuxChooser: false,
+}
+
+describe('resolveDirectoryPickerBackend', () => {
+  it('resolves native for a loopback bind on a display platform', () => {
+    expect(resolveDirectoryPickerBackend(attended)).toBe('native')
+    expect(resolveDirectoryPickerBackend({ ...attended, platform: 'win32' })).toBe('native')
+  })
+
+  it('resolves browse for an all-interfaces bind regardless of other signals', () => {
+    expect(resolveDirectoryPickerBackend({ ...attended, bindHost: '0.0.0.0' })).toBe('browse')
+  })
+
+  it('resolves browse under an SSH launch (either env marker)', () => {
+    expect(resolveDirectoryPickerBackend({ ...attended, env: { SSH_CONNECTION: '10.0.0.2 55 10.0.0.9 22' } })).toBe('browse')
+    expect(resolveDirectoryPickerBackend({ ...attended, env: { SSH_TTY: '/dev/pts/3' } })).toBe('browse')
+  })
+
+  it('requires a display session and a chooser binary on linux', () => {
+    const linux: DirectoryPickerHostFacts = { ...attended, platform: 'linux', linuxChooser: true }
+    expect(resolveDirectoryPickerBackend(linux)).toBe('browse')
+    expect(resolveDirectoryPickerBackend({ ...linux, env: { DISPLAY: ':0' } })).toBe('native')
+    expect(resolveDirectoryPickerBackend({ ...linux, env: { WAYLAND_DISPLAY: 'wayland-1' } })).toBe('native')
+    expect(resolveDirectoryPickerBackend({ ...linux, env: { DISPLAY: ':0' }, linuxChooser: false })).toBe('browse')
+  })
+
+  it('resolves browse on platforms the native backend cannot serve, display or not', () => {
+    expect(resolveDirectoryPickerBackend({ ...attended, platform: 'freebsd', env: { DISPLAY: ':0' }, linuxChooser: true })).toBe('browse')
+    expect(resolveDirectoryPickerBackend({ ...attended, platform: 'openbsd', env: { WAYLAND_DISPLAY: 'wayland-1' } })).toBe('browse')
+  })
+
+  it('treats blank env exports as unset', () => {
+    expect(resolveDirectoryPickerBackend({ ...attended, env: { SSH_CONNECTION: '', SSH_TTY: '' } })).toBe('native')
+    expect(resolveDirectoryPickerBackend({
+      ...attended, platform: 'linux', linuxChooser: true, env: { DISPLAY: '', WAYLAND_DISPLAY: '' },
+    })).toBe('browse')
+  })
+})
+
+let probeRoot: string | undefined
+
+afterEach(() => {
+  if (probeRoot !== undefined) rmSync(probeRoot, { recursive: true, force: true })
+  probeRoot = undefined
+})
+
+describe('hasLinuxChooserBinary', () => {
+  it('finds a chooser binary in any PATH segment, skipping empty segments', () => {
+    const seen: string[] = []
+    const path = ['', '/opt/none', '/usr/local/bin'].join(delimiter)
+    const found = hasLinuxChooserBinary(path, (candidate) => {
+      seen.push(candidate)
+      return candidate === join('/usr/local/bin', 'kdialog')
+    })
+    expect(found).toBe(true)
+    expect(seen).toEqual([
+      join('/opt/none', 'zenity'), join('/opt/none', 'kdialog'),
+      join('/usr/local/bin', 'zenity'), join('/usr/local/bin', 'kdialog'),
+    ])
+  })
+
+  it('reports absence when no segment holds a chooser binary', () => {
+    expect(hasLinuxChooserBinary(['/a', '/b'].join(delimiter), () => false)).toBe(false)
+    expect(hasLinuxChooserBinary('', () => true)).toBe(false)
+    expect(hasLinuxChooserBinary(undefined, () => true)).toBe(false)
+  })
+})
+
+describe('canExecute', () => {
+  it('accepts an executable file and rejects an absent one', () => {
+    probeRoot = mkdtempSync(join(tmpdir(), 'dsh-picker-probe-'))
+    const binary = join(probeRoot, 'zenity')
+    writeFileSync(binary, '#!/bin/sh\n')
+    chmodSync(binary, 0o755)
+    expect(canExecute(binary)).toBe(true)
+    expect(canExecute(join(probeRoot, 'kdialog'))).toBe(false)
+  })
+})

packages/host/directory-picker-auto/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../webserver"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/host/directory-picker-browse/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/host/directory-picker-browse/README.md
+README.md: 52b5fe7e89f915be3b50324628e9d5c48f1ef94c
+README.zh.md: 742da39470083887a71ddba4a7c8012f0ce0ea1f

packages/host/directory-picker-browse/README.md

@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-host-directory-picker-browse
+
+English | [中文](README.zh.md)
+
+The **in-app browsing backend** of the [directory-picker seam](../directory-picker/README.md): `BrowseDirectoryPicker` registers `ctx.directoryPicker` with the `browse` capability — one-level directory listing and child-directory creation over Node's stdlib, which already carries the per-OS adaptation. Nothing renders on the host display, so this backend serves remote clients the native backend cannot.
+
+Behavior facts: listings return **directories only**, name-sorted, with symlinks-to-directories followed (broken/cyclic links skipped — the probe `stat` failing means "not enterable") and a host-owned `hidden` flag (POSIX dot convention) left for the client to act on; `crumbs` is the root-to-target ancestor chain, the root crumb labeled by its full path (`/`, `C:\`); an absent `list` path means the host account's home directory. `createDirectory` is non-recursive (a missing parent is a real failure, not a level to invent) and validates the name as a single non-blank segment even when called directly, mirroring the wire schema's fence. Both primitives reject an explicit path that is not fully qualified — relative forms, and on Windows the rooted drive-less forms (`\foo`, `/foo`) and incomplete UNC prefixes (`\\`, `\\server`) that `isAbsolute` accepts — with `directory-unreadable`/`directory-create-failed`, instead of letting `resolve` rebase it under the host process cwd or current drive. One `list` call returns at most `maxEntries` rows (config, default 1000 — the bound GitHub's web UI applies to directory listings), and the level streams through a bounded window so memory stays O(maxEntries) no matter how many children the directory holds: a cut level keeps the name-sorted head, counts hidden rows against the bound, probes only windowed candidates, and reports `truncated: true` so the client can say the level is incomplete (a windowed broken symlink is not backfilled from beyond the window — the eviction already marks the level truncated); window insertion is binary with an O(1) full-window tail rejection, and `list` threads the caller's `AbortSignal` so a disconnect or timeout stops the scan instead of letting it outlive the caller. Failures throw the seam's typed `DirectoryPickerError`. Policy rationale: [the directory-picker capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md).
+
+**Dual-face package**: the browser half (`./client`) fills [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes with the in-app **Select Workspace Directory** dialog (figma `Harness` 813-23126 family — Miller two-column view whose navigations land selection-anchored and quiet: the previous view keeps rendering while a crumb jump or a submitted path is scanned (a "Loading…" pill floats over it only once the scan outlives a 300ms silence window, never shifting the columns), then target and parent legs land as one two-pane frame with the target re-selected as its actual parent-level entry — so stepping back never collapses and no intermediate frame flashes (a parent leg outliving its 200ms wait bound lands the target alone and upgrades in place; a failed or truncated parent leg keeps the single-pane landing; the display root keeps the single wide level); breadcrumb with a click-to-edit path zone whose editor seeds a trailing separator, prefix-filters the listed level from the draft's final segment while typing (case-insensitively, over the listed — possibly truncated — rows only; Enter still navigates by the exact text), and cancels on Escape or when focus leaves the dialog card (window/tab switches and in-card focus moves keep the draft); a fixed-label show-hidden footer toggle over the host's `hidden` flags, with a dot-led typed prefix revealing its matches and the current selection exempt from both filters; nested New-folder dialog), driving `host.listDirectory`/`host.createDirectory` and registering its own locale namespace (`directory-browser`, zh default / en). One cordis.yml row therefore composes both sides of the browse interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind).
+
+## Model Experience
+
+None, as the backend serves the GUI host's directory selection; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Windows hidden attribute is not read** — Node dirents do not expose `FILE_ATTRIBUTE_HIDDEN`, so `hidden` means dot-prefixed on every platform until a native probe is worth its cost.
+- **No drive-root enumeration** — on Windows the ancestry stops at the drive root; crossing drives waits for the browser UI's path-entry affordance rather than an enumeration primitive here.
+- **Whole-filesystem scope** — no per-deployment browse-root restriction; `workspace.create` accepts arbitrary paths today, so a root here would be UX scoping, not a boundary — deferred until a deployment needs it.

packages/host/directory-picker-browse/README.zh.md

@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-host-directory-picker-browse
+
+[English](README.md) | 中文
+
+[目录选择 seam](../directory-picker/README.md) 的**应用内浏览后端**：`BrowseDirectoryPicker` 以 `browse` 能力注册 `ctx.directoryPicker`——基于 Node 标准库（跨 OS 适配本就由它承担）提供单层目录列举与子目录创建。宿主屏幕上不渲染任何东西，因此该后端能服务 native 后端无法触及的远程客户端。
+
+行为事实：列举**只返回目录**、按名称排序，指向目录的符号链接会被跟随（断链／循环链接被跳过——探测 `stat` 失败即"不可进入"），并携带宿主判定的 `hidden` 标志（POSIX 点前缀约定），展示决策留给客户端；`crumbs` 是从根到目标的祖先链，根 crumb 以完整路径标注（`/`、`C:\`）；`list` 不带路径即列举宿主账户的家目录。`createDirectory` 不递归（父目录缺失是真实失败，不是要补造的层级），且即便被直接调用也把名称校验为单个非空段，与协议 schema 的栅栏一致。两个原语都拒绝非完全限定的显式路径——相对形态，以及 Windows 上 `isAbsolute` 会放行的无盘符有根形态（`\foo`、`/foo`）与不完整的 UNC 前缀（`\\`、`\\server`）——报 `directory-unreadable`／`directory-create-failed`，而不是任由 `resolve` 把它重定位到宿主进程 cwd 或当前盘符之下。单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端对目录列举采用的同一上限），且层级以流式方式经过一个有界窗口，无论目录有多少子项内存都保持 O(maxEntries)：被截断的层级保留按名排序的头部、隐藏行计入上限、只探测窗口内候选，并报告 `truncated: true`，供客户端提示层级不完整（窗口内的断链符号链接不会从窗口外回填——发生过驱逐本身已把层级标记为截断）；窗口插入为二分查找、满窗尾部单次比较即拒绝，且 `list` 透传调用方的 `AbortSignal`，断连或超时会停止扫描而不是让它在调用方离开后继续。失败抛出 seam 的类型化 `DirectoryPickerError`。策略依据：[目录选择能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md)。
+
+**双面包**：browser half（`./client`）以应用内 **选择工作区目录** 对话框（figma `Harness` 813-23126 家族——Miller 双列视图，其导航以选中项为锚、安静落地：扫描 crumb 跳转或提交的路径期间，先前视图持续渲染（"Loading…" 胶囊仅在扫描超出 300ms 静默窗口后才浮于其上，绝不挪动各列），随后目标与父层级两程以单个双栏帧落地，目标被重新选中为其在父层级中的实际条目——因此后退绝不塌缩，也没有中间帧闪现（父层级这一程超出其 200ms 等待上限时，目标单独落地，随后就地升级；父层级这一程失败或被截断时保持单栏落地；展示根保持单个宽层级）；带点击即编辑路径区的面包屑，其编辑器预填尾随分隔符、输入时以草稿末段对所列层级做前缀过滤（不区分大小写，且仅作用于已列出、可能被截断的行；Enter 仍按确切文本导航）、按 Escape 或焦点离开对话框卡片即取消（窗口／标签页切换与卡片内焦点移动保留草稿）；基于宿主 `hidden` 标志、标签固定的"显示隐藏"footer 开关，键入以点开头的前缀会显出其匹配项，且当前选中项不受这两种过滤影响；嵌套新建文件夹对话框）填入 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞，驱动 `host.listDirectory`／`host.createDirectory`，并注册自己的 locale 命名空间（`directory-browser`，zh 默认／en）。因此一行 cordis.yml 同时组合浏览交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。
+
+## 模型体验
+
+无。该后端服务于 GUI 宿主的目录选择；这里没有任何内容进入模型请求。
+
+#### KV 缓存影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+- **不读取 Windows 隐藏属性**——Node 的 dirent 不暴露 `FILE_ATTRIBUTE_HIDDEN`，因此在所有平台上 `hidden` 都意味着点前缀，直到原生探测值回其成本为止。
+- **不枚举盘符根**——Windows 上祖先链止于盘符根；跨盘依赖浏览器 UI 的路径输入入口，而不是这里的枚举原语。
+- **全盘可浏览**——没有按部署限定的浏览根；`workspace.create` 今天就接受任意路径，这里的根只会是 UX 范围而非边界——等到有部署需要时再做。

packages/host/directory-picker-browse/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@deepseek-ai/dsh-host-directory-picker-browse",
+  "description": "In-app browsing backend of the directory-picker seam (listing/creation primitives over the host filesystem)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-host-directory-picker": "workspace:^",
+    "clsx": "^2.0.0",
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-locale": "^0.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-workspace": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-workspace": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-ui-workspace",
+      "@deepseek-ai/dsh-client-locale"
+    ],
+    "platform": "web"
+  }
+}

packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css

@@ -0,0 +1,385 @@
+/* Directory-browser dialog (figma 813-23126 family). The shared Modal renders
+ * headless here — mask, card, Escape only — and this module owns the figma
+ * frame: 680×500 card (viewport-clamped; upsized from the figma 600×420),
+ * header (title + crumbs, l3 separator),
+ * the one-or-two-column Miller content, and the bordered footer. */
+
+/* Doubled class beats Modal's own .dialog regardless of stylesheet order. */
+/* Short viewports clamp the card: header/footer are flex-none and the
+ * columns scroll, so shrinking the height keeps Open/Cancel reachable
+ * instead of clipping them below a fixed overlay. */
+.dialog.dialog {
+  width: min(680px, 100%);
+  height: min(500px, calc(100dvh - 32px));
+  padding: 0;
+  gap: 0;
+  /* The Modal card is an l2 surface and the columns below scroll on it:
+   * rebind the scrollbar indirection to the elevation pair here, on the
+   * surface, so it inherits down to whichever descendant scrolls (the
+   * rebinding contract in ui-theme styles/scrollbar.css). */
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
+}
+
+/* Card-scope wrapper hosting the path editor's Escape and focus-leave
+ * observers; display:contents keeps header/content/footer as direct flex
+ * children of the Modal card. */
+.editorScope {
+  display: contents;
+}
+
+/* Header block: pl24 pr14 pt16 pb8, 8px between title row and crumb row. */
+.header {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  flex: none;
+  padding: 16px 14px 8px 24px;
+  border-bottom: 1px solid var(--dsw-alias-border-l3);
+}
+
+.title {
+  display: flex;
+  align-items: flex-end;
+  min-height: 28px;
+  margin: 0;
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 510;
+  color: var(--dsw-alias-label-primary);
+}
+
+.crumbBar {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  min-height: 20px;
+}
+
+/* Deep chains scroll inside the trail (the effect pins the tail into view)
+ * so the edit zone to the right never leaves the bar. */
+/* The Miller columns keep their own row so a status/error line below never
+ * competes with the fixed column widths for horizontal space. */
+/* A narrow viewport shrinks the dialog below two fixed panes; the row
+ * scrolls horizontally (the effect pins the child pane into view) so
+ * descent never hides behind the Modal's clipping. */
+.millerRow {
+  display: flex;
+  align-items: stretch;
+  flex: 1 1 0;
+  min-height: 0;
+  /* 12px of row gap on each side of the divider; the left side reads wider
+   * by the column's trailing 8px scrollbar clearance, which is deliberate —
+   * the thumb needs that room, the right pane's rows do not. */
+  gap: 12px;
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+
+.crumbTrail {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+
+.crumbSeat {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  flex: none;
+  min-width: 0;
+}
+
+.crumb {
+  border: none;
+  background: transparent;
+  padding: 0;
+  max-width: 160px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+}
+
+.crumb:hover {
+  color: var(--dsw-alias-label-primary);
+}
+
+.crumbChevron {
+  flex: none;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* The empty remainder of the bar: invisible, but a real click target that
+ * flips the bar into path-edit mode. */
+.crumbEditZone {
+  flex: 1 0 34px;
+  min-width: 34px;
+  align-self: stretch;
+  border: none;
+  background: transparent;
+  cursor: text;
+}
+
+.pathInput {
+  box-sizing: border-box;
+  flex: 1 1 0;
+  min-width: 0;
+  height: 24px;
+  padding: 0 8px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 8px;
+  outline: none;
+  background: transparent;
+  font-size: 13px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-primary);
+}
+
+/* Miller content: symmetric 16px vertical padding so the divider clears the
+ * header and footer rules evenly; each column scrolls alone (column widths
+ * live at .column). */
+.content {
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 0;
+  min-height: 0;
+  /* Anchors the floating loading pill (.loadingFloat). */
+  position: relative;
+  /* Right inset is slimmer than the left: the trailing column's own 8px
+   * scrollbar clearance makes up the optical difference. */
+  padding: 16px 16px 16px 24px;
+}
+
+/* Columns split the row evenly around the divider (a solo column takes the
+ * whole row); 256px is the floor below which the row scrolls (scrollbar
+ * hidden, the effect pins the child pane into view) instead of squeezing
+ * the panes. */
+.column {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  flex: 1 1 0;
+  min-width: 256px;
+  overflow-y: auto;
+  /* The themed scrollbar occupies the column's edge (styled scrollbars are
+   * classic, gutter-taking ones); the extra clearance keeps the row pills
+   * clear of the thumb. */
+  padding-right: 8px;
+}
+
+.divider {
+  flex: none;
+  width: 1px;
+  background: var(--dsw-alias-border-l3);
+}
+
+.rowSeat {
+  display: flex;
+  flex: none;
+}
+
+.row {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  height: 28px;
+  flex: none;
+  padding: 4px;
+  border: none;
+  border-radius: 6px;
+  background: transparent;
+  text-align: left;
+  cursor: pointer;
+}
+
+.row:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* Selection: pill fill + the open-folder glyph in the info accent. */
+.rowSelected,
+.rowSelected:hover {
+  background: var(--dsw-alias-interactive-bg-active, var(--dsw-alias-interactive-bg-hover));
+}
+
+.rowIcon {
+  flex: none;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.rowIconSelected {
+  flex: none;
+  color: var(--dsw-alias-button-info-fill);
+}
+
+.rowName {
+  flex: 1 1 0;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+}
+
+.rowChevron {
+  flex: none;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.status,
+.error {
+  padding: 4px;
+  /* The loading pill occupies the opposite corner while a stale status stays
+   * visible. Reserve its widest localized footprint so wrapped text cannot
+   * run underneath it on a narrow card. */
+  padding-right: 120px;
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.status {
+  color: var(--dsw-alias-label-secondary);
+}
+
+.error {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+/* The slow-scan indicator floats over the content's bottom-RIGHT corner on
+ * the card background instead of occupying a row: a scan must never shift
+ * the columns' height, and the stale view keeps rendering beneath it (it
+ * only appears at all once a scan outlives SLOW_SCAN_DELAY_MS). Right,
+ * not left: the truncated/error status rows flow at the bottom LEFT and
+ * stay on screen through a scan, with their reserved right padding keeping
+ * both legible even on a narrow card. After .status in the cascade — the
+ * element carries both classes and this padding must win the
+ * same-specificity race. */
+.loadingFloat {
+  position: absolute;
+  right: 16px;
+  bottom: 8px;
+  padding: 2px 8px;
+  background: var(--dsw-alias-bg-layer-2);
+}
+
+/* Footer: l3 separator on top, symmetric padding so the row sits vertically
+ * centered in the bar; New-folder and the show-hidden toggle pin left. */
+.footerBar {
+  display: flex;
+  align-items: center;
+  /* Narrow viewports wrap the confirm/cancel pair onto their own row
+   * instead of clipping Open past the card's hidden overflow. */
+  flex-wrap: wrap;
+  gap: 8px;
+  flex: none;
+  padding: 16px 24px;
+  border-top: 1px solid var(--dsw-alias-border-l3);
+}
+
+/* Show-hidden toggle: a subtle fixed-label text button left of the gap;
+ * the pressed state seats a check glyph after the label (Menu's selected
+ * vocabulary; trailing so the label never shifts) instead of flipping the
+ * wording. */
+.showHiddenToggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  border: none;
+  background: transparent;
+  padding: 0;
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.showHiddenToggle:hover {
+  color: var(--dsw-alias-label-primary);
+}
+
+.showHiddenToggle:disabled {
+  color: var(--dsw-alias-label-caption);
+  cursor: default;
+}
+
+.showHiddenToggleActive {
+  color: var(--dsw-alias-label-primary);
+}
+
+.footerGap {
+  flex: 1 1 0;
+}
+
+.footerAction {
+  min-width: 72px;
+}
+
+/* Nested create dialog (figma 813:23278): a small centered card. */
+.createDialog.createDialog {
+  width: min(380px, 100%);
+  padding: 0;
+  gap: 0;
+}
+
+.createBody {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 22px 24px 20px;
+}
+
+.createTitle {
+  margin: 0;
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 510;
+  color: var(--dsw-alias-label-primary);
+}
+
+.createIn {
+  margin: 0;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.createInput {
+  box-sizing: border-box;
+  width: 100%;
+  height: 44px;
+  padding: 7px 14px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 22px;
+  outline: none;
+  background: transparent;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.createInput::placeholder {
+  color: var(--dsw-alias-label-caption);
+}
+
+.createActions {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 8px;
+}

packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx

@@ -0,0 +1,836 @@
+/**
+ * The in-app workspace-directory browser (figma Harness 813-23126 family): a
+ * 680×500 dialog (clamped to short/narrow viewports — the Miller row scrolls
+ * sideways, the columns scroll down) whose header carries the title, the selection-path
+ * breadcrumb, and a click-to-edit path zone; below it a Miller view — one
+ * full-width level until a row is selected, then two columns splitting the
+ * row evenly (256px floor; level | selected folder's children) around a
+ * hairline divider. Navigations land selection-anchored and quiet: the
+ * previous view keeps rendering while a crumb jump or a submitted path is
+ * scanned, then target and parent legs land as one two-pane frame (a slow
+ * parent leg falls back to landing the target alone and upgrading in
+ * place), so stepping back keeps two panes away from the display root and
+ * navigation never flashes an intermediate frame. Selecting in the
+ * right column shifts the view one level deeper. "New folder" opens a nested
+ * create dialog targeting the selected folder (or the level itself) and
+ * selects the created folder. Open adopts the selected folder, falling back
+ * to the listed level. Pure consumer of the injected browse calls — the
+ * owning flow decides what "Open" means and owns the workspace-creation
+ * error surface. Hidden entries are host-flagged and hidden by default; the
+ * footer's fixed-label "Show hidden files" toggle (aria-pressed, check when
+ * on) reveals them (client-side only). The path editor opens seeded with a
+ * trailing separator, and while the draft's directory part names a listed
+ * level, its final segment prefix-filters that level's rows (a dot-led
+ * prefix also reveals the hidden entries it names).
+ */
+import { useCallback, useEffect, useRef, useState } from 'react'
+import clsx from 'clsx'
+import {
+  Button, IconCheckOutline16, IconChevronRightOutline14, IconFolderClose16, IconFolderOpen16, IconPlusOutline16, Modal,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { DirectoryEntry, DirectoryListing } from '@deepseek-ai/dsh-client-runtime/client'
+import { DirectoryBrowseError } from '@deepseek-ai/dsh-client-runtime/client'
+import type { Translate } from '@deepseek-ai/dsh-client-locale/client'
+import css from './DirectoryBrowser.module.css'
+
+/** Owner-supplied browser props: browse calls, pick semantics, and copy. */
+export interface DirectoryBrowserProps {
+  /** Dialog visibility (owner-local; closed unmounts nothing but resets on reopen). */
+  open: boolean
+  /** List one directory level (absent path = the Host home directory); the signal aborts a superseded scan on the wire. */
+  listDirectory: (path?: string, signal?: AbortSignal) => Promise<DirectoryListing>
+  /** Create one child directory under an existing parent. */
+  createDirectory: (path: string, name: string) => Promise<string>
+  /** The operator confirmed a directory (the selection, else the listed level). */
+  onOpen: (path: string) => void
+  /** Close without picking (mask, Escape, Cancel). */
+  onClose: () => void
+  /** The owner's confirm is in flight: Open disables, the view freezes. */
+  busy: boolean
+  /** Localized copy. */
+  t: Translate
+}
+
+/** Failure text: the Host business message when typed, else the throw's text. */
+function failureText(error: unknown): string {
+  if (error instanceof DirectoryBrowseError) return error.rpcError.message
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * How long a scan may stay visually silent before the floating "Loading…"
+ * pill appears. The stale view keeps rendering while a scan is in flight, so
+ * a listing that settles inside this window swaps the panes with no
+ * intermediate frame at all; only a genuinely slow host (a network mount, a
+ * cold disk) surfaces the indicator.
+ */
+const SLOW_SCAN_DELAY_MS = 300
+
+/**
+ * How long a navigation landing waits for its parent leg before committing
+ * the target alone. Inside the window both legs land as ONE two-pane frame —
+ * no single-pane flash between them; past it the target commits single-pane
+ * at once (an Enter-submitted navigation is never held hostage by a stalled
+ * parent) and the late parent leg upgrades the landing in place.
+ */
+const PARENT_LEG_WAIT_MS = 200
+
+/**
+ * Breadcrumb rows for display: inside the home subtree the chain starts at a
+ * localized Home crumb; outside it the full ancestry shows, the root labeled
+ * by its own path.
+ */
+function displayCrumbs(listing: DirectoryListing, homeLabel: string): DirectoryEntry[] {
+  const homeIndex = listing.crumbs.findIndex(crumb => crumb.path === listing.home)
+  if (homeIndex === -1) return listing.crumbs
+  const tail = listing.crumbs.slice(homeIndex + 1)
+  return [{ name: homeLabel, path: listing.home, hidden: false }, ...tail]
+}
+
+/**
+ * The listing's platform separator, inferred from the home path the host
+ * stamped — never from typed text or entry paths, where a backslash is a
+ * legal POSIX name character. Still a heuristic at the last step: a POSIX
+ * home directory whose own name contains a backslash would misread.
+ * TODO: replace with a host-stamped `separator` field on the wire
+ * DirectoryListing so the platform fact travels verbatim (the trade-off is
+ * recorded in the directory-picker capability seam Agent Note).
+ */
+function separatorOf(listing: DirectoryListing): '\\' | '/' {
+  return listing.home.includes('\\') ? '\\' : '/'
+}
+
+/**
+ * The path draft's final segment, when its directory part is exactly the
+ * level `listing` lists — the segment the level prefix-filters on while the
+ * user types. Any other draft (no separator yet, or naming some other
+ * directory) leaves the level unfiltered. The directory part compares
+ * exactly (it is the host's own path text, reached by seeding or erasing);
+ * only the name filter downstream is case-insensitive.
+ */
+function draftPrefixFor(listing: DirectoryListing, draft: string | null): string | null {
+  if (draft === null) return null
+  const sep = separatorOf(listing)
+  const cut = draft.lastIndexOf(sep)
+  if (cut === -1) return null
+  const level = listing.path.endsWith(sep) ? listing.path : `${listing.path}${sep}`
+  return draft.slice(0, cut + 1) === level ? draft.slice(cut + 1) : null
+}
+
+/** One column of folder rows (the Miller view renders one or two of these). */
+function LevelColumn({ entries, selectedPath, busy, onPick, showHidden, filterPrefix, pathEditing }: {
+  entries: readonly DirectoryEntry[]
+  selectedPath: string | null
+  busy: boolean
+  onPick: (entry: DirectoryEntry) => void
+  showHidden: boolean
+  filterPrefix: string | null
+  pathEditing: boolean
+}) {
+  const visible = entries.filter((entry) => {
+    // The selection is exempt from both filters: it anchors the two-pane
+    // view (crumbs and the child pane point at it), so neither the hidden
+    // filter after a dot-reveal pick nor a prefix miss may orphan it.
+    if (entry.path === selectedPath) return true
+    if (filterPrefix !== null && !entry.name.toLowerCase().startsWith(filterPrefix.toLowerCase())) return false
+    // A dot-led prefix names hidden entries explicitly, so matching ones
+    // surface even while the toggle keeps the rest hidden.
+    return showHidden || !entry.hidden || filterPrefix?.startsWith('.') === true
+  })
+  return (
+    <div className={css.column} role="list">
+      {visible.map((entry) => {
+        const selected = entry.path === selectedPath
+        return (
+          // The wrapper carries the list semantics; the row keeps its NATIVE
+          // button role so assistive technology exposes an actionable control.
+          <span key={entry.path} role="listitem" className={css.rowSeat}>
+            <button
+              type="button"
+              aria-current={selected || undefined}
+              className={clsx(css.row, selected && css.rowSelected)}
+              disabled={busy}
+              // While the path editor is open, keep focus in it: a focus
+              // steal on mousedown would blur the editor and (in engines
+              // where the blur lands before our guards) drop this click.
+              // Outside editing, rows keep native focus behavior.
+              onMouseDown={pathEditing ? (event) => { event.preventDefault() } : undefined}
+              // Editing-time focus parking happens after commit (the
+              // DirectoryBrowser refocus effect): a right-pane pick replaces
+              // this very column, so focusing the clicked node here would
+              // still fall to body.
+              onClick={() => { onPick(entry) }}
+            >
+              {selected
+                ? <IconFolderOpen16 size={16} className={css.rowIconSelected} />
+                : <IconFolderClose16 size={16} className={css.rowIcon} />}
+              <span className={css.rowName}>{entry.name}</span>
+              <IconChevronRightOutline14 size={12} className={css.rowChevron} />
+            </button>
+          </span>
+        )
+      })}
+    </div>
+  )
+}
+
+/**
+ * Render the directory-browser dialog.
+ * @param props - owner-controlled browser props.
+ * @returns the dialog element (null while closed, via Modal).
+ */
+export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, onClose, busy, t }: DirectoryBrowserProps) {
+  // Miller state: the listed level, the selected row in it, and the selected
+  // folder's own listing (the right column; null while nothing is selected).
+  const [parent, setParent] = useState<DirectoryListing | null>(null)
+  const [selected, setSelected] = useState<DirectoryEntry | null>(null)
+  const [child, setChild] = useState<DirectoryListing | null>(null)
+  const [loading, setLoading] = useState(false)
+  // Derived from `loading` and `scanWindow` by the slow-scan effect below:
+  // true only once the current listing call has been in flight for
+  // SLOW_SCAN_DELAY_MS, so fast listings never render the indicator at all.
+  const [slowScan, setSlowScan] = useState(false)
+  // Every listing call owns a fresh silence window. `loading` may stay true
+  // across a superseding row pick or across a navigation's target and parent
+  // legs, so its boolean edge cannot identify the start of each scan.
+  const [scanWindow, setScanWindow] = useState(0)
+  const [error, setError] = useState<string | null>(null)
+  // Path-edit state: null = breadcrumb mode; a string = the draft being typed.
+  const [pathDraft, setPathDraft] = useState<string | null>(null)
+  // Show-hidden toggle state (pure client-side filter, reset on each open).
+  const [showHidden, setShowHidden] = useState(false)
+  // Create-folder state: null = closed; a string = the nested dialog's draft.
+  const [folderDraft, setFolderDraft] = useState<string | null>(null)
+  const [creatingFolder, setCreatingFolder] = useState(false)
+  const [createError, setCreateError] = useState<string | null>(null)
+  const requestSeq = useRef(0)
+  // The in-flight listing's controller: superseding intent aborts the wire
+  // request too — the Host stops scanning — instead of only discarding the
+  // eventual result while the scan keeps consuming host resources.
+  const scanController = useRef<AbortController | null>(null)
+  // Bumped on every open/close edge: settlements from a previous open (a
+  // pending creation included) must never mutate a reopened dialog.
+  const openGeneration = useRef(0)
+  // Deep ancestry overflows the trail; keep its tail (the current directory
+  // and the edit zone beside it) in view whenever the chain changes.
+  const crumbTrailRef = useRef<HTMLSpanElement | null>(null)
+  // IME confirmation (Enter selecting a candidate) must not submit either
+  // text input; the same guard the workspace-name inputs carry, shared by
+  // the path editor and the folder-name input.
+  const composingRef = useRef(false)
+  // HMR/unmount invalidation: a completion from a disposed flow must not
+  // update state or issue follow-up requests from a dead component.
+  useEffect(() => () => {
+    requestSeq.current += 1
+    openGeneration.current += 1
+    scanController.current?.abort()
+  }, [])
+  const compositionGuard = {
+    onCompositionStart: () => { composingRef.current = true },
+    onCompositionEnd: () => { composingRef.current = false },
+  }
+
+  /** Newer intent wins: invalidate the pending listing's settlement AND abort its wire request. */
+  const supersede = useCallback((): number => {
+    scanController.current?.abort()
+    scanController.current = null
+    return ++requestSeq.current
+  }, [])
+
+  /** Hide any prior indicator and start a fresh silence window for one listing call. */
+  const restartSlowScanWindow = useCallback((): void => {
+    setSlowScan(false)
+    setScanWindow(value => value + 1)
+  }, [])
+
+  /** Launch one listing under a fresh controller so a later supersession can abort it. */
+  const launchListing = useCallback((path: string | undefined): { seq: number; scan: Promise<DirectoryListing> } => {
+    const seq = supersede()
+    const controller = new AbortController()
+    scanController.current = controller
+    restartSlowScanWindow()
+    return { seq, scan: listDirectory(path, controller.signal) }
+  }, [supersede, restartSlowScanWindow, listDirectory])
+
+  /**
+   * Launch a follow-up listing under the CURRENT supersession seq: a newer
+   * intent aborts it like the leg it continues, and it supersedes nothing.
+   */
+  const continueScan = useCallback((path: string): Promise<DirectoryListing> => {
+    const controller = new AbortController()
+    scanController.current = controller
+    restartSlowScanWindow()
+    return listDirectory(path, controller.signal)
+  }, [restartSlowScanWindow, listDirectory])
+
+  /**
+   * Replace the whole view with a freshly navigated level. Away from the
+   * display root — the same collapse the crumb header renders, so crumbs and
+   * pane shape never disagree — the landing is two-pane: the target's ACTUAL
+   * parent-level entry re-selected (left pane = parent, right pane = the
+   * target), so a crumb jump reads as stepping back one pane. Both legs land
+   * as one frame when the parent leg settles within
+   * {@link PARENT_LEG_WAIT_MS}; past that bound (or at the display root) the
+   * target commits alone — single wide level, the editor closes, loading
+   * ends — and a late parent leg still upgrades the landing in place. A
+   * failed parent leg, or a truncated parent window that lacks the target,
+   * leaves the single-pane landing — the upgrade must never orphan the
+   * selection it exists to anchor. Until whichever commit comes first, the
+   * previous view keeps rendering: navigation swaps the panes, it never
+   * blanks them.
+   */
+  const navigate = useCallback((path?: string) => {
+    const { seq, scan } = launchListing(path)
+    setLoading(true)
+    setError(null)
+    scan.then((target) => {
+      if (seq !== requestSeq.current) return
+      // The single-pane landing; `landed` makes it first-commit-only, while
+      // the two-pane commit below may still upgrade an already-landed view.
+      let landed = false
+      const landSingle = (): void => {
+        if (landed || seq !== requestSeq.current) return
+        landed = true
+        setParent(target)
+        setSelected(null)
+        setChild(null)
+        setLoading(false)
+        setPathDraft(null)
+      }
+      // Arity is label-independent: only the collapsed chain's depth decides.
+      if (displayCrumbs(target, '').length < 2) { landSingle(); return }
+      const parentCrumb = target.crumbs.at(-2)
+      /* v8 ignore next -- narrowing: a two-deep display chain implies a parent crumb (root-to-target inclusive). */
+      if (parentCrumb === undefined) { landSingle(); return }
+      continueScan(parentCrumb.path).then((parentLevel) => {
+        if (seq !== requestSeq.current) return
+        // Windows resolves a typed path preserving its case; anchor on the
+        // parent level's actual entry so selection comparisons hold.
+        const sep = separatorOf(parentLevel)
+        const fold = (value: string): string => (sep === '\\' ? value.toLowerCase() : value)
+        const match = parentLevel.entries.find(entry => fold(entry.path) === fold(target.path))
+        if (match === undefined) { landSingle(); return }
+        landed = true
+        setParent(parentLevel)
+        setSelected(match)
+        setChild(target)
+        // Idempotent on a late upgrade of a timed-out landing: reopening the
+        // editor or starting a newer scan supersedes this seq, so reaching
+        // here means the draft is closed and the loading flag is this
+        // navigation's own.
+        setLoading(false)
+        setPathDraft(null)
+      }, () => {
+        // The parent-leg failure (its abort included) never surfaces: the
+        // target listed fine, and nobody asked to see the parent level.
+        landSingle()
+      })
+      window.setTimeout(landSingle, PARENT_LEG_WAIT_MS)
+    }, (reason: unknown) => {
+      if (seq !== requestSeq.current) return
+      setLoading(false)
+      setError(failureText(reason))
+    })
+  }, [launchListing, continueScan])
+
+  // Editor-close focus parking (consumed by the refocus effect below the
+  // miller-row ref): a pick parks on the selection's row, Enter and an
+  // input-focused Escape park on the crumb edit zone that replaces the
+  // input. Pointer-out cancels never set (or clear) these — yanking focus
+  // back from wherever the user clicked would be worse than the fall.
+  const refocusPick = useRef(false)
+  const refocusEditZone = useRef(false)
+  const pathInputRef = useRef<HTMLInputElement | null>(null)
+  const editZoneRef = useRef<HTMLButtonElement | null>(null)
+
+  /**
+   * Select a row of the listed level and preview its children on the right.
+   * Deliberately NOT one-frame like navigate(): a pick's first duty is the
+   * immediate selected state on the clicked row, and the pane split IS that
+   * feedback (aria-current pill, crumbs following the selection) — holding
+   * it back for the child listing would make clicks feel dropped. The quiet
+   * rule governs whole-view replacement, where nothing acknowledges the
+   * click but the swap itself.
+   */
+  const select = useCallback((entry: DirectoryEntry) => {
+    const { seq, scan } = launchListing(entry.path)
+    // A pick while the path editor is open adopts the (filtered) row and
+    // closes the editor — the draft served its purpose. Focus re-parks on
+    // the selection after commit (see the refocus effect below).
+    if (pathDraft !== null) refocusPick.current = true
+    setPathDraft(null)
+    setSelected(entry)
+    setChild(null)
+    setLoading(true)
+    setError(null)
+    scan.then((next) => {
+      if (seq !== requestSeq.current) return
+      setChild(next)
+      setLoading(false)
+    }, (reason: unknown) => {
+      if (seq !== requestSeq.current) return
+      setLoading(false)
+      setError(failureText(reason))
+      // An unreadable selection cannot be the committing target while the
+      // breadcrumb still names the level: fall back to the single pane.
+      setSelected(null)
+      // Clearing the selection can unmount the very row the pick parked
+      // focus on (a dot-revealed hidden row re-hides); the refocus effect
+      // re-parks on the edit zone only if focus actually fell to body.
+      refocusEditZone.current = true
+    })
+  }, [launchListing, pathDraft])
+
+  /** Abandon path editing (Escape or clicking away) and restore the crumb view. */
+  const cancelPathEdit = useCallback(() => {
+    // Cancel also withdraws a navigation the editor already launched: its
+    // late success must not jump to the cancelled path, so the pending
+    // request is superseded and the view leaves the loading state.
+    supersede()
+    setLoading(false)
+    setPathDraft(null)
+    setError(null)
+    // Editing may have superseded the selection's preview request; a
+    // selection with no preview would render a half-empty two-pane view, so
+    // cancel falls back to the single-pane level.
+    if (child === null) setSelected(null)
+    // With no level listed yet (the editor superseded the initial home
+    // listing), plain cancellation would leave a permanently blank picker:
+    // restart the home listing.
+    if (parent === null) navigate()
+  }, [supersede, child, parent, navigate])
+
+  /** A right-column pick advances the view one level: child becomes the level. */
+  const advance = useCallback((entry: DirectoryEntry) => {
+    /* v8 ignore next -- narrowing guard: the right column only renders with a child listing. */
+    if (child === null) return
+    setParent(child)
+    select(entry)
+  }, [child, select])
+
+  // Every open starts fresh at the Host home directory; closing invalidates
+  // any in-flight response so a late arrival cannot repopulate a closed dialog.
+  useEffect(() => {
+    openGeneration.current += 1
+    if (open) {
+      setParent(null)
+      setSelected(null)
+      setChild(null)
+      setCreatingFolder(false)
+      setShowHidden(false)
+      navigate()
+      return
+    }
+    supersede()
+    // Closing mid-scan leaves nothing to load: without this edge the
+    // slow-scan effect keeps arming while hidden and the reopened dialog
+    // would show the indicator on its first frame instead of waiting out a
+    // fresh silence window (reopen's navigate() produces no loading edge).
+    setLoading(false)
+    setError(null)
+    setPathDraft(null)
+    setFolderDraft(null)
+    setCreateError(null)
+    // A close mid-flight (failed Enter, then Cancel) may leave refocus
+    // flags armed; retire them so a later render cannot consume them.
+    refocusPick.current = false
+    refocusEditZone.current = false
+  }, [open, navigate, supersede])
+
+  /** The folder a create or Open acts on: the selection, else the listed level. */
+  const targetPath = selected?.path ?? parent?.path ?? null
+  const targetName = selected?.name
+    ?? (parent === null ? '' : (displayCrumbs(parent, t('browser.home')).at(-1)?.name ?? parent.path))
+
+  const confirmCreate = (): void => {
+    /* v8 ignore next -- reentry fence: the nested dialog only renders with a target and disables while creating. */
+    if (targetPath === null || folderDraft === null || creatingFolder) return
+    // Trim only rejects an all-whitespace draft; the Host gets the original
+    // spelling — the backend accepts any non-blank single segment verbatim,
+    // and trimming here would create (and select) a different sibling.
+    const name = folderDraft
+    if (name.trim() === '') return
+    setCreatingFolder(true)
+    setCreateError(null)
+    const generation = openGeneration.current
+    createDirectory(targetPath, name).then((createdPath) => {
+      // A settlement from a closed (possibly reopened) flow must not touch
+      // the fresh dialog or issue a relist against the stale target.
+      if (generation !== openGeneration.current) return
+      setCreatingFolder(false)
+      setFolderDraft(null)
+      // Land like a right-column pick (figma 802:57446 → 813:23278 flow): the
+      // create target becomes the listed level and the new folder its selection.
+      const { seq, scan } = launchListing(targetPath)
+      setLoading(true)
+      // Symmetric with navigate/select: a launched scan clears the stale
+      // failure text (and keeps the floating indicator's corner the only
+      // occupant of the content's right edge while it shows).
+      setError(null)
+      scan.then((level) => {
+        /* v8 ignore next -- same fence as navigate/select; the modal blocks superseding input */
+        if (seq !== requestSeq.current) return
+        setParent(level)
+        setLoading(false)
+        select({ name, path: createdPath, hidden: false })
+      }, (reason: unknown) => {
+        /* v8 ignore next -- same fence as navigate/select; the modal blocks superseding input */
+        if (seq !== requestSeq.current) return
+        setLoading(false)
+        setError(failureText(reason))
+      })
+    }, (reason: unknown) => {
+      if (generation !== openGeneration.current) return
+      setCreatingFolder(false)
+      setCreateError(failureText(reason))
+    })
+  }
+
+  // The slow-scan gate for the loading indicator: each listing call restarts
+  // the timer even when a superseding scan or a navigation's parent leg keeps
+  // `loading` continuously true. A settle inside its own window means the swap
+  // happened with nothing shown.
+  useEffect(() => {
+    if (!loading) {
+      setSlowScan(false)
+      return
+    }
+    const timer = window.setTimeout(() => { setSlowScan(true) }, SLOW_SCAN_DELAY_MS)
+    return () => { window.clearTimeout(timer) }
+  }, [loading, scanWindow])
+
+  // After the hooks: a closed dialog renders nothing and evaluates no copy.
+  const crumbSource = child ?? parent
+  const crumbs = crumbSource === null ? [] : displayCrumbs(crumbSource, t('browser.home'))
+  const crumbTail = crumbs.at(-1)?.path
+  useEffect(() => {
+    const trail = crumbTrailRef.current
+    if (trail !== null) trail.scrollLeft = trail.scrollWidth
+  }, [crumbTail])
+  // On viewports too narrow for both fixed panes the Miller row scrolls;
+  // whenever a child preview lands, pin it into view the way the crumb tail
+  // pins — otherwise descent is unreachable on a phone-width window.
+  const millerRowRef = useRef<HTMLDivElement | null>(null)
+  const childPath = child?.path
+  useEffect(() => {
+    const row = millerRowRef.current
+    if (row !== null && childPath !== undefined) row.scrollLeft = row.scrollWidth
+  }, [childPath])
+  // Every editor exit that would drop focus to body re-parks it after
+  // commit, so keyboard traversal stays inside the dialog (the Modal has no
+  // focus trap): a pick lands on the selection's row — aria-current in the
+  // freshly rendered left pane, which survives even a right-pane advance
+  // replacing the picked button's column — while Enter and an input-focused
+  // Escape land on the crumb edit zone that replaces the input.
+  useEffect(() => {
+    if (pathDraft !== null) return
+    if (refocusPick.current) {
+      refocusPick.current = false
+      refocusEditZone.current = false
+      const rowHost = millerRowRef.current
+      /* v8 ignore next -- narrowing guard: the miller row is mounted whenever a pick just committed. */
+      if (rowHost === null) return
+      const row = rowHost.querySelector<HTMLButtonElement>('button[aria-current="true"]')
+      /* v8 ignore next -- narrowing guard: the pick that set the flag just rendered its aria-current row. */
+      if (row === null) return
+      row.focus()
+      return
+    }
+    if (refocusEditZone.current) {
+      refocusEditZone.current = false
+      // Re-park only when the close actually dropped focus to body; focus
+      // the user parked elsewhere (a surviving row) stays theirs.
+      if (document.activeElement !== document.body) return
+      const zone = editZoneRef.current
+      /* v8 ignore next -- narrowing guard: crumb mode renders the edit zone whenever the editor just closed. */
+      if (zone === null) return
+      zone.focus()
+    }
+  })
+
+  if (!open) return null
+  const twoPane = selected !== null
+  // The nested create dialog owns the interaction while open: Modal has no
+  // focus trap, so every parent control goes inert (Shift-Tab or AT must not
+  // close, adopt, or retarget underneath the child).
+  const parentInert = busy || folderDraft !== null
+  // An uncommitted path draft makes targetPath stale relative to the header:
+  // committing actions must not act on the previous selection/listing while
+  // a different path is displayed.
+  const draftPending = pathDraft !== null
+
+  return (
+    <Modal
+      open={open}
+      // Escape and mask reach every mounted Modal's document listener; while
+      // the nested create dialog is up only that topmost dialog may close
+      // (its own guard keeps an in-flight creation open), and an in-flight
+      // adoption pins the flow — dismissing it would leave the owner's
+      // createWorkspace to land after an apparent cancel.
+      onClose={() => { if (folderDraft === null && !busy) onClose() }}
+      title={t('browser.title')}
+      className={clsx(css.dialog)}
+      headless
+    >
+      {/* Path-edit cancellation is observed at the card scope, not the
+        * input: once Tab parks focus on a filtered row the input is off the
+        * event path, yet Escape must still collapse the editor (not the
+        * dialog) and a further focus move out of the card must still
+        * cancel. display:contents keeps header/content/footer as direct
+        * flex children of the Modal card. */}
+      <div
+        className={css.editorScope}
+        onKeyDown={(event) => {
+          if (event.key !== 'Escape' || pathDraft === null) return
+          // stopPropagation keeps the card-scope Escape from the Modal's
+          // document listener — the same containment the input previously
+          // provided for itself.
+          event.stopPropagation()
+          // Escape while the input holds focus is about to unmount it; with
+          // focus already parked on a row, that row survives the cancel and
+          // keeps focus naturally. Assignment (not a conditional set) also
+          // retires a stale flag a failed or still-upgrading Enter left.
+          refocusEditZone.current = document.activeElement === pathInputRef.current
+          cancelPathEdit()
+        }}
+        // Focus leaving THIS dialog card while editing cancels like Escape.
+        // Guarded non-cancel paths: window/tab focus loss (document no
+        // longer focused); a focus move that stays inside the card (Tab
+        // onto the filtered rows or the footer toggle); and pointer paths,
+        // where rows and the toggle suppress focus steal on mousedown while
+        // editing so their click lands first. Enter keeps focus in the
+        // input while its navigation is in flight, so a submitted path is
+        // never withdrawn here. Anchored to this card via closest, not any
+        // [role="dialog"], so focus escaping into a sibling overlay cancels.
+        onBlur={(event) => {
+          if (pathDraft === null) return
+          if (!document.hasFocus()) return
+          const card = event.currentTarget.closest('[role="dialog"]')
+          /* v8 ignore next -- narrowing guard: this scope always renders inside the Modal card. */
+          if (card === null) return
+          if (event.relatedTarget instanceof Node && card.contains(event.relatedTarget)) return
+          // The user moved focus out of the card themselves: cancel without
+          // re-parking (a lingering Enter-failure flag must not yank focus
+          // back either).
+          refocusEditZone.current = false
+          cancelPathEdit()
+        }}
+      >
+        <div className={css.header}>
+          <h2 className={css.title}>{t('browser.title')}</h2>
+          <div className={css.crumbBar}>
+            {pathDraft === null
+              ? (
+                <>
+                  <span className={css.crumbTrail} role="navigation" ref={crumbTrailRef}>
+                    {crumbs.map((crumb, index) => (
+                      <span key={crumb.path} className={css.crumbSeat}>
+                        {index > 0 && <IconChevronRightOutline14 size={12} className={css.crumbChevron} />}
+                        <button
+                          type="button"
+                          className={css.crumb}
+                          disabled={parentInert}
+                          onClick={() => { navigate(crumb.path) }}
+                        >
+                          {crumb.name}
+                        </button>
+                      </span>
+                    ))}
+                  </span>
+                  {/* The empty zone right of the crumbs is the path-edit affordance. */}
+                  <button
+                    type="button"
+                    className={css.crumbEditZone}
+                    aria-label={t('browser.editPath')}
+                    // Stays available with no listed level: when the home
+                    // listing itself fails, typing an absolute path is the one
+                    // remaining way forward.
+                    disabled={parentInert}
+                    ref={editZoneRef}
+                    onClick={() => {
+                    // Opening the editor supersedes any pending listing: a
+                    // settlement landing before the first keystroke would
+                    // otherwise close the editor via navigate's draft reset.
+                      supersede()
+                      setLoading(false)
+                      // Seed with a trailing separator so typing immediately
+                      // continues into child names (and prefix-filters below).
+                      // No listed level means nothing to seed from (the editor
+                      // is the recovery path for a failed home listing).
+                      if (parent === null) {
+                        setPathDraft('')
+                        return
+                      }
+                      const base = selected?.path ?? parent.path
+                      const sep = separatorOf(parent)
+                      setPathDraft(base.endsWith(sep) ? base : `${base}${sep}`)
+                    }}
+                  />
+                </>
+              )
+              : (
+                <input
+                  className={css.pathInput}
+                  value={pathDraft}
+                  aria-label={t('browser.editPath')}
+                  autoFocus
+                  ref={pathInputRef}
+                  disabled={parentInert}
+                  onChange={(event) => {
+                  // Editing the draft supersedes any in-flight navigation:
+                  // its completion must neither clear the newer text nor
+                  // repopulate the view with the older path.
+                    supersede()
+                    setLoading(false)
+                    setPathDraft(event.target.value)
+                  }}
+                  {...compositionGuard}
+                  // Escape and focus-leave cancellation live on the card-scope
+                  // wrapper above (they must work after focus Tabs onto the
+                  // rows); this handler owns only submission.
+                  onKeyDown={(event) => {
+                    if (event.key === 'Enter' && !composingRef.current) {
+                      event.preventDefault()
+                      // Trim only detects a blank draft; the Host gets the
+                      // original text — a real directory name may end in
+                      // whitespace, and trimming would list its sibling.
+                      if (pathDraft.trim() !== '') {
+                        // Success will unmount the still-focused input; park
+                        // focus on the returning crumb edit zone (a failure
+                        // keeps the editor, so the flag waits until close).
+                        refocusEditZone.current = true
+                        navigate(pathDraft)
+                      }
+                    }
+                  }}
+                />
+              )}
+          </div>
+        </div>
+        <div className={css.content}>
+          <div className={css.millerRow} ref={millerRowRef}>
+            {parent !== null && (
+              <LevelColumn
+                entries={parent.entries}
+                selectedPath={selected?.path ?? null}
+                busy={parentInert}
+                onPick={select}
+                showHidden={showHidden}
+                filterPrefix={draftPrefixFor(parent, pathDraft)}
+                pathEditing={draftPending}
+              />
+            )}
+            {twoPane && <span className={css.divider} />}
+            {twoPane && child !== null && (
+              <LevelColumn
+                entries={child.entries}
+                selectedPath={null}
+                busy={parentInert}
+                onPick={advance}
+                showHidden={showHidden}
+                filterPrefix={draftPrefixFor(child, pathDraft)}
+                pathEditing={draftPending}
+              />
+            )}
+          </div>
+          {loading && slowScan
+          && <div className={clsx(css.status, css.loadingFloat)} role="status">{t('browser.loading')}</div>}
+          {/* The backend bounds a level at its complete-result limit; say so
+          * whenever a visible pane was cut instead of letting the tail of a
+          * huge directory go silently missing. The note describes the panes
+          * on screen, so an in-flight scan leaves it alone — hiding it while
+          * the stale view still shows the cut level would shift the columns
+          * on every navigation away from it. */}
+          {(parent?.truncated === true || child?.truncated === true)
+          && <div className={css.status} role="status">{t('browser.truncated')}</div>}
+          {error !== null && <div className={css.error} role="alert">{error}</div>}
+        </div>
+        <div className={css.footerBar}>
+          <Button
+            variant="outline"
+            icon={<IconPlusOutline16 size={14} />}
+            disabled={parent === null || loading || parentInert || draftPending}
+            onClick={() => {
+              setFolderDraft('')
+              setCreateError(null)
+            }}
+          >
+            {t('browser.newFolder')}
+          </Button>
+          <button
+            type="button"
+            className={clsx(css.showHiddenToggle, showHidden && css.showHiddenToggleActive)}
+            aria-pressed={showHidden}
+            disabled={parentInert}
+            // The toggle composes with the path editor (dot-led prefixes and
+            // this filter interleave): while editing, don't steal focus, so
+            // toggling never blur-cancels a draft mid-thought. Outside editing
+            // it keeps native focus behavior.
+            onMouseDown={draftPending ? (event) => { event.preventDefault() } : undefined}
+            onClick={() => { setShowHidden(prev => !prev) }}
+          >
+            {t('browser.showHidden')}
+            {/* Trailing check (Menu's selected vocabulary): the label never
+              * shifts when the pressed state toggles. */}
+            {showHidden && <IconCheckOutline16 size={14} />}
+          </button>
+          <span className={css.footerGap} />
+          <Button variant="outline" className={clsx(css.footerAction)} disabled={parentInert} onClick={onClose}>{t('browser.cancel')}</Button>
+          <Button
+            variant="primary"
+            className={clsx(css.footerAction)}
+            disabled={targetPath === null || loading || parentInert || draftPending}
+            /* v8 ignore next -- narrowing guard: Open disables while no target exists. */
+            onClick={() => { if (targetPath !== null) onOpen(targetPath) }}
+          >
+            {t('browser.open')}
+          </Button>
+        </div>
+      </div>
+      {/* Nested create dialog (figma 813:23278): names one folder inside the target. */}
+      <Modal
+        open={folderDraft !== null}
+        onClose={() => { if (!creatingFolder) setFolderDraft(null) }}
+        title={t('browser.newFolder')}
+        className={clsx(css.createDialog)}
+        headless
+      >
+        <div className={css.createBody}>
+          <h3 className={css.createTitle}>{t('browser.newFolder')}</h3>
+          <p className={css.createIn}>{t('browser.createIn', { name: targetName })}</p>
+          <input
+            className={css.createInput}
+            value={folderDraft ?? ''}
+            aria-label={t('browser.folderName')}
+            placeholder={t('browser.untitledFolder')}
+            autoFocus
+            disabled={creatingFolder}
+            onChange={(event) => { setFolderDraft(event.target.value) }}
+            {...compositionGuard}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter' && !composingRef.current) {
+                event.preventDefault()
+                confirmCreate()
+              }
+              if (event.key === 'Escape') {
+                event.stopPropagation()
+                if (!creatingFolder) setFolderDraft(null)
+              }
+            }}
+          />
+          {createError !== null && <div className={css.error} role="alert">{createError}</div>}
+          <div className={css.createActions}>
+            <Button variant="outline" disabled={creatingFolder} onClick={() => { setFolderDraft(null) }}>{t('browser.cancel')}</Button>
+            <Button
+              variant="primary"
+              disabled={creatingFolder || folderDraft === null || folderDraft.trim() === ''}
+              onClick={confirmCreate}
+            >
+              {t('browser.create')}
+            </Button>
+          </div>
+        </div>
+      </Modal>
+    </Modal>
+  )
+}

packages/host/directory-picker-browse/src/client/flow.ts

@@ -0,0 +1,43 @@
+/**
+ * The browse picking occupant (package-internal; the `./client` surface
+ * exposes only the Loader exports). Same-package tests exercise it directly
+ * through this module.
+ */
+import { createElement } from 'react'
+import type { ReactElement } from 'react'
+import type { DirectoryListing } from '@deepseek-ai/dsh-client-runtime/client'
+import type { Translate } from '@deepseek-ai/dsh-client-locale/client'
+// Type-only: the owner contract of the directory-flow holes.
+import type { DirectoryFlowOwnerProps } from '@deepseek-ai/dsh-client-ui-workspace/client'
+import { DirectoryBrowser } from './DirectoryBrowser.tsx'
+
+/** Injected face: the browse wire calls and copy the dialog drives (bound in apply's closure). */
+export interface BrowseFlowInjected {
+  /** List one directory level (absent path = the Host home directory); the signal aborts a superseded scan. */
+  listDirectory: (path?: string, signal?: AbortSignal) => Promise<DirectoryListing>
+  /** Create one child directory under an existing parent. */
+  createDirectory: (path: string, name: string) => Promise<string>
+  /** Localized dialog copy (this package's namespace). */
+  t: Translate
+}
+
+/**
+ * Flow occupant: adapts the hole's owner conversation onto the browser
+ * dialog — a confirmed directory is the picked path, dismissal is the
+ * cancellation. Browse failures (unreadable targets, create conflicts) stay
+ * inside the dialog's own alert surfaces, so the owner's `onError` arm is
+ * never driven by this occupant.
+ * @param props - owner conversation plus the injected browse face.
+ * @returns the dialog element (renders nothing while closed).
+ */
+export function BrowseDirectoryFlow(props: DirectoryFlowOwnerProps & BrowseFlowInjected): ReactElement {
+  return createElement(DirectoryBrowser, {
+    open: props.open,
+    busy: props.busy,
+    listDirectory: props.listDirectory,
+    createDirectory: props.createDirectory,
+    t: props.t,
+    onOpen: props.onPicked,
+    onClose: props.onCancel,
+  })
+}

packages/host/directory-picker-browse/src/client/index.ts

@@ -0,0 +1,93 @@
+/**
+ * Browser half of the browse directory-picker backend: fills ui-workspace's
+ * two directory-flow holes with the in-app Select Workspace Directory dialog
+ * (figma `Harness` 813-23126 family), driving the node half's
+ * `host.listDirectory`/`host.createDirectory` primitives. Mounting this
+ * package therefore composes both sides of the browse interaction with one
+ * cordis.yml row; no client code branches on a capability kind. The dialog's
+ * copy is locale-registered here — the flow package owns its own strings.
+ */
+import { deferGroupRegistration } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: pulls the SlotMap merge declaring the directory-flow holes.
+import type {} from '@deepseek-ai/dsh-client-ui-workspace/client'
+import type { BrowseFlowInjected } from './flow.ts'
+import { BrowseDirectoryFlow } from './flow.ts'
+
+/** Locale namespace owning the browser dialog's copy. */
+const LOCALE_NS = 'directory-browser'
+
+/** Required services (cordis fiber inject): the slot registry, the wire-facing workspace service, and locale. */
+export const inject = ['slots', 'workspaces', 'locale']
+
+/**
+ * Client plugin body: register the dialog's dictionaries and the browse flow
+ * into both directory-flow holes (declaration-aware deferral — the declaring
+ * ui-workspace entries may activate later, and an HMR collapse re-declares).
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => {
+    // The two dictionaries land as a unit: if the second registration hits a
+    // rival owner of the namespace, the first rolls back before the throw —
+    // a failed activation must not squat the namespace's other locale.
+    const disposers: (() => void)[] = []
+    const dictionaries: [locale: string, dict: Record<string, string>][] = [
+      ['zh', {
+        'browser.title': '选择工作区目录',
+        'browser.home': '主目录',
+        'browser.newFolder': '新建文件夹',
+        'browser.folderName': '文件夹名称',
+        'browser.createIn': '在"{name}"中新建文件夹',
+        'browser.untitledFolder': '未命名文件夹',
+        'browser.create': '创建',
+        'browser.cancel': '取消',
+        'browser.open': '打开',
+        'browser.editPath': '编辑路径',
+        'browser.loading': '加载中…',
+        'browser.truncated': '文件夹过多，仅显示开头部分。',
+        'browser.showHidden': '显示隐藏文件',
+      }],
+      ['en', {
+        'browser.title': 'Select Workspace Directory',
+        'browser.home': 'Home',
+        'browser.newFolder': 'New folder',
+        'browser.folderName': 'Folder name',
+        'browser.createIn': 'New folder in "{name}"',
+        'browser.untitledFolder': 'Untitled folder',
+        'browser.create': 'Create',
+        'browser.cancel': 'Cancel',
+        'browser.open': 'Open',
+        'browser.editPath': 'Edit path',
+        'browser.loading': 'Loading…',
+        'browser.truncated': 'Too many folders to list; only the beginning is shown.',
+        'browser.showHidden': 'Show hidden files',
+      }],
+    ]
+    try {
+      for (const [locale, dict] of dictionaries) disposers.push(ctx.locale.register(LOCALE_NS, locale, dict))
+    } catch (error) {
+      for (const dispose of disposers.reverse()) dispose()
+      throw error
+    }
+    return () => { for (const dispose of disposers) dispose() }
+  }, 'directory-picker-browse: dialog dictionaries')
+
+  const injected = (): BrowseFlowInjected => ({
+    listDirectory: (path, signal) => ctx.workspaces.listDirectory(path, signal),
+    createDirectory: (path, name) => ctx.workspaces.createDirectory(path, name),
+    t: ctx.locale.bind(LOCALE_NS),
+  })
+  ctx.effect(() => {
+    // One occupant, both holes, as a unit: construction or late conflicts
+    // (holes declared after rival providers activated) roll the whole pair
+    // back and fail loud — semantics owned by deferGroupRegistration.
+    const group = deferGroupRegistration(
+      ctx.slots,
+      ['conversation.hero.workspace.directoryFlow', 'sidebar.workspaces.directoryFlow'] as const,
+      BrowseDirectoryFlow,
+      name => ctx.slots.register({ name, inject: injected }, BrowseDirectoryFlow),
+    )
+    return () => { group.dispose() }
+  }, 'directory-picker-browse: flow registrations')
+}

packages/host/directory-picker-browse/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'

packages/host/directory-picker-browse/src/index.ts

@@ -0,0 +1,324 @@
+/**
+ * Browse backend of the directory-picker seam: registers `ctx.directoryPicker`
+ * with the `browse` capability — one-level directory listing and child-directory
+ * creation over the host filesystem via Node's stdlib (which already carries
+ * the per-OS adaptation). Nothing renders on the host display, so this backend
+ * serves remote clients the dialog backend cannot. Policy decisions (hidden
+ * entries flagged but returned, symlinks followed, whole-filesystem scope) are
+ * recorded in the directory-picker seam Agent Note.
+ * @module @deepseek-ai/dsh-host-directory-picker-browse
+ */
+
+import { mkdir, opendir, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { basename, dirname, join, posix, resolve, win32 } from 'node:path'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import {
+  DirectoryPicker, DirectoryPickerError,
+} from '@deepseek-ai/dsh-host-directory-picker'
+import type {
+  DirectoryEntry, DirectoryListing, DirectoryPickerCapability,
+} from '@deepseek-ai/dsh-host-directory-picker'
+
+/**
+ * Ancestor chain from the filesystem root to `target` inclusive — the
+ * breadcrumb rows of a listing, every one a jump target.
+ */
+function ancestryCrumbs(target: string): DirectoryEntry[] {
+  const crumbs: DirectoryEntry[] = []
+  let current = target
+  for (;;) {
+    const parent = dirname(current)
+    // basename of a root is '' — label the root crumb by its full path ('/', 'C:\').
+    crumbs.unshift({ name: parent === current ? current : basename(current), path: current, hidden: false })
+    if (parent === current) return crumbs
+    current = parent
+  }
+}
+
+/**
+ * True when the path names one fixed filesystem location regardless of
+ * process state: POSIX-absolute on POSIX; on Windows only drive-qualified
+ * (`C:\…`) or complete UNC (`\\server\share…`) forms. Rooted drive-less
+ * forms (`\foo`, `/foo`) and incomplete UNC prefixes (`\\`, `\\server`)
+ * pass `isAbsolute` yet still resolve against the process's current drive.
+ * @param path - candidate path.
+ * @param platform - replaces `process.platform` for deterministic tests.
+ * @returns whether the path is fully qualified on the platform.
+ */
+export function fullyQualified(path: string, platform: NodeJS.Platform = process.platform): boolean {
+  return platform === 'win32'
+    ? win32.isAbsolute(path) && /^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/]+[^\\/]+)/.test(path)
+    : posix.isAbsolute(path)
+}
+
+/** One streamed listing candidate: the dirent facts a row needs, nothing else retained. */
+export interface ListingCandidate {
+  /** Base name within the streamed level. */
+  name: string
+  /** Dirent says directory (no probe needed). */
+  isDirectory: boolean
+  /** Dirent says symlink (enterability needs a stat probe). */
+  isSymbolicLink: boolean
+}
+
+/**
+ * Insert a streamed candidate into the name-sorted bounded window, evicting
+ * the name-largest candidate when the window exceeds `keep`. Memory over an
+ * arbitrarily large level therefore stays O(keep) regardless of how many
+ * children the directory holds.
+ * @param window - the name-ascending window, mutated in place.
+ * @param candidate - the streamed candidate to place.
+ * @param keep - the window bound.
+ * @returns true when an eviction happened (the level has candidates beyond the window).
+ */
+export function boundedInsert(window: ListingCandidate[], candidate: ListingCandidate, keep: number): boolean {
+  // Full window, name at or beyond the tail: one comparison rejects, so an
+  // oversized level costs O(1) per candidate past the head instead of a
+  // window scan (100k children against a 1,001 window must not approach
+  // 10^8 comparisons).
+  // oxlint-disable-next-line typescript/no-non-null-assertion -- a full window (length === keep >= 1) has a tail
+  if (window.length === keep && candidate.name.localeCompare(window[window.length - 1]!.name) >= 0) return true
+  // Binary insertion keeps a retained candidate at O(log keep) comparisons.
+  let lo = 0
+  let hi = window.length
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1
+    // oxlint-disable-next-line typescript/no-non-null-assertion -- bounded by the loop condition
+    if (candidate.name.localeCompare(window[mid]!.name) < 0) hi = mid
+    else lo = mid + 1
+  }
+  window.splice(lo, 0, candidate)
+  if (window.length <= keep) return false
+  window.pop()
+  return true
+}
+
+/**
+ * Await `operation`, but reject with the signal's reason the moment it
+ * aborts. Node's filesystem reads are not retractable, so the operation
+ * itself keeps running against a handle the caller then closes — its late
+ * settlement is swallowed here so an abandoned read cannot surface as an
+ * unhandled rejection.
+ * @param operation - the in-flight filesystem step.
+ * @param signal - caller lifetime; absent means plain awaiting.
+ * @returns the operation's value.
+ */
+export function raceAbort<T>(operation: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (signal === undefined) return operation
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => {
+      operation.catch(() => {
+        // Abandoned read: its handle is being closed by the aborting caller,
+        // and the abort reason already carried the outcome.
+      })
+      reject(asError(signal.reason))
+    }
+    if (signal.aborted) {
+      onAbort()
+      return
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    operation.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(value)
+      },
+      (reason: unknown) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(asError(reason))
+      },
+    )
+  })
+}
+
+/** The thrown value as an Error (wire/abort reasons may be anything). */
+function asError(reason: unknown): Error {
+  return reason instanceof Error ? reason : new Error(String(reason))
+}
+
+/* v8 ignore start -- a close failure of an abandoned handle has no consumer, and forcing one needs a filesystem torn down mid-request. */
+/** Swallow the close failure of a handle its caller already departed. */
+function swallowCloseFailure(): void {}
+/* v8 ignore stop */
+
+/** Message text of an unknown thrown value. */
+function messageOf(error: unknown): string {
+  /* v8 ignore next -- node:fs rejects with Error instances; the String arm only satisfies the unknown narrowing. */
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * One listing row for a dirent, following symlinks to directories; null for
+ * non-directories and broken/cyclic links (skipped silently — the browser
+ * shows what can be entered, and a broken link cannot).
+ */
+async function directoryRow(
+  parent: string, name: string, isDirectory: boolean, isSymbolicLink: boolean, signal: AbortSignal | undefined,
+): Promise<DirectoryEntry | null> {
+  const path = join(parent, name)
+  let enterable = isDirectory
+  if (!enterable && isSymbolicLink) {
+    try {
+      // The probe races the caller too: a symlink target on a stalled
+      // network filesystem must not keep a departed caller's request alive.
+      enterable = (await raceAbort(stat(path), signal)).isDirectory()
+    } catch {
+      /* v8 ignore next 2 -- an abort landing mid-probe needs a stalled stat; the per-candidate check in list covers the settled path. */
+      if (signal?.aborted) throw asError(signal.reason)
+      // Broken or cyclic symlink: stat is the probe, failure means "not enterable".
+      return null
+    }
+  }
+  if (!enterable) return null
+  // POSIX hidden convention; Windows' hidden attribute is not exposed by
+  // dirents (Known Limitations). The client owns whether hidden rows show.
+  return { name, path, hidden: name.startsWith('.') }
+}
+
+/** Validated plugin configuration. */
+export interface Config {
+  /** Complete-result bound of one listing level; see {@link BrowseDirectoryPicker.Config}. */
+  maxEntries: number
+}
+
+/** The `ctx.directoryPicker` browse implementation (stable capability object per service life). */
+export default class BrowseDirectoryPicker extends DirectoryPicker {
+  /**
+   * `maxEntries` bounds the complete listing level a single `list` call may
+   * materialize and put on the wire: at most this many child-directory rows
+   * (hidden rows included), with `truncated` flagging a cut level. The
+   * default follows GitHub's web UI, which truncates directory listings at
+   * 1,000 entries.
+   */
+  static Config: z<Config> = z.object({
+    maxEntries: z.natural().min(1).default(1000),
+  })
+
+  private readonly browseCapability: DirectoryPickerCapability = {
+    kind: 'browse',
+    list: (path, signal) => this.list(path, signal),
+    createDirectory: (path, name) => this.createDirectory(path, name),
+  }
+
+  constructor(ctx: Context, private readonly config: Config) {
+    super(ctx)
+  }
+
+  /**
+   * The browse interaction capability.
+   * @returns the stable `browse` capability object.
+   */
+  capability(): DirectoryPickerCapability {
+    return this.browseCapability
+  }
+
+  private async list(path?: string, signal?: AbortSignal): Promise<DirectoryListing> {
+    const home = homedir()
+    // The seam contract takes fully qualified paths only; resolve() would
+    // silently rebase a relative or empty wire value under the host process
+    // cwd (or, for rooted drive-less Windows forms, its current drive).
+    if (path !== undefined && !fullyQualified(path)) {
+      throw new DirectoryPickerError('directory-unreadable', path, `cannot list "${path}": not a fully qualified path`)
+    }
+    const target = resolve(path ?? home)
+    // Stream the level (opendir, one dirent at a time) into a name-sorted
+    // window of maxEntries + 1 candidates: memory stays bounded no matter how
+    // many children the directory holds, the window keeps the name-sorted
+    // head, and the +1 slot lets an in-window extra row prove the cut. A
+    // window candidate that turns out non-enterable (broken symlink) is not
+    // backfilled from beyond the window — an eviction already marks the
+    // level truncated, which stays the honest answer.
+    const keep = this.config.maxEntries + 1
+    const window: ListingCandidate[] = []
+    let evicted = false
+    try {
+      // Every filesystem await races the caller's signal: a stalled
+      // opendir/read on a network filesystem must not keep a departed
+      // caller's scan alive, and an already-aborted request rejects even
+      // when the level is empty.
+      const opening = opendir(target)
+      const level = await raceAbort(opening, signal).catch((error: unknown) => {
+        // The abandoned open can still mint a handle after the abort won;
+        // close it so a departed caller cannot leak a descriptor. (A lost
+        // race against opendir's own rejection has nothing to close, and
+        // the close's own failure is swallowed — the request already
+        // returned, so a cleanup error has no consumer.)
+        void opening.then(dir => dir.close().catch(swallowCloseFailure), () => {
+          // Already rejected: raceAbort surfaced or swallowed it.
+        })
+        throw error
+      })
+      try {
+        for (;;) {
+          const dirent = await raceAbort(level.read(), signal)
+          if (dirent === null) break
+          // Only rows a browser could enter contend for the window; dirent
+          // says "directory" outright, a symlink needs the later stat probe.
+          if (!dirent.isDirectory() && !dirent.isSymbolicLink()) continue
+          const candidate = { name: dirent.name, isDirectory: dirent.isDirectory(), isSymbolicLink: dirent.isSymbolicLink() }
+          if (boundedInsert(window, candidate, keep)) evicted = true
+        }
+      } finally {
+        // Manual read() never auto-closes; close on every exit. The aborted
+        // exit must not await it — Node queues close behind any in-flight
+        // read, so awaiting would chain the departed caller back onto the
+        // very stall the abort escaped (the abandoned read's settlement is
+        // already swallowed by raceAbort).
+        const closing = level.close()
+        /* v8 ignore next 3 -- an abort between open and close needs a stalled read; the abandoned-close arm has no observable outcome. */
+        if (signal?.aborted) {
+          closing.catch(swallowCloseFailure)
+        } else {
+          await closing
+        }
+      }
+    } catch (error: unknown) {
+      // An abort is the caller's own reason, not an unreadable directory.
+      signal?.throwIfAborted()
+      throw new DirectoryPickerError('directory-unreadable', target, `cannot list ${target}: ${messageOf(error)}`)
+    }
+    const entries: DirectoryEntry[] = []
+    let truncated = evicted
+    for (const candidate of window) {
+      // A caller that departed between reads and probes stops before the
+      // next probe (each probe's own await is raced inside directoryRow).
+      signal?.throwIfAborted()
+      const row = await directoryRow(target, candidate.name, candidate.isDirectory, candidate.isSymbolicLink, signal)
+      if (row === null) continue
+      if (entries.length === this.config.maxEntries) {
+        truncated = true
+        break
+      }
+      entries.push(row)
+    }
+    return { path: target, home, crumbs: ancestryCrumbs(target), entries, truncated }
+  }
+
+  private async createDirectory(path: string, name: string): Promise<string> {
+    // Same fully-qualified fence as list: never rebase a parent under the
+    // cwd or the current drive.
+    if (!fullyQualified(path)) {
+      throw new DirectoryPickerError('directory-create-failed', path, `cannot create under "${path}": not a fully qualified parent path`)
+    }
+    const parent = resolve(path)
+    // The backend owns segment validation (the wire schema also refuses these,
+    // but direct service consumers must hit the same fence).
+    if (name.trim() === '' || name === '.' || name === '..' || /[/\\]/.test(name)) {
+      throw new DirectoryPickerError('directory-create-failed', join(parent, name), `"${name}" is not a single path segment`)
+    }
+    const target = join(parent, name)
+    try {
+      // Non-recursive: the parent is the directory the browser is showing, so
+      // a missing parent is a real failure, not a level to invent.
+      await mkdir(target)
+      return target
+    } catch (error: unknown) {
+      if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST') {
+        throw new DirectoryPickerError('directory-exists', target, `${target} already exists`)
+      }
+      throw new DirectoryPickerError('directory-create-failed', target, `cannot create ${target}: ${messageOf(error)}`)
+    }
+  }
+}

packages/host/directory-picker-browse/src/invariant.ts

@@ -0,0 +1,25 @@
+/**
+ * Package-owned invariant companion for the browse directory-picker backend.
+ * @module @deepseek-ai/dsh-host-directory-picker-browse/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-directory-picker-browse'
+
+/** Cordis companion plugin name. */
+export const name = 'host-directory-picker-browse-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: each list/create is one stateless filesystem round trip; the filesystem itself is the authoritative state. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register the browse directory-picker invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/host/directory-picker-browse/tests/client-flow.spec.tsx

@@ -0,0 +1,220 @@
+// @vitest-environment jsdom
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { DirectoryListing } from '@deepseek-ai/dsh-client-runtime/client'
+import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
+import { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import type { DirectoryFlowOwnerProps } from '@deepseek-ai/dsh-client-ui-workspace/client'
+import { apply, inject } from '../src/client/index.ts'
+import { BrowseDirectoryFlow } from '../src/client/flow.ts'
+
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
+afterEach(cleanup)
+
+const HOLES = ['conversation.hero.workspace.directoryFlow', 'sidebar.workspaces.directoryFlow'] as const
+
+const HOME = '/home/u'
+const homeListing: DirectoryListing = {
+  path: HOME,
+  home: HOME,
+  crumbs: [{ name: '/', path: '/', hidden: false }, { name: 'u', path: HOME, hidden: false }],
+  entries: [{ name: 'Documents', path: `${HOME}/Documents`, hidden: false }],
+  truncated: false,
+}
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  ctx.provide('locale', new LocaleService(ctx))
+  const listDirectory = vi.fn(async (): Promise<DirectoryListing> => homeListing)
+  const createDirectory = vi.fn(async (path: string, name: string) => `${path}/${name}`)
+  ctx.provide('workspaces', { listDirectory, createDirectory } as never)
+  const slots = ctx.get('slots') as SlotsService
+  const declare = () => slots.register({
+    name: 'root',
+    children: Object.fromEntries(HOLES.map(name => [name, { kind: 'single', scope: 'root' }])),
+  } as never, () => null)
+  return { ctx, slots, listDirectory, createDirectory, declare }
+}
+
+function owner(overrides: Partial<DirectoryFlowOwnerProps> = {}): DirectoryFlowOwnerProps {
+  return {
+    open: true, busy: false,
+    onPicked: vi.fn(), onCancel: vi.fn(), onError: vi.fn(),
+    ...overrides,
+  }
+}
+
+describe('directory-picker-browse client half', () => {
+  it('declares the services it drives', () => {
+    expect(inject).toEqual(['slots', 'workspaces', 'locale'])
+  })
+
+  it('fills both directory-flow holes for declarations before or after apply, and leaves with its fiber', async () => {
+    const before = await bench()
+    before.declare()
+    const fiber = before.ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    for (const hole of HOLES) expect(before.slots.entries(hole)).toHaveLength(1)
+    // Registry-contribution disposal proof: the fiber going down empties the holes.
+    await fiber.dispose()
+    for (const hole of HOLES) expect(before.slots.entries(hole)).toHaveLength(0)
+
+    const after = await bench()
+    await after.ctx.plugin({ inject: [...inject], apply }).await()
+    for (const hole of HOLES) expect(after.slots.entries(hole)).toHaveLength(0)
+    after.declare()
+    await Promise.resolve()
+    for (const hole of HOLES) expect(after.slots.entries(hole)).toHaveLength(1)
+  })
+
+  it('rolls back the first deferral when the second hole is already occupied', async () => {
+    const b = await bench()
+    b.declare()
+    // Foreign occupant in the SECOND registered hole: the pair construction
+    // throws after the first deferral installed its subscription.
+    b.slots.register({ name: HOLES[1] } as never, () => null)
+    const rejections: unknown[] = []
+    const onUnhandled = (reason: unknown): void => { rejections.push(reason) }
+    process.on('unhandledRejection', onUnhandled)
+    try {
+      const fiber = b.ctx.plugin({ inject: [...inject], apply })
+      await expect(fiber.await()).rejects.toThrow(/already has a registration/)
+      // A leaked first deferral would now race this probe registration and
+      // throw from its orphaned subscription against the HERO hole; the
+      // rollback leaves only the activation failure itself (cordis re-raises
+      // the apply throw as a late rejection — installFailLoud's contract).
+      const disposeProbe = b.slots.register({ name: HOLES[0] } as never, () => null)
+      await new Promise(resolve => setTimeout(resolve, 20))
+      expect(rejections.map(String).filter(text => text.includes(HOLES[0]))).toEqual([])
+      disposeProbe()
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+    }
+  })
+
+  it('rolls back wholesale and reports loudly when a rival provider wins after deferred activation', async () => {
+    const b = await bench()
+    const rejections: unknown[] = []
+    const onUnhandled = (reason: unknown): void => { rejections.push(reason) }
+    process.on('unhandledRejection', onUnhandled)
+    process.on('uncaughtException', onUnhandled)
+    try {
+      // This provider activates BEFORE any hole exists: both deferrals wait.
+      await b.ctx.plugin({ inject: [...inject], apply }).await()
+      b.declare()
+      // A rival occupies both holes ahead of the pending microtask flush.
+      b.slots.register({ name: HOLES[0] } as never, () => null)
+      b.slots.register({ name: HOLES[1] } as never, () => null)
+      await new Promise(resolve => setTimeout(resolve, 20))
+      // The rival keeps both holes; this provider rolled back wholesale and
+      // surfaced the conflict on the fail-loud channel — no partial mix.
+      for (const hole of HOLES) expect(b.slots.entries(hole)).toHaveLength(1)
+      expect(rejections.map(String).join('\n')).toContain('already has a registration')
+
+      // Non-Error conflicts wrap before the loud rethrow (same channel).
+      const c = await bench()
+      await c.ctx.plugin({ inject: [...inject], apply }).await()
+      const original = c.slots.register.bind(c.slots)
+      const slotsAny = c.slots as { register: typeof original }
+      slotsAny.register = ((options: never, component: never) => {
+        if ((options as { name?: string }).name === HOLES[0]) throw 'string conflict'
+        return original(options, component)
+      }) as typeof original
+      c.declare()
+      await new Promise(resolve => setTimeout(resolve, 20))
+      expect(rejections.map(String).join('\n')).toContain('string conflict')
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+      process.off('uncaughtException', onUnhandled)
+    }
+  })
+
+  it('rolls back the zh dictionary when a rival already owns the namespace en slot', async () => {
+    const b = await bench()
+    b.declare()
+    const locale = b.ctx.get('locale') as LocaleService
+    const disposeRival = locale.register('directory-browser', 'en', { 'browser.title': 'rival' })
+    const rejections: unknown[] = []
+    const onUnhandled = (reason: unknown): void => { rejections.push(reason) }
+    // cordis re-raises the apply throw as a late rejection (installFailLoud's contract).
+    process.on('unhandledRejection', onUnhandled)
+    try {
+      const fiber = b.ctx.plugin({ inject: [...inject], apply })
+      await expect(fiber.await()).rejects.toThrow(/already has locale/)
+      // The zh registration rolled back with the failure: once the rival
+      // leaves, a fresh registrant owns the whole namespace again.
+      disposeRival()
+      const disposeZh = locale.register('directory-browser', 'zh', { 'browser.title': '空闲' })
+      disposeZh()
+    } finally {
+      await new Promise(resolve => setTimeout(resolve, 0))
+      process.off('unhandledRejection', onUnhandled)
+    }
+  })
+
+  it('registers the dialog dictionaries and binds this package namespace', async () => {
+    const b = await bench()
+    b.declare()
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const entry = b.slots.entries(HOLES[0])[0]!
+    const injected = (entry.inject as () => { t: (key: string) => string })()
+    // zh is the shipped default locale.
+    expect(injected.t('browser.title')).toBe('选择工作区目录')
+    expect(injected.t('browser.newFolder')).toBe('新建文件夹')
+    expect(injected.t('browser.showHidden')).toBe('显示隐藏文件')
+  })
+
+  it('drives the injected browse calls through the hole entry', async () => {
+    const b = await bench()
+    b.declare()
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const entry = b.slots.entries(HOLES[1])[0]!
+    const injected = (entry.inject as () => {
+      listDirectory: (path?: string) => Promise<DirectoryListing>
+      createDirectory: (path: string, name: string) => Promise<string>
+    })()
+    await expect(injected.listDirectory()).resolves.toBe(homeListing)
+    await expect(injected.createDirectory(HOME, 'fresh')).resolves.toBe(`${HOME}/fresh`)
+    expect(b.listDirectory).toHaveBeenCalledOnce()
+    expect(b.createDirectory).toHaveBeenCalledWith(HOME, 'fresh')
+  })
+
+  it('adapts the owner conversation onto the dialog: confirm picks, dismissal cancels', async () => {
+    const props = owner()
+    const listDirectory = vi.fn(async (): Promise<DirectoryListing> => homeListing)
+    const t = (key: string): string => key
+    render(
+      <BrowseDirectoryFlow
+        {...props}
+        listDirectory={listDirectory}
+        createDirectory={vi.fn(async () => '')}
+        t={t}
+      />,
+    )
+    // The dialog opened at home; its confirm (browser.open) adopts the listed level.
+    const openButton = await screen.findByRole('button', { name: 'browser.open' })
+    openButton.click()
+    expect(props.onPicked).toHaveBeenCalledWith(HOME)
+    screen.getByRole('button', { name: 'browser.cancel' }).click()
+    expect(props.onCancel).toHaveBeenCalled()
+    expect(props.onError).not.toHaveBeenCalled()
+  })
+
+  it('renders nothing while the flow is closed', () => {
+    const view = render(
+      <BrowseDirectoryFlow
+        {...owner({ open: false })}
+        listDirectory={vi.fn(async () => homeListing)}
+        createDirectory={vi.fn(async () => '')}
+        t={key => key}
+      />,
+    )
+    expect(view.container.innerHTML).toBe('')
+  })
+})

packages/host/directory-picker-browse/tests/service.spec.ts

@@ -0,0 +1,231 @@
+/** Behavior of the browse backend over a real temporary directory tree. */
+
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { DirectoryPickerError } from '@deepseek-ai/dsh-host-directory-picker'
+import type { DirectoryPickerBrowseCapability } from '@deepseek-ai/dsh-host-directory-picker'
+import BrowseDirectoryPicker, { boundedInsert, fullyQualified, raceAbort } from '../src/index.ts'
+import type { ListingCandidate } from '../src/index.ts'
+
+let root: string
+let capability: DirectoryPickerBrowseCapability
+let dispose: () => Promise<void>
+
+beforeAll(async () => {
+  root = await mkdtemp(join(tmpdir(), 'dsh-browse-'))
+  await mkdir(join(root, 'projects'))
+  await mkdir(join(root, 'projects', 'harness'))
+  await mkdir(join(root, '.hidden-dir'))
+  await writeFile(join(root, 'notes.txt'), 'not a directory')
+  await symlink(join(root, 'projects'), join(root, 'linked'), 'junction')
+  await symlink(join(root, 'gone'), join(root, 'broken'), 'junction')
+  try {
+    await symlink(join(root, 'notes.txt'), join(root, 'file-link'))
+  } catch {
+    // Windows denies unprivileged file symlinks; the file-link row only
+    // feeds the POSIX lanes' coverage of the symlink-to-file arm, and every
+    // assertion below expects it to be filtered out anyway.
+  }
+
+  const ctx = new Context()
+  const fiber = ctx.plugin(BrowseDirectoryPicker)
+  await fiber.await()
+  const picked = ctx.get('directoryPicker')!.capability()
+  if (picked.kind !== 'browse') throw new Error('browse backend must advertise the browse capability')
+  capability = picked
+  dispose = () => fiber.dispose()
+})
+
+afterAll(async () => {
+  await dispose()
+  await rm(root, { recursive: true, force: true })
+})
+
+describe('BrowseDirectoryPicker', () => {
+  it('lists directories only, flags hidden rows, follows symlinks, skips broken links, sorts by name', async () => {
+    const listing = await capability.list(root)
+    expect(listing.path).toBe(root)
+    expect(listing.home).toBe(homedir())
+    expect(listing.entries.map(entry => entry.name)).toEqual(['.hidden-dir', 'linked', 'projects'])
+    expect(listing.entries.map(entry => entry.hidden)).toEqual([true, false, false])
+    // Every entry path is absolute and host-joined — clients never join segments.
+    expect(listing.entries.every(entry => entry.path === join(root, entry.name))).toBe(true)
+    // Well under the default bound: the complete level, not a cut one.
+    expect(listing.truncated).toBe(false)
+  })
+
+  it('cuts a level at maxEntries keeping the name-sorted head, and flags the cut', async () => {
+    const ctx = new Context()
+    const fiber = ctx.plugin(BrowseDirectoryPicker, { maxEntries: 1 })
+    await fiber.await()
+    const bounded = ctx.get('directoryPicker')!.capability()
+    if (bounded.kind !== 'browse') throw new Error('browse backend must advertise the browse capability')
+    try {
+      const cut = await bounded.list(root)
+      expect(cut.entries.map(entry => entry.name)).toEqual(['.hidden-dir'])
+      expect(cut.truncated).toBe(true)
+      // Exactly at the bound is complete, not truncated.
+      const exact = await bounded.list(join(root, 'projects'))
+      expect(exact.entries.map(entry => entry.name)).toEqual(['harness'])
+      expect(exact.truncated).toBe(false)
+      // A level that fits the window but exceeds the bound (two rows, bound
+      // one): the in-window extra row proves the cut without any eviction.
+      await mkdir(join(root, 'projects', 'harness', 'a'))
+      await mkdir(join(root, 'projects', 'harness', 'b'))
+      const inWindow = await bounded.list(join(root, 'projects', 'harness'))
+      expect(inWindow.entries.map(entry => entry.name)).toEqual(['a'])
+      expect(inWindow.truncated).toBe(true)
+    } finally {
+      await fiber.dispose()
+    }
+  })
+
+  it('stops the scan with the caller: an aborted signal rejects with its own reason', async () => {
+    const gone = new AbortController()
+    gone.abort(new Error('caller left'))
+    // The abort surfaces as-is, not dressed as an unreadable directory —
+    // and rejects even before any level row is read.
+    await expect(capability.list(root, gone.signal)).rejects.toThrow('caller left')
+    // The abandoned open that still succeeds is closed, not leaked.
+    await new Promise(resolve => setTimeout(resolve, 10))
+    // Aborted against a missing target: the abandoned open rejects on its
+    // own and there is nothing to close.
+    await expect(capability.list(join(root, 'no-such-dir'), gone.signal)).rejects.toThrow('caller left')
+    await new Promise(resolve => setTimeout(resolve, 10))
+    // A live signal leaves a normal listing untouched — the reads and the
+    // symlink probes race it without ever losing.
+    const live = new AbortController()
+    const complete = await capability.list(root, live.signal)
+    expect(complete.truncated).toBe(false)
+    expect(complete.entries.map(entry => entry.name)).toContain('linked')
+    // A live signal changes nothing about ordinary failures.
+    const missing = join(root, 'no-such-dir')
+    const failure = await capability.list(missing, live.signal).catch((error: unknown) => error)
+    expect(failure).toBeInstanceOf(DirectoryPickerError)
+    expect((failure as DirectoryPickerError).code).toBe('directory-unreadable')
+  })
+
+  it('raceAbort follows the operation until the signal wins, and swallows the abandoned settlement', async () => {
+    // No signal / settled operations: plain passthrough, listener removed.
+    await expect(raceAbort(Promise.resolve('ok'), undefined)).resolves.toBe('ok')
+    const live = new AbortController()
+    await expect(raceAbort(Promise.resolve('ok'), live.signal)).resolves.toBe('ok')
+    // Failure passthrough keeps the operation's own error.
+    await expect(raceAbort(Promise.reject(new Error('raw failure')), live.signal)).rejects.toThrow('raw failure')
+    // The abort wins over a pending operation and carries its own reason;
+    // the operation's late rejection is swallowed, never unhandled.
+    const rejections: unknown[] = []
+    const onUnhandled = (reason: unknown): void => { rejections.push(reason) }
+    process.on('unhandledRejection', onUnhandled)
+    try {
+      let rejectLate!: (reason: unknown) => void
+      const pending = new Promise<never>((_resolve, reject) => { rejectLate = reject })
+      const controller = new AbortController()
+      const raced = raceAbort(pending, controller.signal)
+      // A bare-string abort reason exercises the Error wrap.
+      controller.abort('caller left')
+      await expect(raced).rejects.toThrow('caller left')
+      rejectLate(new Error('late read failure'))
+      await new Promise(resolve => setTimeout(resolve, 10))
+      expect(rejections).toEqual([])
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+    }
+  })
+
+  it('boundedInsert keeps the window name-sorted and bounded, reporting evictions', () => {
+    const candidate = (name: string): ListingCandidate => ({ name, isDirectory: true, isSymbolicLink: false })
+    const window: ListingCandidate[] = []
+    expect(boundedInsert(window, candidate('m'), 2)).toBe(false)
+    expect(boundedInsert(window, candidate('z'), 2)).toBe(false)
+    // A smaller name lands in place and pushes the current largest out.
+    expect(boundedInsert(window, candidate('a'), 2)).toBe(true)
+    expect(window.map(entry => entry.name)).toEqual(['a', 'm'])
+    // A name at or beyond the full window's tail rejects on one comparison.
+    expect(boundedInsert(window, candidate('t'), 2)).toBe(true)
+    expect(window.map(entry => entry.name)).toEqual(['a', 'm'])
+    expect(boundedInsert(window, candidate('m'), 2)).toBe(true)
+    expect(window.map(entry => entry.name)).toEqual(['a', 'm'])
+  })
+
+  it('reports the ancestry as jump-target crumbs ending at the listed directory', async () => {
+    const listing = await capability.list(join(root, 'projects'))
+    const tail = listing.crumbs.at(-1)!
+    expect(tail).toMatchObject({ name: 'projects', path: join(root, 'projects'), hidden: false })
+    expect(listing.crumbs.at(-2)!.path).toBe(root)
+    expect(listing.crumbs.at(-2)!.name).toBe(basename(root))
+    // The chain starts at the filesystem root, whose crumb is labeled by its full path.
+    expect(listing.crumbs[0]!.name).toBe(listing.crumbs[0]!.path)
+  })
+
+  it('lists the home directory when no path is given', async () => {
+    const listing = await capability.list()
+    expect(listing.path).toBe(homedir())
+  })
+
+  it('throws directory-unreadable for a missing target', async () => {
+    const missing = join(root, 'no-such-dir')
+    const failure = await capability.list(missing).catch((error: unknown) => error)
+    expect(failure).toBeInstanceOf(DirectoryPickerError)
+    expect((failure as DirectoryPickerError).code).toBe('directory-unreadable')
+    expect((failure as DirectoryPickerError).path).toBe(missing)
+  })
+
+  it('classifies fully qualified paths per platform (drive-less rooted Windows forms rejected)', () => {
+    expect(fullyQualified('/home/x', 'linux')).toBe(true)
+    expect(fullyQualified('x/y', 'darwin')).toBe(false)
+    expect(fullyQualified('C:\\projects', 'win32')).toBe(true)
+    expect(fullyQualified('C:/projects', 'win32')).toBe(true)
+    expect(fullyQualified('\\\\server\\share', 'win32')).toBe(true)
+    expect(fullyQualified('//server/share/deep', 'win32')).toBe(true)
+    // Rooted but drive-less: isAbsolute accepts these, yet resolve() would
+    // inject the process's current drive.
+    expect(fullyQualified('\\foo', 'win32')).toBe(false)
+    expect(fullyQualified('/foo', 'win32')).toBe(false)
+    expect(fullyQualified('C:relative', 'win32')).toBe(false)
+    // Incomplete UNC prefixes collapse to drive-relative roots under resolve().
+    expect(fullyQualified('\\\\', 'win32')).toBe(false)
+    expect(fullyQualified('\\\\server', 'win32')).toBe(false)
+    expect(fullyQualified('\\\\server\\', 'win32')).toBe(false)
+  })
+
+  it('rejects non-absolute paths instead of rebasing them under the process cwd', async () => {
+    for (const relative of ['', 'projects', './projects', '..']) {
+      const listFailure = await capability.list(relative).catch((error: unknown) => error)
+      expect(listFailure).toBeInstanceOf(DirectoryPickerError)
+      expect((listFailure as DirectoryPickerError).code).toBe('directory-unreadable')
+      expect((listFailure as DirectoryPickerError).path).toBe(relative)
+      const createFailure = await capability.createDirectory(relative, 'child').catch((error: unknown) => error)
+      expect(createFailure).toBeInstanceOf(DirectoryPickerError)
+      expect((createFailure as DirectoryPickerError).code).toBe('directory-create-failed')
+      expect((createFailure as DirectoryPickerError).path).toBe(relative)
+    }
+  })
+
+  it('creates one child directory and surfaces it in the next listing', async () => {
+    const created = await capability.createDirectory(root, 'fresh')
+    expect(created).toBe(join(root, 'fresh'))
+    const listing = await capability.list(root)
+    expect(listing.entries.map(entry => entry.name)).toContain('fresh')
+  })
+
+  it('refuses an existing child with directory-exists', async () => {
+    const failure = await capability.createDirectory(root, 'projects').catch((error: unknown) => error)
+    expect(failure).toBeInstanceOf(DirectoryPickerError)
+    expect((failure as DirectoryPickerError).code).toBe('directory-exists')
+  })
+
+  it('refuses non-segment names and other filesystem failures with directory-create-failed', async () => {
+    for (const name of ['', '  ', '.', '..', 'a/b', 'a\\b']) {
+      const failure = await capability.createDirectory(root, name).catch((error: unknown) => error)
+      expect(failure).toBeInstanceOf(DirectoryPickerError)
+      expect((failure as DirectoryPickerError).code).toBe('directory-create-failed')
+    }
+    // Missing parent is a real failure, not a level to invent.
+    const missingParent = await capability.createDirectory(join(root, 'no-such-dir'), 'child').catch((error: unknown) => error)
+    expect((missingParent as DirectoryPickerError).code).toBe('directory-create-failed')
+  })
+})

packages/host/directory-picker-browse/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../directory-picker"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../client/ui-slots"
+    },
+    {
+      "path": "../../client/ui-primitives"
+    },
+    {
+      "path": "../../client/locale"
+    },
+    {
+      "path": "../../client/runtime"
+    },
+    {
+      "path": "../../client/ui-workspace"
+    }
+  ]
+}

packages/host/directory-picker-browse/tsdown.config.ts

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

packages/host/directory-picker-native/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/host/directory-picker-native/README.md
+README.md: 0b54c651d4f5382021d0f8832ab4f1146b7652c8
+README.zh.md: e5ac2762a691a16a7e6d9d6dd9aefc70a59dcd4f

packages/host/directory-picker-native/README.md

@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-host-directory-picker-native
+
+English | [中文](README.zh.md)
+
+The **native-OS-chooser backend** of the [directory-picker seam](../directory-picker/README.md): `NativeDirectoryPicker` registers `ctx.directoryPicker` with the `native` capability, whose `pick(signal)` opens one native chooser per call and resolves the chosen absolute path (`null` on cancel). Platform tools run without a shell: `osascript` on macOS, an STA PowerShell `FolderBrowserDialog` on Windows, and Zenity with a KDialog fallback on Linux; the caller's abort terminates the native process. Only viable when the operator sits at the host's display — remote deployments compose [`-browse`](../directory-picker-browse/README.md) instead. The command boundary (`DirectoryPickerRunner`) and platform facts are injectable for deterministic tests. The shared no-shell subprocess runner lives in [`dsh-native-command`](../../util/native-command/README.md).
+
+**Dual-face package**: the browser half (`./client`) registers a renderless flow occupant into [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes — each `open` request drives `host.pickDirectory` and reports the one outcome (picked path / cancel / failure) through the hole's owner conversation. One cordis.yml row therefore composes both sides of the native interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind).
+
+## Model Experience
+
+None, as the backend serves the GUI host's directory selection; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Linux requires desktop tooling** — with neither Zenity nor KDialog installed, `pick` rejects with an actionable error; it does not fall back to a typed-path prompt (the browse backend is that fallback at the composition level).

packages/host/directory-picker-native/README.zh.md

@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-host-directory-picker-native
+
+[English](README.md) | 中文
+
+[目录选择 seam](../directory-picker/README.md) 的**原生 OS 选择器后端**：`NativeDirectoryPicker` 以 `native` 能力注册 `ctx.directoryPicker`，其 `pick(signal)` 每次调用打开一个原生选择器并解析出所选绝对路径（取消时为 `null`）。平台工具不经 shell 调用：macOS 使用 `osascript`，Windows 使用以 STA 模式运行的 PowerShell `FolderBrowserDialog`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。只有操作者坐在宿主屏幕前时才可用——远程部署应组合 [`-browse`](../directory-picker-browse/README.md)。命令边界（`DirectoryPickerRunner`）与平台事实可注入，便于确定性测试。共享的免 shell 子进程运行器位于 [`dsh-native-command`](../../util/native-command/README.md)。
+
+**双面包**：browser half（`./client`）向 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞注册一个无渲染的流程占用者——每次 `open` 请求驱动 `host.pickDirectory`，并经洞的 owner 会话上报唯一结果（所选路径／取消／失败）。因此一行 cordis.yml 同时组合原生交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。
+
+## 模型体验
+
+无。该后端服务于 GUI 宿主的目录选择；这里没有任何内容进入模型请求。
+
+#### KV 缓存影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+- **Linux 依赖桌面工具**——Zenity 与 KDialog 均未安装时，`pick` 以包含解决建议的错误拒绝；它不会回退为手输路径提示（组合层面的回退是 browse 后端）。

packages/host/directory-picker-native/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@deepseek-ai/dsh-host-directory-picker-native",
+  "description": "Native-OS-chooser backend of the directory-picker seam for the DeepSeek Harness web GUI host",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-host-directory-picker": "workspace:^",
+    "@deepseek-ai/dsh-native-command": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-workspace": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-workspace": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-ui-workspace"
+    ],
+    "platform": "web"
+  }
+}

packages/host/directory-picker-native/src/client/flow.ts

@@ -0,0 +1,65 @@
+/**
+ * The native picking occupant (package-internal; the `./client` surface
+ * exposes only the Loader exports). Same-package tests exercise it directly
+ * through this module.
+ */
+import { useEffect, useRef } from 'react'
+import type { ReactElement } from 'react'
+// Type-only: the owner contract of the directory-flow holes.
+import type { DirectoryFlowOwnerProps } from '@deepseek-ai/dsh-client-ui-workspace/client'
+
+/** Injected face: the wire call the flow drives (bound in apply's closure). */
+export interface NativeFlowInjected {
+  /** Ask the local Host to open its native single-directory chooser. */
+  pick: () => Promise<string | null>
+}
+
+/**
+ * Renderless flow occupant: each rising `open` edge runs exactly one pick and
+ * reports exactly one outcome; the ref arms once per open so re-renders (and
+ * an adoption keeping `open` true while `busy`) never launch a second
+ * chooser. The owner withdrawing `open` re-arms the next request.
+ * @param props - owner conversation plus the injected pick call.
+ * @returns nothing — the native chooser renders on the host display.
+ */
+export function NativeDirectoryFlow(props: DirectoryFlowOwnerProps & NativeFlowInjected): ReactElement | null {
+  const { open, pick } = props
+  const armed = useRef(false)
+  // Callbacks ride a ref so the settled pick reports through the owner's
+  // latest handlers, not the ones captured when the chooser opened.
+  const outcome = useRef(props)
+  outcome.current = props
+  // Unmount (HMR replacing the occupant) discards settlements wholesale: the
+  // dead instance must neither adopt a path nor drive the owner's error
+  // surface. The wire carries no per-request abort, so the host-side chooser
+  // survives until answered — its answer just lands nowhere; the replacement
+  // instance re-arms under the owner's still-open request. An injected-face
+  // identity change alone (re-registration) keeps the pending settlement:
+  // the chooser on the host display is still the same dialog.
+  const alive = useRef(true)
+  useEffect(() => {
+    // StrictMode's development replay runs the cleanup once before the real
+    // lifetime: re-arm on setup or every outcome would be discarded.
+    alive.current = true
+    return () => { alive.current = false }
+  }, [])
+  useEffect(() => {
+    if (!open) {
+      armed.current = false
+      return
+    }
+    if (armed.current) return
+    armed.current = true
+    pick().then(
+      (path) => {
+        if (!alive.current) return
+        if (path === null) outcome.current.onCancel(); else outcome.current.onPicked(path)
+      },
+      (reason: unknown) => {
+        if (!alive.current) return
+        outcome.current.onError(reason instanceof Error ? reason.message : String(reason))
+      },
+    )
+  }, [open, pick])
+  return null
+}

packages/host/directory-picker-native/src/client/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Browser half of the native directory-picker backend: fills ui-workspace's
+ * two directory-flow holes with a renderless occupant that answers each
+ * `open` by driving `host.pickDirectory` (the node half's OS chooser) and
+ * reporting the one outcome — picked path, cancellation, or failure — back
+ * through the owner conversation. Mounting this package therefore composes
+ * both sides of the native interaction with one cordis.yml row; no client
+ * code branches on a capability kind.
+ */
+import { deferGroupRegistration } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: pulls the SlotMap merge declaring the directory-flow holes.
+import type {} from '@deepseek-ai/dsh-client-ui-workspace/client'
+import type { NativeFlowInjected } from './flow.ts'
+import { NativeDirectoryFlow } from './flow.ts'
+
+
+/** Required services (cordis fiber inject): the slot registry and the wire-facing workspace service. */
+export const inject = ['slots', 'workspaces']
+
+/**
+ * Client plugin body: register the renderless native flow into both
+ * directory-flow holes (declaration-aware deferral — the declaring
+ * ui-workspace entries may activate later, and an HMR collapse re-declares).
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  const injected = (): NativeFlowInjected => ({ pick: () => ctx.workspaces.pickDirectory() })
+  ctx.effect(() => {
+    // One occupant, both holes, as a unit: construction or late conflicts
+    // (holes declared after rival providers activated) roll the whole pair
+    // back and fail loud — semantics owned by deferGroupRegistration.
+    const group = deferGroupRegistration(
+      ctx.slots,
+      ['conversation.hero.workspace.directoryFlow', 'sidebar.workspaces.directoryFlow'] as const,
+      NativeDirectoryFlow,
+      name => ctx.slots.register({ name, inject: injected }, NativeDirectoryFlow),
+    )
+    return () => { group.dispose() }
+  }, 'directory-picker-native: flow registrations')
+}

packages/host/directory-picker-native/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Native backend of the directory-picker seam: registers `ctx.directoryPicker`
+ * with the `native` capability, opening one native OS chooser on the host
+ * display per pick (macOS `osascript`, Windows STA PowerShell
+ * `FolderBrowserDialog`, Linux Zenity with a KDialog fallback). Only viable
+ * when the operator sits at the host's screen; remote deployments compose the
+ * browse backend instead.
+ * @module @deepseek-ai/dsh-host-directory-picker-native
+ */
+
+import { DirectoryPicker } from '@deepseek-ai/dsh-host-directory-picker'
+import type { DirectoryPickerCapability } from '@deepseek-ai/dsh-host-directory-picker'
+import { pickNativeDirectory } from './native-picker.ts'
+
+export type { DirectoryPickerInternals, DirectoryPickerRunner } from './native-picker.ts'
+export { pickNativeDirectory } from './native-picker.ts'
+
+/** The `ctx.directoryPicker` native implementation (stable capability object per service life). */
+export default class NativeDirectoryPicker extends DirectoryPicker {
+  private readonly nativeCapability: DirectoryPickerCapability = {
+    kind: 'native',
+    /* v8 ignore next -- pure forward to pickNativeDirectory (its spec owns behavior); invoking here opens a real chooser. */
+    pick: signal => pickNativeDirectory(signal),
+  }
+
+  /**
+   * The native interaction capability.
+   * @returns the stable `native` capability object.
+   */
+  capability(): DirectoryPickerCapability {
+    return this.nativeCapability
+  }
+}

packages/host/directory-picker-native/src/invariant.ts

@@ -0,0 +1,25 @@
+/**
+ * Package-owned invariant companion for the native directory-picker backend.
+ * @module @deepseek-ai/dsh-host-directory-picker-native/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-directory-picker-native'
+
+/** Cordis companion plugin name. */
+export const name = 'host-directory-picker-native-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: each pick is one stateless subprocess round trip; the chooser outcome is only the returned path. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register the native directory-picker invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/host/directory-picker-native/src/native-picker.ts

@@ -1,13 +1,9 @@
-/** Cross-platform native single-directory picker used by the local GUI carrier. */
+/** Cross-platform native single-directory chooser behind the native backend's capability. */
 
-import { execFile } from 'node:child_process'
+import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
 
 /** Testable command boundary; native implementations never invoke a shell. */
-export type DirectoryPickerRunner = (
-  command: string,
-  args: readonly string[],
-  signal: AbortSignal,
-) => Promise<{ stdout: string; stderr: string }>
+export type DirectoryPickerRunner = NativeCommandRunner
 
 /** Injectable platform facts for deterministic adapter tests. */
 export interface DirectoryPickerInternals {
@@ -15,27 +11,6 @@ export interface DirectoryPickerInternals {
   run?: DirectoryPickerRunner
 }
 
-const runCommand: DirectoryPickerRunner = (command, args, signal) =>
-  new Promise((resolve, reject) => {
-    execFile(
-      command,
-      [...args],
-      { encoding: 'utf8', signal, windowsHide: true },
-      (error, stdout, stderr) => {
-        if (error !== null) {
-          const failure = Object.assign(new Error(error.message, { cause: error }), {
-            code: error.code,
-            stdout,
-            stderr,
-          })
-          reject(failure)
-          return
-        }
-        resolve({ stdout, stderr })
-      },
-    )
-  })
-
 function outputPath(stdout: string): string | null {
   const path = stdout.replace(/[\r\n]+$/, '')
   return path === '' ? null : path
@@ -72,7 +47,7 @@ export async function pickNativeDirectory(
   internals: DirectoryPickerInternals = {},
 ): Promise<string | null> {
   const platform = internals.platform ?? process.platform
-  const run = internals.run ?? runCommand
+  const run = internals.run ?? runNativeCommand
 
   if (platform === 'darwin') {
     try {

packages/host/directory-picker-native/tests/client-flow.spec.tsx

@@ -0,0 +1,219 @@
+// @vitest-environment jsdom
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render } from '@testing-library/react'
+import { afterEach } from 'vitest'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { DirectoryFlowOwnerProps } from '@deepseek-ai/dsh-client-ui-workspace/client'
+import { apply, inject } from '../src/client/index.ts'
+import { NativeDirectoryFlow } from '../src/client/flow.ts'
+
+afterEach(cleanup)
+
+const HOLES = ['conversation.hero.workspace.directoryFlow', 'sidebar.workspaces.directoryFlow'] as const
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  const pickDirectory = vi.fn(async (): Promise<string | null> => '/tmp/picked')
+  ctx.provide('workspaces', { pickDirectory } as never)
+  const slots = ctx.get('slots') as SlotsService
+  const declare = () => slots.register({
+    name: 'root',
+    children: Object.fromEntries(HOLES.map(name => [name, { kind: 'single', scope: 'root' }])),
+  } as never, () => null)
+  return { ctx, slots, pickDirectory, declare }
+}
+
+function owner(overrides: Partial<DirectoryFlowOwnerProps> = {}): DirectoryFlowOwnerProps {
+  return {
+    open: true, busy: false,
+    onPicked: vi.fn(), onCancel: vi.fn(), onError: vi.fn(),
+    ...overrides,
+  }
+}
+
+describe('directory-picker-native client half', () => {
+  it('declares the services it drives', () => {
+    expect(inject).toEqual(['slots', 'workspaces'])
+  })
+
+  it('fills both directory-flow holes for declarations before or after apply, and leaves with its fiber', async () => {
+    const before = await bench()
+    before.declare()
+    const fiber = before.ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    for (const hole of HOLES) expect(before.slots.entries(hole)).toHaveLength(1)
+    // Registry-contribution disposal proof: the fiber going down empties the holes.
+    await fiber.dispose()
+    for (const hole of HOLES) expect(before.slots.entries(hole)).toHaveLength(0)
+
+    const after = await bench()
+    await after.ctx.plugin({ inject: [...inject], apply }).await()
+    for (const hole of HOLES) expect(after.slots.entries(hole)).toHaveLength(0)
+    after.declare()
+    await Promise.resolve()
+    for (const hole of HOLES) expect(after.slots.entries(hole)).toHaveLength(1)
+  })
+
+  it('rolls back wholesale and reports loudly when a rival provider wins after deferred activation', async () => {
+    const b = await bench()
+    const rejections: unknown[] = []
+    const onUnhandled = (reason: unknown): void => { rejections.push(reason) }
+    // queueMicrotask throws surface as uncaughtException, not a rejection.
+    process.on('unhandledRejection', onUnhandled)
+    process.on('uncaughtException', onUnhandled)
+    try {
+      // This provider activates BEFORE any hole exists: both deferrals wait.
+      // (Duplicate rows of the SAME package converge silently — the deferral
+      // skips a hole its own component already occupies; the conflict needs
+      // a rival provider.)
+      await b.ctx.plugin({ inject: [...inject], apply }).await()
+      b.declare()
+      // A rival occupies both holes ahead of the pending microtask flush.
+      b.slots.register({ name: HOLES[0] } as never, () => null)
+      b.slots.register({ name: HOLES[1] } as never, () => null)
+      await new Promise(resolve => setTimeout(resolve, 20))
+      // The rival keeps both holes; this provider rolled back wholesale and
+      // surfaced the conflict on the fail-loud channel — no partial mix.
+      for (const hole of HOLES) expect(b.slots.entries(hole)).toHaveLength(1)
+      expect(rejections.map(String).join('\n')).toContain('already has a registration')
+
+      // Non-Error conflicts wrap before the loud rethrow (same channel).
+      const c = await bench()
+      await c.ctx.plugin({ inject: [...inject], apply }).await()
+      const original = c.slots.register.bind(c.slots)
+      const slotsAny = c.slots as { register: typeof original }
+      slotsAny.register = ((options: never, component: never) => {
+        if ((options as { name?: string }).name === HOLES[0]) throw 'string conflict'
+        return original(options, component)
+      }) as typeof original
+      c.declare()
+      await new Promise(resolve => setTimeout(resolve, 20))
+      expect(rejections.map(String).join('\n')).toContain('string conflict')
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+      process.off('uncaughtException', onUnhandled)
+    }
+  })
+
+  it('rolls back the first deferral when the second hole is already occupied', async () => {
+    const b = await bench()
+    b.declare()
+    // Foreign occupant in the SECOND registered hole: the pair construction
+    // throws after the first deferral installed its subscription.
+    b.slots.register({ name: HOLES[1] } as never, () => null)
+    const rejections: unknown[] = []
+    const onUnhandled = (reason: unknown): void => { rejections.push(reason) }
+    process.on('unhandledRejection', onUnhandled)
+    try {
+      const fiber = b.ctx.plugin({ inject: [...inject], apply })
+      await expect(fiber.await()).rejects.toThrow(/already has a registration/)
+      // A leaked first deferral would now race this probe registration and
+      // throw from its orphaned subscription against the HERO hole; the
+      // rollback leaves only the activation failure itself (cordis re-raises
+      // the apply throw as a late rejection — installFailLoud's contract).
+      const disposeProbe = b.slots.register({ name: HOLES[0] } as never, () => null)
+      await new Promise(resolve => setTimeout(resolve, 20))
+      expect(rejections.map(String).filter(text => text.includes(HOLES[0]))).toEqual([])
+      disposeProbe()
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+    }
+  })
+
+  it('rejects a second flow occupant at load (single-kind hole)', async () => {
+    const b = await bench()
+    b.declare()
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    expect(() => b.slots.register({ name: HOLES[0] } as never, () => null))
+      .toThrow(/already has a registration/)
+  })
+
+  it('drives the injected pick through the hole entry and reports the picked path', async () => {
+    const b = await bench()
+    b.declare()
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const entry = b.slots.entries(HOLES[0])[0]!
+    const injected = (entry.inject as () => { pick: () => Promise<string | null> })()
+    await expect(injected.pick()).resolves.toBe('/tmp/picked')
+    expect(b.pickDirectory).toHaveBeenCalledOnce()
+  })
+
+  it('runs one pick per open edge and reports the path to the latest onPicked', async () => {
+    let resolve!: (path: string | null) => void
+    const pick = vi.fn(() => new Promise<string | null>((settle) => { resolve = settle }))
+    const first = owner()
+    const view = render(<NativeDirectoryFlow {...first} pick={pick} />)
+    expect(pick).toHaveBeenCalledOnce()
+    // Re-renders while open (busy flips, handler identity changes) must not relaunch the chooser.
+    const second = owner()
+    view.rerender(<NativeDirectoryFlow {...second} busy pick={pick} />)
+    expect(pick).toHaveBeenCalledOnce()
+    // Even a fresh injected face (re-registration re-runs the inject factory)
+    // must not relaunch while the same request is still open.
+    const replacedPick = vi.fn(() => new Promise<string | null>(() => {}))
+    view.rerender(<NativeDirectoryFlow {...second} busy pick={replacedPick} />)
+    expect(replacedPick).not.toHaveBeenCalled()
+    await act(async () => { resolve('/tmp/project') })
+    expect(second.onPicked).toHaveBeenCalledWith('/tmp/project')
+    expect(first.onPicked).not.toHaveBeenCalled()
+  })
+
+  it('discards a settlement that lands after the flow unmounted', async () => {
+    let resolve!: (path: string | null) => void
+    const pick = vi.fn(() => new Promise<string | null>((settle) => { resolve = settle }))
+    const props = owner()
+    const view = render(<NativeDirectoryFlow {...props} pick={pick} />)
+    expect(pick).toHaveBeenCalledOnce()
+    view.unmount()
+    // The dead instance must neither adopt nor error; the owner's callbacks
+    // stay untouched by the orphaned chooser's answer.
+    await act(async () => { resolve('/tmp/late') })
+    expect(props.onPicked).not.toHaveBeenCalled()
+    expect(props.onCancel).not.toHaveBeenCalled()
+    expect(props.onError).not.toHaveBeenCalled()
+
+    // The failure arm is discarded the same way.
+    let reject!: (reason: unknown) => void
+    const failing = vi.fn(() => new Promise<string | null>((_settle, rejectPick) => { reject = rejectPick }))
+    const late = owner()
+    const failingView = render(<NativeDirectoryFlow {...late} pick={failing} />)
+    failingView.unmount()
+    await act(async () => { reject(new Error('too late')) })
+    expect(late.onError).not.toHaveBeenCalled()
+  })
+
+  it('reports null as cancellation and re-arms after the owner withdraws open', async () => {
+    const pick = vi.fn(async () => null as string | null)
+    const props = owner()
+    const view = render(<NativeDirectoryFlow {...props} pick={pick} />)
+    await act(async () => {})
+    expect(props.onCancel).toHaveBeenCalledOnce()
+    expect(props.onPicked).not.toHaveBeenCalled()
+    // Withdraw and reopen: a fresh request runs a fresh pick.
+    view.rerender(<NativeDirectoryFlow {...props} open={false} pick={pick} />)
+    view.rerender(<NativeDirectoryFlow {...props} pick={pick} />)
+    await act(async () => {})
+    expect(pick).toHaveBeenCalledTimes(2)
+  })
+
+  it('folds pick failures into onError messages', async () => {
+    const props = owner()
+    render(<NativeDirectoryFlow {...props} pick={vi.fn(async () => { throw new Error('no chooser installed') })} />)
+    await act(async () => {})
+    expect(props.onError).toHaveBeenCalledWith('no chooser installed')
+
+    const nonError = owner()
+    render(<NativeDirectoryFlow {...nonError} pick={vi.fn(async () => { throw 'denied' })} />)
+    await act(async () => {})
+    expect(nonError.onError).toHaveBeenCalledWith('denied')
+  })
+
+  it('renders nothing while closed and while open', () => {
+    const closed = render(<NativeDirectoryFlow {...owner({ open: false })} pick={vi.fn(async () => null)} />)
+    expect(closed.container.innerHTML).toBe('')
+    const opened = render(<NativeDirectoryFlow {...owner()} pick={vi.fn(async () => null)} />)
+    expect(opened.container.innerHTML).toBe('')
+  })
+})

packages/host/directory-picker-native/tests/native-picker.spec.ts

@@ -15,7 +15,7 @@ const { execFileMock } = vi.hoisted(() => ({ execFileMock: vi.fn<ExecFileMock>()
 vi.mock('node:child_process', () => ({ execFile: execFileMock }))
 
 import { describe, expect, it, vi } from 'vitest'
-import { pickNativeDirectory, type DirectoryPickerRunner } from '../src/native-directory-picker.ts'
+import { pickNativeDirectory, type DirectoryPickerRunner } from '../src/native-picker.ts'
 
 function failure(code: string | number, stderr = ''): Error {
   return Object.assign(new Error(`command failed: ${String(code)}`), { code, stderr })

packages/host/directory-picker-native/tests/service.spec.ts

@@ -0,0 +1,21 @@
+/** Registration/capability behavior of the native backend (the seam's cordis half). */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import NativeDirectoryPicker from '../src/index.ts'
+
+describe('NativeDirectoryPicker', () => {
+  it('registers ctx.directoryPicker with a stable native capability and leaves with its fiber', async () => {
+    const ctx = new Context()
+    const fiber = ctx.plugin(NativeDirectoryPicker)
+    await fiber.await()
+    const picker = ctx.get('directoryPicker')
+    expect(picker).toBeInstanceOf(NativeDirectoryPicker)
+    const capability = picker!.capability()
+    expect(capability.kind).toBe('native')
+    // Stability: consumers may capture the capability object across calls.
+    expect(picker!.capability()).toBe(capability)
+    await fiber.dispose()
+    expect(ctx.get('directoryPicker')).toBeUndefined()
+  })
+})

packages/host/directory-picker-native/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../directory-picker"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../util/native-command"
+    },
+    {
+      "path": "../../client/ui-slots"
+    },
+    {
+      "path": "../../client/runtime"
+    },
+    {
+      "path": "../../client/ui-workspace"
+    }
+  ]
+}

packages/host/directory-picker-native/tsdown.config.ts

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

packages/host/directory-picker/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/host/directory-picker/README.md
+README.md: 3749b238b56578ec68610bc13550760aa084bad6
+README.zh.md: 488da5129ec211c2a064156c22a9d0abf04d99be

packages/host/directory-picker/README.md

@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-host-directory-picker
+
+English | [中文](README.zh.md)
+
+The **workspace-directory picking seam** for the web-GUI host: an abstract `DirectoryPicker` service (`ctx.directoryPicker`) whose single contract method `capability()` returns a discriminated capability describing how an operator selects a directory. Backends differ in interaction shape, not just mechanism, so the seam models the shapes explicitly instead of one method set: `{ kind: 'native', pick(signal) }` opens one native OS chooser on the host display ([`-native`](../directory-picker-native/README.md)); `{ kind: 'browse', list(path?), createDirectory(path, name) }` serves listing/creation primitives an in-app browser drives, which works for remote clients no OS chooser can reach ([`-browse`](../directory-picker-browse/README.md)). Consumers switch on `capability().kind`; the union derives from the merge-extensible `DirectoryPickerCapabilities` map (a new backend declaration-merges its shape there), and the documented default for an unknown kind is to hide the picking affordance rather than fail. The capability object must be stable for the service lifetime. The client side mirrors the seam without a wire advertisement: each backend package is dual-face, its browser half registering the matching picking interaction into ui-workspace's directory-flow slots — so one composition row swaps both the host capability and the client flow together. A composition that should not pin an interaction mounts the [`-auto`](../directory-picker-auto/README.md) chooser instead, which resolves the host's situation once at boot and mounts the matching backend row itself.
+
+Browse primitives fail with the typed `DirectoryPickerError` (`directory-unreadable` / `directory-exists` / `directory-create-failed`, each carrying the subject `path`), which the consuming gateway maps 1:1 onto wire error codes. `DirectoryEntry` rows carry a host-owned `hidden` flag (POSIX dot convention) so display policy stays client-side; `DirectoryListing.crumbs` is the ancestor chain from the filesystem root, every crumb a jump target. Design rationale, the `ctx.fs` separation, and the policy decisions live in [the directory-picker capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md).
+
+## Model Experience
+
+None, as the seam serves the GUI host's directory selection; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No multi-root vocabulary** — the browse contract exposes one ancestry chain per listing; per-deployment root scoping (and Windows drive-root enumeration above a drive) waits for a consumer that needs it, per the seam Agent Note.

packages/host/directory-picker/README.zh.md

@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-host-directory-picker
+
+[English](README.md) | 中文
+
+web GUI 宿主的**工作区目录选择 seam**：抽象服务 `DirectoryPicker`（`ctx.directoryPicker`），唯一契约方法 `capability()` 返回一个可辨识能力对象，描述操作者以何种方式选择目录。后端之间的差异在交互形态而不只是机制，因此 seam 显式建模形态而非统一方法集：`{ kind: 'native', pick(signal) }` 在宿主屏幕上打开一个原生 OS 选择器（[`-native`](../directory-picker-native/README.md)）；`{ kind: 'browse', list(path?), createDirectory(path, name) }` 提供应用内浏览器驱动的列举／创建原语，可服务任何 OS 对话框都触及不到的远程客户端（[`-browse`](../directory-picker-browse/README.md)）。消费方按 `capability().kind` 分支；联合类型由可合并扩展的 `DirectoryPickerCapabilities` 映射派生（新后端在其中声明合并自己的形态），未知 kind 的文档化默认行为是隐藏选择入口而非失败。能力对象在服务生命周期内必须保持稳定。client 侧以镜像方式承接该 seam 而不经 wire 广播：每个后端包都是双面包，其 browser half 把匹配的选取交互注册进 ui-workspace 的目录流 slot——因此一行组合同时切换宿主能力与 client 流程。不应固定某种交互的组合改为挂载 [`-auto`](../directory-picker-auto/README.md) 选择器，它在启动时一次性判定宿主处境，并自行挂载匹配的后端行。
+
+浏览原语以带类型的 `DirectoryPickerError` 失败（`directory-unreadable`／`directory-exists`／`directory-create-failed`，各自携带主体 `path`），消费网关将其 1:1 映射为协议错误码。`DirectoryEntry` 行携带宿主判定的 `hidden` 标志（POSIX 点前缀约定），展示策略留在客户端；`DirectoryListing.crumbs` 是从文件系统根开始的祖先链，每个 crumb 都是跳转目标。设计依据、与 `ctx.fs` 的切分、策略裁决见[目录选择能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md)。
+
+## 模型体验
+
+无。该 seam 服务于 GUI 宿主的目录选择；这里没有任何内容进入模型请求。
+
+#### KV 缓存影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+- **没有多根词汇**——浏览契约每次列举只暴露一条祖先链；按部署限定可浏览根（以及 Windows 盘符之上的根枚举）等到出现需要它的消费方再做，见 seam Agent Note。

packages/host/directory-picker/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/dsh-host-directory-picker",
+  "description": "Abstract workspace-directory picking seam (ctx.directoryPicker) for the DeepSeek Harness web GUI host",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/host/directory-picker/src/index.ts

@@ -0,0 +1,143 @@
+/**
+ * The `ctx.directoryPicker` seam: how the web-GUI host lets an operator
+ * select a workspace directory. Backends differ in interaction shape, not
+ * just mechanism, so the service exposes a discriminated capability instead
+ * of one method set: a `native` backend opens one OS chooser on the
+ * host's display, while a `browse` backend serves listing/creation primitives
+ * for an in-app browser (and thereby works for remote clients no OS dialog
+ * can reach). Consumers switch on `capability().kind`; the union is
+ * merge-extensible, and the documented default for an unknown kind is to
+ * hide the picking affordance rather than fail.
+ * @module @deepseek-ai/dsh-host-directory-picker
+ */
+
+import { Context, Service } from 'cordis'
+
+/** The native interaction: one OS directory chooser on the host display. */
+export interface DirectoryPickerNativeCapability {
+  kind: 'native'
+  /**
+   * Open the chooser and wait for the operator.
+   * @param signal - caller/connection lifetime; abort terminates the chooser.
+   * @returns the chosen absolute path, or null when the operator cancels.
+   */
+  pick(signal: AbortSignal): Promise<string | null>
+}
+
+/** One directory row: a listing child or a breadcrumb ancestor. */
+export interface DirectoryEntry {
+  /** Base name shown in a browser row (a root crumb carries its full path). */
+  name: string
+  /** Absolute host path — clients never join path segments themselves. */
+  path: string
+  /** Hidden by the host platform's convention (dot-prefixed on POSIX); the client owns whether to show it. */
+  hidden: boolean
+}
+
+/** One directory level plus its ancestry, as a browse backend reports it. */
+export interface DirectoryListing {
+  /** Absolute path of the listed directory. */
+  path: string
+  /** The host account's home directory (breadcrumb "Home" rooting). */
+  home: string
+  /**
+   * Ancestor chain from the filesystem root to the listed directory
+   * inclusive; every crumb is a jump target (crumb `hidden` is always false).
+   */
+  crumbs: DirectoryEntry[]
+  /** Direct child directories, name-sorted; symlinks to directories included. */
+  entries: DirectoryEntry[]
+  /**
+   * True when the backend cut `entries` at its complete-result bound: the
+   * level has more child directories than reported, and the missing rows are
+   * the name-sorted tail (hidden rows count toward the bound).
+   */
+  truncated: boolean
+}
+
+/**
+ * The browse interaction: listing/creation primitives an in-app browser
+ * drives one level at a time. Works for remote clients — nothing renders on
+ * the host display.
+ */
+export interface DirectoryPickerBrowseCapability {
+  kind: 'browse'
+  /**
+   * List one directory level.
+   * @param path - absolute directory to list; absent lists the home directory.
+   * @param signal - caller lifetime; abort stops the scan (a stalled network
+   * directory must not outlive a disconnected caller) and rejects with the
+   * abort reason.
+   * @returns the level's listing with ancestry; backends bound the complete
+   * result, and a cut level reports `truncated`.
+   * @throws {DirectoryPickerError} `directory-unreadable` when the target is not fully
+   * qualified (a wire value must never resolve against the host cwd or, on
+   * Windows, its current drive) or cannot be listed.
+   */
+  list(path?: string, signal?: AbortSignal): Promise<DirectoryListing>
+  /**
+   * Create one child directory under an existing parent.
+   * @param path - absolute existing parent directory.
+   * @param name - single non-blank path segment (no separators, not `.`/`..`).
+   * @returns the created directory's absolute path.
+   * @throws {DirectoryPickerError} `directory-exists` for an existing child,
+   * `directory-create-failed` for a parent that is not fully qualified or any other failure.
+   */
+  createDirectory(path: string, name: string): Promise<string>
+}
+
+/**
+ * Merge-extensible registry of interaction shapes keyed by capability kind: a
+ * new backend declaration-merges its shape here (the entry's `kind` literal
+ * must equal its key) instead of editing this package.
+ */
+export interface DirectoryPickerCapabilities {
+  native: DirectoryPickerNativeCapability
+  browse: DirectoryPickerBrowseCapability
+}
+
+/** Union of interaction shapes a backend can provide, derived from the merge-extensible {@link DirectoryPickerCapabilities} map. */
+export type DirectoryPickerCapability = DirectoryPickerCapabilities[keyof DirectoryPickerCapabilities]
+
+/** Closed failure vocabulary of the browse primitives (mirrored onto the wire by consumers). */
+export type DirectoryPickerErrorCode = 'directory-unreadable' | 'directory-exists' | 'directory-create-failed'
+
+/** Typed failure thrown by browse primitives so consumers can map business codes without string matching. */
+export class DirectoryPickerError extends Error {
+  /**
+   * @param code - closed business code of the failure.
+   * @param path - the absolute path the failure is about.
+   * @param message - operator-facing description.
+   */
+  constructor(readonly code: DirectoryPickerErrorCode, readonly path: string, message: string) {
+    super(message)
+    this.name = 'DirectoryPickerError'
+  }
+}
+
+declare module 'cordis' {
+  interface Context {
+    directoryPicker: DirectoryPicker
+  }
+}
+
+/**
+ * Abstract directory-picking service. Subclass, implement `capability()`, and
+ * load the subclass as a plugin — it registers as `ctx.directoryPicker` (one
+ * implementation per context; loading a second throws, cordis' standard
+ * duplicate-service behavior). The capability object must be stable for the
+ * service lifetime: consumers may capture it across calls.
+ */
+export abstract class DirectoryPicker extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'directoryPicker')
+  }
+
+  /**
+   * The backend's interaction capability.
+   * @returns the discriminated capability consumers switch on.
+   */
+  abstract capability(): DirectoryPickerCapability
+}
+
+export default DirectoryPicker

packages/host/directory-picker/src/invariant.ts

@@ -0,0 +1,22 @@
+/** Package-owned invariant companion for the directory-picker seam. @module @deepseek-ai/dsh-host-directory-picker/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-directory-picker'
+
+/** Cordis companion plugin name. */
+export const name = 'host-directory-picker-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: this stateless seam owns the capability vocabulary, while backends and the RPC consumer own observations. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register the directory-picker invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))