Merge remote-tracking branch 'origin/master' into feat/gui-full-access-confirmation

# Conflicts:
#	packages/client/ui-conversation/README.i18n.yaml

packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: c0e04e0d1266fd7cb60f4ea24ce9681233e41dfb
-README.zh.md: 193cfbe92e19258eecb62c9f552f37a2f1f28e8f
+README.md: d2e113138e331d54221e59732720a64b398f5c3f
+README.zh.md: 985fbc6e6d46f23e617452b53e8e521ba435b584

packages/client/ui-conversation/README.md

@@ -20,6 +20,8 @@ Tool rows are slots too — the standalone tool ring (`ToolViewRegistry`/`ctx.to
 
 The todo surfaces are two registrations over that shape, both plain registrant plugins with `inject: ['slots', 'conversation']`. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> 已完成 · <active item>` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: 10` — between Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus `"<done>/<total> tasks · <n> in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
 
+`QueueDock` is the terminal input-dock entry at `order: 20`. It hides while empty, renders one pending row directly, and defaults two or more rows to a collapsed `"<n> 条排队消息"` header whose button expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Each visible row remains a single-line preview with its exact-occurrence edit and delete actions.
+
 Per-session UI state for selection and the active view lives in the declared chat store (`stores.ts` `createChatStore`); the InputHub owns the composer state machine and mirrors its draft into that store for persistence. Apply passes one store handle to the strict session subtree, chat view, and details registrations, so each session shares one instance and the framework owns its lifecycle. Components are pure: the framework standard kit supplies `useSession`/`sessionId`, global `useSessions`/`useWorkspaces`, and the input machine's `useInput`/`inputActions`; store faces and inject factories supply the remaining state and callbacks.
 
 The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop button), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `command.hint` locale namespace this package registers and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The composer-bar slot itself is `session-maybe`: with no current session the same bar renders inert (machine faces absent, `disabled` owner prop) instead of swapping in a parallel disabled tree, so the textarea DOM survives the workspace pick; the strict-session control seats simply stay empty until a session exists.

packages/client/ui-conversation/README.zh.md

@@ -20,6 +20,8 @@
 
 todo 两个面就是在该形状上的两个注册项，都是普通注册方插件，`inject: ['slots', 'conversation']`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。`TodoDock` 以 `order: 10` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 和 Queue 之间），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加 `"<已完成>/<总数> tasks · <n> in progress"`（状态图标为 figma 的勾选／进行中／虚线未开始一组）。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。
 
+`QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `"<n> 条排队消息"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。每条可见行仍是单行预览，并提供针对精确单次入队项的编辑和删除操作。
+
 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。
 
 输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止按钮之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `command.hint` locale 命名空间本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 以不可交互状态渲染（machine face 均缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此选择 workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。

packages/client/ui-conversation/src/client/queue/QueueDock.module.css

@@ -20,6 +20,8 @@
   padding-top: 2px;
   border-radius: 14px 14px 0 0;
   background: var(--dsw-specific-tip);
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
 }
 
 .panel::after {
@@ -32,7 +34,52 @@
   pointer-events: none;
 }
 
+.header {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  height: 36px;
+  padding: 4px 16px 4px 12px;
+  border: none;
+  border-radius: 8px;
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
+  text-align: left;
+  cursor: pointer;
+}
+
+.header:focus-visible {
+  outline: 2px solid var(--dsw-alias-label-tertiary);
+  outline-offset: -2px;
+}
+
+.header:disabled {
+  cursor: default;
+}
+
+.count {
+  flex: 1 1 auto;
+  min-width: 0;
+  font-family: Inter, var(--dsw-font-family);
+  font-size: 14px;
+  font-weight: 500;
+  line-height: 24px;
+}
+
+.chevron {
+  display: grid;
+  flex: none;
+  place-items: center;
+  width: 14px;
+  height: 14px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
 .list {
+  max-height: 180px;
+  overflow-y: auto;
   margin: 0;
   padding: 0;
   list-style: none;

packages/client/ui-conversation/src/client/queue/QueueDock.tsx

@@ -4,11 +4,12 @@
 // The 'conversation.input.dock' SlotMap declaration lives in
 // ../contract/slots.ts beside the other input-region slots.
 import type { Context } from 'cordis'
-import { useEffect, useState } from 'react'
+import { useEffect, useId, useState } from 'react'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import {
-  IconCheckOutline16, IconCloseOutline16, IconEditOutline16, IconTrashOutline16,
+  IconCheckOutline16, IconChevronDownOutline14, IconChevronUpOutline14,
+  IconCloseOutline16, IconEditOutline16, IconTrashOutline16,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { QueueAction, QueueItemId } from '../contract/queue.ts'
 import css from './QueueDock.module.css'
@@ -22,18 +23,28 @@ export interface QueueDockInjected {
 /** Full props of a dock entry: InputZone owner share + session standard kit + global seat. */
 export type QueueDockProps = PropsRuntime<'conversation.input.dock'> & QueueDockInjected
 
-/** Queue strip: one preview line per queued message; renders null when the queue is empty. */
+/**
+ * Queue strip: one item renders directly; multiple items default to a
+ * collapsible count header; an empty queue renders nothing.
+ */
 export function QueueDock({ useSession, updateQueue, notify }: QueueDockProps) {
   const queue = useSession(s => s.queue)
   const [editing, setEditing] = useState<{ id: QueueItemId; text: string } | null>(null)
   const [busy, setBusy] = useState<QueueItemId | null>(null)
+  const [collapsed, setCollapsed] = useState(true)
+  const listId = useId()
 
   useEffect(() => {
+    if (queue.length === 0 && !collapsed) setCollapsed(true)
     if (editing !== null && !queue.some(row => row.id === editing.id)) setEditing(null)
-  }, [editing, queue])
+  }, [collapsed, editing, queue])
 
   if (queue.length === 0) return null
 
+  const interactionActive = editing !== null || busy !== null
+  const expanded = !collapsed || interactionActive
+  const listVisible = queue.length === 1 || expanded
+
   const applyAction = async (
     itemId: QueueItemId,
     action: QueueAction,
@@ -63,8 +74,23 @@ export function QueueDock({ useSession, updateQueue, notify }: QueueDockProps) {
   return (
     <div className={css.dock}>
       <div className={css.panel}>
-        <ul className={css.list}>
-          {queue.map(row => (
+        {queue.length > 1 && (
+          <button
+            type="button"
+            className={css.header}
+            aria-controls={listId}
+            aria-expanded={expanded}
+            disabled={interactionActive}
+            onClick={() => { setCollapsed(value => !value) }}
+          >
+            <span className={css.count}>{queue.length} 条排队消息</span>
+            <span className={css.chevron} aria-hidden>
+              {expanded ? <IconChevronDownOutline14 /> : <IconChevronUpOutline14 />}
+            </span>
+          </button>
+        )}
+        <ul id={listId} className={css.list} hidden={!listVisible}>
+          {listVisible && queue.map(row => (
             <li key={row.id} className={css.row}>
               {editing?.id === row.id
                 ? (

packages/client/ui-conversation/tests/queue-dock.spec.tsx

@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 /**
  * QueueDock rendering and operations: authoritative rows, inline editing,
- * removal, failure notices, and live retirement.
+ * collapse state, removal, failure notices, and live retirement.
  */
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react'
@@ -78,16 +78,109 @@ describe('QueueDock', () => {
     expect(container.innerHTML).toBe('')
   })
 
+  it('renders one row directly and defaults multiple rows to a collapsible count header', () => {
+    const single = snapshotWith([row('i-1', 'one')])
+    const source = liveSession(single)
+    const view = render(<QueueDock {...kitFor(single)} useSession={source.useSession} />)
+    expect(view.queryByRole('button', { name: '1 条排队消息' })).toBeNull()
+    expect(view.getByText('one')).toBeTruthy()
+
+    act(() => { source.push(snapshotWith([row('i-1', 'one'), row('i-2', 'two')])) })
+    const header = view.getByRole('button', { name: '2 条排队消息' })
+    expect(header.getAttribute('aria-expanded')).toBe('false')
+    expect(document.getElementById(header.getAttribute('aria-controls')!)).toBeTruthy()
+    expect(view.queryByText('one')).toBeNull()
+    expect(view.queryByText('two')).toBeNull()
+
+    fireEvent.click(header)
+    expect(header.getAttribute('aria-expanded')).toBe('true')
+    expect(view.getByText('one')).toBeTruthy()
+    expect(view.getByText('two')).toBeTruthy()
+
+    fireEvent.click(header)
+    expect(header.getAttribute('aria-expanded')).toBe('false')
+    expect(view.queryByText('one')).toBeNull()
+  })
+
+  it('keeps an active single-row editor visible when another item arrives', () => {
+    const single = snapshotWith([row('i-edit', 'before')])
+    const source = liveSession(single)
+    const view = render(<QueueDock {...kitFor(single)} useSession={source.useSession} />)
+
+    fireEvent.click(view.getByLabelText('编辑排队消息'))
+    fireEvent.change(view.getByLabelText('编辑排队消息'), { target: { value: 'draft' } })
+    act(() => {
+      source.push(snapshotWith([row('i-edit', 'before'), row('i-2', 'second')]))
+    })
+
+    const header = view.getByRole('button', { name: '2 条排队消息' })
+    expect(header).toHaveProperty('disabled', true)
+    expect(header.getAttribute('aria-expanded')).toBe('true')
+    expect(view.getByRole('textbox', { name: '编辑排队消息' })).toHaveProperty('value', 'draft')
+    expect(view.getByText('second')).toBeTruthy()
+
+    fireEvent.click(view.getByLabelText('取消编辑'))
+    expect(header).toHaveProperty('disabled', false)
+    expect(header.getAttribute('aria-expanded')).toBe('false')
+    expect(view.queryByText('second')).toBeNull()
+  })
+
+  it('keeps an in-flight row action visible when another item arrives', async () => {
+    const single = snapshotWith([row('i-remove', 'remove me')])
+    const source = liveSession(single)
+    let finishUpdate: (() => void) | undefined
+    const updateQueue = vi.fn(() => new Promise<void>((resolve) => { finishUpdate = resolve }))
+    const view = render(
+      <QueueDock {...kitFor(single, { updateQueue })} useSession={source.useSession} />,
+    )
+
+    fireEvent.click(view.getByLabelText('删除排队消息'))
+    act(() => {
+      source.push(snapshotWith([row('i-remove', 'remove me'), row('i-2', 'second')]))
+    })
+
+    const header = view.getByRole('button', { name: '2 条排队消息' })
+    expect(header).toHaveProperty('disabled', true)
+    expect(header.getAttribute('aria-expanded')).toBe('true')
+    expect(view.getByText('remove me')).toBeTruthy()
+    expect(view.getByText('second')).toBeTruthy()
+
+    act(() => { finishUpdate?.() })
+    await waitFor(() => {
+      expect(header).toHaveProperty('disabled', false)
+      expect(header.getAttribute('aria-expanded')).toBe('false')
+    })
+  })
+
+  it('defaults a new multi-row queue to collapsed after the prior queue empties', () => {
+    const first = snapshotWith([row('i-1', 'one'), row('i-2', 'two')])
+    const source = liveSession(first)
+    const view = render(<QueueDock {...kitFor(first)} useSession={source.useSession} />)
+    fireEvent.click(view.getByRole('button', { name: '2 条排队消息' }))
+    expect(view.getByText('one')).toBeTruthy()
+
+    act(() => { source.push(snapshotWith([])) })
+    expect(view.container.innerHTML).toBe('')
+    act(() => {
+      source.push(snapshotWith([row('i-3', 'three'), row('i-4', 'four')]))
+    })
+
+    const header = view.getByRole('button', { name: '2 条排队消息' })
+    expect(header.getAttribute('aria-expanded')).toBe('false')
+    expect(view.queryByText('three')).toBeNull()
+  })
+
   it('renders active actions and disables editing for mixed-content rows', () => {
     const snap = snapshotWith([
       row('i-1', '第一条排队消息'),
       row('i-2', null, 'image [image]'),
     ])
     const source = liveSession(snap)
-    const { container } = render(<QueueDock {...kitFor(snap)} useSession={source.useSession} />)
+    const { container, getByRole } = render(<QueueDock {...kitFor(snap)} useSession={source.useSession} />)
+    fireEvent.click(getByRole('button', { name: '2 条排队消息' }))
     expect([...container.querySelectorAll('li')].map(item => item.textContent))
       .toEqual(['第一条排队消息', 'image [image]'])
-    expect(container.querySelectorAll('button')).toHaveLength(4)
+    expect(container.querySelectorAll('button')).toHaveLength(5)
     expect(container.querySelectorAll('[aria-label="编辑排队消息"]')).toHaveLength(2)
     expect(container.querySelectorAll('[aria-label="删除排队消息"]')).toHaveLength(2)
     expect(container.querySelectorAll('[aria-label="立即发送排队消息"]')).toHaveLength(0)
@@ -162,10 +255,11 @@ describe('QueueDock', () => {
     const snap = snapshotWith([row('i-1', 'one'), row('i-2', 'two')])
     const source = liveSession(snap)
     const updateQueue = vi.fn(() => Promise.resolve())
-    const { getAllByLabelText } = render(
+    const { getAllByLabelText, getByRole } = render(
       <QueueDock {...kitFor(snap, { updateQueue })} useSession={source.useSession} />,
     )
 
+    fireEvent.click(getByRole('button', { name: '2 条排队消息' }))
     fireEvent.click(getAllByLabelText('删除排队消息')[0]!)
     await waitFor(() => {
       expect(updateQueue).toHaveBeenCalledWith(iid('i-1'), { kind: 'remove' })

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: 0417a1b8aec36d58ec0f690f397edcf9e015f982
-README.zh.md: 46516d187321029ed739d8c071f246bc1755b125
+README.md: 391adb7009a01d1ec95c8dcb809e8a2065aa0b31
+README.zh.md: 7fc730ed9ec3a067589b277733eb5bb2c42f8b4e

packages/host/README.md

@@ -11,5 +11,6 @@ The host side of the dsh web GUI: the API gateway every client shape shares, and
 | `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

@@ -11,5 +11,6 @@ dsh web GUI 的宿主侧：所有客户端形态共用的 API 网关，以及承
 | `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/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,176 @@
+/**
+ * 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',
+    `    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/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: 8ef8889c875f5b1d07c015ddef819591041c8d7f
-README.zh.md: 8aefffa7b29a47205ea42d0d1df742d1e1b2502d
+README.md: 3749b238b56578ec68610bc13550760aa084bad6
+README.zh.md: 488da5129ec211c2a064156c22a9d0abf04d99be

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

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 的文档化默认行为是隐藏选择入口而非失败。能力对象在服务生命周期内必须保持稳定。client 侧以镜像方式承接该 seam 而不经 wire 广播：每个后端包都是双面包，其 browser half 把匹配的选取交互注册进 ui-workspace 的目录流 slot——因此一行组合同时切换宿主能力与 client 流程。
+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)。
 

packages/host/webserver/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/webserver/README.md
-README.md: e715e4452ddb808f36e6b097eee0fda7b8d0bfb0
-README.zh.md: 05e7e10d7815c8f26bb90597b38b7c6b83a86dbc
+README.md: ace8c09e43dd8544a28d300f97b04610be78bc69
+README.zh.md: b9948e3d387a5da393ff62b9eeacfe310516f46a

packages/host/webserver/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Plain HTTP route-registration plugin (default-exported `HttpServerService`, config `{host, port, distIndex}`): a `node:http` server that listens on activation and provides `ctx.httpServer` — `register(route)` adds a named `exact`/`prefix` route (duplicate `(kind, path)` throws: route patterns are a composition-level contract, so a collision is a misconfiguration; the returned disposer removes the route), `tapIndex(transform)` adds an index.html transform applied in registration order, and `port` reads the listening port (the OS-assigned value when `port` is 0). The match order is fixed — exact over the whole table, then longest prefix, then the static dist fallback with the locked semantics: traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as octet-stream, non-GET/HEAD is 405. Registration order carries no request-facing semantics.
+Plain HTTP route-registration plugin (default-exported `HttpServerService`, config `{host, port, distIndex}`): a `node:http` server that listens on activation and provides `ctx.httpServer` — `register(route)` adds a named `exact`/`prefix` route (duplicate `(kind, path)` throws: route patterns are a composition-level contract, so a collision is a misconfiguration; the returned disposer removes the route), `tapIndex(transform)` adds an index.html transform applied in registration order, `port` reads the listening port (the OS-assigned value when `port` is 0), and `host` reads the configured bind host (composition-time facts other plugins adapt to, e.g. the directory-picker chooser). The match order is fixed — exact over the whole table, then longest prefix, then the static dist fallback with the locked semantics: traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as octet-stream, non-GET/HEAD is 405. Registration order carries no request-facing semantics.
 
 The package knows no harness concepts: the `/api` bridge is the connection plugin's route, plugin bundles and the HMR event stream are the modules/hmr plugins' routes. `host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); `distIndex` is an assembly fact the composing app resolves and injects, never self-resolved (dist location is workspace knowledge of the app). Web (browser) shape only — Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server. This package never prints; the URL line belongs to the shell.
 

packages/host/webserver/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-朴素的 HTTP 路由注册插件（默认导出 `HttpServerService`，配置为 `{host, port, distIndex}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` 路由；重复的 `(kind, path)` 会抛错，因为路由模式是组合层契约，冲突即配置错误；返回的 disposer 会移除该路由。`tapIndex(transform)` 添加按注册顺序应用的 index.html 转换，`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值）。匹配顺序固定不变：先在整张表中匹配精确路由，再匹配最长前缀，最后回退到静态 dist，并遵循固定语义：越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 提供，GET／HEAD 之外的方法返回 405。注册顺序不承载任何面向请求的语义。
+朴素的 HTTP 路由注册插件（默认导出 `HttpServerService`，配置为 `{host, port, distIndex}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` 路由；重复的 `(kind, path)` 会抛错，因为路由模式是组合层契约，冲突即配置错误；返回的 disposer 会移除该路由。`tapIndex(transform)` 添加按注册顺序应用的 index.html 转换，`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。匹配顺序固定不变：先在整张表中匹配精确路由，再匹配最长前缀，最后回退到静态 dist，并遵循固定语义：越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 提供，GET／HEAD 之外的方法返回 405。注册顺序不承载任何面向请求的语义。
 
 该包不了解任何 harness 概念：`/api` 桥接是 connection 插件的路由，插件 bundle 与 HMR（热模块替换）事件流则是 modules／hmr 插件的路由。`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（有意向网络开放）；`distIndex` 是由组合应用解析并注入的组装事实，绝不会自行解析，因为 dist 位置属于应用的工作区知识。该服务器只服务 Web（浏览器）形态；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，而不使用本服务器。该包从不打印内容；URL 行属于 shell。
 

packages/host/webserver/src/index.ts

@@ -78,6 +78,11 @@ export class HttpServerService extends Service {
     return this.listenedPort
   }
 
+  /** The configured bind host (the loopback or all-interfaces literal). */
+  get host(): Config['host'] {
+    return this.config.host
+  }
+
   /**
    * Register a named route. Duplicate (kind, path) throws — route patterns are
    * a composition-level contract, so a collision is a misconfiguration.