feat(host,client): compose directory picking through slots — dual-face -native, no wire advertisement

ui-workspace's two trigger surfaces each declare a single-kind directory-flow hole (conversation.hero.workspace.directoryFlow / sidebar.workspaces.directoryFlow, same owner contract) and keep only the trigger and the adoption: the Open-local- folder entry renders while the surface's hole is occupied, and the occupant reports one picked path per open through the hole's owner conversation (open/busy/onPicked/onCancel/onError). directory-picker-native becomes dual-face: its browser half fills both holes with a renderless occupant driving host.pickDirectory, so the cordis.yml row that mounts the backend also composes the client interaction — a mismatch is impossible and a second flow package fails at client load. With composition wiring both sides, the host.describe.directoryPicker advertisement and the client's kind branching lose their last consumer: the field, WorkspacesService.directoryPickerKind(), the DirectoryPickerKind wire type, and the picker's per-open describe read are deleted. The connection fixture now serves a deterministic pickDirectory path so the keyless snapshot drives the full pick-then-adopt flow. ui-workspace's hand-rolled declaration deferral is replaced by the deferRegistration helper it duplicated.
2026-07-28 21:51:01 +08:00
parent 51402ac7af
commit 85ca8be104
59 changed files with 614 additions and 385 deletions
--- a/packages/host/README.i18n.yaml
+++ b/packages/host/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/README.md
-README.md: 0810be58fc773a241528656d7f6e826e9c3aabda
-README.zh.md: f9133eee8498594d913b2fe0814ac51d712b678d
+README.md: 7df0ecc4a362be1149188d133233307b1fc48c8a
+README.zh.md: 90d5ea2b0947d2cff9ba06e89b6225b39dad7fce
--- a/packages/host/README.md
+++ b/packages/host/README.md
@@ -9,7 +9,7 @@ The host side of the dsh web GUI: the API gateway every client shape shares, and
 | `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/` | Native-OS-chooser backend (osascript / PowerShell / Zenity+KDialog); host-display only | (registers `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/` | In-app browsing backend: listing/creation primitives over Node stdlib; remote-capable | (registers `ctx.directoryPicker`) |

 `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.
--- a/packages/host/README.zh.md
+++ b/packages/host/README.zh.md
@@ -9,7 +9,7 @@ dsh web GUI 的宿主侧：所有客户端形态共用的 API 网关，以及承
 | `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）；仅宿主屏幕可用 | （注册 `ctx.directoryPicker`） |
+| `directory-picker-native/` | 双面原生交互：OS 选择器后端（osascript／PowerShell／Zenity+KDialog，仅宿主屏幕可用）+ 填入 ui-workspace 目录流 slot 的 browser half | （注册 `ctx.directoryPicker`） |
 | `directory-picker-browse/` | 应用内浏览后端：基于 Node 标准库的列举／创建原语；支持远程 | （注册 `ctx.directoryPicker`） |

 `apiproxy` 在设计上与传输方式无关——它不注册任何路由；载体自行包装 `ctx.apiProxy`。HTTP 载体路由（连同其 `/api` 浏览器信任栅栏）由 [`client/connection`](../client/connection/README.md) 的 node 半侧挂载，这正是该包住在 client 组的原因：它拥有这条线的两端。
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/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: 3639722ab25826af8f7a0721f22d244f78b4210b
-README.zh.md: 3ac81fb412d4e4caf192953bc7a7c846a1d29965
+README.md: ca4471454f5be5d3fcba38ce665d4fb3fbd85e74
+README.zh.md: 953539e1198a52b2bf7cdd9ca1b0d263cc2ae6f9
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -18,7 +18,7 @@ Session model routing is a session-domain contract. `session.models` returns the

 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()`.

-Directory picking delegates to the composed `ctx.directoryPicker` backend ([the directory-picker seam](../directory-picker/README.md)); `host.describe.directoryPicker` advertises the capability kind the client renders for, and a method called outside the advertised kind fails with `directory-picker-unavailable`. Under `native`, `host.pickDirectory` opens one native chooser and returns its selected path (`null` on cancel); this user-paced method is the sole unary call exempt from the default 30-second timeout, and 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.
+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 is the sole unary call exempt from the default 30-second timeout, and 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`.

--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -18,7 +18,7 @@

 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()` 中。

-目录选择委托给组合的 `ctx.directoryPicker` 后端（[目录选择 seam](../directory-picker/README.md)）；`host.describe.directoryPicker` 广播客户端应按其渲染的能力 kind，调用广播之外的方法会以 `directory-picker-unavailable` 失败。在 `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` 请求一样覆盖上述全部方法。
+目录选择委托给组合的 `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` 相同的回环、同源限制。

--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -1009,7 +1009,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
          provider: defaults.provider,
          model: defaults.model,
          attachedSessions: ctx.agents.list().length,
-          directoryPicker: ctx.directoryPicker.capability().kind,
        }))
      },

--- a/packages/host/apiproxy/src/api/host.schema.ts
+++ b/packages/host/apiproxy/src/api/host.schema.ts
@@ -19,7 +19,6 @@ export const hostDescribeValueSchema = z.object({
  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).
-  directoryPicker: z.string(),
 }) satisfies z.ZodType<Wire<ResponseValue<'host.describe'>>>

 /** host.pickDirectory request payload (empty object literal). */
--- a/packages/host/apiproxy/src/api/host.ts
+++ b/packages/host/apiproxy/src/api/host.ts
@@ -5,18 +5,6 @@

 import type { RpcRequest, RpcResponse } from './rpc.ts'

-/**
- * The composed directory-picker interaction the host serves (mirror of the
- * `ctx.directoryPicker` capability kind): `native` = one OS chooser on
- * the host display (`host.pickDirectory`); `browse` = in-app listing/creation
- * primitives (`host.listDirectory`/`host.createDirectory`). Calling a method
- * outside the advertised kind fails with `directory-picker-unavailable`.
- * The wire preserves kinds beyond the two with methods here (a merge-added
- * capability advertises before its RPCs exist); the client's documented
- * default for a kind it does not recognize is to hide the picking affordance.
- */
-export type DirectoryPickerKind = 'native' | 'browse' | (string & {})
-
 /** 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). */
@@ -51,7 +39,6 @@ export interface HostApi {
   * 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);
-   * directoryPicker = the composed picker interaction the client renders for.
   */
  describe(request: RpcRequest<{}>): Promise<RpcResponse<{
    version: string
@@ -59,7 +46,6 @@ export interface HostApi {
    provider?: string
    model?: string
    attachedSessions: number
-    directoryPicker: DirectoryPickerKind
  }>>

  /**
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -29,7 +29,7 @@ export type {
  HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
  ModelReasoningEffort, ModelTarget, SessionModels, SessionProjectionsBlock, SessionsApi, SessionSummary,
 } from './sessions.ts'
-export type { DirectoryEntry, DirectoryListing, DirectoryPickerKind, HostApi } from './host.ts'
+export type { DirectoryEntry, DirectoryListing, HostApi } from './host.ts'
 export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
 export type { CommandsApi, CommandDescriptor } from './commands.ts'
 export type { SkillsApi, SkillEntry } from './skills.ts'
--- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
@@ -192,17 +192,14 @@ describe('host.listDirectory / host.createDirectory', () => {
    })
  })

-  it('refuses the browse RPCs under a native composition and advertises the kind in describe', async () => {
+  it('refuses the browse RPCs under a native composition', async () => {
    const { api } = await harness()
-    expect((await api.host.describe(request({}))).result).toMatchObject({ ok: true, value: { directoryPicker: 'native' } })
    expect((await api.host.listDirectory(request({}))).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' } },
    })
-    const browse = await harness(undefined, BROWSE_STUB)
-    expect((await browse.api.host.describe(request({}))).result).toMatchObject({ ok: true, value: { directoryPicker: 'browse' } })
  })
 })

--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -48,7 +48,7 @@ function scriptedApi(overrides: {
      ...overrides.sessions,
    },
    host: {
-      describe: r => ok(r, { version: '0-test', cwd: '/t', attachedSessions: 0, directoryPicker: 'browse' as const }),
+      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: [] }),
      createDirectory: r => ok(r, { path: '/t/new' }),
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -76,7 +76,7 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
    },
    host: {
      async describe(request) {
-        return { rpcId: request.rpcId, result: { ok: true, value: { version: 'v', cwd: '/w', attachedSessions: 0, directoryPicker: 'native' as const } } }
+        return { rpcId: request.rpcId, result: { ok: true, value: { version: 'v', cwd: '/w', attachedSessions: 0 } } }
      },
      async pickDirectory(request) {
        return { rpcId: request.rpcId, result: { ok: true, value: { path: null } } }
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -218,12 +218,9 @@ describe('sessions domain schemas', () => {
 describe('host domain schemas', () => {
  it('validates describe request/value', () => {
    expect(hostDescribeRequestSchema.parse({})).toEqual({})
-    const value = hostDescribeValueSchema.parse({ version: '1', cwd: '/x', provider: 'p', model: 'm', attachedSessions: 2, directoryPicker: 'native' })
+    const value = hostDescribeValueSchema.parse({ version: '1', cwd: '/x', provider: 'p', model: 'm', attachedSessions: 2 })
    expect(value.attachedSessions).toBe(2)
-    expect(hostDescribeValueSchema.parse({ version: '1', cwd: '/x', attachedSessions: 0, directoryPicker: 'browse' }).provider).toBeUndefined()
-    // A kind beyond the two with methods survives the wire (merge-added
-    // capabilities advertise; the client hides the affordance).
-    expect(hostDescribeValueSchema.parse({ version: '1', cwd: '/x', attachedSessions: 0, directoryPicker: 'other' }).directoryPicker).toBe('other')
+    expect(hostDescribeValueSchema.parse({ version: '1', cwd: '/x', attachedSessions: 0 }).provider).toBeUndefined()
  })

  it('validates the browse listing/creation payloads', () => {
--- a/packages/host/directory-picker-native/README.i18n.yaml
+++ b/packages/host/directory-picker-native/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/directory-picker-native/README.md
-README.md: 8e9d6c7c558a6b33c2a37d504c571fd3eda579bb
-README.zh.md: 68f23698ff0c1a5ee4456a1f121dcf244f09c72b
+README.md: 0b54c651d4f5382021d0f8832ab4f1146b7652c8
+README.zh.md: e5ac2762a691a16a7e6d9d6dd9aefc70a59dcd4f
--- a/packages/host/directory-picker-native/README.md
+++ b/packages/host/directory-picker-native/README.md
@@ -2,7 +2,9 @@

 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 **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

--- a/packages/host/directory-picker-native/README.zh.md
+++ b/packages/host/directory-picker-native/README.zh.md
@@ -2,7 +2,9 @@

 [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`）与平台事实可注入，便于确定性测试。
+[目录选择 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）。

 ## 模型体验

--- a/packages/host/directory-picker-native/package.json
+++ b/packages/host/directory-picker-native/package.json
@@ -15,12 +15,17 @@
      "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"
@@ -31,11 +36,27 @@
    "@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"
+    "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:^",
-    "cordis": "^4.0.0-rc.7"
+    "@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"
  }
 }
--- a/packages/host/directory-picker-native/src/client/index.ts
+++ b/packages/host/directory-picker-native/src/client/index.ts
@@ -0,0 +1,73 @@
+/**
+ * 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 { useEffect, useRef } from 'react'
+import type { ReactElement } from 'react'
+import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: the SlotMap merge declaring the directory-flow holes and their owner contract.
+import type { DirectoryFlowOwnerProps } from '@deepseek-ai/dsh-client-ui-workspace/client'
+
+/** Injected face: the wire call the flow drives (bound in apply's closure). */
+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
+  useEffect(() => {
+    if (!open) {
+      armed.current = false
+      return
+    }
+    if (armed.current) return
+    armed.current = true
+    pick().then(
+      (path) => { if (path === null) outcome.current.onCancel(); else outcome.current.onPicked(path) },
+      (reason: unknown) => { outcome.current.onError(reason instanceof Error ? reason.message : String(reason)) },
+    )
+  }, [open, pick])
+  return null
+}
+
+/** 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(() => {
+    const deferred = [
+      deferRegistration(ctx.slots, 'conversation.hero.workspace.directoryFlow', NativeDirectoryFlow, () =>
+        ctx.slots.register({ name: 'conversation.hero.workspace.directoryFlow', inject: injected }, NativeDirectoryFlow)),
+      deferRegistration(ctx.slots, 'sidebar.workspaces.directoryFlow', NativeDirectoryFlow, () =>
+        ctx.slots.register({ name: 'sidebar.workspaces.directoryFlow', inject: injected }, NativeDirectoryFlow)),
+    ]
+    return () => { for (const entry of deferred) entry.dispose() }
+  }, 'directory-picker-native: flow registrations')
+}
--- a/packages/host/directory-picker-native/src/native-picker.ts
+++ b/packages/host/directory-picker-native/src/native-picker.ts
@@ -1,4 +1,4 @@
-/** Cross-platform native single-directory chooser behind the dialog backend's capability. */
+/** Cross-platform native single-directory chooser behind the native backend's capability. */

 import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'

--- a/packages/host/directory-picker-native/tests/client-flow.spec.tsx
+++ b/packages/host/directory-picker-native/tests/client-flow.spec.tsx
@@ -0,0 +1,123 @@
+// @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, NativeDirectoryFlow } from '../src/client/index.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('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()
+    await act(async () => { resolve('/tmp/project') })
+    expect(second.onPicked).toHaveBeenCalledWith('/tmp/project')
+    expect(first.onPicked).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('')
+  })
+})
--- a/packages/host/directory-picker-native/tsconfig.json
+++ b/packages/host/directory-picker-native/tsconfig.json
@@ -1,19 +1,16 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
  "compilerOptions": {
    "rootDir": "src",
-    "outDir": "lib/types"
+    "outDir": "lib/types",
+    "types": [
+      "node"
+    ]
  },
  "include": [
    "src"
  ],
  "references": [
-    {
-      "path": "../../../vendor/cosmokit"
-    },
-    {
-      "path": "../../../vendor/cordis"
-    },
    {
      "path": "../directory-picker"
    },
@@ -22,6 +19,15 @@
    },
    {
      "path": "../../util/native-command"
+    },
+    {
+      "path": "../../client/ui-slots"
+    },
+    {
+      "path": "../../client/runtime"
+    },
+    {
+      "path": "../../client/ui-workspace"
    }
  ]
 }
--- a/packages/host/directory-picker-native/tsdown.config.ts
+++ b/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'])
--- a/packages/host/directory-picker/README.i18n.yaml
+++ b/packages/host/directory-picker/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/directory-picker/README.md
-README.md: dcac8903522d53a8dd5fd346f124071f0f24b38e
-README.zh.md: 5b7fc15513bf19722bd71bcbb30c6d187d6a71f5
+README.md: 8ef8889c875f5b1d07c015ddef819591041c8d7f
+README.zh.md: 8aefffa7b29a47205ea42d0d1df742d1e1b2502d
--- a/packages/host/directory-picker/README.md
+++ b/packages/host/directory-picker/README.md
@@ -2,7 +2,7 @@

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

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

--- a/packages/host/directory-picker/README.zh.md
+++ b/packages/host/directory-picker/README.zh.md
@@ -2,7 +2,7 @@

 [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 的文档化默认行为是隐藏选择入口而非失败。能力对象在服务生命周期内必须保持稳定。
+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 流程。

 浏览原语以带类型的 `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)。