refactor(host): rename the directory-picker dialog backend and kind to native

The browse interaction also presents a dialog (the in-app modal), so 'dialog'
failed to discriminate the two capability kinds; 'native' names where the
chooser runs. Package directory-picker-dialog -> directory-picker-native, kind
'dialog' -> 'native', with every seam/gateway/client/doc reference updated and
the seam Agent Note's naming rationale rewritten to match.

packages/host/directory-picker-native/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Native backend of the directory-picker seam: registers `ctx.directoryPicker`
+ * with the `native` capability, opening one native OS chooser on the host
+ * display per pick (macOS `osascript`, Windows STA PowerShell
+ * `FolderBrowserDialog`, Linux Zenity with a KDialog fallback). Only viable
+ * when the operator sits at the host's screen; remote deployments compose the
+ * browse backend instead.
+ * @module @deepseek-ai/dsh-host-directory-picker-native
+ */
+
+import { DirectoryPicker } from '@deepseek-ai/dsh-host-directory-picker'
+import type { DirectoryPickerCapability } from '@deepseek-ai/dsh-host-directory-picker'
+import { pickNativeDirectory } from './native-picker.ts'
+
+export type { DirectoryPickerInternals, DirectoryPickerRunner } from './native-picker.ts'
+export { pickNativeDirectory } from './native-picker.ts'
+
+/** The `ctx.directoryPicker` native implementation (stable capability object per service life). */
+export default class NativeDirectoryPicker extends DirectoryPicker {
+  private readonly nativeCapability: DirectoryPickerCapability = {
+    kind: 'native',
+    /* v8 ignore next -- pure forward to pickNativeDirectory (its spec owns behavior); invoking here opens a real chooser. */
+    pick: signal => pickNativeDirectory(signal),
+  }
+
+  /**
+   * The native interaction capability.
+   * @returns the stable `native` capability object.
+   */
+  capability(): DirectoryPickerCapability {
+    return this.nativeCapability
+  }
+}

packages/host/directory-picker-native/src/invariant.ts

@@ -0,0 +1,25 @@
+/**
+ * Package-owned invariant companion for the native directory-picker backend.
+ * @module @deepseek-ai/dsh-host-directory-picker-native/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-directory-picker-native'
+
+/** Cordis companion plugin name. */
+export const name = 'host-directory-picker-native-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: each pick is one stateless subprocess round trip; the chooser outcome is only the returned path. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register the native directory-picker invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/host/directory-picker-native/src/native-picker.ts

@@ -0,0 +1,136 @@
+/** Cross-platform native single-directory chooser behind the dialog backend's capability. */
+
+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}`)
+}