@jetcrab/pi-desk 1.1.8 → 1.1.10-dev

package/docs/plugins.md

@@ -67,6 +67,18 @@ plugin.push('changed', {})
 
 Node `plugin.setState()` 则整体替换自身全局状态；Browser 通过 `host.globalState.getSnapshot()/subscribe()` 只读。两者不是同一槽位，均不得读写其他插件状态。宿主地区设置由 `host.settings.getSnapshot()/subscribe()` 只读，不另存权威副本。
 
+### 会话预览目录
+
+Session 插件可为左侧项目文件增加目录，不改变 Pi 会话 CWD：
+
+```ts
+plugin.addPreviewDirectory(directory, { default: true })
+```
+
+`directory` 为服务端绝对目录；省略第二个参数只登记，`default: true` 同时设为默认预览目录，后登记的默认生效。原 CWD 始终可选；目录规范化后去重，最多登记 32 个。重复快照不会覆盖用户的手动选择。登记只在当前会话运行态内，插件在 `session_start`、`session_tree` 从自身数据恢复后重新登记；不要在普通查询时重复请求默认选择。
+
+调用不等待回执；非法路径或超限由宿主拒绝并记日志，实际目录内容按需读取。旧宿主或独立 Pi 不处理该登记；兼容旧 SDK 时使用 `plugin.addPreviewDirectory?.(...)`。已有 `files.preview/reveal/readImage` 的相对路径仍以会话 CWD 为基准。
+
 ## Browser Entry 与懒界面
 
 Entry 默认导出普通同步函数即可；在函数返回前完成全部 `registerContribution(kind, name, definition)`。kind 支持 `application`、`composer-panel`、`settings-page`、`session-sidebar-tab`、`message-view`。Entry 只放元数据、loader、轻量页面状态和事件订阅；返回 disposer 清理自有订阅与资源。
@@ -110,7 +122,9 @@ Method 调用没有 Browser 视图级取消参数；Global handler 的 `context.
 Push 可丢失、不持久化、不 ACK、不重放，也不创建聊天消息。Entry ready、连接恢复 ready、视图 mount 时按需要查询 Method 建立权威基线；不要用页面轮询替代已有的宿主状态同步。
 
 - 当前页面轻提示：`plugin.notify({ level: 'success', title: '保存成功' })` 或 `host.notify()`，只在当前页面短暂展示，离线可错过。
-- 服务端全局通知：Node `plugin.notifications.publish({ level: 'success', title: '处理完成', event: { name: 'open-result', data: {} } })`；用返回 ID 调用 `update/delete`。Browser Entry 通过 `plugin.notifications.onEvent('open-result', handler)` 处理点击，成功后宿主删除通知。Node 未重启时重连可恢复；Node 重启或插件释放后清空，不持久化。
+- 服务端全局通知：Node `plugin.notifications.publish({ key: 'result:run-1', level: 'success', title: '处理完成', event: { name: 'open-result', data: { runId: 'run-1' } } })`；用返回 ID 调用 `update/delete`。Browser Entry 通过 `plugin.notifications.onEvent('open-result', handler)` 处理点击，成功后宿主删除通知。Node 未重启时重连可恢复；Node 重启或插件释放后清空，不持久化。
+
+`publish()` 的 `key` 可选，去除首尾空白后为 1～256 字符，由业务标识事件，例如 `post:${postId}` 或 `build:${runId}`。同一插件、同一 `key` 的现存通知只保留一条：内容相同不广播；内容变化整体更新文字、级别和点击 Event，返回原 ID，保留创建时间与位置。再次发布时省略 `description/event` 会清除旧值；`update()` 仍只修改文字和级别。不传 `key` 每次新增，不按文字自动合并。通知删除或淘汰后同 `key` 可重新创建，不保存已关闭记录；`key` 只存在于服务端通知内存，不随通知传给浏览器。带 `key` 的发布需使用支持通知去重的宿主；旧宿主会拒绝未知字段，不自动降级为新增通知。
 
 ## 消息展示
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetcrab/pi-desk",
-  "version": "1.1.8",
+  "version": "1.1.10-dev",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -69,13 +69,13 @@
     "viewerjs": "^1.11.8",
     "ws": "^8.21.3",
     "zod": "^4.4.3",
-    "@jetcrab/pi-desk-sdk": "^1.1.0"
+    "@jetcrab/pi-desk-sdk": "^1.1.2-dev"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "1.0.1",
-    "@earendil-works/pi-ai": "1.0.1",
-    "@earendil-works/pi-coding-agent": "1.0.1",
-    "@earendil-works/pi-tui": "1.0.1",
+    "@earendil-works/pi-agent-core": "1.2.0",
+    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "@tailwindcss/postcss": "^4",
     "@types/node": "^20",
     "@types/react": "^19",
@@ -94,7 +94,7 @@
     "yaml": "^2.9.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=1.0.1"
+    "@earendil-works/pi-coding-agent": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/src/client/l2_biz/auth/l2-login-biz.ts

@@ -11,7 +11,10 @@ export async function loginL2Auth(clientId: string, input: L2AuthLoginRequest):
   const parsed = L2AuthLoginRequestSchema.safeParse(input)
   if (!parsed.success) {
     throw new Error(
-      l4LocalizedErrorMessage({ msg: '登录参数无效', i18n: { key: 'auth:invalidInput' } })
+      l4LocalizedErrorMessage({
+        msg: '登录失败，请检查登录信息后重试。',
+        i18n: { key: 'auth:invalidInput' }
+      })
     )
   }
   const response = await fetch('/api/auth/login', {

package/src/client/l2_biz/settings/hooks/l2-use-auth-settings.ts

@@ -5,7 +5,12 @@ import { useTranslation } from 'react-i18next'
 import type { L2AuthSettings } from '@common/l2_biz/auth/l2-auth-contract'
 import { useL4AppSocket } from '@client/l4_foundation/realtime/app-socket/l4-app-socket'
 import { useL4ConfirmDialog } from '@client/l4_foundation/ui/l4-confirm-dialog'
-import { getL2AuthSettings, logoutL2Auth, replaceL2AuthSettings } from '../l2-auth-settings-biz'
+import {
+  generateL2AuthPassword,
+  getL2AuthSettings,
+  logoutL2Auth,
+  replaceL2AuthSettings
+} from '../l2-auth-settings-biz'
 
 interface AuthSettingsState {
   settings: L2AuthSettings | null
@@ -17,6 +22,7 @@ interface AuthSettingsState {
   setPassword: (value: string) => void
   retry: () => void
   save: () => Promise<void>
+  generatePassword: () => void
   disable: () => Promise<void>
   logout: () => Promise<void>
   dialog: React.JSX.Element | null
@@ -51,6 +57,16 @@ export function useL2AuthSettings(): AuthSettingsState {
     return () => controller.abort()
   }, [clientId, attempt, t])
 
+  const generatePassword = (): void => {
+    if (pending.current) return
+    try {
+      setPassword(generateL2AuthPassword())
+      setError(null)
+    } catch {
+      setError(t('generatePasswordFailed'))
+    }
+  }
+
   const save = async (): Promise<void> => {
     if (pending.current || !settings) return
     pending.current = true
@@ -111,6 +127,7 @@ export function useL2AuthSettings(): AuthSettingsState {
     password,
     setPassword,
     save,
+    generatePassword,
     disable,
     logout,
     dialog,

package/src/client/l2_biz/settings/l2-auth-settings-biz.ts

@@ -47,6 +47,23 @@ export async function logoutL2Auth(clientId: string): Promise<void> {
   window.location.replace('/login')
 }
 
+export function generateL2AuthPassword(): string {
+  // 64 个字符可直接映射随机字节，不产生取模偏差。
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@'
+  while (true) {
+    const bytes = crypto.getRandomValues(new Uint8Array(16))
+    const password = Array.from(bytes, (value) => alphabet[value % 64]).join('')
+    if (
+      /[A-Z]/.test(password) &&
+      /[a-z]/.test(password) &&
+      /[0-9]/.test(password) &&
+      /[!@]/.test(password)
+    ) {
+      return password
+    }
+  }
+}
+
 export async function replaceL2AuthSettings(
   clientId: string,
   input: L2AuthSettingsReplaceRequest
@@ -55,7 +72,7 @@ export async function replaceL2AuthSettings(
   if (!parsed.success) {
     throw new Error(
       l4LocalizedErrorMessage({
-        msg: '请填写至少 8 位密码',
+        msg: '密码不符合要求，请按输入框下方的规则调整。',
         i18n: { key: 'auth:settingsInvalid' }
       })
     )

package/src/client/l2_biz/settings/l2-auth-settings.tsx

@@ -2,6 +2,7 @@
 
 import {
   ChevronRightIcon,
+  DicesIcon,
   LoaderCircleIcon,
   LogOutIcon,
   ShieldCheckIcon,
@@ -76,15 +77,28 @@ export function L2AuthSettings(): React.JSX.Element {
             </div>
             <div className="min-w-0 max-w-[40rem] space-y-4">
               <div className="space-y-1">
-                <label className="block text-sm font-medium" htmlFor="auth-password">
-                  {t(enabled ? 'newPassword' : 'password')}
-                </label>
+                <div className="flex flex-wrap items-center justify-between gap-2">
+                  <label className="block text-sm font-medium" htmlFor="auth-password">
+                    {t(enabled ? 'newPassword' : 'password')}
+                  </label>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="sm"
+                    disabled={busy}
+                    title={t('generatePasswordHint')}
+                    onClick={state.generatePassword}
+                  >
+                    <DicesIcon aria-hidden="true" />
+                    {t('generatePassword')}
+                  </Button>
+                </div>
                 <L4PasswordInput
                   id="auth-password"
                   name="password"
                   className="[&::-ms-reveal]:hidden"
                   autoComplete="new-password"
-                  minLength={8}
+                  minLength={12}
                   maxLength={256}
                   required
                   disabled={busy}
@@ -92,7 +106,7 @@ export function L2AuthSettings(): React.JSX.Element {
                   aria-describedby={`auth-password-hint${state.error ? ' auth-settings-error' : ''}`}
                   onChange={(event) => state.setPassword(event.target.value)}
                 />
-                <p id="auth-password-hint" className="text-xs text-muted-foreground">
+                <p id="auth-password-hint" className="text-sm text-muted-foreground">
                   {t('passwordHint')}
                 </p>
               </div>

package/src/client/l2_biz/workbench/file-workspace/l2-file-workspace-runtime.ts

@@ -1,4 +1,9 @@
 import type { L2WorkSessionListItem } from '@common/l2_biz/work-session/l2-work-session-contract'
+import type { L2ChatSource } from '@common/l2_biz/chat/l2-chat-contract'
+import {
+  projectPreviewDirectoryKey,
+  type L4ProjectPreviewState
+} from '@common/l4_foundation/file/l4-project-preview-contract'
 import type { L4CodePreviewState } from '@client/l4_foundation/ui/code/l4-code-preview'
 import { readL3ImagePreviewMode } from '@client/l3_modules/preferences/l3-work-session-file-preferences'
 import {
@@ -26,12 +31,21 @@ export interface L2SessionFileWorkspace extends L3ProjectFileState {
   readonly activePane: 'chat' | 'files'
 }
 type SourceRef = Pick<L2WorkSessionListItem, 'workId' | 'cwd' | 'sessionId' | 'branchId'>
+interface FileRoot {
+  files: L3ProjectFileRuntime
+  unsubscribe: () => void
+}
+interface SessionDirectories {
+  directories: string[]
+  defaultDirectory: string | null
+  selectedDirectory: string
+}
 interface SessionLayout {
   files: L3ProjectFileRuntime
+  roots: Map<string, FileRoot>
   windowOpen: boolean
   chatWidthPercent: number
   activePane: 'chat' | 'files'
-  unsubscribe: () => void
 }
 
 export class L2FileWorkspaceRuntime {
@@ -39,6 +53,7 @@ export class L2FileWorkspaceRuntime {
   private readonly listeners = new Set<() => void>()
   private readonly workspaces = new Map<string, SessionLayout>()
   private readonly sources = new Map<string, SourceRef>()
+  private readonly previewDirectories = new Map<string, SessionDirectories>()
   private expandedWorkId: string | null = null
   private revision = 0
   constructor(
@@ -69,6 +84,69 @@ export class L2FileWorkspaceRuntime {
   getExpandedWorkId(): string | null {
     return this.expandedWorkId
   }
+  getDirectories(workId: string): readonly string[] {
+    return this.previewDirectories.get(workId)?.directories ?? []
+  }
+  getDirectory(workId: string): string {
+    const selection = this.previewDirectories.get(workId)
+    if (!selection) throw new Error(l2WorkbenchText('sourceChanged'))
+    return selection.selectedDirectory
+  }
+  applyPreviewDirectories(source: L2ChatSource, state: L4ProjectPreviewState): void {
+    const current = this.sources.get(source.workId)
+    if (!current || current.sessionId !== source.sessionId || current.branchId !== source.branchId)
+      return
+    const previous = this.previewDirectories.get(source.workId)!
+    const unique = new Map([[projectPreviewDirectoryKey(current.cwd), current.cwd]])
+    for (const directory of state.directories) {
+      const key = projectPreviewDirectoryKey(directory)
+      if (!unique.has(key)) unique.set(key, directory)
+    }
+    const defaultDirectory = state.defaultDirectory
+      ? (unique.get(projectPreviewDirectoryKey(state.defaultDirectory)) ?? null)
+      : null
+    const previousDefaultKey = previous.defaultDirectory
+      ? projectPreviewDirectoryKey(previous.defaultDirectory)
+      : null
+    const defaultKey = defaultDirectory ? projectPreviewDirectoryKey(defaultDirectory) : null
+    const selectedDirectory =
+      previousDefaultKey !== defaultKey
+        ? (defaultDirectory ?? current.cwd)
+        : (unique.get(projectPreviewDirectoryKey(previous.selectedDirectory)) ?? current.cwd)
+    const directories = [...unique.values()]
+    if (
+      previous.defaultDirectory === defaultDirectory &&
+      previous.selectedDirectory === selectedDirectory &&
+      previous.directories.length === directories.length &&
+      previous.directories.every((directory, index) => directory === directories[index])
+    )
+      return
+    this.previewDirectories.set(source.workId, { directories, defaultDirectory, selectedDirectory })
+    const layout = this.workspaces.get(source.workId)
+    if (layout) {
+      for (const [key, root] of layout.roots) {
+        if (unique.has(key)) continue
+        root.unsubscribe()
+        root.files.dispose()
+        layout.roots.delete(key)
+      }
+      this.switchFiles(source.workId, layout)
+    }
+    this.publish()
+  }
+  selectDirectory(workId: string, directory: string): void {
+    const selection = this.previewDirectories.get(workId)
+    if (!selection) throw new Error(l2WorkbenchText('sourceChanged'))
+    const registered = selection.directories.find(
+      (candidate) => projectPreviewDirectoryKey(candidate) === projectPreviewDirectoryKey(directory)
+    )
+    if (!registered) throw new Error(l2WorkbenchText('sourceChanged'))
+    if (selection.selectedDirectory === registered) return
+    selection.selectedDirectory = registered
+    const layout = this.workspaces.get(workId)
+    if (layout) this.switchFiles(workId, layout)
+    this.publish()
+  }
   reconcileWorkSessions(sessions: readonly L2WorkSessionListItem[]): void {
     this.standaloneImages.reconcileWorkSessions(sessions)
     const next = new Map(
@@ -88,15 +166,24 @@ export class L2FileWorkspaceRuntime {
         continue
       const layout = this.workspaces.get(id)
       if (layout) {
-        layout.unsubscribe()
-        layout.files.dispose()
+        this.disposeLayout(layout)
         this.workspaces.delete(id)
-        changed = true
       }
+      this.previewDirectories.delete(id)
+      changed = true
       if (this.expandedWorkId === id) this.expandedWorkId = null
     }
     this.sources.clear()
-    for (const [id, source] of next) this.sources.set(id, source)
+    for (const [id, source] of next) {
+      this.sources.set(id, source)
+      if (!this.previewDirectories.has(id)) {
+        this.previewDirectories.set(id, {
+          directories: [source.cwd],
+          defaultDirectory: null,
+          selectedDirectory: source.cwd
+        })
+      }
+    }
     if (changed) this.publish()
   }
   ensureRoot(id: string): Promise<void> {
@@ -214,7 +301,9 @@ export class L2FileWorkspaceRuntime {
   }
   handleGitBranchChanged(cwd: string, root: string): void {
     for (const layout of this.workspaces.values()) {
-      if (layout.files.cwd === cwd) layout.files.handleGitBranchChanged(root)
+      for (const entry of layout.roots.values()) {
+        if (entry.files.cwd === cwd) entry.files.handleGitBranchChanged(root)
+      }
     }
   }
   saveEditorState(id: string, path: string, state: L4CodePreviewState | null): void {
@@ -228,12 +317,10 @@ export class L2FileWorkspaceRuntime {
   }
   dispose(): void {
     this.standaloneImages.dispose()
-    for (const layout of this.workspaces.values()) {
-      layout.unsubscribe()
-      layout.files.dispose()
-    }
+    for (const layout of this.workspaces.values()) this.disposeLayout(layout)
     this.workspaces.clear()
     this.sources.clear()
+    this.previewDirectories.clear()
     this.expandedWorkId = null
     this.listeners.clear()
   }
@@ -242,9 +329,21 @@ export class L2FileWorkspaceRuntime {
     if (!source) throw new Error(l2WorkbenchText('sourceChanged'))
     const existing = this.workspaces.get(id)
     if (existing) return existing
-    const context = { workId: id, cwd: source.cwd }
-    const files = new L3ProjectFileRuntime(
-      source.cwd,
+    const layout: SessionLayout = {
+      files: this.createFiles(id, this.getDirectory(id)),
+      roots: new Map(),
+      windowOpen: false,
+      chatWidthPercent: 50,
+      activePane: 'files'
+    }
+    this.attachRoot(id, layout, layout.files)
+    this.workspaces.set(id, layout)
+    return layout
+  }
+  private createFiles(id: string, cwd: string): L3ProjectFileRuntime {
+    const context = { workId: id, cwd }
+    return new L3ProjectFileRuntime(
+      cwd,
       {
         list: (path, signal) => this.biz.list({ ...context, path }, signal),
         search: (query, signal) => this.biz.search({ ...context, query }, signal),
@@ -266,22 +365,44 @@ export class L2FileWorkspaceRuntime {
         }
       }
     )
-    const layout: SessionLayout = {
-      files,
-      windowOpen: false,
-      chatWidthPercent: 50,
-      activePane: 'files',
-      unsubscribe: () => undefined
-    }
-    layout.unsubscribe = files.subscribe(() => {
+  }
+  private attachRoot(id: string, layout: SessionLayout, files: L3ProjectFileRuntime): void {
+    const unsubscribe = files.subscribe(() => {
+      if (layout.files !== files) return
       if (!files.state.activePath && !files.state.activeDiff && this.expandedWorkId !== id) {
         layout.windowOpen = false
         layout.activePane = 'chat'
       }
       this.publish()
     })
-    this.workspaces.set(id, layout)
-    return layout
+    layout.roots.set(projectPreviewDirectoryKey(files.cwd), { files, unsubscribe })
+  }
+  private switchFiles(id: string, layout: SessionLayout): void {
+    const directory = this.getDirectory(id)
+    const key = projectPreviewDirectoryKey(directory)
+    if (projectPreviewDirectoryKey(layout.files.cwd) === key) return
+    let root = layout.roots.get(key)
+    if (!root) {
+      const files = this.createFiles(id, directory)
+      this.attachRoot(id, layout, files)
+      root = layout.roots.get(key)!
+    }
+    layout.files = root.files
+    if (
+      !root.files.state.activePath &&
+      !root.files.state.activeDiff &&
+      this.expandedWorkId !== id
+    ) {
+      layout.windowOpen = false
+      layout.activePane = 'chat'
+    }
+  }
+  private disposeLayout(layout: SessionLayout): void {
+    for (const root of layout.roots.values()) {
+      root.unsubscribe()
+      root.files.dispose()
+    }
+    layout.roots.clear()
   }
   private publish(): void {
     this.revision += 1

package/src/client/l2_biz/workbench/file-workspace/l2-file-workspace-view.tsx

@@ -53,8 +53,11 @@ export function L2FileWorkspaceView({
 }: L2FileWorkspaceViewProps): React.JSX.Element | null {
   const { t } = useTranslation('workbench')
   useSyncExternalStore(runtime.subscribe, runtime.getRevision, runtime.getRevision)
-  const { workId, cwd, projectName } = workSession
+  const { workId, projectName } = workSession
+  const cwd = runtime.getDirectory(workId)
   const workspace = runtime.getWorkspace(workId)
+  const directoryName = cwd.replaceAll('\\', '/').split('/').filter(Boolean).at(-1) ?? cwd
+  const previewProjectName = cwd === workSession.cwd ? projectName : directoryName
   const [directoryOpen, setDirectoryOpen] = useState(true)
   const documentRef = useRef<L3ProjectDocumentHandle>(null)
   const expanded = presentation === 'expanded'
@@ -137,9 +140,9 @@ export function L2FileWorkspaceView({
           </p>
           <p
             className="truncate text-xs text-muted-foreground"
-            title={`${projectName} · ${diffPath ?? activePath ?? cwd}`}
+            title={`${cwd} · ${diffPath ?? activePath ?? ''}`}
           >
-            {projectName}
+            {previewProjectName}
             {(diffPath ?? activePath) ? ` · ${diffPath ?? activePath}` : ''}
           </p>
         </div>
@@ -178,7 +181,7 @@ export function L2FileWorkspaceView({
                   size="icon-sm"
                   aria-label={t('newTerminal')}
                   title={t('newTerminal')}
-                  onClick={() => onOpenTerminal(cwd)}
+                  onClick={() => onOpenTerminal(workSession.cwd)}
                 >
                   <TerminalIcon className="size-4" />
                 </Button>
@@ -197,7 +200,7 @@ export function L2FileWorkspaceView({
             </div>
             <L2ProjectFileBrowser
               workId={workId}
-              cwd={cwd}
+              cwd={workSession.cwd}
               projectName={projectName}
               runtime={runtime}
               gitRuntime={gitRuntime}
@@ -217,6 +220,7 @@ export function L2FileWorkspaceView({
             onClose={(path, scope) => runtime.closeTabs(workId, path, scope)}
           />
           <L3ProjectDocumentView
+            key={cwd}
             ref={documentRef}
             runtime={runtime.getFileRuntime(workId)}
             gitRuntime={gitRuntime}

package/src/client/l2_biz/workbench/file-workspace/l2-project-file-browser.tsx

@@ -1,10 +1,31 @@
 'use client'
 
+import { ChevronDownIcon, FolderIcon } from 'lucide-react'
+import { useSyncExternalStore } from 'react'
+import { useTranslation } from 'react-i18next'
+import { projectPreviewDirectoryKey } from '@common/l4_foundation/file/l4-project-preview-contract'
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem
+} from '@client/l4_foundation/ui/shadcn/dropdown-menu'
 import { L3ProjectFileBrowser } from '@client/l3_modules/project-files/l3-project-file-browser'
 import type { L2FileWorkspaceRuntime } from './l2-file-workspace-runtime'
 import type { L2GitWorkspaceRuntime } from '../git-workspace/l2-git-workspace-runtime'
 import type { L2GitBranchPickerTarget } from '../git-workspace/l2-git-workspace-model'
 
+function directoryName(directory: string): string {
+  return directory.replaceAll('\\', '/').split('/').filter(Boolean).at(-1) ?? directory
+}
+function compactDirectory(directory: string): string {
+  const parts = directory.replaceAll('\\', '/').split('/').filter(Boolean)
+  return parts.length <= 2 ? directory : `…/${parts.slice(-2).join('/')}`
+}
+
 interface Props {
   workId: string
   cwd: string
@@ -23,15 +44,83 @@ export function L2ProjectFileBrowser({
   onOpenGitBranches,
   onFileOpened
 }: Props): React.JSX.Element {
+  const { t } = useTranslation('projectFiles')
+  useSyncExternalStore(runtime.subscribe, runtime.getRevision, runtime.getRevision)
+  const directory = runtime.getDirectory(workId)
+  const directories = runtime.getDirectories(workId)
+  const original = projectPreviewDirectoryKey(cwd) === projectPreviewDirectoryKey(directory)
+  const name = original ? projectName : directoryName(directory)
   return (
     <L3ProjectFileBrowser
-      cwd={cwd}
-      projectName={projectName}
+      cwd={directory}
+      projectName={name}
+      gitReadOnly={!original}
+      rootTitle={
+        directories.length > 1 ? (
+          <DropdownMenu>
+            <DropdownMenuTrigger
+              data-testid="project-preview-directory-trigger"
+              aria-label={t('selectPreviewDirectory')}
+              title={directory}
+              className="flex min-h-7 min-w-0 flex-1 items-center gap-1 rounded-md px-1 text-left hover:bg-accent focus-visible:outline-2 focus-visible:outline-ring"
+            >
+              <span className="max-w-[45%] truncate text-xs font-semibold">{name}</span>
+              <span className="text-xs text-muted-foreground">·</span>
+              <span className="min-w-0 flex-1 truncate font-mono text-xs text-muted-foreground">
+                {compactDirectory(directory)}
+              </span>
+              <ChevronDownIcon className="size-3.5 shrink-0 text-muted-foreground" />
+            </DropdownMenuTrigger>
+            <DropdownMenuContent
+              finalFocus
+              className="w-[23rem] min-w-0 max-w-[calc(100vw-1.5rem)]"
+              aria-label={t('previewDirectories')}
+            >
+              <DropdownMenuGroup>
+                <DropdownMenuLabel>{t('previewDirectories')}</DropdownMenuLabel>
+                <DropdownMenuRadioGroup
+                  value={directory}
+                  onValueChange={(value) => runtime.selectDirectory(workId, value)}
+                >
+                  {directories.map((root) => (
+                    <DropdownMenuRadioItem
+                      key={projectPreviewDirectoryKey(root)}
+                      value={root}
+                      data-testid="project-preview-directory-option"
+                      data-directory={root}
+                      className="items-start py-2 data-checked:bg-muted"
+                    >
+                      <FolderIcon className="mt-0.5 size-4 text-muted-foreground" />
+                      <span className="min-w-0 flex-1">
+                        <span className="flex items-start gap-2">
+                          <span className="min-w-0 flex-1 break-all">
+                            {projectPreviewDirectoryKey(root) === projectPreviewDirectoryKey(cwd)
+                              ? projectName
+                              : directoryName(root)}
+                          </span>
+                          {projectPreviewDirectoryKey(root) === projectPreviewDirectoryKey(cwd) ? (
+                            <span className="shrink-0 text-xs text-muted-foreground">
+                              {t('sessionDirectory')}
+                            </span>
+                          ) : null}
+                        </span>
+                        <span className="mt-0.5 block break-all font-mono text-xs leading-5 text-muted-foreground">
+                          {root}
+                        </span>
+                      </span>
+                    </DropdownMenuRadioItem>
+                  ))}
+                </DropdownMenuRadioGroup>
+              </DropdownMenuGroup>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        ) : undefined
+      }
       runtime={runtime.getFileRuntime(workId)}
       gitRuntime={gitRuntime}
-      onOpenGitBranches={(repositoryRoot) =>
-        onOpenGitBranches({ workId, cwd, projectName, repositoryRoot })
-      }
+      onOpenGitBranches={(repositoryRoot) => {
+        if (original) onOpenGitBranches({ workId, cwd, projectName, repositoryRoot })
+      }}
       onFileOpened={() => {
         runtime.showWindow(workId)
         onFileOpened?.()

package/src/client/l2_biz/workbench/file-workspace/l2-project-preview-biz.ts

@@ -0,0 +1,48 @@
+import type { L2WorkSessionListItem } from '@common/l2_biz/work-session/l2-work-session-contract'
+import {
+  L4_PROJECT_PREVIEW_PLUGIN_KEY,
+  readL4ProjectPreviewState
+} from '@common/l4_foundation/file/l4-project-preview-contract'
+import type { L2WorkbenchChatRuntime } from '../l2-workbench-chat'
+import type { L2GitWorkspaceRuntime } from '../git-workspace/l2-git-workspace-runtime'
+import type { L2FileWorkspaceRuntime } from './l2-file-workspace-runtime'
+
+export function syncL2ProjectPreviewGitReferences(
+  files: L2FileWorkspaceRuntime,
+  git: L2GitWorkspaceRuntime,
+  sessions: readonly L2WorkSessionListItem[],
+  focusedWorkId: string | null
+): void {
+  git.reconcileWorkSessions(
+    sessions,
+    focusedWorkId,
+    sessions.flatMap(({ workId }) => files.getDirectories(workId).map((cwd) => ({ workId, cwd })))
+  )
+}
+
+export function subscribeL2ProjectPreviewDirectories(
+  chat: L2WorkbenchChatRuntime,
+  files: L2FileWorkspaceRuntime,
+  git: L2GitWorkspaceRuntime,
+  getSessions: () => readonly L2WorkSessionListItem[],
+  getFocusedWorkId: () => string | null
+): () => void {
+  const unsubscribeChat = chat.subscribeSourceEvents(({ source, event }, state) => {
+    if (event.type !== 'session_sync' && event.type !== 'runtime_update') return
+    files.applyPreviewDirectories(
+      source,
+      readL4ProjectPreviewState(state.runtime.plugins[L4_PROJECT_PREVIEW_PLUGIN_KEY])
+    )
+    syncL2ProjectPreviewGitReferences(files, git, getSessions(), getFocusedWorkId())
+  })
+  for (const session of getSessions()) {
+    const state = chat.getSourceState(session)
+    if (state.syncStatus === 'loading') continue
+    files.applyPreviewDirectories(
+      session,
+      readL4ProjectPreviewState(state.runtime.plugins[L4_PROJECT_PREVIEW_PLUGIN_KEY])
+    )
+  }
+  syncL2ProjectPreviewGitReferences(files, git, getSessions(), getFocusedWorkId())
+  return unsubscribeChat
+}