feat(host): directory-picker capability seam with dialog and browse backends

The web GUI's folder picking was hardwired to one interaction: a native
OS chooser compiled into the gateway, unusable for remote deployments
and swappable only by editing apiproxy source.

Directory picking becomes a three-package capability seam in
packages/host: ctx.directoryPicker returns a discriminated capability —
dialog (the extracted native chooser; host-display only) or browse
(new: one-level listing + child creation over Node stdlib, hidden flags
host-stamped, symlinks followed, ancestry crumbs; remote-capable). The
gateway injects the seam, advertises the kind via
host.describe.directoryPicker, serves host.listDirectory /
host.createDirectory under browse, and answers
directory-picker-unavailable across kinds. cordis.yml is the swap
point; apps/cli keeps dialog mounted, so behavior is unchanged until
the in-app browser PR flips the default. The connection fixture serves
a deterministic browse tree; WorkspacesService gains the browse calls
the browser UI will drive. Decision record:
.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md

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

@@ -0,0 +1,118 @@
+/**
+ * The `ctx.directoryPicker` seam: how the web-GUI host lets an operator
+ * select a workspace directory. Backends differ in interaction shape, not
+ * just mechanism, so the service exposes a discriminated capability instead
+ * of one method set: a `dialog` backend opens one native OS chooser on the
+ * host's display, while a `browse` backend serves listing/creation primitives
+ * for an in-app browser (and thereby works for remote clients no OS dialog
+ * can reach). Consumers switch on `capability().kind`; the union is
+ * merge-extensible, and the documented default for an unknown kind is to
+ * hide the picking affordance rather than fail.
+ * @module @deepseek-ai/dsh-host-directory-picker
+ */
+
+import { Context, Service } from 'cordis'
+
+/** The dialog interaction: one native OS directory chooser on the host display. */
+export interface DirectoryPickerDialogCapability {
+  kind: 'dialog'
+  /**
+   * Open the chooser and wait for the operator.
+   * @param signal - caller/connection lifetime; abort terminates the chooser.
+   * @returns the chosen absolute path, or null when the operator cancels.
+   */
+  pick(signal: AbortSignal): Promise<string | null>
+}
+
+/** One directory row: a listing child or a breadcrumb ancestor. */
+export interface DirectoryEntry {
+  /** Base name shown in a browser row (a root crumb carries its full path). */
+  name: string
+  /** Absolute host path — clients never join path segments themselves. */
+  path: string
+  /** Hidden by the host platform's convention (dot-prefixed on POSIX); the client owns whether to show it. */
+  hidden: boolean
+}
+
+/** One directory level plus its ancestry, as a browse backend reports it. */
+export interface DirectoryListing {
+  /** Absolute path of the listed directory. */
+  path: string
+  /** The host account's home directory (breadcrumb "Home" rooting). */
+  home: string
+  /**
+   * Ancestor chain from the filesystem root to the listed directory
+   * inclusive; every crumb is a jump target (crumb `hidden` is always false).
+   */
+  crumbs: DirectoryEntry[]
+  /** Direct child directories, name-sorted; symlinks to directories included. */
+  entries: DirectoryEntry[]
+}
+
+/**
+ * The browse interaction: listing/creation primitives an in-app browser
+ * drives one level at a time. Works for remote clients — nothing renders on
+ * the host display.
+ */
+export interface DirectoryPickerBrowseCapability {
+  kind: 'browse'
+  /**
+   * List one directory level.
+   * @param path - absolute directory to list; absent lists the home directory.
+   * @returns the level's listing with ancestry.
+   * @throws {DirectoryPickerError} `directory-unreadable` when the target cannot be listed.
+   */
+  list(path?: string): Promise<DirectoryListing>
+  /**
+   * Create one child directory under an existing parent.
+   * @param path - absolute existing parent directory.
+   * @param name - single non-blank path segment (no separators, not `.`/`..`).
+   * @returns the created directory's absolute path.
+   * @throws {DirectoryPickerError} `directory-exists` for an existing child, `directory-create-failed` otherwise.
+   */
+  createDirectory(path: string, name: string): Promise<string>
+}
+
+/** Union of interaction shapes a backend can provide (merge-extensible: grows with backends). */
+export type DirectoryPickerCapability = DirectoryPickerDialogCapability | DirectoryPickerBrowseCapability
+
+/** Closed failure vocabulary of the browse primitives (mirrored onto the wire by consumers). */
+export type DirectoryPickerErrorCode = 'directory-unreadable' | 'directory-exists' | 'directory-create-failed'
+
+/** Typed failure thrown by browse primitives so consumers can map business codes without string matching. */
+export class DirectoryPickerError extends Error {
+  /**
+   * @param code - closed business code of the failure.
+   * @param path - the absolute path the failure is about.
+   * @param message - operator-facing description.
+   */
+  constructor(readonly code: DirectoryPickerErrorCode, readonly path: string, message: string) {
+    super(message)
+    this.name = 'DirectoryPickerError'
+  }
+}
+
+declare module 'cordis' {
+  interface Context {
+    directoryPicker: DirectoryPicker
+  }
+}
+
+/**
+ * Abstract directory-picking service. Subclass, implement `capability()`, and
+ * load the subclass as a plugin — it registers as `ctx.directoryPicker` (one
+ * implementation per context; loading a second throws, cordis' standard
+ * duplicate-service behavior). The capability object must be stable for the
+ * service lifetime: consumers may capture it across calls.
+ */
+export abstract class DirectoryPicker extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'directoryPicker')
+  }
+
+  /**
+   * The backend's interaction capability.
+   * @returns the discriminated capability consumers switch on.
+   */
+  abstract capability(): DirectoryPickerCapability
+}

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

@@ -0,0 +1,22 @@
+/** Package-owned invariant companion for the directory-picker seam. @module @deepseek-ai/dsh-host-directory-picker/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-directory-picker'
+
+/** Cordis companion plugin name. */
+export const name = 'host-directory-picker-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: this stateless seam owns the capability vocabulary, while backends and the RPC consumer own observations. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register the 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))