@x1a0f3n9/dsh-host-directory-picker-native 0.1.5-rc.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/host/directory-picker-native/README.md
+README.md: 3f980831848965b976e32b0e5ef25abb77fe4e6e
+README.zh.md: 7a221cbbfebf3d79534e049800e26dab6ca39ad3

package/README.md

@@ -0,0 +1,113 @@
+---
+description: "Native-OS-chooser backend of the directory-picker seam: opens one platform chooser per pick for operators sitting at the web GUI host's display."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-host-directory-picker-native
+
+English | [中文](README.zh.md)
+
+## Summary
+
+An operator at the host's display picks a workspace directory through a native OS chooser: `dsh-host-directory-picker-native` opens one platform directory chooser per pick and resolves the chosen absolute path (`null` on cancel). macOS drives `osascript`, Linux uses Zenity with a KDialog fallback, and Windows opens the modern `IFileOpenDialog` in a spawned child process. Only viable when the operator sits at the host's display — remote deployments compose the [browse backend](../directory-picker-browse/README.md) instead. One composition row also registers the matching browser-side interaction in the workspace flow, so it selects both sides.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Compose this backend when the operator works at the host's display and a native chooser is the right interaction. A workspace flow that opens a directory picker calls `pick(signal)` once per open request; the returned promise resolves with the chosen absolute path, or `null` when the operator cancels.
+
+### When to choose it
+
+Choose this backend for a workstation-local operator on macOS, Windows, or desktop Linux. Choose the [browse backend](../directory-picker-browse/README.md) when clients cannot reach an OS chooser — remote browsers, SSH-forwarded sessions, or unattended hosts. When the situation varies, the [adaptive chooser](../directory-picker-auto/README.md) resolves it at boot.
+
+### What an operator experiences
+
+Each call opens one native chooser on the host display and waits for the operator; aborting the caller's signal terminates the chooser process instead of leaving it open. On Linux the chooser needs either Zenity or KDialog installed; with neither present, `pick` rejects with an actionable error instead of falling back to a typed-path prompt. The browser half of this package registers a renderless flow occupant into the workspace flow — every `open` request drives `directoryPicker/pick` and reports the one outcome (picked path, cancel, or failure).
+
+### Observable failures
+
+A cancel returns `null`, not an error. Missing platform tooling, a failed chooser launch, or an aborted pick surfaces as a rejection the UI can present; the [browse backend](../directory-picker-browse/README.md) remains the composition-level fallback for deployments where native picking is unreliable.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+### Design concept
+
+The backend is a thin service over a platform chooser: `NativeDirectoryPicker` registers the `native` capability whose `pick` forwards to `pickNativeDirectory`, and the chooser runs as a subprocess so the host process never blocks on the dialog. The command boundary (`DirectoryPickerRunner`) and platform facts are injectable, and the shared no-shell subprocess runner lives in [`dsh-native-command`](../../util/native-command/README.md).
+
+### Platform mechanics
+
+Platform tools run without a shell: `osascript` on macOS, and Zenity with a KDialog fallback on Linux; the caller's abort terminates the native process. Windows opens the modern `IFileOpenDialog` in a spawned child process — a koffi-driven COM conversation on the child's main thread with the best thread DPI awareness the host accepts (per-monitor-v2 first), aborted by posting `WM_CLOSE` to the dialog thread. Immediately before `Show`, the child synthesizes one Alt press through `keybd_event`, which lets the dialog activate as the foreground window even when a background host process spawned the child.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `NativeDirectoryPicker` service with the stable `native` capability |
+| [`src/native-picker.ts`](src/native-picker.ts) | Chooser dispatch: platform selection, subprocess running, abort wiring |
+| [`src/win32-dialog.ts`](src/win32-dialog.ts) + siblings | Windows child-process `IFileOpenDialog` via koffi, DPI handling, `WM_CLOSE` abort |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these when the backend contract is not enough: the seam definition first, then the alternative backend and the chooser that selects between them.
+
+- [Directory-picker seam](../directory-picker/README.md) — the `native` capability contract and the typed error vocabulary.
+- [Directory-picker capability seam decision](../../../.agents/notes/archived/architecture/2026-07-28-directory-picker-capability-seam.md) — why backends differ in interaction shape.
+- [Browse backend](../directory-picker-browse/README.md) — the in-app alternative for remote clients.
+- [Adaptive chooser](../directory-picker-auto/README.md) — boot-time resolution between native and browse.
+- [No-shell subprocess runner](../../util/native-command/README.md) — the shared subprocess primitive the chooser runs on.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the GUI-host picking backend registers nothing model-facing.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the native interaction is unavailable or fragile. They are current package constraints, not a task backlog.
+
+- **Linux requires desktop tooling** — with neither Zenity nor KDialog installed, `pick` rejects with an actionable error; it does not fall back to a typed-path prompt (the browse backend is that fallback at the composition level).
+- **Windows has no mechanism fallback** — the child-process picker through packaged koffi is the only native tier, so a COM refusal or dialog crash surfaces the failure; the browse backend remains the fallback at the composition level.
+- **Windows foreground grant relies on injected input** — the child synthesizes an Alt press before `Show` so the dialog can take the foreground from a background host; where synthesized input is suppressed (secure desktops, restricted remote sessions, an elevated foreground window), the dialog may still open behind other windows. The technique is validated on Windows 11 only.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. Each pick is one stateless subprocess round trip; the chooser outcome is only the returned path.

package/README.zh.md

@@ -0,0 +1,113 @@
+---
+description: "目录选择 seam 的原生 OS 选择器后端：为坐在 web GUI 宿主屏幕前的操作者每次打开一个平台选择器。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-host-directory-picker-native
+
+[English](README.md) | 中文
+
+## 概述
+
+坐在宿主屏幕前的操作者通过原生 OS 选择器选择工作区目录：`dsh-host-directory-picker-native` 每次选择打开一个平台目录选择器，并解析出所选绝对路径（取消时为 `null`）。macOS 驱动 `osascript`，Linux 使用 Zenity 并以 KDialog 回退，Windows 在 spawn 的子进程中打开现代 `IFileOpenDialog`。只有操作者坐在宿主屏幕前时才可用——远程部署应组合[浏览后端](../directory-picker-browse/README.zh.md)。一行组合配置还会在工作区流程中注册匹配的浏览器侧交互，因此同时选择两侧。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当操作者工作在宿主屏幕前，且原生选择器是合适的交互时，组合此后端。打开目录选择器的工作区流程每个打开请求调用一次 `pick(signal)`；返回的 Promise 解析为所选绝对路径，操作者取消时解析为 `null`。
+
+### 何时选择
+
+为 macOS、Windows 或桌面 Linux 上的工作站本地操作者选择此后端。当客户端无法触达 OS 选择器时——远程浏览器、SSH 转发会话或无人值守宿主——请选择[浏览后端](../directory-picker-browse/README.zh.md)。具体情况不固定时，[自适应选择器](../directory-picker-auto/README.zh.md)会在启动时判定。
+
+### 操作者会看到什么
+
+每次调用在宿主屏幕上打开一个原生选择器并等待操作者；中止调用方的信号会终止选择器进程，而不是让它留在屏幕上。Linux 上选择器需要安装 Zenity 或 KDialog 之一；两者都没有时，`pick` 以包含解决建议的错误拒绝，而不会回退为手输路径提示。本包的浏览器端向工作区流程注册一个无渲染的流程占用者——每次 `open` 请求驱动 `directoryPicker/pick`，并上报唯一结果（所选路径、取消或失败）。
+
+### 可观察的失败
+
+取消返回 `null`，不是错误。平台工具缺失、选择器启动失败或选择操作中止都会导致 Promise 拒绝，界面可呈现相应错误；[浏览后端](../directory-picker-browse/README.zh.md)仍是原生目录选择不可靠时的组合层回退方案。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+### 设计理念
+
+后端是平台选择器之上的一层薄服务：`NativeDirectoryPicker` 注册 `native` 能力，其 `pick` 转发给 `pickNativeDirectory`，选择器以子进程运行，因此宿主进程不会因对话框而阻塞。命令边界（`DirectoryPickerRunner`）与平台事实可注入；共享的免 shell 子进程运行器位于 [`dsh-native-command`](../../util/native-command/README.zh.md)。
+
+### 平台机制
+
+平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在 spawn 的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。在 `Show` 之前，子进程立即通过 `keybd_event` 合成一次 Alt 按键，让对话框即使由后台宿主进程 spawn 也能激活为前台窗口。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：持有稳定 `native` 能力的 `NativeDirectoryPicker` 服务 |
+| [`src/native-picker.ts`](src/native-picker.ts) | 选择器分发：平台选择、子进程运行、中止接线 |
+| [`src/win32-dialog.ts`](src/win32-dialog.ts) 及同族文件 | Windows 经 koffi 的子进程 `IFileOpenDialog`、DPI 处理、`WM_CLOSE` 中止 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当后端约定不够用时阅读以下内容：先看 seam 定义，再看替代后端与在两者之间选择的那个选择器。
+
+- [目录选择 seam](../directory-picker/README.zh.md)——`native` 能力约定与类型化错误词汇。
+- [目录选择能力 seam 决策](../../../.agents/notes/archived/architecture/2026-07-28-directory-picker-capability-seam.md)——后端为何在交互形态上彼此不同。
+- [浏览后端](../directory-picker-browse/README.zh.md)——面向远程客户端的应用内替代方案。
+- [自适应选择器](../directory-picker-auto/README.zh.md)——native 与 browse 之间的启动时判定。
+- [免 shell 子进程运行器](../../util/native-command/README.zh.md)——选择器运行所依赖的共享子进程原语。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无。GUI 宿主的目录选择后端不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明原生交互何时不可用或不稳定。它们是当前包约束，不是任务积压。
+
+- **Linux 依赖桌面工具**——Zenity 与 KDialog 均未安装时，`pick` 以包含解决建议的错误拒绝；它不会回退为手输路径提示（组合层面的回退是浏览后端）。
+- **Windows 没有机制级回退**——通过打包依赖 koffi 运行的子进程选择器是唯一原生层级，因此 COM 拒绝或对话框崩溃会直接上报失败；组合层面的回退仍是浏览后端。
+- **Windows 前台授权依赖注入的输入**——子进程在 `Show` 之前合成一次 Alt 按键，对话框才能从后台宿主取得前台；在合成输入被抑制的环境（安全桌面、受限远程会话、提权前台窗口）中，对话框仍可能在其他窗口后面打开。该技术仅在 Windows 11 上验证过。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变式：** 不发布伴生入口。每次选择都是一次无状态的子进程往返；选择器的结果仅为返回的路径。

package/lib/index.js

@@ -0,0 +1,303 @@
+import { DirectoryPicker } from "@x1a0f3n9/dsh-host-directory-picker";
+import { runNativeCommand } from "@x1a0f3n9/dsh-native-command";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+//#region lib/types/win32-dialog-bindings.js
+const WM_CLOSE = 16;
+/**
+* Encode a canonical GUID string as its 16 little-endian bytes.
+* @param text - the `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` form.
+* @returns the in-memory GUID bytes CoCreateInstance expects.
+*/
+function guidBytes(text) {
+	const match = /^([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})$/i.exec(text);
+	const bytes = Buffer.alloc(16);
+	bytes.writeUInt32LE(parseInt(match[1], 16), 0);
+	bytes.writeUInt16LE(parseInt(match[2], 16), 4);
+	bytes.writeUInt16LE(parseInt(match[3], 16), 6);
+	Buffer.from(match[4] + match[5], "hex").copy(bytes, 8);
+	return bytes;
+}
+guidBytes("dc1c5a9c-e88a-4dde-a5a1-60f82a20aef7");
+guidBytes("d57c7288-d4ad-4768-be02-9d969532d960");
+/**
+* Post `WM_CLOSE` to every window of a native thread — the driver's abort
+* lever against the worker blocked inside `Show`, after which `Show` returns
+* `HRESULT_CANCELLED` and the worker unwinds normally.
+* @param threadId - the dialog thread's native id (from the `showing` notice).
+*/
+async function closeThreadWindows(threadId) {
+	const koffi = (await import("koffi")).default;
+	const user32 = koffi.load("user32.dll");
+	const enumThreadWindows = user32.func("__stdcall", "EnumThreadWindows", "int", [
+		"uint32",
+		"void *",
+		"intptr"
+	]);
+	const postMessageW = user32.func("__stdcall", "PostMessageW", "int", [
+		"void *",
+		"uint32",
+		"uintptr",
+		"intptr"
+	]);
+	const protoEnumProc = koffi.proto("int __stdcall DshEnumThreadWndProc(void *hwnd, intptr lparam)");
+	const callback = koffi.register((hwnd) => {
+		postMessageW(hwnd, WM_CLOSE, 0, 0);
+		return 1;
+	}, koffi.pointer(protoEnumProc));
+	try {
+		enumThreadWindows(threadId, callback, 0);
+	} finally {
+		koffi.unregister(callback);
+	}
+}
+//#endregion
+//#region lib/types/win32-dialog-host.js
+/**
+* Real-process half of the Win32 dialog driver: spawn the dialog child
+* process (source or built plane) and close a dialog thread's windows. The
+* module itself loads everywhere (the import chain from native-picker.ts is
+* static); what stays win32-only is koffi, imported dynamically inside the
+* bindings' functions. The driver's logic is tested against fakes of this
+* surface instead.
+*/
+/**
+* Spawn the dialog child process. Built consumers launch the bundled CJS
+* entry next to this module under plain node; unbuilt (source) consumers
+* bootstrap tsx first, mirroring the dsh CLI's source launch. The child
+* opens its dialog as foreground on its own: `runFolderDialog` synthesizes
+* an Alt press before `Show`, which matters when a background host spawned
+* the child.
+* @param data - the child payload (dialog title).
+* @returns the spawned child process.
+*/
+function spawnDialogWorker(data) {
+	const env = {
+		...process.env,
+		DSH_DIALOG_TITLE: data.title
+	};
+	const stdio = [
+		"ignore",
+		"inherit",
+		"inherit",
+		"ipc"
+	];
+	/* v8 ignore next 3 -- the built-output arm: tests always run unbuilt (src/) */
+	if (!import.meta.url.endsWith(".ts")) return spawn(process.execPath, [fileURLToPath(new URL("./worker.cjs", import.meta.url))], {
+		env,
+		stdio,
+		windowsHide: true
+	});
+	return spawn(process.execPath, [
+		"--import",
+		import.meta.resolve("tsx/esm"),
+		fileURLToPath(new URL("./win32-dialog-worker.ts", import.meta.url))
+	], {
+		env,
+		stdio,
+		windowsHide: true
+	});
+}
+//#endregion
+//#region lib/types/win32-dialog.js
+/**
+* Main-thread driver for the Win32 folder dialog: spawns the dialog child
+* process (which blocks inside the modal `Show`), maps its message protocol
+* onto a promise, and services aborts by posting `WM_CLOSE` to the dialog
+* thread's windows until the child reports back. The real process/window
+* surface is injectable so every driver path is testable on any platform.
+*/
+/** The dialog title every host shows. */
+const DIALOG_TITLE = "Select Workspace Directory";
+/** `WM_CLOSE` re-post cadence while an abort waits for the worker to unwind. */
+const CLOSE_RETRY_MS = 150;
+/** Abort-service attempts before force-terminating the worker. */
+const CLOSE_MAX_ATTEMPTS = 20;
+/** Fail loudly if the closed worker-to-driver union gains an unhandled member. */
+/* v8 ignore start -- closed-union backstop; unreachable without a TypeScript contract violation */
+function assertNever(value) {
+	throw new TypeError(`unknown win32 dialog worker message kind: ${String(value)}`);
+}
+/* v8 ignore stop */
+/**
+* Open the modern Win32 folder picker off the event loop.
+* @param signal - caller lifetime; abort closes the dialog and rejects.
+* @param internals - Worker/window hooks for deterministic tests.
+* @returns the selected path, or null when the user cancels.
+*/
+async function pickWin32Directory(signal, internals = {}) {
+	if (signal.aborted) throw new Error("native directory picker aborted");
+	const spawnWorker = internals.spawnWorker ?? spawnDialogWorker;
+	const closeWindows = internals.closeThreadWindows ?? closeThreadWindows;
+	const closeRetryMs = internals.closeRetryMs ?? CLOSE_RETRY_MS;
+	const worker = spawnWorker({ title: DIALOG_TITLE });
+	let dialogThreadId;
+	let closeTimer;
+	let settled = false;
+	return await new Promise((resolve, reject) => {
+		const settle = (outcome) => {
+			if (settled) return;
+			settled = true;
+			if (closeTimer !== void 0) clearInterval(closeTimer);
+			signal.removeEventListener("abort", onAbort);
+			worker.unref?.();
+			outcome();
+		};
+		const postClose = () => {
+			if (dialogThreadId !== void 0) closeWindows(dialogThreadId).catch(() => void 0);
+		};
+		const serviceAbort = () => {
+			let attempts = 0;
+			closeTimer = setInterval(() => {
+				attempts += 1;
+				if (attempts > CLOSE_MAX_ATTEMPTS) {
+					settle(() => {
+						worker.kill();
+						reject(/* @__PURE__ */ new Error("native directory picker aborted (dialog unresponsive; worker killed)"));
+					});
+					return;
+				}
+				postClose();
+			}, closeRetryMs);
+			postClose();
+		};
+		const onAbort = () => {
+			serviceAbort();
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		worker.on("message", (message) => {
+			switch (message.kind) {
+				case "showing":
+					dialogThreadId = message.threadId;
+					if (signal.aborted) postClose();
+					return;
+				case "done":
+					settle(() => {
+						if (signal.aborted) reject(/* @__PURE__ */ new Error("native directory picker aborted"));
+						else resolve(message.path);
+					});
+					return;
+				case "error":
+					settle(() => {
+						reject(/* @__PURE__ */ new Error(`win32 folder dialog failed: ${message.message}`));
+					});
+					return;
+				/* v8 ignore next 2 -- closed worker-owned union; a fourth kind becomes a compile error */
+				default: assertNever(message);
+			}
+		});
+		worker.on("error", (error) => {
+			settle(() => {
+				reject(error);
+			});
+		});
+		worker.on("exit", () => {
+			settle(() => {
+				reject(/* @__PURE__ */ new Error("win32 folder dialog worker exited before reporting a result"));
+			});
+		});
+	});
+}
+//#endregion
+//#region lib/types/native-picker.js
+/** Cross-platform native single-directory chooser behind the native backend's capability. */
+function outputPath(stdout) {
+	const path = stdout.replace(/[\r\n]+$/, "");
+	return path === "" ? null : path;
+}
+function errorCode(error) {
+	if (typeof error !== "object" || error === null || !("code" in error)) return void 0;
+	const code = error.code;
+	return typeof code === "string" || typeof code === "number" ? code : void 0;
+}
+function errorStderr(error) {
+	if (typeof error !== "object" || error === null || !("stderr" in error)) return "";
+	const stderr = error.stderr;
+	return typeof stderr === "string" ? stderr : "";
+}
+function isMissingCommand(error) {
+	return errorCode(error) === "ENOENT";
+}
+function rethrowIfAborted(signal, error) {
+	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 hooks for deterministic tests.
+* @returns the selected path, or null when the user cancels.
+*/
+async function pickNativeDirectory(signal, internals = {}) {
+	const platform = internals.platform ?? process.platform;
+	const run = internals.run ?? runNativeCommand;
+	if (platform === "darwin") try {
+		return outputPath((await run("osascript", [
+			"-e",
+			"set selectedFolder to choose folder with prompt \"Select Workspace Directory\"",
+			"-e",
+			"POSIX path of selectedFolder"
+		], signal)).stdout);
+	} catch (error) {
+		if (!signal.aborted && errorCode(error) === 1 && /(?:User canceled|-128)/i.test(errorStderr(error))) return null;
+		throw error;
+	}
+	if (platform === "win32") return await (internals.pickWin32Dialog ?? pickWin32Directory)(signal);
+	if (platform === "linux") {
+		try {
+			return outputPath((await run("zenity", [
+				"--file-selection",
+				"--directory",
+				"--title=Select Workspace Directory"
+			], signal)).stdout);
+		} catch (error) {
+			rethrowIfAborted(signal, error);
+			if (errorCode(error) === 1) return null;
+			if (!isMissingCommand(error)) throw error;
+		}
+		try {
+			return outputPath((await run("kdialog", [
+				"--getexistingdirectory",
+				".",
+				"--title",
+				"Select Workspace Directory"
+			], signal)).stdout);
+		} catch (error) {
+			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}`);
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* 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`, Linux Zenity with a KDialog fallback;
+* Windows opens the modern `IFileOpenDialog` in a spawned child process — a
+* koffi-driven COM conversation on the child's main thread, preceded by a
+* synthesized Alt press so the dialog activates as foreground even when a
+* background host spawned the child). Only viable when
+* the operator sits at the host's screen; remote deployments compose the
+* browse backend instead.
+* @module @x1a0f3n9/dsh-host-directory-picker-native
+*/
+/** The `ctx.directoryPicker` native implementation (stable capability object per service life). */
+var NativeDirectoryPicker = class extends DirectoryPicker {
+	nativeCapability = {
+		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() {
+		return this.nativeCapability;
+	}
+};
+//#endregion
+export { NativeDirectoryPicker as default, pickNativeDirectory };

package/lib/types/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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`, Linux Zenity with a KDialog fallback;
+ * Windows opens the modern `IFileOpenDialog` in a spawned child process — a
+ * koffi-driven COM conversation on the child's main thread, preceded by a
+ * synthesized Alt press so the dialog activates as foreground even when a
+ * background host spawned the child). Only viable when
+ * the operator sits at the host's screen; remote deployments compose the
+ * browse backend instead.
+ * @module @x1a0f3n9/dsh-host-directory-picker-native
+ */
+import { DirectoryPicker } from '@x1a0f3n9/dsh-host-directory-picker';
+import type { DirectoryPickerCapability } from '@x1a0f3n9/dsh-host-directory-picker';
+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;
+    /**
+     * The native interaction capability.
+     * @returns the stable `native` capability object.
+     */
+    capability(): DirectoryPickerCapability;
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/types/native-picker.d.ts

@@ -0,0 +1,19 @@
+/** Cross-platform native single-directory chooser behind the native backend's capability. */
+import { type NativeCommandRunner } from '@x1a0f3n9/dsh-native-command';
+/** Testable command boundary; native implementations never invoke a shell. */
+export type DirectoryPickerRunner = NativeCommandRunner;
+/** Injectable platform facts for deterministic adapter tests. */
+export interface DirectoryPickerInternals {
+    platform?: NodeJS.Platform;
+    run?: DirectoryPickerRunner;
+    /** Replaces the in-process Win32 dialog (`pickWin32Directory`) for deterministic tests. */
+    pickWin32Dialog?: (signal: AbortSignal) => Promise<string | null>;
+}
+/**
+ * Open the platform directory picker.
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - Platform and runner hooks for deterministic tests.
+ * @returns the selected path, or null when the user cancels.
+ */
+export declare function pickNativeDirectory(signal: AbortSignal, internals?: DirectoryPickerInternals): Promise<string | null>;
+//# sourceMappingURL=native-picker.d.ts.map

package/lib/types/win32-dialog-bindings.d.ts

@@ -0,0 +1,27 @@
+/**
+ * koffi-backed Win32 bindings for the folder dialog: the COM vtable calls
+ * behind {@link Win32DialogBindings} plus the cross-thread window closer the
+ * driver uses to service aborts. The module loads on every platform; koffi
+ * itself is imported lazily inside each function, so non-Windows processes
+ * never load it — the same containment as the repo's other `win32.ts`
+ * modules.
+ *
+ * The COM surface used here (IModalWindow/IFileDialog/IFileOpenDialog and
+ * IShellItem vtable order, the GUIDs, `FOS_*` and `SIGDN_FILESYSPATH`) is
+ * frozen Windows ABI since Vista; slots are offsets into the vtable at the
+ * object's first pointer.
+ */
+import type { Win32DialogBindings } from './win32-dialog-logic.ts';
+/**
+ * Load koffi and expose the dialog bindings for this thread.
+ * @returns the bindings {@link runFolderDialog} sequences against.
+ */
+export declare function loadWin32DialogBindings(): Promise<Win32DialogBindings>;
+/**
+ * Post `WM_CLOSE` to every window of a native thread — the driver's abort
+ * lever against the worker blocked inside `Show`, after which `Show` returns
+ * `HRESULT_CANCELLED` and the worker unwinds normally.
+ * @param threadId - the dialog thread's native id (from the `showing` notice).
+ */
+export declare function closeThreadWindows(threadId: number): Promise<void>;
+//# sourceMappingURL=win32-dialog-bindings.d.ts.map

package/lib/types/win32-dialog-host.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Real-process half of the Win32 dialog driver: spawn the dialog child
+ * process (source or built plane) and close a dialog thread's windows. The
+ * module itself loads everywhere (the import chain from native-picker.ts is
+ * static); what stays win32-only is koffi, imported dynamically inside the
+ * bindings' functions. The driver's logic is tested against fakes of this
+ * surface instead.
+ */
+import { spawn } from 'node:child_process';
+import type { Win32DialogWorkerData } from './win32-dialog-worker.ts';
+/**
+ * Spawn the dialog child process. Built consumers launch the bundled CJS
+ * entry next to this module under plain node; unbuilt (source) consumers
+ * bootstrap tsx first, mirroring the dsh CLI's source launch. The child
+ * opens its dialog as foreground on its own: `runFolderDialog` synthesizes
+ * an Alt press before `Show`, which matters when a background host spawned
+ * the child.
+ * @param data - the child payload (dialog title).
+ * @returns the spawned child process.
+ */
+export declare function spawnDialogWorker(data: Win32DialogWorkerData): ReturnType<typeof spawn>;
+export { closeThreadWindows } from './win32-dialog-bindings.ts';
+//# sourceMappingURL=win32-dialog-host.d.ts.map

package/lib/types/win32-dialog-logic.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Pure sequencing of the Win32 `IFileOpenDialog` folder-picker COM
+ * conversation over injectable platform bindings, so every outcome path
+ * (selection, cancellation, HRESULT failure, cleanup ordering) is testable on
+ * any platform. The koffi-backed bindings live in
+ * `win32-dialog-bindings.ts`, which only a real win32 process ever loads.
+ */
+/** `HRESULT_FROM_WIN32(ERROR_CANCELLED)`: the user dismissed the dialog. */
+export declare const HRESULT_CANCELLED: number;
+/** `FOS_PICKFOLDERS`: the dialog selects directories, not files. */
+export declare const FOS_PICKFOLDERS = 32;
+/** `FOS_FORCEFILESYSTEM`: only results with a filesystem path can be chosen. */
+export declare const FOS_FORCEFILESYSTEM = 64;
+/** `FOS_NOCHANGEDIR`: never mutate the process working directory. */
+export declare const FOS_NOCHANGEDIR = 8;
+/** One created folder dialog: the vtable calls the sequencing needs. */
+export interface Win32FolderDialog {
+    /**
+     * `IFileDialog::SetOptions`.
+     * @param options - the `FOS_*` flag union to apply.
+     * @returns the call's HRESULT.
+     */
+    setOptions(options: number): number;
+    /**
+     * `IFileDialog::SetTitle`.
+     * @param title - the dialog title text.
+     * @returns the call's HRESULT.
+     */
+    setTitle(title: string): number;
+    /**
+     * `IModalWindow::Show` with no owner window; blocks the calling thread
+     * until the user selects or dismisses.
+     * @returns the call's HRESULT (`HRESULT_CANCELLED` on dismissal).
+     */
+    show(): number;
+    /**
+     * `IFileDialog::GetResult` + `IShellItem::GetDisplayName(SIGDN_FILESYSPATH)`,
+     * releasing the shell item and freeing the COM string.
+     * @returns the call chain's HRESULT and, on success, the selected path.
+     */
+    resultPath(): {
+        hr: number;
+        path?: string;
+    };
+    /** Release the dialog's COM reference. */
+    release(): void;
+}
+/** The thread-level native surface the dialog sequencing runs against. */
+export interface Win32DialogBindings {
+    /**
+     * Opt the calling thread into the best supported DPI awareness
+     * (per-monitor-v2, then per-monitor, then system-aware), checking each
+     * call's result. Best-effort on purpose: a host accepting none of them
+     * (or lacking the API, pre-1607) still shows the modern dialog — possibly
+     * blurry above 100 % scaling — because a cosmetic degradation must not
+     * cost the tier.
+     */
+    setThreadDpiAwareness(): void;
+    /**
+     * `CoInitializeEx(COINIT_APARTMENTTHREADED)` on the calling thread.
+     * @returns the call's HRESULT (`S_FALSE` re-entry is still a success).
+     */
+    coInitializeSta(): number;
+    /**
+     * `CoUninitialize` on the calling thread — COM requires one pairing call
+     * for every successful (including `S_FALSE`) `CoInitializeEx`, even on a
+     * thread that exits right after the conversation.
+     */
+    coUninitialize(): void;
+    /**
+     * `CoCreateInstance(CLSID_FileOpenDialog)`.
+     * @returns the created dialog surface; throws when creation fails.
+     */
+    createFolderDialog(): Win32FolderDialog;
+    /**
+     * `GetCurrentThreadId` — the native id a driver needs to close this
+     * thread's windows from outside.
+     * @returns the calling thread's native id.
+     */
+    currentThreadId(): number;
+    /**
+     * Make the dialog that `Show` is about to create able to take the
+     * foreground. Windows grants activation only to the foreground process,
+     * to a process it started, or to a process that received recent input; a
+     * worker spawned by a background host (the web GUI server) qualifies for
+     * none, so the dialog would open behind every other window. Synthesizing
+     * one Alt press (down, then up) through `keybd_event` counts this process
+     * as the most recent input owner — a community-documented technique with
+     * no documented contract. Call immediately before `Show`. When the
+     * process already holds foreground rights (a console-launched CLI), the
+     * press is inert, but the focused window still receives the lone Alt and
+     * may briefly highlight its menu bar before the dialog activates.
+     */
+    pressAltForForeground(): void;
+}
+/**
+ * Run one modal folder-picker conversation on the calling thread: DPI opt-in,
+ * STA init, dialog creation, `Show`, and result extraction, releasing the
+ * dialog on every path.
+ * @param bindings - the native surface (koffi-backed in production, fakes in tests).
+ * @param title - the dialog title text.
+ * @param onShowing - called with the native thread id immediately before the
+ *   blocking `Show`, so a driver on another thread can close the dialog.
+ * @returns the selected filesystem path, or null when the user cancels.
+ */
+export declare function runFolderDialog(bindings: Win32DialogBindings, title: string, onShowing: (threadId: number) => void): string | null;
+//# sourceMappingURL=win32-dialog-logic.d.ts.map

package/lib/types/win32-dialog-worker.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Child-process entry for the Win32 folder dialog: blocks THIS process
+ * inside the modal `Show` so the host event loop stays live, reporting over
+ * the IPC channel. Spawned as a child process (not a worker thread) so a
+ * native fault stays contained and the modal call never wedges the host.
+ * A background host (the web GUI server) leaves this process without
+ * foreground rights, so `runFolderDialog` synthesizes an Alt press
+ * immediately before `Show` and the dialog then activates as foreground.
+ * Protocol: `{kind:'showing',threadId}` right
+ * before the blocking call (the driver's abort lever needs the native
+ * thread id), then exactly one of `{kind:'done',path}` or
+ * `{kind:'error',message}`.
+ */
+/** The driver-to-child payload: the dialog title (passed via env). */
+export interface Win32DialogWorkerData {
+    title: string;
+}
+/** One notice or outcome posted back to the driver. */
+export type Win32DialogWorkerMessage = {
+    kind: 'showing';
+    threadId: number;
+} | {
+    kind: 'done';
+    path: string | null;
+} | {
+    kind: 'error';
+    message: string;
+};
+//# sourceMappingURL=win32-dialog-worker.d.ts.map

package/lib/types/win32-dialog.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Main-thread driver for the Win32 folder dialog: spawns the dialog child
+ * process (which blocks inside the modal `Show`), maps its message protocol
+ * onto a promise, and services aborts by posting `WM_CLOSE` to the dialog
+ * thread's windows until the child reports back. The real process/window
+ * surface is injectable so every driver path is testable on any platform.
+ */
+import type { Win32DialogWorkerData, Win32DialogWorkerMessage } from './win32-dialog-worker.ts';
+/** The child-process surface the driver drives (satisfied by `node:child_process`). */
+export interface Win32DialogWorkerLike {
+    /**
+     * Subscribe to a child-process event.
+     * @param event - `message`, `error`, or `exit`.
+     * @param listener - the event consumer.
+     */
+    on(event: 'message', listener: (message: Win32DialogWorkerMessage) => void): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    on(event: 'exit', listener: (code: number) => void): unknown;
+    /**
+     * Force-stop the child; the abort path's last resort when `WM_CLOSE`
+     * never lands (e.g. the dialog window was never created).
+     * @returns whether a kill signal was delivered.
+     */
+    kill(): boolean;
+    /**
+     * Release the event-loop reference. Called once the pick settles so a
+     * child stuck in the native modal call never blocks process exit.
+     */
+    unref?(): void;
+}
+/** Injectable process surface for deterministic driver tests. */
+export interface Win32DialogInternals {
+    /** Replaces the real child spawn (`win32-dialog-host.ts`). */
+    spawnWorker?: (data: Win32DialogWorkerData) => Win32DialogWorkerLike;
+    /** Replaces the real `WM_CLOSE` poster (`win32-dialog-host.ts`). */
+    closeThreadWindows?: (threadId: number) => Promise<void>;
+    /** Abort-service cadence override so tests never wait wall-clock time. */
+    closeRetryMs?: number;
+}
+/** The dialog title every host shows. */
+export declare const DIALOG_TITLE = "Select Workspace Directory";
+/**
+ * Open the modern Win32 folder picker off the event loop.
+ * @param signal - caller lifetime; abort closes the dialog and rejects.
+ * @param internals - Worker/window hooks for deterministic tests.
+ * @returns the selected path, or null when the user cancels.
+ */
+export declare function pickWin32Directory(signal: AbortSignal, internals?: Win32DialogInternals): Promise<string | null>;
+//# sourceMappingURL=win32-dialog.d.ts.map

package/lib/worker.cjs

@@ -0,0 +1,253 @@
+//#region lib/types/win32-dialog-bindings.js
+/**
+* koffi-backed Win32 bindings for the folder dialog: the COM vtable calls
+* behind {@link Win32DialogBindings} plus the cross-thread window closer the
+* driver uses to service aborts. The module loads on every platform; koffi
+* itself is imported lazily inside each function, so non-Windows processes
+* never load it — the same containment as the repo's other `win32.ts`
+* modules.
+*
+* The COM surface used here (IModalWindow/IFileDialog/IFileOpenDialog and
+* IShellItem vtable order, the GUIDs, `FOS_*` and `SIGDN_FILESYSPATH`) is
+* frozen Windows ABI since Vista; slots are offsets into the vtable at the
+* object's first pointer.
+*/
+/**
+* Read a valid NUL-terminated UTF-16 allocation without an external buffer.
+* Generic `koffi.decode(..., 'str16')` expects a pointer variable, so the
+* buffer holds the string address rather than the string bytes.
+* @param koffi - the loaded koffi binding.
+* @param address - the string address surfaced by the `_Out_ void **` param.
+* @param pointerSize - the process's pointer width (`koffi.sizeof('void *')`).
+* @returns the decoded UTF-16 path.
+*/
+function readUtf16(koffi, address, pointerSize) {
+	const pointer = Buffer.alloc(8);
+	pointer.writeBigUInt64LE(BigInt(address));
+	return koffi.decode(pointer.subarray(0, pointerSize), "str16");
+}
+const COINIT_APARTMENTTHREADED = 2;
+const CLSCTX_INPROC_SERVER = 1;
+const SIGDN_FILESYSPATH = -2147123200;
+/**
+* Thread DPI awareness contexts, best first: per-monitor-v2 (Windows 10
+* 1703+), per-monitor (1607+), then system-aware. `SetThreadDpiAwarenessContext`
+* returns NULL for an unsupported context instead of throwing, so the caller
+* cascades to the best one the host accepts; DPI stays a cosmetic
+* best-effort — an unsupported host still gets the modern dialog.
+*/
+const DPI_AWARENESS_CONTEXTS = [
+	-4,
+	-3,
+	-2
+];
+/** `VK_MENU`: the synthesized Alt press's virtual key. */
+const VK_MENU = 18;
+/** `KEYEVENTF_KEYUP`: the synthesized Alt press's release flag. */
+const KEYEVENTF_KEYUP = 2;
+/** IFileOpenDialog vtable slots (IUnknown 0-2, IModalWindow 3, IFileDialog 4+). */
+const SLOT_RELEASE = 2;
+const SLOT_SHOW = 3;
+const SLOT_SET_OPTIONS = 9;
+const SLOT_SET_TITLE = 17;
+const SLOT_GET_RESULT = 20;
+/** IShellItem vtable slot for `GetDisplayName`. */
+const SLOT_GET_DISPLAY_NAME = 5;
+/**
+* Encode a canonical GUID string as its 16 little-endian bytes.
+* @param text - the `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` form.
+* @returns the in-memory GUID bytes CoCreateInstance expects.
+*/
+function guidBytes(text) {
+	const match = /^([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})$/i.exec(text);
+	const bytes = Buffer.alloc(16);
+	bytes.writeUInt32LE(parseInt(match[1], 16), 0);
+	bytes.writeUInt16LE(parseInt(match[2], 16), 4);
+	bytes.writeUInt16LE(parseInt(match[3], 16), 6);
+	Buffer.from(match[4] + match[5], "hex").copy(bytes, 8);
+	return bytes;
+}
+const CLSID_FILE_OPEN_DIALOG = guidBytes("dc1c5a9c-e88a-4dde-a5a1-60f82a20aef7");
+const IID_IFILE_OPEN_DIALOG = guidBytes("d57c7288-d4ad-4768-be02-9d969532d960");
+/**
+* Load koffi and expose the dialog bindings for this thread.
+* @returns the bindings {@link runFolderDialog} sequences against.
+*/
+async function loadWin32DialogBindings() {
+	const koffi = (await import("koffi")).default;
+	const ole32 = koffi.load("ole32.dll");
+	const user32 = koffi.load("user32.dll");
+	const kernel32 = koffi.load("kernel32.dll");
+	const pointerSize = koffi.sizeof("void *");
+	const coInitializeEx = ole32.func("__stdcall", "CoInitializeEx", "int32", ["void *", "uint32"]);
+	const coUninitialize = ole32.func("__stdcall", "CoUninitialize", "void", []);
+	const coCreateInstance = ole32.func("__stdcall", "CoCreateInstance", "int32", [
+		"void *",
+		"void *",
+		"uint32",
+		"void *",
+		"void *"
+	]);
+	const coTaskMemFree = ole32.func("__stdcall", "CoTaskMemFree", "void", ["void *"]);
+	const getCurrentThreadId = kernel32.func("__stdcall", "GetCurrentThreadId", "uint32", []);
+	const keybdEvent = user32.func("__stdcall", "keybd_event", "void", [
+		"uint8",
+		"uint8",
+		"uint32",
+		"uintptr"
+	]);
+	const protoShow = koffi.proto("int32 __stdcall DshDialogShow(void *self, void *owner)");
+	const protoSetOptions = koffi.proto("int32 __stdcall DshDialogSetOptions(void *self, uint32 options)");
+	const protoSetTitle = koffi.proto("int32 __stdcall DshDialogSetTitle(void *self, str16 title)");
+	const protoGetResult = koffi.proto("int32 __stdcall DshDialogGetResult(void *self, _Out_ void **item)");
+	const protoGetDisplayName = koffi.proto("int32 __stdcall DshItemGetDisplayName(void *self, int32 form, _Out_ void **name)");
+	const protoRelease = koffi.proto("uint32 __stdcall DshComRelease(void *self)");
+	/** Bind vtable slot `slot` of COM object `self` to a caller through `proto`. */
+	const method = (self, slot, proto) => {
+		const vtable = koffi.decode(self, "void *");
+		const fn = koffi.decode(vtable, slot * pointerSize, "void *");
+		return (...args) => koffi.call(fn, proto, self, ...args);
+	};
+	return {
+		setThreadDpiAwareness: () => {
+			let setContext;
+			try {
+				setContext = user32.func("__stdcall", "SetThreadDpiAwarenessContext", "void *", ["intptr"]);
+			} catch {
+				return;
+			}
+			for (const context of DPI_AWARENESS_CONTEXTS) if (setContext(context) !== null) return;
+		},
+		coInitializeSta: () => coInitializeEx(null, COINIT_APARTMENTTHREADED),
+		coUninitialize: () => {
+			coUninitialize();
+		},
+		currentThreadId: () => getCurrentThreadId(),
+		pressAltForForeground: () => {
+			keybdEvent(VK_MENU, 0, 0, 0);
+			keybdEvent(VK_MENU, 0, KEYEVENTF_KEYUP, 0);
+		},
+		createFolderDialog: () => {
+			const out = Buffer.alloc(pointerSize);
+			const created = coCreateInstance(CLSID_FILE_OPEN_DIALOG, null, CLSCTX_INPROC_SERVER, IID_IFILE_OPEN_DIALOG, out);
+			if (created < 0) throw new Error(`CoCreateInstance(FileOpenDialog) failed: HRESULT 0x${(created >>> 0).toString(16)}`);
+			const dialog = koffi.decode(out, "void *");
+			return {
+				setOptions: (options) => method(dialog, SLOT_SET_OPTIONS, protoSetOptions)(options),
+				setTitle: (title) => method(dialog, SLOT_SET_TITLE, protoSetTitle)(title),
+				show: () => method(dialog, SLOT_SHOW, protoShow)(null),
+				resultPath: () => {
+					const itemOut = [null];
+					const gotItem = method(dialog, SLOT_GET_RESULT, protoGetResult)(itemOut);
+					if (gotItem < 0) return { hr: gotItem };
+					const item = itemOut[0];
+					try {
+						const nameOut = [null];
+						const gotName = method(item, SLOT_GET_DISPLAY_NAME, protoGetDisplayName)(SIGDN_FILESYSPATH, nameOut);
+						if (gotName < 0) return { hr: gotName };
+						const path = readUtf16(koffi, nameOut[0], pointerSize);
+						coTaskMemFree(nameOut[0]);
+						return {
+							hr: gotName,
+							path
+						};
+					} finally {
+						method(item, SLOT_RELEASE, protoRelease)();
+					}
+				},
+				release: () => {
+					method(dialog, SLOT_RELEASE, protoRelease)();
+				}
+			};
+		}
+	};
+}
+/**
+* Throw when an HRESULT signals failure.
+* @param hr - the HRESULT to check.
+* @param what - the failing call's name for the error message.
+* @returns the (successful) HRESULT unchanged.
+*/
+function check(hr, what) {
+	if (hr < 0) throw new Error(`${what} failed: HRESULT 0x${(hr >>> 0).toString(16)}`);
+	return hr;
+}
+/**
+* Run one modal folder-picker conversation on the calling thread: DPI opt-in,
+* STA init, dialog creation, `Show`, and result extraction, releasing the
+* dialog on every path.
+* @param bindings - the native surface (koffi-backed in production, fakes in tests).
+* @param title - the dialog title text.
+* @param onShowing - called with the native thread id immediately before the
+*   blocking `Show`, so a driver on another thread can close the dialog.
+* @returns the selected filesystem path, or null when the user cancels.
+*/
+function runFolderDialog(bindings, title, onShowing) {
+	bindings.setThreadDpiAwareness();
+	check(bindings.coInitializeSta(), "CoInitializeEx");
+	try {
+		const dialog = bindings.createFolderDialog();
+		try {
+			check(dialog.setOptions(104), "SetOptions");
+			check(dialog.setTitle(title), "SetTitle");
+			onShowing(bindings.currentThreadId());
+			bindings.pressAltForForeground();
+			const shown = dialog.show();
+			if (shown === -2147023673) return null;
+			check(shown, "Show");
+			const result = dialog.resultPath();
+			check(result.hr, "GetResult");
+			return result.path;
+		} finally {
+			dialog.release();
+		}
+	} finally {
+		bindings.coUninitialize();
+	}
+}
+//#endregion
+//#region lib/types/win32-dialog-worker.js
+/**
+* Child-process entry for the Win32 folder dialog: blocks THIS process
+* inside the modal `Show` so the host event loop stays live, reporting over
+* the IPC channel. Spawned as a child process (not a worker thread) so a
+* native fault stays contained and the modal call never wedges the host.
+* A background host (the web GUI server) leaves this process without
+* foreground rights, so `runFolderDialog` synthesizes an Alt press
+* immediately before `Show` and the dialog then activates as foreground.
+* Protocol: `{kind:'showing',threadId}` right
+* before the blocking call (the driver's abort lever needs the native
+* thread id), then exactly one of `{kind:'done',path}` or
+* `{kind:'error',message}`.
+*/
+const title = process.env.DSH_DIALOG_TITLE ?? "";
+if (title === "") throw new Error("win32-dialog-worker: DSH_DIALOG_TITLE is required");
+if (process.send === void 0) throw new Error("win32-dialog-worker must run as a child process with an IPC channel");
+const send = process.send.bind(process);
+const post = (message) => {
+	/* v8 ignore next 3 -- disconnect needs a live IPC channel the unit lane must not sever (built-worker.e2e.ts owns the real close path). */
+	send(message, () => {
+		if (process.connected) process.disconnect();
+	});
+};
+/* v8 ignore next 3 -- the handler exits(0), which would kill the unit lane; built-worker.e2e.ts owns the real disconnect lifecycle. */
+process.on("disconnect", () => process.exit(0));
+(async () => {
+	try {
+		post({
+			kind: "done",
+			path: runFolderDialog(await loadWin32DialogBindings(), title, (threadId) => {
+				post({
+					kind: "showing",
+					threadId
+				});
+			})
+		});
+	} catch (error) {
+		post({
+			kind: "error",
+			message: error instanceof Error ? error.stack ?? error.message : String(error)
+		});
+	}
+})();
+//#endregion

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@x1a0f3n9/dsh-host-directory-picker-native",
+  "description": "Native-OS-chooser backend of the directory-picker seam for the DeepSeek Harness web GUI host",
+  "version": "0.1.5-rc.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/host/directory-picker-native"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./worker": {
+      "types": "./lib/types/win32-dialog-worker.d.ts",
+      "default": "./lib/worker.cjs"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/worker.cjs",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "koffi": "^3.1.0",
+    "@x1a0f3n9/dsh-host-directory-picker": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-native-command": "^0.1.5-rc.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2",
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}