Merge remote-tracking branch 'origin/master' into web-permission-sandbox-merge-master

2026-07-29 11:16:49 +08:00
parent efc7c14a7c 75b32f7d76
commit 5c432955ed
222 changed files with 8347 additions and 1465 deletions
--- a/packages/client/ui-workspace/README.i18n.yaml
+++ b/packages/client/ui-workspace/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-workspace/README.md
-README.md: edd6c2f9373d97832def86bb44658d7c1c68dae9
-README.zh.md: f7b73dde953d4294d4d157f479fe932adf1a29c4
+README.md: 8acf819121b46512d38b39ff858bb2bf797cfe96
+README.zh.md: e97d93f7e38d00af91b43f0df9fb0e3b17ae8ed5
--- a/packages/client/ui-workspace/README.md
+++ b/packages/client/ui-workspace/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)

 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 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.
+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. Each registration declares a **directory-flow child hole** (`single` kind: `conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`) that the composed picker package's client half fills with its picking interaction — the [`-native`](../../host/directory-picker-native/README.md) backend's renderless OS-chooser driver today, an in-app browsing dialog under a `-browse` composition. The flat **Open local folder...** action renders only while the surface's hole is occupied (occupancy read per menu render; an empty hole means the composition has no picking affordance — the seam's documented no-flow default). This package owns the trigger and the adoption: the occupant reports one picked path per open through the hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`), and the owner adopts it through the object layer, selecting the committed Workspace only after its list projection has refreshed; cancellation is silent, and errors land in the retryable folder dialog whose **Choose again** reopens the flow. **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.
- **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.
+- **Native folder selection depends on the local Host carrier** — under the `-native` composition, fixture-only or remote browser deployments cannot open a local operating-system dialog; platform failures are shown in a retryable modal. Remote-capable picking is the `-browse` composition's in-app flow.
--- a/packages/client/ui-workspace/README.zh.md
+++ b/packages/client/ui-workspace/README.zh.md
@@ -4,7 +4,7 @@

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

-该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。平铺显示的 **打开本地文件夹…** 操作会委托 Host 的原生单目录选择器，通过对象层接纳返回的路径，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，发生错误后仍可重试。**创建新工作区** 操作保留名称对话框，并禁用列表中已有的名称，而 Host 对并发或非 UI 调用方仍具有最终决定权。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。
+该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。每个注册各自声明一个**目录流子洞**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **打开本地文件夹…** 操作仅在本表层的洞被占用时渲染（每次菜单渲染读取占用状态；洞为空意味着该组合没有选目录能力——seam 文档化的无流程默认行为）。本包持有触发与接纳：占用者经洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。**创建新工作区** 操作保留名称对话框，并禁用列表中已有的名称，而 Host 对并发或非 UI 调用方仍具有最终决定权。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。

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

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

 - **没有 Session 删除控件**：现有 Session 菜单行仍仅提供视觉效果；删除 Workspace 注册记录不会删除 Session。
- **原生文件夹选择依赖本地 Host 载体**：仅使用 fixture（测试前置数据）的部署或远程浏览器部署无法打开本地操作系统对话框；模态框会显示平台故障，并允许重试。
+- **原生文件夹选择依赖本地 Host 载体**：在 `-native` 组合下，仅使用 fixture（测试前置数据）的部署或远程浏览器部署无法打开本地操作系统对话框；模态框会显示平台故障，并允许重试。可远程的选取是 `-browse` 组合的应用内流程。
--- a/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx
+++ b/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx
@@ -253,7 +253,8 @@ export function WorkspaceBrowser({
  deleteWorkspace,
  insertSessionBefore,
  createWorkspace,
-  pickDirectory,
+  useDirectoryFlow,
+  renderSlot,
 }: WorkspaceBrowserProps) {
  const workspaces = useWorkspaces(state => state.items)
  const groupBy = useStore(s => s.groupBy)
@@ -371,7 +372,8 @@ export function WorkspaceBrowser({
          anchorRef={wsPlusRef}
          useWorkspaces={useWorkspaces}
          createWorkspace={createWorkspace}
-          pickDirectory={pickDirectory}
+          useDirectoryFlow={useDirectoryFlow}
+          renderDirectoryFlow={owner => renderSlot('sidebar.workspaces.directoryFlow', owner)}
          createOnly
          side="right"
          onPick={(workspaceId) => {
--- a/packages/client/ui-workspace/src/client/WorkspacePicker.tsx
+++ b/packages/client/ui-workspace/src/client/WorkspacePicker.tsx
@@ -2,10 +2,12 @@
 * Workspace pick/create flow. WorkspaceCreateFlow is the reusable core
 * (menu + path/create dialogs) consumed directly by WorkspaceBrowser (same
 * package) and wrapped by WorkspacePicker for the conversation empty-state
- * slot registration.
+ * slot registration. Directory picking itself lives in the composed flow
+ * package's slot occupant (see the contract module doc): this core only
+ * opens the flow, adopts the picked path, and owns the error surface.
 */
-import type { RefObject } from 'react'
-import { useCallback, useRef, useState } from 'react'
+import type { ReactNode, RefObject } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import {
  Button, IconFolderClose16, IconPlusOutline16, Menu, Modal, type MenuEntry,
 } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -13,7 +15,8 @@ import {
  WorkspaceCreateError,
  type WorkspaceId, type WorkspaceListState, type WorkspaceView,
 } from '@deepseek-ai/dsh-client-runtime/client'
-import type { WorkspacePickerProps } from './contract/slots.ts'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
+import type { DirectoryFlowOwnerProps, WorkspacePickerProps } from './contract/slots.ts'
 import css from './WorkspacePicker.module.css'

 const OPEN_LOCAL_FOLDER = '::open-local-folder'
@@ -31,8 +34,10 @@ 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>
+  /** Bound occupancy selector hook for this surface's directory-flow hole (empty hides the local-folder entry). */
+  useDirectoryFlow: SnapshotSelectorHook<boolean>
+  /** Render this surface's directory-flow hole with the owner conversation (the entry's narrowed renderSlot). */
+  renderDirectoryFlow: (owner: DirectoryFlowOwnerProps) => ReactNode
  /** A real Workspace was picked or created. */
  onPick: (workspaceId: WorkspaceId) => void
  /** Close the popover (outside click / Escape / post-pick). */
@@ -55,7 +60,8 @@ export function WorkspaceCreateFlow({
  anchorRef,
  useWorkspaces,
  createWorkspace,
-  pickDirectory,
+  useDirectoryFlow,
+  renderDirectoryFlow,
  onPick,
  onClose,
  createOnly = false,
@@ -72,16 +78,37 @@ export function WorkspaceCreateFlow({
  const [workspaceName, setWorkspaceName] = useState('')
  const [creating, setCreating] = useState(false)
  const [modalError, setModalError] = useState<string | null>(null)
+  const [flowOpen, setFlowOpen] = useState(false)
  const [pickingFolder, setPickingFolder] = useState(false)
  const [folderConflict, setFolderConflict] = useState(false)
  const composingRef = useRef(false)
+  // One picking interaction at a time: while the flow is open (native chooser
+  // pending, browse dialog up) or its pick is being adopted, every other
+  // menu action stays disabled — a late outcome must not race a concurrent
+  // selection or creation.
+  const flowBusy = flowOpen || pickingFolder
  const normalizedWorkspaceName = workspaceName.trim()
  const duplicateWorkspaceName = !creating && normalizedWorkspaceName !== ''
    && workspaces.some(workspace => workspace.title === normalizedWorkspaceName)

+  // The occupied hole gates the picking affordance: with no composed flow the
+  // entry simply is not there (the seam's documented no-flow default). The
+  // framework-bound hook keeps occupancy live: flow plugins activate (and
+  // HMR-reload) independently of this menu's renders.
+  const flowAvailable = useDirectoryFlow(occupied => occupied)
+  // An occupant that unloads mid-interaction leaves nobody to cancel: an
+  // open flow over an empty hole withdraws so the menu actions come back.
+  // flowOpen is a dependency because the flow can also OPEN over an already
+  // empty hole (Choose again after the occupant unloaded with the error
+  // dialog up) — that transition must snap back too, not just occupancy loss.
+  useEffect(() => {
+    if (flowOpen && !flowAvailable) setFlowOpen(false)
+  }, [flowOpen, flowAvailable])
  const createEntries: MenuEntry[] = [
-    { 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 },
+    ...(flowAvailable
+      ? [{ id: OPEN_LOCAL_FOLDER, label: 'Open local folder…', icon: <IconFolderClose16 size={16} />, disabled: flowBusy }]
+      : []),
+    { id: CREATE_NEW, label: 'Create a new workspace', icon: <IconPlusOutline16 size={16} />, disabled: flowBusy },
  ]
  // With workspaces listed, the create actions pin below the scroll region
  // (divider + always visible); otherwise they ARE the menu.
@@ -91,7 +118,7 @@ export function WorkspaceCreateFlow({
      id: workspace.workspaceId,
      label: workspace.title,
      icon: <IconFolderClose16 size={16} />,
-      disabled: pickingFolder,
+      disabled: flowBusy,
    }))
    : createEntries

@@ -101,15 +128,10 @@ 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 })
+  /** Adopt a picked directory; failures land in the folder-error dialog (Choose again reopens the flow). */
+  const adoptDirectory = (path: string): Promise<void> =>
+    createWorkspace({ path }).then((workspace) => {
+      setFlowOpen(false)
      onPick(workspace.workspaceId)
    }).catch((reason: unknown) => {
      setFolderConflict(
@@ -117,8 +139,33 @@ export function WorkspaceCreateFlow({
        && reason.rpcError.code === 'workspace-name-conflict',
      )
      setModalError(reason instanceof Error ? reason.message : String(reason))
+      setFlowOpen(false)
      setModalKind('folder-error')
-    }).finally(() => { setPickingFolder(false) })
+    })
+
+  const openLocalFolder = (): void => {
+    onClose()
+    setModalKind(null)
+    setModalError(null)
+    setFolderConflict(false)
+    setFlowOpen(true)
+  }
+
+  /** Owner side of the flow conversation: adopt keeps the flow open (busy) until the Host answers. */
+  const flowOwner: DirectoryFlowOwnerProps = {
+    open: flowOpen,
+    busy: pickingFolder,
+    onPicked: (path) => {
+      setPickingFolder(true)
+      void adoptDirectory(path).finally(() => { setPickingFolder(false) })
+    },
+    onCancel: () => { setFlowOpen(false) },
+    onError: (message) => {
+      setFlowOpen(false)
+      setFolderConflict(false)
+      setModalError(message)
+      setModalKind('folder-error')
+    },
  }

  const handleSelect = (id: string): void => {
@@ -172,6 +219,7 @@ export function WorkspaceCreateFlow({
        getAnchorRect={getAnchorRect}
      />
      {open && workspaceSnapshot.phase === 'pending' && <div className={css.menuStatus} role="status">Loading workspaces…</div>}
+      {renderDirectoryFlow(flowOwner)}
      <Modal
        open={modalKind === 'folder-error'}
        onClose={closeModal}
@@ -179,7 +227,9 @@ export function WorkspaceCreateFlow({
        footer={(
          <>
            <Button variant="outline" className={css.modalAction} onClick={closeModal}>Cancel</Button>
-            <Button variant="primary" className={css.modalAction} onClick={openLocalFolder}>Choose again</Button>
+            {/* Retrying needs an occupant to serve the flow; without one the
+              * button would open a flow nobody can answer or cancel. */}
+            <Button variant="primary" className={css.modalAction} disabled={!flowAvailable} onClick={openLocalFolder}>Choose again</Button>
          </>
        )}
      >
@@ -249,7 +299,8 @@ export function WorkspacePicker({
  onPick,
  onClose,
  createWorkspace,
-  pickDirectory,
+  useDirectoryFlow,
+  renderSlot,
 }: WorkspacePickerProps) {
  return (
    <WorkspaceCreateFlow
@@ -257,7 +308,8 @@ export function WorkspacePicker({
      anchorRef={anchorRef}
      useWorkspaces={useWorkspaces}
      createWorkspace={createWorkspace}
-      pickDirectory={pickDirectory}
+      useDirectoryFlow={useDirectoryFlow}
+      renderDirectoryFlow={owner => renderSlot('conversation.hero.workspace.directoryFlow', owner)}
      selectedId={selectedId}
      onPick={onPick}
      onClose={onClose}
--- a/packages/client/ui-workspace/src/client/contract/slots.ts
+++ b/packages/client/ui-workspace/src/client/contract/slots.ts
@@ -7,8 +7,19 @@
 *   consumes the shell's two-fact owner share (wide / expandSidebar).
 * - WorkspacePicker fills the conversation empty-state hole (menu +
 *   create dialogs shared with the browser).
+ *
+ * Each registration also declares one **directory-flow hole** (`single`
+ * kind): the slot a composed picker package's client half fills with its
+ * picking interaction — a renderless native-chooser driver or an in-app
+ * browsing dialog. ui-workspace owns the trigger (the "Open local folder…"
+ * menu entry, shown only while the hole is occupied) and the adoption
+ * semantics (`createWorkspace({ path })`, the conflict/error dialog, Choose
+ * again); the occupant owns everything between `open` and the picked path.
+ * Two holes exist because the two menu surfaces are independent slot entries
+ * and a hole has exactly one declaring entry — they carry the same owner
+ * contract and the same occupant.
 */
-import type { PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
+import type { HostObservable, PropsRenderSlots, PropsRuntime, PropsStore, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 // Type-only: pull the owner SlotMap merges into programs that resolve the
 // runtime shares below.
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar/client'
@@ -16,12 +27,64 @@ import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { SessionId, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-runtime/client'
 import type { createWorkspaceViewStore } from '../stores.ts'

+/**
+ * Owner share of the directory-flow holes: the complete conversation between
+ * the trigger surface and the picking interaction. The occupant reads `open`
+ * to run/render its interaction and reports exactly one outcome per open.
+ */
+export interface DirectoryFlowOwnerProps {
+  /** True while a picking interaction is requested; flipping back to false withdraws the request. */
+  open: boolean
+  /** True while the owner adopts a picked path (`createWorkspace` in flight); occupants disable their commit affordances. */
+  busy: boolean
+  /** The operator picked a directory (absolute host path); the owner adopts it. */
+  onPicked: (path: string) => void
+  /** The operator dismissed the interaction; the owner just closes the flow. */
+  onCancel: () => void
+  /** The interaction itself failed (chooser missing, listing denied); the owner shows its error surface. */
+  onError: (message: string) => void
+}
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /** Directory-flow hole under the conversation empty-state picker (declared by the WorkspacePicker entry). */
+    'conversation.hero.workspace.directoryFlow': { kind: 'single'; scope: 'root'; owner: DirectoryFlowOwnerProps }
+    /** Directory-flow hole under the sidebar browsing region (declared by the WorkspaceBrowser entry). */
+    'sidebar.workspaces.directoryFlow': { kind: 'single'; scope: 'root'; owner: DirectoryFlowOwnerProps }
+  }
+}
+
+/** The two directory-flow holes; a flow package's client half registers its one component into both. */
+export type DirectoryFlowSlotName =
+  | 'conversation.hero.workspace.directoryFlow'
+  | 'sidebar.workspaces.directoryFlow'
+
+/**
+ * Directory-picking share both trigger surfaces consume. Occupancy rides the
+ * inject face's reserved `hooks` compartment: the renderer binds the source
+ * into the `useDirectoryFlow` selector hook, so an empty hole hides the
+ * "Open local folder…" entry reactively and the surface withdraws an open
+ * flow whose occupant unloaded mid-interaction (nobody is left to cancel).
+ */
+export type DirectoryPickingInjected = {
+  hooks: {
+    /** True while this surface's directory-flow hole is occupied. */
+    directoryFlow: HostObservable<boolean>
+  }
+}
+
+/** Component-side view of the picking share: the bound occupancy selector hook. */
+export type DirectoryPickingHooks = {
+  /** Selector hook over this surface's directory-flow occupancy. */
+  useDirectoryFlow: SnapshotSelectorHook<boolean>
+}
+
 /**
 * Browser-private injected share (arrives via the register inject factory).
 * Data reads use the global framework hooks; these are the Host actions the
 * browsing region drives.
 */
-export type WorkspaceBrowserInjected = {
+export type WorkspaceBrowserInjected = DirectoryPickingInjected & {
  /**
   * Start a New Session in a Workspace: reuse-or-create its blank session
   * and open it; with no workspace, clear the selection into the New Session
@@ -42,26 +105,24 @@ 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. */
 export type WorkspaceBrowserProps =
  PropsRuntime<'sidebar.workspaces'>
+  & PropsRenderSlots<'sidebar.workspaces.directoryFlow'>
  & PropsStore<ReturnType<typeof createWorkspaceViewStore>>
-  & WorkspaceBrowserInjected
+  & Omit<WorkspaceBrowserInjected, 'hooks'>
+  & DirectoryPickingHooks

 /**
 * Picker-private injected share. Pick semantics remain in the owner's onPick
 * callback; this callback creates only the real Host Workspace. A type alias
 * supplies the implicit index signature required by the registry.
 */
-export type WorkspacePickerInjected = {
+export type WorkspacePickerInjected = DirectoryPickingInjected & {
  /** 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>
 }

 /**
@@ -70,4 +131,7 @@ export type WorkspacePickerInjected = {
 * currency, so one composed type serves both registrations.
 */
 export type WorkspacePickerProps =
-  PropsRuntime<'conversation.hero.workspace'> & WorkspacePickerInjected
+  PropsRuntime<'conversation.hero.workspace'>
+  & PropsRenderSlots<'conversation.hero.workspace.directoryFlow'>
+  & Omit<WorkspacePickerInjected, 'hooks'>
+  & DirectoryPickingHooks
--- a/packages/client/ui-workspace/src/client/index.ts
+++ b/packages/client/ui-workspace/src/client/index.ts
@@ -3,9 +3,13 @@
 * the sidebar shell's `sidebar.workspaces` hole (the whole browsing region),
 * and WorkspacePicker fills the conversation hero's picker hole
 * (`conversation.hero.workspace` — both hero forms). Both read real Host
- * Workspaces through the global useWorkspaces hook. Export discipline:
+ * Workspaces through the global useWorkspaces hook, and each declares its
+ * own `single` directory-flow child hole for the composed picker package's
+ * client half (see the contract module doc). Export discipline:
 * packages/client/AGENTS.md.
 */
+import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots'
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { WorkspaceBrowserInjected, WorkspacePickerInjected } from './contract/slots.ts'
 import { createWorkspaceViewStore } from './stores.ts'
@@ -13,6 +17,7 @@ import { WorkspaceBrowser } from './WorkspaceBrowser.tsx'
 import { WorkspacePicker } from './WorkspacePicker.tsx'

 export type {
+  DirectoryFlowOwnerProps, DirectoryFlowSlotName, DirectoryPickingHooks, DirectoryPickingInjected,
  WorkspaceBrowserInjected, WorkspaceBrowserProps, WorkspacePickerInjected, WorkspacePickerProps,
 } from './contract/slots.ts'

@@ -33,6 +38,14 @@ export const inject = ['slots', 'sessions', 'workspaces']
 * @param ctx - client root context.
 */
 export function apply(ctx: ClientContext): void {
+  // Stable per-surface occupancy sources (the renderer's hook cache keys by
+  // source identity): true while the surface's directory-flow hole is filled.
+  const flowSource = (hole: 'sidebar.workspaces.directoryFlow' | 'conversation.hero.workspace.directoryFlow'): HostObservable<boolean> => ({
+    getSnapshot: () => ctx.slots.entries(hole).length > 0,
+    subscribe: listener => ctx.slots.subscribe(hole, listener),
+  })
+  const browserFlowSource = flowSource('sidebar.workspaces.directoryFlow')
+  const pickerFlowSource = flowSource('conversation.hero.workspace.directoryFlow')
  const browserInjected = (): WorkspaceBrowserInjected => ({
    // Explicit group actions keep their target; unscoped New Session rides
    // the runtime's shared action (recent-Workspace projection inside).
@@ -44,48 +57,40 @@ export function apply(ctx: ClientContext): void {
      await ctx.workspaces.insertSessionBefore(workspaceId, sessionId, beforeSessionId)
    },
    createWorkspace: input => ctx.workspaces.create(input),
-    pickDirectory: () => ctx.workspaces.pickDirectory(),
+    hooks: { directoryFlow: browserFlowSource },
  })
  const pickerInjected = (): WorkspacePickerInjected => ({
    createWorkspace: input => ctx.workspaces.create(input),
-    pickDirectory: () => ctx.workspaces.pickDirectory(),
+    hooks: { directoryFlow: pickerFlowSource },
  })
-  // Declaration-aware registration: each owner's declaring apply may activate
-  // after this one (entry activation order is unconstrained), and a register
-  // into an undeclared slot throws. Register once the declaration is on the
-  // ledger; the subscription also re-registers after an HMR collapse
-  // re-declares the slot (the cascade disposed our entry with it).
+  // Declaration-aware registration (deferRegistration): each owner's
+  // declaring apply may activate after this one, and a register into an
+  // undeclared slot throws; the deferral also re-registers after an HMR
+  // collapse re-declares the slot. Each registration declares its own
+  // directory-flow child hole in the same call (declaration = render
+  // authorization, one table).
  ctx.effect(() => {
-    const registrations = [
-      {
-        name: 'sidebar.workspaces' as const,
-        component: WorkspaceBrowser,
-        register: () => ctx.slots.register(
-          { name: 'sidebar.workspaces', store: createWorkspaceViewStore(), inject: browserInjected },
+    const deferred = [
+      deferRegistration(ctx.slots, 'sidebar.workspaces', WorkspaceBrowser, () =>
+        ctx.slots.register(
+          {
+            name: 'sidebar.workspaces',
+            children: { 'sidebar.workspaces.directoryFlow': { kind: 'single', scope: 'root' } },
+            store: createWorkspaceViewStore(),
+            inject: browserInjected,
+          },
          WorkspaceBrowser,
-        ),
-      },
-      {
-        name: 'conversation.hero.workspace' as const,
-        component: WorkspacePicker,
-        register: () => ctx.slots.register(
-          { name: 'conversation.hero.workspace', inject: pickerInjected },
+        )),
+      deferRegistration(ctx.slots, 'conversation.hero.workspace', WorkspacePicker, () =>
+        ctx.slots.register(
+          {
+            name: 'conversation.hero.workspace',
+            children: { 'conversation.hero.workspace.directoryFlow': { kind: 'single', scope: 'root' } },
+            inject: pickerInjected,
+          },
          WorkspacePicker,
-        ),
-      },
+        )),
    ]
-    const disposers = new Map<string, () => void>()
-    const tryRegister = (entry: (typeof registrations)[number]): void => {
-      if (ctx.slots.spec(entry.name) === undefined) return
-      if (ctx.slots.entries(entry.name).some(e => e.component === entry.component)) return
-      disposers.set(entry.name, entry.register())
-    }
-    const unsubscribers = registrations.map(entry =>
-      ctx.slots.subscribe(entry.name, () => { tryRegister(entry) }))
-    for (const entry of registrations) tryRegister(entry)
-    return () => {
-      for (const unsubscribe of unsubscribers) unsubscribe()
-      for (const dispose of disposers.values()) dispose()
-    }
+    return () => { for (const entry of deferred) entry.dispose() }
  }, 'ui-workspace: browser + picker registrations')
 }
--- a/packages/client/ui-workspace/tests/apply.spec.ts
+++ b/packages/client/ui-workspace/tests/apply.spec.ts
@@ -14,17 +14,16 @@ 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, pickDirectory, startSession, rename, insertSessionBefore,
+    create, startSession, rename, insertSessionBefore,
  } as never)
  ctx.provide('sessions', { open, clear } as never)
-  return { ctx, slots: ctx.get('slots') as SlotsService, create, pickDirectory, startSession, rename, insertSessionBefore, open, clear }
+  return { ctx, slots: ctx.get('slots') as SlotsService, create, startSession, rename, insertSessionBefore, open, clear }
 }

 type HoleName = 'sidebar.workspaces' | 'conversation.hero.workspace' | 'conversation.empty.workspace'
@@ -73,14 +72,35 @@ 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('declares the two directory-flow holes and reports their occupancy per surface', async () => {
+    const b = await bench()
+    declare(b.slots, 'sidebar.workspaces', 'conversation.hero.workspace')
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    // Registration declared the child holes (declaration = render authorization).
+    expect(b.slots.spec('sidebar.workspaces.directoryFlow')).toMatchObject({ kind: 'single' })
+    expect(b.slots.spec('conversation.hero.workspace.directoryFlow')).toMatchObject({ kind: 'single' })
+
+    const browser = (b.slots.entries('sidebar.workspaces')[0]!.inject as () => WorkspaceBrowserInjected)()
+    const picker = (b.slots.entries('conversation.hero.workspace')[0]!.inject as () => WorkspacePickerInjected)()
+    expect(browser.hooks.directoryFlow.getSnapshot()).toBe(false)
+    expect(picker.hooks.directoryFlow.getSnapshot()).toBe(false)
+    // A flow occupant flips exactly its own surface, and the source notifies.
+    const notified = vi.fn()
+    const unsubscribe = browser.hooks.directoryFlow.subscribe(notified)
+    const dispose = b.slots.register({ name: 'sidebar.workspaces.directoryFlow' } as never, () => null)
+    expect(browser.hooks.directoryFlow.getSnapshot()).toBe(true)
+    expect(picker.hooks.directoryFlow.getSnapshot()).toBe(false)
+    await Promise.resolve()
+    expect(notified).toHaveBeenCalled()
+    dispose()
+    expect(browser.hooks.directoryFlow.getSnapshot()).toBe(false)
+    unsubscribe()
  })

  it('unregisters every entry on teardown', async () => {
--- a/packages/client/ui-workspace/tests/workspace-browser.spec.tsx
+++ b/packages/client/ui-workspace/tests/workspace-browser.spec.tsx
@@ -59,7 +59,8 @@ function mount(overrides: Partial<WorkspaceBrowserProps> = {}) {
    deleteWorkspace: vi.fn(async () => {}),
    insertSessionBefore: vi.fn(async () => {}),
    createWorkspace: vi.fn(async () => workspace('created', [])),
-    pickDirectory: vi.fn(async () => null),
+    useDirectoryFlow: bindSnapshotSelector({ getSnapshot: () => true, subscribe: () => () => {} }),
+    renderSlot: ((_name: string, owner: { open: boolean }) => (owner.open ? <div data-testid="directory-flow" /> : null)) as never,
    ...overrides,
  }
  const view = render(<WorkspaceBrowser {...props} />)
--- a/packages/client/ui-workspace/tests/workspace-picker.spec.tsx
+++ b/packages/client/ui-workspace/tests/workspace-picker.spec.tsx
@@ -5,6 +5,8 @@ import type {
  SessionListState, WorkspaceId, WorkspaceListState, WorkspaceView,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { WorkspaceCreateError } from '@deepseek-ai/dsh-client-runtime/client'
+import type { DirectoryFlowOwnerProps } from '../src/client/contract/slots.ts'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { WorkspacePicker } from '../src/client/WorkspacePicker.tsx'

 afterEach(cleanup)
@@ -35,14 +37,49 @@ function anchor(): { current: HTMLElement } {
  return { current: element }
 }

+/**
+ * Probe occupant of the directory-flow hole: records the latest owner
+ * conversation so tests drive onPicked/onCancel/onError like a composed flow
+ * package would, and renders a marker element while the flow is open.
+ */
+function flowProbe() {
+  const probe: { owner: DirectoryFlowOwnerProps | undefined } = { owner: undefined }
+  const renderSlot = ((_name: string, owner: DirectoryFlowOwnerProps) => {
+    probe.owner = owner
+    return owner.open ? <div data-testid="directory-flow" data-busy={owner.busy} /> : null
+  }) as never
+  return { probe, renderSlot }
+}
+
+/** Manual occupancy source bound like the renderer would: flip() drives the hook like a real registration change. */
+function occupancySource(initial = true) {
+  let occupied = initial
+  const listeners = new Set<() => void>()
+  const useDirectoryFlow = bindSnapshotSelector({
+    getSnapshot: () => occupied,
+    subscribe: (listener: () => void) => {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+  })
+  return {
+    useDirectoryFlow,
+    flip: (next: boolean) => {
+      occupied = next
+      for (const listener of [...listeners]) listener()
+    },
+  }
+}
+
 function mount(
  items: readonly WorkspaceView[] = [workspace('alpha', 'Alpha')],
  createWorkspace = vi.fn(),
-  pickDirectory = vi.fn(async () => null as string | null),
+  occupancy = occupancySource(),
 ) {
  const onPick = vi.fn()
  const onClose = vi.fn()
  const anchorRef = anchor()
+  const { probe, renderSlot } = flowProbe()
  const renderPicker = (nextItems: readonly WorkspaceView[]) => (
    <WorkspacePicker
      open
@@ -52,14 +89,15 @@ function mount(
      onPick={onPick}
      onClose={onClose}
      createWorkspace={createWorkspace}
-      pickDirectory={pickDirectory}
+      useDirectoryFlow={occupancy.useDirectoryFlow}
+      renderSlot={renderSlot}
    />
  )
  const view = render(
    renderPicker(items),
  )
  return {
-    view, onPick, onClose, createWorkspace, pickDirectory,
+    view, onPick, onClose, createWorkspace, probe, occupancy,
    rerenderItems: (nextItems: readonly WorkspaceView[]) => { view.rerender(renderPicker(nextItems)) },
  }
 }
@@ -87,65 +125,75 @@ describe('WorkspacePicker', () => {
    await waitFor(() => { expect(b.onPick).toHaveBeenCalledWith(created.workspaceId) })
  })

-  it('opens a native directory picker, adopts its path, and selects the returned Workspace', async () => {
+  it('opens the composed directory flow, adopts its picked path, and selects the returned Workspace', async () => {
    const created = { ...workspace('adopted'), path: '/tmp/project', title: 'project' }
    const createWorkspace = vi.fn(async () => created)
-    const pickDirectory = vi.fn(async () => '/tmp/project')
-    const b = mount([], createWorkspace, pickDirectory)
+    const b = mount([], createWorkspace)
+    expect(screen.queryByTestId('directory-flow')).toBeNull()
    chooseItem('Open local folder…')
-    expect(pickDirectory).toHaveBeenCalledOnce()
-    await waitFor(() => { expect(createWorkspace).toHaveBeenCalledWith({ path: '/tmp/project' }) })
+    expect(b.onClose).toHaveBeenCalled()
+    expect(screen.getByTestId('directory-flow')).toBeTruthy()
+    await act(async () => { b.probe.owner!.onPicked('/tmp/project') })
    expect(createWorkspace).toHaveBeenCalledWith({ path: '/tmp/project' })
    await waitFor(() => { expect(b.onPick).toHaveBeenCalledWith(created.workspaceId) })
+    // Successful adoption withdraws the flow request.
+    expect(screen.queryByTestId('directory-flow')).toBeNull()
  })

-  it('treats native picker cancellation as a silent no-op', async () => {
-    const b = mount([], vi.fn(), vi.fn(async () => null))
+  it('treats flow cancellation as a silent no-op', () => {
+    const b = mount([])
    chooseItem('Open local folder…')
-    await waitFor(() => { expect(b.pickDirectory).toHaveBeenCalledOnce() })
+    act(() => { b.probe.owner!.onCancel() })
+    expect(screen.queryByTestId('directory-flow')).toBeNull()
    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)
+  it('shows a name conflict and retries by reopening the flow', async () => {
    const createWorkspace = vi.fn(async () => {
      throw new WorkspaceCreateError({
        code: 'workspace-name-conflict', message: 'project already exists', details: { name: 'project' },
      })
    })
-    const b = mount([], createWorkspace, pickDirectory)
+    const b = mount([], createWorkspace)
    chooseItem('Open local folder…')
+    await act(async () => { b.probe.owner!.onPicked('/one/project') })
    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.')
+    // The failed adoption withdrew the flow; Choose again reopens it.
+    expect(b.probe.owner!.open).toBe(false)
    fireEvent.click(screen.getByRole('button', { name: 'Choose again' }))
-    await waitFor(() => { expect(pickDirectory).toHaveBeenCalledTimes(2) })
+    expect(b.probe.owner!.open).toBe(true)
    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))
+  it('disables every menu action from flow open through adoption, and reports busy to the flow', async () => {
+    let resolve!: (workspace: WorkspaceView) => void
+    const pending = new Promise<WorkspaceView>((settle) => { resolve = settle })
+    const created = workspace('adopted')
+    const b = mount([workspace('alpha', 'Alpha')], vi.fn(() => pending))
    chooseItem('Open local folder…')
+    // The flow is open but nothing is picked yet: a chooser pending on the
+    // host display must already block concurrent workspace actions.
+    expect(screen.getByRole<HTMLButtonElement>('menuitem', { name: 'Alpha' }).disabled).toBe(true)
+    expect(screen.getByRole<HTMLButtonElement>('menuitem', { name: 'Create a new workspace' }).disabled).toBe(true)
+    act(() => { b.probe.owner!.onPicked('/tmp/project') })
+    expect(b.probe.owner!.busy).toBe(true)
    expect(screen.getByRole<HTMLButtonElement>('menuitem', { name: 'Open local folder…' }).disabled).toBe(true)
    expect(screen.getByRole<HTMLButtonElement>('menuitem', { name: 'Create a new workspace' }).disabled).toBe(true)
-    fireEvent.click(screen.getByRole('menuitem', { name: 'Open local folder…' }))
-    expect(b.pickDirectory).toHaveBeenCalledTimes(1)
-    await act(async () => { resolve(null); await pending })
+    await act(async () => { resolve(created); await pending })
+    expect(b.probe.owner!.busy).toBe(false)
  })

-  it('reports non-Error native picker failures', async () => {
-    const b = mount([], vi.fn(), vi.fn(async () => { throw 'picker unavailable' }))
+  it('shows the flow-reported failure in the folder-error surface', () => {
+    const b = mount([])
    chooseItem('Open local folder…')
-    await waitFor(() => {
-      expect(screen.getByRole('alert').textContent).toBe('picker unavailable')
-    })
+    act(() => { b.probe.owner!.onError('no chooser installed') })
+    expect(screen.getByRole('alert').textContent).toBe('no chooser installed')
+    expect(screen.queryByTestId('directory-flow')).toBeNull()
    expect(b.createWorkspace).not.toHaveBeenCalled()
  })

@@ -215,10 +263,12 @@ describe('WorkspacePicker', () => {
  })

  it('waits to show its menu until an optional anchor is available', () => {
+    const { renderSlot } = flowProbe()
    render(
      <WorkspacePicker
        open useSessions={hook(sessions)} useWorkspaces={hook(workspaceState([]))}
-        onPick={vi.fn()} onClose={vi.fn()} createWorkspace={vi.fn()} pickDirectory={vi.fn()}
+        onPick={vi.fn()} onClose={vi.fn()} createWorkspace={vi.fn()}
+        useDirectoryFlow={occupancySource().useDirectoryFlow} renderSlot={renderSlot}
      />,
    )
    expect(screen.queryByRole('menu')).toBeNull()
@@ -228,12 +278,54 @@ describe('WorkspacePicker', () => {
    const state: WorkspaceListState = {
      ...workspaceState([]), phase: 'pending', state: 'loading', baselinesReady: false,
    }
+    const { renderSlot } = flowProbe()
    render(
      <WorkspacePicker
        open anchorRef={anchor()} useSessions={hook(sessions)} useWorkspaces={hook(state)}
-        onPick={vi.fn()} onClose={vi.fn()} createWorkspace={vi.fn()} pickDirectory={vi.fn()}
+        onPick={vi.fn()} onClose={vi.fn()} createWorkspace={vi.fn()}
+        useDirectoryFlow={occupancySource().useDirectoryFlow} renderSlot={renderSlot}
      />,
    )
    expect(screen.getByRole('status').textContent).toBe('Loading workspaces…')
  })
+
+  it('hides the folder entry while the directory-flow hole is empty', () => {
+    mount([], vi.fn(), occupancySource(false))
+    expect(screen.getByRole('menuitem', { name: 'Create a new workspace' })).toBeTruthy()
+    expect(screen.queryByRole('menuitem', { name: 'Open local folder…' })).toBeNull()
+  })
+
+  it('shows the folder entry when a flow package activates after the first paint', () => {
+    const b = mount([], vi.fn(), occupancySource(false))
+    expect(screen.queryByRole('menuitem', { name: 'Open local folder…' })).toBeNull()
+    // Registration changes flow through the subscription, no re-render needed.
+    act(() => { b.occupancy.flip(true) })
+    expect(screen.getByRole('menuitem', { name: 'Open local folder…' })).toBeTruthy()
+  })
+
+  it('keeps Choose again inert while the flow occupant is gone, and snaps back a flow opened over an empty hole', async () => {
+    const b = mount([], vi.fn(async () => { throw new Error('adoption failed') }))
+    chooseItem('Open local folder…')
+    await act(async () => { b.probe.owner!.onPicked('/one/project') })
+    await waitFor(() => { expect(screen.getByRole('dialog', { name: 'Couldn’t open folder' })).toBeTruthy() })
+    // The occupant unloads while the error dialog is up: retrying would open
+    // a flow nobody can serve or cancel, so the button goes inert.
+    act(() => { b.occupancy.flip(false) })
+    expect(screen.getByRole<HTMLButtonElement>('button', { name: 'Choose again' }).disabled).toBe(true)
+    // Cancel stays the way out, and the menu actions are usable again.
+    fireEvent.click(screen.getByRole('button', { name: 'Cancel' }))
+    expect(screen.getByRole<HTMLButtonElement>('menuitem', { name: 'Create a new workspace' }).disabled).toBe(false)
+  })
+
+  it('withdraws an open flow when its occupant unloads, re-enabling the menu actions', () => {
+    const b = mount([])
+    chooseItem('Open local folder…')
+    expect(screen.getByTestId('directory-flow')).toBeTruthy()
+    // The flow plugin unloads mid-interaction (HMR): nobody is left to
+    // cancel, so the owner withdraws and the actions come back.
+    act(() => { b.occupancy.flip(false) })
+    expect(b.probe.owner!.open).toBe(false)
+    expect(screen.getByRole<HTMLButtonElement>('menuitem', { name: 'Create a new workspace' }).disabled).toBe(false)
+    expect(screen.queryByRole('menuitem', { name: 'Open local folder…' })).toBeNull()
+  })
 })
--- a/packages/client/ui-workspace/tsconfig.json
+++ b/packages/client/ui-workspace/tsconfig.json
@@ -8,6 +8,9 @@
    "src"
  ],
  "references": [
+    {
+      "path": "../locale"
+    },
    {
      "path": "../../../vendor/cordis"
    },