feat(explorer): add optional host filesystem navigation

src/main/ipc/filesystem/filesystem-host-browse-handlers.test.ts

@@ -0,0 +1,126 @@
+import { mkdir, mkdtemp, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { HostDirectoryListing } from '../../../shared/filesystem-entry-types'
+import type { Store } from '../../persistence'
+import { isPathAllowed, resolveAuthorizedPath } from './filesystem-auth'
+import {
+  registerFilesystemHostBrowseHandlers,
+  resolveHostBrowseEntry
+} from './filesystem-host-browse-handlers'
+
+const { handlers } = vi.hoisted(() => ({
+  handlers: new Map<string, (event: unknown, args: unknown) => unknown>()
+}))
+
+vi.mock('electron', () => ({
+  ipcMain: {
+    handle: (channel: string, handler: (event: unknown, args: unknown) => unknown) =>
+      handlers.set(channel, handler)
+  }
+}))
+
+// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: allowed-root lookups read only these four accessors.
+const store = {
+  getRepos: () => [],
+  getProjectGroups: () => [],
+  getFolderWorkspaces: () => [],
+  getSettings: () => ({})
+} as unknown as Store
+
+describe('host browse handlers', () => {
+  let root: string
+
+  beforeEach(async () => {
+    root = await realpath(await mkdtemp(join(tmpdir(), 'orca-host-browse-')))
+    await mkdir(join(root, 'outside', 'nested'), { recursive: true })
+    await writeFile(join(root, 'outside', 'notes.txt'), 'hi')
+  })
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true })
+  })
+
+  it('lists a directory outside allowed roots without granting access to it', async () => {
+    registerFilesystemHostBrowseHandlers()
+    const outside = join(root, 'outside')
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: fs:browseHostDir resolves to a HostDirectoryListing.
+    const listing = (await handlers.get('fs:browseHostDir')?.(null, {
+      dirPath: outside
+    })) as HostDirectoryListing
+
+    expect(listing.resolvedPath).toBe(outside)
+    expect(listing.entries.map((entry) => entry.name).sort()).toEqual(['nested', 'notes.txt'])
+    await expect(isPathAllowed(outside, store)).resolves.toBe(false)
+    await expect(isPathAllowed(join(outside, 'nested', 'x'), store)).resolves.toBe(false)
+    await expect(resolveAuthorizedPath(join(outside, 'nested'), store)).rejects.toThrow(
+      /Access denied/
+    )
+  })
+
+  it('classifies a regular file outside the workspace without granting it', async () => {
+    const file = join(root, 'outside', 'notes.txt')
+    const resolution = await resolveHostBrowseEntry(file)
+
+    expect(resolution).toEqual({ kind: 'file', realPath: file, workspaceRelativePath: null })
+    await expect(isPathAllowed(file, store)).resolves.toBe(false)
+    await expect(isPathAllowed(join(root, 'outside'), store)).resolves.toBe(false)
+    await expect(isPathAllowed(join(root, 'outside', 'nested'), store)).resolves.toBe(false)
+  })
+
+  it('classifies a symlink to a directory as a directory and grants nothing', async () => {
+    const target = join(root, 'outside', 'nested')
+    const link = join(root, 'dir-link')
+    await symlink(target, link, 'dir')
+
+    const resolution = await resolveHostBrowseEntry(link)
+
+    expect(resolution).toEqual({ kind: 'directory', realPath: target, workspaceRelativePath: null })
+    await expect(isPathAllowed(join(target, 'anything'), store)).resolves.toBe(false)
+    await expect(isPathAllowed(join(link, 'anything'), store)).resolves.toBe(false)
+  })
+
+  it('reports the canonical path of a symlinked file for worktree ownership checks', async () => {
+    const target = join(root, 'outside', 'notes.txt')
+    const link = join(root, 'file-link')
+    await symlink(target, link, 'file')
+
+    await expect(resolveHostBrowseEntry(link)).resolves.toEqual({
+      kind: 'file',
+      realPath: target,
+      workspaceRelativePath: null
+    })
+  })
+
+  it('rejects relative and null-byte paths, locally and over SSH', async () => {
+    await expect(resolveHostBrowseEntry('outside/notes.txt'), 'relative').rejects.toThrow(
+      /absolute/
+    )
+    await expect(resolveHostBrowseEntry(`${root}\0x`), 'local NUL').rejects.toThrow(/null bytes/)
+    await expect(
+      resolveHostBrowseEntry('/home/allen\0x', 'ssh-1'),
+      'null-byte SSH path'
+    ).rejects.toThrow(/null bytes/)
+  })
+
+  it('resolves workspace ownership against the canonical workspace root', async () => {
+    const realWorkspace = join(root, 'real-workspace')
+    await mkdir(join(realWorkspace, 'src'), { recursive: true })
+    await writeFile(join(realWorkspace, 'src', 'a.ts'), 'x')
+    const workspaceAlias = join(root, 'workspace-alias')
+    await symlink(realWorkspace, workspaceAlias, 'dir')
+    const outsideLink = join(root, 'outside', 'a-link.ts')
+    await symlink(join(realWorkspace, 'src', 'a.ts'), outsideLink, 'file')
+
+    const resolution = await resolveHostBrowseEntry(outsideLink, undefined, workspaceAlias)
+
+    expect(resolution).toEqual({
+      kind: 'file',
+      realPath: join(realWorkspace, 'src', 'a.ts'),
+      workspaceRelativePath: 'src/a.ts'
+    })
+    // Why: workspace files are reached through allowed roots; no external grant is added.
+    await expect(isPathAllowed(outsideLink, store)).resolves.toBe(false)
+  })
+})

src/main/ipc/filesystem/filesystem-host-browse-handlers.ts

@@ -0,0 +1,69 @@
+import { ipcMain } from 'electron'
+import { realpath, stat } from 'node:fs/promises'
+import { isAbsolute } from 'node:path'
+import { relativePathInsideRoot } from '../../../shared/cross-platform-path'
+import type {
+  HostBrowseEntryResolution,
+  HostDirectoryListing
+} from '../../../shared/filesystem-entry-types'
+import { browseServerDirectory } from '../../runtime/runtime-server-environment-commands'
+
+async function canonicalRelativePath(
+  realPath: string,
+  workspaceRoot: string | undefined,
+  canonicalize: (path: string) => Promise<string>
+): Promise<string | null> {
+  if (!workspaceRoot) {
+    return null
+  }
+  try {
+    return relativePathInsideRoot(await canonicalize(workspaceRoot), realPath)
+  } catch {
+    return null
+  }
+}
+
+export async function resolveHostBrowseEntry(
+  targetPath: string,
+  connectionId?: string,
+  workspaceRoot?: string
+): Promise<HostBrowseEntryResolution> {
+  if (targetPath.includes('\0')) {
+    throw new Error('Path cannot contain null bytes')
+  }
+  if (connectionId) {
+    // ponytail: no SSH filesystem provider exists since the relay removal (#31922); add an SSH realpath/stat RPC to classify remote entries.
+    throw new Error('Remote connection dropped. Click Reconnect on the SSH target before retrying.')
+  }
+  if (!isAbsolute(targetPath)) {
+    throw new Error('Host browse path must be absolute')
+  }
+  const realPath = await realpath(targetPath)
+  const target = await stat(realPath)
+  const workspaceRelativePath = await canonicalRelativePath(realPath, workspaceRoot, realpath)
+  if (target.isDirectory()) {
+    return { kind: 'directory', realPath, workspaceRelativePath }
+  }
+  if (!target.isFile()) {
+    return { kind: 'unsupported', realPath, workspaceRelativePath }
+  }
+  return { kind: 'file', realPath, workspaceRelativePath }
+}
+
+export function registerFilesystemHostBrowseHandlers(): void {
+  // Why: names-only listing never touches the external-path allowlist, so browsing
+  // outside the workspace grants nothing to later read/write/delete handlers.
+  ipcMain.handle(
+    'fs:browseHostDir',
+    (_event, args: { dirPath: string }): Promise<HostDirectoryListing> =>
+      browseServerDirectory(args.dirPath)
+  )
+  ipcMain.handle(
+    'fs:resolveHostBrowseEntry',
+    (
+      _event,
+      args: { targetPath: string; connectionId?: string; workspaceRoot?: string }
+    ): Promise<HostBrowseEntryResolution> =>
+      resolveHostBrowseEntry(args.targetPath, args.connectionId, args.workspaceRoot)
+  )
+}

src/main/ipc/filesystem/filesystem.ts

@@ -19,6 +19,7 @@ import { registerFilesystemGitRemoteHandlers } from './filesystem-git-remote-han
 import { registerFilesystemGitDiffHandlers } from './filesystem-git-diff-handlers'
 import { registerFilesystemGitIndexHandlers } from './filesystem-git-index-handlers'
 import { registerFilesystemGitUrlHandlers } from './filesystem-git-url-handlers'
+import { registerFilesystemHostBrowseHandlers } from './filesystem-host-browse-handlers'
 
 export function registerFilesystemHandlers(
   store: Store,
@@ -44,5 +45,6 @@ export function registerFilesystemHandlers(
   registerFilesystemGitDiffHandlers(context)
   registerFilesystemGitIndexHandlers(context)
   registerFilesystemGitUrlHandlers(context)
+  registerFilesystemHostBrowseHandlers()
   registerLocalLogTailHandlers(store)
 }

src/main/runtime/runtime-server-environment-commands.ts

@@ -2,7 +2,7 @@ import { readdir, stat } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import type { Dirent } from 'node:fs'
 import { isAbsolute, join, resolve } from 'node:path'
-import type { DirEntry, FilesystemPathFlavor } from '../../shared/filesystem-entry-types'
+import type { HostDirectoryListing } from '../../shared/filesystem-entry-types'
 import { sortDirEntries } from '../../shared/file-name-sort'
 import { probeGitAvailability } from '../git/git-availability'
 import { gitExecFileAsync } from '../git/runner'
@@ -40,36 +40,36 @@ async function isBrowseEntryDirectory(dirPath: string, entry: Dirent): Promise<b
   }
 }
 
+export async function browseServerDirectory(pathValue: string): Promise<HostDirectoryListing> {
+  if (isServerDriveListRequest(pathValue)) {
+    return listWindowsDrives()
+  }
+  const dirPath = resolveServerBrowsePath(pathValue)
+  const dirStat = await stat(dirPath)
+  if (!dirStat.isDirectory()) {
+    throw new Error(`${dirPath} is not a directory`)
+  }
+  const entries = await readdir(dirPath, { withFileTypes: true })
+  const mapped = await Promise.all(
+    entries
+      .filter((entry) => entry.name !== '.' && entry.name !== '..')
+      .map(async (entry) => ({
+        name: entry.name,
+        isDirectory: await isBrowseEntryDirectory(dirPath, entry),
+        isSymlink: entry.isSymbolicLink()
+      }))
+  )
+  sortDirEntries(mapped)
+  return {
+    resolvedPath: dirPath,
+    entries: mapped,
+    pathFlavor: process.platform === 'win32' ? 'win32' : 'posix'
+  }
+}
+
 export class RuntimeServerEnvironmentCommands {
-  async browseDirectory(pathValue: string): Promise<{
-    resolvedPath: string
-    entries: DirEntry[]
-    pathFlavor: FilesystemPathFlavor
-  }> {
-    if (isServerDriveListRequest(pathValue)) {
-      return listWindowsDrives()
-    }
-    const dirPath = resolveServerBrowsePath(pathValue)
-    const dirStat = await stat(dirPath)
-    if (!dirStat.isDirectory()) {
-      throw new Error(`${dirPath} is not a directory`)
-    }
-    const entries = await readdir(dirPath, { withFileTypes: true })
-    const mapped = await Promise.all(
-      entries
-        .filter((entry) => entry.name !== '.' && entry.name !== '..')
-        .map(async (entry) => ({
-          name: entry.name,
-          isDirectory: await isBrowseEntryDirectory(dirPath, entry),
-          isSymlink: entry.isSymbolicLink()
-        }))
-    )
-    sortDirEntries(mapped)
-    return {
-      resolvedPath: dirPath,
-      entries: mapped,
-      pathFlavor: process.platform === 'win32' ? 'win32' : 'posix'
-    }
+  async browseDirectory(pathValue: string): Promise<HostDirectoryListing> {
+    return browseServerDirectory(pathValue)
   }
 
   async isGitAvailable(): Promise<boolean> {

src/preload/api/filesystem-api.ts

@@ -5,6 +5,8 @@ import type { PdfExportResult } from '../../shared/pdf-export-failure-copy'
 import type {
   DirEntry,
   FsChangedPayload,
+  HostBrowseEntryResolution,
+  HostDirectoryListing,
   MarkdownDocument
 } from '../../shared/filesystem-entry-types'
 import type {
@@ -184,6 +186,14 @@ export type FilesystemApi = {
         permanent?: boolean
       } & SshMutationExpectation
     ) => Promise<void>
+    /** Desktop-only names listing for the Explorer's Host mode; never widens path grants. */
+    browseHostDir?: (args: { dirPath: string }) => Promise<HostDirectoryListing>
+    /** Desktop-only; classifies a host path against the workspace without granting access. */
+    resolveHostBrowseEntry?: (args: {
+      targetPath: string
+      connectionId?: string
+      workspaceRoot?: string
+    }) => Promise<HostBrowseEntryResolution>
     stat: (args: {
       filePath: string
       connectionId?: string

src/preload/api/fs-bridge.ts

@@ -18,7 +18,11 @@ import type {
   AgentSessionAttachmentUploadTarget
 } from '../../shared/agent-session-attachments'
 import type { SearchResult } from '../../shared/code-search-types'
-import type { FsChangedPayload } from '../../shared/filesystem-entry-types'
+import type {
+  FsChangedPayload,
+  HostBrowseEntryResolution,
+  HostDirectoryListing
+} from '../../shared/filesystem-entry-types'
 import type {
   ImportItemResult,
   ResolveDroppedPathsResult,
@@ -183,6 +187,13 @@ export const fsApi = {
       permanent?: boolean
     } & SshMutationExpectation
   ): Promise<void> => ipcRenderer.invoke('fs:deletePath', args),
+  browseHostDir: (args: { dirPath: string }): Promise<HostDirectoryListing> =>
+    ipcRenderer.invoke('fs:browseHostDir', args),
+  resolveHostBrowseEntry: (args: {
+    targetPath: string
+    connectionId?: string
+    workspaceRoot?: string
+  }): Promise<HostBrowseEntryResolution> => ipcRenderer.invoke('fs:resolveHostBrowseEntry', args),
   stat: (args: {
     filePath: string
     connectionId?: string