Merge remote-tracking branch 'origin/master' into feat/telemetry-otel-plugin

2026-08-29 04:26:38 +00:00 · 2026-07-27 21:32:50 +08:00
parent 0af16387ae 4feb657b45
commit 605df45928
54 changed files with 1221 additions and 193 deletions
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.md
+2026-07-27-question-composer-rows-do-not-shrink.md: 2e0e9b9ca6b141a200ba53d8b6f6f0cad5f7e89d
+2026-07-27-question-composer-rows-do-not-shrink.zh.md: 845d9ee883ad1c2c7abc63a01fce626be924b87f
@@ -0,0 +1,50 @@
+# Agent Note: Question-composer option rows are scroll content, not the slack absorber
+
+Status: implemented
+
+English | [中文](2026-07-27-question-composer-rows-do-not-shrink.zh.md)
+
+## Problem
+
+The question composer card is capped against the viewport (`max-height: min(60vh, 520px)`) and scrolls its option list, so the header and the footer actions stay reachable on long question batches. When the composer seat got short — a small window, or a short viewport with the details panel open — the option rows rendered on top of each other and on top of the question title.
+
+The cap was not the defect; the distribution of the shortfall was. `.options` is a `flex-direction: column` box whose children default to `flex-shrink: 1`, so under-allocation shrank the rows first instead of overflowing the scroll container. A row shrank to its `min-height: 42px` while `.optionCopy` kept the taller intrinsic height its wrapped copy needs (two lines for an option with a description). With `align-items: center`, the copy is then centered on a box shorter than itself and paints outside the row's border box in both directions — over the title above and the next row below. Measured on the shipped client at 900x440: 6.5px of copy outside the row box, growing to 10px at 380px tall, while `.options` reported `scrollHeight === clientHeight` and therefore never offered a scrollbar.
+
+Only rows whose copy wraps can reproduce it. A row whose copy fits on one line has slack between its content and its 42px minimum, so shrinking it stays invisible — which is why the pre-existing e2e fixture (options `Blue`/`Green`, no descriptions) rendered correctly at every size.
+
+## Decision
+
+`.option` and `.custom` declare `flex-shrink: 0`.
+
+The rows are the scroll content of a capped card; the card's overflow belongs to `.options`, which already owns `overflow-y: auto` and `min-height: 0`. Pinning the children makes the shortfall reach that scroll container instead of being absorbed by the rows, which is the behavior the cap was designed for. The alternative — letting rows shrink but keeping the copy inside them — would require clipping or ellipsizing option descriptions at exactly the sizes where the user most needs to read them.
+
+`.header` and `.footer` already carried `flex-shrink: 0` for the same reason at the card level; the option list's children were the missing half of that rule.
+
+## Alternatives considered
+
+**Clip or ellipsize the copy inside a shrunk row (`overflow: hidden` on `.option`).** This removes the overlap with one declaration and no layout rethink. Rejected because it trades a visible defect for a silent one: the row keeps its 42px, and the second line of an option description simply disappears at exactly the sizes where the card is tightest. The description is decision-relevant content, not decoration.
+
+**Drop `align-items: center` for `align-items: flex-start`.** The copy would grow downward only, so it would no longer paint over the title above. It does not fix anything: a shrunk row still overflows onto the row below, and the fix would silently change the vertical alignment of every option row at every size, including the common one.
+
+**Remove the card's `max-height` cap so nothing is ever squeezed.** No shortfall means no distribution problem. Rejected because the cap is what keeps the header and the footer actions on screen for a long question batch; removing it reintroduces the failure the cap exists to prevent (the composer seat is a fixed-height conversation column with `overflow: hidden`, so an uncapped card loses its own submit button instead).
+
+**Cap the wrapped copy at one line (`white-space: nowrap` plus ellipsis on `.description`).** Rows would never wrap, so they could never overflow when shrunk. Rejected for the same reason as clipping, plus it degrades the wide-viewport rendering — where there is ample room — to fix a narrow-viewport defect.
+
+## Consequences
+
+- A squeezed composer scrolls its option list instead of overlapping it: at 900x380 the list reports `scrollHeight` 200 against `clientHeight` 114 and offers a scrollbar, where before it reported them equal and offered none.
+- Option rows keep their full wrapped copy at every viewport size. Nothing is clipped or ellipsized, and the wide-viewport rendering is unchanged (the rule only takes effect when the flex box is under-allocated).
+- The card now reaches its scroll state sooner, since the shortfall is no longer partly absorbed by the rows. That is the intended behavior of the cap, and it means a short seat shows a scrollbar in cases that previously showed a silently mis-painted list.
+- The scenario's recorded question is longer than it needs to be for the round trip it primarily tests. That cost is deliberate: the layout invariant is unfalsifiable without wrapping copy, and a second fixture for one CSS rule would be worse.
+
+## Verification
+
+The web e2e composer scenario asserts the invariant on the live composer at three squeezed seat heights (900x520 / 440 / 380): every option row's children stay inside the row's border box. Two guards keep the assertion from holding vacuously — at least one row must be wrapped (the only shape that overflows) and `.options` must actually be scrolling (proof the seat is genuinely capped). The scenario's recorded question now carries long option descriptions for exactly that reason; without wrapping copy the assertion cannot fail.
+
+Confirmed both directions against the built client: with `flex-shrink: 0` reverted the scenario fails (`scrolls: false`, 6.5px spill), and with it restored it passes. A standalone geometry sweep over 340 viewport sizes (420-1600 x 320-960) went from 86 sizes with copy outside a row box to zero.
+
+The assertion is replay-only: record mode must reach the fixture write rather than aborting on layout. Note that the composer ships as a client-module bundle, so `pnpm run build:web` alone does not pick up a change to `QuestionComposer.module.css` — the package build must run for the browser lane to see it.
+
+Reproducing the shortfall requires a short viewport, not a short container. The cap is `min(60vh, 520px)`, so shrinking the conversation column below the card's own height clips the card without under-allocating it — the rows keep their full height and nothing spills. Anything demonstrating or measuring this defect outside the e2e scenario has to change the viewport.
+
+A stale `lib/` makes the browser lane assert against an older client than the tree, and a `pnpm run build` that fails part-way leaves exactly that: the packages built before the failure are current, the rest are not. Refreshing a golden in that state records the older client's surface. Confirm the build exited zero before capturing, and note that untracked directories under `packages/` are compiled too — a leftover from another branch can fail the build for reasons the diff does not explain.
@@ -0,0 +1,50 @@
+# Agent Note: 提问 composer 的选项行是滚动内容，而非空间不足时的吸收方
+
+Status: implemented
+
+[English](2026-07-27-question-composer-rows-do-not-shrink.md) | 中文
+
+## 问题
+
+提问 composer 的卡片会按视口设上限（`max-height: min(60vh, 520px)`），并让选项列表自行滚动，这样在成批提问时标题和底部操作按钮始终可达。但当 composer 的容器变矮时（窗口较小，或视口偏矮且详情面板处于展开状态），选项行会互相叠在一起，也会叠到问题标题上。
+
+缺陷不在这个高度上限，而在高度不足时由谁来吸收。`.options` 是一个 `flex-direction: column` 的盒子，其子元素默认取 `flex-shrink: 1`，因此空间不足时首先被压缩的是各个选项行，而不是让滚动容器产生溢出。一行会被压到它的 `min-height: 42px`，而 `.optionCopy` 仍保持文案折行后所需的更大固有高度（带描述的选项会占两行）。由于 `align-items: center`，文案于是以一个比自身更矮的盒子为基准居中，并向上下两个方向画到该行边框盒之外——向上盖住标题，向下盖住下一行。在实际发布的客户端上于 900x440 处实测：文案有 6.5px 落在行盒之外，视口高度降到 380px 时增至 10px，而 `.options` 报告的 `scrollHeight` 等于 `clientHeight`，因此始终不会给出滚动条。
+
+只有文案会折行的选项行才能复现该问题。文案单行即可容纳的行，其内容与 42px 最小高度之间尚有余量，被压缩也看不出来——这正是既有 e2e fixture（测试前置数据）（选项为 `Blue`／`Green`，无描述）在任何尺寸下都渲染正常的原因。
+
+## 决策
+
+`.option` 与 `.custom` 声明 `flex-shrink: 0`。
+
+在设有高度上限的卡片中，这些行是滚动内容；卡片的溢出归 `.options` 承担，它本就持有 `overflow-y: auto` 与 `min-height: 0`。把子元素固定住之后，高度不足会传导到那个滚动容器，而不再被行本身吸收，这正是该高度上限设计时想要的行为。另一种做法是允许行被压缩，但把文案约束在行内，那就必须在用户最需要阅读选项描述的尺寸上对其做裁剪或省略号处理。
+
+`.header` 与 `.footer` 出于同样的原因，已在卡片层级带有 `flex-shrink: 0`；选项列表的子元素正是这条规则缺失的另一半。
+
+## 曾考虑的替代方案
+
+**在被压缩的行内裁剪文案或加省略号（对 `.option` 设 `overflow: hidden`）。** 这样一条声明就能消除重叠，且不必重新考虑布局。之所以否决：它把一个可见缺陷换成了一个无声缺陷——行仍保持 42px，而选项描述的第二行会在卡片最紧张的那些尺寸上直接消失。描述属于影响决策的内容，不是装饰。
+
+**把 `align-items: center` 改为 `align-items: flex-start`。** 文案就只会向下生长，因此不再向上盖住标题。但这什么也没修好：被压缩的行依然会溢出到下一行上，而且这一改动会在所有尺寸下（包括常见尺寸）无声改变每个选项行的垂直对齐。
+
+**移除卡片的 `max-height` 上限，使其永远不会被压缩。** 没有高度不足，就没有分配问题。之所以否决：正是这个上限保证成批提问时标题和底部操作按钮留在屏幕内；移除它会重新引入该上限本就为之存在的失败（composer 所处的容器是一个固定高度、`overflow: hidden` 的会话列，因此不设上限的卡片会连自己的提交按钮一起丢掉）。
+
+**把折行文案限制为单行（对 `.description` 设 `white-space: nowrap` 加省略号）。** 行永远不会折行，因此被压缩时也永远不会溢出。否决理由与裁剪相同，此外它还为了修一个窄视口缺陷，而牺牲了空间充裕的宽视口渲染效果。
+
+## 后果
+
+- 被压缩的 composer 会滚动其选项列表，而不是让它互相重叠：在 900x380 处，该列表报告 `scrollHeight` 为 200、`clientHeight` 为 114，并给出滚动条；此前两者相等，不给滚动条。
+- 选项行在任何视口尺寸下都保留完整的折行文案。不裁剪、不加省略号，宽视口下的渲染保持不变（该规则仅在 flex 盒子空间不足时才生效）。
+- 由于高度不足不再被行部分吸收，卡片现在更早进入滚动状态。这正是该高度上限想要的行为，也意味着在此前只会无声画错列表的情形下，矮容器现在会显示滚动条。
+- 该场景录制的问题，比它主要测试的那次往返所需的长度更长。这个代价是有意付出的：没有折行文案，该布局不变式无法被证伪，而为一条 CSS 规则再加一份 fixture 会更糟。
+
+## 验证
+
+Web e2e 的 composer 场景会在三个被压缩的容器高度（900x520／440／380）上，对活动的 composer 断言该运行时不变式：每个选项行的子元素都留在该行的边框盒之内。两道守卫防止该断言空洞地成立——必须至少有一行处于折行状态（这是唯一会溢出的形态），且 `.options` 必须确实处在滚动状态（证明容器确实触及了高度上限）。该场景录制的问题现在带有较长的选项描述，正是为此；没有折行文案，这条断言不可能失败。
+
+在构建产物客户端上双向确认过：撤销 `flex-shrink: 0` 后该场景失败（`scrolls: false`，6.5px 溢出），恢复后通过。一次覆盖 340 种视口尺寸（420-1600 x 320-960）的独立几何遍历，从 86 种尺寸存在文案落在行盒之外，降到 0 种。
+
+该断言仅在回放模式下执行：录制模式必须走到写入 fixture 那一步，而不是在布局检查处中断。另需注意，composer 以客户端模组包的形式发布，因此单跑 `pnpm run build:web` 不会带上对 `QuestionComposer.module.css` 的改动——必须执行包构建，浏览器测试通道才能看到它。
+
+要复现这种空间不足，需要的是矮视口，而不是矮容器。高度上限为 `min(60vh, 520px)`，因此把会话列压到比卡片自身高度更矮，只会裁剪卡片，而不会让它空间不足——各行仍保持完整高度，也不会有任何溢出。凡是在 e2e 场景之外演示或测量该缺陷的手段，都必须改变视口。
+
+`lib/` 陈旧会让浏览器测试通道对着一个比工作树更旧的客户端做断言，而中途失败的 `pnpm run build` 留下的正是这种状态：失败之前构建的那些包是新的，其余不是。在这种状态下刷新 golden，记录下来的是旧客户端的界面。抓取之前先确认构建以 0 退出；另需注意 `packages/` 下的未跟踪目录同样会被编译——来自另一个分支的遗留物可能以 diff 无法解释的原因让构建失败。
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.md
+2026-07-27-native-workspace-directory-picker.md: 847b7a7c7844a47e534183008acfdc32e2e08125
+2026-07-27-native-workspace-directory-picker.zh.md: e484a2ba5860d43925aba82be31c803716a33bc5
@@ -0,0 +1,51 @@
+# Agent Note: Native workspace directory picker
+
+Status: implemented
+
+English | [中文](2026-07-27-native-workspace-directory-picker.zh.md)
+
+## Problem
+
+The desktop GUI asks users to type an absolute path when they add an existing workspace. This is slower and more error-prone than choosing a directory with the operating system's native picker. The GUI is delivered through the local Web carrier, so opening a native dialog also creates a privileged boundary that ordinary remote requests must not cross.
+
+## Decision
+
+Add a single-folder `host.pickDirectory` RPC and expose it through `WorkspacesService`. The workspace menu presents two flat actions: **Open local folder...** and **Create a new workspace**. Selecting a folder reuses the existing `workspace.create({ path })` flow, selects the returned workspace, and starts a blank session.
+
+The workspace manager must upsert the returned workspace before the selection callback runs. A newly adopted directory therefore renders its basename immediately. Reopening an already registered path preserves its existing workspace title.
+
+## Interaction contract
+
+- The picker accepts one directory on macOS, Windows, and Linux.
+- Cancelling the system dialog is silent and returns `null`.
+- A duplicate path selects the existing workspace.
+- A different path whose derived title conflicts with another workspace shows a focused error with **Choose again** and **Cancel** actions.
+- Other picker failures show a compact retryable error.
+- The existing create-by-name flow remains unchanged.
+
+## Host boundary
+
+The native dialog RPC is accepted only from a loopback socket with same-origin browser metadata. The RPC does not use the default 30-second request timeout because a system dialog may remain open indefinitely; caller and connection aborts still propagate to the platform process.
+
+Platform adapters invoke native tools without a shell:
+
+- macOS: `osascript` and the system folder chooser.
+- Windows: PowerShell in STA mode and `FolderBrowserDialog`.
+- Linux: `zenity`, with `kdialog` as a fallback when Zenity is unavailable.
+
+## Alternatives considered
+
+- A custom directory browser duplicates operating-system behavior and permissions, and belongs to the Web implementation rather than this desktop-only change.
+- Reusing the manual path field keeps the current error-prone interaction.
+- Adding authentication infrastructure for one local native dialog would expand the change beyond its threat model; loopback and same-origin checks are sufficient for this carrier.
+
+## Consequences
+
+The current GUI opens one local folder through a native picker on macOS, Windows, and Linux. Cancelling changes no state, failures remain retryable, and duplicate paths are idempotent while title conflicts require an explicit new choice. The selected workspace and its displayed name refresh before a new blank session starts. Existing workspace creation by name remains available.
+
+The added host, runtime, component, and GUI tests cover the native boundary, request trust checks, cancellation and failure handling, existing-path reuse, title conflicts, and the immediate visible-name update. The privileged RPC remains specific to the local desktop carrier; a remote Web directory browser is outside this decision.
+
+## Risks
+
+- Linux desktop environments may provide neither supported picker. The GUI reports that limitation instead of falling back to a typed path.
+- Browser metadata varies outside the supported local carrier. The endpoint intentionally rejects requests that cannot prove the required local same-origin context.
@@ -0,0 +1,51 @@
+# Agent Note: 原生工作区目录选择器
+
+Status: implemented
+
+[English](2026-07-27-native-workspace-directory-picker.md) | 中文
+
+## 问题
+
+桌面端 GUI 在添加现有工作区时要求用户输入绝对路径。相比使用操作系统原生选择器选取目录，这种操作速度更慢，也更容易出错。GUI 由本地 Web 载体提供，因此打开原生对话框也会形成一条特权边界，普通远程请求不得越过这条边界。
+
+## 决策
+
+新增一个用于选择单个文件夹的 `host.pickDirectory` RPC，并通过 `WorkspacesService` 暴露该 RPC。工作区菜单提供两个平铺操作：**打开本地文件夹…** 和 **创建新工作区**。选定文件夹后，系统复用现有的 `workspace.create({ path })` 流程，选中返回的工作区，并启动一个空白会话。
+
+工作区管理器必须在选择回调运行前插入或更新返回的工作区。因此，新纳入的目录会立即显示其 basename。再次打开已注册的路径时，则保留该工作区现有的标题。
+
+## 交互契约
+
+- 在 macOS、Windows 和 Linux 上，选择器一次只允许选择一个目录。
+- 取消系统对话框不会显示提示，并返回 `null`。
+- 路径重复时，选中现有工作区。
+- 如果路径不同，但其派生标题与另一个工作区冲突，则显示明确指出该冲突的错误提示，其中包含 **重新选择** 和 **取消** 操作。
+- 选择器的其他故障会显示简洁且可重试的错误提示。
+- 现有的按名称创建流程保持不变。
+
+## 宿主边界
+
+只有来自回环套接字、且携带同源浏览器元数据的请求才能调用原生对话框 RPC。该 RPC 不使用默认的 30 秒请求超时，因为系统对话框可能无限期保持打开；调用方中止或连接中止仍会传递至平台进程。
+
+平台适配器不经 shell，直接调用原生工具：
+
+- macOS：`osascript` 和系统文件夹选择器。
+- Windows：采用 STA 模式的 PowerShell 和 `FolderBrowserDialog`。
+- Linux：使用 `zenity`；Zenity 不可用时回退到 `kdialog`。
+
+## 考虑过的替代方案
+
+- 自定义目录浏览器会重复实现操作系统的行为和权限逻辑，而且应属于 Web 实现，而非本次仅面向桌面端的变更。
+- 继续使用手动路径字段会保留当前容易出错的交互方式。
+- 为一个本地原生对话框添加身份认证基础设施，会使变更范围超出其威胁模型；对当前载体而言，回环与同源检查已经足够。
+
+## 后果
+
+当前 GUI 可以在 macOS、Windows 和 Linux 上通过原生选择器打开一个本地文件夹。取消操作不会改变任何状态，故障仍可重试；重复路径的处理具有幂等性，标题冲突则要求用户明确重新选择。选中的工作区及其显示名称会在启动新的空白会话前完成刷新。现有的按名称创建工作区功能仍可使用。
+
+新增的宿主、运行时、组件和 GUI 测试覆盖原生边界、请求信任校验、取消与故障处理、已有路径复用、标题冲突和可见名称即时更新。该特权 RPC 仍仅面向本地桌面载体；远程 Web 目录浏览器不属于本次决策范围。
+
+## 风险
+
+- Linux 桌面环境可能不提供任何一种受支持的选择器。GUI 会报告这项限制，而不会回退到要求用户输入路径。
+- 在受支持的本地载体之外，浏览器元数据可能有所不同。对于无法证明其满足所需本地同源上下文的请求，该端点会按设计拒绝。
@@ -28,7 +28,10 @@ const UI_EXPECTED = join(SNAPSHOT_DIR, 'ui.expected.md')
 const ANSWERED_EXPECTED = join(SNAPSHOT_DIR, 'answered.expected.md')
 const MODE = webSnapshotMode()

-const PROMPT = 'Use the ask_user_question tool to ask me exactly one question with id "color", question "Which color do you prefer?", header "Pick one", and options labeled "Blue" and "Green". After I answer, reply with the single word DONE and stop.'
+// The options carry long descriptions on purpose: the squeeze assertion below
+// needs option copy that WRAPS, which is the only shape that reproduces a
+// collapsed row painting its copy outside its own box.
+const PROMPT = 'Use the ask_user_question tool to ask me exactly one question with id "color", question "Which color do you prefer?", header "Pick one", and two options: label "Blue" with description "A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.", and label "Green" with description "A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions." After I answer, reply with the single word DONE and stop.'

 describe('web e2e: resident question composer round trip', () => {
  let scaffold: WebScaffold
@@ -79,6 +82,48 @@ describe('web e2e: resident question composer round trip', () => {
      await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
    }

+    // Squeezed card: the option rows are the capped card's scroll content, so
+    // shrinking the seat must push overflow into the option list, never
+    // collapse a row below the height its own copy needs — a collapsed row
+    // paints its centered copy outside the row box, over the title and the
+    // neighbouring rows. Measured on the live composer at seat heights that
+    // force the cap, then restored for the answer gesture below. Replay only:
+    // record mode must reach the recording write below, not abort on layout.
+    if (MODE !== 'record') {
+      const original = page.viewportSize() ?? { width: 1680, height: 1000 }
+      for (const height of [520, 440, 380]) {
+        await page.setViewportSize({ width: 900, height })
+        const squeeze = await composer.evaluate((card) => {
+          // Role/ARIA selectors, not the CSS-module class names: the built
+          // client hashes those.
+          const rows = [...card.querySelectorAll<HTMLElement>(
+            '[role="radio"], [role="checkbox"], [aria-expanded]',
+          )]
+          const spill = rows.map(row => Math.max(...[...row.children].map((child) => {
+            const box = row.getBoundingClientRect()
+            const inner = child.getBoundingClientRect()
+            return Math.max(box.top - inner.top, inner.bottom - box.bottom)
+          })))
+          const list = rows[0]?.parentElement ?? null
+          return {
+            rows: rows.length,
+            spill: Math.max(...spill),
+            // Wrapped copy is the shape that overflows a collapsed row, and a
+            // scrolling list proves the seat is genuinely capped. Without both,
+            // the spill assertion would hold vacuously.
+            wrappedRows: rows.filter(row => row.getBoundingClientRect().height > 42).length,
+            scrolls: list === null ? false : list.scrollHeight > list.clientHeight,
+          }
+        })
+        expect(squeeze.rows).toBeGreaterThan(0)
+        expect(squeeze.wrappedRows).toBeGreaterThan(0)
+        expect(squeeze.scrolls).toBe(true)
+        // Sub-pixel tolerance: every row's copy stays inside its border box.
+        expect(squeeze.spill).toBeLessThan(0.6)
+      }
+      await page.setViewportSize(original)
+    }
+
    await composer.getByRole('radio', { name: 'Blue' }).click()
    // Submit: Enter on the focused option (the composer's documented submit).
    await composer.getByRole('radio', { name: 'Blue' }).press('Enter')
@@ -128,7 +128,6 @@ it('locked view state, connectWorkspace unlock, /echo claim chain, and blank-on-
  // Session+Agent and the provider swaps in the live blank-session hero.
  fireEvent.click(screen.getAllByRole('button', { name: 'Choose workspace' })
    .find(el => el.getAttribute('aria-haspopup') === 'menu')!)
-  fireEvent.click(await screen.findByRole('menuitem', { name: 'Create workspace' }))
  fireEvent.click(await screen.findByRole('menuitem', { name: 'Create a new workspace' }))
  const dialog = await screen.findByRole('dialog', { name: 'Create a new workspace' })
  fireEvent.change(within(dialog).getByRole('textbox', { name: 'New workspace name' }), {
@@ -6,18 +6,24 @@
    - tab "Chat" [selected]
    - tab "Trajectory"
    - tab "Waterfall"
- text: Use the ask_user_question tool to ask me exactly one question with id "color", question "Which color do you prefer?", header "Pick one", and options labeled "Blue" and "Green". After I answer, reply with the single word DONE and stop.
- button "Think The user wants me to use the ask_user_question tool to ask a specific question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and options labeled \"Blue\" and \"Green\". Let me do exactly that.":
+- text: "Use the ask_user_question tool to ask me exactly one question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" After I answer, reply with the single word DONE and stop."
+- button "复制":
  - img
-  - text: Think The user wants me to use the ask_user_question tool to ask a specific question with id "color", question "Which color do you prefer?", header "Pick one", and options labeled "Blue" and "Green". Let me do exactly that.
+- button "在新对话中分支":
+  - img
+- button "编辑":
+  - img
+- button "Think The user wants me to use the ask_user_question tool with specific parameters. Let me do exactly that.":
+  - img
+  - text: Think The user wants me to use the ask_user_question tool with specific parameters. Let me do exactly that.
 - button:
  - img
- text: "Tool call ask_user_question · {\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"options\": [{\"label\": \"Blue\"}, {\"label\": \"Green\"}]}]}"
- button "Think The user answered \"Blue\". I need to reply with the single word DONE and stop.":
+- text: "Tool call ask_user_question · {\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"options\": [{\"label\": \"Blue\", \"description\": \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\"}, {\"label\": \"Green\", \"description\": \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\"}]}]}"
+- button "Think The user answered \"Blue\". I should now reply with the single word DONE and stop.":
  - img
-  - text: Think The user answered "Blue". I need to reply with the single word DONE and stop.
+  - text: Think The user answered "Blue". I should now reply with the single word DONE and stop.
 - paragraph: DONE
- text: cache hit 99% · 15,978 tokens · 1 turns · 2 steps
+- text: cache hit 95% · 8,769 tokens · 1 turns · 2 steps
 - textbox "Message the agent"
 - button "Add attachment":
  - img
@@ -1,31 +1,31 @@
-{"type":"session","version":0,"id":"{{sessionId}}","createdAt":1785001700711,"cwd":"{{cwd}}/workspace"}
-{"type":"turn/start","seq":0,"time":1785001700724,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user","rpcId":"{{rpcId}}"}}}}
-{"type":"user/message","seq":1,"time":1785001700725,"data":{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and options labeled \"Blue\" and \"Green\". After I answer, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpcId}}"}},"surfaceOp":"append"}
-{"type":"session/title","seq":2,"time":1785001700727,"data":{"title":"Use the ask_user_question tool to","messageSeqs":[1],"source":{"kind":"fallback"}}}
-{"type":"step/start","seq":3,"time":1785001700783,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":4,"time":1785001700784,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}","messagePrefix":["{{messagePrefix}}"]},"reason":"initial"}}
-{"type":"assistant/chunk","seq":5,"time":1785001701372,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
-{"type":"reasoning-chunks","seq0":6,"time0":1785001701373,"data":{"turn":1,"step":1,"index":0,"dt":[117,23,0,0,0,1,26,1,0,0,0,0,25,0,0,0,27,1,24,1,0,0,0,27,0,0,0,0,1,34,0,0,0,0,1,17,0,0,0,1,0,27,1,0,0,28,0,0,22,0],"texts":["The"," user"," wants"," me"," to"," use"," the"," ask","_user","_","question"," tool"," to"," ask"," a"," specific"," question"," with"," id"," \"","color","\","," question"," \"","Which"," color"," do"," you"," prefer","?\","," header"," \"","Pick"," one","\","," and"," options"," labeled"," \"","Blue","\""," and"," \"","Green","\"."," Let"," me"," do"," exactly"," that","."]}}
-{"type":"assistant/chunk","seq":57,"time":1785001701858,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
-{"type":"tool-call-chunks","seq0":58,"time0":1785001701858,"data":{"turn":1,"step":1,"index":1,"dt":[27,1,0,0,0,24,1,0,0,28,0,0,0,0,1,24,0,0,1,0,0,26,0,0,0,0,0,26,0,1,0,0,0,25,0,0,0,0,3,23,1,0,0,0,0,26,1,26],"id":"call_00_evaSJ80aahxJCcpWrfA00887","name":"ask_user_question","args":["","{","\"","questions","\"",": ","[","{\"","id","\":"," \"","color","\","," \"","question","\":"," \"","Which"," color"," do"," you"," prefer","?\","," \"","header","\":"," \"","Pick"," one","\","," \"","options","\":"," [","{\"","label","\":"," \"","Blue","\"},"," {\"","label","\":"," \"","Green","\"","}]","}]","}"]}}
-{"type":"assistant/chunk","seq":107,"time":1785001702154,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to use the ask_user_question tool to ask a specific question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and options labeled \"Blue\" and \"Green\". Let me do exactly that."}}}}
-{"type":"assistant/chunk","seq":108,"time":1785001702155,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_evaSJ80aahxJCcpWrfA00887","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"options\": [{\"label\": \"Blue\"}, {\"label\": \"Green\"}]}]}"}}}}
-{"type":"assistant/chunk","seq":109,"time":1785001702155,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":23,"outputTokens":138,"cacheReadTokens":7808,"reasoningTokens":51}}}}
-{"type":"assistant/chunk","seq":110,"time":1785001702155,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":111,"time":1785001702159,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to use the ask_user_question tool to ask a specific question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and options labeled \"Blue\" and \"Green\". Let me do exactly that."},{"type":"tool-call","id":"call_00_evaSJ80aahxJCcpWrfA00887","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"options\": [{\"label\": \"Blue\"}, {\"label\": \"Green\"}]}]}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":23,"outputTokens":138,"cacheReadTokens":7808,"reasoningTokens":51}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110],"surfaceOp":"append"}
-{"type":"tool/call","seq":112,"time":1785001702160,"data":{"turn":1,"step":1,"callId":"call_00_evaSJ80aahxJCcpWrfA00887","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"options\": [{\"label\": \"Blue\"}, {\"label\": \"Green\"}]}]}"}}
-{"type":"tool/result","seq":113,"time":1785001702566,"data":{"turn":1,"step":1,"callId":"call_00_evaSJ80aahxJCcpWrfA00887","content":[{"type":"text","text":"{\"answers\":[{\"id\":\"color\",\"selected\":[\"Blue\"]}]}"}],"isError":false},"sourceEventSeqs":[112],"surfaceOp":"append"}
-{"type":"step/end","seq":114,"time":1785001702568,"data":{"turn":1,"step":1}}
-{"type":"step/start","seq":115,"time":1785001702569,"data":{"turn":1,"step":2}}
-{"type":"assistant/chunk","seq":116,"time":1785001702948,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
-{"type":"reasoning-chunks","seq0":117,"time0":1785001702949,"data":{"turn":1,"step":2,"index":0,"dt":[84,26,1,0,0,0,0,29,0,0,22,0,1,0,0,0,27,1],"texts":["The"," user"," answered"," \"","Blue","\"."," I"," need"," to"," reply"," with"," the"," single"," word"," D","ONE"," and"," stop","."]}}
-{"type":"assistant/chunk","seq":136,"time":1785001703140,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":137,"time":1785001703140,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"D"}}}
-{"type":"assistant/chunk","seq":138,"time":1785001703140,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
-{"type":"assistant/chunk","seq":139,"time":1785001703140,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user answered \"Blue\". I need to reply with the single word DONE and stop."}}}}
-{"type":"assistant/chunk","seq":140,"time":1785001703141,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}}
-{"type":"assistant/chunk","seq":141,"time":1785001703141,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":179,"outputTokens":22,"cacheReadTokens":7808,"reasoningTokens":19}}}}
-{"type":"assistant/chunk","seq":142,"time":1785001703141,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":143,"time":1785001703141,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The user answered \"Blue\". I need to reply with the single word DONE and stop."},{"type":"text","text":"DONE"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":179,"outputTokens":22,"cacheReadTokens":7808,"reasoningTokens":19}},"sourceEventSeqs":[116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142],"surfaceOp":"append"}
-{"type":"step/end","seq":144,"time":1785001703142,"data":{"turn":1,"step":2}}
-{"type":"turn/end","seq":145,"time":1785001703142,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":1785150167878,"cwd":"{{cwd}}/workspace"}
+{"type":"turn/start","seq":0,"time":1785150167924,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user","rpcId":"{{rpcId}}"}}}}
+{"type":"user/message","seq":1,"time":1785150167925,"data":{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" After I answer, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpcId}}"}},"surfaceOp":"append"}
+{"type":"session/title","seq":2,"time":1785150167927,"data":{"title":"Use the ask_user_question tool to","messageSeqs":[1],"source":{"kind":"fallback"}}}
+{"type":"step/start","seq":3,"time":1785150167928,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":4,"time":1785150167929,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":5,"time":1785150168452,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"reasoning-chunks","seq0":6,"time0":1785150168452,"data":{"turn":1,"step":1,"index":0,"dt":[87,26,1,0,0,0,38,0,0,0,0,1,12,27,0,27,0,0,1,25,0],"texts":["The"," user"," wants"," me"," to"," use"," the"," ask","_user","_","question"," tool"," with"," specific"," parameters","."," Let"," me"," do"," exactly"," that","."]}}
+{"type":"assistant/chunk","seq":28,"time":1785150168775,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":29,"time0":1785150168776,"data":{"turn":1,"step":1,"index":1,"dt":[25,1,0,0,0,25,0,0,0,26,1,0,0,0,0,25,1,0,0,0,0,25,1,0,0,0,0,25,1,0,0,0,1,25,0,0,0,0,1,25,1,0,0,0,0,25,1,0,0,26,0,0,1,0,24,1,0,0,0,1,26,1,0,0,0,0,25,0,1,0,0,0,25,1,0,0,25,0,0,0,0,1,25,0,0,1,0,0,25,0,0,0,1,0,26,1,24],"id":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","args":["","{","\"","questions","\"",": ","[","{\"","id","\":"," \"","color","\","," \"","question","\":"," \"","Which"," color"," do"," you"," prefer","?\","," \"","header","\":"," \"","Pick"," one","\","," \"","options","\":"," [","{\"","label","\":"," \"","Blue","\","," \"","description","\":"," \"","A"," cool"," recessive"," hue"," that"," reads"," as"," calm"," and"," trustworthy"," in"," long"," reading"," sessions"," and"," dense"," dash","boards",".\"","},"," {\"","label","\":"," \"","Green","\","," \"","description","\":"," \"","A"," rest","ful"," mid","-spect","rum"," hue"," with"," the"," highest"," perceived"," brightness",","," easiest"," on"," the"," eye"," over"," long"," sessions",".\"","}]","}]","}"]}}
+{"type":"assistant/chunk","seq":127,"time":1785150169308,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to use the ask_user_question tool with specific parameters. Let me do exactly that."}}}}
+{"type":"assistant/chunk","seq":128,"time":1785150169308,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"options\": [{\"label\": \"Blue\", \"description\": \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\"}, {\"label\": \"Green\", \"description\": \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\"}]}]}"}}}}
+{"type":"assistant/chunk","seq":129,"time":1785150169308,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":113,"outputTokens":158,"cacheReadTokens":4096,"reasoningTokens":22}}}}
+{"type":"assistant/chunk","seq":130,"time":1785150169308,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":131,"time":1785150169311,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to use the ask_user_question tool with specific parameters. Let me do exactly that."},{"type":"tool-call","id":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"options\": [{\"label\": \"Blue\", \"description\": \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\"}, {\"label\": \"Green\", \"description\": \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\"}]}]}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":113,"outputTokens":158,"cacheReadTokens":4096,"reasoningTokens":22}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130],"surfaceOp":"append"}
+{"type":"tool/call","seq":132,"time":1785150169312,"data":{"turn":1,"step":1,"callId":"call_00_Cijldc88LYmVPCXYUsRq1617","name":"ask_user_question","arguments":"{\"questions\": [{\"id\": \"color\", \"question\": \"Which color do you prefer?\", \"header\": \"Pick one\", \"options\": [{\"label\": \"Blue\", \"description\": \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\"}, {\"label\": \"Green\", \"description\": \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\"}]}]}"}}
+{"type":"tool/result","seq":133,"time":1785150169787,"data":{"turn":1,"step":1,"callId":"call_00_Cijldc88LYmVPCXYUsRq1617","content":[{"type":"text","text":"{\"answers\":[{\"id\":\"color\",\"selected\":[\"Blue\"]}]}"}],"isError":false},"sourceEventSeqs":[132],"surfaceOp":"append"}
+{"type":"step/end","seq":134,"time":1785150169790,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":135,"time":1785150169790,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":136,"time":1785150170605,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"reasoning-chunks","seq0":137,"time0":1785150170606,"data":{"turn":1,"step":2,"index":0,"dt":[111,29,0,0,0,1,34,0,0,17,1,29,0,0,0,0,1,26],"texts":["The"," user"," answered"," \"","Blue","\"."," I"," should"," now"," reply"," with"," the"," single"," word"," D","ONE"," and"," stop","."]}}
+{"type":"assistant/chunk","seq":156,"time":1785150170856,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":157,"time":1785150170856,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"D"}}}
+{"type":"assistant/chunk","seq":158,"time":1785150170856,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":159,"time":1785150170856,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user answered \"Blue\". I should now reply with the single word DONE and stop."}}}}
+{"type":"assistant/chunk","seq":160,"time":1785150170856,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":161,"time":1785150170856,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":284,"outputTokens":22,"cacheReadTokens":4096,"reasoningTokens":19}}}}
+{"type":"assistant/chunk","seq":162,"time":1785150170856,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":163,"time":1785150170857,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The user answered \"Blue\". I should now reply with the single word DONE and stop."},{"type":"text","text":"DONE"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":284,"outputTokens":22,"cacheReadTokens":4096,"reasoningTokens":19}},"sourceEventSeqs":[136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162],"surfaceOp":"append"}
+{"type":"step/end","seq":164,"time":1785150170858,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":165,"time":1785150170858,"data":{"turn":1,"reason":{"kind":"completed"}}}
@@ -10,10 +10,10 @@
    - img
  - radiogroup:
    - radio "Blue":
-      - text: 1 Blue
+      - text: 1 Blue A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.
      - img
    - radio "Green":
-      - text: 2 Green
+      - text: 2 Green A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.
      - img
    - button "其他，请填写自定义答案":
      - img
@@ -45,7 +45,6 @@ export function probeFreePort(): Promise<number> {
 */
 export async function connectFreshWorkspace(page: Page, name = 'workspace'): Promise<void> {
  await page.getByRole('button', { name: 'Choose workspace' }).click()
-  await page.getByRole('menuitem', { name: 'Create workspace' }).hover()
  await page.getByRole('menuitem', { name: 'Create a new workspace' }).click()
  const dialog = page.getByRole('dialog', { name: 'Create a new workspace' })
  await dialog.waitFor({ timeout: 10_000 })
@@ -134,10 +134,9 @@ function setComposerText(composer: HTMLElement, value: string): void {
  expect((composer as HTMLTextAreaElement).value).toBe(value)
 }

-/** Drive the picker's create flow: chip → Create workspace → name dialog. */
+/** Drive the picker's create flow: chip → Create a new workspace → name dialog. */
 async function createWorkspaceViaPicker(name: string): Promise<void> {
  fireEvent.click(workspaceChip())
-  fireEvent.click(await screen.findByRole('menuitem', { name: 'Create workspace' }))
  fireEvent.click(await screen.findByRole('menuitem', { name: 'Create a new workspace' }))
  const dialog = await screen.findByRole('dialog', { name: 'Create a new workspace' })
  fireEvent.change(within(dialog).getByRole('textbox', { name: 'New workspace name' }), {
@@ -30,9 +30,14 @@ describe('web e2e: workspace management (create / rename / flat view / hover car
  let browser: Browser
  let page: Page
  let tripwire: ReturnType<typeof watchConsole>
+  let pickedDirectory: string | null = null

  beforeAll(async () => {
    scaffold = await launchWebScaffold({})
+    scaffold.ctx.apiProxy.host.pickDirectory = request => Promise.resolve({
+      rpcId: request.rpcId,
+      result: { ok: true, value: { path: pickedDirectory } },
+    })
    // Seed one cold session (Ungrouped bucket) for the flat view + hover card.
    const sessionCwd = join(scaffold.workspaceCwd, 'workspace')
    await mkdir(sessionCwd, { recursive: true })
@@ -55,8 +60,6 @@ describe('web e2e: workspace management (create / rename / flat view / hover car
    onTestFailed(() => saveFailureShot(page, 'web-e2e-ws-create'))
    const createByName = async (name: string): Promise<void> => {
      await page.getByRole('button', { name: 'Create workspace' }).click()
-      // The pick menu's Create workspace submenu opens on hover/focus.
-      await page.getByRole('menuitem', { name: 'Create workspace' }).hover()
      await page.getByRole('menuitem', { name: 'Create a new workspace' }).click()
      const dialog = page.getByRole('dialog', { name: 'Create a new workspace' })
      await dialog.waitFor({ timeout: 10_000 })
@@ -134,14 +137,14 @@ describe('web e2e: workspace management (create / rename / flat view / hover car
      collect()
    })
    // Register the scaffold's existing project directory through the real UI.
+    pickedDirectory = scaffold.workspaceCwd
    await page.getByRole('button', { name: 'Create workspace' }).click()
-    await page.getByRole('menuitem', { name: 'Create workspace' }).hover()
-    await page.getByRole('menuitem', { name: 'Use an existing folder' }).click()
-    const useFolder = page.getByRole('dialog', { name: 'Use an existing folder' })
-    await useFolder.getByLabel('Existing folder path').fill(scaffold.workspaceCwd)
-    await useFolder.getByRole('button', { name: 'Use folder' }).click()
-    await expect.poll(() => useFolder.count(), { timeout: 10_000 }).toBe(0)
+    await page.getByRole('menuitem', { name: 'Open local folder…' }).click()

+    await expect.poll(
+      () => scaffold.ctx.workspace.resolveByPath(scaffold.workspaceCwd),
+      { timeout: 10_000 },
+    ).not.toBeUndefined()
    const workspace = await scaffold.ctx.workspace.resolveByPath(scaffold.workspaceCwd)
    if (workspace === undefined) throw new Error('GUI did not register the existing project directory')
    await workspace.attachSession(SessionId(SEED_ID))
@@ -197,13 +200,13 @@ describe('web e2e: workspace management (create / rename / flat view / hover car
    // Re-registering the exact deleted path immediately, without a reload, is
    // a supported reversible flow. It creates a fresh Workspace id without
    // re-adopting the retained Session.
+    pickedDirectory = scaffold.workspaceCwd
    await page.getByRole('button', { name: 'Create workspace' }).click()
-    await page.getByRole('menuitem', { name: 'Create workspace' }).hover()
-    await page.getByRole('menuitem', { name: 'Use an existing folder' }).click()
-    const reuseFolder = page.getByRole('dialog', { name: 'Use an existing folder' })
-    await reuseFolder.getByLabel('Existing folder path').fill(scaffold.workspaceCwd)
-    await reuseFolder.getByRole('button', { name: 'Use folder' }).click()
-    await expect.poll(() => reuseFolder.count(), { timeout: 10_000 }).toBe(0)
+    await page.getByRole('menuitem', { name: 'Open local folder…' }).click()
+    await expect.poll(
+      () => scaffold.ctx.workspace.resolveByPath(scaffold.workspaceCwd),
+      { timeout: 10_000 },
+    ).not.toBeUndefined()
    const reregistered = await scaffold.ctx.workspace.resolveByPath(scaffold.workspaceCwd)
    expect(reregistered?.id).toBeDefined()
    expect(reregistered?.id).not.toBe(workspace.id)
@@ -269,13 +272,13 @@ describe('web e2e: workspace management (create / rename / flat view / hover car
      collect()
    })

+    pickedDirectory = oldPath
    await page.getByRole('button', { name: 'Create workspace' }).click()
-    await page.getByRole('menuitem', { name: 'Create workspace' }).hover()
-    await page.getByRole('menuitem', { name: 'Use an existing folder' }).click()
-    const adopt = page.getByRole('dialog', { name: 'Use an existing folder' })
-    await adopt.getByLabel('Existing folder path').fill(oldPath)
-    await adopt.getByRole('button', { name: 'Use folder' }).click()
-    await expect.poll(() => adopt.count(), { timeout: 10_000 }).toBe(0)
+    await page.getByRole('menuitem', { name: 'Open local folder…' }).click()
+    await expect.poll(
+      () => scaffold.ctx.workspace.resolveByPath(oldPath),
+      { timeout: 10_000 },
+    ).not.toBeUndefined()
    const oldWorkspace = await scaffold.ctx.workspace.resolveByPath(oldPath)
    if (oldWorkspace === undefined) throw new Error('old same-name Workspace was not registered')

@@ -288,7 +291,6 @@ describe('web e2e: workspace management (create / rename / flat view / hover car
    await expect.poll(() => scaffold.ctx.workspace.get(oldWorkspace.id), { timeout: 10_000 }).toBeUndefined()

    await page.getByRole('button', { name: 'Create workspace' }).click()
-    await page.getByRole('menuitem', { name: 'Create workspace' }).hover()
    await page.getByRole('menuitem', { name: 'Create a new workspace' }).click()
    const create = page.getByRole('dialog', { name: 'Create a new workspace' })
    await create.getByLabel('New workspace name').fill(title)
@@ -704,6 +704,7 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
    },
    host: {
      describe: request => ok(request, { version: '0.0.0-fixture', cwd: '/tmp/fixture', attachedSessions }),
+      pickDirectory: request => ok(request, { path: null }),
    },
    workspace: {
      list: request => ok(request, { items: workspaces.map(w => ({ ...w })) }),
@@ -952,6 +953,7 @@ export class FixtureApiClient extends AbstractApiClient {
      case 'session.prompt': return this.api.sessions.prompt(request)
      case 'session.cancel': return this.api.sessions.cancel(request)
      case 'host.describe': return this.api.host.describe(request)
+      case 'host.pickDirectory': return this.api.host.pickDirectory(request, new AbortController().signal)
      case 'workspace.list': return this.api.workspace.list(request)
      case 'workspace.create': return this.api.workspace.create(request)
      case 'workspace.rename': return this.api.workspace.rename(request)
@@ -5,6 +5,7 @@ import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
 import { API_PATH } from './api-path.ts'
 import { bridge } from './http-bridge.ts'
+import { isTrustedNativeDialogRequest } from './native-dialog-request.ts'

 export { API_PATH } from './api-path.ts'

@@ -23,7 +24,16 @@ export function apply(ctx: Context): void {
  const route: WebRoute = {
    kind: 'prefix',
    path: API_PATH,
-    handler: (req, res) => bridge(req, res, apiHandler),
+    handler: async (req, res) => {
+      const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
+      if (pathname === `${API_PATH}/host.pickDirectory`
+        && !isTrustedNativeDialogRequest(req)) {
+        res.writeHead(403)
+        res.end('forbidden')
+        return
+      }
+      await bridge(req, res, apiHandler)
+    },
  }
  ctx.effect(() => ctx.httpServer.register(route), 'client-connection: /api route')
 }
@@ -0,0 +1,52 @@
+/** Trust check for browser requests that can open an operating-system dialog. */
+
+import type { IncomingHttpHeaders } from 'node:http'
+
+interface NativeDialogRequest {
+  headers: IncomingHttpHeaders
+  socket: { remoteAddress?: string | undefined }
+}
+
+function header(headers: IncomingHttpHeaders, name: string): string | undefined {
+  const value = headers[name]
+  return typeof value === 'string' ? value : undefined
+}
+
+function isLoopback(address: string | undefined): boolean {
+  if (address === undefined) return false
+  if (address === '::1') return true
+  const ipv4 = address.startsWith('::ffff:') ? address.slice('::ffff:'.length) : address
+  const first = ipv4.split('.')[0]
+  return first === '127'
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  if (hostname === 'localhost' || hostname === '[::1]' || hostname === '::1') return true
+  const parts = hostname.split('.')
+  return parts.length === 4
+    && parts[0] === '127'
+    && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/**
+ * Require a local socket plus browser-controlled same-origin metadata.
+ * @param request - the node HTTP request facts used by the carrier guard.
+ * @returns true only for a same-origin browser request whose peer and URL are loopback.
+ */
+export function isTrustedNativeDialogRequest(request: NativeDialogRequest): boolean {
+  if (!isLoopback(request.socket.remoteAddress)) return false
+  if (header(request.headers, 'sec-fetch-site') !== 'same-origin') return false
+  const origin = header(request.headers, 'origin')
+  const host = header(request.headers, 'host')
+  if (origin === undefined || host === undefined) return false
+  try {
+    const parsed = new URL(origin)
+    const hostUrl = new URL(`http://${host}`)
+    return (parsed.protocol === 'http:' || parsed.protocol === 'https:')
+      && parsed.host === host
+      && isLoopbackHostname(parsed.hostname)
+      && isLoopbackHostname(hostUrl.hostname)
+  } catch {
+    return false
+  }
+}
@@ -52,6 +52,8 @@ export class FakeApiClient implements IApiClient {
  onCancel: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
  onDescribe: (payload: unknown) => Promise<RpcResponse<{ version: string; cwd: string; attachedSessions: number }>> =
    () => Promise.resolve(ok({ version: '0-fake', cwd: '/f', attachedSessions: 0 }))
+  onPickDirectory: (payload: unknown) => Promise<RpcResponse<{ path: string | null }>> =
+    () => Promise.resolve(ok({ path: null }))

  private readonly muxConns: StreamConn<MuxFrame>[] = []
  private readonly hostConns: StreamConn<HostFrame>[] = []
@@ -70,6 +72,7 @@ export class FakeApiClient implements IApiClient {

  readonly host: IApiClient['host'] = {
    describe: payload => this.record('host.describe', payload, this.onDescribe(payload)),
+    pickDirectory: payload => this.record('host.pickDirectory', payload, this.onPickDirectory(payload)),
  }

  readonly workspace: IApiClient['workspace'] = {
@@ -0,0 +1,47 @@
+import { EventEmitter } from 'node:events'
+import { Readable } from 'node:stream'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { describe, expect, it } from 'vitest'
+import { bridge } from '../src/http-bridge.ts'
+
+describe('HTTP bridge abort', () => {
+  it('aborts a pending native picker request when the browser disconnects', async () => {
+    const body = JSON.stringify({
+      type: 'client-request', rpcId: 'picker-1', method: 'host.pickDirectory', payload: {},
+    })
+    const request = Readable.from([Buffer.from(body)]) as unknown as IncomingMessage
+    Object.assign(request, {
+      url: '/api/host.pickDirectory',
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+    })
+
+    const response = Object.assign(new EventEmitter(), {
+      writableEnded: false,
+      writeHead() { return this },
+      write() { return true },
+      end() { this.writableEnded = true; return this },
+    }) as unknown as ServerResponse
+
+    let resolveStarted!: () => void
+    const started = new Promise<void>((resolve) => { resolveStarted = resolve })
+    let carrierSignal: AbortSignal | undefined
+    const pending = bridge(request, response, {
+      fetch: async (input) => {
+        const fetchRequest = input as Request
+        carrierSignal = fetchRequest.signal
+        resolveStarted()
+        if (!fetchRequest.signal.aborted) {
+          await new Promise<void>((resolve) => {
+            fetchRequest.signal.addEventListener('abort', () => { resolve() }, { once: true })
+          })
+        }
+        return Response.json({ aborted: fetchRequest.signal.aborted })
+      },
+    })
+    await started
+    response.emit('close')
+    await pending
+    expect(carrierSignal?.aborted).toBe(true)
+  })
+})
@@ -0,0 +1,57 @@
+import type { IncomingHttpHeaders } from 'node:http'
+import { describe, expect, it } from 'vitest'
+import { isTrustedNativeDialogRequest } from '../src/native-dialog-request.ts'
+
+function request(
+  remoteAddress: string | undefined,
+  headers: IncomingHttpHeaders = {
+    host: '127.0.0.1:3080',
+    origin: 'http://127.0.0.1:3080',
+    'sec-fetch-site': 'same-origin',
+  },
+) {
+  return { socket: { remoteAddress }, headers }
+}
+
+describe('native dialog request trust', () => {
+  it('accepts loopback same-origin browser requests', () => {
+    expect(isTrustedNativeDialogRequest(request('127.0.0.1'))).toBe(true)
+    expect(isTrustedNativeDialogRequest(request('::1', {
+      host: '[::1]:3080', origin: 'http://[::1]:3080', 'sec-fetch-site': 'same-origin',
+    }))).toBe(true)
+    expect(isTrustedNativeDialogRequest(request('::ffff:127.0.0.1'))).toBe(true)
+    expect(isTrustedNativeDialogRequest(request('127.0.0.1', {
+      host: 'localhost:3080', origin: 'http://localhost:3080', 'sec-fetch-site': 'same-origin',
+    }))).toBe(true)
+    expect(isTrustedNativeDialogRequest(request('127.0.0.2', {
+      host: '127.0.0.2:3080', origin: 'https://127.0.0.2:3080', 'sec-fetch-site': 'same-origin',
+    }))).toBe(true)
+  })
+
+  it('rejects remote sockets and requests without matching browser metadata', () => {
+    expect(isTrustedNativeDialogRequest(request('192.168.1.5'))).toBe(false)
+    expect(isTrustedNativeDialogRequest(request(undefined))).toBe(false)
+    expect(isTrustedNativeDialogRequest(request('127.0.0.1', {
+      host: '127.0.0.1:3080', origin: 'http://evil.example', 'sec-fetch-site': 'cross-site',
+    }))).toBe(false)
+    expect(isTrustedNativeDialogRequest(request('127.0.0.1', {
+      host: '127.0.0.1:3080', origin: 'http://localhost:3080', 'sec-fetch-site': 'same-origin',
+    }))).toBe(false)
+    expect(isTrustedNativeDialogRequest(request('127.0.0.1', { host: '127.0.0.1:3080' }))).toBe(false)
+    expect(isTrustedNativeDialogRequest(request('127.0.0.1', {
+      origin: 'http://127.0.0.1:3080', 'sec-fetch-site': 'same-origin',
+    }))).toBe(false)
+    expect(isTrustedNativeDialogRequest(request('127.0.0.1', {
+      host: 'attacker.example:3080', origin: 'http://attacker.example:3080', 'sec-fetch-site': 'same-origin',
+    }))).toBe(false)
+    expect(isTrustedNativeDialogRequest(request('127.0.0.1', {
+      host: '127.0.0.1:3080', origin: 'ftp://127.0.0.1:3080', 'sec-fetch-site': 'same-origin',
+    }))).toBe(false)
+    expect(isTrustedNativeDialogRequest(request('127.0.0.1', {
+      host: '127.999.0.1:3080', origin: 'http://127.999.0.1:3080', 'sec-fetch-site': 'same-origin',
+    }))).toBe(false)
+    expect(isTrustedNativeDialogRequest(request('127.0.0.1', {
+      host: '[invalid', origin: 'http://[invalid', 'sec-fetch-site': 'same-origin',
+    }))).toBe(false)
+  })
+})
@@ -1,6 +1,7 @@
 /** Node half: registers the /api prefix route bridging to the api gateway. */
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
+import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { HttpServerService, WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { API_PATH, apply, inject } from '../src/index.ts'
@@ -27,6 +28,23 @@ describe('connection node half', () => {
    expect(routes).toHaveLength(1)
    expect(routes[0]).toMatchObject({ kind: 'prefix', path: API_PATH })

+    let status: number | undefined
+    let body: unknown
+    const deniedRequest = {
+      url: '/api/host.pickDirectory',
+      headers: {
+        host: 'harness.example', origin: 'http://harness.example', 'sec-fetch-site': 'same-origin',
+      },
+      socket: { remoteAddress: '192.168.1.8' },
+    } as unknown as IncomingMessage
+    const deniedResponse = {
+      writeHead(value: number) { status = value; return this },
+      end(value?: unknown) { body = value; return this },
+    } as unknown as ServerResponse
+    await routes[0]!.handler(deniedRequest, deniedResponse)
+    expect(status).toBe(403)
+    expect(body).toBe('forbidden')
+
    await fiber.dispose()
    expect(routes).toHaveLength(0)
  })
@@ -13,7 +13,7 @@ export type { RootOwnerProps } from './slots.ts'
 export { SessionCreateError, SessionsService, scopeOf, workspaceTitleOf } from './sessions/service.ts'
 export { createScope } from './agents/scope.ts'
 export type { AgentScopeHandle } from './agents/scope.ts'
-export { WorkspacesService } from './workspaces/service.ts'
+export { WorkspaceCreateError, WorkspacesService } from './workspaces/service.ts'
 export type { Session } from './sessions/session.ts'
 export type {
  SessionBinding, SessionListState, SessionProvideContribution, SessionProvideDescriptor, SessionSummary,
@@ -21,6 +21,14 @@ export interface WorkspaceListState {
  recentWorkspaceId: WorkspaceId | undefined
 }

+/** Structured create failure for UI flows that distinguish Host business errors. */
+export class WorkspaceCreateError extends Error {
+  constructor(readonly rpcError: RpcError) {
+    super(`workspace create failed: ${rpcError.code}: ${rpcError.message}`)
+    this.name = 'WorkspaceCreateError'
+  }
+}
+
 /** Real Workspace object layer and Host actions. */
 export class WorkspacesService {
  /** UI-facing immutable projection; the manager remains wire truth. */
@@ -37,7 +45,7 @@ export class WorkspacesService {
   * @param api - shared wire client.
   * @param sessions - lower-level Session service used for recency and blank-session reuse.
   */
-  constructor(ctx: Context, api: IApiClient, private readonly sessions: SessionsService) {
+  constructor(ctx: Context, private readonly api: IApiClient, private readonly sessions: SessionsService) {
    this.manager = new WorkspaceManager(api)
    this.list = createSnapshotStore<WorkspaceListState>({
      items: [], state: 'idle', phase: 'pending', error: null,
@@ -158,10 +166,22 @@ export class WorkspacesService {
   */
  async create(input: { name: string } | { path: string }): Promise<WorkspaceView> {
    const result = await this.manager.create(input)
-    if (!result.ok) throw new Error(`workspace create failed: ${result.error.code}: ${result.error.message}`)
+    if (!result.ok) throw new WorkspaceCreateError(result.error)
    return result.value.workspace
  }

+  /**
+   * Open the Host's native directory picker.
+   * @returns the selected path, or null when the user cancelled.
+   */
+  async pickDirectory(): Promise<string | null> {
+    const response = await this.api.host.pickDirectory({})
+    if (!response.result.ok) {
+      throw new Error(`directory picker failed: ${response.result.error.message}`)
+    }
+    return response.result.value.path
+  }
+
  /**
   * Rename a Workspace.
   * @param workspaceId - target workspace.
@@ -69,6 +69,8 @@ export class FakeApiClient implements IApiClient {
  onCancel: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
  onDescribe: (payload: unknown) => Promise<RpcResponse<{ version: string; cwd: string; attachedSessions: number }>> =
    () => Promise.resolve(ok({ version: '0-fake', cwd: '/f', attachedSessions: 0 }))
+  onPickDirectory: (payload: unknown) => Promise<RpcResponse<{ path: string | null }>> =
+    () => Promise.resolve(ok({ path: null }))

  private readonly muxConns: StreamConn<MuxFrame>[] = []
  private readonly hostConns: StreamConn<HostFrame>[] = []
@@ -87,6 +89,7 @@ export class FakeApiClient implements IApiClient {

  readonly host: IApiClient['host'] = {
    describe: (payload: unknown) => this.record('host.describe', payload, this.onDescribe(payload)),
+    pickDirectory: (payload: unknown) => this.record('host.pickDirectory', payload, this.onPickDirectory(payload)),
  }

  onWorkspaceList: (payload: unknown) => Promise<RpcResponse<{ items: never[] }>> = () => Promise.resolve(ok({ items: [] }))
@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest'
 import type { SessionId, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-connection/client'
 import { SessionsService } from '../src/client/sessions/service.ts'
 import { WorkspaceManager } from '../src/client/workspaces/manager.ts'
-import { WorkspacesService } from '../src/client/workspaces/service.ts'
+import { WorkspaceCreateError, WorkspacesService } from '../src/client/workspaces/service.ts'
 import { FakeApiClient, deferred, err, ok } from './fake-api.ts'

 const sid = (id: string): SessionId => id as SessionId
@@ -210,12 +210,30 @@ describe('WorkspacesService', () => {
    const api = new FakeApiClient()
    const sessions = new SessionsService(ctx, api)
    const workspaces = new WorkspacesService(ctx, api, sessions)
-    await expect(workspaces.create({ path: '/w/existing' })).resolves.toMatchObject({ workspaceId: 'fk-ws' })
-    expect(api.callsOf('workspace.create')).toEqual([{ path: '/w/existing' }])
+    api.onWorkspaceCreate = () => Promise.resolve(ok({
+      workspace: { ...workspace('picked'), path: '/w/alpha', title: 'alpha' }, created: true,
+    }))
+    await expect(workspaces.create({ path: '/w/alpha' })).resolves.toMatchObject({ workspaceId: 'picked' })
+    expect(workspaces.list.getSnapshot().items[0]).toMatchObject({ path: '/w/alpha', title: 'alpha' })
+    expect(api.callsOf('workspace.create')).toEqual([{ path: '/w/alpha' }])
    api.onWorkspaceCreate = () => Promise.resolve(err({
      code: 'workspace-invalid-path', message: 'missing', details: { path: '/missing' },
    }))
-    await expect(workspaces.create({ path: '/missing' })).rejects.toThrow(/workspace-invalid-path: missing/)
+    const rejected = workspaces.create({ path: '/missing' })
+    await expect(rejected).rejects.toThrow(/workspace-invalid-path: missing/)
+    await expect(rejected).rejects.toBeInstanceOf(WorkspaceCreateError)
+  })
+
+  it('passes native directory selection and cancellation through without local state', async () => {
+    const ctx = new Context()
+    const api = new FakeApiClient()
+    const sessions = new SessionsService(ctx, api)
+    const workspaces = new WorkspacesService(ctx, api, sessions)
+    api.onPickDirectory = () => Promise.resolve(ok({ path: '/w/alpha' }))
+    await expect(workspaces.pickDirectory()).resolves.toBe('/w/alpha')
+    api.onPickDirectory = () => Promise.resolve(ok({ path: null }))
+    await expect(workspaces.pickDirectory()).resolves.toBeNull()
+    expect(api.callsOf('host.pickDirectory')).toEqual([{}, {}])
  })

  it('deletes a Workspace or preserves it when the Host rejects deletion', async () => {
@@ -90,20 +90,17 @@ export function apply(ctx: Context): void {
      'conversation.hero.workspace': { kind: 'single', scope: 'root' },
    },
    inject: (sessionId: SessionId | undefined): ConversationInjected => ({
-      selectWorkspace: (workspaceId) => {
-        void workspaces.connectWorkspace(workspaceId).then((nextId) => {
-          if (sessionId !== undefined && nextId !== sessionId) {
-            const from = inputHub.shell(sessionId)
-            const draft = from.snapshot.draft
-            if (draft !== '') {
-              inputHub.shell(nextId).setDraft(draft)
-              from.setDraft('')
-            }
+      selectWorkspace: async (workspaceId) => {
+        const nextId = await workspaces.connectWorkspace(workspaceId)
+        if (sessionId !== undefined && nextId !== sessionId) {
+          const from = inputHub.shell(sessionId)
+          const draft = from.snapshot.draft
+          if (draft !== '') {
+            inputHub.shell(nextId).setDraft(draft)
+            from.setDraft('')
          }
-          sessions.open(nextId)
-        }).catch(() => {
-          // Failure leaves the current Hero state available to retry.
-        })
+        }
+        sessions.open(nextId)
      },
    }),
  }, ConversationRoot)
@@ -175,7 +175,7 @@ export interface ConversationInjected {
   * Connect the selected Workspace and open its reusable/new blank session.
   * When a blank session is already current, carry its draft to the target.
   */
-  selectWorkspace(workspaceId: WorkspaceId): void
+  selectWorkspace(workspaceId: WorkspaceId): Promise<void>
 }

 /** Business callbacks injected into the strict session content seat. */
@@ -2,8 +2,9 @@
 // chain stay mounted across no-session/session transitions. Only the inert
 // input body swaps for the strict session InputBar.

-import { useRef, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import clsx from 'clsx'
+import type { WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConversationSlotProps, InputZone } from '../contract/slots.ts'
 import { HeroShell, WorkspaceChip, workspaceLabel } from './EmptyHero.tsx'
 import { DisabledInputBar } from './DisabledInputBar.tsx'
@@ -25,8 +26,23 @@ export function ConversationRoot({
  const workspaces = useWorkspaces(s => s)

  const [pickerOpen, setPickerOpen] = useState(false)
+  const [pendingWorkspaceId, setPendingWorkspaceId] = useState<WorkspaceId | undefined>()
  const pickerAnchor = useRef<HTMLButtonElement>(null)

+  const sessionWorkspace = sessionId === undefined
+    ? undefined
+    : workspaces.items.find(workspace => workspace.sessionIds.includes(sessionId))
+  const pendingWorkspace = workspaces.items.find(
+    workspace => workspace.workspaceId === pendingWorkspaceId,
+  )
+
+  useEffect(() => {
+    if (pendingWorkspaceId !== undefined
+      && sessionWorkspace?.workspaceId === pendingWorkspaceId) {
+      setPendingWorkspaceId(undefined)
+    }
+  }, [pendingWorkspaceId, sessionWorkspace?.workspaceId])
+
  const hero = sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || openState === 'loading'))
  const zone: InputZone | undefined =
    session === undefined || inputState === undefined ? undefined : { session, input: inputState }
@@ -36,9 +52,10 @@ export function ConversationRoot({
      <WorkspaceChip
        buttonRef={pickerAnchor}
        label={
-          sessionId === undefined
+          pendingWorkspace?.title
+          ?? (sessionId === undefined
            ? workspaceLabel('')
-            : workspaces.items.find(w => w.sessionIds.includes(sessionId))?.title ?? workspaceLabel(cwd ?? '')
+            : sessionWorkspace?.title ?? workspaceLabel(cwd ?? ''))
        }
        menuOpen={pickerOpen}
        onClick={() => { setPickerOpen(open => !open) }}
@@ -48,7 +65,10 @@ export function ConversationRoot({
        anchorRef: pickerAnchor,
        onPick: (workspaceId) => {
          setPickerOpen(false)
-          selectWorkspace(workspaceId)
+          setPendingWorkspaceId(workspaceId)
+          void selectWorkspace(workspaceId).catch(() => {
+            setPendingWorkspaceId(current => current === workspaceId ? undefined : current)
+          })
        },
        onClose: () => { setPickerOpen(false) },
      })}
@@ -3,7 +3,7 @@
 // hero (blank session) and active phases — same textarea DOM node, machine-
 // owned draft, and the hero workspace picker (switching = retargetWorkspace).
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { cleanup, fireEvent, render } from '@testing-library/react'
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
@@ -55,7 +55,11 @@ function conversationSnapshot(overrides: Partial<ConversationSnapshot> = {}): Co
  }
 }

-function mount(snapshot: ConversationSnapshot, workspaceRows: WorkspaceView[] = [{ ...workspace('one'), sessionIds: [SID] }]) {
+function mount(
+  snapshot: ConversationSnapshot,
+  workspaceRows: WorkspaceView[] = [{ ...workspace('one'), sessionIds: [SID] }],
+  retargetWorkspace = vi.fn(async (_workspaceId: WorkspaceId) => {}),
+) {
  const root = sid('root')
  const sessions = createSnapshotStore<SessionListState>({
    ids: [root, SID],
@@ -76,7 +80,6 @@ function mount(snapshot: ConversationSnapshot, workspaceRows: WorkspaceView[] =
  const inputActions = wiring.actions
  const stop = vi.fn()
  const open = vi.fn()
-  const retargetWorkspace = vi.fn()
  const slotCalls: string[] = []
  let pickerOwner: unknown
  const renderSlot = ((key: string, owner: object, opts?: { only?: string }) => {
@@ -158,7 +161,13 @@ describe('ConversationRoot resident composer', () => {
  })

  it('hero phase: same textarea, hero chrome, no header, picker switches the workspace', () => {
-    const b = mount(conversationSnapshot({ composerPhase: 'blank', blank: true }))
+    const b = mount(
+      conversationSnapshot({ composerPhase: 'blank', blank: true }),
+      [
+        { ...workspace('one'), sessionIds: [SID] },
+        { ...workspace('second'), title: 'Selected Folder' },
+      ],
+    )
    // Hero chrome present, view ring absent.
    expect(b.view.getByText("Let's start building")).toBeTruthy()
    expect(b.view.queryByTestId('view-chat')).toBeNull()
@@ -173,8 +182,9 @@ describe('ConversationRoot resident composer', () => {
    fireEvent.click(b.view.getByRole('button', { name: 'Choose workspace' }))
    const owner = b.pickerOwner() as { open: boolean; onPick(id: WorkspaceId): void }
    expect(owner.open).toBe(true)
-    owner.onPick(wid('second'))
+    act(() => { owner.onPick(wid('second')) })
    expect(b.retargetWorkspace).toHaveBeenCalledWith(wid('second'))
+    expect(b.view.getByText('Selected Folder')).toBeTruthy()
  })

  it('textarea DOM identity survives the hero → active flip', () => {
@@ -191,6 +201,24 @@ describe('ConversationRoot resident composer', () => {
    expect(b.view.getByTestId('view-chat')).toBeTruthy()
  })

+  it('rolls the pending workspace label back when switching fails', async () => {
+    const selectWorkspace = vi.fn(async () => { throw new Error('connect failed') })
+    const b = mount(
+      conversationSnapshot({ composerPhase: 'blank', blank: true }),
+      [
+        { ...workspace('one'), sessionIds: [SID] },
+        { ...workspace('second'), title: 'Selected Folder' },
+      ],
+      selectWorkspace,
+    )
+    fireEvent.click(b.view.getByRole('button', { name: 'Choose workspace' }))
+    const owner = b.pickerOwner() as { onPick(id: WorkspaceId): void }
+    await act(async () => { owner.onPick(wid('second')); await Promise.resolve() })
+    expect(selectWorkspace).toHaveBeenCalledWith(wid('second'))
+    expect(b.view.queryByText('Selected Folder')).toBeNull()
+    expect(b.view.getByText('one')).toBeTruthy()
+  })
+
  it('blank session keeps the interactive picker chip (workspace switchable until the first message)', () => {
    const b = mount(conversationSnapshot({ composerPhase: 'blank', blank: true }))
    const chip = b.view.getByRole('button', { name: 'Choose workspace' })
@@ -128,6 +128,11 @@
  gap: 10px;
  width: 100%;
  min-height: 42px;
+  /* Rows are the scroll content, never the slack absorber: a shrinkable row
+     collapses to min-height while its wrapped copy keeps the taller
+     intrinsic height, and centered content then paints outside the row box —
+     over the title and the next row. Overflow belongs to .options. */
+  flex-shrink: 0;
  padding: 5px 8px;
  border: 1px solid transparent;
  border-radius: 12px;
@@ -208,6 +213,9 @@
 }

 .custom {
+  /* Same reason as .option: the custom block is scroll content, and shrinking
+     it pushes its trigger row (and the open textarea) past the footer. */
+  flex-shrink: 0;
  border: 1px solid transparent;
  border-radius: 12px;
 }
@@ -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-workspace/README.md
-README.md: b5a78c30ddae5e12612bb8cced65b5fe95f7e259
-README.zh.md: 904543a48f1609e23ba80cf240be965d0654a951
+README.md: edd6c2f9373d97832def86bb44658d7c1c68dae9
+README.zh.md: f7b73dde953d4294d4d157f479fe932adf1a29c4
@@ -2,9 +2,9 @@

 English | [中文](README.zh.md)

-Shared Workspace picker plugin. `WorkspacePicker` is registered into the sidebar's `sidebar.workspace` slot and the page-local Session Intent hero's `conversation.empty.workspace` slot, so both surfaces use the same menu and creation modals.
+Shared Workspace picker plugin. `WorkspaceBrowser` is registered into the sidebar's `sidebar.workspaces` slot and `WorkspacePicker` into the page-local Session Intent hero's `conversation.hero.workspace` slot, so both surfaces use the same menu and creation flow.

-The picker lists real Host Workspace entities through the global `useWorkspaces` hook. Selecting a Workspace invokes the slot owner's `onPick` callback to retarget the frontend Session object; the existing-folder and create-new actions first create a real Workspace through the object layer, then select it. Create-new disables names already present in that list, while the Host remains authoritative for concurrent or non-UI callers. The runtime Session and Workspace services own materialization. The Workspace row's Delete action opens a confirmation that states the retention boundary, blocks duplicate submission, and keeps failures open; success removes the group while its Sessions remain under Ungrouped.
+The picker lists real Host Workspace entities through the global `useWorkspaces` hook. Selecting a Workspace invokes the slot owner's `onPick` callback to retarget the frontend Session object. The flat **Open local folder...** action delegates to the Host's native single-directory picker, adopts a returned path through the object layer, and selects the committed Workspace only after its list projection has refreshed; cancellation is silent, and errors remain retryable. **Create a new workspace** retains the name dialog and disables names already present in that list, while the Host remains authoritative for concurrent or non-UI callers. The runtime Session and Workspace services own materialization. The Workspace row's Delete action opens a confirmation that states the retention boundary, blocks duplicate submission, and keeps failures open; success removes the group while its Sessions remain under Ungrouped.

 Both target slots are declared by other plugins, so `apply` registers through declaration-aware deferral and re-registers after a declaring slot is restored.

@@ -19,4 +19,4 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work

 - **No Session deletion control** — the existing Session menu row remains visual-only; Workspace registration deletion does not delete Sessions.
- **Existing-folder entry is manual path input only** — Host creation failures are shown in the modal.
+- **Native folder selection depends on the local Host carrier** — fixture-only or remote browser deployments cannot open a local operating-system dialog; platform failures are shown in a retryable modal.
@@ -2,9 +2,9 @@

 [English](README.md) | 中文

-共享 Workspace 选择器插件。`WorkspacePicker` 注册到侧边栏的 `sidebar.workspace` slot，以及页面局部 Session Intent 主视觉区的 `conversation.empty.workspace` slot，因此两个表层使用同一菜单和创建模态框。
+共享 Workspace 选择器插件。`WorkspaceBrowser` 注册到侧边栏的 `sidebar.workspaces` slot，`WorkspacePicker` 注册到页面局部 Session Intent 主视觉区的 `conversation.hero.workspace` slot，因此两个表层使用同一菜单和创建流程。

-该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象；使用现有文件夹和新建操作时，系统会先通过对象层创建真实 Workspace，再将其选中。新建操作会禁用列表中已有的名称，而 Host 对并发或非 UI 调用方仍具有最终决定权。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。
+该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。平铺显示的 **打开本地文件夹…** 操作会委托 Host 的原生单目录选择器，通过对象层接纳返回的路径，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，发生错误后仍可重试。**创建新工作区** 操作保留名称对话框，并禁用列表中已有的名称，而 Host 对并发或非 UI 调用方仍具有最终决定权。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。

 两个目标 slot 都由其他插件声明，因此 `apply` 通过声明感知的延迟机制完成注册，并在声明该 slot 的插件恢复后重新注册。

@@ -19,4 +19,4 @@
 ## 已知限制与暂缓事项

 - **没有 Session 删除控件**：现有 Session 菜单行仍仅提供视觉效果；删除 Workspace 注册记录不会删除 Session。
- **现有文件夹入口仅支持手动输入路径**：Host 创建失败会显示在模态框中。
+- **原生文件夹选择依赖本地 Host 载体**：仅使用 fixture（测试前置数据）的部署或远程浏览器部署无法打开本地操作系统对话框；模态框会显示平台故障，并允许重试。
@@ -250,6 +250,7 @@ export function WorkspaceBrowser({
  deleteWorkspace,
  insertSessionBefore,
  createWorkspace,
+  pickDirectory,
 }: WorkspaceBrowserProps) {
  const workspaces = useWorkspaces(state => state.items)
  const groupBy = useStore(s => s.groupBy)
@@ -367,6 +368,7 @@ export function WorkspaceBrowser({
          anchorRef={wsPlusRef}
          useWorkspaces={useWorkspaces}
          createWorkspace={createWorkspace}
+          pickDirectory={pickDirectory}
          onPick={(workspaceId) => {
            setWsPickerOpen(false)
            startSession(workspaceId)
@@ -9,15 +9,17 @@ import { useCallback, useState } from 'react'
 import {
  Button, IconFolderClose16, IconPlusOutline16, Menu, Modal, type MenuEntry,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { WorkspaceId, WorkspaceListState, WorkspaceView } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  WorkspaceCreateError,
+  type WorkspaceId, type WorkspaceListState, type WorkspaceView,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type { WorkspacePickerProps } from './contract/slots.ts'
 import css from './WorkspacePicker.module.css'

-const CREATE_WORKSPACE = '::create-workspace'
-const USE_EXISTING = '::use-existing'
+const OPEN_LOCAL_FOLDER = '::open-local-folder'
 const CREATE_NEW = '::create-new'

-type ModalKind = 'path' | 'create' | null
+type ModalKind = 'create' | 'folder-error' | null

 /** Core flow props: the owner supplies popover control and pick semantics. */
 export interface WorkspaceCreateFlowProps {
@@ -29,6 +31,8 @@ export interface WorkspaceCreateFlowProps {
  useWorkspaces: <S>(selector: (state: WorkspaceListState) => S) => S
  /** Create or adopt a real Host Workspace. */
  createWorkspace: (input: { name: string } | { path: string }) => Promise<WorkspaceView>
+  /** Open the Host's native single-directory picker. */
+  pickDirectory: () => Promise<string | null>
  /** A real Workspace was picked or created. */
  onPick: (workspaceId: WorkspaceId) => void
  /** Close the popover (outside click / Escape / post-pick). */
@@ -45,6 +49,7 @@ export function WorkspaceCreateFlow({
  anchorRef,
  useWorkspaces,
  createWorkspace,
+  pickDirectory,
  onPick,
  onClose,
 }: WorkspaceCreateFlowProps) {
@@ -55,10 +60,11 @@ export function WorkspaceCreateFlow({
    [anchorRef],
  )
  const [modalKind, setModalKind] = useState<ModalKind>(null)
-  const [pathDraft, setPathDraft] = useState('')
  const [workspaceName, setWorkspaceName] = useState('')
  const [creating, setCreating] = useState(false)
  const [modalError, setModalError] = useState<string | null>(null)
+  const [pickingFolder, setPickingFolder] = useState(false)
+  const [folderConflict, setFolderConflict] = useState(false)
  const normalizedWorkspaceName = workspaceName.trim()
  const duplicateWorkspaceName = !creating && normalizedWorkspaceName !== ''
    && workspaces.some(workspace => workspace.title === normalizedWorkspaceName)
@@ -68,17 +74,11 @@ export function WorkspaceCreateFlow({
      id: workspace.workspaceId as string,
      label: workspace.title,
      icon: <IconFolderClose16 size={16} />,
+      disabled: pickingFolder,
    })),
    ...(workspaces.length > 0 ? [{ type: 'separator' as const, id: 'sep-create' }] : []),
-    {
-      id: CREATE_WORKSPACE,
-      label: 'Create workspace',
-      icon: <IconPlusOutline16 size={16} />,
-      submenu: [
-        { id: USE_EXISTING, label: 'Use an existing folder' },
-        { id: CREATE_NEW, label: 'Create a new workspace' },
-      ],
-    },
+    { id: OPEN_LOCAL_FOLDER, label: 'Open local folder…', icon: <IconFolderClose16 size={16} />, disabled: pickingFolder },
+    { id: CREATE_NEW, label: 'Create a new workspace', icon: <IconPlusOutline16 size={16} />, disabled: pickingFolder },
  ]

  const closeModal = (): void => {
@@ -87,12 +87,29 @@ export function WorkspaceCreateFlow({
    setModalError(null)
  }

+  const openLocalFolder = (): void => {
+    onClose()
+    setModalKind(null)
+    setModalError(null)
+    setFolderConflict(false)
+    setPickingFolder(true)
+    void pickDirectory().then(async (path) => {
+      if (path === null) return
+      const workspace = await createWorkspace({ path })
+      onPick(workspace.workspaceId)
+    }).catch((reason: unknown) => {
+      setFolderConflict(
+        reason instanceof WorkspaceCreateError
+        && reason.rpcError.code === 'workspace-name-conflict',
+      )
+      setModalError(reason instanceof Error ? reason.message : String(reason))
+      setModalKind('folder-error')
+    }).finally(() => { setPickingFolder(false) })
+  }
+
  const handleSelect = (id: string): void => {
-    if (id === USE_EXISTING) {
-      onClose()
-      setPathDraft('')
-      setModalError(null)
-      setModalKind('path')
+    if (id === OPEN_LOCAL_FOLDER) {
+      openLocalFolder()
      return
    }
    if (id === CREATE_NEW) {
@@ -120,11 +137,6 @@ export function WorkspaceCreateFlow({
    })
  }

-  const confirmPath = (): void => {
-    const path = pathDraft.trim()
-    if (path !== '') create({ path })
-  }
-
  const confirmCreate = (): void => {
    if (normalizedWorkspaceName !== '' && !duplicateWorkspaceName) {
      create({ name: normalizedWorkspaceName })
@@ -144,40 +156,21 @@ export function WorkspaceCreateFlow({
      />
      {open && workspaceSnapshot.phase === 'pending' && <div className={css.menuStatus} role="status">Loading workspaces…</div>}
      <Modal
-        open={modalKind === 'path'}
+        open={modalKind === 'folder-error'}
        onClose={closeModal}
-        title="Use an existing folder"
+        title={folderConflict ? 'A workspace with this name already exists' : 'Couldn’t open folder'}
        footer={(
          <>
-            <Button variant="outline" className={css.modalAction!} disabled={creating} onClick={closeModal}>Cancel</Button>
-            <Button
-              variant="primary"
-              className={css.modalAction!}
-              disabled={creating || pathDraft.trim() === ''}
-              onClick={confirmPath}
-            >
-              Use folder
-            </Button>
+            <Button variant="outline" className={css.modalAction!} onClick={closeModal}>Cancel</Button>
+            <Button variant="primary" className={css.modalAction!} onClick={openLocalFolder}>Choose again</Button>
          </>
        )}
      >
-        <input
-          className={css.modalInput}
-          value={pathDraft}
-          aria-label="Existing folder path"
-          autoFocus
-          disabled={creating}
-          placeholder="/path/to/project"
-          onChange={(event) => { setPathDraft(event.target.value) }}
-          onKeyDown={(event) => {
-            if (event.key === 'Enter') {
-              event.preventDefault()
-              confirmPath()
-            }
-          }}
-        />
-        {creating && <div className={css.modalStatus} role="status">Creating workspace…</div>}
-        {modalError !== null && <div className={css.modalError} role="alert">{modalError}</div>}
+        <div className={css.modalError} role="alert">
+          {folderConflict
+            ? 'Choose a folder with a different name.'
+            : modalError}
+        </div>
      </Modal>
      <Modal
        open={modalKind === 'create'}
@@ -235,6 +228,7 @@ export function WorkspacePicker({
  onPick,
  onClose,
  createWorkspace,
+  pickDirectory,
 }: WorkspacePickerProps) {
  return (
    <WorkspaceCreateFlow
@@ -242,6 +236,7 @@ export function WorkspacePicker({
      anchorRef={anchorRef}
      useWorkspaces={useWorkspaces}
      createWorkspace={createWorkspace}
+      pickDirectory={pickDirectory}
      onPick={onPick}
      onClose={onClose}
    />
@@ -42,6 +42,8 @@ export type WorkspaceBrowserInjected = {
  insertSessionBefore: (workspaceId: WorkspaceId, sessionId: SessionId, beforeSessionId?: SessionId) => Promise<void>
  /** Explicitly create or adopt a real Workspace before targeting a Session. */
  createWorkspace: (input: { name: string } | { path: string }) => Promise<WorkspaceView>
+  /** Ask the local Host to open its native single-directory picker. */
+  pickDirectory: () => Promise<string | null>
 }

 /** Full browser props: shell owner share + viewing store + injected actions. */
@@ -58,6 +60,8 @@ export type WorkspaceBrowserProps =
 export type WorkspacePickerInjected = {
  /** Explicitly create or adopt a real Workspace before targeting a Session. */
  createWorkspace(input: { name: string } | { path: string }): Promise<WorkspaceView>
+  /** Ask the local Host to open its native single-directory picker. */
+  pickDirectory(): Promise<string | null>
 }

 /**
@@ -44,9 +44,11 @@ export function apply(ctx: ClientContext): void {
      await ctx.workspaces.insertSessionBefore(workspaceId, sessionId, beforeSessionId)
    },
    createWorkspace: input => ctx.workspaces.create(input),
+    pickDirectory: () => ctx.workspaces.pickDirectory(),
  })
  const pickerInjected = (): WorkspacePickerInjected => ({
    createWorkspace: input => ctx.workspaces.create(input),
+    pickDirectory: () => ctx.workspaces.pickDirectory(),
  })
  // Declaration-aware registration: each owner's declaring apply may activate
  // after this one (entry activation order is unconstrained), and a register
@@ -14,16 +14,17 @@ async function bench() {
    path: 'name' in input ? `/projects/${input.name}` : input.path,
    title: 'new', sessionIds: [], createdAt: '0', updatedAt: '0',
  }))
+  const pickDirectory = vi.fn(async () => '/tmp/picked')
  const startSession = vi.fn()
  const rename = vi.fn(async () => ({}))
  const insertSessionBefore = vi.fn(async () => ({}))
  const open = vi.fn()
  const clear = vi.fn()
  ctx.provide('workspaces', {
-    create, startSession, rename, insertSessionBefore,
+    create, pickDirectory, startSession, rename, insertSessionBefore,
  } as never)
  ctx.provide('sessions', { open, clear } as never)
-  return { ctx, slots: ctx.get('slots') as SlotsService, create, startSession, rename, insertSessionBefore, open, clear }
+  return { ctx, slots: ctx.get('slots') as SlotsService, create, pickDirectory, startSession, rename, insertSessionBefore, open, clear }
 }

 type HoleName = 'sidebar.workspaces' | 'conversation.hero.workspace' | 'conversation.empty.workspace'
@@ -72,10 +73,14 @@ describe('ui-workspace apply', () => {
    expect(b.insertSessionBefore).toHaveBeenCalledWith('ws', 's1', 's2')
    await browser.createWorkspace({ name: 'project' })
    expect(b.create).toHaveBeenCalledWith({ name: 'project' })
+    await browser.pickDirectory()
+    expect(b.pickDirectory).toHaveBeenCalledOnce()

    const picker = (b.slots.entries('conversation.hero.workspace')[0]!.inject as () => WorkspacePickerInjected)()
    await picker.createWorkspace({ path: '/tmp/project' })
    expect(b.create).toHaveBeenCalledWith({ path: '/tmp/project' })
+    await picker.pickDirectory()
+    expect(b.pickDirectory).toHaveBeenCalledTimes(2)
  })

  it('unregisters every entry on teardown', async () => {
@@ -57,6 +57,7 @@ function mount(overrides: Partial<WorkspaceBrowserProps> = {}) {
    deleteWorkspace: vi.fn(async () => {}),
    insertSessionBefore: vi.fn(async () => {}),
    createWorkspace: vi.fn(async () => workspace('created', [])),
+    pickDirectory: vi.fn(async () => null),
    ...overrides,
  }
  const view = render(<WorkspaceBrowser {...props} />)
@@ -4,6 +4,7 @@ import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-libra
 import type {
  SessionListState, WorkspaceId, WorkspaceListState, WorkspaceView,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import { WorkspaceCreateError } from '@deepseek-ai/dsh-client-runtime/client'
 import { WorkspacePicker } from '../src/client/WorkspacePicker.tsx'

 afterEach(cleanup)
@@ -32,7 +33,11 @@ function anchor(): { current: HTMLElement } {
  return { current: element }
 }

-function mount(items: readonly WorkspaceView[] = [workspace('alpha', 'Alpha')], createWorkspace = vi.fn()) {
+function mount(
+  items: readonly WorkspaceView[] = [workspace('alpha', 'Alpha')],
+  createWorkspace = vi.fn(),
+  pickDirectory = vi.fn(async () => null as string | null),
+) {
  const onPick = vi.fn()
  const onClose = vi.fn()
  const anchorRef = anchor()
@@ -45,20 +50,19 @@ function mount(items: readonly WorkspaceView[] = [workspace('alpha', 'Alpha')],
      onPick={onPick}
      onClose={onClose}
      createWorkspace={createWorkspace}
+      pickDirectory={pickDirectory}
    />
  )
  const view = render(
    renderPicker(items),
  )
  return {
-    view, onPick, onClose, createWorkspace,
+    view, onPick, onClose, createWorkspace, pickDirectory,
    rerenderItems: (nextItems: readonly WorkspaceView[]) => { view.rerender(renderPicker(nextItems)) },
  }
 }

-function chooseCreateItem(name: 'Use an existing folder' | 'Create a new workspace'): void {
-  const parent = screen.getByRole('menuitem', { name: 'Create workspace' })
-  fireEvent.mouseEnter(parent.parentElement as HTMLElement)
+function chooseItem(name: 'Open local folder…' | 'Create a new workspace'): void {
  fireEvent.click(screen.getByRole('menuitem', { name }))
 }

@@ -73,7 +77,7 @@ describe('WorkspacePicker', () => {
    const created = workspace('new', 'New')
    const createWorkspace = vi.fn(async () => created)
    const b = mount([], createWorkspace)
-    chooseCreateItem('Create a new workspace')
+    chooseItem('Create a new workspace')
    const input = screen.getByLabelText('New workspace name')
    fireEvent.change(input, { target: { value: 'project-one' } })
    fireEvent.click(screen.getByRole('button', { name: 'Create workspace' }))
@@ -81,31 +85,78 @@ describe('WorkspacePicker', () => {
    await waitFor(() => { expect(b.onPick).toHaveBeenCalledWith(created.workspaceId) })
  })

-  it('adopts an existing path through the same immediate create action', async () => {
-    const created = workspace('adopted')
+  it('opens a native directory picker, adopts its path, and selects the returned Workspace', async () => {
+    const created = { ...workspace('adopted'), path: '/tmp/project', title: 'project' }
    const createWorkspace = vi.fn(async () => created)
-    const b = mount([], createWorkspace)
-    chooseCreateItem('Use an existing folder')
-    const input = screen.getByLabelText('Existing folder path')
-    fireEvent.keyDown(input, { key: 'ArrowRight' })
-    fireEvent.keyDown(input, { key: 'Enter' })
-    expect(createWorkspace).not.toHaveBeenCalled()
-    fireEvent.change(input, { target: { value: ' /tmp/project ' } })
-    fireEvent.keyDown(input, { key: 'Enter' })
+    const pickDirectory = vi.fn(async () => '/tmp/project')
+    const b = mount([], createWorkspace, pickDirectory)
+    chooseItem('Open local folder…')
+    expect(pickDirectory).toHaveBeenCalledOnce()
+    await waitFor(() => { expect(createWorkspace).toHaveBeenCalledWith({ path: '/tmp/project' }) })
    expect(createWorkspace).toHaveBeenCalledWith({ path: '/tmp/project' })
    await waitFor(() => { expect(b.onPick).toHaveBeenCalledWith(created.workspaceId) })
  })

+  it('treats native picker cancellation as a silent no-op', async () => {
+    const b = mount([], vi.fn(), vi.fn(async () => null))
+    chooseItem('Open local folder…')
+    await waitFor(() => { expect(b.pickDirectory).toHaveBeenCalledOnce() })
+    expect(b.createWorkspace).not.toHaveBeenCalled()
+    expect(b.onPick).not.toHaveBeenCalled()
+    expect(screen.queryByRole('dialog')).toBeNull()
+  })
+
+  it('shows a name conflict and retries through the native picker', async () => {
+    const pickDirectory = vi.fn()
+      .mockResolvedValueOnce('/one/project')
+      .mockResolvedValueOnce(null)
+    const createWorkspace = vi.fn(async () => {
+      throw new WorkspaceCreateError({
+        code: 'workspace-name-conflict', message: 'project already exists', details: { name: 'project' },
+      })
+    })
+    const b = mount([], createWorkspace, pickDirectory)
+    chooseItem('Open local folder…')
+    await waitFor(() => {
+      expect(screen.getByRole('dialog', { name: 'A workspace with this name already exists' })).toBeTruthy()
+    })
+    expect(screen.getByRole('alert').textContent).toBe('Choose a folder with a different name.')
+    fireEvent.click(screen.getByRole('button', { name: 'Choose again' }))
+    await waitFor(() => { expect(pickDirectory).toHaveBeenCalledTimes(2) })
+    expect(b.onPick).not.toHaveBeenCalled()
+  })
+
+  it('disables the folder action while the native picker is already open', async () => {
+    let resolve!: (path: string | null) => void
+    const pending = new Promise<string | null>((settle) => { resolve = settle })
+    const b = mount([], vi.fn(), vi.fn(() => pending))
+    chooseItem('Open local folder…')
+    expect((screen.getByRole('menuitem', { name: 'Open local folder…' }) as HTMLButtonElement).disabled).toBe(true)
+    expect((screen.getByRole('menuitem', { name: 'Create a new workspace' }) as HTMLButtonElement).disabled).toBe(true)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Open local folder…' }))
+    expect(b.pickDirectory).toHaveBeenCalledTimes(1)
+    await act(async () => { resolve(null); await pending })
+  })
+
+  it('reports non-Error native picker failures', async () => {
+    const b = mount([], vi.fn(), vi.fn(async () => { throw 'picker unavailable' }))
+    chooseItem('Open local folder…')
+    await waitFor(() => {
+      expect(screen.getByRole('alert').textContent).toBe('picker unavailable')
+    })
+    expect(b.createWorkspace).not.toHaveBeenCalled()
+  })
+
  it('closes a creation modal when the user cancels', () => {
    mount([])
-    chooseCreateItem('Create a new workspace')
+    chooseItem('Create a new workspace')
    fireEvent.click(screen.getByRole('button', { name: 'Cancel' }))
    expect(screen.queryByRole('dialog')).toBeNull()
  })

  it('blocks a create-new name already present in the Workspace list', () => {
    const b = mount([workspace('alpha', 'Alpha')])
-    chooseCreateItem('Create a new workspace')
+    chooseItem('Create a new workspace')
    fireEvent.change(screen.getByLabelText('New workspace name'), { target: { value: ' Alpha ' } })
    expect(screen.getByRole('alert').textContent).toBe('A workspace named “Alpha” already exists.')
    expect((screen.getByRole('button', { name: 'Create workspace' }) as HTMLButtonElement).disabled).toBe(true)
@@ -118,7 +169,7 @@ describe('WorkspacePicker', () => {
    const pending = new Promise<WorkspaceView>((settle) => { resolve = settle })
    const created = workspace('fresh', 'same-name')
    const b = mount([], vi.fn(() => pending))
-    chooseCreateItem('Create a new workspace')
+    chooseItem('Create a new workspace')
    fireEvent.change(screen.getByLabelText('New workspace name'), { target: { value: 'same-name' } })
    fireEvent.click(screen.getByRole('button', { name: 'Create workspace' }))

@@ -134,7 +185,7 @@ describe('WorkspacePicker', () => {
    const pending = new Promise<WorkspaceView>((_resolve, rejectPromise) => { reject = rejectPromise })
    const createWorkspace = vi.fn(() => pending)
    const b = mount([], createWorkspace)
-    chooseCreateItem('Create a new workspace')
+    chooseItem('Create a new workspace')
    const input = screen.getByLabelText('New workspace name')
    fireEvent.keyDown(input, { key: 'ArrowRight' })
    fireEvent.change(input, { target: { value: 'broken' } })
@@ -151,7 +202,7 @@ describe('WorkspacePicker', () => {

  it('reports non-Error creation failures', async () => {
    const b = mount([], vi.fn(async () => { throw 'permission denied' }))
-    chooseCreateItem('Create a new workspace')
+    chooseItem('Create a new workspace')
    fireEvent.click(screen.getByRole('button', { name: 'Create workspace' }))
    await waitFor(() => {
      expect(screen.getByRole('alert').textContent).toBe('Workspace creation failed: permission denied')
@@ -163,7 +214,7 @@ describe('WorkspacePicker', () => {
    render(
      <WorkspacePicker
        open useSessions={hook(sessions)} useWorkspaces={hook(workspaceState([]))}
-        onPick={vi.fn()} onClose={vi.fn()} createWorkspace={vi.fn()}
+        onPick={vi.fn()} onClose={vi.fn()} createWorkspace={vi.fn()} pickDirectory={vi.fn()}
      />,
    )
    expect(screen.queryByRole('menu')).toBeNull()
@@ -176,7 +227,7 @@ describe('WorkspacePicker', () => {
    render(
      <WorkspacePicker
        open anchorRef={anchor()} useSessions={hook(sessions)} useWorkspaces={hook(state)}
-        onPick={vi.fn()} onClose={vi.fn()} createWorkspace={vi.fn()}
+        onPick={vi.fn()} onClose={vi.fn()} createWorkspace={vi.fn()} pickDirectory={vi.fn()}
      />,
    )
    expect(screen.getByRole('status').textContent).toBe('Loading workspaces…')
@@ -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: adcffaf553bb62f77e38cf8f19f5b48e8d7881e1
-README.zh.md: 957b7967c95131f3da6cd25ce395fba8db57b020
+README.md: 253c0974cc1427fb7140c332fabdccbfc049ae86
+README.zh.md: d79628ca3e1f1d06ad94a0dada16e2208af3cd2c
@@ -14,6 +14,8 @@ The mux stream projects the latest log-backed title as a validated `session/titl

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

+`host.pickDirectory` opens one native directory picker and returns its selected path, or `null` when the user cancels. Its host implementation invokes platform tools without a shell: `osascript` on macOS, an STA PowerShell `FolderBrowserDialog` on Windows, and Zenity with a KDialog fallback on Linux. The picker function is injectable for tests. This user-paced method is the sole unary call exempt from the default 30-second timeout; caller and connection aborts still propagate to the native process. The browser carrier separately restricts this privileged method to loopback, same-origin requests.
+
 `session.history` pages on message boundaries, and its tail page (no `beforeSeq`) carries two session-level extras the page window cannot supply: the in-flight partial's chunk events, and `todos` — the latest `todo/write` whole-list projection over the full log. Older pages omit `todos` because the projection is session-level, not per-page; a tail response that omits it means the whole log holds no `todo/write`, so clients read the absent field as the empty plan rather than as unchanged state.

 The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `command.execute` runs a slash-command line host-side and returns a detached result; the carrier's request signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
@@ -35,3 +37,4 @@ None; this package neither assembles nor sends a provider request.
 - **`respond` routing is shipped, but pending-interaction state is host-side work** — the wire shape (POST `/api/respond`, `RpcReceipt`) is final; the pending table that makes late/duplicate answers meaningful lives in `src/api-proxy.ts` and is still minimal (questions only, no approvals).
 - **Reserved seams stay out of `RpcMethodMap`** — `session.fork`, `prompt.mode: 'inject'`, `task.list`, `host.listModels`, and a describe `hostInstanceId` are documented reservations; an unknown method fails loud at envelope parse rather than getting a not-implemented code.
 - **No protocol version field** — client and host ship together; `host.describe` gains a version negotiation field only when an independently released client exists.
+- **Linux native picker requires desktop tooling** — `host.pickDirectory` reports an actionable error when neither Zenity nor KDialog is installed; it does not fall back to a custom or typed-path browser.
@@ -14,6 +14,8 @@ mux 流会在每个已附加会话的订阅基线之后，以及对应的实时

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

+`host.pickDirectory` 会打开一个原生目录选择器并返回选中的路径；用户取消时返回 `null`。宿主实现不经 shell 调用平台工具：macOS 使用 `osascript`，Windows 使用以 STA 模式运行的 PowerShell `FolderBrowserDialog`，Linux 使用 Zenity，并以 KDialog 作为回退。选择器函数可在测试中注入。该方法需等待用户完成操作，是唯一不受默认 30 秒超时限制的一元调用；调用方发出的中止信号和连接中止仍会传播至原生进程。浏览器载体另行将这一特权方法限制为仅接受来自回环地址的同源请求。
+
 `session.history` 按消息边界分页，其尾页（不带 `beforeSeq`）额外携带两项页窗口本身无法提供的会话级数据：进行中局部消息的 chunk 事件，以及 `todos`——整份日志上最后一次 `todo/write` 的整表投影。较早的页面不带 `todos`，因为该投影是会话级而非分页级的；尾页响应缺少该字段意味着整份日志中没有任何 `todo/write`，因此客户端要把缺失字段读作空计划，而不是读作「状态未变」。

 `command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`command.execute` 在宿主侧运行一条斜杠命令行并返回脱耦结果；载体的请求信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
@@ -35,3 +37,4 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 - **`respond` 路由已经发布，但待处理交互状态仍属宿主侧工作**：协议形状（POST `/api/respond`、`RpcReceipt`）已经定型；使延迟或重复回答具有明确语义的待处理表位于 `src/api-proxy.ts`，目前仍很精简（只支持问题，不支持审批）。
 - **预留 seam 不进入 `RpcMethodMap`**：`session.fork`、`prompt.mode: 'inject'`、`task.list`、`host.listModels` 和描述字段 `hostInstanceId` 都是已记录的预留项；未知方法会在信封解析时直接失败，而不会返回「尚未实现」错误码。
 - **没有协议版本字段**：客户端与宿主一同发布；只有出现独立发布的客户端后，`host.describe` 才会增加版本协商字段。
+- **Linux 原生选择器依赖桌面工具**：Zenity 和 KDialog 均未安装时，`host.pickDirectory` 会给出包含解决建议的错误提示；它不会回退到自定义目录浏览器，也不会要求用户手动输入路径。
@@ -33,6 +33,7 @@ import type {
  AskUserQuestionAnswer, AskUserQuestionItem, AskUserQuestionRequest,
 } from '@deepseek-ai/dsh-user-interaction'
 import { UserInteractionError } from '@deepseek-ai/dsh-user-interaction'
+import { pickNativeDirectory } from './native-directory-picker.ts'

 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
@@ -194,6 +195,8 @@ export interface ApiProxyDefaults {
  cwd: string
  /** Parent directory for name-created workspaces. */
  workspaceRoot: string
+  /** Native single-directory picker; injectable for carrier tests. */
+  pickDirectory?: (signal: AbortSignal) => Promise<string | null>
 }

 /** The tool/call payload fields the presenter path reads. */
@@ -823,6 +826,26 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
          attachedSessions: ctx.agents.list().length,
        }))
      },
+
+      async pickDirectory(request, signal) {
+        try {
+          const path = await (defaults.pickDirectory ?? pickNativeDirectory)(signal)
+          return ok(request, { path })
+        } catch (error: unknown) {
+          if (signal.aborted) {
+            return err(request, {
+              code: 'cancelled',
+              message: 'directory picker was aborted',
+              details: {},
+            })
+          }
+          return err(request, {
+            code: 'internal',
+            message: `directory picker failed: ${error instanceof Error ? error.message : String(error)}`,
+            details: {},
+          })
+        }
+      },
    },

    commands: {
@@ -17,3 +17,11 @@ export const hostDescribeValueSchema = z.object({
  model: z.string().optional(),
  attachedSessions: z.number().int().nonnegative(),
 }) satisfies z.ZodType<Wire<ResponseValue<'host.describe'>>>
+
+/** host.pickDirectory request payload (empty object literal). */
+export const hostPickDirectoryRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'host.pickDirectory'>>>
+
+/** host.pickDirectory response value; null means the user cancelled. */
+export const hostPickDirectoryValueSchema = z.object({
+  path: z.string().nullable(),
+}) satisfies z.ZodType<Wire<ResponseValue<'host.pickDirectory'>>>
@@ -22,4 +22,10 @@ export interface HostApi {
    model?: string
    attachedSessions: number
  }>>
+
+  /** Open the operating system's single-directory picker; cancellation returns null. */
+  pickDirectory(
+    request: RpcRequest<{}>,
+    signal: AbortSignal,
+  ): Promise<RpcResponse<{ path: string | null }>>
 }
@@ -23,6 +23,7 @@ export interface RpcMethodMap {
  'session.prompt': SessionsApi['prompt']
  'session.cancel': SessionsApi['cancel']
  'host.describe': HostApi['describe']
+  'host.pickDirectory': HostApi['pickDirectory']
  'workspace.list': WorkspaceApi['list']
  'workspace.create': WorkspaceApi['create']
  'workspace.rename': WorkspaceApi['rename']
@@ -13,7 +13,7 @@ import { RpcId } from '../api/rpc.ts'
 import type { Wire } from '../api/rpc.schema.ts'
 import { rpcReceiptSchema, serverRequestSchema, serverResponseSchema } from '../api/rpc.schema.ts'
 import { hostFrameSchema, muxFrameSchema } from '../api/events.schema.ts'
-import { hostDescribeValueSchema } from '../api/host.schema.ts'
+import { hostDescribeValueSchema, hostPickDirectoryValueSchema } from '../api/host.schema.ts'
 import {
  sessionCancelValueSchema,
  sessionCreateValueSchema,
@@ -56,6 +56,7 @@ export interface IApiClient {
  }
  host: {
    describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
+    pickDirectory(payload: RequestPayload<'host.pickDirectory'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.pickDirectory'>>>
  }
  workspace: {
    list(payload: RequestPayload<'workspace.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.list'>>>
@@ -90,6 +91,7 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
  'session.prompt': sessionPromptValueSchema,
  'session.cancel': sessionCancelValueSchema,
  'host.describe': hostDescribeValueSchema,
+  'host.pickDirectory': hostPickDirectoryValueSchema,
  'workspace.list': workspaceListValueSchema,
  'workspace.create': workspaceCreateValueSchema,
  'workspace.rename': workspaceRenameValueSchema,
@@ -177,13 +179,22 @@ export abstract class AbstractApiClient implements IApiClient {
   * Shared POST leg of both C→S carriers (callUnary/respond): JSON body,
   * timeout merged with the caller's optional external signal, non-2xx → transport throw.
   */
-  private async postJson(path: string, body: ClientRequest | ClientResponse, signal: AbortSignal | undefined): Promise<Response> {
-    const timeout = AbortSignal.timeout(this.timeoutMs)
+  private async postJson(
+    path: string,
+    body: ClientRequest | ClientResponse,
+    signal: AbortSignal | undefined,
+    useDefaultTimeout = true,
+  ): Promise<Response> {
+    const requestSignal = useDefaultTimeout
+      ? signal === undefined
+        ? AbortSignal.timeout(this.timeoutMs)
+        : AbortSignal.any([AbortSignal.timeout(this.timeoutMs), signal])
+      : signal
    const response = await this.doFetch(new URL(path, this.resolveBase()), {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(body),
-      signal: signal === undefined ? timeout : AbortSignal.any([timeout, signal]),
+      ...requestSignal === undefined ? {} : { signal: requestSignal },
    })
    if (!response.ok) throw new Error(`transport failure for ${path}: HTTP ${response.status}`)
    return response
@@ -198,10 +209,11 @@ export abstract class AbstractApiClient implements IApiClient {
    method: K,
    payload: RequestPayload<K>,
    signal?: AbortSignal,
+    useDefaultTimeout = true,
  ): Promise<RpcResponse<ResponseValue<K>>> {
    const message: ClientRequest = { type: 'client-request', rpcId: this.mintRpcId(), method, payload }
    this.onEnvelope(message)
-    const response = await this.postJson(`/api/${method}`, message, signal)
+    const response = await this.postJson(`/api/${method}`, message, signal, useDefaultTimeout)
    const full = serverResponseSchema.parse(await response.json())
    this.onEnvelope(full)
    if (full.rpcId !== message.rpcId) throw new Error(`rpcId mismatch for ${method}: sent ${message.rpcId}, got ${full.rpcId}`)
@@ -282,6 +294,9 @@ export abstract class AbstractApiClient implements IApiClient {

  readonly host: IApiClient['host'] = {
    describe: (payload, signal) => this.callUnary('host.describe', payload, signal),
+    // A native system dialog is user-paced and may legitimately stay open
+    // longer than the normal unary deadline. Caller/connection aborts remain.
+    pickDirectory: (payload, signal) => this.callUnary('host.pickDirectory', payload, signal, false),
  }

  readonly workspace: IApiClient['workspace'] = {
@@ -21,7 +21,7 @@ import {
  sessionListRequestSchema,
  sessionPromptRequestSchema,
 } from '../api/sessions.schema.ts'
-import { hostDescribeRequestSchema } from '../api/host.schema.ts'
+import { hostDescribeRequestSchema, hostPickDirectoryRequestSchema } from '../api/host.schema.ts'
 import {
  workspaceCreateRequestSchema,
  workspaceDeleteRequestSchema,
@@ -55,6 +55,7 @@ const UNARY_ROUTES: UnaryRoutes = {
  'session.prompt': { schema: sessionPromptRequestSchema, invoke: (api, r) => api.sessions.prompt(r) },
  'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
  'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
+  'host.pickDirectory': { schema: hostPickDirectoryRequestSchema, invoke: (api, r, signal) => api.host.pickDirectory(r, signal) },
  'workspace.list': { schema: workspaceListRequestSchema, invoke: (api, r) => api.workspace.list(r) },
  'workspace.create': { schema: workspaceCreateRequestSchema, invoke: (api, r) => api.workspace.create(r) },
  'workspace.rename': { schema: workspaceRenameRequestSchema, invoke: (api, r) => api.workspace.rename(r) },
@@ -0,0 +1,136 @@
+/** Cross-platform native single-directory picker used by the local GUI carrier. */
+
+import { execFile } from 'node:child_process'
+
+/** Testable command boundary; native implementations never invoke a shell. */
+export type DirectoryPickerRunner = (
+  command: string,
+  args: readonly string[],
+  signal: AbortSignal,
+) => Promise<{ stdout: string; stderr: string }>
+
+/** Injectable platform facts for deterministic adapter tests. */
+export interface DirectoryPickerInternals {
+  platform?: NodeJS.Platform
+  run?: DirectoryPickerRunner
+}
+
+const runCommand: DirectoryPickerRunner = (command, args, signal) =>
+  new Promise((resolve, reject) => {
+    execFile(
+      command,
+      [...args],
+      { encoding: 'utf8', signal, windowsHide: true },
+      (error, stdout, stderr) => {
+        if (error !== null) {
+          const failure = Object.assign(new Error(error.message, { cause: error }), {
+            code: error.code,
+            stdout,
+            stderr,
+          })
+          reject(failure)
+          return
+        }
+        resolve({ stdout, stderr })
+      },
+    )
+  })
+
+function outputPath(stdout: string): string | null {
+  const path = stdout.replace(/[\r\n]+$/, '')
+  return path === '' ? null : path
+}
+
+function errorCode(error: unknown): string | number | undefined {
+  if (typeof error !== 'object' || error === null || !('code' in error)) return undefined
+  const code = (error as { code?: unknown }).code
+  return typeof code === 'string' || typeof code === 'number' ? code : undefined
+}
+
+function errorStderr(error: unknown): string {
+  if (typeof error !== 'object' || error === null || !('stderr' in error)) return ''
+  const stderr = (error as { stderr?: unknown }).stderr
+  return typeof stderr === 'string' ? stderr : ''
+}
+
+function isMissingCommand(error: unknown): boolean {
+  return errorCode(error) === 'ENOENT'
+}
+
+function rethrowIfAborted(signal: AbortSignal, error: unknown): void {
+  if (signal.aborted) throw error
+}
+
+/**
+ * Open the platform directory picker.
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - platform and runner seam for deterministic tests.
+ * @returns the selected path, or null when the user cancels.
+ */
+export async function pickNativeDirectory(
+  signal: AbortSignal,
+  internals: DirectoryPickerInternals = {},
+): Promise<string | null> {
+  const platform = internals.platform ?? process.platform
+  const run = internals.run ?? runCommand
+
+  if (platform === 'darwin') {
+    try {
+      const result = await run('osascript', [
+        '-e', 'set selectedFolder to choose folder with prompt "Select Workspace Directory"',
+        '-e', 'POSIX path of selectedFolder',
+      ], signal)
+      return outputPath(result.stdout)
+    } catch (error: unknown) {
+      if (!signal.aborted && errorCode(error) === 1
+        && /(?:User canceled|-128)/i.test(errorStderr(error))) return null
+      throw error
+    }
+  }
+
+  if (platform === 'win32') {
+    const script = [
+      "$ErrorActionPreference = 'Stop'",
+      'Add-Type -AssemblyName System.Windows.Forms',
+      '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+      "$dialog.Description = 'Select Workspace Directory'",
+      '$dialog.ShowNewFolderButton = $true',
+      '$result = $dialog.ShowDialog()',
+      'if ($result -eq [System.Windows.Forms.DialogResult]::OK) {',
+      '  [Console]::OutputEncoding = [System.Text.Encoding]::UTF8',
+      '  [Console]::WriteLine($dialog.SelectedPath)',
+      '}',
+    ].join('; ')
+    const result = await run('powershell.exe', ['-NoProfile', '-STA', '-Command', script], signal)
+    return outputPath(result.stdout)
+  }
+
+  if (platform === 'linux') {
+    try {
+      const result = await run('zenity', [
+        '--file-selection', '--directory', '--title=Select Workspace Directory',
+      ], signal)
+      return outputPath(result.stdout)
+    } catch (error: unknown) {
+      rethrowIfAborted(signal, error)
+      if (errorCode(error) === 1) return null
+      if (!isMissingCommand(error)) throw error
+    }
+
+    try {
+      const result = await run('kdialog', [
+        '--getexistingdirectory', '.', '--title', 'Select Workspace Directory',
+      ], signal)
+      return outputPath(result.stdout)
+    } catch (error: unknown) {
+      rethrowIfAborted(signal, error)
+      if (errorCode(error) === 1) return null
+      if (isMissingCommand(error)) {
+        throw new Error('no supported native directory picker found (install zenity or kdialog)')
+      }
+      throw error
+    }
+  }
+
+  throw new Error(`native directory picker is unsupported on ${platform}`)
+}
@@ -57,6 +57,7 @@ function stubAgent(session: Session): Agent {
 /** Compose the API over real Session, Agent, Storage, Domain, and Workspace services. */
 async function harness(
  workspaceRoot = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-apiproxy-workspace-'))),
+  pickDirectory?: (signal: AbortSignal) => Promise<string | null>,
 ) {
  const ctx = new Context()
  await ctx.plugin(SessionStore)
@@ -96,10 +97,33 @@ async function harness(
    model: 'test-model',
    cwd: workspaceRoot,
    workspaceRoot,
+    ...pickDirectory === undefined ? {} : { pickDirectory },
  })
  return { api, ctx, storageDomain, workspaceRoot }
 }

+describe('host.pickDirectory', () => {
+  it('returns a selected path or explicit cancellation from the injected native boundary', async () => {
+    const selected = await harness(undefined, async () => '/tmp/project')
+    expect((await selected.api.host.pickDirectory(request({}), new AbortController().signal)).result)
+      .toEqual({ ok: true, value: { path: '/tmp/project' } })
+
+    const cancelled = await harness(undefined, async () => null)
+    expect((await cancelled.api.host.pickDirectory(request({}), new AbortController().signal)).result)
+      .toEqual({ ok: true, value: { path: null } })
+  })
+
+  it('propagates abort into the native boundary as a cancelled RPC error', async () => {
+    const { api } = await harness(undefined, signal => new Promise((_resolve, reject) => {
+      signal.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
+    }))
+    const abort = new AbortController()
+    const pending = api.host.pickDirectory(request({}), abort.signal)
+    abort.abort()
+    expect((await pending).result).toMatchObject({ ok: false, error: { code: 'cancelled' } })
+  })
+})
+
 describe('workspace.create', () => {
  it('serializes concurrent names and rejects the duplicate', async () => {
    const { api, workspaceRoot } = await harness()
@@ -131,6 +155,13 @@ describe('workspace.create', () => {
    expect(first).toMatchObject({ created: true, workspace: { path: existing, title: 'existing' } })
    expect(repeated).toMatchObject({ created: false, workspace: { workspaceId: first.workspace.workspaceId } })

+    expectOk(await api.workspace.rename(request({
+      workspaceId: first.workspace.workspaceId,
+      title: 'renamed-existing',
+    })))
+    const reopened = expectOk(await api.workspace.create(request({ path: existing })))
+    expect(reopened.workspace.title).toBe('renamed-existing')
+
    const missing = join(workspaceRoot, 'missing')
    const missingResult = await api.workspace.create(request({ path: missing }))
    expect(missingResult.result).toMatchObject({ ok: false, error: { code: 'workspace-invalid-path' } })
@@ -141,6 +172,20 @@ describe('workspace.create', () => {
      expect(invalid.result).toMatchObject({ ok: false, error: { code: 'workspace-invalid-path' } })
    }
  })
+
+  it('rejects different paths that derive the same Workspace title', async () => {
+    const { api, workspaceRoot } = await harness()
+    const first = join(workspaceRoot, 'one', 'project')
+    const second = join(workspaceRoot, 'two', 'project')
+    mkdirSync(first, { recursive: true })
+    mkdirSync(second, { recursive: true })
+    expectOk(await api.workspace.create(request({ path: first })))
+    const conflict = await api.workspace.create(request({ path: second }))
+    expect(conflict.result).toMatchObject({
+      ok: false,
+      error: { code: 'workspace-name-conflict', details: { name: 'project' } },
+    })
+  })
 })

 describe('session creation and Workspace membership', () => {
@@ -35,7 +35,11 @@ function scriptedApi(overrides: {
      cancel: r => ok(r, { accepted: true as const }),
      ...overrides.sessions,
    },
-    host: { describe: r => ok(r, { version: '0-test', cwd: '/t', attachedSessions: 0 }), ...overrides.host },
+    host: {
+      describe: r => ok(r, { version: '0-test', cwd: '/t', attachedSessions: 0 }),
+      pickDirectory: r => ok(r, { path: null }),
+      ...overrides.host,
+    },
    workspace: {
      list: r => ok(r, { items: [] }),
      create: r => ok(r, { workspace: { workspaceId: 'w1' as never, path: '/t', title: 't', sessionIds: [], createdAt: '0', updatedAt: '0' }, created: true }),
@@ -47,6 +47,9 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
      async describe(request) {
        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 } } }
+      },
    },
    workspace: {
      async list(request) {
@@ -108,8 +111,8 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
  }
 }

-function client(api: ApiProxy = fakeApi()): InProcessApiClient {
-  return new InProcessApiClient(toFetchHandler(api))
+function client(api: ApiProxy = fakeApi(), timeoutMs?: number): InProcessApiClient {
+  return new InProcessApiClient(toFetchHandler(api), timeoutMs)
 }

 async function collect<F>(stream: AsyncIterable<RpcRequest<F>>): Promise<RpcRequest<F>[]> {
@@ -145,6 +148,16 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
    expect((await c.host.describe({})).result.ok).toBe(true)
  })

+  it('round-trips the native picker without the default unary timeout', async () => {
+    const api = fakeApi()
+    api.host.pickDirectory = async (request) => {
+      await new Promise(resolve => setTimeout(resolve, 15))
+      return { rpcId: request.rpcId, result: { ok: true, value: { path: '/tmp/project' } } }
+    }
+    const response = await client(api, 1).host.pickDirectory({})
+    expect(response.result).toEqual({ ok: true, value: { path: '/tmp/project' } })
+  })
+
  it('round-trips command.list / command.execute / skill.list through the wire form', async () => {
    const c = client()
    const list = await c.commands.list({ sessionId: 's' as never })
@@ -170,6 +183,30 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
    expect(parsed.rpcId).toBe('r-sig')
    expect(parsed.result.error?.code).toBe('cancelled')
  })
+
+  it('propagates the carrier Request signal into host.pickDirectory', async () => {
+    const api = fakeApi()
+    api.host.pickDirectory = async (request, signal) => {
+      if (!signal.aborted) {
+        await new Promise<void>((resolve) => {
+          signal.addEventListener('abort', () => { resolve() }, { once: true })
+        })
+      }
+      return {
+        rpcId: request.rpcId,
+        result: { ok: false, error: { code: 'cancelled', message: 'aborted', details: {} } },
+      }
+    }
+    const handler = toFetchHandler(api)
+    const controller = new AbortController()
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-picker', method: 'host.pickDirectory', payload: {} })
+    const pending = handler.fetch(new Request('http://x/api/host.pickDirectory', {
+      method: 'POST', body, signal: controller.signal,
+    }))
+    controller.abort()
+    const parsed = await (await pending).json() as { result: { error?: { code: string } } }
+    expect(parsed.result.error?.code).toBe('cancelled')
+  })
 })

 describe('handler carrier-layer statuses', () => {
@@ -0,0 +1,139 @@
+type ExecFileCallback = (
+  error: (Error & { code?: string | number }) | null,
+  stdout: string,
+  stderr: string,
+) => void
+type ExecFileMock = (
+  command: string,
+  args: readonly string[],
+  options: { encoding: string; signal: AbortSignal; windowsHide: boolean },
+  callback: ExecFileCallback,
+) => void
+
+const { execFileMock } = vi.hoisted(() => ({ execFileMock: vi.fn<ExecFileMock>() }))
+
+vi.mock('node:child_process', () => ({ execFile: execFileMock }))
+
+import { describe, expect, it, vi } from 'vitest'
+import { pickNativeDirectory, type DirectoryPickerRunner } from '../src/native-directory-picker.ts'
+
+function failure(code: string | number, stderr = ''): Error {
+  return Object.assign(new Error(`command failed: ${String(code)}`), { code, stderr })
+}
+
+const signal = () => new AbortController().signal
+
+describe('native directory picker', () => {
+  it('uses the macOS folder chooser and maps user cancellation to null', async () => {
+    const run = vi.fn<DirectoryPickerRunner>(async () => ({ stdout: '/Users/test/project/\n', stderr: '' }))
+    await expect(pickNativeDirectory(signal(), { platform: 'darwin', run })).resolves.toBe('/Users/test/project/')
+    expect(run).toHaveBeenCalledWith('osascript', expect.arrayContaining(['POSIX path of selectedFolder']), expect.any(AbortSignal))
+
+    run.mockRejectedValueOnce(failure(1, 'execution error: User canceled. (-128)'))
+    await expect(pickNativeDirectory(signal(), { platform: 'darwin', run })).resolves.toBeNull()
+
+    run.mockRejectedValueOnce(failure(2, 'permission denied'))
+    await expect(pickNativeDirectory(signal(), { platform: 'darwin', run })).rejects.toThrow('command failed')
+  })
+
+  it.each([
+    ['a primitive error', 'failed'],
+    ['an invalid code type', { code: true }],
+    ['a missing stderr property', { code: 1 }],
+    ['a non-string stderr property', { code: 1, stderr: 42 }],
+  ])('does not mistake %s for macOS cancellation', async (_label, reason) => {
+    const run = vi.fn<DirectoryPickerRunner>(async () => { throw reason })
+    await expect(pickNativeDirectory(signal(), { platform: 'darwin', run })).rejects.toBe(reason)
+  })
+
+  it('uses the Windows STA folder dialog and maps empty output to cancellation', async () => {
+    const run = vi.fn<DirectoryPickerRunner>(async () => ({ stdout: 'C:\\work\\project\r\n', stderr: '' }))
+    await expect(pickNativeDirectory(signal(), { platform: 'win32', run })).resolves.toBe('C:\\work\\project')
+    expect(run).toHaveBeenCalledWith(
+      'powershell.exe',
+      expect.arrayContaining(['-NoProfile', '-STA', '-Command']),
+      expect.any(AbortSignal),
+    )
+    expect(run.mock.calls[0]?.[1].at(-1)).toContain("$ErrorActionPreference = 'Stop'")
+    run.mockResolvedValueOnce({ stdout: '', stderr: '' })
+    await expect(pickNativeDirectory(signal(), { platform: 'win32', run })).resolves.toBeNull()
+    run.mockRejectedValueOnce(failure(1, 'Add-Type failed'))
+    await expect(pickNativeDirectory(signal(), { platform: 'win32', run })).rejects.toThrow('command failed')
+  })
+
+  it('runs the default command adapter without a shell and preserves command failures', async () => {
+    execFileMock.mockImplementationOnce((_command, _args, _options, callback) => {
+      callback(null, 'C:\\work\\default\r\n', '')
+    })
+    await expect(pickNativeDirectory(signal(), { platform: 'win32' })).resolves.toBe('C:\\work\\default')
+    const [command, args, options] = execFileMock.mock.calls[0]!
+    expect(command).toBe('powershell.exe')
+    expect(args).toEqual(expect.arrayContaining(['-NoProfile', '-STA', '-Command']))
+    expect(options.encoding).toBe('utf8')
+    expect(options.windowsHide).toBe(true)
+    expect(options.signal).toBeInstanceOf(AbortSignal)
+
+    const commandError = Object.assign(new Error('powershell failed'), { code: 7 })
+    execFileMock.mockImplementationOnce((_command, _args, _options, callback) => {
+      callback(commandError, 'partial output', 'failure details')
+    })
+    await expect(pickNativeDirectory(signal(), { platform: 'win32' })).rejects.toMatchObject({
+      message: 'powershell failed', cause: commandError, code: 7,
+      stdout: 'partial output', stderr: 'failure details',
+    })
+  })
+
+  it('uses the current process platform when no platform override is supplied', async () => {
+    const run = vi.fn<DirectoryPickerRunner>(async () => ({ stdout: '/default/platform\n', stderr: '' }))
+    await expect(pickNativeDirectory(signal(), { run })).resolves.toBe('/default/platform')
+  })
+
+  it('uses Zenity on Linux and falls back to KDialog only when Zenity is missing', async () => {
+    const run = vi.fn<DirectoryPickerRunner>()
+      .mockRejectedValueOnce(failure('ENOENT'))
+      .mockResolvedValueOnce({ stdout: '/home/test/project\n', stderr: '' })
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run })).resolves.toBe('/home/test/project')
+    expect(run.mock.calls.map(call => call[0])).toEqual(['zenity', 'kdialog'])
+
+    const zenity = vi.fn<DirectoryPickerRunner>(async () => ({ stdout: '/home/test/direct\n', stderr: '' }))
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: zenity }))
+      .resolves.toBe('/home/test/direct')
+    expect(zenity).toHaveBeenCalledOnce()
+  })
+
+  it('maps Linux cancellation to null and reports a missing desktop picker', async () => {
+    const cancelled = vi.fn<DirectoryPickerRunner>(async () => { throw failure(1) })
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: cancelled })).resolves.toBeNull()
+
+    const missing = vi.fn<DirectoryPickerRunner>(async () => { throw failure('ENOENT') })
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: missing }))
+      .rejects.toThrow('install zenity or kdialog')
+
+    const kdialogCancelled = vi.fn<DirectoryPickerRunner>()
+      .mockRejectedValueOnce(failure('ENOENT'))
+      .mockRejectedValueOnce(failure(1))
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: kdialogCancelled }))
+      .resolves.toBeNull()
+
+    const zenityFailed = vi.fn<DirectoryPickerRunner>(async () => { throw failure(2) })
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: zenityFailed }))
+      .rejects.toThrow('command failed')
+
+    const kdialogFailed = vi.fn<DirectoryPickerRunner>()
+      .mockRejectedValueOnce(failure('ENOENT'))
+      .mockRejectedValueOnce(failure(2))
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: kdialogFailed }))
+      .rejects.toThrow('command failed')
+  })
+
+  it('does not convert caller aborts into user cancellation', async () => {
+    const abort = new AbortController()
+    abort.abort(new Error('closed'))
+    const run = vi.fn<DirectoryPickerRunner>(async () => { throw failure('ABORT_ERR') })
+    await expect(pickNativeDirectory(abort.signal, { platform: 'linux', run })).rejects.toThrow('command failed')
+  })
+
+  it('reports unsupported platforms', async () => {
+    await expect(pickNativeDirectory(signal(), { platform: 'aix' })).rejects.toThrow('unsupported on aix')
+  })
+})